@lunora/do 1.0.0-alpha.8 → 1.0.0-alpha.9

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

@@ -14,8 +14,9 @@ import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } fr
 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 './CDC_LOG_TABLE-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;
@@ -350,6 +351,58 @@ 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 DANGLING_SCAN_CAP = 5e3;
 const DANGLING_RESULT_CAP = 500;
 const DOC_COLUMN = "__doc__";
@@ -829,6 +882,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) {
@@ -913,6 +973,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<rowKey, hash>`) 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
@@ -1014,6 +1096,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
@@ -1064,6 +1179,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();
   /**
@@ -1195,6 +1343,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";
@@ -1210,20 +1362,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) {
@@ -1249,6 +1406,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;
@@ -1286,6 +1447,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);
@@ -1317,6 +1481,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" }));
@@ -1367,12 +1545,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
@@ -2079,13 +2286,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) {
@@ -2101,6 +2310,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 <= 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
@@ -2150,6 +2528,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
@@ -2221,6 +2649,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
@@ -3573,8 +4041,8 @@ class ShardDO {
    * 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` call, so a later batch always reflects the latest
-   * committed state.
+   * `refreshSubscriptions` / `pokeShapeSubscribers` call, so a later batch
+   * always reflects the latest committed state.
    */
   async drainSubscriptionRefreshes() {
     if (this.refreshInFlight) {
@@ -3585,7 +4053,9 @@ class ShardDO {
       let batch = this.pendingRefreshTables;
       while (batch && batch.size > 0) {
         this.pendingRefreshTables = void 0;
-        await this.refreshSubscriptions(batch);
+        const frameCursor = this.currentCdcCursor();
+        const frameEpoch = this.currentCdcEpoch();
+        await Promise.all([this.refreshSubscriptions(batch), this.pokeShapeSubscribers(batch, frameCursor, frameEpoch)]);
         batch = this.pendingRefreshTables;
       }
     } finally {
@@ -3733,6 +4203,513 @@ 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 pokeOne = async (ws) => {
+      if (this.isSocketExpired(ws)) {
+        this.dropExpiredSocket(ws);
+        return;
+      }
+      const attachment = this.readAttachment(ws);
+      const { shapes } = attachment;
+      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);
+          }
+        }
+      }
+    };
+    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()));
+  }
+  /**
+   * 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) {
+    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);
+        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 };
+  }
+  /**
+   * 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).
+   */
+  // 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) {
+    const latest = /* @__PURE__ */ new Map();
+    const tables = /* @__PURE__ */ new Set([resolved.table]);
+    let from = sinceSeq;
+    for (; ; ) {
+      const { changes, cursor } = readCdcChanges(sql, { sinceSeq: from, tables });
+      for (const change of changes) {
+        latest.set(change.id, change);
+      }
+      if (changes.length === 0 || cursor === from || cursor >= upTo) {
+        break;
+      }
+      from = cursor;
+    }
+    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