@lunora/do 1.0.0-alpha.3 → 1.0.0-alpha.31

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

@@ -1,29 +1,103 @@
+import { LunoraError, toErrorBody } from '@lunora/errors';
 import { drizzle } from 'drizzle-orm/durable-sqlite';
-import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-DZEhUeyI.mjs';
-import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKET_MS-CiHHYeJi.mjs';
-import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-PTtTiQ7U.mjs';
+import { c as constantTimeEqual } from './constant-time-equal-BVRWZgES.mjs';
+import { j as jsonResponse } from './json-response-BdbtpOhm.mjs';
+import { e as encodeWire, d as decodeWire } from './wire-codec-CzQc1pvf.mjs';
+import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-Dy3oFZ26.mjs';
+import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
+import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-CYwBpyTr.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-CAHLZMj8.mjs';
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
-import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './clearCapturedMail-CPpgl-dX.mjs';
-import { readBookmark, armRestore } from './armRestore-BJk53Ro8.mjs';
-import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-ByVzgH3d.mjs';
+import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
+import { readBookmark, armRestore } from './armRestore-4Px61hHS.mjs';
+import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-DnSvbjil.mjs';
+import { stableWireKey } from './stableWireKey-DKuXO7T5.mjs';
+import { awaitWsDrain, trySendFrame, subscriptionListDeltas, sendDeltaFrames } from './subscriptionListDeltas-CT76bYny.mjs';
+import { fingerprintError } from '@lunora/fingerprint';
 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 { 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 { runReadonlySql } from './MAX_SQL_ROWS-iFAA8FbD.mjs';
+import { ConflictError } from './ConflictError-CLoq37xH.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-DjJEHiM2.mjs';
+import { stableStringify } from './stableStringify-mC40mZts.mjs';
+import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
+
+const MAX_BATCH_ENTRIES = 500;
+
+const evictOldestEntry = (map, capacity) => {
+  if (map.size < capacity) {
+    return;
+  }
+  const oldest = map.keys().next().value;
+  if (oldest !== void 0) {
+    map.delete(oldest);
+  }
+};
+
+const textEncoder = new TextEncoder();
+const fromBase64Url = (input) => {
+  const padded = input.replaceAll("-", "+").replaceAll("_", "/") + "===".slice((input.length + 3) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return bytes;
+};
+const KEY_CACHE_MAX = 64;
+const keyCache = /* @__PURE__ */ new Map();
+const importHmacKey = async (secret) => {
+  const cached = keyCache.get(secret);
+  if (cached) {
+    return cached;
+  }
+  evictOldestEntry(keyCache, KEY_CACHE_MAX);
+  const keyPromise = crypto.subtle.importKey("raw", textEncoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign", "verify"]);
+  keyCache.set(secret, keyPromise);
+  return keyPromise;
+};
+const verifyCanonical = async (secret, canonical, sigBytes) => {
+  const cryptoKey = await importHmacKey(secret);
+  return crypto.subtle.verify("HMAC", cryptoKey, sigBytes, textEncoder.encode(canonical));
+};
+
+const WS_ADMIN_TOKEN_VERSION = "v1";
+const verifyWsAdminToken = async (secret, token, now = Date.now()) => {
+  if (secret.length === 0 || token.length === 0) {
+    return false;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return false;
+  }
+  const [version, expString, signature] = parts;
+  if (version !== WS_ADMIN_TOKEN_VERSION || signature.length === 0) {
+    return false;
+  }
+  const expiresAtMs = Number(expString);
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now) {
+    return false;
+  }
+  let signatureBytes;
+  try {
+    signatureBytes = fromBase64Url(signature);
+  } catch {
+    return false;
+  }
+  return verifyCanonical(secret, `${version}.${expString}`, signatureBytes);
+};
 
 const AUDIT_LOG_TABLE = "__lunora_audit__";
 const AUDIT_LOG_RETENTION = 1e3;
-const runSql$2 = (sql, query, ...params) => {
+const runSql$3 = (sql, query, ...params) => {
   const runner = sql.exec;
   return runner.call(sql, query, ...params);
 };
 const ensureAuditTable = (sql) => {
-  runSql$2(
+  runSql$3(
     sql,
     `CREATE TABLE IF NOT EXISTS "${AUDIT_LOG_TABLE}" (
             seq INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -37,7 +111,7 @@ const ensureAuditTable = (sql) => {
 };
 const appendAuditEntry = (sql, entry) => {
   ensureAuditTable(sql);
-  runSql$2(
+  runSql$3(
     sql,
     `INSERT INTO "${AUDIT_LOG_TABLE}" (ts, op, "table", id, detail) VALUES (?, ?, ?, ?, ?)`,
     entry.ts,
@@ -49,13 +123,13 @@ const appendAuditEntry = (sql, entry) => {
     // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for an op with no associated table/id/detail.
     entry.detail === void 0 ? null : JSON.stringify(entry.detail)
   );
-  runSql$2(sql, `DELETE FROM "${AUDIT_LOG_TABLE}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${AUDIT_LOG_TABLE}")`, AUDIT_LOG_RETENTION);
+  runSql$3(sql, `DELETE FROM "${AUDIT_LOG_TABLE}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${AUDIT_LOG_TABLE}")`, AUDIT_LOG_RETENTION);
 };
 const readAuditLog = (sql, options = {}) => {
   ensureAuditTable(sql);
   const sinceSeq = options.sinceSeq ?? 0;
   const limit = Math.max(1, Math.min(options.limit ?? AUDIT_LOG_RETENTION, 1e4));
-  const rows = runSql$2(
+  const rows = runSql$3(
     sql,
     `SELECT seq, ts, op, "table", id, detail FROM "${AUDIT_LOG_TABLE}" WHERE seq > ? ORDER BY seq DESC LIMIT ?`,
     sinceSeq,
@@ -76,10 +150,42 @@ 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;
-const runSql$1 = (sql, query, ...params) => {
+const runSql$2 = (sql, query, ...params) => {
   const runner = sql.exec;
   return runner.call(sql, query, ...params);
 };
@@ -91,7 +197,7 @@ const normalizeSql = (sql) => {
   return normalized;
 };
 const ensureQueryMetricsTable = (sql) => {
-  runSql$1(
+  runSql$2(
     sql,
     `CREATE TABLE IF NOT EXISTS "${QUERY_METRICS_TABLE}" (
             normalized_sql TEXT PRIMARY KEY,
@@ -108,10 +214,10 @@ const recordQueryMetric = (sql, rawSql, durationMs, rowsRead, rowsWritten) => {
     return;
   }
   ensureQueryMetricsTable(sql);
-  const countRow = runSql$1(sql, `SELECT COUNT(*) AS n FROM "${QUERY_METRICS_TABLE}"`).one();
+  const countRow = runSql$2(sql, `SELECT COUNT(*) AS n FROM "${QUERY_METRICS_TABLE}"`).one();
   const count = countRow.n;
   if (count >= QUERY_METRICS_MAX_STATEMENTS) {
-    const existing = runSql$1(sql, `SELECT COUNT(*) AS c FROM "${QUERY_METRICS_TABLE}" WHERE normalized_sql = ?`, normalized).one();
+    const existing = runSql$2(sql, `SELECT COUNT(*) AS c FROM "${QUERY_METRICS_TABLE}" WHERE normalized_sql = ?`, normalized).one();
     if (existing.c === 0) {
       return;
     }
@@ -123,11 +229,11 @@ const recordQueryMetric = (sql, rawSql, durationMs, rowsRead, rowsWritten) => {
              total_duration_ms = total_duration_ms + excluded.total_duration_ms,
              rows_read = rows_read + excluded.rows_read,
              rows_written = rows_written + excluded.rows_written`;
-  runSql$1(sql, upsertSql, normalized, durationMs, rowsRead, rowsWritten);
+  runSql$2(sql, upsertSql, normalized, durationMs, rowsRead, rowsWritten);
 };
 const readQueryMetrics = (sql) => {
   ensureQueryMetricsTable(sql);
-  const rows = runSql$1(
+  const rows = runSql$2(
     sql,
     `SELECT normalized_sql, exec_count, total_duration_ms, rows_read, rows_written FROM "${QUERY_METRICS_TABLE}" ORDER BY total_duration_ms DESC`
   ).toArray();
@@ -142,6 +248,916 @@ const readQueryMetrics = (sql) => {
   });
 };
 
+const QUEUE_TABLE = "__lunora_queue_messages";
+const QUEUE_RETENTION = 500;
+const MAX_BODY_CHARS = 128 * 1024;
+const runSql$1 = (sql, query, ...params) => {
+  const runner = sql.exec;
+  return runner.call(sql, query, ...params);
+};
+const orNull = (value) => (
+  // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for an absent column.
+  value ?? null
+);
+const TRUNCATION_SUFFIX = "… [truncated by the dev queue catcher]";
+const UNSERIALIZABLE_MARKER = "[unserializable message body]";
+const encodeBody = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  try {
+    const encoded = JSON.stringify(value);
+    if (encoded.length > MAX_BODY_CHARS) {
+      return JSON.stringify(`${encoded.slice(0, MAX_BODY_CHARS)}${TRUNCATION_SUFFIX}`);
+    }
+    return encoded;
+  } catch {
+    return JSON.stringify(UNSERIALIZABLE_MARKER);
+  }
+};
+const isLossyBody = (body) => typeof body === "string" && (body === UNSERIALIZABLE_MARKER || body.endsWith(TRUNCATION_SUFFIX));
+const decodeBody = (value) => {
+  if (value === null || value === void 0 || value === "") {
+    return void 0;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+};
+const ensureQueueTable = (sql) => {
+  runSql$1(
+    sql,
+    `CREATE TABLE IF NOT EXISTS "${QUEUE_TABLE}" (
+            id TEXT PRIMARY KEY,
+            captured_at INTEGER NOT NULL,
+            message_id TEXT NOT NULL,
+            queue TEXT NOT NULL,
+            export_name TEXT,
+            body TEXT NOT NULL,
+            attempts INTEGER NOT NULL,
+            outcome TEXT NOT NULL,
+            error TEXT,
+            dead_lettered INTEGER NOT NULL,
+            message_ts INTEGER NOT NULL
+        )`
+  );
+};
+const recordQueueMessages = (sql, inputs, capturedAt) => {
+  ensureQueueTable(sql);
+  for (const input of inputs) {
+    runSql$1(
+      sql,
+      `INSERT INTO "${QUEUE_TABLE}" (id, captured_at, message_id, queue, export_name, body, attempts, outcome, error, dead_lettered, message_ts)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      crypto.randomUUID(),
+      capturedAt,
+      input.messageId,
+      input.queue,
+      orNull(input.exportName),
+      encodeBody(input.body),
+      input.attempts,
+      input.outcome,
+      orNull(input.error),
+      input.deadLettered === true ? 1 : 0,
+      input.timestamp
+    );
+  }
+  runSql$1(
+    sql,
+    `DELETE FROM "${QUEUE_TABLE}"
+         WHERE id NOT IN (
+            SELECT id FROM "${QUEUE_TABLE}" ORDER BY captured_at DESC, id DESC LIMIT ?
+         )`,
+    QUEUE_RETENTION
+  );
+  return { recorded: inputs.length };
+};
+const rowToEntry = (row) => {
+  return {
+    attempts: row.attempts,
+    body: decodeBody(row.body),
+    capturedAt: row.captured_at,
+    deadLettered: row.dead_lettered === 1,
+    error: row.error ?? void 0,
+    exportName: row.export_name ?? void 0,
+    id: row.id,
+    messageId: row.message_id,
+    outcome: row.outcome,
+    queue: row.queue,
+    timestamp: row.message_ts
+  };
+};
+const readQueueMessages = (sql, options = {}) => {
+  ensureQueueTable(sql);
+  const limit = Math.min(Math.max(options.limit ?? 100, 1), QUEUE_RETENTION);
+  const filterQueue = typeof options.queue === "string" && options.queue.length > 0 ? options.queue : void 0;
+  const where = filterQueue === void 0 ? "" : `WHERE queue = ?`;
+  const params = filterQueue === void 0 ? [limit] : [filterQueue, limit];
+  const rows = runSql$1(sql, `SELECT * FROM "${QUEUE_TABLE}" ${where} ORDER BY captured_at DESC, id DESC LIMIT ?`, ...params).toArray();
+  return { entries: rows.map((row) => rowToEntry(row)) };
+};
+const readQueueMessageById = (sql, id) => {
+  ensureQueueTable(sql);
+  const rows = runSql$1(sql, `SELECT * FROM "${QUEUE_TABLE}" WHERE id = ? LIMIT 1`, id).toArray();
+  const row = rows[0];
+  return row === void 0 ? void 0 : rowToEntry(row);
+};
+const clearQueueMessages = (sql) => {
+  ensureQueueTable(sql);
+  runSql$1(sql, `DELETE FROM "${QUEUE_TABLE}"`);
+  return { cleared: true };
+};
+
+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) => stableWireKey({ 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 LunoraError("INTERNAL", `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 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 LunoraError("INTERNAL", `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(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, args: decodeWire(message.args) });
+        this.host.recordShapePokeFanout(iterated, delivered, Date.now() - startMs);
+        return noContent();
+      }
+      case "relay_shape_subscribe": {
+        return jsonRelayResponse(this.onShapeSubscribe({ ...message, args: decodeWire(message.args) }));
+      }
+      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` wire-encoded for the same reason as `rowsPatch` below; the
+        // relay decodes them at `handleControl` before the routing match.
+        args: encodeWire(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` wire-encoded like `rowsPatch`; decoded relay-side at
+        // `handleControl` before the routing match.
+        args: encodeWire(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) {
+      const { body } = toErrorBody(error, { fallbackCode: "SHAPE_RESOLVE_FAILED", redactedMessage: "shape resolution failed" });
+      return { error: { code: body.code, message: body.message } };
+    }
+    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 = stableWireKey(base.effectiveWhere);
+    const baseColumns = stableWireKey(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 && stableWireKey(resolved.effectiveWhere) === baseWhere && stableWireKey(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 = {
+      // Wire-encode before the relay->owner `JSON.stringify` hop: the shard
+      // decoded these args at its `shape_subscribe` entry point, so a
+      // `bigint`/`Date`/bytes arg would otherwise throw (or corrupt) here.
+      args: encodeWire(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";
@@ -348,6 +1364,69 @@ const readRequestLog = (sql, options = {}) => {
     return base;
   });
 };
+const readErrorIssues = (sql, options = {}) => {
+  ensureRequestLogTable(sql);
+  const limit = Math.max(1, Math.min(options.limit ?? REQUEST_LOG_RETENTION, 1e4));
+  const conjuncts = ["outcome = 'error'"];
+  const parameters = [];
+  if (options.functionPathPrefix !== void 0 && options.functionPathPrefix !== "") {
+    conjuncts.push(String.raw`function_path LIKE ? ESCAPE '\'`);
+    parameters.push(`${escapeLike(options.functionPathPrefix)}%`);
+  }
+  if (options.userId !== void 0 && options.userId !== "") {
+    conjuncts.push("user_id = ?");
+    parameters.push(options.userId);
+  }
+  if (options.shardKey !== void 0 && options.shardKey !== "") {
+    conjuncts.push("shard_key = ?");
+    parameters.push(options.shardKey);
+  }
+  parameters.push(limit);
+  const rows = runSql(
+    sql,
+    `SELECT function_path, error_message, ts
+         FROM "${REQUEST_LOG_TABLE}" WHERE ${conjuncts.join(" AND ")} ORDER BY seq DESC LIMIT ?`,
+    ...parameters
+  ).toArray();
+  const issues = /* @__PURE__ */ new Map();
+  const sampleTs = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const message = row.error_message ?? "";
+    const { culprit, hash, title } = fingerprintError({ functionPath: row.function_path, message });
+    const existing = issues.get(hash);
+    if (existing === void 0) {
+      issues.set(hash, { count: 1, culprit, firstSeen: row.ts, hash, lastSeen: row.ts, sampleMessage: message, title });
+      sampleTs.set(hash, row.ts);
+      continue;
+    }
+    existing.count += 1;
+    existing.firstSeen = Math.min(existing.firstSeen, row.ts);
+    existing.lastSeen = Math.max(existing.lastSeen, row.ts);
+    if (row.ts > (sampleTs.get(hash) ?? Number.NEGATIVE_INFINITY)) {
+      sampleTs.set(hash, row.ts);
+      existing.sampleMessage = message;
+      existing.title = title;
+    }
+  }
+  return [...issues.values()].toSorted((a, b) => b.lastSeen - a.lastSeen);
+};
+
+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;
@@ -413,116 +1492,14 @@ 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 REQUIRE_EPHEMERAL_ENV_VALUES = /* @__PURE__ */ new Set(["1", "enabled", "on", "true", "yes"]);
+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];
@@ -536,7 +1513,7 @@ const setsIntersect = (a, b) => {
 const parseRunMigrationArgs = (args) => {
   const id = typeof args["id"] === "string" ? args["id"] : "";
   if (id.trim() === "") {
-    throw Object.assign(new Error("runMigration: `id` is required"), { code: "MIGRATION_ID_REQUIRED", name: "LunoraError", status: 400 });
+    throw new LunoraError("MIGRATION_ID_REQUIRED", "runMigration: `id` is required", { status: 400 });
   }
   return {
     batchSize: typeof args["batchSize"] === "number" ? args["batchSize"] : void 0,
@@ -551,25 +1528,25 @@ const parseWriteRowArgs = (args) => {
   const { op } = args;
   const table = typeof args["table"] === "string" ? args["table"] : "";
   if (op !== "insert" && op !== "patch" && op !== "replace" && op !== "delete") {
-    throw Object.assign(new Error("writeRow: `op` must be insert|patch|replace|delete"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "writeRow: `op` must be insert|patch|replace|delete");
   }
   if (table.trim() === "") {
-    throw Object.assign(new Error("writeRow: `table` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "writeRow: `table` is required");
   }
   const id = typeof args["id"] === "string" ? args["id"] : void 0;
   const record = typeof args["doc"] === "object" && args["doc"] !== null && !Array.isArray(args["doc"]) ? args["doc"] : void 0;
   if (op !== "insert" && (id === void 0 || id === "")) {
-    throw Object.assign(new Error(`writeRow: \`id\` is required for op "${op}"`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", `writeRow: \`id\` is required for op "${op}"`);
   }
   if (op !== "delete" && record === void 0) {
-    throw Object.assign(new Error(`writeRow: \`doc\` is required for op "${op}"`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", `writeRow: \`doc\` is required for op "${op}"`);
   }
   return { doc: record, id, op, table };
 };
 const parseCreateWorkflowInstanceArgs = (args) => {
   const exportName = typeof args["exportName"] === "string" ? args["exportName"].trim() : "";
   if (exportName === "") {
-    throw Object.assign(new Error("createWorkflowInstance: `exportName` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "createWorkflowInstance: `exportName` is required");
   }
   const id = typeof args["id"] === "string" && args["id"] !== "" ? args["id"] : void 0;
   return { exportName, id, params: args["params"] };
@@ -578,10 +1555,10 @@ const parseGetWorkflowInstanceStatusArgs = (args) => {
   const exportName = typeof args["exportName"] === "string" ? args["exportName"].trim() : "";
   const id = typeof args["id"] === "string" ? args["id"].trim() : "";
   if (exportName === "") {
-    throw Object.assign(new Error("getWorkflowInstanceStatus: `exportName` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "getWorkflowInstanceStatus: `exportName` is required");
   }
   if (id === "") {
-    throw Object.assign(new Error("getWorkflowInstanceStatus: `id` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "getWorkflowInstanceStatus: `id` is required");
   }
   return { exportName, id };
 };
@@ -636,7 +1613,7 @@ const parseTablePageOrderBy = (raw) => {
 const parseBulkDeleteArgs = (args) => {
   const table = typeof args["table"] === "string" ? args["table"] : "";
   if (table.trim() === "") {
-    throw Object.assign(new Error("deleteRows: `table` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "deleteRows: `table` is required");
   }
   return {
     filters: parseTablePageFilters(args["filters"]),
@@ -648,37 +1625,39 @@ const parseBulkDeleteArgs = (args) => {
 const parseClearTableArgs = (args) => {
   const table = typeof args["table"] === "string" ? args["table"] : "";
   if (table.trim() === "") {
-    throw Object.assign(new Error("clearTable: `table` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "clearTable: `table` is required");
   }
   return { limit: typeof args["limit"] === "number" ? args["limit"] : void 0, table };
 };
 const parseRecordAuthEventArgs = (args) => {
   const { outcome } = args;
   if (outcome !== "ok" && outcome !== "fail") {
-    throw Object.assign(new Error('recordAuthEvent: `outcome` must be "ok" or "fail"'), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", 'recordAuthEvent: `outcome` must be "ok" or "fail"');
   }
   return { outcome };
 };
+const CONTAINER_EXIT_CODE_PATTERN = /\(exit (\d+)\)/;
 const parseRecordContainerEventArgs = (args) => {
   const raw = args["event"];
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw Object.assign(new Error("recordContainerEvent: `event` must be an object"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "recordContainerEvent: `event` must be an object");
   }
   const envelope = raw;
   const container = typeof envelope["container"] === "string" ? envelope["container"] : "";
   const event = typeof envelope["event"] === "string" ? envelope["event"] : "";
   if (container.trim() === "" || event.trim() === "") {
-    throw Object.assign(new Error("recordContainerEvent: `event.container` and `event.event` are required"), {
-      code: "BAD_REQUEST",
-      name: "LunoraError",
-      status: 400
-    });
+    throw new LunoraError("BAD_REQUEST", "recordContainerEvent: `event.container` and `event.event` are required");
   }
   const level = envelope["level"] === "error" ? "error" : "info";
   const detail = typeof envelope["message"] === "string" ? envelope["message"] : void 0;
   const timestamp = typeof envelope["ts"] === "number" ? envelope["ts"] : Date.now();
+  const instance = typeof envelope["instance"] === "string" && envelope["instance"] !== "" ? envelope["instance"] : void 0;
+  const exitRaw = detail === void 0 ? void 0 : CONTAINER_EXIT_CODE_PATTERN.exec(detail)?.[1];
+  const exitCode = exitRaw === void 0 ? void 0 : Number.parseInt(exitRaw, 10);
   return {
+    exitCode,
     functionPath: `container:${container}`,
+    instance,
     level,
     message: detail === void 0 || detail === "" ? event : `${event}: ${detail}`,
     timestamp
@@ -688,21 +1667,21 @@ const parseRunAsArgs = (args) => {
   const functionPath = typeof args["functionPath"] === "string" ? args["functionPath"] : "";
   const userId = typeof args["userId"] === "string" ? args["userId"] : "";
   if (functionPath.trim() === "") {
-    throw Object.assign(new Error("runAs: `functionPath` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "runAs: `functionPath` is required");
   }
   if (functionPath.startsWith(ADMIN_FUNCTION_PREFIX)) {
-    throw Object.assign(new Error("runAs: cannot target a reserved admin function"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "runAs: cannot target a reserved admin function");
   }
   if (userId.trim() === "") {
-    throw Object.assign(new Error("runAs: `userId` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "runAs: `userId` is required");
   }
   const rawArgs = args["args"];
   if (rawArgs !== void 0 && (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs))) {
-    throw Object.assign(new Error("runAs: `args` must be an object"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "runAs: `args` must be an object");
   }
   const rawIdentity = args["identity"];
   if (rawIdentity !== void 0 && (typeof rawIdentity !== "object" || rawIdentity === null || Array.isArray(rawIdentity))) {
-    throw Object.assign(new Error("runAs: `identity` must be an object"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "runAs: `identity` must be an object");
   }
   return {
     args: rawArgs === void 0 ? {} : rawArgs,
@@ -713,7 +1692,7 @@ const parseRunAsArgs = (args) => {
 };
 const parseRecordMailArgs = (args) => {
   const bad = (message) => {
-    throw Object.assign(new Error(`recordMail: ${message}`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", `recordMail: ${message}`);
   };
   const { bcc, cc, from, headers, html, replyTo, subject, text, to } = args;
   if (typeof subject !== "string") {
@@ -754,7 +1733,7 @@ const TEST_MAIL_DEFAULT_TO = "test@lunora.sh";
 const buildTestMailInput = (args) => {
   const { to } = args;
   if (to !== void 0 && typeof to !== "string") {
-    throw Object.assign(new Error("sendTestMail: `to` must be a string"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "sendTestMail: `to` must be a string");
   }
   const recipient = to ?? TEST_MAIL_DEFAULT_TO;
   const link = "https://example.test/verify?token=demo";
@@ -768,29 +1747,99 @@ Verify your email: ${link}`,
     to: recipient
   };
 };
+const parseRecordQueueMessageArgs = (args) => {
+  const bad = (message) => {
+    throw new LunoraError("BAD_REQUEST", `recordQueueMessage: ${message}`);
+  };
+  const raw = args["messages"];
+  if (!Array.isArray(raw)) {
+    bad("`messages` must be an array");
+  }
+  const outcomes = /* @__PURE__ */ new Set(["ack", "error", "retry"]);
+  return raw.map((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      bad(`\`messages[${String(index)}]\` must be an object`);
+    }
+    const record = entry;
+    const messageId = typeof record["messageId"] === "string" ? record["messageId"] : "";
+    const queue = typeof record["queue"] === "string" ? record["queue"] : "";
+    const outcome = typeof record["outcome"] === "string" ? record["outcome"] : "";
+    if (messageId === "") {
+      bad(`\`messages[${String(index)}].messageId\` is required`);
+    }
+    if (queue === "") {
+      bad(`\`messages[${String(index)}].queue\` is required`);
+    }
+    if (!outcomes.has(outcome)) {
+      bad(`\`messages[${String(index)}].outcome\` must be one of ack | error | retry`);
+    }
+    const { attempts, timestamp } = record;
+    return {
+      attempts: typeof attempts === "number" && Number.isFinite(attempts) ? attempts : 1,
+      body: record["body"],
+      deadLettered: record["deadLettered"] === true,
+      error: typeof record["error"] === "string" ? record["error"] : void 0,
+      exportName: typeof record["exportName"] === "string" ? record["exportName"] : void 0,
+      messageId,
+      outcome,
+      queue,
+      timestamp: typeof timestamp === "number" && Number.isFinite(timestamp) ? timestamp : 0
+    };
+  });
+};
+const MAX_QUEUE_SEND_BATCH = 100;
+const parseSendQueueMessageArgs = (args) => {
+  const exportName = typeof args["exportName"] === "string" ? args["exportName"].trim() : "";
+  if (exportName === "") {
+    throw new LunoraError("BAD_REQUEST", "sendQueueMessage: `exportName` is required");
+  }
+  const delayRaw = args["delaySeconds"];
+  if (delayRaw !== void 0 && (typeof delayRaw !== "number" || !Number.isFinite(delayRaw) || delayRaw < 0)) {
+    throw new LunoraError("BAD_REQUEST", "sendQueueMessage: `delaySeconds` must be a non-negative number");
+  }
+  const batch = Array.isArray(args["batch"]) ? args["batch"] : void 0;
+  if (batch !== void 0 && (batch.length === 0 || batch.length > MAX_QUEUE_SEND_BATCH)) {
+    throw new LunoraError("BAD_REQUEST", `sendQueueMessage: \`batch\` must contain between 1 and ${String(MAX_QUEUE_SEND_BATCH)} messages`);
+  }
+  return {
+    batch,
+    body: args["body"],
+    contentType: typeof args["contentType"] === "string" ? args["contentType"] : void 0,
+    delaySeconds: delayRaw,
+    exportName
+  };
+};
+const parseReplayQueueMessageArgs = (args) => {
+  const id = typeof args["id"] === "string" ? args["id"].trim() : "";
+  if (id === "") {
+    throw new LunoraError("BAD_REQUEST", "replayQueueMessage: `id` is required");
+  }
+  const target = typeof args["target"] === "string" && args["target"].trim() !== "" ? args["target"].trim() : void 0;
+  return { id, target };
+};
 const parseRankBeforeArgs = (args) => {
   const table = typeof args["table"] === "string" ? args["table"] : "";
   const index = typeof args["index"] === "string" ? args["index"] : "";
   const rowId = typeof args["rowId"] === "string" ? args["rowId"] : "";
   if (table.trim() === "") {
-    throw Object.assign(new Error("rankBefore: `table` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "rankBefore: `table` is required");
   }
   if (index.trim() === "") {
-    throw Object.assign(new Error("rankBefore: `index` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "rankBefore: `index` is required");
   }
   if (typeof args["partitionKey"] !== "string") {
-    throw Object.assign(new Error("rankBefore: `partitionKey` must be a string"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "rankBefore: `partitionKey` must be a string");
   }
   if (rowId.trim() === "") {
-    throw Object.assign(new Error("rankBefore: `rowId` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "rankBefore: `rowId` is required");
   }
   if (!Array.isArray(args["sortValues"])) {
-    throw Object.assign(new Error("rankBefore: `sortValues` must be an array"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "rankBefore: `sortValues` must be an array");
   }
   return { index, partitionKey: args["partitionKey"], rowId, sortValues: args["sortValues"], table };
 };
 const badRequest = (message) => {
-  throw Object.assign(new Error(message), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  throw new LunoraError("BAD_REQUEST", message);
 };
 const requireNonEmptyString = (value, field) => {
   if (typeof value !== "string" || value.trim() === "") {
@@ -850,7 +1899,7 @@ const decodeIndexHitKey = (key) => {
 const parseApplyCdcArgs = (args) => {
   const raw = args["changes"];
   if (!Array.isArray(raw)) {
-    throw Object.assign(new Error("applyCdc: `changes` must be an array"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+    throw new LunoraError("BAD_REQUEST", "applyCdc: `changes` must be an array");
   }
   const changes = raw.map((entry, index) => {
     const record = entry;
@@ -858,27 +1907,15 @@ const parseApplyCdcArgs = (args) => {
     const table = typeof record["table"] === "string" ? record["table"] : "";
     const id = typeof record["id"] === "string" ? record["id"] : "";
     if (table === "" || id === "" || op !== "insert" && op !== "update" && op !== "delete") {
-      throw Object.assign(new Error(`applyCdc: changes[${String(index)}] must have a table, id, and op of insert|update|delete`), {
-        code: "BAD_REQUEST",
-        name: "LunoraError",
-        status: 400
-      });
+      throw new LunoraError("BAD_REQUEST", `applyCdc: changes[${String(index)}] must have a table, id, and op of insert|update|delete`);
     }
     const rawDocument = record["doc"];
     if (rawDocument !== void 0 && (typeof rawDocument !== "object" || rawDocument === null || Array.isArray(rawDocument))) {
-      throw Object.assign(new Error(`applyCdc: changes[${String(index)}].doc must be an object`), {
-        code: "BAD_REQUEST",
-        name: "LunoraError",
-        status: 400
-      });
+      throw new LunoraError("BAD_REQUEST", `applyCdc: changes[${String(index)}].doc must be an object`);
     }
     const document = rawDocument;
     if (document !== void 0 && typeof document["_id"] === "string" && document["_id"] !== id) {
-      throw Object.assign(new Error(`applyCdc: changes[${String(index)}].doc._id must match the entry id`), {
-        code: "BAD_REQUEST",
-        name: "LunoraError",
-        status: 400
-      });
+      throw new LunoraError("BAD_REQUEST", `applyCdc: changes[${String(index)}].doc._id must match the entry id`);
     }
     return {
       doc: document,
@@ -898,13 +1935,7 @@ const parseCdcSyncArgs = (args) => {
   };
   return { limit: toCount(args["limit"]), sinceSeq: toCount(args["sinceSeq"]) ?? 0 };
 };
-const jsonResponse = (body, status = 200, bookmark) => {
-  const headers = { "content-type": "application/json" };
-  if (bookmark) {
-    headers["x-d1-bookmark"] = bookmark;
-  }
-  return Response.json(body, { headers, status });
-};
+const bookmarkHeaders = (bookmark) => bookmark ? { "x-d1-bookmark": bookmark } : void 0;
 const parseIdentityHeader = (raw) => {
   if (!raw) {
     return void 0;
@@ -918,6 +1949,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) {
@@ -971,16 +2009,6 @@ const extractBearerToken = (authorization) => {
   const value = rest.join(" ").trim();
   return value.length > 0 ? value : void 0;
 };
-const constantTimeEqual = (a, b) => {
-  const max = Math.max(a.length, b.length);
-  let diff = a.length ^ b.length;
-  for (let index = 0; index < max; index += 1) {
-    const charA = index < a.length ? a.charCodeAt(index) : 0;
-    const charB = index < b.length ? b.charCodeAt(index) : 0;
-    diff |= charA ^ charB;
-  }
-  return diff === 0;
-};
 class ShardDO {
   /**
    * Per-socket cap on concurrent stream iterators. Each in-flight stream
@@ -1002,6 +2030,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
@@ -1093,6 +2143,8 @@ class ShardDO {
    * cleared in the `finally` block of `fetch` like the other per-request fields.
    */
   currentRequestIp;
+  /** W3C `traceparent` of the inbound RPC; forwarded onto outbound container fetches. */
+  currentRequestTraceparent;
   /**
    * Client-issued idempotency key for the in-flight mutation, forwarded via the
    * `x-lunora-mutation-id` header. When set, the dispatch path dedups the call
@@ -1103,6 +2155,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 +2218,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 +2238,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 +2288,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 +2403,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 +2435,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,9 +2456,14 @@ 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";
+    this.currentRequestTraceparent = request.headers.get("traceparent") ?? void 0;
     this.currentRequestReadTables = void 0;
     this.currentRequestCacheHit = void 0;
     this.metrics.requests += 1;
@@ -1285,22 +2474,30 @@ class ShardDO {
     try {
       if (payload.functionPath.startsWith(RELATION_FUNCTION_PREFIX)) {
         const value = await this.runRelationFanoutRead(payload.functionPath, payload.args ?? {});
-        return jsonResponse(value, 200, this.currentResponseBookmark);
+        return jsonResponse(value, 200, bookmarkHeaders(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) {
@@ -1320,15 +2517,22 @@ class ShardDO {
         message,
         timestamp: Date.now()
       });
+      this.recordChangedTable(REQUEST_LOG_TABLE);
+      await this.flushChangedTables();
       return this.errorToResponse(error);
     } finally {
       this.currentRequestBookmark = void 0;
       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;
+      this.currentRequestTraceparent = void 0;
       this.currentScannedTables = void 0;
       this.currentIndexHits = void 0;
       this.currentRequestReadTables = void 0;
@@ -1363,6 +2567,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);
@@ -1378,7 +2585,24 @@ class ShardDO {
         ws.send(JSON.stringify({ id: envelope.id, message: "admin subscription requires admin authorization", type: "error" }));
         return;
       }
-      const status = this.subscribe(ws, envelope.id, envelope.query);
+      let query;
+      try {
+        query = envelope.query.args === void 0 ? envelope.query : { ...envelope.query, args: decodeWire(envelope.query.args) };
+      } catch {
+        try {
+          ws.send(
+            JSON.stringify({
+              code: "BAD_SUBSCRIPTION_ARGS",
+              error: { code: "BAD_SUBSCRIPTION_ARGS", message: "subscription args failed wire decoding" },
+              id: envelope.id,
+              type: "error"
+            })
+          );
+        } catch {
+        }
+        return;
+      }
+      const status = this.subscribe(ws, envelope.id, query);
       if (status !== "ok") {
         const code = status === "too_many" ? "TOO_MANY_SUBSCRIPTIONS" : "SUBSCRIPTION_PERSIST_FAILED";
         const errorMessage = status === "too_many" ? `subscription cap of ${String(ShardDO.MAX_SUBSCRIPTIONS_PER_SOCKET)} reached on this socket` : "failed to persist subscription attachment";
@@ -1389,9 +2613,30 @@ class ShardDO {
         return;
       }
       ws.send(JSON.stringify({ id: envelope.id, type: "ack" }));
-      if (functionPath) {
-        await this.seedSubscription(ws, envelope.id, envelope.query, functionPath, isAdmin);
-      }
+      if (functionPath) {
+        await this.seedSubscription(ws, envelope.id, query, functionPath, isAdmin);
+      }
+      return;
+    }
+    if (envelope.type === "shape_subscribe" && envelope.shape) {
+      let shapeArgs;
+      try {
+        shapeArgs = envelope.shape.args === void 0 ? void 0 : decodeWire(envelope.shape.args);
+      } catch {
+        this.sendShapeSubscribeError(ws, envelope.id, "BAD_SUBSCRIPTION_ARGS", "shape args failed wire decoding");
+        return;
+      }
+      await this.handleShapeSubscribe(ws, envelope.id, {
+        args: shapeArgs,
+        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) {
@@ -1399,19 +2644,23 @@ class ShardDO {
         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 +2693,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
@@ -1505,9 +2791,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with a schema-aware reader that uses `this`
   runRelationFanoutRead(_functionPath, _args) {
-    throw Object.assign(new Error("__lunora_relation__: no schema bound — the base ShardDO cannot serve cross-shard relation reads"), {
-      code: "NOT_IMPLEMENTED",
-      name: "LunoraError",
+    throw new LunoraError("NOT_IMPLEMENTED", "__lunora_relation__: no schema bound — the base ShardDO cannot serve cross-shard relation reads", {
       status: 500
     });
   }
@@ -1634,34 +2918,20 @@ class ShardDO {
    */
   async runInTransaction(handler) {
     if (this.transactionDepth > 0) {
-      throw Object.assign(new Error("nested transactions are not supported in SQLite-in-DO"), {
-        code: "NESTED_TRANSACTION",
-        name: "LunoraError",
-        status: 500
-      });
+      throw new LunoraError("NESTED_TRANSACTION", "nested transactions are not supported in SQLite-in-DO", { status: 500 });
     }
     const sqlHandle = this.state.storage.sql;
     if (!sqlHandle || typeof sqlHandle.exec !== "function") {
-      throw Object.assign(new Error("storage.sql is not available on this ShardDO state"), {
-        code: "SQL_UNAVAILABLE",
-        name: "LunoraError",
-        status: 500
-      });
+      throw new LunoraError("SQL_UNAVAILABLE", "storage.sql is not available on this ShardDO state", { 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;
       }
@@ -1705,6 +2975,14 @@ class ShardDO {
   getCurrentIp() {
     return this.currentRequestIp;
   }
+  /**
+   * W3C `traceparent` of the inbound RPC (forwarded by the runtime), or
+   * `undefined`. `buildCtx` passes it to `createContainerContext` so outbound
+   * container fetches carry it and the container's spans join the same trace.
+   */
+  getCurrentTraceparent() {
+    return this.currentRequestTraceparent;
+  }
   /**
    * Identity claims (email, name, roles, …) forwarded by the runtime's
    * `resolveIdentity` hook. Returns `undefined` for anonymous requests
@@ -1732,9 +3010,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to reach the generated migration registry
   runShardDataMigration(args) {
-    return Promise.reject(
-      Object.assign(new Error(`data migration "${args.id}" is not registered`), { code: "MIGRATION_NOT_FOUND", name: "LunoraError", status: 404 })
-    );
+    return Promise.reject(new LunoraError("MIGRATION_NOT_FOUND", `data migration "${args.id}" is not registered`, { status: 404 }));
   }
   /**
    * Lazily provision the shard's physical tables before an operation that
@@ -1859,7 +3135,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
@@ -1941,7 +3268,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to build a schema-aware writer
   runShardWrite(args) {
-    return Promise.reject(Object.assign(new Error(`unknown table: ${args.table}`), { code: "UNKNOWN_TABLE", name: "LunoraError", status: 404 }));
+    return Promise.reject(new LunoraError("UNKNOWN_TABLE", `unknown table: ${args.table}`, { status: 404 }));
   }
   /**
    * Delete one row by primary key THROUGH the schema-aware writer — the
@@ -1956,7 +3283,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to build a schema-aware writer
   deleteRowThroughWriter(_table, _id) {
-    return Promise.reject(Object.assign(new Error(`unknown table: ${_table}`), { code: "UNKNOWN_TABLE", name: "LunoraError", status: 404 }));
+    return Promise.reject(new LunoraError("UNKNOWN_TABLE", `unknown table: ${_table}`, { status: 404 }));
   }
   /**
    * Bulk-delete the rows of `table` matching the active `filters`/`search`
@@ -1998,9 +3325,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to build a schema-aware writer
   runShardRankBefore(_args) {
-    return Promise.reject(
-      Object.assign(new Error("rankBefore is not implemented in base ShardDO"), { code: "NOT_IMPLEMENTED", name: "LunoraError", status: 500 })
-    );
+    return Promise.reject(new LunoraError("NOT_IMPLEMENTED", "rankBefore is not implemented in base ShardDO", { status: 500 }));
   }
   /**
    * Page this shard's local ranked slice under `index`, each row tagged with
@@ -2014,9 +3339,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to build a schema-aware writer
   runShardRankPage(_args) {
-    return Promise.reject(
-      Object.assign(new Error("rankPage is not implemented in base ShardDO"), { code: "NOT_IMPLEMENTED", name: "LunoraError", status: 500 })
-    );
+    return Promise.reject(new LunoraError("NOT_IMPLEMENTED", "rankPage is not implemented in base ShardDO", { status: 500 }));
   }
   /**
    * Page this shard's change-data-capture log past `sinceSeq`. Read-only and
@@ -2124,13 +3447,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 +3463,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 +3471,195 @@ 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, bookmarkHeaders(this.currentResponseBookmark));
+    }
+    return jsonResponse(
+      {
+        error: {
+          code: "OUT_OF_ORDER",
+          expectedMutationId: mutatorClass.expected,
+          message: `out-of-order mutation; expected sequence ${String(mutatorClass.expected)}`
+        }
+      },
+      409,
+      bookmarkHeaders(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,
+      bookmarkHeaders(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, bookmarkHeaders(this.currentResponseBookmark));
+    }
+    const commitCursor = this.mutationCommitCursor();
+    return jsonResponse(commitCursor === void 0 ? { result } : { commitCursor, result }, 200, bookmarkHeaders(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
@@ -2154,9 +3668,7 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to build a schema-aware writer
   runShardApplyCdc(_args) {
-    return Promise.reject(
-      Object.assign(new Error("applyCdc is not implemented in base ShardDO"), { code: "NOT_IMPLEMENTED", name: "LunoraError", status: 500 })
-    );
+    return Promise.reject(new LunoraError("NOT_IMPLEMENTED", "applyCdc is not implemented in base ShardDO", { status: 500 }));
   }
   /**
    * Register a subscription on the given socket. Stored via
@@ -2195,6 +3707,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 +3805,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 +3828,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
@@ -2308,8 +3952,17 @@ class ShardDO {
     const tracker = createDependencyTracker();
     this.currentTracker = tracker;
     const hitsBefore = this.reactiveCache.stats().hits;
+    const userId = this.getCurrentUserId();
+    const claims = this.getCurrentIdentity();
+    const identity = userId === void 0 && claims === void 0 ? (
+      // eslint-disable-next-line unicorn/no-null -- reactiveCacheKey's identity arg is `null | string`; null is the documented "anonymous caller" discriminator
+      null
+    ) : (
+      // eslint-disable-next-line unicorn/no-null -- fold userId/claims into the discriminator; missing fields serialize as null so the shape stays canonical
+      stableStringify({ claims: claims ?? null, userId: userId ?? null })
+    );
     try {
-      const result = await this.reactiveCache.run(reactiveCacheKey(functionPath, args, this.getCurrentUserId() ?? null), tracker.collect(), run);
+      const result = await this.reactiveCache.run(reactiveCacheKey(functionPath, args, identity), tracker.collect(), run);
       this.currentRequestCacheHit = this.reactiveCache.stats().hits > hitsBefore;
       this.currentRequestReadTables = tablesFromDeps(tracker.collect());
       return result;
@@ -2667,20 +4320,67 @@ class ShardDO {
    */
   // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method (groups with the request handlers); kept non-static so subclasses can override the error mapping
   errorToResponse(error) {
-    if (error instanceof ConflictError) {
-      return jsonResponse({ error: { code: error.code, message: error.message } }, error.status);
+    const { body, redacted, status } = toErrorBody(error, { encodeData: encodeWire, fallbackCode: "RPC_FAILED", redactedMessage: "internal error" });
+    if (redacted) {
+      console.error("[@lunora/do] internal error:", error);
+    }
+    return jsonResponse({ error: body }, status);
+  }
+  /**
+   * 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 (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);
+    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 });
     }
-    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);
+    return jsonResponse({ results }, 200, bookmarkHeaders(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 { body, status } = toErrorBody(error, { fallbackCode: "BATCH_ENTRY_FAILED" });
+      return {
+        body: { error: body },
+        bookmark: void 0,
+        id: entry?.id,
+        status
+      };
     }
-    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
@@ -2796,12 +4496,27 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.sendTestMail) {
       return this.handleSendTestMail(args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.recordQueueMessage) {
+      return this.handleRecordQueueMessage(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.clearQueueMessages) {
+      return this.handleClearQueueMessages();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.sendQueueMessage) {
+      return this.handleSendQueueMessage(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.replayQueueMessage) {
+      return this.handleReplayQueueMessage(args);
+    }
     if (functionPath === ADMIN_FUNCTIONS.createWorkflowInstance) {
       return this.handleCreateWorkflowInstance(args);
     }
     if (functionPath === ADMIN_FUNCTIONS.getWorkflowInstanceStatus) {
       return this.handleGetWorkflowInstanceStatus(args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.listFlags) {
+      return this.handleListFlags(args);
+    }
     return this.handlePitrAdminOp(functionPath, args);
   }
   /**
@@ -2831,10 +4546,32 @@ class ShardDO {
    * the panel renders it alongside `ctx.log` lines. Admin-gated by
    * `handleAdminRpc`'s caller (the same `LUNORA_ADMIN_TOKEN` bearer as every
    * other admin write).
-   */
-  handleRecordContainerEvent(args) {
+   *
+   * An `error`-level lifecycle event (a crash/`onError`, or a non-zero-exit
+   * `stop`) is ALSO appended as an `error`-outcome row to the durable
+   * `__lunora_reqlog__` — the same readout `getIssues` groups over — so a
+   * crash-looping container folds into the Issues list right beside Worker
+   * errors (they share the `fingerprintError` hash over `functionPath ::
+   * bucket(message)`). The in-memory buffer stays the live Logs feed; the
+   * durable row is what survives hibernation for triage.
+   */
+  async handleRecordContainerEvent(args) {
     const entry = parseRecordContainerEventArgs(args);
     this.logs.push(entry);
+    const crashed = entry.level === "error" || entry.exitCode !== void 0 && entry.exitCode !== 0;
+    if (crashed) {
+      const logEntry = {
+        durationMs: 0,
+        errorMessage: entry.message,
+        functionPath: entry.functionPath,
+        outcome: "error",
+        shardKey: this.state.id?.name,
+        ts: entry.timestamp
+      };
+      this.persistRequestLog(logEntry, this.requestLogConfig());
+      this.recordChangedTable(REQUEST_LOG_TABLE);
+      await this.flushChangedTables();
+    }
     return jsonResponse({ result: { recorded: true } }, 200);
   }
   /**
@@ -2872,15 +4609,11 @@ class ShardDO {
   resolveWorkflowBinding(exportName) {
     const metadata = this.workflowsMetadata().workflows.find((workflow) => workflow.exportName === exportName);
     if (!metadata) {
-      throw Object.assign(new Error(`workflow "${exportName}" is not declared`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+      throw new LunoraError("BAD_REQUEST", `workflow "${exportName}" is not declared`);
     }
     const binding = this.env?.[metadata.binding];
     if (typeof binding !== "object" || binding === null || typeof binding.create !== "function" || typeof binding.get !== "function") {
-      throw Object.assign(new Error(`workflow binding "${metadata.binding}" is not available on this deployment`), {
-        code: "BAD_REQUEST",
-        name: "LunoraError",
-        status: 400
-      });
+      throw new LunoraError("BAD_REQUEST", `workflow binding "${metadata.binding}" is not available on this deployment`);
     }
     return binding;
   }
@@ -2922,6 +4655,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
@@ -2987,6 +4735,119 @@ class ShardDO {
     const result = recordCapturedMail(this.state.storage.sql, input, Date.now());
     return jsonResponse({ result }, 200);
   }
+  /**
+   * Serve `__lunora_admin__:recordQueueMessage` — the capture sink the generated
+   * worker `queue()` handler (via `@lunora/queue`'s `dispatchQueueBatch`) posts
+   * every consumed message batch to. Records it into the reserved
+   * `__lunora_queue_messages` table (bounded, auto-trimmed) so the studio Queues
+   * panel shows one unified consumed-message log across every push consumer. Like
+   * the mail catcher, the gate is the admin token alone — a token holder can
+   * already mutate the shard, so a token-gated capture insert adds no privilege.
+   */
+  handleRecordQueueMessage(args) {
+    const messages = parseRecordQueueMessageArgs(args);
+    const result = recordQueueMessages(this.state.storage.sql, messages, Date.now());
+    return jsonResponse({ result }, 200);
+  }
+  /** Empty the dev queue consumed-message log (studio "clear log" action). Admin-gated by the caller. */
+  handleClearQueueMessages() {
+    const result = clearQueueMessages(this.state.storage.sql);
+    return jsonResponse({ result }, 200);
+  }
+  /**
+   * Serve `__lunora_admin__:sendQueueMessage` — the studio's "Send test message"
+   * button. Resolves the declared queue's `QUEUE_*` producer binding and calls
+   * `.send(body, { delaySeconds?, contentType? })`, or `.sendBatch(...)` when a
+   * `batch` array is supplied. No SQLite write happens here (the message is only
+   * captured once a consumer processes it), so this only records an audit entry.
+   * Admin-gated by `handleAdminRpc`'s caller.
+   */
+  async handleSendQueueMessage(args) {
+    const parsed = parseSendQueueMessageArgs(args);
+    const { binding } = this.resolveQueueBinding(parsed.exportName);
+    let sent;
+    if (parsed.batch === void 0) {
+      await binding.send(parsed.body, { contentType: parsed.contentType, delaySeconds: parsed.delaySeconds });
+      sent = 1;
+    } else {
+      await binding.sendBatch(
+        parsed.batch.map((body) => {
+          return { body, contentType: parsed.contentType, delaySeconds: parsed.delaySeconds };
+        })
+      );
+      sent = parsed.batch.length;
+    }
+    this.recordAudit("sendQueueMessage", { detail: { count: sent, exportName: parsed.exportName } });
+    return jsonResponse({ result: { sent } }, 200);
+  }
+  /**
+   * Serve `__lunora_admin__:replayQueueMessage` — the studio's one-click replay /
+   * DLQ redrive. Looks the captured row up by id, resolves the destination export
+   * (explicit `target` → the parent queue when the message was captured off a
+   * dead-letter queue → the queue it was consumed from), and re-enqueues the
+   * stored body onto that producer. Records an audit entry; no SQLite write beyond
+   * that (the replayed message is re-captured when a consumer processes it).
+   * Admin-gated by `handleAdminRpc`'s caller.
+   */
+  async handleReplayQueueMessage(args) {
+    const parsed = parseReplayQueueMessageArgs(args);
+    const row = readQueueMessageById(this.state.storage.sql, parsed.id);
+    if (row === void 0) {
+      throw new LunoraError("BAD_REQUEST", `replayQueueMessage: captured message "${parsed.id}" was not found`, { status: 404 });
+    }
+    if (isLossyBody(row.body)) {
+      throw new LunoraError(
+        "BAD_REQUEST",
+        `replayQueueMessage: captured message "${parsed.id}" has a truncated or unserializable body and can't be replayed faithfully`,
+        { status: 422 }
+      );
+    }
+    const target = parsed.target ?? this.resolveReplayTarget(row.queue) ?? row.exportName;
+    if (typeof target !== "string" || target === "") {
+      throw new LunoraError(
+        "BAD_REQUEST",
+        `replayQueueMessage: captured message "${parsed.id}" has no declared producer to replay onto (pass \`target\`)`
+      );
+    }
+    const { binding } = this.resolveQueueBinding(target);
+    await binding.send(row.body);
+    this.recordAudit("replayQueueMessage", { detail: { messageId: row.messageId, target }, id: parsed.id });
+    return jsonResponse({ result: { sent: 1, target } }, 200);
+  }
+  /**
+   * Resolve a declared queue's runtime producer binding from this shard's `env`.
+   * Looks the `exportName` up in {@link queuesMetadata} (the codegen subclass's
+   * statically-discovered list) to find its generated `QUEUE_*` binding, then
+   * reads `env[binding]` and validates it carries `send`/`sendBatch`. A bad export
+   * name or a missing/malformed binding throws a 400 `LunoraError` so the studio
+   * surfaces an actionable message. Mirrors {@link resolveWorkflowBinding}.
+   */
+  resolveQueueBinding(exportName) {
+    const metadata = this.queuesMetadata().queues.find((queue) => queue.exportName === exportName);
+    if (!metadata) {
+      throw new LunoraError("BAD_REQUEST", `queue "${exportName}" is not declared`);
+    }
+    const binding = this.env?.[metadata.binding];
+    if (typeof binding !== "object" || binding === null || typeof binding.send !== "function") {
+      throw new LunoraError("BAD_REQUEST", `queue binding "${metadata.binding}" is not available on this deployment`);
+    }
+    return { binding, metadata };
+  }
+  /**
+   * Pick the replay destination export for a captured message's origin queue.
+   * When the message was consumed off a queue that is another queue's dead-letter
+   * queue, prefer that PARENT queue's producer (a DLQ usually has no producer of
+   * its own) so replay redrives onto the original; otherwise re-enqueue onto the
+   * queue the message came from. Returns `undefined` when neither is declared.
+   */
+  resolveReplayTarget(queueName) {
+    const { queues } = this.queuesMetadata();
+    const parent = queues.find((queue) => queue.deadLetterQueue === queueName);
+    if (parent !== void 0) {
+      return parent.exportName;
+    }
+    return queues.find((queue) => queue.name === queueName)?.exportName;
+  }
   /**
    * Append one durable audit entry for a state-changing admin op that just
    * succeeded, folding the acting user (from `getCurrentUserId`) into `detail`.
@@ -3051,12 +4912,33 @@ class ShardDO {
       ts: Date.now(),
       userId: this.getCurrentUserId()
     };
+    this.persistRequestLog(entry, config);
+  }
+  /**
+   * The single durable-row + Logpush write seam for `__lunora_reqlog__`. Both
+   * the per-dispatch {@link recordRequestLog} and the container-crash path
+   * ({@link handleRecordContainerEvent}) funnel through here so they can't
+   * drift — before this was extracted the container writer persisted the row
+   * but silently skipped the Logpush emit every other error got.
+   *
+   * Best-effort by contract: a SQL failure (e.g. a test double with no `sql`
+   * handle) or a serialization hiccup in the emit must NEVER turn a served
+   * request — or a container event push — into a failed one, so each half is
+   * swallowed independently.
+   *
+   * Errors are always streamed to `console` (rare, high-value — they ride CF
+   * Workers Logs at error level and the dev-server formats them in the
+   * terminal), redacted in prod like any other event. The full per-dispatch
+   * summary stream (successful OKs too) stays opt-in behind
+   * `LUNORA_REQUEST_LOG_EMIT` so a hot shard doesn't emit a line per call.
+   */
+  persistRequestLog(entry, config) {
     const writeOptions = { captureRaw: config.captureRaw, retention: config.retention };
     try {
       appendRequestLogEntry(this.state.storage.sql, entry, writeOptions);
     } catch {
     }
-    if (config.emit || outcome === "error") {
+    if (config.emit || entry.outcome === "error") {
       try {
         emitRequestLogEvent(entry, writeOptions);
       } catch {
@@ -3149,6 +5031,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.getRequestLog) {
       return this.readAdminRequestLog(sql, args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.getIssues) {
+      return this.readAdminIssues(sql, args);
+    }
     const durable = this.readAdminDurableSignal(functionPath, sql, args);
     if (durable) {
       return durable;
@@ -3274,6 +5159,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 +5189,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.listWorkflows) {
       return this.workflowsMetadata();
     }
+    if (functionPath === ADMIN_FUNCTIONS.listQueues) {
+      return this.queuesMetadata();
+    }
     return void 0;
   }
   /**
@@ -3313,6 +5204,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) {
@@ -3347,6 +5264,30 @@ class ShardDO {
     };
     return { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
   }
+  /**
+   * Resolve a `getIssues` admin read: fold the recent `error`-outcome
+   * request-log rows into grouped {@link readErrorIssues Issues} by fingerprint,
+   * accepting the same optional correlation filters as `getRequestLog`
+   * (function-path prefix, exact shardKey/userId) plus a `limit` on rows
+   * scanned. This is a read over the bounded reqlog readout — no new store —
+   * so a self-hosted worker gets grouped error triage for free. Carries the
+   * {@link ADMIN_WILDCARD} like the other log reads so a live Issues
+   * subscription re-runs on every write-flush (the per-socket JSON memo still
+   * suppresses byte-identical pushes).
+   */
+  // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
+  readAdminIssues(sql, args) {
+    ensureRequestLogTable(sql);
+    const result = {
+      issues: readErrorIssues(sql, {
+        functionPathPrefix: typeof args["functionPathPrefix"] === "string" ? args["functionPathPrefix"] : void 0,
+        limit: typeof args["limit"] === "number" ? args["limit"] : void 0,
+        shardKey: typeof args["shardKey"] === "string" ? args["shardKey"] : void 0,
+        userId: typeof args["userId"] === "string" ? args["userId"] : void 0
+      })
+    };
+    return { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+  }
   /**
    * Resolve a `getAuthMetrics` admin read: the durable app-level auth
    * attempt/failure counters + minute-bucketed history the studio SLO panel
@@ -3376,6 +5317,9 @@ class ShardDO {
     if (functionPath === ADMIN_FUNCTIONS.getCapturedMail) {
       return this.readAdminCapturedMail(sql, args);
     }
+    if (functionPath === ADMIN_FUNCTIONS.getQueueMessages) {
+      return this.readAdminQueueMessages(sql, args);
+    }
     return void 0;
   }
   // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
@@ -3396,15 +5340,37 @@ class ShardDO {
    * JSON memo still suppresses byte-identical pushes).
    */
   // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
-  readAdminCapturedMail(sql, args) {
+  readAdminCapturedMail(sql, args) {
+    const limit = typeof args["limit"] === "number" ? args["limit"] : void 0;
+    let result;
+    try {
+      result = readCapturedMail(sql, { limit });
+    } catch {
+      result = { entries: [] };
+    }
+    return { result, tables: /* @__PURE__ */ new Set([MAIL_TABLE]) };
+  }
+  /**
+   * Resolve a `getQueueMessages` admin read — the dev queue catcher's consumed
+   * message log (`queue-catcher.ts`), newest-first, optionally filtered to one
+   * queue. Best-effort: a SQL failure returns an empty log rather than throwing.
+   * Reported against the {@link QUEUE_TABLE} so this read participates in
+   * table-scoped subscription invalidation, but new captures arrive via the
+   * worker→root-shard `recordQueueMessage` write, which (like the mail catcher)
+   * inserts directly without a `flushChangedTables` — so the panel refreshes on
+   * its poll (`useAutoRefresh`) rather than a live push.
+   */
+  // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
+  readAdminQueueMessages(sql, args) {
     const limit = typeof args["limit"] === "number" ? args["limit"] : void 0;
+    const queue = typeof args["queue"] === "string" ? args["queue"] : void 0;
     let result;
     try {
-      result = readCapturedMail(sql, { limit });
+      result = readQueueMessages(sql, { limit, queue });
     } catch {
       result = { entries: [] };
     }
-    return { result, tables: /* @__PURE__ */ new Set([MAIL_TABLE]) };
+    return { result, tables: /* @__PURE__ */ new Set([QUEUE_TABLE]) };
   }
   /** Resolve a `readTablePage` admin read, parsing the loosely-typed args into the reader's options. */
   readAdminTablePage(sql, args) {
@@ -3416,6 +5382,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 +5427,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
@@ -3517,17 +5551,19 @@ 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 { body, redacted } = toErrorBody(error, { fallbackCode: "INTERNAL_SERVER_ERROR", redactedMessage: "internal error" });
+      if (redacted) {
+        console.error("[@lunora/do] unhandled stream error:", error);
+      }
       ws.send(
         JSON.stringify({
-          error: { code: typeof code === "string" ? code : "INTERNAL_SERVER_ERROR", message },
+          error: { code: body.code, message: body.message },
           id,
           type: "error"
         })
@@ -3558,11 +5594,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 +5701,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 +5719,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 +5736,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 +5756,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 +5776,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 { body } = toErrorBody(error, { fallbackCode: "SHAPE_RESOLVE_FAILED", redactedMessage: "shape resolution failed" });
+      return { code: body.code, message: body.message };
+    }
+    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 { body } = toErrorBody(error, { fallbackCode: "SHAPE_SEED_FAILED", redactedMessage: "shape seed failed" });
+      return { code: body.code, message: body.message };
+    }
+  }
+  /**
+   * 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 +6341,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 +6368,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:
@@ -3788,9 +6400,14 @@ class ShardDO {
    * server logs, browser history, and `Referer` headers on any
    * subresource the upgrade page loads after the handshake. Use a
    * short-lived rotating token in production rather than a long-lived
-   * secret.
+   * secret — for the ADMIN credential specifically, the worker mints one
+   * (`POST /_lunora/admin/ws-token`) and {@link isAdminSocket} accepts it, so
+   * the master `LUNORA_ADMIN_TOKEN` never rides the URL.
+   *
+   * Async because the admin fallback ({@link isAdminSocket}) verifies the
+   * ephemeral sub-token with WebCrypto HMAC.
    */
-  isUpgradeAllowed(request) {
+  async isUpgradeAllowed(request) {
     const env = this.env ?? {};
     const allowedOrigins = env.LUNORA_ALLOWED_ORIGINS;
     if (allowedOrigins && allowedOrigins.trim() !== "") {
@@ -3806,7 +6423,7 @@ class ShardDO {
     const expectedBearer = env.LUNORA_WS_BEARER;
     if (expectedBearer && expectedBearer.length > 0) {
       const supplied = this.suppliedWsToken(request);
-      if (!supplied || !constantTimeEqual(supplied, expectedBearer) && !this.isAdminSocket(request)) {
+      if (!supplied || !constantTimeEqual(supplied, expectedBearer) && !await this.isAdminSocket(request)) {
         return false;
       }
     }
@@ -3827,19 +6444,40 @@ class ShardDO {
     return new URL(request.url).searchParams.get("token") ?? void 0;
   }
   /**
-   * Whether the upgrade presented a token matching `LUNORA_ADMIN_TOKEN`,
-   * constant-time compared. Closed (returns `false`) when the admin token is
-   * unset, mirroring `isAdminAuthorized` for the HTTP path so admin
-   * streaming is opt-in rather than exposed by default.
+   * Whether the upgrade presented an admin credential: the master
+   * `LUNORA_ADMIN_TOKEN` (constant-time compared) or a short-lived sub-token
+   * the worker minted with it (`POST /_lunora/admin/ws-token` —
+   * HMAC-verified statelessly here, since both isolates hold the master token
+   * in `env`). The ephemeral token is what the studio sends in `?token=`, so
+   * the master credential stays out of URLs/logs. Closed (resolves `false`)
+   * when the admin token is unset, mirroring `isAdminAuthorized` for the HTTP
+   * path so admin streaming is opt-in rather than exposed by default.
+   *
+   * Enforcement: with `LUNORA_REQUIRE_EPHEMERAL_WS_TOKEN` set
+   * (`1`/`true`/`on`/`yes`/`enabled`), a raw master token in the
+   * `?token=` query parameter is rejected — the query string is exactly
+   * where it leaks. The `Authorization` header path still takes the master
+   * token: browsers can't set it on a WS upgrade, so it never rides a URL.
    */
-  isAdminSocket(request) {
+  async isAdminSocket(request) {
     const env = this.env ?? {};
     const adminToken = env.LUNORA_ADMIN_TOKEN;
     if (!adminToken || adminToken.length === 0) {
       return false;
     }
     const supplied = this.suppliedWsToken(request);
-    return supplied !== void 0 && constantTimeEqual(supplied, adminToken);
+    if (supplied === void 0) {
+      return false;
+    }
+    if (await verifyWsAdminToken(adminToken, supplied)) {
+      return true;
+    }
+    const fromQuery = extractBearerToken(request.headers.get("authorization")) === void 0;
+    const requireEphemeral = REQUIRE_EPHEMERAL_ENV_VALUES.has((env.LUNORA_REQUIRE_EPHEMERAL_WS_TOKEN ?? "").trim().toLowerCase());
+    if (fromQuery && requireEphemeral) {
+      return false;
+    }
+    return constantTimeEqual(supplied, adminToken);
   }
   /**
    * Register the hibernation-safe ping/pong keepalive. The runtime answers a
@@ -3858,10 +6496,34 @@ class ShardDO {
     }
     setter.call(this.state, new WebSocketRequestResponsePair(WS_KEEPALIVE_PING, WS_KEEPALIVE_PONG));
   }
-  handleWebSocketUpgrade(request) {
-    if (!this.isUpgradeAllowed(request)) {
+  /**
+   * 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;
+  }
+  async handleWebSocketUpgrade(request) {
+    if (!await this.isUpgradeAllowed(request)) {
       return new Response("Forbidden", { status: 403 });
     }
+    const admin = await this.isAdminSocket(request);
     const pair = new WebSocketPair();
     const client = pair[0];
     const server = pair[1];
@@ -3871,7 +6533,7 @@ class ShardDO {
     const expiresAtRaw = Number(request.headers.get("x-lunora-identity-exp"));
     const expiresAt = Number.isFinite(expiresAtRaw) && expiresAtRaw > 0 ? expiresAtRaw : void 0;
     server.serializeAttachment?.({
-      admin: this.isAdminSocket(request),
+      admin,
       connectionId: crypto.randomUUID(),
       subs: {},
       ...expiresAt === void 0 ? {} : { expiresAt },
@@ -3975,7 +6637,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 +6648,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) {