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

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

@@ -1,20 +1,25 @@
 import { drizzle } from 'drizzle-orm/durable-sqlite';
+import { e as encodeWire, a as awaitWsDrain, t as trySendFrame, d as decodeWire, s as subscriptionListDeltas, b as sendDeltaFrames } from './subscription-delivery-CK8qga-k.mjs';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-DZEhUeyI.mjs';
-import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKET_MS-CiHHYeJi.mjs';
-import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-PTtTiQ7U.mjs';
+import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
+import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-DfPxn8I0.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 { createFanoutCounters, ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, summarizeFanoutTopics, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, recordFanoutPass, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-DSUQ5fX9.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-BYlSGY0N.mjs';
+import { stableStringify } from './stableStringify-MydiuScU.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 { 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 { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-0RaIOy7J.mjs';
+
+const MAX_BATCH_ENTRIES = 500;
 
 const AUDIT_LOG_TABLE = "__lunora_audit__";
 const AUDIT_LOG_RETENTION = 1e3;
@@ -76,6 +81,38 @@ const readAuditLog = (sql, options = {}) => {
   });
 };
 
+const SHARED_BATCH_HEADERS = [
+  "x-lunora-userid",
+  "x-lunora-identity",
+  "x-d1-bookmark",
+  "x-lunora-client-ip",
+  "x-lunora-system",
+  "x-lunora-shard-binding"
+];
+const buildBatchEntryRequest = (batchRequest, entry) => {
+  const headers = new Headers({ "content-type": "application/json" });
+  for (const name of SHARED_BATCH_HEADERS) {
+    const value = batchRequest.headers.get(name);
+    if (value !== null) {
+      headers.set(name, value);
+    }
+  }
+  if (entry.mutationId !== void 0) {
+    headers.set("x-lunora-mutation-id", entry.mutationId);
+  }
+  if (entry.clientId !== void 0) {
+    headers.set("x-lunora-client-id", entry.clientId);
+  }
+  if (entry.clientSeq !== void 0) {
+    headers.set("x-lunora-client-seq", String(entry.clientSeq));
+  }
+  return new Request("https://shard.internal/rpc", {
+    body: JSON.stringify({ args: entry.args ?? {}, functionPath: entry.functionPath }),
+    headers,
+    method: "POST"
+  });
+};
+
 const QUERY_METRICS_TABLE = "__lunora_metrics_queries";
 const QUERY_METRICS_MAX_SQL_LEN = 512;
 const QUERY_METRICS_MAX_STATEMENTS = 500;
@@ -142,6 +179,798 @@ const readQueryMetrics = (sql) => {
   });
 };
 
+const RELAY_NAME_INFIX = "::relay::";
+const relayName = (ownerKey, index) => `${ownerKey}${RELAY_NAME_INFIX}${String(index)}`;
+const parseRelayName = (name) => {
+  const at = name.lastIndexOf(RELAY_NAME_INFIX);
+  if (at === -1) {
+    return void 0;
+  }
+  const ownerKey = name.slice(0, at);
+  const indexText = name.slice(at + RELAY_NAME_INFIX.length);
+  const relayIndex = Number(indexText);
+  if (ownerKey.length === 0 || !Number.isInteger(relayIndex) || relayIndex < 0 || String(relayIndex) !== indexText) {
+    return void 0;
+  }
+  return { ownerKey, relayIndex };
+};
+
+const shapeRoutingKey = (name, args) => stableStringify({ args: args ?? {}, name });
+const DEFAULT_PROMOTION_THRESHOLDS = { tDown: 4e3, tUp: 8e3 };
+const nextPromotionState = (current, subscribers, thresholds = DEFAULT_PROMOTION_THRESHOLDS) => {
+  if (thresholds.tDown >= thresholds.tUp) {
+    throw new Error(`invalid promotion thresholds: tDown (${String(thresholds.tDown)}) must be < tUp (${String(thresholds.tUp)})`);
+  }
+  if (current === "owned") {
+    return subscribers >= thresholds.tUp ? "promoted" : "owned";
+  }
+  return subscribers < thresholds.tDown ? "owned" : "promoted";
+};
+const clampPromotionThresholds = (tUp, tDownRaw) => {
+  if (tDownRaw < tUp) {
+    return { tDown: tDownRaw, tUp };
+  }
+  return { tDown: Math.min(Math.max(1, Math.floor(tUp / 2)), tUp - 1), tUp };
+};
+
+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(encodeWire(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 encodeRowsPatch = (rowsPatch) => rowsPatch.map((op) => op.value === void 0 ? op : { ...op, value: encodeWire(op.value) });
+const buildPokeFrames = (parts, meta, options = {}) => {
+  const { baseCheckpoint, checkpoint, epoch, lastMutationId, pokeId } = meta;
+  const frames = [JSON.stringify({ baseCheckpoint, epoch, pokeId, type: "pokeStart" })];
+  for (const part of parts) {
+    const rowsPatch = options.preEncoded ? part.rowsPatch : encodeRowsPatch(part.rowsPatch);
+    frames.push(
+      JSON.stringify({
+        pokeId,
+        rowsPatch,
+        shapeId: part.shapeId,
+        type: "pokePart",
+        ...lastMutationId === void 0 ? {} : { lastMutationId }
+      })
+    );
+  }
+  frames.push(JSON.stringify({ checkpoint, epoch, pokeId, type: "pokeEnd" }));
+  return frames;
+};
+
+const DEFAULT_RELAY_FAN = 2;
+const DEFAULT_MAX_RELAYS = 8;
+const RELAY_SECRET_KEY = "LUNORA_RELAY_SECRET";
+const RELAY_SIGNATURE_HEADER = "x-lunora-relay-sig";
+const relaySecretOf = (env) => {
+  const value = env?.[RELAY_SECRET_KEY];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+const constantTimeEqual$1 = (a, b) => {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    const charA = a.charCodeAt(index);
+    const charB = b.charCodeAt(index);
+    mismatch |= charA ^ charB;
+  }
+  return mismatch === 0;
+};
+const signRelayBody = async (secret, body) => {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
+  return [...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+const envPositiveInt = (env, key, fallback) => {
+  const raw = env?.[key];
+  let parsed = Number.NaN;
+  if (typeof raw === "string") {
+    parsed = Number.parseInt(raw, 10);
+  } else if (typeof raw === "number") {
+    parsed = raw;
+  }
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+};
+const RELAY_MULTICAST_IDENTITY = {};
+const assertNeverFrame = (frame) => {
+  throw new Error(`unhandled relay frame: ${JSON.stringify(frame)}`);
+};
+const asRelayNamespace = (value) => {
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const candidate = value;
+  return typeof candidate.idFromName === "function" && typeof candidate.get === "function" ? candidate : void 0;
+};
+const jsonRelayResponse = (body) => Response.json(body, { headers: { "content-type": "application/json" } });
+const noContent = () => new Response(null, { status: 204 });
+class RelayLink {
+  constructor(host, roleId) {
+    this.host = host;
+    this.roleId = roleId;
+  }
+  host;
+  roleId;
+  /**
+   * Serve the internal `/_lunora/relay` control channel: parse the frame, then
+   * dispatch to the role hooks. One exhaustive switch means a new frame type added
+   * to `relay.ts` without a case here is a COMPILE error, not a runtime mis-route.
+   */
+  async handleControl(request) {
+    let raw;
+    try {
+      raw = await request.text();
+    } catch {
+      return new Response("bad request", { status: 400 });
+    }
+    const secret = relaySecretOf(this.host.env());
+    if (secret !== void 0) {
+      const supplied = request.headers.get(RELAY_SIGNATURE_HEADER);
+      const expected = await signRelayBody(secret, raw);
+      if (supplied === null || !constantTimeEqual$1(supplied, expected)) {
+        return new Response("forbidden", { status: 403 });
+      }
+    }
+    let message;
+    try {
+      message = JSON.parse(raw);
+    } catch {
+      return new Response("bad request", { status: 400 });
+    }
+    switch (message.type) {
+      case "relay_attach": {
+        this.onAttach(message.relayIndex);
+        return noContent();
+      }
+      case "relay_detach": {
+        this.onDetach(message.relayIndex);
+        return noContent();
+      }
+      case "relay_frame": {
+        this.host.deliverWhisperLocal(message.topic, message.frame, void 0);
+        await this.onWhisperFrame(message);
+        return noContent();
+      }
+      case "relay_shape_poke": {
+        const iterated = this.host.getWebSockets().length;
+        const startMs = Date.now();
+        const delivered = this.onShapePoke(message);
+        this.host.recordShapePokeFanout(iterated, delivered, Date.now() - startMs);
+        return noContent();
+      }
+      case "relay_shape_subscribe": {
+        return jsonRelayResponse(this.onShapeSubscribe(message));
+      }
+      default: {
+        return assertNeverFrame(message);
+      }
+    }
+  }
+  /** The hard cap on relays per shard (`LUNORA_MAX_RELAYS`) — a deployment constant the runtime surfaces in Studio as the cost ceiling. */
+  maxRelays() {
+    return envPositiveInt(this.host.env(), "LUNORA_MAX_RELAYS", DEFAULT_MAX_RELAYS);
+  }
+  /** Whether this DO can currently address its siblings (a namespace binding has been learned) — the relay tier is inert in single-DO mode. */
+  canAddressSiblings() {
+    return this.relayNamespace() !== void 0;
+  }
+  /** Resolve this DO's own namespace binding so it can address sibling owners/relays, or `undefined` when unknown. */
+  relayNamespace() {
+    const binding = this.host.shardBinding();
+    if (binding === void 0) {
+      return void 0;
+    }
+    return asRelayNamespace(this.host.env()?.[binding]);
+  }
+  /** POST a control frame to a sibling by name, fire-and-forget. Best-effort: a transient cross-DO failure drops the frame rather than throwing into the handler. */
+  async postRelayMessage(targetName, message) {
+    await this.requestRelayMessage(targetName, message);
+  }
+  /**
+   * POST a control frame to a sibling by name and return its response (the shape-seed
+   * path needs the owner's frames back). Best-effort: a transient cross-DO failure
+   * returns `undefined` rather than throwing.
+   * @returns the sibling's response, or `undefined` when it can't be reached
+   */
+  async requestRelayMessage(targetName, message) {
+    const namespace = this.relayNamespace();
+    if (namespace === void 0) {
+      return void 0;
+    }
+    const stub = typeof namespace.getByName === "function" ? namespace.getByName(targetName) : namespace.get(namespace.idFromName(targetName));
+    const body = JSON.stringify(message);
+    const headers = { "content-type": "application/json", "x-lunora-shard-binding": this.host.shardBinding() ?? "" };
+    const secret = relaySecretOf(this.host.env());
+    if (secret !== void 0) {
+      headers[RELAY_SIGNATURE_HEADER] = await signRelayBody(secret, body);
+    }
+    try {
+      return await stub.fetch("https://relay.internal/_lunora/relay", {
+        body,
+        headers,
+        method: "POST"
+      });
+    } catch {
+      return void 0;
+    }
+  }
+}
+class OwnerRelay extends RelayLink {
+  /** Memoized RLS-uniform verdict per `(name, args)` shape — uniformity is stable, so the gate probe runs at most once per distinct shape. */
+  shapeUniformCache = /* @__PURE__ */ new Map();
+  /** Active relay indices, hydrated once from `__lunora_relays` and cached for the synchronous forward path. */
+  relaySetCache;
+  /** Relay-uniform shapes a relay has subscribers for, keyed by `(name, args)`. `cursor` is the cohort frontier the owner has multicast deltas up to. */
+  relayShapeRegistry = /* @__PURE__ */ new Map();
+  /** NON-uniform (identity-scoped) relay shapes, one entry per relay socket, keyed `relayIndex:connectionId:subId`. Each is served live by a per-socket proxy poke. */
+  relayShapeProxies = /* @__PURE__ */ new Map();
+  /** The owner's current promotion state (plan 075 Phase 4), carried across `relayCount()` calls so hysteresis has memory — a shard hovering near the threshold can't flap. */
+  promotionState = "owned";
+  constructor(host, ownerKey) {
+    super(host, { ownerKey });
+  }
+  async forwardWhisper(topic, frame) {
+    if (!this.canAddressSiblings()) {
+      return;
+    }
+    const relays = this.ownerRelaySet();
+    if (relays.size === 0) {
+      return;
+    }
+    await Promise.all([...relays].map((index) => this.postRelayMessage(relayName(this.roleId.ownerKey, index), { frame, topic, type: "relay_frame" })));
+  }
+  async onFlush(changed, frameCursor) {
+    await Promise.all([this.multicastShapePokes(changed, frameCursor), this.proxyShapePokes(changed, frameCursor)]);
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: an owner serves its own shape subscribers locally, never through a relay
+  seedRelayShape() {
+    return Promise.resolve(void 0);
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only a relay announces
+  announce() {
+    return Promise.resolve();
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only a relay drains
+  announceDrain() {
+    return Promise.resolve();
+  }
+  /**
+   * How many relays the runtime should spread new connections across for this shard
+   * (plan 075 Phase 2, hysteresis added in Phase 4). `0` keeps every connection on
+   * the owner. The owner promotes once its live socket count reaches
+   * `LUNORA_RELAY_THRESHOLD` (`tUp`), fanning to a fixed `LUNORA_RELAY_FAN` (capped
+   * by `LUNORA_MAX_RELAYS`, the cost ceiling), and only collapses back to
+   * owner-served once subscribers drain below `LUNORA_RELAY_COLLAPSE_THRESHOLD`
+   * (`tDown`) — the band between the two holds the current state so a shard
+   * hovering near the threshold can't flap. {@link clampPromotionThresholds}
+   * guarantees a valid `tDown < tUp` band even under a misconfigured collapse
+   * threshold. Advances the promotion latch, so it is not a pure read.
+   */
+  relayCount() {
+    const subscribers = this.host.getWebSockets().length;
+    const tUp = envPositiveInt(this.host.env(), "LUNORA_RELAY_THRESHOLD", DEFAULT_PROMOTION_THRESHOLDS.tUp);
+    const tDownRaw = envPositiveInt(this.host.env(), "LUNORA_RELAY_COLLAPSE_THRESHOLD", DEFAULT_PROMOTION_THRESHOLDS.tDown);
+    this.promotionState = nextPromotionState(this.promotionState, subscribers, clampPromotionThresholds(tUp, tDownRaw));
+    if (this.promotionState === "owned") {
+      return 0;
+    }
+    const maxRelays = envPositiveInt(this.host.env(), "LUNORA_MAX_RELAYS", DEFAULT_MAX_RELAYS);
+    const fan = envPositiveInt(this.host.env(), "LUNORA_RELAY_FAN", DEFAULT_RELAY_FAN);
+    return Math.min(maxRelays, Math.max(1, fan));
+  }
+  /**
+   * The RLS-uniform gate (plan 075 Phase 3, review-hardened): whether a reactive
+   * shape may be relay-multicast — i.e. one delta is correct for **every**
+   * subscriber. Fail-closed on four grounds — a static RLS read-policy guard, the
+   * anonymous multicast identity as the probe base, two `Proxy`-backed probes that
+   * yield a distinct value for ANY accessed claim (so any claim a `where` reads —
+   * even a custom one outside `rls()` — diverges), and a wholesale-copy backstop.
+   * Cached per `(name, args)`, whose uniformity is stable.
+   */
+  isShapeRelayUniform(name, args) {
+    const cacheKey = shapeRoutingKey(name, args);
+    const cached = this.shapeUniformCache.get(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const uniform = this.probeShapeRelayUniform(name, args);
+    this.shapeUniformCache.set(cacheKey, uniform);
+    return uniform;
+  }
+  onAttach(index) {
+    this.addRelayToSet(index);
+  }
+  onDetach(index) {
+    this.removeRelayFromSet(index);
+  }
+  async onWhisperFrame(message) {
+    await Promise.all(
+      [...this.ownerRelaySet()].filter((index) => index !== message.originRelay).map(
+        (index) => this.postRelayMessage(relayName(this.roleId.ownerKey, index), { frame: message.frame, topic: message.topic, type: "relay_frame" })
+      )
+    );
+  }
+  onShapeSubscribe(message) {
+    return this.buildShapeSeedFrames(message);
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: an owner doesn't receive multicast pokes (it sends them)
+  onShapePoke() {
+    return 0;
+  }
+  /**
+   * Owner side (slice B.2): for every registered relay-uniform shape whose table
+   * changed this flush, compute the membership diff ONCE over `(cohort cursor,
+   * frameCursor]` and multicast the `rowsPatch` to every relay. Advances the cohort
+   * cursor synchronously (before any await) so a seed interleaving during the
+   * multicast registers at `frameCursor` and is skipped by this in-flight poke.
+   */
+  async multicastShapePokes(changed, frameCursor) {
+    if (this.relayShapeRegistry.size === 0) {
+      return;
+    }
+    const relays = this.ownerRelaySet();
+    if (relays.size === 0) {
+      return;
+    }
+    const epoch = this.host.currentCdcEpoch();
+    const sends = [];
+    for (const entry of this.relayShapeRegistry.values()) {
+      let resolved;
+      try {
+        resolved = this.host.resolveShape(entry.name, entry.args, RELAY_MULTICAST_IDENTITY);
+      } catch {
+        continue;
+      }
+      if (resolved === void 0 || resolved.global === true || !changed.has(resolved.table)) {
+        continue;
+      }
+      const fromCursor = entry.cursor;
+      const rowsPatch = this.host.buildShapeDiff(resolved, fromCursor, frameCursor);
+      if (rowsPatch.length === 0) {
+        continue;
+      }
+      entry.cursor = frameCursor;
+      const poke = {
+        args: entry.args,
+        checkpoint: frameCursor,
+        epoch,
+        fromCursor,
+        name: entry.name,
+        // Wire-encode before the poke crosses the owner→relay `JSON.stringify`
+        // hop (`requestRelayMessage`); the relay re-frames it with
+        // `preEncoded` so a `bytes`/`bigint` shape column isn't dropped/truncated.
+        rowsPatch: encodeRowsPatch(rowsPatch),
+        type: "relay_shape_poke"
+      };
+      for (const index of relays) {
+        sends.push(this.postRelayMessage(relayName(this.roleId.ownerKey, index), poke));
+      }
+    }
+    await Promise.all(sends);
+  }
+  /**
+   * Owner side (review MEDIUM-3): for every NON-uniform relay-shape proxy whose
+   * table changed this flush, compute that one subscriber's diff over `(entry.cursor,
+   * frameCursor]` UNDER ITS OWN forwarded identity (RLS-correct) and deliver a
+   * `targetConnectionId`-addressed poke to just that socket's relay. Each entry
+   * tracks its own cursor — the diffs are identity-specific, no cohort sharing.
+   */
+  async proxyShapePokes(changed, frameCursor) {
+    if (this.relayShapeProxies.size === 0) {
+      return;
+    }
+    const epoch = this.host.currentCdcEpoch();
+    const sends = [];
+    for (const entry of this.relayShapeProxies.values()) {
+      let resolved;
+      try {
+        resolved = this.host.resolveShape(entry.name, entry.args, entry.identity);
+      } catch {
+        continue;
+      }
+      if (resolved === void 0 || resolved.global === true || !changed.has(resolved.table)) {
+        continue;
+      }
+      const fromCursor = entry.cursor;
+      const rowsPatch = this.host.buildShapeDiff(resolved, fromCursor, frameCursor);
+      if (rowsPatch.length === 0) {
+        continue;
+      }
+      entry.cursor = frameCursor;
+      const poke = {
+        args: entry.args,
+        checkpoint: frameCursor,
+        epoch,
+        fromCursor,
+        name: entry.name,
+        // Wire-encode before the owner→relay `JSON.stringify` hop (see the
+        // cohort-multicast path); the relay re-frames it with `preEncoded`.
+        rowsPatch: encodeRowsPatch(rowsPatch),
+        targetConnectionId: entry.connectionId,
+        type: "relay_shape_poke"
+      };
+      sends.push(this.postRelayMessage(relayName(this.roleId.ownerKey, entry.relayIndex), poke));
+    }
+    await Promise.all(sends);
+  }
+  /**
+   * Serialize a shape's seed poke frames for a relay to deliver verbatim. Resolves
+   * under the forwarded socket identity (so RLS applies exactly as for a local
+   * subscribe), self-heals the relay set, registers the shape for live updates
+   * (cohort multicast when uniform, per-socket proxy when not), and stamps the
+   * relay's cohort memo at the registry FRONTIER (not the global cursor) so a late
+   * joiner is never stranded. `lastMutationId` is omitted (relayed sockets are
+   * owner-served for custom mutators).
+   * @returns the serialized frames + the cohort-memo cursor, or an error
+   */
+  buildShapeSeedFrames(request) {
+    const identity = { identity: request.identity, userId: request.userId };
+    let resolved;
+    try {
+      resolved = this.host.resolveShape(request.name, request.args, identity);
+    } catch (error) {
+      return { error: { code: "SHAPE_RESOLVE_FAILED", message: error instanceof Error ? error.message : "shape resolve failed" } };
+    }
+    if (resolved === void 0 || resolved.global === true) {
+      return { error: { code: "SHAPE_NOT_FOUND", message: `shape not relayable: ${request.name}` } };
+    }
+    if (request.relayIndex !== void 0) {
+      this.addRelayToSet(request.relayIndex);
+    }
+    const { baseCheckpoint, cursor, epoch, rowsPatch } = this.host.computeOpLogShapeSeed(
+      { args: request.args, name: request.name, sinceEpoch: request.sinceEpoch, sinceSeq: request.sinceSeq },
+      resolved
+    );
+    let cohortCursor = cursor;
+    if (this.isShapeRelayUniform(request.name, request.args)) {
+      const routingKey = shapeRoutingKey(request.name, request.args);
+      let entry = this.relayShapeRegistry.get(routingKey);
+      if (entry === void 0) {
+        entry = { args: request.args, cursor, name: request.name };
+        this.relayShapeRegistry.set(routingKey, entry);
+      }
+      cohortCursor = entry.cursor;
+    } else if (request.relayIndex !== void 0 && request.connectionId !== void 0) {
+      this.relayShapeProxies.set(`${String(request.relayIndex)}:${request.connectionId}:${request.subId}`, {
+        args: request.args,
+        connectionId: request.connectionId,
+        cursor,
+        epoch,
+        identity,
+        name: request.name,
+        relayIndex: request.relayIndex,
+        subId: request.subId
+      });
+    }
+    const frames = buildPokeFrames([{ rowsPatch, shapeId: request.subId }], {
+      baseCheckpoint,
+      checkpoint: cursor,
+      epoch,
+      lastMutationId: void 0,
+      pokeId: this.host.nextPokeId()
+    });
+    return { cursor: cohortCursor, epoch, frames };
+  }
+  /** Ensure the reserved owner-side relay-set table exists (auto-hidden from the data browser by the `__lunora` prefix). */
+  ensureRelayTable() {
+    this.host.sql().exec("CREATE TABLE IF NOT EXISTS __lunora_relays (idx INTEGER PRIMARY KEY)");
+  }
+  /** The owner's active relay indices, hydrated once from `__lunora_relays` and cached for the synchronous forward path. */
+  ownerRelaySet() {
+    if (this.relaySetCache === void 0) {
+      this.ensureRelayTable();
+      const rows = this.host.sql().exec("SELECT idx FROM __lunora_relays").toArray();
+      this.relaySetCache = new Set(rows.map((row) => Number(row.idx)));
+    }
+    return this.relaySetCache;
+  }
+  /** Record a relay as active (idempotent), persisting it so the set survives the owner's hibernation. */
+  addRelayToSet(index) {
+    this.ensureRelayTable();
+    this.host.sql().exec("INSERT OR IGNORE INTO __lunora_relays (idx) VALUES (?)", index);
+    this.ownerRelaySet().add(index);
+  }
+  /** Drop a drained relay from the set and prune its dead per-socket proxy entries; on full drain, clear the (now dead) registry + uniform cache to bound growth. */
+  removeRelayFromSet(index) {
+    this.ensureRelayTable();
+    this.host.sql().exec("DELETE FROM __lunora_relays WHERE idx = ?", index);
+    const set = this.ownerRelaySet();
+    set.delete(index);
+    for (const [key, entry] of this.relayShapeProxies) {
+      if (entry.relayIndex === index) {
+        this.relayShapeProxies.delete(key);
+      }
+    }
+    if (set.size === 0) {
+      this.relayShapeRegistry.clear();
+      this.shapeUniformCache.clear();
+    }
+  }
+  /**
+   * The one-shot computation behind {@link OwnerRelay.isShapeRelayUniform}, made
+   * sound against the cross-identity row-leak (review). Resolves under the anonymous
+   * multicast identity (the base) plus two `Proxy`-backed identities that return a
+   * distinct value for ANY accessed claim, requires all to agree on table + where +
+   * columns, rejects any table with an RLS read policy or ANY masked column
+   * defined (even if unprojected — see {@link OwnerRelay.tableHasAnyMask}), and
+   * fails closed if the claims are enumerated (a wholesale copy the proxy can't
+   * differentiate).
+   */
+  probeShapeRelayUniform(name, args) {
+    let base;
+    try {
+      base = this.host.resolveShape(name, args, RELAY_MULTICAST_IDENTITY);
+    } catch {
+      return false;
+    }
+    if (base === void 0 || base.global === true) {
+      return false;
+    }
+    if (this.host.rlsMetadata().policies.some((policy) => policy.on === "read" && policy.table === base.table)) {
+      return false;
+    }
+    if (this.tableHasAnyMask(base.table)) {
+      return false;
+    }
+    const baseWhere = stableStringify(base.effectiveWhere);
+    const baseColumns = stableStringify(base.columns);
+    let enumerated = false;
+    const populate = (side) => {
+      const backing = { groups: [`grp_${side}`], roles: [side], sub: `__lunora_probe_${side}__` };
+      const claims = /* @__PURE__ */ new Proxy(backing, {
+        get: (target, key) => {
+          if (typeof key === "symbol" || key in target) {
+            return Reflect.get(target, key);
+          }
+          return `${side}:${key}`;
+        },
+        getOwnPropertyDescriptor: (target, key) => {
+          enumerated = true;
+          return Reflect.getOwnPropertyDescriptor(target, key);
+        },
+        has: (target, key) => typeof key === "symbol" ? Reflect.has(target, key) : true,
+        ownKeys: (target) => {
+          enumerated = true;
+          return Reflect.ownKeys(target);
+        }
+      });
+      return { identity: claims, userId: `__lunora_probe_${side}__` };
+    };
+    const matches = [RELAY_MULTICAST_IDENTITY, populate("a"), populate("b")].every((probe) => {
+      let resolved;
+      try {
+        resolved = this.host.resolveShape(name, args, probe);
+      } catch {
+        return false;
+      }
+      return resolved !== void 0 && resolved.global !== true && resolved.table === base.table && stableStringify(resolved.effectiveWhere) === baseWhere && stableStringify(resolved.columns) === baseColumns;
+    });
+    return matches && !enumerated;
+  }
+  /**
+   * Whether `table` has ANY masked column defined (L7). Deliberately conservative:
+   * we disqualify a shape from relay-multicast if its table declares any mask at
+   * all, even when the current query doesn't project the masked column. A masked
+   * value is identity-dependent, and keying uniformity off the *projected* set
+   * meant a later column addition (or a `select` change) could silently widen a
+   * cohort to include an identity-dependent value. Refusing on any table-level
+   * mask removes that footgun; the cost is a few extra shapes falling back to the
+   * per-identity path, which is always correct.
+   */
+  tableHasAnyMask(table) {
+    return this.host.maskMetadata().columns.some((entry) => entry.table === table);
+  }
+}
+class RelayMember extends RelayLink {
+  /** `true` once this relay has announced itself to its owner this wake, so a hot socket churn doesn't re-attach on every subscribe. */
+  relayAnnounced = false;
+  /** Per-socket cohort memo `ws → subId → { cursor, epoch }`: the relay delivers a poke to a socket only while its memo matches the poke's `fromCursor`+`epoch`. */
+  shapeRelayMemos = /* @__PURE__ */ new WeakMap();
+  constructor(host, ownerKey, relayIndex) {
+    super(host, { ownerKey, relayIndex });
+  }
+  async forwardWhisper(topic, frame) {
+    if (!this.canAddressSiblings()) {
+      return;
+    }
+    await this.postRelayMessage(this.roleId.ownerKey, { frame, originRelay: this.roleId.relayIndex, topic, type: "relay_frame" });
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: a relay receives no writes, so it never flushes its own CDC
+  onFlush() {
+    return Promise.resolve();
+  }
+  /**
+   * Seed a shape held by a socket on this relay by forwarding the request to the
+   * owner: the owner resolves under this socket's verified identity and computes the
+   * seed frames, which the relay delivers verbatim. Returns a structured error
+   * (surfaced as a `shape_subscribe` error) when the owner can't be reached.
+   */
+  async seedRelayShape(ws, subId, shape, identity) {
+    if (!this.canAddressSiblings()) {
+      return { code: "RELAY_MISCONFIGURED", message: "relay cannot address its owner" };
+    }
+    await this.announce();
+    const request = {
+      args: shape.args ?? {},
+      connectionId: this.host.readAttachment(ws).connectionId,
+      identity: identity.identity,
+      name: shape.name,
+      relayIndex: this.roleId.relayIndex,
+      sinceEpoch: shape.sinceEpoch,
+      sinceSeq: shape.sinceSeq,
+      subId,
+      type: "relay_shape_subscribe",
+      userId: identity.userId
+    };
+    const response = await this.requestRelayMessage(this.roleId.ownerKey, request);
+    if (response === void 0) {
+      return { code: "RELAY_SEED_FAILED", message: "owner did not answer the shape seed" };
+    }
+    let seed;
+    try {
+      seed = await response.json();
+    } catch {
+      return { code: "RELAY_SEED_FAILED", message: "malformed shape seed from owner" };
+    }
+    if (seed.error !== void 0) {
+      return seed.error;
+    }
+    if (seed.frames === void 0) {
+      return { code: "RELAY_SEED_FAILED", message: "owner returned no shape frames" };
+    }
+    await awaitWsDrain(ws);
+    for (const frame of seed.frames) {
+      trySendFrame(ws, frame);
+    }
+    this.recordRelayShapeMemo(ws, subId, seed.cursor ?? 0, seed.epoch);
+    return "ok";
+  }
+  /** A relay announces itself to its owner (once per wake) on its first subscriber, retrying on a failed attach so a dropped frame can't strand its sockets (LOW-4). */
+  async announce() {
+    if (this.relayAnnounced || !this.canAddressSiblings()) {
+      return;
+    }
+    this.relayAnnounced = true;
+    const response = await this.requestRelayMessage(this.roleId.ownerKey, { relayIndex: this.roleId.relayIndex, type: "relay_attach" });
+    if (!response?.ok) {
+      this.relayAnnounced = false;
+    }
+  }
+  /** Once this relay loses its last socket (the `closing` one excluded), detach from the owner and re-arm the announce latch for a future subscriber. */
+  async announceDrain(closing) {
+    if (!this.canAddressSiblings()) {
+      return;
+    }
+    if (this.host.getWebSockets().some((ws) => ws !== closing)) {
+      return;
+    }
+    this.relayAnnounced = false;
+    await this.postRelayMessage(this.roleId.ownerKey, { relayIndex: this.roleId.relayIndex, type: "relay_detach" });
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: a relay never spreads connections (flat single tier)
+  relayCount() {
+    return 0;
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: the RLS-uniform gate is an owner concern
+  isShapeRelayUniform() {
+    return false;
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only an owner tracks a relay set
+  onAttach() {
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only an owner tracks a relay set
+  onDetach() {
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only an owner re-distributes a forwarded whisper
+  onWhisperFrame() {
+    return Promise.resolve();
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: a relay can't seed (no op-log) — the owner does
+  onShapeSubscribe() {
+    return { error: { code: "RELAY_CANNOT_SEED", message: "a relay has no op-log to seed from" } };
+  }
+  onShapePoke(poke) {
+    return this.deliverShapePoke(poke);
+  }
+  /** Record a relay socket's cohort cursor + epoch for `subId` (creating the per-socket map lazily). */
+  recordRelayShapeMemo(ws, subId, cursor, epoch) {
+    let memos = this.shapeRelayMemos.get(ws);
+    if (memos === void 0) {
+      memos = /* @__PURE__ */ new Map();
+      this.shapeRelayMemos.set(ws, memos);
+    }
+    memos.set(subId, { cursor, epoch });
+  }
+  /**
+   * Deliver an owner-multicast shape delta to this relay's cohort sockets. A socket
+   * receives it only while its memo matches the poke's `fromCursor` AND `epoch` (so a
+   * socket that seeded at a different cursor/epoch never double-applies), then
+   * advances to `checkpoint`. A targeted (per-socket proxy) poke goes ONLY to its one
+   * connection; a cohort multicast goes to every matching socket.
+   * @returns the number of sockets delivered to
+   */
+  deliverShapePoke(poke) {
+    const routingKey = shapeRoutingKey(poke.name, poke.args);
+    let delivered = 0;
+    for (const ws of this.host.getWebSockets()) {
+      const attachment = this.host.readAttachment(ws);
+      const { shapes } = attachment;
+      const memos = this.shapeRelayMemos.get(ws);
+      if (shapes === void 0 || memos === void 0) {
+        continue;
+      }
+      if (poke.targetConnectionId !== void 0 && attachment.connectionId !== poke.targetConnectionId) {
+        continue;
+      }
+      for (const [subId, sub] of Object.entries(shapes)) {
+        const memo = memos.get(subId);
+        if (memo?.cursor !== poke.fromCursor || memo.epoch !== poke.epoch || shapeRoutingKey(sub.name, sub.args) !== routingKey) {
+          continue;
+        }
+        const frames = buildPokeFrames(
+          [{ rowsPatch: poke.rowsPatch, shapeId: subId }],
+          {
+            baseCheckpoint: void 0,
+            checkpoint: poke.checkpoint,
+            epoch: poke.epoch,
+            lastMutationId: void 0,
+            pokeId: this.host.nextPokeId()
+          },
+          // `poke.rowsPatch` was wire-encoded by the owner before it crossed
+          // the hub — don't double-encode it here.
+          { preEncoded: true }
+        );
+        for (const frame of frames) {
+          trySendFrame(ws, frame);
+        }
+        memos.set(subId, { cursor: poke.checkpoint, epoch: poke.epoch });
+        delivered += 1;
+      }
+    }
+    return delivered;
+  }
+}
+const createRelayLink = (host) => {
+  const name = host.doName();
+  if (name === void 0) {
+    return void 0;
+  }
+  const parsed = parseRelayName(name);
+  return parsed === void 0 ? new OwnerRelay(host, name) : new RelayMember(host, parsed.ownerKey, parsed.relayIndex);
+};
+
 const REQUEST_LOG_TABLE = "__lunora_reqlog__";
 const REQUEST_LOG_RETENTION = 1e3;
 const REQUEST_LOG_EVENT_SOURCE = "lunora";
@@ -349,6 +1178,23 @@ const readRequestLog = (sql, options = {}) => {
   });
 };
 
+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,116 +1259,13 @@ 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;
 const IDEMPOTENCY_GC_INTERVAL_MS = 36e5;
 const ROOT_SHARD_NAME = "__root__";
 const ADMIN_WILDCARD = "*";
-const awaitWsDrain = async (ws) => {
-  let attempts = 0;
-  while (attempts < 100) {
-    attempts += 1;
-    const buffered = ws.bufferedAmount;
-    if (typeof buffered !== "number" || buffered < 1048576) {
-      return;
-    }
-    await new Promise((resolve) => {
-      setTimeout(resolve, 20);
-    });
-  }
-};
 const cdcSuffix = (cursor, epoch) => (cursor === void 0 ? "" : `,"cursor":${String(cursor)}`) + (epoch === void 0 ? "" : `,"epoch":${JSON.stringify(epoch)}`);
 const setsIntersect = (a, b) => {
   const [small, large] = a.size <= b.size ? [a, b] : [b, a];
@@ -918,6 +1661,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 +1752,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 +1875,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 +1938,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 +1958,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();
   /**
@@ -1158,6 +2008,35 @@ class ShardDO {
    * (durable aggregation would be a separate, heavier feature).
    */
   metrics = { errors: 0, requests: 0, sinceMs: Date.now() };
+  /**
+   * Running fan-out cost counters surfaced by the
+   * `__lunora_admin__:getFanoutMetrics` RPC — one tally for the reactive
+   * shape-poke path (`pokeShapeSubscribers`) and one for the whisper broadcast
+   * path (`broadcastWhisper`). Each pass records the sockets it iterated (the
+   * O(subscribers) cost) and delivered to. In-memory and reset on
+   * hibernation/restart, sharing `metrics.sinceMs` as the "since this instance
+   * woke" epoch. This is the observability half of plan 075's auto-elastic
+   * relay tier (Phase 1): measure the per-flush fan-out cost so the promotion
+   * threshold is grounded in real numbers, with no behavior change.
+   */
+  fanout = { shapePoke: createFanoutCounters(), whisper: createFanoutCounters() };
+  /**
+   * The runtime's Durable Object namespace binding name (e.g. `"SHARD"`),
+   * forwarded as `x-lunora-shard-binding` on every request so a DO can address
+   * its siblings (`this.env[binding].getByName(...)`) for the relay hub. Absent
+   * in single-DO mode / the unit harness — when absent, the relay tier is inert
+   * and whispers stay shard-local (no behavior change). In-memory; re-learned per
+   * request.
+   */
+  shardBinding;
+  /**
+   * The auto-elastic fan-out relay collaborator (plan 075) — an {@link OwnerRelay}
+   * or {@link RelayMember} chosen ONCE from this DO's name, or `undefined` for an
+   * unnamed (single-DO) DO where the relay tier is inert. All relay state +
+   * transport lives on it, reached back through the {@link RelayHost} adapter, so
+   * owner-only state can never sit next to relay-only state on this class.
+   */
+  relay;
   /**
    * Declared indexes (`table:index`) a query has exercised since this instance
    * woke, stamped by `getCtxDbIndexUseHook`. In-memory and reset on
@@ -1244,6 +2123,29 @@ class ShardDO {
     if (options.reactiveCache) {
       this.reactiveCache = new ReactiveCache(options.reactiveCache);
     }
+    const host = {
+      buildShapeDiff: (resolved, fromCursor, toCursor) => this.buildShapeDiff(this.sql, resolved, fromCursor, toCursor),
+      computeOpLogShapeSeed: (shape, resolved) => this.computeOpLogShapeSeed(shape, resolved),
+      currentCdcEpoch: () => this.currentCdcEpoch(),
+      deliverWhisperLocal: (topic, frame, exclude) => this.deliverWhisperLocal(topic, frame, exclude),
+      doName: () => this.state.id?.name,
+      env: () => this.env,
+      getWebSockets: () => this.state.getWebSockets(),
+      maskMetadata: () => this.maskMetadata(),
+      nextPokeId: () => {
+        this.pokeSequence += 1;
+        return `poke-${String(this.pokeSequence)}`;
+      },
+      readAttachment: (ws) => this.readAttachment(ws),
+      recordShapePokeFanout: (iterated, delivered, elapsedMs) => {
+        this.fanout.shapePoke = recordFanoutPass(this.fanout.shapePoke, iterated, delivered, elapsedMs);
+      },
+      resolveShape: (name, args, identity) => this.resolveShape(name, args, identity),
+      rlsMetadata: () => this.rlsMetadata(),
+      shardBinding: () => this.shardBinding,
+      sql: () => this.sql
+    };
+    this.relay = createRelayLink(host);
     this.armWebSocketKeepalive();
   }
   /** SQLite handle scoped to this Durable Object. */
@@ -1253,8 +2155,10 @@ class ShardDO {
    */
   async fetch(request) {
     const url = new URL(request.url);
-    if (request.headers.get("Upgrade") === "websocket") {
-      return this.handleWebSocketUpgrade(request);
+    this.shardBinding = request.headers.get("x-lunora-shard-binding") ?? this.shardBinding;
+    const early = await this.routeNonRpc(url, request);
+    if (early !== void 0) {
+      return early;
     }
     if (url.pathname !== "/rpc" || request.method !== "POST") {
       return new Response("Not found", { status: 404 });
@@ -1272,6 +2176,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 +2195,28 @@ 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, decodeWire(payload.args ?? {}));
+      this.recordPostDispatchBookkeeping(result, mutatorClass);
+      if (mutatorClass?.kind === "next") {
+        this.advanceClientMutationWatermark();
       }
-      const result = await this.handleRpc(payload.functionPath, payload.args ?? {});
-      this.persistIdempotentResult(result);
       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, encodeWire(result));
       await this.flushChangedTables();
       return response;
     } catch (error) {
@@ -1326,6 +2242,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 +2283,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,24 +2317,42 @@ 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" }));
         return;
       }
-      this.handleStream(ws, envelope.id, envelope.query.functionPath, envelope.query.args ?? {}).catch(() => {
+      this.handleStream(ws, envelope.id, envelope.query.functionPath, decodeWire(envelope.query.args ?? {})).catch(() => {
       });
       return;
     }
     if (envelope.type === "whisper_subscribe" || envelope.type === "whisper_unsubscribe") {
       if (typeof envelope.topic === "string" && envelope.topic.length > 0) {
-        this.setWhisperMembership(ws, envelope.topic, envelope.type === "whisper_subscribe");
+        const join = envelope.type === "whisper_subscribe";
+        this.setWhisperMembership(ws, envelope.topic, join);
+        if (join) {
+          await this.relay?.announce();
+        }
       }
       return;
     }
     if (envelope.type === "whisper") {
       if (typeof envelope.topic === "string" && envelope.topic.length > 0) {
-        this.broadcastWhisper(ws, envelope.topic, envelope.data);
+        await this.broadcastWhisper(ws, envelope.topic, envelope.data);
       }
       return;
     }
@@ -1444,12 +2385,49 @@ 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);
+    await this.relay?.announceDrain(ws);
   }
   /** 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;
+    }
+    try {
+      remaining += await this.pollExternalSources();
+    } catch (error) {
+      this.recordShapeError("source:poll", error);
+      remaining += 1;
+    }
+    await this.flushChangedTables();
+    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 +2626,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 +2831,58 @@ 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 {
+      analytics: false,
+      auth: false,
+      containers: false,
+      flags: false,
+      kv: 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 +3147,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) {
@@ -2138,7 +3163,7 @@ class ShardDO {
     }
     const now = Date.now();
     try {
-      writeIdempotent(this.sql, this.currentRequestUserId ?? "", this.currentRequestMutationId, JSON.stringify(result) ?? "null", now);
+      writeIdempotent(this.sql, this.currentRequestUserId ?? "", this.currentRequestMutationId, JSON.stringify(encodeWire(result)), now);
       if (now - this.lastIdempotencyTrimAt > IDEMPOTENCY_GC_INTERVAL_MS) {
         trimIdempotent(this.sql, now - IDEMPOTENCY_RETENTION_MS);
         this.lastIdempotencyTrimAt = now;
@@ -2146,6 +3171,191 @@ 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);
+    }
+    const commitCursor = this.mutationCommitCursor();
+    return jsonResponse(commitCursor === void 0 ? { result: cachedValue } : { commitCursor, result: cachedValue }, 200, this.currentResponseBookmark);
+  }
+  /**
+   * The CDC cursor a just-committed plain mutation landed at — the post-write
+   * high-watermark, on the same scale as the `cursor` on `data`/`delta` frames.
+   * The client drops a pending per-call optimistic overlay once it sees a frame
+   * with `cursor >= commitCursor` (gapless reconciliation that keeps mutations
+   * concurrent, without the serialized custom-mutator watermark). Scoped to a
+   * mutation (carries an `x-lunora-mutation-id`) on a CDC-enabled shard;
+   * `undefined` otherwise, leaving the wire byte-identical for queries/actions
+   * and CDC-off shards.
+   */
+  mutationCommitCursor() {
+    return this.currentRequestMutationId === void 0 ? void 0 : this.currentCdcCursor();
+  }
+  /**
+   * 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; a plain mutation echoes
+   * `commitCursor` (see {@link mutationCommitCursor}); other calls return the
+   * bare `{ result }` envelope unchanged.
+   */
+  buildDispatchResponse(mutatorClass, result) {
+    if (mutatorClass?.kind === "next") {
+      return jsonResponse({ lastMutationId: this.currentRequestClientSeq, result }, 200, this.currentResponseBookmark);
+    }
+    const commitCursor = this.mutationCommitCursor();
+    return jsonResponse(commitCursor === void 0 ? { result } : { commitCursor, 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 +3405,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 +3503,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 +3526,91 @@ 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;
+  }
+  /**
+   * The RLS-uniform gate (plan 075 Phase 3): whether a reactive shape may be
+   * relay-multicast — i.e. one delta is correct for **every** subscriber. The owner
+   * decides it (see {@link OwnerRelay.isShapeRelayUniform} — a static RLS read-policy
+   * guard plus claim-exhaustive `Proxy` probes, fail-closed); this thin delegation
+   * is the seam the gate test exercises. A non-owner DO is never relay-uniform.
+   */
+  isShapeRelayUniform(name, args) {
+    return this.relay?.isShapeRelayUniform(name, args) ?? false;
+  }
+  /**
+   * 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([]);
+  }
+  /**
+   * Poll external-source (`.source(...)`) tables once (plan 077): materialize
+   * each sourced table's freshly-pulled tenant slice into this DO's SQLite. The
+   * base `ShardDO` has no sourced tables, so it returns `0` and the ingest tier
+   * stays dormant — zero behavior change for every existing DO. The codegen
+   * subclass overrides it to, per sourced table, build a `createShardCtxDb`
+   * writer, read the tenant slice from Hyperdrive under this DO's shard key, and
+   * run `runExternalSourceTick` (read local baseline → diff → apply via the
+   * validated CDC writer). Returns the number of sourced tables still being
+   * polled, so the shared poll alarm ({@link ShardDO.alarm}) re-arms while ingest
+   * is active.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass implements the real Hyperdrive-backed poll
+  pollExternalSources() {
+    return Promise.resolve(0);
+  }
+  /**
+   * Arm the shared poll alarm for external-source ingest (plan 077). The alarm is
+   * shared with the global-shape poll tier; the codegen subclass calls this once
+   * (on construction / first sourced write) so a sourced DO starts its ingest
+   * loop, after which {@link ShardDO.alarm} re-arms itself while
+   * {@link ShardDO.pollExternalSources} reports remaining work. Idempotent; a
+   * no-op when the runtime exposes no `setAlarm` (unit harness).
+   */
+  scheduleSourcePoll() {
+    return this.scheduleGlobalPoll();
+  }
+  /** This DO's shard key (its DO name), or `__root__` for the single-DO default. The `tenantBy` mapper binds it into the source query. */
+  currentShardKey() {
+    return this.state.id?.name ?? ROOT_SHARD_NAME;
+  }
+  /** Record a contained external-source ingest failure (one sourced table's poll) into the log ring without aborting the others. */
+  recordExternalSourceError(table, error) {
+    this.recordShapeError(`source:${table}`, error);
+  }
   /**
    * 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 +4013,79 @@ 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 body = {
+        code: lunoraError.code ?? "INTERNAL",
+        message: lunoraError.message ?? "internal error"
+      };
+      if (lunoraError.data !== void 0) {
+        body.data = encodeWire(lunoraError.data);
+      }
+      return jsonResponse({ error: body }, status);
+    }
+    console.error("[@lunora/do] unhandled RPC error:", error);
+    return jsonResponse({ error: { code: "RPC_FAILED", message: "internal error" } }, 500);
+  }
+  /**
+   * Batch dispatch (plan 088). Applies each `calls[]` entry through the SAME
+   * single-call `/rpc` path (via a nested `this.fetch`), **sequentially**, so
+   * the per-`(identity, mutationId)` idempotency dedup and the per-client
+   * `__client_watermark` ordering are enforced entry-by-entry exactly as for an
+   * individual call — no duplication of the dispatch core, no reordering.
+   *
+   * Failures are **per-slot, not fail-fast**: an entry that throws (or a
+   * custom-mutator `OUT_OF_ORDER` gap) is captured in its own result slot and
+   * later entries still run. Ordering is still safe — a later same-client
+   * mutator after a gap re-classifies as a gap too (the watermark never
+   * advanced), so it cannot apply out of order; unrelated entries/queries are
+   * independent. The response is `{ results: [{ id, status, body }] }` in
+   * request order; each `body` is the untouched single-call envelope (its
+   * `result` already wire-encoded), so the client demuxes + decodes each
+   * exactly as one call.
+   */
+  async handleBatchRpc(request) {
+    let payload;
+    try {
+      payload = await request.json();
+    } catch {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: "invalid JSON body" } }, 400);
+    }
+    if (!Array.isArray(payload.calls)) {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: "batch `calls` must be an array" } }, 400);
+    }
+    if (payload.calls.length > MAX_BATCH_ENTRIES) {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: `batch exceeds the ${String(MAX_BATCH_ENTRIES)}-call limit` } }, 400);
+    }
+    const results = [];
+    let latestBookmark;
+    for (const raw of payload.calls) {
+      const outcome = await this.dispatchBatchEntry(request, raw);
+      if (outcome.bookmark !== void 0) {
+        latestBookmark = outcome.bookmark;
+      }
+      results.push({ body: outcome.body, id: outcome.id, status: outcome.status });
+    }
+    return jsonResponse({ results }, 200, latestBookmark);
+  }
+  /** Dispatch one batch entry through the single-call `/rpc` path and capture its envelope (plan 088). */
+  async dispatchBatchEntry(batchRequest, entry) {
+    try {
+      const response = await this.fetch(buildBatchEntryRequest(batchRequest, entry));
+      return { body: await response.json(), bookmark: response.headers.get("x-d1-bookmark") ?? void 0, id: entry.id, status: response.status };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        body: { error: { code: "BATCH_ENTRY_FAILED", message } },
+        bookmark: void 0,
+        id: entry?.id,
+        status: 500
+      };
     }
-    const message = error instanceof Error ? error.message : "unknown error";
-    return jsonResponse({ error: { code: "RPC_FAILED", message } }, 500);
   }
   /**
    * Serve a reserved admin-introspection RPC (`__lunora_admin__:*`) for the
@@ -2802,6 +4207,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 +4330,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
@@ -3274,6 +4697,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.listSubscriptions) {
       return this.collectSubscriptions();
     }
+    if (functionPath === ADMIN_FUNCTIONS.getFanoutMetrics) {
+      return this.collectFanoutMetrics();
+    }
     if (functionPath === ADMIN_FUNCTIONS.getLogs) {
       return { entries: this.logs.entries() };
     }
@@ -3301,6 +4727,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.listWorkflows) {
       return this.workflowsMetadata();
     }
+    if (functionPath === ADMIN_FUNCTIONS.listQueues) {
+      return this.queuesMetadata();
+    }
     return void 0;
   }
   /**
@@ -3313,6 +4742,32 @@ class ShardDO {
   collectSubscriptions() {
     return summarizeSubscriptions(this.state.getWebSockets().map((ws) => this.readAttachment(ws)));
   }
+  /**
+   * Assemble the `__lunora_admin__:getFanoutMetrics` payload for the Studio
+   * fan-out observability panel (plan 075 Phase 1). The point-in-time topic
+   * subscriber counts are folded live from each socket's attachment via
+   * {@link summarizeFanoutTopics}; the running per-path cost counters are the
+   * in-memory {@link ShardDO.fanout} tallies, sharing `metrics.sinceMs` as the
+   * "since this instance woke" epoch. Touches no SQLite and mutates no socket
+   * state; it does call `relay.relayCount()`, which advances the promotion
+   * latch — safe here because that transition is a pure, monotonic function of
+   * the live socket count (DOs are single-threaded), so a metrics poll only ever
+   * drives the latch to the same state the routing path would compute for the
+   * same count, never a divergent one.
+   */
+  collectFanoutMetrics() {
+    const summary = summarizeFanoutTopics(this.state.getWebSockets().map((ws) => this.readAttachment(ws)));
+    const relayCount = this.relay?.relayCount() ?? 0;
+    return {
+      ...summary,
+      maxRelays: this.relay?.maxRelays() ?? DEFAULT_MAX_RELAYS,
+      promoted: relayCount > 0,
+      relayCount,
+      shapePoke: this.fanout.shapePoke,
+      sinceMs: this.metrics.sinceMs,
+      whisper: this.fanout.whisper
+    };
+  }
   /** Resolve a `getAuditLog` admin read, parsing the optional `limit`/`sinceSeq` cursor args and ensuring the reserved table first. */
   // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers and future per-instance state
   readAdminAuditLog(sql, args) {
@@ -3416,6 +4871,7 @@ class ShardDO {
       orderBy: parseTablePageOrderBy(args["orderBy"]),
       refs: this.tableRefs(table),
       search: typeof args["search"] === "string" ? args["search"] : void 0,
+      skipCount: typeof args["skipCount"] === "boolean" ? args["skipCount"] : void 0,
       table
     });
     return { result: page, tables: /* @__PURE__ */ new Set([table === "" ? ADMIN_WILDCARD : table]) };
@@ -3460,6 +4916,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 +5007,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) {
@@ -3517,17 +5041,22 @@ class ShardDO {
           break;
         }
         await awaitWsDrain(ws);
-        ws.send(JSON.stringify({ data: chunk, id, type: "chunk" }));
+        ws.send(JSON.stringify({ data: encodeWire(chunk), id, type: "chunk" }));
       }
       if (!controller.signal.aborted) {
         ws.send(JSON.stringify({ id, type: "complete" }));
       }
     } 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 +5087,53 @@ 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.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;
     }
-    await this.refreshSubscriptions(changed);
+    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),
+          this.relay?.onFlush(batch, frameCursor ?? 0)
+        ]);
+        batch = this.pendingRefreshTables;
+      }
+    } finally {
+      this.refreshInFlight = false;
+    }
   }
   /**
    * For every live subscription whose query reads one of `changed`, re-run
@@ -3623,6 +5194,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 +5212,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 +5229,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 +5249,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 +5269,559 @@ 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 };
+    const relayed = await this.relay?.seedRelayShape(ws, subId, shape, identity);
+    if (relayed !== void 0) {
+      return relayed;
+    }
+    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 { baseCheckpoint, cursor, epoch, rowsPatch } = this.computeOpLogShapeSeed(shape, resolved);
+    await awaitWsDrain(ws);
+    if (this.sendPoke(ws, [{ rowsPatch, shapeId: subId }], cursor, epoch, baseCheckpoint)) {
+      this.recordShapeMemo(ws, subId, cursor);
+    }
+    return "ok";
+  }
+  /**
+   * Compute an op-log shape seed (cursor, epoch, the resume base, and the
+   * membership `rowsPatch`) WITHOUT sending — the shared core of
+   * {@link ShardDO.seedOpLogShape} (sends to a local socket) and the owner relay's
+   * `buildShapeSeedFrames` (serializes the frames for a relay to deliver, plan 075
+   * Phase 3, via the {@link RelayHost} seam). Resume only when CDC is on, the client is on this
+   * epoch, its checkpoint doesn't run ahead of ours, and the log still covers it;
+   * else a full re-seed. A fully-compacted log only proves "nothing missed" when
+   * the client is already at `cursor`.
+   * @returns the cursor/epoch, the resume base (`baseCheckpoint`), and the membership patch
+   */
+  computeOpLogShapeSeed(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);
+    return { baseCheckpoint: canResume ? shape.sinceSeq : void 0, cursor, epoch, rowsPatch };
+  }
+  /**
+   * 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();
+    let delivered = 0;
+    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)) {
+            delivered += 1;
+            for (const subId of partAdvanced) {
+              this.recordShapeMemo(ws, subId, checkpoint);
+            }
+          }
+        }
+      } catch {
+      }
+    };
+    const startMs = Date.now();
+    await runSocketPool(sockets, pokeOne);
+    this.fanout.shapePoke = recordFanoutPass(this.fanout.shapePoke, sockets.length, delivered, Date.now() - startMs);
+  }
+  /**
+   * 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
@@ -3719,7 +5834,7 @@ class ShardDO {
       memos = /* @__PURE__ */ new Map();
       this.subMemos.set(ws, memos);
     }
-    memos.set(subId, { lastJson: JSON.stringify(outcome.result ?? null), tables: outcome.tables });
+    memos.set(subId, { lastJson: JSON.stringify(encodeWire(outcome.result ?? null)), tables: outcome.tables });
   }
   /**
    * Memoise `outcome` for `(ws, subId)` and push it to the socket, unless an
@@ -3746,29 +5861,19 @@ class ShardDO {
       this.subMemos.set(ws, memos);
     }
     const cursorSuffix = cdcSuffix(cursor, epoch);
-    const json = JSON.stringify(outcome.result ?? null);
+    const json = JSON.stringify(encodeWire(outcome.result ?? null));
     const existing = memos.get(subId);
     if (existing?.lastJson === json) {
       existing.tables = outcome.tables;
+      const settledWatermark = this.socketClientWatermark(ws);
+      const watermarkField = settledWatermark === void 0 ? "" : `,"lastMutationId":${String(settledWatermark)}`;
+      trySendFrame(ws, `{"type":"settled","id":${JSON.stringify(subId)}${watermarkField}${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:
@@ -3858,6 +5963,29 @@ class ShardDO {
     }
     setter.call(this.state, new WebSocketRequestResponsePair(WS_KEEPALIVE_PING, WS_KEEPALIVE_PONG));
   }
+  /**
+   * Route the non-RPC requests `fetch` handles before the shard-local RPC
+   * endpoint: a WebSocket upgrade, and the internal `/_lunora/relay` owner↔relay
+   * control channel (never reachable by a client — the runtime forwards only
+   * worker-internal traffic there). Returns `undefined` for an RPC request, which
+   * `fetch` then dispatches.
+   * @returns the routed response, or `undefined` when this is an RPC request
+   */
+  async routeNonRpc(url, request) {
+    if (url.pathname === "/_lunora/relay" && request.method === "POST") {
+      return this.relay ? await this.relay.handleControl(request) : new Response("relay tier inactive", { status: 404 });
+    }
+    if (url.pathname === "/_lunora/route" && request.method === "GET") {
+      return jsonResponse({ relayCount: this.relay?.relayCount() ?? 0 });
+    }
+    if (url.pathname === "/rpc-batch" && request.method === "POST") {
+      return this.handleBatchRpc(request);
+    }
+    if (request.headers.get("Upgrade") === "websocket") {
+      return this.handleWebSocketUpgrade(request);
+    }
+    return void 0;
+  }
   handleWebSocketUpgrade(request) {
     if (!this.isUpgradeAllowed(request)) {
       return new Response("Forbidden", { status: 403 });
@@ -3975,7 +6103,7 @@ class ShardDO {
    * topic name. That matches the AnyCable model (and `from` is unforgeable),
    * but per-topic auth does not exist here; see `whisperSubscribe` on the client.
    */
-  broadcastWhisper(sender, topic, data) {
+  async broadcastWhisper(sender, topic, data) {
     if (!this.allowWhisper(sender)) {
       return;
     }
@@ -3986,15 +6114,29 @@ class ShardDO {
     const from = this.readAttachment(sender).userId;
     const fromSuffix = from === void 0 ? "" : `,"from":${JSON.stringify(from)}`;
     const frame = `{"type":"whisper","topic":${JSON.stringify(topic)},"data":${dataJson}${fromSuffix}}`;
+    this.deliverWhisperLocal(topic, frame, sender);
+    await this.relay?.forwardWhisper(topic, frame);
+  }
+  /**
+   * Deliver an already-serialized whisper `frame` to every local socket joined to
+   * `topic`, excluding `exclude` (the sender, or `undefined` for a frame the relay
+   * hub forwarded in — its sender lives on another DO). Records the fan-out pass
+   * for `getFanoutMetrics` (plan 075 Phase 1). Pure delivery — no SQLite, no CDC.
+   * @returns the number of sockets the frame was sent to
+   */
+  deliverWhisperLocal(topic, frame, exclude) {
+    let scanned = 0;
+    let delivered = 0;
     for (const ws of this.state.getWebSockets()) {
-      if (ws === sender || this.readAttachment(ws).whispers?.includes(topic) !== true) {
+      scanned += 1;
+      if (ws === exclude || this.readAttachment(ws).whispers?.includes(topic) !== true) {
         continue;
       }
-      try {
-        ws.send(frame);
-      } catch {
-      }
+      trySendFrame(ws, frame);
+      delivered += 1;
     }
+    this.fanout.whisper = recordFanoutPass(this.fanout.whisper, scanned, delivered, 0);
+    return delivered;
   }
   // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method grouped with the hibernation/attachment helpers; reads only the socket
   readAttachment(ws) {