@lunora/do 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-DQkmGiCS.mjs → ROOT_DO_SIZE_WARN_BYTES-DtZqOBIF.mjs}

@@ -1,20 +1,22 @@
 import { drizzle } from 'drizzle-orm/durable-sqlite';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-DZEhUeyI.mjs';
-import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKET_MS-CiHHYeJi.mjs';
+import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
 import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-PTtTiQ7U.mjs';
 import { SCAN_DEP, createDependencyTracker, tableFromDepKey } from './SCAN_DEP-DLJF8dsj.mjs';
-import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './ensureFunctionMetricsTables-UDNVD7FS.mjs';
-import { ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, readTablePage, facetColumn, MAX_PAGE_SIZE } from './ADMIN_FUNCTION_PREFIX-Dzdqq5J2.mjs';
+import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
+import { ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-D_UiYJFk.mjs';
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
-import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './clearCapturedMail-CPpgl-dX.mjs';
+import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
 import { readBookmark, armRestore } from './armRestore-BJk53Ro8.mjs';
-import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-ByVzgH3d.mjs';
+import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-1hDydFyv.mjs';
 import { redact, standardRules } from '@visulima/redact';
 import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } from './security-audit-CucgBice.mjs';
-import { runReadonlySql } from './assertReadonly-dDcFE1YZ.mjs';
+import { runReadonlySql } from './MAX_SQL_ROWS-dDcFE1YZ.mjs';
+import { trySendFrame, subscriptionListDeltas, sendDeltaFrames } from './subscriptionListDeltas-ce84gpwL.mjs';
 import { ConflictError } from './ConflictError-C0STs6bU.mjs';
-import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './applyCdcChanges-Ctdmxmrv.mjs';
-import { r as readIdempotent, w as writeIdempotent, t as trimIdempotent } from './ctx-db-idempotency-DkC9rP91.mjs';
+import { e as deleteGlobalShapeSnapshotsForConnection, g as readIdempotent, h as writeIdempotent, t as trimIdempotent, r as readClientWatermark, m as migrateClientWatermark, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, f as readGlobalShapeSnapshot, w as writeGlobalShapeSnapshot } from './ctx-db-idempotency-BdcNpvY4.mjs';
+import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-DSycmnDf.mjs';
+import { s as selectShapeMemberIds, a as selectShapeRows } from './ctx-db-shapes-DVoeZpo-.mjs';
 
 const AUDIT_LOG_TABLE = "__lunora_audit__";
 const AUDIT_LOG_RETENTION = 1e3;
@@ -349,6 +351,75 @@ const readRequestLog = (sql, options = {}) => {
   });
 };
 
+const projectColumns = (document_, columns) => {
+  if (!columns) {
+    return document_;
+  }
+  const projected = /* @__PURE__ */ Object.create(null);
+  for (const key of ["_id", "_creationTime", ...columns]) {
+    if (Object.hasOwn(document_, key)) {
+      projected[key] = document_[key];
+    }
+  }
+  return projected;
+};
+const diffGlobalMembership = (rows, previous, options) => {
+  const { columns, table } = options;
+  const next = /* @__PURE__ */ new Map();
+  const rowsPatch = [];
+  for (const { doc, id } of rows) {
+    const value = projectColumns(doc, columns);
+    const json = JSON.stringify(value);
+    next.set(id, json);
+    const before = previous.get(id);
+    if (before === void 0) {
+      rowsPatch.push({ key: id, op: "insert", table, value });
+    } else if (before !== json) {
+      rowsPatch.push({ key: id, op: "update", table, value });
+    }
+  }
+  for (const id of previous.keys()) {
+    if (!next.has(id)) {
+      rowsPatch.push({ key: id, op: "delete", table });
+    }
+  }
+  return { next, rowsPatch };
+};
+const buildPokeFrames = (parts, meta) => {
+  const { baseCheckpoint, checkpoint, epoch, lastMutationId, pokeId } = meta;
+  const frames = [JSON.stringify({ baseCheckpoint, epoch, pokeId, type: "pokeStart" })];
+  for (const part of parts) {
+    frames.push(
+      JSON.stringify({
+        pokeId,
+        rowsPatch: part.rowsPatch,
+        shapeId: part.shapeId,
+        type: "pokePart",
+        ...lastMutationId === void 0 ? {} : { lastMutationId }
+      })
+    );
+  }
+  frames.push(JSON.stringify({ checkpoint, epoch, pokeId, type: "pokeEnd" }));
+  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__";
@@ -413,97 +484,7 @@ const findDanglingReferences = (sql, storageColumns, liveKeys) => {
 
 const WS_KEEPALIVE_PING = "lunora-ping";
 const WS_KEEPALIVE_PONG = "lunora-pong";
-const ROW_ID_FIELD = "_id";
-const DELTA_FALLBACK_TABLE = "__lunora__";
-const readRowId = (row) => {
-  if (typeof row !== "object" || row === null || Array.isArray(row)) {
-    return void 0;
-  }
-  const id = row[ROW_ID_FIELD];
-  return typeof id === "string" ? id : void 0;
-};
-const indexRowsById = (rows) => {
-  const byId = /* @__PURE__ */ new Map();
-  const order = [];
-  for (const row of rows) {
-    const id = readRowId(row);
-    if (id === void 0 || byId.has(id)) {
-      return void 0;
-    }
-    byId.set(id, row);
-    order.push(id);
-  }
-  return { byId, order };
-};
-const survivorsKeepOrder = (previous, next) => {
-  const survivingPrevious = previous.order.filter((id) => next.byId.has(id));
-  const survivingNext = next.order.filter((id) => previous.byId.has(id));
-  if (survivingPrevious.length !== survivingNext.length) {
-    return false;
-  }
-  return survivingPrevious.every((id, index) => survivingNext[index] === id);
-};
-const collectDeleteDeltas = (previous, next, deltaTable, tableJson) => {
-  const out = [];
-  for (const id of previous.order) {
-    if (!next.byId.has(id)) {
-      out.push({
-        delta: { key: id, op: "delete", table: deltaTable },
-        frame: `{"key":${JSON.stringify(id)},"op":"delete","table":${tableJson}}`
-      });
-    }
-  }
-  return out;
-};
-const collectUpsertDeltas = (previous, next, deltaTable, tableJson) => {
-  const out = [];
-  for (const id of next.order) {
-    const nextRow = next.byId.get(id);
-    const previousRow = previous.byId.get(id);
-    const nextFingerprint = JSON.stringify(nextRow);
-    const previousFingerprint = previousRow === void 0 ? void 0 : JSON.stringify(previousRow);
-    if (previousFingerprint === nextFingerprint) {
-      continue;
-    }
-    const op = previousFingerprint === void 0 ? "insert" : "update";
-    out.push({
-      delta: { key: id, op, row: nextRow, table: deltaTable },
-      frame: `{"key":${JSON.stringify(id)},"op":"${op}","row":${nextFingerprint},"table":${tableJson}}`
-    });
-  }
-  return out;
-};
-const subscriptionListDeltas = (previousJson, nextResult, table, frames) => {
-  let parsed;
-  try {
-    parsed = JSON.parse(previousJson);
-  } catch {
-    return void 0;
-  }
-  if (!Array.isArray(parsed) || !Array.isArray(nextResult)) {
-    return void 0;
-  }
-  const previous = indexRowsById(parsed);
-  const next = indexRowsById(nextResult);
-  if (previous === void 0 || next === void 0) {
-    return void 0;
-  }
-  if (!survivorsKeepOrder(previous, next)) {
-    return void 0;
-  }
-  const deltaTable = table === "" ? DELTA_FALLBACK_TABLE : table;
-  const tableJson = JSON.stringify(deltaTable);
-  const framed = [...collectDeleteDeltas(previous, next, deltaTable, tableJson), ...collectUpsertDeltas(previous, next, deltaTable, tableJson)];
-  if (framed.length > next.order.length) {
-    return void 0;
-  }
-  if (frames !== void 0) {
-    for (const { frame } of framed) {
-      frames.push(frame);
-    }
-  }
-  return framed.map(({ delta }) => delta);
-};
+const UNDELIVERED_BASELINE = "<undelivered>";
 const ROOT_DO_SIZE_WARN_BYTES = 1073741824;
 const CDC_RESUME_SCAN_LIMIT = 1e4;
 const IDEMPOTENCY_RETENTION_MS = 864e5;
@@ -918,6 +899,13 @@ const parseIdentityHeader = (raw) => {
   }
   return void 0;
 };
+const parseClientSeqHeader = (raw) => {
+  if (!raw) {
+    return void 0;
+  }
+  const seq = Number(raw);
+  return Number.isInteger(seq) && seq > 0 ? seq : void 0;
+};
 const tablesFromDeps = (deps) => {
   const tables = /* @__PURE__ */ new Set();
   for (const dep of deps) {
@@ -1002,6 +990,28 @@ class ShardDO {
    * failure stays unlikely.
    */
   static MAX_SUBSCRIPTIONS_PER_SOCKET = 32;
+  /**
+   * Poll interval (ms) for `.global()`-table shapes. A global table lives in
+   * D1 with no per-DO op-log, so its shapes can't be poke-live; the DO re-reads
+   * each subscribed global shape's membership from D1 on an alarm every
+   * `GLOBAL_SHAPE_POLL_INTERVAL_MS` and pokes only the diff. This is the
+   * latency floor for a global-shape update — deliberately coarse (seconds, not
+   * the sub-millisecond poke-live path) since the D1 read fans out per tick.
+   */
+  static GLOBAL_SHAPE_POLL_INTERVAL_MS = 2e3;
+  /**
+   * Upper bound on a `.global()`-shape's materialized membership. Each global
+   * shape keeps its ENTIRE current membership as a per-socket snapshot
+   * (`Map&lt;rowKey, hash&gt;`) so the poll loop can diff it; that snapshot — and the
+   * read buffer feeding it — scale with the membership size, multiplied by every
+   * subscribed socket. An unbounded membership (a global table with no narrowing
+   * shape predicate or RLS read scope) would grow them without limit and evict
+   * the DO. A shape whose membership exceeds this cap is failed closed (left
+   * empty, logged) rather than retained — the developer must narrow it. Sized
+   * well above any reasonable per-identity replicated set so legitimate shapes
+   * never trip it.
+   */
+  static GLOBAL_SHAPE_MAX_ROWS = 5e4;
   /**
    * Per-socket whisper-topic cap. Topic membership rides the same hibernation
    * attachment as `subs`, so bound it for the same reason — a runaway
@@ -1103,6 +1113,39 @@ class ShardDO {
    * `finally` block.
    */
   currentRequestMutationId;
+  /**
+   * Stable per-device client id for the in-flight custom-mutator push,
+   * forwarded via the `x-lunora-client-id` header. Backs the
+   * `__client_watermark` table: the dispatch path classifies the paired
+   * `currentRequestClientSeq` against the stored high-watermark (already
+   * processed / next / out-of-order gap). Absent on legacy mutations and
+   * queries (those keep the `__idempotency` path). Cleared in `fetch`'s
+   * `finally`.
+   */
+  currentRequestClientId;
+  /**
+   * Monotonic per-client mutation sequence for the in-flight custom-mutator
+   * push, forwarded via the `x-lunora-client-seq` header (numeric). Paired
+   * with `currentRequestClientId` to drive the watermark classification.
+   * `undefined` when absent or non-numeric.
+   */
+  currentRequestClientSeq;
+  /**
+   * The in-flight push's custom-mutator classification, stashed by `fetch`
+   * before `handleRpc` so the in-transaction bookkeeping ({@link
+   * ShardDO.commitMutationBookkeeping}) can advance the `__client_watermark` for
+   * a `"next"` push inside the same commit as the writes. `undefined` for an
+   * ordinary mutation / non-mutator push. Cleared per request.
+   */
+  currentMutatorClass;
+  /**
+   * Set once a mutation's replay bookkeeping (idempotency row + watermark
+   * advance) has committed INSIDE the handler transaction, so the post-dispatch
+   * path skips the now-redundant best-effort writes. Cleared per request; stays
+   * `false` for actions/queries (no transaction wrapper) so their dispatch-level
+   * idempotency persist still runs.
+   */
+  mutationBookkeepingCommitted = false;
   /**
    * Wall-clock millis of the last `__idempotency` GC sweep on this warm
    * instance. The dedup write throttles `trimIdempotent` to at most once an
@@ -1133,6 +1176,18 @@ class ShardDO {
    * the common read-only path allocates nothing.
    */
   pendingChangedTables = void 0;
+  /**
+   * Coalesced set of tables awaiting a subscription-refresh pass, merged
+   * across every {@link ShardDO.flushChangedTables} call that lands while a
+   * pass is already draining. The single drain loop
+   * ({@link ShardDO.drainSubscriptionRefreshes}) owns this set; a burst of N
+   * writes to the same table therefore collapses into one (or two) refresh
+   * passes instead of N, so each affected subscription's handler re-runs once
+   * per burst rather than once per write. `undefined` when nothing is pending.
+   */
+  pendingRefreshTables = void 0;
+  /** True while {@link ShardDO.drainSubscriptionRefreshes} is running; the single-waiter gate that coalesces concurrent flushes. */
+  refreshInFlight = false;
   /**
    * Last pushed result per `(socket, subId)`, keyed by socket. Lets
    * `refreshSubscriptions` skip re-running queries whose tables were
@@ -1141,6 +1196,39 @@ class ShardDO {
    * memo simply forces one re-run and (at most) one redundant push.
    */
   subMemos = /* @__PURE__ */ new WeakMap();
+  /**
+   * Per-socket poke baseline for shape subscriptions: maps each shape's
+   * subscription id to the `__cdc_log` cursor it has been poked through.
+   * `pokeShapeSubscribers` reads each op page since this cursor and advances
+   * it to the flush watermark. In-memory only (like {@link ShardDO.subMemos});
+   * a cold memo on a reconnected/hibernated socket re-seeds from the client's
+   * `sinceCheckpoint`.
+   */
+  shapeMemos = /* @__PURE__ */ new WeakMap();
+  /**
+   * Per-socket, per-**global**-shape membership snapshot: maps each global
+   * shape's subscription id to a `key → projected-value JSON` map of the rows
+   * last poked to that socket. A `.global()` (D1) table has no op-log to diff,
+   * so {@link ShardDO.refreshGlobalShape} re-reads the full membership on each
+   * alarm tick and diffs it against this snapshot to compute the poke. Parallel
+   * to {@link ShardDO.shapeMemos} (the cursor baseline for poke-live shapes).
+   *
+   * This is a hot in-memory **cache** over the durable `__global_shape_snapshot`
+   * table (keyed by the socket's `connectionId` + subId): a hibernation eviction
+   * clears the WeakMap, so on the next alarm wake {@link ShardDO.readGlobalSnapshot}
+   * misses and re-loads the baseline from SQLite — without it, the diff would run
+   * against an empty baseline and a row deleted from D1 while the DO slept would
+   * never be poked as a `delete`, lingering on the client as a phantom row.
+   */
+  globalShapeSnapshots = /* @__PURE__ */ new WeakMap();
+  /**
+   * Whether a global-shape poll alarm is currently armed. Guards
+   * {@link ShardDO.scheduleGlobalPoll} from re-arming on every seed; reset in
+   * {@link ShardDO.alarm} before the poll so a still-subscribed shape re-arms.
+   */
+  globalPollScheduled = false;
+  /** Monotonic per-DO poke id source; correlates a poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
+  pokeSequence = 0;
   /** Per-socket whisper-rate token bucket (see {@link ShardDO.WHISPER_RATE_BURST}). In-memory; resets on hibernation. */
   whisperBuckets = /* @__PURE__ */ new WeakMap();
   /**
@@ -1272,6 +1360,10 @@ class ShardDO {
     this.currentResponseBookmark = void 0;
     this.currentRequestUserId = request.headers.get("x-lunora-userid") ?? void 0;
     this.currentRequestMutationId = request.headers.get("x-lunora-mutation-id") ?? void 0;
+    this.currentRequestClientId = request.headers.get("x-lunora-client-id") ?? void 0;
+    this.currentRequestClientSeq = parseClientSeqHeader(request.headers.get("x-lunora-client-seq"));
+    this.currentMutatorClass = void 0;
+    this.mutationBookkeepingCommitted = false;
     this.currentRequestIdentity = parseIdentityHeader(request.headers.get("x-lunora-identity"));
     this.currentRequestIp = request.headers.get("x-lunora-client-ip") ?? void 0;
     this.currentRequestSystem = request.headers.get("x-lunora-system") === "1";
@@ -1287,20 +1379,25 @@ class ShardDO {
         const value = await this.runRelationFanoutRead(payload.functionPath, payload.args ?? {});
         return jsonResponse(value, 200, this.currentResponseBookmark);
       }
+      const mutatorClass = this.isCustomMutator(payload.functionPath) ? this.classifyClientMutation() : void 0;
+      this.currentMutatorClass = mutatorClass;
+      const watermarkShortCircuit = this.rejectNonNextMutation(payload.functionPath, mutatorClass, dispatchStartedAt);
+      if (watermarkShortCircuit !== void 0) {
+        return watermarkShortCircuit;
+      }
       const cached = this.readIdempotentResult(this.currentRequestMutationId);
       if (cached !== void 0) {
-        this.recordFunctionCall(payload.functionPath, Date.now() - dispatchStartedAt, void 0, this.currentScannedTables, this.currentIndexHits);
-        return jsonResponse({ result: cached.value }, 200, this.currentResponseBookmark);
+        return this.respondFromIdempotencyCache(payload.functionPath, dispatchStartedAt, mutatorClass, cached.value);
       }
       const result = await this.handleRpc(payload.functionPath, payload.args ?? {});
-      this.persistIdempotentResult(result);
+      this.recordPostDispatchBookkeeping(result, mutatorClass);
       const durationMs = Date.now() - dispatchStartedAt;
       this.recordFunctionCall(payload.functionPath, durationMs, void 0, this.currentScannedTables, this.currentIndexHits);
       this.flushStmtSamples();
       const tablesWritten = [...this.pendingChangedTables ?? []];
       this.recordRequestLog(payload.functionPath, payload.args ?? {}, durationMs, "ok", tablesWritten);
       this.maybeWarnRootSize();
-      const response = jsonResponse({ result }, 200, this.currentResponseBookmark);
+      const response = this.buildDispatchResponse(mutatorClass, result);
       await this.flushChangedTables();
       return response;
     } catch (error) {
@@ -1326,6 +1423,10 @@ class ShardDO {
       this.currentResponseBookmark = void 0;
       this.currentRequestUserId = void 0;
       this.currentRequestMutationId = void 0;
+      this.currentRequestClientId = void 0;
+      this.currentRequestClientSeq = void 0;
+      this.currentMutatorClass = void 0;
+      this.mutationBookkeepingCommitted = false;
       this.currentRequestIdentity = void 0;
       this.currentRequestIp = void 0;
       this.currentRequestSystem = false;
@@ -1363,6 +1464,9 @@ class ShardDO {
       if (envelope.context !== void 0) {
         attachment.context = envelope.context;
       }
+      if (envelope.clientId !== void 0) {
+        attachment.clientId = envelope.clientId;
+      }
       attachment.connected = true;
       try {
         ws.serializeAttachment?.(attachment);
@@ -1394,6 +1498,20 @@ class ShardDO {
       }
       return;
     }
+    if (envelope.type === "shape_subscribe" && envelope.shape) {
+      await this.handleShapeSubscribe(ws, envelope.id, {
+        args: envelope.shape.args,
+        name: envelope.shape.name,
+        sinceEpoch: envelope.sinceEpoch,
+        sinceSeq: envelope.sinceCheckpoint
+      });
+      return;
+    }
+    if (envelope.type === "shape_unsubscribe") {
+      this.shapeUnsubscribe(ws, envelope.id);
+      ws.send(JSON.stringify({ id: envelope.id, type: "ack" }));
+      return;
+    }
     if (envelope.type === "stream" && envelope.query?.functionPath) {
       if (envelope.query.functionPath.startsWith(ADMIN_FUNCTION_PREFIX)) {
         ws.send(JSON.stringify({ id: envelope.id, message: "streams must be public", type: "error" }));
@@ -1444,12 +1562,41 @@ class ShardDO {
       this.streamCancellers.delete(ws);
     }
     this.subMemos.delete(ws);
+    this.shapeMemos.delete(ws);
+    this.globalShapeSnapshots.delete(ws);
+    if (attachment.connectionId !== void 0) {
+      try {
+        deleteGlobalShapeSnapshotsForConnection(this.sql, attachment.connectionId);
+      } catch {
+      }
+    }
     ws.serializeAttachment?.(void 0);
   }
   /** Hibernation API: invoked on socket error. */
   // eslint-disable-next-line class-methods-use-this -- Workers hibernation handler: the platform invokes it on the instance; the signature must stay an instance method
   webSocketError(_ws, _error) {
   }
+  /**
+   * Durable Object alarm handler — the heartbeat for `.global()`-table shapes.
+   * The runtime wakes this when the poll alarm armed by `scheduleGlobalPoll`
+   * fires; it refreshes every subscribed global shape (diff-poke from the global
+   * backend) and re-arms while any remain. With no global subscribers left, the
+   * alarm is not re-armed and the DO goes idle. A base-only / global-free DO
+   * never arms it, so this stays dormant there.
+   */
+  async alarm() {
+    this.globalPollScheduled = false;
+    let remaining;
+    try {
+      remaining = await this.pollGlobalShapes();
+    } catch (error) {
+      this.recordShapeError("shape:poll", error);
+      remaining = 1;
+    }
+    if (remaining > 0) {
+      await this.scheduleGlobalPoll();
+    }
+  }
   /**
    * The registered function paths to dispatch when a socket connects/disconnects.
    * Base default is empty; the codegen subclass overrides it to return the
@@ -1648,20 +1795,14 @@ class ShardDO {
         status: 500
       });
     }
-    const sqlExec = sqlHandle.exec.bind(sqlHandle);
+    const transactionalStorage = this.state.storage;
     const run = async () => {
       this.transactionDepth = 1;
-      sqlExec("BEGIN");
       try {
-        const value = await handler();
-        sqlExec("COMMIT");
-        return value;
-      } catch (error) {
-        try {
-          sqlExec("ROLLBACK");
-        } catch {
+        if (typeof transactionalStorage?.transaction === "function") {
+          return await transactionalStorage.transaction(async () => handler());
         }
-        throw error;
+        return await handler();
       } finally {
         this.transactionDepth = 0;
       }
@@ -1859,7 +2000,45 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the statically-discovered feature flags
   studioFeatures() {
-    return { mail: false, payments: false, scheduler: false, storage: false, vectors: false, workflows: false };
+    return { flags: false, mail: false, payments: false, queues: false, scheduler: false, storage: false, vectors: false, workflows: false };
+  }
+  /**
+   * Evaluate every statically-discovered feature flag under `context` for the
+   * studio's read-only Flags page (`__lunora_admin__:listFlags`). The flag keys
+   * + value types are discovered by `@lunora/codegen` from the app's
+   * `ctx.flags.&lt;type>("key", …)` reads and evaluated through the configured
+   * `@lunora/flags` provider — work only the codegen subclass can do, so it
+   * overrides this. The base class wires no provider and reports
+   * `configured: false` with zero flags (an un-generated `ShardDO` has none).
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with live OpenFeature evaluation over the discovered flag keys
+  evaluateFlags(_context) {
+    return Promise.resolve({ configured: false, flags: [] });
+  }
+  /**
+   * Serve one reserved {@link FLAGS_FUNCTION_PREFIX} live flag read for the
+   * React client's `useFlag`/`useFlags`. `functionPath` carries the flag key +
+   * type and `args` the per-subscriber targeting context; the codegen subclass
+   * overrides this to evaluate the flag through the app's `@lunora/flags`
+   * provider under `identity` and return the resolved value. The base class
+   * wires no provider, so it returns `null` — `resolveReactiveOutcome` reads
+   * `null` as "nothing to deliver" and the subscriber keeps its default.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this to evaluate the flag through the configured provider
+  runFlagSubscriptionRead(_functionPath, _arguments, _identity) {
+    return Promise.resolve(null);
+  }
+  /**
+   * The Cloudflare Queues declared by this app, surfaced via
+   * `__lunora_admin__:listQueues` for the studio's Queues page. Queues are NOT
+   * Durable Objects and hold no shard state, so this is pure declaration
+   * metadata statically discovered by `@lunora/codegen` from `lunora/queues.ts`
+   * and emitted into the generated subclass, which overrides this. The base
+   * class can't see the user's project, so it reports none.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the statically-discovered queue metadata
+  queuesMetadata() {
+    return { queues: [] };
   }
   /**
    * The Cloudflare Workflows declared by this app, surfaced via
@@ -2124,13 +2303,15 @@ class ShardDO {
    * unless the request carried an `x-lunora-mutation-id` header (queries and
    * legacy clients leave `currentRequestMutationId` undefined).
    *
-   * Called on the live dispatch path right after the handler's writes have
-   * auto-committed, through the same `this.sql` handle, so the dedup row is
-   * durable iff those writes are. (The DO has no ambient BEGIN/COMMIT around a
-   * mutation — `handleRpc` invokes the user handler directly — so this can't
-   * piggyback on a surrounding transaction; it commits as its own statement
-   * immediately after.) `INSERT OR IGNORE` keeps a concurrent double-dispatch
-   * of the same id idempotent. Also runs the throttled dedup-table GC.
+   * For a mutation this runs INSIDE the handler's transaction (via
+   * {@link ShardDO.commitMutationBookkeeping}, which `handleRpc` invokes before
+   * the transaction commits), so the dedup row is durable iff the writes are —
+   * closing the crash window where the writes commit but the replay guard does
+   * not. Actions/queries aren't transaction-wrapped, so they call this on the
+   * live dispatch path right after the handler resolves, through the same
+   * `this.sql` handle. `INSERT OR IGNORE` keeps a concurrent double-dispatch (or
+   * the now-skipped post-dispatch call) of the same id idempotent. Also runs the
+   * throttled dedup-table GC.
    */
   persistIdempotentResult(result) {
     if (this.currentRequestMutationId === void 0) {
@@ -2146,6 +2327,175 @@ class ShardDO {
     } catch {
     }
   }
+  /**
+   * Whether `functionPath` names a registered custom mutator (a `defineMutator`
+   * declaration) rather than an ordinary `mutation`. The base class knows of no
+   * mutators, so the default is `false`; the codegen-generated subclass
+   * overrides this to consult its mutator registry. When `true` (and the push
+   * carries a `clientId`/`clientSeq`), the dispatch path applies the
+   * `__client_watermark` ordering semantics instead of the legacy idempotency
+   * dedup.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this to consult its mutator registry
+  isCustomMutator(_functionPath) {
+    return false;
+  }
+  /**
+   * Classify an in-flight custom-mutator push against the shard's stored
+   * high-watermark for `currentRequestClientId`. The watermark is the highest
+   * per-client sequence the DO has applied, so the push is exactly one of:
+   *
+   * - `"already"` — `seq &lt;= watermark`: a replay of a confirmed (or in-flight,
+   * now-resent) mutation. The handler must NOT re-run; the dispatch path returns
+   * a benign ack so the client drops the pending overlay.
+   * - `"next"` — `seq == watermark + 1`: the next mutation in order. Run the
+   * authoritative `server` impl and advance the watermark in the same commit.
+   * - `"gap"` — `seq > watermark + 1`: an out-of-order arrival (an earlier push
+   * was lost). Halt: the client must resend from `watermark + 1`.
+   *
+   * Returns `undefined` when the push is not a watermarked custom mutator
+   * (missing client id/seq, or a stub `sql` handle without the table) so the
+   * caller falls through to the legacy idempotency path.
+   */
+  classifyClientMutation() {
+    const clientId = this.currentRequestClientId;
+    const seq = this.currentRequestClientSeq;
+    if (clientId === void 0 || seq === void 0) {
+      return void 0;
+    }
+    const identity = this.currentRequestUserId ?? "";
+    let watermark;
+    try {
+      watermark = readClientWatermark(this.sql, identity, clientId);
+    } catch {
+      try {
+        migrateClientWatermark(this.sql);
+        watermark = readClientWatermark(this.sql, identity, clientId);
+      } catch {
+        return void 0;
+      }
+    }
+    const expected = watermark + 1;
+    if (seq <= watermark) {
+      return { expected, kind: "already" };
+    }
+    return seq === expected ? { expected, kind: "next" } : { expected, kind: "gap" };
+  }
+  /**
+   * Terminal response for a watermarked custom-mutator push that is NOT the
+   * next-in-order mutation — an idempotent replay ack (`"already"`) or an
+   * out-of-order halt (`"gap"`). Returns `undefined` for an ordinary mutation
+   * or a `"next"` push so `fetch` proceeds to the authoritative handler. Records
+   * the function call on the short-circuit paths so metrics stay attributed.
+   */
+  rejectNonNextMutation(functionPath, mutatorClass, dispatchStartedAt) {
+    if (mutatorClass === void 0 || mutatorClass.kind === "next") {
+      return void 0;
+    }
+    this.recordFunctionCall(functionPath, Date.now() - dispatchStartedAt, void 0, this.currentScannedTables, this.currentIndexHits);
+    if (mutatorClass.kind === "already") {
+      return jsonResponse({ lastMutationId: mutatorClass.expected - 1, result: null }, 200, this.currentResponseBookmark);
+    }
+    return jsonResponse(
+      {
+        error: {
+          code: "OUT_OF_ORDER",
+          expectedMutationId: mutatorClass.expected,
+          message: `out-of-order mutation; expected sequence ${String(mutatorClass.expected)}`
+        }
+      },
+      409,
+      this.currentResponseBookmark
+    );
+  }
+  /**
+   * Respond to a dispatch that hit the `(identity, mutationId)` idempotency
+   * cache. Records the (zero-work) function call, then: for a `"next"` custom
+   * mutator whose handler already committed but whose watermark advance was
+   * lost to a crash in between, re-advance and echo `lastMutationId` exactly as
+   * the post-commit path does (otherwise the cached branch returns a bare
+   * result with a stale watermark and the client reports every later seq as a
+   * gap forever); for everything else, return the bare cached `{ result }`.
+   */
+  respondFromIdempotencyCache(functionPath, dispatchStartedAt, mutatorClass, cachedValue) {
+    this.recordFunctionCall(functionPath, Date.now() - dispatchStartedAt, void 0, this.currentScannedTables, this.currentIndexHits);
+    if (mutatorClass?.kind === "next") {
+      this.advanceClientMutationWatermark();
+      return this.buildDispatchResponse(mutatorClass, cachedValue);
+    }
+    return jsonResponse({ result: cachedValue }, 200, this.currentResponseBookmark);
+  }
+  /**
+   * Build the success response for a dispatched RPC. A `"next"` custom-mutator
+   * push echoes the applied `lastMutationId` so the client drops the pending
+   * optimistic overlay as soon as the ack lands; ordinary calls return the bare
+   * `{ result }` envelope unchanged.
+   */
+  buildDispatchResponse(mutatorClass, result) {
+    if (mutatorClass?.kind === "next") {
+      return jsonResponse({ lastMutationId: this.currentRequestClientSeq, result }, 200, this.currentResponseBookmark);
+    }
+    return jsonResponse({ result }, 200, this.currentResponseBookmark);
+  }
+  /**
+   * Commit a mutation's replay bookkeeping — the `(identity, mutationId)`
+   * idempotency dedup row and, for a `"next"` custom-mutator push, the
+   * `__client_watermark` advance — INSIDE the handler's transaction. Called by
+   * the generated `handleRpc` mutation branch after the user handler resolves
+   * but before the transaction commits, so the writes, the dedup row, and the
+   * watermark land in one atomic commit: a crash can't leave the writes durable
+   * without the replay guard (which a re-dispatch would otherwise re-run) nor
+   * without the watermark. Sets {@link ShardDO.mutationBookkeepingCommitted} so
+   * `fetch` skips the redundant post-dispatch persist.
+   */
+  commitMutationBookkeeping(result) {
+    this.persistIdempotentResult(result);
+    if (this.currentMutatorClass?.kind === "next") {
+      this.advanceClientMutationWatermark({ strict: true });
+    }
+    this.mutationBookkeepingCommitted = true;
+  }
+  /**
+   * Best-effort replay bookkeeping for the live dispatch path, run after
+   * `handleRpc` returns. A generated mutation already committed it atomically
+   * inside its transaction (via {@link ShardDO.commitMutationBookkeeping}, which
+   * sets the flag), so this skips. Actions/queries aren't transaction-wrapped,
+   * so they record their dedup row here (a no-op without an `x-lunora-mutation-id`),
+   * and a `"next"` push advances its watermark (the gap self-heals on replay).
+   */
+  recordPostDispatchBookkeeping(result, mutatorClass) {
+    if (this.mutationBookkeepingCommitted) {
+      return;
+    }
+    this.persistIdempotentResult(result);
+    if (mutatorClass?.kind === "next") {
+      this.advanceClientMutationWatermark();
+    }
+  }
+  /**
+   * Advance the stored high-watermark for the in-flight custom mutator to
+   * `currentRequestClientSeq` through the same `this.sql` handle. On the
+   * transactional path ({@link ShardDO.commitMutationBookkeeping}, `strict`) it
+   * runs inside the handler's commit, so the watermark is durable iff the writes
+   * are; a failure rethrows to roll the mutation back. On the best-effort
+   * cache-hit recovery path (`strict` omitted) a missing table is swallowed —
+   * the replay re-runs and re-advances (the read side treats a missing row as
+   * watermark 0), so the gap self-heals.
+   */
+  advanceClientMutationWatermark(options) {
+    const clientId = this.currentRequestClientId;
+    const seq = this.currentRequestClientSeq;
+    if (clientId === void 0 || seq === void 0) {
+      return;
+    }
+    try {
+      advanceClientWatermark(this.sql, this.currentRequestUserId ?? "", clientId, seq);
+    } catch (error) {
+      if (options?.strict) {
+        throw error;
+      }
+    }
+  }
   /**
    * Replay a batch of CDC changes into this shard (point-in-time recovery).
    * Schema-aware — it builds a `createShardCtxDb` writer — so the base class
@@ -2195,6 +2545,56 @@ class ShardDO {
     }
     this.subMemos.get(ws)?.delete(subId);
   }
+  /**
+   * Register a live shape subscription on a socket — the partial-replication
+   * parallel to {@link ShardDO.subscribe}. Stores the descriptor in the
+   * attachment's `shapes` registry (created lazily) so it survives
+   * hibernation, sharing the per-socket cap with `subs`. Returns a status the
+   * caller surfaces as a structured error frame; never throws (a thrown
+   * `webSocketMessage` is a fatal-channel error under the hibernation API).
+   */
+  shapeSubscribe(ws, subId, shape) {
+    const attachment = this.readAttachment(ws);
+    const shapes = attachment.shapes ?? {};
+    if (Object.keys(attachment.subs).length + Object.keys(shapes).length >= ShardDO.MAX_SUBSCRIPTIONS_PER_SOCKET) {
+      return "too_many";
+    }
+    shapes[subId] = shape;
+    attachment.shapes = shapes;
+    try {
+      ws.serializeAttachment?.(attachment);
+    } catch {
+      delete attachment.shapes[subId];
+      return "serialize_failed";
+    }
+    return "ok";
+  }
+  /** Remove a shape subscription and its poke baseline. Mirrors {@link ShardDO.unsubscribe}'s rollback-on-serialize-failure contract. */
+  shapeUnsubscribe(ws, subId) {
+    const attachment = this.readAttachment(ws);
+    const { shapes } = attachment;
+    if (!shapes) {
+      return;
+    }
+    const captured = shapes[subId];
+    delete shapes[subId];
+    try {
+      ws.serializeAttachment?.(attachment);
+    } catch {
+      if (captured !== void 0) {
+        shapes[subId] = captured;
+      }
+      return;
+    }
+    this.shapeMemos.get(ws)?.delete(subId);
+    this.globalShapeSnapshots.get(ws)?.delete(subId);
+    if (attachment.connectionId !== void 0) {
+      try {
+        deleteGlobalShapeSnapshot(this.sql, attachment.connectionId, subId);
+      } catch {
+      }
+    }
+  }
   /**
    * Decide whether a single subscription is interested in a mutation
    * delta. The default implementation checks the table name, then runs a
@@ -2243,10 +2643,7 @@ class ShardDO {
         if (!this.matchesSubscription(query, delta)) {
           continue;
         }
-        try {
-          ws.send(`{"type":"delta","id":${JSON.stringify(subId)},"delta":${deltaJson}}`);
-        } catch {
-        }
+        trySendFrame(ws, `{"type":"delta","id":${JSON.stringify(subId)},"delta":${deltaJson}}`);
       }
     }
   }
@@ -2269,6 +2666,46 @@ class ShardDO {
   executeSubscription(_functionPath, _args, _identity) {
     return Promise.resolve(null);
   }
+  /**
+   * Resolve a named shape to its concrete query plan for `identity`. The base
+   * class has no shape registry, so it returns `undefined` — partial
+   * replication is disabled and a `shape_subscribe` is rejected. The
+   * codegen-generated subclass overrides this to look the shape up in the
+   * project's `defineShape` registry, evaluate its `where(ctx, args)` under the
+   * subscriber's verified identity, and AND-compose it with the table's RLS
+   * read base-where into {@link ResolvedShape.effectiveWhere}.
+   *
+   * `identity` is the socket's OWN verified identity (the same unforgeable
+   * value `refreshSubscriptions` threads), passed by value so this never reads
+   * the mutable per-request identity fields. Returning `undefined` is the
+   * fail-closed signal — an unknown shape, or an RLS-required table with no
+   * policy resolving for this identity, yields no subscription rather than
+   * leaking rows.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to dispatch via the generated shape registry
+  resolveShape(_name, _args, _identity) {
+    return void 0;
+  }
+  /**
+   * Read the FULL current membership of a `.global()`-table shape from its D1
+   * (or Hyperdrive) backend — the seed/poll source for the latency-tiered
+   * global shape path. A `.global()` table lives in another store with no
+   * per-DO op-log, so this is the only way to learn its rows from inside the
+   * shard DO; {@link ShardDO.seedGlobalShape} calls it once on subscribe and
+   * {@link ShardDO.refreshGlobalShape} on every alarm tick, diffing the result
+   * against the per-socket snapshot to compute the poke.
+   *
+   * The base class has no global backend, so it returns `[]` (a base-only DO,
+   * or a project with no global tables, never resolves a global shape). The
+   * codegen subclass overrides it to drain `globalDb.findMany(table, { where:
+   * effectiveWhere })` under the socket's verified `identity` — the same
+   * unforgeable value `resolveShape` composed the RLS predicate with, so the
+   * D1 read is identity-scoped exactly like the poke-live path.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this to read the global (D1) backend; the base has none
+  readGlobalShapeRows(_resolved, _identity) {
+    return Promise.resolve([]);
+  }
   /**
    * Look up a streaming-query function and return a thunk that produces the
    * `AsyncIterable&lt;unknown>` when handed an {@link AbortSignal}. The codegen
@@ -2671,16 +3108,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
@@ -2802,6 +3239,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.getWorkflowInstanceStatus) {
       return this.handleGetWorkflowInstanceStatus(args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.listFlags) {
+      return this.handleListFlags(args);
+    }
     return this.handlePitrAdminOp(functionPath, args);
   }
   /**
@@ -2922,6 +3362,21 @@ class ShardDO {
     return jsonResponse({ result }, 200);
   }
   /* eslint-enable no-secrets/no-secrets */
+  /**
+   * Serve `__lunora_admin__:listFlags` — the studio's read-only Flags page.
+   * Evaluates every statically-discovered feature flag under an optional
+   * `args.context` targeting context (the studio's editable context editor)
+   * via the {@link evaluateFlags} hook, which the codegen subclass overrides
+   * with live OpenFeature evaluation. Read-only: a flag lookup mutates no shard
+   * state, so nothing is flushed or audited. Admin-gated by `handleAdminRpc`'s
+   * caller.
+   */
+  async handleListFlags(args) {
+    const rawContext = args.context;
+    const context = typeof rawContext === "object" && rawContext !== null && !Array.isArray(rawContext) ? rawContext : void 0;
+    const result = await this.evaluateFlags(context);
+    return jsonResponse({ result }, 200);
+  }
   /**
    * Run `run()` with the per-request identity pinned to (`userId`, `identity`),
    * then restore the prior values in a `finally` (even if `run()` throws), so the
@@ -3301,6 +3756,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.listWorkflows) {
       return this.workflowsMetadata();
     }
+    if (functionPath === ADMIN_FUNCTIONS.listQueues) {
+      return this.queuesMetadata();
+    }
     return void 0;
   }
   /**
@@ -3460,6 +3918,73 @@ class ShardDO {
     const read = this.readAdminOp(functionPath, args);
     return read ? { result: read.result, tables: read.tables } : null;
   }
+  /**
+   * Resolve one subscription (seed or refresh) to its {@link SubscriptionOutcome}
+   * by routing the `functionPath` to the right read path — shared by
+   * {@link seedSubscription} and {@link refreshSubscriptions} so both branch
+   * identically:
+   * - `__lunora_admin__:*` → {@link executeAdminSubscription} (raw SQLite read).
+   * - {@link FLAGS_FUNCTION_PREFIX} → {@link runFlagSubscriptionRead} (the codegen subclass evaluates the flag through the configured provider). The value isn't bound to any table, so it is tagged with the {@link ADMIN_WILDCARD} dep — re-evaluated on every write-flush so a live `useFlag` stays current within a session. A `null` read means "nothing to deliver" (no provider, or a flag that resolved to `null`).
+   * - everything else → {@link executeSubscription} (the user query, under the socket's own by-value identity).
+   */
+  async resolveReactiveOutcome(functionPath, args, isAdmin, identity) {
+    if (isAdmin) {
+      return this.executeAdminSubscription(functionPath, args);
+    }
+    if (functionPath.startsWith(FLAGS_FUNCTION_PREFIX)) {
+      const result = await this.runFlagSubscriptionRead(functionPath, args, identity);
+      return result === null ? null : { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+    }
+    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
@@ -3484,6 +4009,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) {
@@ -3524,10 +4050,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"
         })
@@ -3558,11 +4089,49 @@ class ShardDO {
     if (!changed || changed.size === 0) {
       return;
     }
+    if (this.pendingRefreshTables) {
+      for (const table of changed) {
+        this.pendingRefreshTables.add(table);
+      }
+    } else {
+      this.pendingRefreshTables = changed;
+    }
+    if (this.refreshInFlight) {
+      return;
+    }
     if (typeof this.state.waitUntil === "function") {
-      this.state.waitUntil(this.refreshSubscriptions(changed));
+      this.state.waitUntil(this.drainSubscriptionRefreshes());
       return;
     }
-    await this.refreshSubscriptions(changed);
+    await this.drainSubscriptionRefreshes();
+  }
+  /**
+   * Drain {@link ShardDO.pendingRefreshTables} one coalesced batch at a time
+   * until it is empty, then release the {@link ShardDO.refreshInFlight} gate.
+   * Tables merged by a `flushChangedTables` that lands mid-pass are picked up
+   * by the next loop iteration, so every committed write is observed by a
+   * refresh that runs after it — bursts simply share a pass. The post-write
+   * high-watermark and live-socket set are re-read inside each
+   * `refreshSubscriptions` / `pokeShapeSubscribers` call, so a later batch
+   * always reflects the latest committed state.
+   */
+  async drainSubscriptionRefreshes() {
+    if (this.refreshInFlight) {
+      return;
+    }
+    this.refreshInFlight = true;
+    try {
+      let batch = this.pendingRefreshTables;
+      while (batch && batch.size > 0) {
+        this.pendingRefreshTables = void 0;
+        const frameCursor = this.currentCdcCursor();
+        const frameEpoch = this.currentCdcEpoch();
+        await Promise.all([this.refreshSubscriptions(batch), this.pokeShapeSubscribers(batch, frameCursor, frameEpoch)]);
+        batch = this.pendingRefreshTables;
+      }
+    } finally {
+      this.refreshInFlight = false;
+    }
   }
   /**
    * For every live subscription whose query reads one of `changed`, re-run
@@ -3623,6 +4192,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);
@@ -3640,14 +4210,12 @@ class ShardDO {
           continue;
         }
         try {
-          const outcome = isAdmin ? this.executeAdminSubscription(functionPath, query.args ?? {}) : (
-            // Re-run under the socket's OWN verified identity (stamped on the
-            // attachment at upgrade, unforgeable by the client) — passed BY
-            // VALUE, so this deferred re-run never reads or mutates the shared
-            // per-request identity fields. Without it an `rls()` / `ctx.auth`
-            // scoped live query would evaluate anonymous and return zero rows.
-            // eslint-disable-next-line no-await-in-loop -- subscriptions on a socket re-run sequentially; each shares the single SQLite handle
-            await this.executeSubscription(functionPath, query.args ?? {}, { 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;
@@ -3659,18 +4227,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
@@ -3690,7 +4247,10 @@ class ShardDO {
   async seedSubscription(ws, subId, query, functionPath, isAdmin) {
     const seedArgs = query.args ?? {};
     const attachment = this.readAttachment(ws);
-    const outcome = isAdmin ? this.executeAdminSubscription(functionPath, seedArgs) : await this.executeSubscription(functionPath, seedArgs, { identity: attachment.identity, userId: attachment.userId });
+    const outcome = await this.resolveReactiveOutcome(functionPath, seedArgs, isAdmin, {
+      identity: attachment.identity,
+      userId: attachment.userId
+    });
     if (!outcome) {
       return;
     }
@@ -3707,6 +4267,536 @@ class ShardDO {
     }
     this.pushSubscriptionData(ws, subId, outcome, resume?.cursor ?? this.currentCdcCursor(), epoch);
   }
+  /**
+   * Drive the full `shape_subscribe` flow as one failure-aware unit: persist the
+   * attachment, seed the shape, and ack ONLY once both succeed. A persist
+   * rejection (`too_many`/`serialize_failed`) or a seed that can't resolve the
+   * shape (unknown / RLS-denied / cross-shard-invalid) rolls the attachment back
+   * and sends an `error` frame instead of acking — so a client is never left
+   * acked but subscribed to a shape that will never deliver. Never throws (a
+   * thrown `webSocketMessage` is fatal to the hibernating socket).
+   */
+  async handleShapeSubscribe(ws, subId, shape) {
+    const status = this.shapeSubscribe(ws, subId, shape);
+    if (status !== "ok") {
+      const code = status === "too_many" ? "TOO_MANY_SUBSCRIPTIONS" : "SUBSCRIPTION_PERSIST_FAILED";
+      const message = status === "too_many" ? `subscription cap of ${String(ShardDO.MAX_SUBSCRIPTIONS_PER_SOCKET)} reached on this socket` : "failed to persist shape subscription attachment";
+      this.sendShapeSubscribeError(ws, subId, code, message);
+      return;
+    }
+    const seed = await this.seedShapeSubscription(ws, subId, shape);
+    if (seed !== "ok") {
+      this.shapeUnsubscribe(ws, subId);
+      this.sendShapeSubscribeError(ws, subId, seed.code, seed.message);
+      return;
+    }
+    try {
+      ws.send(JSON.stringify({ id: subId, type: "ack" }));
+    } catch {
+    }
+  }
+  /** Send a structured `error` frame for a failed `shape_subscribe`, swallowing a send on an already-closed socket. */
+  // eslint-disable-next-line class-methods-use-this -- groups with the shape-subscribe flow; uses only its args + the socket
+  sendShapeSubscribeError(ws, subId, code, message) {
+    try {
+      ws.send(JSON.stringify({ code, error: { code, message }, id: subId, type: "error" }));
+    } catch {
+    }
+  }
+  /**
+   * Seed a freshly-registered shape subscription. Resolves the shape under the
+   * socket's verified identity, then ships either:
+   *
+   * - a **catch-up** poke (the membership diff in `(sinceCheckpoint, cursor]`)
+   * when the client supplied a still-current checkpoint within the CDC retention
+   * window and on this epoch — the cheap reconnect path; or
+   * - a **full** insert-poke of the shape's entire current membership — a
+   * first-time subscribe, or a reconnect that fell outside retention / forked
+   * epoch.
+   *
+   * Either way the per-socket shape memo advances to the flush watermark so
+   * later `pokeShapeSubscribers` passes diff from the right point.
+   *
+   * Returns `"ok"` once the shape resolved and its seed poke was attempted, or a
+   * `{ code, message }` failure when the shape can't be resolved — an unknown /
+   * RLS-denied shape (a base class with no registry resolves nothing), or a
+   * `resolveShape` that threw (e.g. a cross-shard-join guard). The caller rolls
+   * back the persisted attachment and errors instead of acking, so a client is
+   * never left subscribed to a shape that will never deliver.
+   */
+  async seedShapeSubscription(ws, subId, shape) {
+    const attachment = this.readAttachment(ws);
+    const identity = { identity: attachment.identity, userId: attachment.userId };
+    let resolved;
+    try {
+      resolved = this.resolveShape(shape.name, shape.args ?? {}, identity);
+    } catch (error) {
+      this.recordShapeError(`shape:seed:${subId}`, error);
+      const code = typeof error.code === "string" ? error.code : "SHAPE_RESOLVE_FAILED";
+      return { code, message: error instanceof Error ? error.message : "shape resolution failed" };
+    }
+    if (!resolved) {
+      return { code: "SHAPE_NOT_FOUND", message: `shape "${shape.name}" not found or not permitted` };
+    }
+    try {
+      if (resolved.global) {
+        return await this.seedGlobalShape(ws, subId, resolved, identity, attachment.connectionId ?? "");
+      }
+      return await this.seedOpLogShape(ws, subId, shape, resolved);
+    } catch (error) {
+      this.recordShapeError(`shape:seed:${subId}`, error);
+      const code = typeof error.code === "string" ? error.code : "SHAPE_SEED_FAILED";
+      return { code, message: error instanceof Error ? error.message : "shape seed failed" };
+    }
+  }
+  /**
+   * Seed a non-`.global()` (op-log-backed) shape: either a catch-up diff over
+   * `(sinceSeq, cursor]` when the client supplied a still-current checkpoint on
+   * this epoch within the CDC retention window, or a full membership insert-poke
+   * otherwise. The memo advances to `cursor` only once the poke is delivered, so
+   * a failed send re-diffs from the prior point rather than skipping rows. May
+   * throw (a stub `sql` handle, a membership probe failure); the caller converts
+   * it to a structured `shape_subscribe` error.
+   */
+  async seedOpLogShape(ws, subId, shape, resolved) {
+    const sql = this.sql;
+    const cursor = this.currentCdcCursor() ?? 0;
+    const epoch = this.currentCdcEpoch();
+    const floor = this.cdcEnabled() ? minCdcSeq(sql) : void 0;
+    const canResume = this.cdcEnabled() && shape.sinceSeq !== void 0 && shape.sinceEpoch === epoch && shape.sinceSeq <= cursor && (shape.sinceSeq === cursor || floor !== void 0 && floor <= shape.sinceSeq + 1);
+    const rowsPatch = canResume && shape.sinceSeq !== void 0 ? this.buildShapeDiff(sql, resolved, shape.sinceSeq, cursor) : this.buildShapeSeed(sql, resolved);
+    await awaitWsDrain(ws);
+    if (this.sendPoke(ws, [{ rowsPatch, shapeId: subId }], cursor, epoch, canResume ? shape.sinceSeq : void 0)) {
+      this.recordShapeMemo(ws, subId, cursor);
+    }
+    return "ok";
+  }
+  /**
+   * Fan the membership diff of every shape affected by this flush to its
+   * subscribers — the partial-replication parallel to
+   * {@link ShardDO.refreshSubscriptions}, called alongside it from
+   * {@link ShardDO.flushChangedTables}. For each socket (bounded fan-out, same
+   * concurrency + `awaitWsDrain` backpressure as the subscription path) it
+   * resolves each shape under the socket's identity, diffs only the shapes
+   * whose table changed in `(memoCursor, frameCursor]`, and emits one poke
+   * carrying a part per changed shape. No-op when no socket holds a shape.
+   */
+  async pokeShapeSubscribers(changed, frameCursor, frameEpoch) {
+    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);
+        return;
+      }
+      const attachment = this.readAttachment(ws);
+      const { shapes } = attachment;
+      if (!shapes) {
+        return;
+      }
+      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 {
+      }
+    };
+    await runSocketPool(sockets, pokeOne);
+  }
+  /**
+   * Diff every op-log-backed shape a socket holds against this flush, splitting
+   * the results into the poke parts to send and the per-shape memo advances. A
+   * `.global()` shape (driven by the alarm poll loop, not this flush) and a shape
+   * whose table didn't change are skipped; a shape whose resolve/diff throws is
+   * logged and skipped with its memo unadvanced so a later flush retries. Empty
+   * diffs advance unconditionally; part-bearing shapes advance only once the
+   * caller confirms the poke was delivered.
+   */
+  collectShapePokeParts(ws, shapes, identity, changed, checkpoint, sql, opRangeCache) {
+    const parts = [];
+    const emptyAdvanced = [];
+    const partAdvanced = [];
+    for (const [subId, shape] of Object.entries(shapes)) {
+      try {
+        const resolved = this.resolveShape(shape.name, shape.args ?? {}, identity);
+        if (!resolved || resolved.global || !changed.has(resolved.table)) {
+          continue;
+        }
+        const memoCursor = this.shapeMemos.get(ws)?.get(subId)?.cursor ?? 0;
+        const rowsPatch = this.buildShapeDiff(sql, resolved, memoCursor, checkpoint, opRangeCache);
+        if (rowsPatch.length > 0) {
+          parts.push({ rowsPatch, shapeId: subId });
+          partAdvanced.push(subId);
+        } else {
+          emptyAdvanced.push(subId);
+        }
+      } catch (error) {
+        this.recordShapeError(`shape:poke:${subId}`, error);
+      }
+    }
+    return { emptyAdvanced, partAdvanced, parts };
+  }
+  /**
+   * 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.
+   */
+  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([table]);
+    let from = sinceSeq;
+    for (; ; ) {
+      const { changes, cursor } = this.readShapeCdcPage(sql, from, tables);
+      for (const change of changes) {
+        latest.set(change.id, change);
+      }
+      if (changes.length === 0 || cursor === from || cursor >= upTo) {
+        break;
+      }
+      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 [];
+    }
+    const ids = [...latest.keys()];
+    const members = selectShapeMemberIds(sql, resolved.table, resolved.effectiveWhere, ids);
+    const ops = [];
+    for (const [id, change] of latest) {
+      if (members.has(id)) {
+        if (change.doc !== void 0) {
+          ops.push({ key: id, op: change.op, table: resolved.table, value: projectColumns(change.doc, resolved.columns) });
+        }
+        continue;
+      }
+      if (change.op !== "insert") {
+        ops.push({ key: id, op: "delete", table: resolved.table });
+      }
+    }
+    return ops;
+  }
+  /** Build the full insert-poke of a shape's current membership — the first-seed/full-reseed rowset. */
+  // eslint-disable-next-line class-methods-use-this -- instance method for symmetry with `buildShapeDiff`; reads via the passed `sql` handle
+  buildShapeSeed(sql, resolved) {
+    return selectShapeRows(sql, resolved.table, resolved.effectiveWhere).map((row) => {
+      return {
+        key: row.id,
+        op: "insert",
+        table: resolved.table,
+        value: projectColumns(row.doc, resolved.columns)
+      };
+    });
+  }
+  /**
+   * Seed a `.global()`-table shape: read its full membership from D1, ship it
+   * as one insert-poke, record the membership snapshot the alarm poll loop will
+   * diff against, and arm the poll alarm. A global shape has no op-log cursor,
+   * so the poke is stamped at this DO's current cursor (informational only) and
+   * carries no resume base — a reconnect always re-seeds full.
+   */
+  async seedGlobalShape(ws, subId, resolved, identity, connectionId) {
+    const rows = await this.readGlobalShapeRows(resolved, identity);
+    if (!this.withinGlobalShapeBound(rows.length, `shape:seed:${subId}`, resolved.table)) {
+      return {
+        code: "SHAPE_GLOBAL_TOO_LARGE",
+        message: `global shape membership for "${resolved.table}" exceeds the ${String(ShardDO.GLOBAL_SHAPE_MAX_ROWS)}-row cap; narrow it with a shape predicate or an RLS read policy`
+      };
+    }
+    const { next: snapshot, rowsPatch } = diffGlobalMembership(rows, /* @__PURE__ */ new Map(), { columns: resolved.columns, table: resolved.table });
+    await awaitWsDrain(ws);
+    if (this.sendPoke(ws, [{ rowsPatch, shapeId: subId }], this.currentCdcCursor() ?? 0, this.currentCdcEpoch(), void 0)) {
+      this.recordGlobalSnapshot(ws, subId, snapshot);
+      this.saveGlobalSnapshot(connectionId, subId, snapshot);
+    }
+    await this.scheduleGlobalPoll();
+    return "ok";
+  }
+  /**
+   * Re-read a global shape's membership from D1 and poke only the diff against
+   * the socket's last snapshot: a new key → `insert`, a changed projected value
+   * → `update`, a vanished key → `delete`. The snapshot advances to the fresh
+   * membership even when the diff is empty, so the next tick compares from here.
+   * No frame is sent when nothing changed (the common steady-state tick).
+   */
+  async refreshGlobalShape(ws, subId, resolved, identity, connectionId) {
+    const rows = await this.readGlobalShapeRows(resolved, identity);
+    if (!this.withinGlobalShapeBound(rows.length, `shape:poll:${subId}`, resolved.table)) {
+      return;
+    }
+    const previous = this.readGlobalSnapshot(ws, subId, connectionId);
+    const { next, rowsPatch } = diffGlobalMembership(rows, previous, { columns: resolved.columns, table: resolved.table });
+    if (rowsPatch.length === 0) {
+      this.recordGlobalSnapshot(ws, subId, next);
+      return;
+    }
+    await awaitWsDrain(ws);
+    if (this.sendPoke(ws, [{ rowsPatch, shapeId: subId }], this.currentCdcCursor() ?? 0, this.currentCdcEpoch(), void 0)) {
+      this.recordGlobalSnapshot(ws, subId, next);
+      this.saveGlobalSnapshot(connectionId, subId, next);
+    }
+  }
+  /**
+   * Read a socket's global-shape baseline, preferring the hot in-memory cache
+   * and falling back to the durable `__global_shape_snapshot` table on a miss (a
+   * cold socket after a hibernation eviction). The loaded baseline repopulates
+   * the cache so subsequent ticks in this wake hit memory. An empty
+   * `connectionId` (a socket that never went through the lifecycle-aware upgrade,
+   * e.g. a unit harness) skips the durable read and behaves as in-memory-only.
+   */
+  readGlobalSnapshot(ws, subId, connectionId) {
+    const cached = this.globalShapeSnapshots.get(ws)?.get(subId);
+    if (cached) {
+      return cached;
+    }
+    const stored = this.loadGlobalSnapshot(connectionId, subId);
+    this.recordGlobalSnapshot(ws, subId, stored);
+    return stored;
+  }
+  /** Record a socket's latest global-shape membership snapshot in the in-memory cache (creating the per-socket map lazily). */
+  recordGlobalSnapshot(ws, subId, snapshot) {
+    let snapshots = this.globalShapeSnapshots.get(ws);
+    if (!snapshots) {
+      snapshots = /* @__PURE__ */ new Map();
+      this.globalShapeSnapshots.set(ws, snapshots);
+    }
+    snapshots.set(subId, snapshot);
+  }
+  /**
+   * Load a durable global-shape baseline from SQLite, or an empty map when none
+   * is stored / the durable path is unavailable. A stub `sql` handle (unit
+   * harness) or a missing table degrades to in-memory-only behavior rather than
+   * failing the poll tick.
+   */
+  loadGlobalSnapshot(connectionId, subId) {
+    if (connectionId === "") {
+      return /* @__PURE__ */ new Map();
+    }
+    try {
+      return readGlobalShapeSnapshot(this.sql, connectionId, subId);
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  /**
+   * Persist a socket's global-shape baseline to SQLite so the poll-loop diff
+   * survives hibernation. A no-op for a connection-id-less socket or a stub
+   * `sql` handle (the in-memory cache then carries the baseline for the DO's
+   * lifetime, matching the pre-durable behavior).
+   */
+  saveGlobalSnapshot(connectionId, subId, snapshot) {
+    if (connectionId === "") {
+      return;
+    }
+    try {
+      writeGlobalShapeSnapshot(this.sql, connectionId, subId, snapshot);
+    } catch {
+    }
+  }
+  /**
+   * Arm the poll alarm for `.global()` shapes if one isn't already pending.
+   * Idempotent — every global-shape seed calls it, but only the first arms the
+   * alarm. Degrades to a no-op when the runtime exposes no `setAlarm` (the unit
+   * harness): a global shape is then seed-only, which the poll-loop tests assert
+   * by driving {@link ShardDO.alarm} directly.
+   */
+  async scheduleGlobalPoll() {
+    if (this.globalPollScheduled) {
+      return;
+    }
+    const { setAlarm } = this.state.storage;
+    if (!setAlarm) {
+      return;
+    }
+    this.globalPollScheduled = true;
+    try {
+      await setAlarm.call(this.state.storage, Date.now() + ShardDO.GLOBAL_SHAPE_POLL_INTERVAL_MS);
+    } catch {
+      this.globalPollScheduled = false;
+    }
+  }
+  /**
+   * Record a contained shape-tier error (poll / poke / seed) into the DO's log
+   * ring without aborting the rest of the pass. The shape pipeline is a
+   * best-effort fan-out: one socket's read or one shape's resolve failing must
+   * never take down the others — so callers swallow the throw and surface it
+   * here for diagnosis. `context` is a synthetic `shape:phase:subId` path.
+   */
+  recordShapeError(context, error) {
+    this.logs.push({
+      functionPath: context,
+      level: "error",
+      message: error instanceof Error ? error.message : String(error),
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Guard a global shape's materialized membership against {@link
+   * ShardDO.GLOBAL_SHAPE_MAX_ROWS}. Returns `true` when the row count is within
+   * the cap; otherwise records a diagnosable error and returns `false` so the
+   * caller fails the shape closed (no snapshot retained, no poke sent) rather
+   * than risking a DO eviction on an unbounded global table. The transient read
+   * buffer is bounded by the same gate — an over-cap membership is dropped, not
+   * snapshotted per socket.
+   */
+  withinGlobalShapeBound(rowCount, context, table) {
+    if (rowCount <= ShardDO.GLOBAL_SHAPE_MAX_ROWS) {
+      return true;
+    }
+    this.recordShapeError(
+      context,
+      new Error(
+        `global shape membership for "${table}" (${String(rowCount)} rows) exceeds the ${String(ShardDO.GLOBAL_SHAPE_MAX_ROWS)}-row cap; narrow it with a shape predicate or an RLS read policy`
+      )
+    );
+    return false;
+  }
+  /**
+   * Refresh every `.global()`-table shape held across all live sockets, one
+   * diff-poke per (socket, shape). Returns the number of global shapes still
+   * subscribed so {@link ShardDO.alarm} knows whether to re-arm. Expired sockets
+   * are dropped in passing (mirrors {@link ShardDO.pokeShapeSubscribers}).
+   */
+  async pollGlobalShapes() {
+    const sockets = [...this.state.getWebSockets()];
+    let remaining = 0;
+    for (const ws of sockets) {
+      if (this.isSocketExpired(ws)) {
+        this.dropExpiredSocket(ws);
+        continue;
+      }
+      const attachment = this.readAttachment(ws);
+      const { shapes } = attachment;
+      if (!shapes) {
+        continue;
+      }
+      const identity = { identity: attachment.identity, userId: attachment.userId };
+      remaining += await this.pollSocketGlobalShapes(ws, shapes, identity, attachment.connectionId ?? "");
+    }
+    return remaining;
+  }
+  /**
+   * Refresh one socket's `.global()`-table shapes, containing per-shape
+   * failures so a single throw never aborts the poll tick (and with it the
+   * re-arm). Returns the count of global shapes still subscribed on this socket
+   * — a failed `resolveShape`/read keeps its shape counted so the alarm keeps
+   * polling and retries next tick.
+   */
+  async pollSocketGlobalShapes(ws, shapes, identity, connectionId) {
+    let count = 0;
+    for (const [subId, shape] of Object.entries(shapes)) {
+      let resolved;
+      try {
+        resolved = this.resolveShape(shape.name, shape.args ?? {}, identity);
+      } catch (error) {
+        count += 1;
+        this.recordShapeError(`shape:poll:${subId}`, error);
+        continue;
+      }
+      if (!resolved?.global) {
+        continue;
+      }
+      count += 1;
+      try {
+        await this.refreshGlobalShape(ws, subId, resolved, identity, connectionId);
+      } catch (error) {
+        this.recordShapeError(`shape:poll:${subId}`, error);
+      }
+    }
+    return count;
+  }
+  /**
+   * Send one poke (`pokeStart` → `pokePart` per shape → `pokeEnd`) to a socket.
+   * All parts apply atomically at `pokeEnd`. Returns `true` when every frame was
+   * handed to the socket, `false` when a send threw mid-poke (the socket closed)
+   * — callers must NOT advance their shape baselines on a `false` so the client
+   * re-receives the rows on its next flush/reconnect instead of losing them.
+   */
+  sendPoke(ws, parts, checkpoint, epoch, baseCheckpoint) {
+    this.pokeSequence += 1;
+    const pokeId = `poke-${String(this.pokeSequence)}`;
+    const frames = buildPokeFrames(parts, { baseCheckpoint, checkpoint, epoch, lastMutationId: this.socketClientWatermark(ws), pokeId });
+    try {
+      for (const frame of frames) {
+        ws.send(frame);
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * The recipient client's `__client_watermark` for stamping a poke's
+   * `lastMutationId`, or `undefined` when the socket announced no `clientId`
+   * (a client that doesn't use custom mutators — nothing to drop an overlay
+   * for). Read off the attachment so it survives hibernation.
+   */
+  socketClientWatermark(ws) {
+    const attachment = this.readAttachment(ws);
+    const { clientId } = attachment;
+    if (clientId === void 0) {
+      return void 0;
+    }
+    try {
+      return readClientWatermark(this.sql, attachment.userId ?? "", clientId);
+    } catch {
+      return void 0;
+    }
+  }
+  /** Record a shape's poke baseline cursor on a socket (creating the per-socket map lazily). */
+  recordShapeMemo(ws, subId, cursor) {
+    let memos = this.shapeMemos.get(ws);
+    if (!memos) {
+      memos = /* @__PURE__ */ new Map();
+      this.shapeMemos.set(ws, memos);
+    }
+    memos.set(subId, { cursor });
+  }
   /**
    * Record `outcome` as this socket's diff baseline for `subId` without
    * sending a frame. Used by the resume fast-path, where the client keeps its
@@ -3750,25 +4840,16 @@ 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 = [];
     const deltas = existing === void 0 ? void 0 : subscriptionListDeltas(existing.lastJson, outcome.result, outcome.tables.values().next().value ?? "", deltaFrames);
-    memos.set(subId, { lastJson: json, tables: outcome.tables });
-    if (deltas !== void 0) {
-      const idJson = JSON.stringify(subId);
-      for (const deltaBody of deltaFrames) {
-        try {
-          ws.send(`{"type":"delta","id":${idJson},"delta":${deltaBody}${cursorSuffix}}`);
-        } catch {
-        }
-      }
-      return;
-    }
-    try {
-      ws.send(`{"type":"data","id":${JSON.stringify(subId)},"data":${json}${cursorSuffix}}`);
-    } catch {
-    }
+    const delivered = deltas === void 0 ? trySendFrame(ws, `{"type":"data","id":${JSON.stringify(subId)},"data":${json}${cursorSuffix}}`) : sendDeltaFrames(ws, subId, deltaFrames, cursorSuffix);
+    memos.set(subId, { lastJson: delivered ? json : existing?.lastJson ?? UNDELIVERED_BASELINE, tables: outcome.tables });
   }
   /**
    * Gate the upgrade request against two complementary controls:
@@ -3990,10 +5071,7 @@ class ShardDO {
       if (ws === sender || this.readAttachment(ws).whispers?.includes(topic) !== true) {
         continue;
       }
-      try {
-        ws.send(frame);
-      } catch {
-      }
+      trySendFrame(ws, frame);
     }
   }
   // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method grouped with the hibernation/attachment helpers; reads only the socket