@lunora/do 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-XEs4csIH.mjs → ROOT_DO_SIZE_WARN_BYTES-CEVhBec2.mjs}

@@ -1,22 +1,25 @@
 import { drizzle } from 'drizzle-orm/durable-sqlite';
+import { e as encodeWire, a as awaitWsDrain, t as trySendFrame, d as decodeWire, s as subscriptionListDeltas, b as sendDeltaFrames } from './subscription-delivery-Z6nXHvQN.mjs';
 import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-DZEhUeyI.mjs';
 import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
 import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-PTtTiQ7U.mjs';
 import { SCAN_DEP, createDependencyTracker, tableFromDepKey } from './SCAN_DEP-DLJF8dsj.mjs';
 import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-import { ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, readTablePage, facetColumn, FLAGS_FUNCTION_PREFIX, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-D_UiYJFk.mjs';
+import { 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-fMl1vyt1.mjs';
 import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
 import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
 import { readBookmark, armRestore } from './armRestore-BJk53Ro8.mjs';
-import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-1hDydFyv.mjs';
+import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-BYlSGY0N.mjs';
+import { stableStringify } from './stableStringify-MydiuScU.mjs';
 import { redact, standardRules } from '@visulima/redact';
 import { i as isDevEnvironment, c as buildSettings, b as buildSecurityAudit } from './security-audit-CucgBice.mjs';
 import { runReadonlySql } from './MAX_SQL_ROWS-dDcFE1YZ.mjs';
-import { trySendFrame, subscriptionListDeltas, sendDeltaFrames } from './subscriptionListDeltas-ce84gpwL.mjs';
 import { ConflictError } from './ConflictError-C0STs6bU.mjs';
 import { e as deleteGlobalShapeSnapshotsForConnection, g as readIdempotent, h as writeIdempotent, t as trimIdempotent, r as readClientWatermark, m as migrateClientWatermark, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, f as readGlobalShapeSnapshot, w as writeGlobalShapeSnapshot } from './ctx-db-idempotency-BdcNpvY4.mjs';
 import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-DSycmnDf.mjs';
-import { s as selectShapeMemberIds, a as selectShapeRows } from './ctx-db-shapes-DVoeZpo-.mjs';
+import { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-BQapRFjB.mjs';
+
+const MAX_BATCH_ENTRIES = 500;
 
 const AUDIT_LOG_TABLE = "__lunora_audit__";
 const AUDIT_LOG_RETENTION = 1e3;
@@ -78,6 +81,38 @@ const readAuditLog = (sql, options = {}) => {
   });
 };
 
+const SHARED_BATCH_HEADERS = [
+  "x-lunora-userid",
+  "x-lunora-identity",
+  "x-d1-bookmark",
+  "x-lunora-client-ip",
+  "x-lunora-system",
+  "x-lunora-shard-binding"
+];
+const buildBatchEntryRequest = (batchRequest, entry) => {
+  const headers = new Headers({ "content-type": "application/json" });
+  for (const name of SHARED_BATCH_HEADERS) {
+    const value = batchRequest.headers.get(name);
+    if (value !== null) {
+      headers.set(name, value);
+    }
+  }
+  if (entry.mutationId !== void 0) {
+    headers.set("x-lunora-mutation-id", entry.mutationId);
+  }
+  if (entry.clientId !== void 0) {
+    headers.set("x-lunora-client-id", entry.clientId);
+  }
+  if (entry.clientSeq !== void 0) {
+    headers.set("x-lunora-client-seq", String(entry.clientSeq));
+  }
+  return new Request("https://shard.internal/rpc", {
+    body: JSON.stringify({ args: entry.args ?? {}, functionPath: entry.functionPath }),
+    headers,
+    method: "POST"
+  });
+};
+
 const QUERY_METRICS_TABLE = "__lunora_metrics_queries";
 const QUERY_METRICS_MAX_SQL_LEN = 512;
 const QUERY_METRICS_MAX_STATEMENTS = 500;
@@ -144,6 +179,714 @@ const readQueryMetrics = (sql) => {
   });
 };
 
+const RELAY_NAME_INFIX = "::relay::";
+const relayName = (ownerKey, index) => `${ownerKey}${RELAY_NAME_INFIX}${String(index)}`;
+const parseRelayName = (name) => {
+  const at = name.lastIndexOf(RELAY_NAME_INFIX);
+  if (at === -1) {
+    return void 0;
+  }
+  const ownerKey = name.slice(0, at);
+  const indexText = name.slice(at + RELAY_NAME_INFIX.length);
+  const relayIndex = Number(indexText);
+  if (ownerKey.length === 0 || !Number.isInteger(relayIndex) || relayIndex < 0 || String(relayIndex) !== indexText) {
+    return void 0;
+  }
+  return { ownerKey, relayIndex };
+};
+
+const shapeRoutingKey = (name, args) => stableStringify({ args: args ?? {}, name });
+const DEFAULT_PROMOTION_THRESHOLDS = { tUp: 8e3 };
+
+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 buildPokeFrames = (parts, meta) => {
+  const { baseCheckpoint, checkpoint, epoch, lastMutationId, pokeId } = meta;
+  const frames = [JSON.stringify({ baseCheckpoint, epoch, pokeId, type: "pokeStart" })];
+  for (const part of parts) {
+    const rowsPatch = part.rowsPatch.map((op) => op.value === void 0 ? op : { ...op, value: encodeWire(op.value) });
+    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 envPositiveInt = (env, key, fallback) => {
+  const raw = env?.[key];
+  let parsed = Number.NaN;
+  if (typeof raw === "string") {
+    parsed = Number.parseInt(raw, 10);
+  } else if (typeof raw === "number") {
+    parsed = raw;
+  }
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+};
+const RELAY_MULTICAST_IDENTITY = {};
+const assertNeverFrame = (frame) => {
+  throw new Error(`unhandled relay frame: ${JSON.stringify(frame)}`);
+};
+const asRelayNamespace = (value) => {
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const candidate = value;
+  return typeof candidate.idFromName === "function" && typeof candidate.get === "function" ? candidate : void 0;
+};
+const jsonRelayResponse = (body) => Response.json(body, { headers: { "content-type": "application/json" } });
+const noContent = () => new Response(null, { status: 204 });
+class RelayLink {
+  constructor(host, roleId) {
+    this.host = host;
+    this.roleId = roleId;
+  }
+  host;
+  roleId;
+  /**
+   * Serve the internal `/_lunora/relay` control channel: parse the frame, then
+   * dispatch to the role hooks. One exhaustive switch means a new frame type added
+   * to `relay.ts` without a case here is a COMPILE error, not a runtime mis-route.
+   */
+  async handleControl(request) {
+    let message;
+    try {
+      message = await request.json();
+    } catch {
+      return new Response("bad request", { status: 400 });
+    }
+    switch (message.type) {
+      case "relay_attach": {
+        this.onAttach(message.relayIndex);
+        return noContent();
+      }
+      case "relay_detach": {
+        this.onDetach(message.relayIndex);
+        return noContent();
+      }
+      case "relay_frame": {
+        this.host.deliverWhisperLocal(message.topic, message.frame, void 0);
+        await this.onWhisperFrame(message);
+        return noContent();
+      }
+      case "relay_shape_poke": {
+        const iterated = this.host.getWebSockets().length;
+        const startMs = Date.now();
+        const delivered = this.onShapePoke(message);
+        this.host.recordShapePokeFanout(iterated, delivered, Date.now() - startMs);
+        return noContent();
+      }
+      case "relay_shape_subscribe": {
+        return jsonRelayResponse(this.onShapeSubscribe(message));
+      }
+      default: {
+        return assertNeverFrame(message);
+      }
+    }
+  }
+  /** The hard cap on relays per shard (`LUNORA_MAX_RELAYS`) — a deployment constant the runtime surfaces in Studio as the cost ceiling. */
+  maxRelays() {
+    return envPositiveInt(this.host.env(), "LUNORA_MAX_RELAYS", DEFAULT_MAX_RELAYS);
+  }
+  /** Whether this DO can currently address its siblings (a namespace binding has been learned) — the relay tier is inert in single-DO mode. */
+  canAddressSiblings() {
+    return this.relayNamespace() !== void 0;
+  }
+  /** Resolve this DO's own namespace binding so it can address sibling owners/relays, or `undefined` when unknown. */
+  relayNamespace() {
+    const binding = this.host.shardBinding();
+    if (binding === void 0) {
+      return void 0;
+    }
+    return asRelayNamespace(this.host.env()?.[binding]);
+  }
+  /** POST a control frame to a sibling by name, fire-and-forget. Best-effort: a transient cross-DO failure drops the frame rather than throwing into the handler. */
+  async postRelayMessage(targetName, message) {
+    await this.requestRelayMessage(targetName, message);
+  }
+  /**
+   * POST a control frame to a sibling by name and return its response (the shape-seed
+   * path needs the owner's frames back). Best-effort: a transient cross-DO failure
+   * returns `undefined` rather than throwing.
+   * @returns the sibling's response, or `undefined` when it can't be reached
+   */
+  async requestRelayMessage(targetName, message) {
+    const namespace = this.relayNamespace();
+    if (namespace === void 0) {
+      return void 0;
+    }
+    const stub = typeof namespace.getByName === "function" ? namespace.getByName(targetName) : namespace.get(namespace.idFromName(targetName));
+    try {
+      return await stub.fetch("https://relay.internal/_lunora/relay", {
+        body: JSON.stringify(message),
+        headers: { "content-type": "application/json", "x-lunora-shard-binding": this.host.shardBinding() ?? "" },
+        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();
+  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). `0` keeps every connection on the owner. The owner promotes
+   * once its live socket count crosses `LUNORA_RELAY_THRESHOLD`, fanning to a fixed
+   * `LUNORA_RELAY_FAN` (capped by `LUNORA_MAX_RELAYS`, the cost ceiling).
+   */
+  relayCount() {
+    const threshold = envPositiveInt(this.host.env(), "LUNORA_RELAY_THRESHOLD", DEFAULT_PROMOTION_THRESHOLDS.tUp);
+    if (this.host.getWebSockets().length < threshold) {
+      return 0;
+    }
+    const maxRelays = envPositiveInt(this.host.env(), "LUNORA_MAX_RELAYS", DEFAULT_MAX_RELAYS);
+    const fan = envPositiveInt(this.host.env(), "LUNORA_RELAY_FAN", DEFAULT_RELAY_FAN);
+    return Math.min(maxRelays, Math.max(1, fan));
+  }
+  /**
+   * The RLS-uniform gate (plan 075 Phase 3, review-hardened): whether a reactive
+   * shape may be relay-multicast — i.e. one delta is correct for **every**
+   * subscriber. Fail-closed on four grounds — a static RLS read-policy guard, the
+   * anonymous multicast identity as the probe base, two `Proxy`-backed probes that
+   * yield a distinct value for ANY accessed claim (so any claim a `where` reads —
+   * even a custom one outside `rls()` — diverges), and a wholesale-copy backstop.
+   * Cached per `(name, args)`, whose uniformity is stable.
+   */
+  isShapeRelayUniform(name, args) {
+    const cacheKey = shapeRoutingKey(name, args);
+    const cached = this.shapeUniformCache.get(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const uniform = this.probeShapeRelayUniform(name, args);
+    this.shapeUniformCache.set(cacheKey, uniform);
+    return uniform;
+  }
+  onAttach(index) {
+    this.addRelayToSet(index);
+  }
+  onDetach(index) {
+    this.removeRelayFromSet(index);
+  }
+  async onWhisperFrame(message) {
+    await Promise.all(
+      [...this.ownerRelaySet()].filter((index) => index !== message.originRelay).map(
+        (index) => this.postRelayMessage(relayName(this.roleId.ownerKey, index), { frame: message.frame, topic: message.topic, type: "relay_frame" })
+      )
+    );
+  }
+  onShapeSubscribe(message) {
+    return this.buildShapeSeedFrames(message);
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: an owner doesn't receive multicast pokes (it sends them)
+  onShapePoke() {
+    return 0;
+  }
+  /**
+   * Owner side (slice B.2): for every registered relay-uniform shape whose table
+   * changed this flush, compute the membership diff ONCE over `(cohort cursor,
+   * frameCursor]` and multicast the `rowsPatch` to every relay. Advances the cohort
+   * cursor synchronously (before any await) so a seed interleaving during the
+   * multicast registers at `frameCursor` and is skipped by this in-flight poke.
+   */
+  async multicastShapePokes(changed, frameCursor) {
+    if (this.relayShapeRegistry.size === 0) {
+      return;
+    }
+    const relays = this.ownerRelaySet();
+    if (relays.size === 0) {
+      return;
+    }
+    const epoch = this.host.currentCdcEpoch();
+    const sends = [];
+    for (const entry of this.relayShapeRegistry.values()) {
+      let resolved;
+      try {
+        resolved = this.host.resolveShape(entry.name, entry.args, RELAY_MULTICAST_IDENTITY);
+      } catch {
+        continue;
+      }
+      if (resolved === void 0 || resolved.global === true || !changed.has(resolved.table)) {
+        continue;
+      }
+      const fromCursor = entry.cursor;
+      const rowsPatch = this.host.buildShapeDiff(resolved, fromCursor, frameCursor);
+      if (rowsPatch.length === 0) {
+        continue;
+      }
+      entry.cursor = frameCursor;
+      const poke = {
+        args: entry.args,
+        checkpoint: frameCursor,
+        epoch,
+        fromCursor,
+        name: entry.name,
+        rowsPatch,
+        type: "relay_shape_poke"
+      };
+      for (const index of relays) {
+        sends.push(this.postRelayMessage(relayName(this.roleId.ownerKey, index), poke));
+      }
+    }
+    await Promise.all(sends);
+  }
+  /**
+   * Owner side (review MEDIUM-3): for every NON-uniform relay-shape proxy whose
+   * table changed this flush, compute that one subscriber's diff over `(entry.cursor,
+   * frameCursor]` UNDER ITS OWN forwarded identity (RLS-correct) and deliver a
+   * `targetConnectionId`-addressed poke to just that socket's relay. Each entry
+   * tracks its own cursor — the diffs are identity-specific, no cohort sharing.
+   */
+  async proxyShapePokes(changed, frameCursor) {
+    if (this.relayShapeProxies.size === 0) {
+      return;
+    }
+    const epoch = this.host.currentCdcEpoch();
+    const sends = [];
+    for (const entry of this.relayShapeProxies.values()) {
+      let resolved;
+      try {
+        resolved = this.host.resolveShape(entry.name, entry.args, entry.identity);
+      } catch {
+        continue;
+      }
+      if (resolved === void 0 || resolved.global === true || !changed.has(resolved.table)) {
+        continue;
+      }
+      const fromCursor = entry.cursor;
+      const rowsPatch = this.host.buildShapeDiff(resolved, fromCursor, frameCursor);
+      if (rowsPatch.length === 0) {
+        continue;
+      }
+      entry.cursor = frameCursor;
+      const poke = {
+        args: entry.args,
+        checkpoint: frameCursor,
+        epoch,
+        fromCursor,
+        name: entry.name,
+        rowsPatch,
+        targetConnectionId: entry.connectionId,
+        type: "relay_shape_poke"
+      };
+      sends.push(this.postRelayMessage(relayName(this.roleId.ownerKey, entry.relayIndex), poke));
+    }
+    await Promise.all(sends);
+  }
+  /**
+   * Serialize a shape's seed poke frames for a relay to deliver verbatim. Resolves
+   * under the forwarded socket identity (so RLS applies exactly as for a local
+   * subscribe), self-heals the relay set, registers the shape for live updates
+   * (cohort multicast when uniform, per-socket proxy when not), and stamps the
+   * relay's cohort memo at the registry FRONTIER (not the global cursor) so a late
+   * joiner is never stranded. `lastMutationId` is omitted (relayed sockets are
+   * owner-served for custom mutators).
+   * @returns the serialized frames + the cohort-memo cursor, or an error
+   */
+  buildShapeSeedFrames(request) {
+    const identity = { identity: request.identity, userId: request.userId };
+    let resolved;
+    try {
+      resolved = this.host.resolveShape(request.name, request.args, identity);
+    } catch (error) {
+      return { error: { code: "SHAPE_RESOLVE_FAILED", message: error instanceof Error ? error.message : "shape resolve failed" } };
+    }
+    if (resolved === void 0 || resolved.global === true) {
+      return { error: { code: "SHAPE_NOT_FOUND", message: `shape not relayable: ${request.name}` } };
+    }
+    if (request.relayIndex !== void 0) {
+      this.addRelayToSet(request.relayIndex);
+    }
+    const { baseCheckpoint, cursor, epoch, rowsPatch } = this.host.computeOpLogShapeSeed(
+      { args: request.args, name: request.name, sinceEpoch: request.sinceEpoch, sinceSeq: request.sinceSeq },
+      resolved
+    );
+    let cohortCursor = cursor;
+    if (this.isShapeRelayUniform(request.name, request.args)) {
+      const routingKey = shapeRoutingKey(request.name, request.args);
+      let entry = this.relayShapeRegistry.get(routingKey);
+      if (entry === void 0) {
+        entry = { args: request.args, cursor, name: request.name };
+        this.relayShapeRegistry.set(routingKey, entry);
+      }
+      cohortCursor = entry.cursor;
+    } else if (request.relayIndex !== void 0 && request.connectionId !== void 0) {
+      this.relayShapeProxies.set(`${String(request.relayIndex)}:${request.connectionId}:${request.subId}`, {
+        args: request.args,
+        connectionId: request.connectionId,
+        cursor,
+        epoch,
+        identity,
+        name: request.name,
+        relayIndex: request.relayIndex,
+        subId: request.subId
+      });
+    }
+    const frames = buildPokeFrames([{ rowsPatch, shapeId: request.subId }], {
+      baseCheckpoint,
+      checkpoint: cursor,
+      epoch,
+      lastMutationId: void 0,
+      pokeId: this.host.nextPokeId()
+    });
+    return { cursor: cohortCursor, epoch, frames };
+  }
+  /** Ensure the reserved owner-side relay-set table exists (auto-hidden from the data browser by the `__lunora` prefix). */
+  ensureRelayTable() {
+    this.host.sql().exec("CREATE TABLE IF NOT EXISTS __lunora_relays (idx INTEGER PRIMARY KEY)");
+  }
+  /** The owner's active relay indices, hydrated once from `__lunora_relays` and cached for the synchronous forward path. */
+  ownerRelaySet() {
+    if (this.relaySetCache === void 0) {
+      this.ensureRelayTable();
+      const rows = this.host.sql().exec("SELECT idx FROM __lunora_relays").toArray();
+      this.relaySetCache = new Set(rows.map((row) => Number(row.idx)));
+    }
+    return this.relaySetCache;
+  }
+  /** Record a relay as active (idempotent), persisting it so the set survives the owner's hibernation. */
+  addRelayToSet(index) {
+    this.ensureRelayTable();
+    this.host.sql().exec("INSERT OR IGNORE INTO __lunora_relays (idx) VALUES (?)", index);
+    this.ownerRelaySet().add(index);
+  }
+  /** Drop a drained relay from the set and prune its dead per-socket proxy entries; on full drain, clear the (now dead) registry + uniform cache to bound growth. */
+  removeRelayFromSet(index) {
+    this.ensureRelayTable();
+    this.host.sql().exec("DELETE FROM __lunora_relays WHERE idx = ?", index);
+    const set = this.ownerRelaySet();
+    set.delete(index);
+    for (const [key, entry] of this.relayShapeProxies) {
+      if (entry.relayIndex === index) {
+        this.relayShapeProxies.delete(key);
+      }
+    }
+    if (set.size === 0) {
+      this.relayShapeRegistry.clear();
+      this.shapeUniformCache.clear();
+    }
+  }
+  /**
+   * The one-shot computation behind {@link OwnerRelay.isShapeRelayUniform}, made
+   * sound against the cross-identity row-leak (review). Resolves under the anonymous
+   * multicast identity (the base) plus two `Proxy`-backed identities that return a
+   * distinct value for ANY accessed claim, requires all to agree on table + where +
+   * columns, rejects any table with an RLS read policy or a masked projected column,
+   * 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.shapeColumnsMasked(base.table, base.columns)) {
+      return false;
+    }
+    const baseWhere = stableStringify(base.effectiveWhere);
+    const baseColumns = stableStringify(base.columns);
+    let enumerated = false;
+    const populate = (side) => {
+      const backing = { groups: [`grp_${side}`], roles: [side], sub: `__lunora_probe_${side}__` };
+      const claims = /* @__PURE__ */ new Proxy(backing, {
+        get: (target, key) => {
+          if (typeof key === "symbol" || key in target) {
+            return Reflect.get(target, key);
+          }
+          return `${side}:${key}`;
+        },
+        getOwnPropertyDescriptor: (target, key) => {
+          enumerated = true;
+          return Reflect.getOwnPropertyDescriptor(target, key);
+        },
+        has: (target, key) => typeof key === "symbol" ? Reflect.has(target, key) : true,
+        ownKeys: (target) => {
+          enumerated = true;
+          return Reflect.ownKeys(target);
+        }
+      });
+      return { identity: claims, userId: `__lunora_probe_${side}__` };
+    };
+    const matches = [RELAY_MULTICAST_IDENTITY, populate("a"), populate("b")].every((probe) => {
+      let resolved;
+      try {
+        resolved = this.host.resolveShape(name, args, probe);
+      } catch {
+        return false;
+      }
+      return resolved !== void 0 && resolved.global !== true && resolved.table === base.table && stableStringify(resolved.effectiveWhere) === baseWhere && stableStringify(resolved.columns) === baseColumns;
+    });
+    return matches && !enumerated;
+  }
+  /** Whether any column the shape projects from `table` is masked — a masked value is identity-dependent, so the shape can't be relay-uniform. */
+  shapeColumnsMasked(table, columns) {
+    const masked = this.host.maskMetadata().columns.filter((entry) => entry.table === table);
+    if (masked.length === 0) {
+      return false;
+    }
+    if (columns === void 0) {
+      return true;
+    }
+    const projected = new Set(columns);
+    return masked.some((entry) => projected.has(entry.column));
+  }
+}
+class RelayMember extends RelayLink {
+  /** `true` once this relay has announced itself to its owner this wake, so a hot socket churn doesn't re-attach on every subscribe. */
+  relayAnnounced = false;
+  /** Per-socket cohort memo `ws → subId → { cursor, epoch }`: the relay delivers a poke to a socket only while its memo matches the poke's `fromCursor`+`epoch`. */
+  shapeRelayMemos = /* @__PURE__ */ new WeakMap();
+  constructor(host, ownerKey, relayIndex) {
+    super(host, { ownerKey, relayIndex });
+  }
+  async forwardWhisper(topic, frame) {
+    if (!this.canAddressSiblings()) {
+      return;
+    }
+    await this.postRelayMessage(this.roleId.ownerKey, { frame, originRelay: this.roleId.relayIndex, topic, type: "relay_frame" });
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: a relay receives no writes, so it never flushes its own CDC
+  onFlush() {
+    return Promise.resolve();
+  }
+  /**
+   * Seed a shape held by a socket on this relay by forwarding the request to the
+   * owner: the owner resolves under this socket's verified identity and computes the
+   * seed frames, which the relay delivers verbatim. Returns a structured error
+   * (surfaced as a `shape_subscribe` error) when the owner can't be reached.
+   */
+  async seedRelayShape(ws, subId, shape, identity) {
+    if (!this.canAddressSiblings()) {
+      return { code: "RELAY_MISCONFIGURED", message: "relay cannot address its owner" };
+    }
+    await this.announce();
+    const request = {
+      args: shape.args ?? {},
+      connectionId: this.host.readAttachment(ws).connectionId,
+      identity: identity.identity,
+      name: shape.name,
+      relayIndex: this.roleId.relayIndex,
+      sinceEpoch: shape.sinceEpoch,
+      sinceSeq: shape.sinceSeq,
+      subId,
+      type: "relay_shape_subscribe",
+      userId: identity.userId
+    };
+    const response = await this.requestRelayMessage(this.roleId.ownerKey, request);
+    if (response === void 0) {
+      return { code: "RELAY_SEED_FAILED", message: "owner did not answer the shape seed" };
+    }
+    let seed;
+    try {
+      seed = await response.json();
+    } catch {
+      return { code: "RELAY_SEED_FAILED", message: "malformed shape seed from owner" };
+    }
+    if (seed.error !== void 0) {
+      return seed.error;
+    }
+    if (seed.frames === void 0) {
+      return { code: "RELAY_SEED_FAILED", message: "owner returned no shape frames" };
+    }
+    await awaitWsDrain(ws);
+    for (const frame of seed.frames) {
+      trySendFrame(ws, frame);
+    }
+    this.recordRelayShapeMemo(ws, subId, seed.cursor ?? 0, seed.epoch);
+    return "ok";
+  }
+  /** A relay announces itself to its owner (once per wake) on its first subscriber, retrying on a failed attach so a dropped frame can't strand its sockets (LOW-4). */
+  async announce() {
+    if (this.relayAnnounced || !this.canAddressSiblings()) {
+      return;
+    }
+    this.relayAnnounced = true;
+    const response = await this.requestRelayMessage(this.roleId.ownerKey, { relayIndex: this.roleId.relayIndex, type: "relay_attach" });
+    if (!response?.ok) {
+      this.relayAnnounced = false;
+    }
+  }
+  /** Once this relay loses its last socket (the `closing` one excluded), detach from the owner and re-arm the announce latch for a future subscriber. */
+  async announceDrain(closing) {
+    if (!this.canAddressSiblings()) {
+      return;
+    }
+    if (this.host.getWebSockets().some((ws) => ws !== closing)) {
+      return;
+    }
+    this.relayAnnounced = false;
+    await this.postRelayMessage(this.roleId.ownerKey, { relayIndex: this.roleId.relayIndex, type: "relay_detach" });
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: a relay never spreads connections (flat single tier)
+  relayCount() {
+    return 0;
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: the RLS-uniform gate is an owner concern
+  isShapeRelayUniform() {
+    return false;
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only an owner tracks a relay set
+  onAttach() {
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only an owner tracks a relay set
+  onDetach() {
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: only an owner re-distributes a forwarded whisper
+  onWhisperFrame() {
+    return Promise.resolve();
+  }
+  // eslint-disable-next-line class-methods-use-this -- role hook: a relay can't seed (no op-log) — the owner does
+  onShapeSubscribe() {
+    return { error: { code: "RELAY_CANNOT_SEED", message: "a relay has no op-log to seed from" } };
+  }
+  onShapePoke(poke) {
+    return this.deliverShapePoke(poke);
+  }
+  /** Record a relay socket's cohort cursor + epoch for `subId` (creating the per-socket map lazily). */
+  recordRelayShapeMemo(ws, subId, cursor, epoch) {
+    let memos = this.shapeRelayMemos.get(ws);
+    if (memos === void 0) {
+      memos = /* @__PURE__ */ new Map();
+      this.shapeRelayMemos.set(ws, memos);
+    }
+    memos.set(subId, { cursor, epoch });
+  }
+  /**
+   * Deliver an owner-multicast shape delta to this relay's cohort sockets. A socket
+   * receives it only while its memo matches the poke's `fromCursor` AND `epoch` (so a
+   * socket that seeded at a different cursor/epoch never double-applies), then
+   * advances to `checkpoint`. A targeted (per-socket proxy) poke goes ONLY to its one
+   * connection; a cohort multicast goes to every matching socket.
+   * @returns the number of sockets delivered to
+   */
+  deliverShapePoke(poke) {
+    const routingKey = shapeRoutingKey(poke.name, poke.args);
+    let delivered = 0;
+    for (const ws of this.host.getWebSockets()) {
+      const attachment = this.host.readAttachment(ws);
+      const { shapes } = attachment;
+      const memos = this.shapeRelayMemos.get(ws);
+      if (shapes === void 0 || memos === void 0) {
+        continue;
+      }
+      if (poke.targetConnectionId !== void 0 && attachment.connectionId !== poke.targetConnectionId) {
+        continue;
+      }
+      for (const [subId, sub] of Object.entries(shapes)) {
+        const memo = memos.get(subId);
+        if (memo?.cursor !== poke.fromCursor || memo.epoch !== poke.epoch || shapeRoutingKey(sub.name, sub.args) !== routingKey) {
+          continue;
+        }
+        const frames = buildPokeFrames([{ rowsPatch: poke.rowsPatch, shapeId: subId }], {
+          baseCheckpoint: void 0,
+          checkpoint: poke.checkpoint,
+          epoch: poke.epoch,
+          lastMutationId: void 0,
+          pokeId: this.host.nextPokeId()
+        });
+        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";
@@ -351,58 +1094,6 @@ const readRequestLog = (sql, options = {}) => {
   });
 };
 
-const projectColumns = (document_, columns) => {
-  if (!columns) {
-    return document_;
-  }
-  const projected = /* @__PURE__ */ Object.create(null);
-  for (const key of ["_id", "_creationTime", ...columns]) {
-    if (Object.hasOwn(document_, key)) {
-      projected[key] = document_[key];
-    }
-  }
-  return projected;
-};
-const diffGlobalMembership = (rows, previous, options) => {
-  const { columns, table } = options;
-  const next = /* @__PURE__ */ new Map();
-  const rowsPatch = [];
-  for (const { doc, id } of rows) {
-    const value = projectColumns(doc, columns);
-    const json = JSON.stringify(value);
-    next.set(id, json);
-    const before = previous.get(id);
-    if (before === void 0) {
-      rowsPatch.push({ key: id, op: "insert", table, value });
-    } else if (before !== json) {
-      rowsPatch.push({ key: id, op: "update", table, value });
-    }
-  }
-  for (const id of previous.keys()) {
-    if (!next.has(id)) {
-      rowsPatch.push({ key: id, op: "delete", table });
-    }
-  }
-  return { next, rowsPatch };
-};
-const buildPokeFrames = (parts, meta) => {
-  const { baseCheckpoint, checkpoint, epoch, lastMutationId, pokeId } = meta;
-  const frames = [JSON.stringify({ baseCheckpoint, epoch, pokeId, type: "pokeStart" })];
-  for (const part of parts) {
-    frames.push(
-      JSON.stringify({
-        pokeId,
-        rowsPatch: part.rowsPatch,
-        shapeId: part.shapeId,
-        type: "pokePart",
-        ...lastMutationId === void 0 ? {} : { lastMutationId }
-      })
-    );
-  }
-  frames.push(JSON.stringify({ checkpoint, epoch, pokeId, type: "pokeEnd" }));
-  return frames;
-};
-
 const runSocketPool = async (items, processOne, concurrency = 8) => {
   let cursor = 0;
   const worker = async () => {
@@ -491,19 +1182,6 @@ 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];
@@ -1246,6 +1924,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
@@ -1332,6 +2039,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. */
@@ -1341,8 +2071,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 });
@@ -1389,7 +2121,7 @@ class ShardDO {
       if (cached !== void 0) {
         return this.respondFromIdempotencyCache(payload.functionPath, dispatchStartedAt, mutatorClass, cached.value);
       }
-      const result = await this.handleRpc(payload.functionPath, payload.args ?? {});
+      const result = await this.handleRpc(payload.functionPath, decodeWire(payload.args ?? {}));
       this.recordPostDispatchBookkeeping(result, mutatorClass);
       if (mutatorClass?.kind === "next") {
         this.advanceClientMutationWatermark();
@@ -1400,7 +2132,7 @@ class ShardDO {
       const tablesWritten = [...this.pendingChangedTables ?? []];
       this.recordRequestLog(payload.functionPath, payload.args ?? {}, durationMs, "ok", tablesWritten);
       this.maybeWarnRootSize();
-      const response = this.buildDispatchResponse(mutatorClass, result);
+      const response = this.buildDispatchResponse(mutatorClass, encodeWire(result));
       await this.flushChangedTables();
       return response;
     } catch (error) {
@@ -1520,19 +2252,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;
     }
@@ -1574,6 +2310,7 @@ class ShardDO {
       }
     }
     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
@@ -1596,6 +2333,13 @@ class ShardDO {
       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();
     }
@@ -2322,7 +3066,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;
@@ -2705,6 +3449,16 @@ class ShardDO {
   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
@@ -2725,6 +3479,41 @@ class ShardDO {
   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
@@ -3133,11 +3922,74 @@ class ShardDO {
     if (error && typeof error === "object" && error.name === "LunoraError") {
       const lunoraError = error;
       const status = typeof lunoraError.status === "number" ? lunoraError.status : 500;
-      return jsonResponse({ error: { code: lunoraError.code ?? "INTERNAL", message: lunoraError.message ?? "internal error" } }, status);
+      const body = {
+        code: lunoraError.code ?? "INTERNAL",
+        message: lunoraError.message ?? "internal error"
+      };
+      if (lunoraError.data !== void 0) {
+        body.data = encodeWire(lunoraError.data);
+      }
+      return jsonResponse({ error: body }, status);
     }
     console.error("[@lunora/do] unhandled RPC error:", error);
     return jsonResponse({ error: { code: "RPC_FAILED", message: "internal error" } }, 500);
   }
+  /**
+   * Batch dispatch (plan 088). Applies each `calls[]` entry through the SAME
+   * single-call `/rpc` path (via a nested `this.fetch`), **sequentially**, so
+   * the per-`(identity, mutationId)` idempotency dedup and the per-client
+   * `__client_watermark` ordering are enforced entry-by-entry exactly as for an
+   * individual call — no duplication of the dispatch core, no reordering.
+   *
+   * Failures are **per-slot, not fail-fast**: an entry that throws (or a
+   * custom-mutator `OUT_OF_ORDER` gap) is captured in its own result slot and
+   * later entries still run. Ordering is still safe — a later same-client
+   * mutator after a gap re-classifies as a gap too (the watermark never
+   * advanced), so it cannot apply out of order; unrelated entries/queries are
+   * independent. The response is `{ results: [{ id, status, body }] }` in
+   * request order; each `body` is the untouched single-call envelope (its
+   * `result` already wire-encoded), so the client demuxes + decodes each
+   * exactly as one call.
+   */
+  async handleBatchRpc(request) {
+    let payload;
+    try {
+      payload = await request.json();
+    } catch {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: "invalid JSON body" } }, 400);
+    }
+    if (!Array.isArray(payload.calls)) {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: "batch `calls` must be an array" } }, 400);
+    }
+    if (payload.calls.length > MAX_BATCH_ENTRIES) {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: `batch exceeds the ${String(MAX_BATCH_ENTRIES)}-call limit` } }, 400);
+    }
+    const results = [];
+    let latestBookmark;
+    for (const raw of payload.calls) {
+      const outcome = await this.dispatchBatchEntry(request, raw);
+      if (outcome.bookmark !== void 0) {
+        latestBookmark = outcome.bookmark;
+      }
+      results.push({ body: outcome.body, id: outcome.id, status: outcome.status });
+    }
+    return jsonResponse({ results }, 200, latestBookmark);
+  }
+  /** Dispatch one batch entry through the single-call `/rpc` path and capture its envelope (plan 088). */
+  async dispatchBatchEntry(batchRequest, entry) {
+    try {
+      const response = await this.fetch(buildBatchEntryRequest(batchRequest, entry));
+      return { body: await response.json(), bookmark: response.headers.get("x-d1-bookmark") ?? void 0, id: entry.id, status: response.status };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        body: { error: { code: "BATCH_ENTRY_FAILED", message } },
+        bookmark: void 0,
+        id: entry?.id,
+        status: 500
+      };
+    }
+  }
   /**
    * Serve a reserved admin-introspection RPC (`__lunora_admin__:*`) for the
    * data browser. Gated by `env.LUNORA_ADMIN_TOKEN`: introspection is
@@ -3748,6 +4600,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() };
     }
@@ -3790,6 +4645,28 @@ 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. Read-only: touches no SQLite and mutates
+   * no socket state.
+   */
+  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) {
@@ -4062,7 +4939,7 @@ 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" }));
@@ -4145,7 +5022,11 @@ class ShardDO {
         this.pendingRefreshTables = void 0;
         const frameCursor = this.currentCdcCursor();
         const frameEpoch = this.currentCdcEpoch();
-        await Promise.all([this.refreshSubscriptions(batch), this.pokeShapeSubscribers(batch, frameCursor, frameEpoch)]);
+        await Promise.all([
+          this.refreshSubscriptions(batch),
+          this.pokeShapeSubscribers(batch, frameCursor, frameEpoch),
+          this.relay?.onFlush(batch, frameCursor ?? 0)
+        ]);
         batch = this.pendingRefreshTables;
       }
     } finally {
@@ -4346,6 +5227,10 @@ class ShardDO {
   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);
@@ -4378,17 +5263,32 @@ class ShardDO {
    * 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);
-    await awaitWsDrain(ws);
-    if (this.sendPoke(ws, [{ rowsPatch, shapeId: subId }], cursor, epoch, canResume ? shape.sinceSeq : void 0)) {
-      this.recordShapeMemo(ws, subId, cursor);
-    }
-    return "ok";
+    return { baseCheckpoint: canResume ? shape.sinceSeq : void 0, cursor, epoch, rowsPatch };
   }
   /**
    * Fan the membership diff of every shape affected by this flush to its
@@ -4405,6 +5305,7 @@ class ShardDO {
     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);
@@ -4424,6 +5325,7 @@ class ShardDO {
         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);
             }
@@ -4432,7 +5334,9 @@ class ShardDO {
       } 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
@@ -4828,7 +5732,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
@@ -4855,7 +5759,7 @@ 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;
@@ -4957,6 +5861,29 @@ class ShardDO {
     }
     setter.call(this.state, new WebSocketRequestResponsePair(WS_KEEPALIVE_PING, WS_KEEPALIVE_PONG));
   }
+  /**
+   * Route the non-RPC requests `fetch` handles before the shard-local RPC
+   * endpoint: a WebSocket upgrade, and the internal `/_lunora/relay` owner↔relay
+   * control channel (never reachable by a client — the runtime forwards only
+   * worker-internal traffic there). Returns `undefined` for an RPC request, which
+   * `fetch` then dispatches.
+   * @returns the routed response, or `undefined` when this is an RPC request
+   */
+  async routeNonRpc(url, request) {
+    if (url.pathname === "/_lunora/relay" && request.method === "POST") {
+      return this.relay ? await this.relay.handleControl(request) : new Response("relay tier inactive", { status: 404 });
+    }
+    if (url.pathname === "/_lunora/route" && request.method === "GET") {
+      return jsonResponse({ relayCount: this.relay?.relayCount() ?? 0 });
+    }
+    if (url.pathname === "/rpc-batch" && request.method === "POST") {
+      return this.handleBatchRpc(request);
+    }
+    if (request.headers.get("Upgrade") === "websocket") {
+      return this.handleWebSocketUpgrade(request);
+    }
+    return void 0;
+  }
   handleWebSocketUpgrade(request) {
     if (!this.isUpgradeAllowed(request)) {
       return new Response("Forbidden", { status: 403 });
@@ -5074,7 +6001,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;
     }
@@ -5085,12 +6012,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;
       }
       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) {