@lunora/do 0.0.0 → 1.0.0-alpha.1

package/dist/packem_shared/ROOT_DO_SIZE_WARN_BYTES-DQkmGiCS.mjs

@@ -0,0 +1,4009 @@
+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 { 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 { 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 { 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';
+
+const AUDIT_LOG_TABLE = "__lunora_audit__";
+const AUDIT_LOG_RETENTION = 1e3;
+const runSql$2 = (sql, query, ...params) => {
+  const runner = sql.exec;
+  return runner.call(sql, query, ...params);
+};
+const ensureAuditTable = (sql) => {
+  runSql$2(
+    sql,
+    `CREATE TABLE IF NOT EXISTS "${AUDIT_LOG_TABLE}" (
+            seq INTEGER PRIMARY KEY AUTOINCREMENT,
+            ts REAL NOT NULL,
+            op TEXT NOT NULL,
+            "table" TEXT,
+            id TEXT,
+            detail TEXT
+        )`
+  );
+};
+const appendAuditEntry = (sql, entry) => {
+  ensureAuditTable(sql);
+  runSql$2(
+    sql,
+    `INSERT INTO "${AUDIT_LOG_TABLE}" (ts, op, "table", id, detail) VALUES (?, ?, ?, ?, ?)`,
+    entry.ts,
+    entry.op,
+    // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for an op with no associated table/id/detail.
+    entry.table ?? null,
+    // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for an op with no associated table/id/detail.
+    entry.id ?? null,
+    // 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);
+};
+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(
+    sql,
+    `SELECT seq, ts, op, "table", id, detail FROM "${AUDIT_LOG_TABLE}" WHERE seq > ? ORDER BY seq DESC LIMIT ?`,
+    sinceSeq,
+    limit
+  ).toArray();
+  return rows.map((row) => {
+    const base = { op: row.op, seq: row.seq, ts: row.ts };
+    if (row.table !== null) {
+      base.table = row.table;
+    }
+    if (row.id !== null) {
+      base.id = row.id;
+    }
+    if (row.detail !== null) {
+      base.detail = JSON.parse(row.detail);
+    }
+    return base;
+  });
+};
+
+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 runner = sql.exec;
+  return runner.call(sql, query, ...params);
+};
+const normalizeSql = (sql) => {
+  let normalized = sql.replaceAll(/'(?:[^']|'')*'/g, "?").replaceAll(/\b0x[\da-f]+\b/gi, "?").replaceAll(/(?<=[=,([\s])\d+(?:\.\d+)?/g, "?").replaceAll(/\s+/g, " ").trim();
+  if (normalized.length > QUERY_METRICS_MAX_SQL_LEN) {
+    normalized = `${normalized.slice(0, QUERY_METRICS_MAX_SQL_LEN - 1)}…`;
+  }
+  return normalized;
+};
+const ensureQueryMetricsTable = (sql) => {
+  runSql$1(
+    sql,
+    `CREATE TABLE IF NOT EXISTS "${QUERY_METRICS_TABLE}" (
+            normalized_sql TEXT PRIMARY KEY,
+            exec_count     INTEGER NOT NULL DEFAULT 0,
+            total_duration_ms REAL NOT NULL DEFAULT 0,
+            rows_read      INTEGER NOT NULL DEFAULT 0,
+            rows_written   INTEGER NOT NULL DEFAULT 0
+        )`
+  );
+};
+const recordQueryMetric = (sql, rawSql, durationMs, rowsRead, rowsWritten) => {
+  const normalized = normalizeSql(rawSql);
+  if (normalized.length === 0) {
+    return;
+  }
+  ensureQueryMetricsTable(sql);
+  const countRow = runSql$1(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();
+    if (existing.c === 0) {
+      return;
+    }
+  }
+  const upsertSql = `INSERT INTO "${QUERY_METRICS_TABLE}" (normalized_sql, exec_count, total_duration_ms, rows_read, rows_written)
+         VALUES (?, 1, ?, ?, ?)
+         ON CONFLICT(normalized_sql) DO UPDATE SET
+             exec_count = exec_count + 1,
+             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);
+};
+const readQueryMetrics = (sql) => {
+  ensureQueryMetricsTable(sql);
+  const rows = runSql$1(
+    sql,
+    `SELECT normalized_sql, exec_count, total_duration_ms, rows_read, rows_written FROM "${QUERY_METRICS_TABLE}" ORDER BY total_duration_ms DESC`
+  ).toArray();
+  return rows.map((row) => {
+    return {
+      execCount: row.exec_count,
+      normalizedSql: row.normalized_sql,
+      rowsRead: row.rows_read,
+      rowsWritten: row.rows_written,
+      totalDurationMs: row.total_duration_ms
+    };
+  });
+};
+
+const REQUEST_LOG_TABLE = "__lunora_reqlog__";
+const REQUEST_LOG_RETENTION = 1e3;
+const REQUEST_LOG_EVENT_SOURCE = "lunora";
+const runSql = (sql, query, ...params) => {
+  const runner = sql.exec;
+  return runner.call(sql, query, ...params);
+};
+const redactArgs = (value, captureRaw = false) => {
+  if (captureRaw || value === null || value === void 0) {
+    return value;
+  }
+  return redact(value, standardRules);
+};
+const ensureRequestLogTable = (sql) => {
+  runSql(
+    sql,
+    `CREATE TABLE IF NOT EXISTS "${REQUEST_LOG_TABLE}" (
+            seq INTEGER PRIMARY KEY AUTOINCREMENT,
+            ts REAL NOT NULL,
+            function_path TEXT NOT NULL,
+            shard_key TEXT,
+            user_id TEXT,
+            identity TEXT,
+            args TEXT,
+            outcome TEXT NOT NULL,
+            error_message TEXT,
+            duration_ms REAL NOT NULL,
+            tables_read TEXT NOT NULL DEFAULT '[]',
+            tables_written TEXT NOT NULL DEFAULT '[]',
+            cache_hit INTEGER,
+            subscriptions_rerun INTEGER NOT NULL DEFAULT 0
+        )`
+  );
+};
+const encodeTables = (tables) => JSON.stringify([...new Set(tables)].toSorted((a, b) => a.localeCompare(b)));
+const cacheHitColumn = (cacheHit) => {
+  if (cacheHit === void 0) {
+    return null;
+  }
+  return cacheHit ? 1 : 0;
+};
+const appendRequestLogEntry = (sql, entry, options = {}) => {
+  ensureRequestLogTable(sql);
+  const captureRaw = options.captureRaw ?? false;
+  const retention = options.retention ?? REQUEST_LOG_RETENTION;
+  runSql(
+    sql,
+    `INSERT INTO "${REQUEST_LOG_TABLE}"
+            (ts, function_path, shard_key, user_id, identity, args, outcome, error_message, duration_ms, tables_read, tables_written, cache_hit, subscriptions_rerun)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    entry.ts,
+    entry.functionPath,
+    // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for a request with no shard key / anonymous caller / absent field.
+    entry.shardKey ?? null,
+    // eslint-disable-next-line unicorn/no-null -- anonymous request: no acting user.
+    entry.userId ?? null,
+    // Identity claims (email/name/roles) are PII, so they're redacted by
+    // default exactly like args — keeping the envelope's shape for the
+    // studio while keeping raw PII out of the durable log. The opaque
+    // `user_id` column above stays raw; it's the non-PII correlation key the
+    // `getRequestLog` filters key on.
+    // eslint-disable-next-line unicorn/no-null -- anonymous request or no claims attached.
+    entry.identity === void 0 ? null : JSON.stringify(redactArgs(entry.identity, captureRaw)),
+    // eslint-disable-next-line unicorn/no-null -- no args were sent on this dispatch.
+    entry.redactedArgs === void 0 ? null : JSON.stringify(redactArgs(entry.redactedArgs, captureRaw)),
+    entry.outcome,
+    // eslint-disable-next-line unicorn/no-null -- success path: no error message.
+    entry.errorMessage ?? null,
+    entry.durationMs,
+    encodeTables(entry.tablesRead),
+    encodeTables(entry.tablesWritten),
+    cacheHitColumn(entry.cacheHit),
+    entry.subscriptionsReRun ?? 0
+  );
+  runSql(sql, `DELETE FROM "${REQUEST_LOG_TABLE}" WHERE seq <= (SELECT MAX(seq) - ? FROM "${REQUEST_LOG_TABLE}")`, retention);
+};
+const emitRequestLogEvent = (entry, options = {}) => {
+  const captureRaw = options.captureRaw ?? false;
+  const event = {
+    args: entry.redactedArgs === void 0 ? void 0 : redactArgs(entry.redactedArgs, captureRaw),
+    cacheHit: entry.cacheHit,
+    durationMs: entry.durationMs,
+    error: entry.errorMessage,
+    function: entry.functionPath,
+    identity: entry.identity === void 0 ? void 0 : redactArgs(entry.identity, captureRaw),
+    outcome: entry.outcome,
+    shard: entry.shardKey,
+    source: REQUEST_LOG_EVENT_SOURCE,
+    tablesRead: entry.tablesRead ?? [],
+    tablesWritten: entry.tablesWritten ?? [],
+    ts: entry.ts,
+    type: "request",
+    userId: entry.userId
+  };
+  const line = JSON.stringify(event);
+  if (entry.outcome === "error") {
+    console.error(line);
+  } else {
+    console.log(line);
+  }
+};
+const LOG_EVENT_TYPE = "log";
+const renderLogMessage = (args) => args.map((value) => {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    const json = JSON.stringify(value);
+    return json ?? String(value);
+  } catch {
+    return String(value);
+  }
+}).join(" ");
+const emitLogEvent = (input) => {
+  const line = JSON.stringify({
+    function: input.functionPath,
+    level: input.level,
+    message: input.message,
+    shard: input.shardKey,
+    source: REQUEST_LOG_EVENT_SOURCE,
+    ts: input.ts,
+    type: LOG_EVENT_TYPE,
+    userId: input.userId
+  });
+  if (input.level === "error") {
+    console.error(line);
+  } else if (input.level === "warn") {
+    console.warn(line);
+  } else {
+    console.log(line);
+  }
+};
+const escapeLike = (value) => value.replaceAll(/[\\%_]/g, (character) => `\\${character}`);
+const decodeTables = (text) => {
+  try {
+    const value = JSON.parse(text);
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+  } catch {
+    return [];
+  }
+};
+const readRequestLog = (sql, options = {}) => {
+  ensureRequestLogTable(sql);
+  const limit = Math.max(1, Math.min(options.limit ?? REQUEST_LOG_RETENTION, 1e4));
+  const conjuncts = ["seq > ?"];
+  const parameters = [options.sinceSeq ?? 0];
+  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);
+  }
+  if (options.outcome !== void 0) {
+    conjuncts.push("outcome = ?");
+    parameters.push(options.outcome);
+  }
+  if (options.tableTouched !== void 0 && options.tableTouched !== "") {
+    const needle = `%${escapeLike(JSON.stringify(options.tableTouched))}%`;
+    conjuncts.push(String.raw`(tables_read LIKE ? ESCAPE '\' OR tables_written LIKE ? ESCAPE '\')`);
+    parameters.push(needle, needle);
+  }
+  parameters.push(limit);
+  const rows = runSql(
+    sql,
+    `SELECT seq, ts, function_path, shard_key, user_id, identity, args, outcome, error_message, duration_ms, tables_read, tables_written, cache_hit, subscriptions_rerun
+         FROM "${REQUEST_LOG_TABLE}" WHERE ${conjuncts.join(" AND ")} ORDER BY seq DESC LIMIT ?`,
+    ...parameters
+  ).toArray();
+  return rows.map((row) => {
+    const base = {
+      durationMs: row.duration_ms,
+      functionPath: row.function_path,
+      outcome: row.outcome === "error" ? "error" : "ok",
+      seq: row.seq,
+      subscriptionsReRun: row.subscriptions_rerun,
+      tablesRead: decodeTables(row.tables_read),
+      tablesWritten: decodeTables(row.tables_written),
+      ts: row.ts
+    };
+    if (row.shard_key !== null) {
+      base.shardKey = row.shard_key;
+    }
+    if (row.user_id !== null) {
+      base.userId = row.user_id;
+    }
+    if (row.identity !== null) {
+      base.identity = JSON.parse(row.identity);
+    }
+    if (row.args !== null) {
+      base.redactedArgs = JSON.parse(row.args);
+    }
+    if (row.error_message !== null) {
+      base.errorMessage = row.error_message;
+    }
+    if (row.cache_hit !== null) {
+      base.cacheHit = row.cache_hit === 1;
+    }
+    return base;
+  });
+};
+
+const DANGLING_SCAN_CAP = 5e3;
+const DANGLING_RESULT_CAP = 500;
+const DOC_COLUMN = "__doc__";
+const isInternalTable = (name) => name.startsWith("sqlite_") || name.startsWith("_cf_") || name.startsWith("__miniflare") || name.startsWith("__lunora") || name.includes("__fts_");
+const quoteIdentifier = (name) => `"${name.replaceAll('"', '""')}"`;
+const tableExists = (sql, table) => {
+  if (isInternalTable(table)) {
+    return false;
+  }
+  return sql.exec("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1", table).toArray().length > 0;
+};
+const resolveColumnExpression = (column, physicalColumns) => {
+  const isPhysical = physicalColumns.includes(column);
+  const isDocumentStored = physicalColumns.includes(DOC_COLUMN);
+  if (!isPhysical && !isDocumentStored) {
+    return void 0;
+  }
+  return isPhysical ? { expression: quoteIdentifier(column), params: [] } : { expression: `json_extract(${quoteIdentifier(DOC_COLUMN)}, ?)`, params: [`$."${column.replaceAll('"', '""')}"`] };
+};
+const scanColumnForDangling = (sql, quoted, table, column, physicalColumns, live, accumulator) => {
+  const resolved = resolveColumnExpression(column, physicalColumns);
+  if (resolved === void 0) {
+    return;
+  }
+  const rows = sql.exec(
+    `SELECT id, ${resolved.expression} AS ref FROM ${quoted} WHERE ${resolved.expression} IS NOT NULL AND ${resolved.expression} <> '' LIMIT ?`,
+    ...resolved.params,
+    ...resolved.params,
+    ...resolved.params,
+    DANGLING_SCAN_CAP + 1
+  ).toArray();
+  if (rows.length > DANGLING_SCAN_CAP) {
+    accumulator.truncated = true;
+  }
+  for (const row of rows.slice(0, DANGLING_SCAN_CAP)) {
+    accumulator.scanned += 1;
+    if (live.has(row.ref)) {
+      continue;
+    }
+    if (accumulator.references.length >= DANGLING_RESULT_CAP) {
+      accumulator.truncated = true;
+      continue;
+    }
+    accumulator.references.push({ column, id: row.id, key: row.ref, table });
+  }
+};
+const findDanglingReferences = (sql, storageColumns, liveKeys) => {
+  const live = liveKeys instanceof Set ? liveKeys : new Set(liveKeys);
+  const accumulator = { references: [], scanned: 0, truncated: false };
+  for (const [table, columns] of Object.entries(storageColumns)) {
+    if (!tableExists(sql, table)) {
+      continue;
+    }
+    const quoted = quoteIdentifier(table);
+    const physicalColumns = sql.exec(`PRAGMA table_info(${quoted})`).toArray().map((column) => column.name);
+    for (const column of columns) {
+      scanColumnForDangling(sql, quoted, table, column, physicalColumns, live, accumulator);
+    }
+  }
+  return accumulator;
+};
+
+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 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];
+  for (const value of small) {
+    if (large.has(value)) {
+      return true;
+    }
+  }
+  return false;
+};
+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 });
+  }
+  return {
+    batchSize: typeof args["batchSize"] === "number" ? args["batchSize"] : void 0,
+    direction: args["direction"] === "down" ? "down" : "up",
+    dryRun: args["dryRun"] === true,
+    id,
+    maxBatches: typeof args["maxBatches"] === "number" ? args["maxBatches"] : void 0
+  };
+};
+const SHARD_BULK_DELETE_CAP = MAX_PAGE_SIZE;
+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 });
+  }
+  if (table.trim() === "") {
+    throw Object.assign(new Error("writeRow: `table` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  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 });
+  }
+  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 });
+  }
+  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 });
+  }
+  const id = typeof args["id"] === "string" && args["id"] !== "" ? args["id"] : void 0;
+  return { exportName, id, params: args["params"] };
+};
+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 });
+  }
+  if (id === "") {
+    throw Object.assign(new Error("getWorkflowInstanceStatus: `id` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  return { exportName, id };
+};
+const WORKFLOW_INSTANCE_STATES = /* @__PURE__ */ new Set([
+  "complete",
+  "errored",
+  "paused",
+  "queued",
+  "running",
+  "terminated",
+  "unknown",
+  "waiting",
+  "waitingForPause"
+]);
+const toWorkflowInstanceState = (raw) => typeof raw === "string" && WORKFLOW_INSTANCE_STATES.has(raw) ? raw : "unknown";
+const toWorkflowInstanceError = (raw) => {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const { message, name } = raw;
+  return { message: typeof message === "string" ? message : "", name: typeof name === "string" ? name : "Error" };
+};
+const FILTER_OPERATORS = /* @__PURE__ */ new Set(["contains", "eq", "gt", "gte", "lt", "lte", "ne"]);
+const parseTablePageFilters = (raw) => {
+  if (!Array.isArray(raw)) {
+    return void 0;
+  }
+  const clauses = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) {
+      continue;
+    }
+    const record = item;
+    const { column, operator } = record;
+    if (typeof column !== "string" || column === "" || typeof operator !== "string" || !FILTER_OPERATORS.has(operator)) {
+      continue;
+    }
+    clauses.push({ column, operator, value: record["value"] });
+  }
+  return clauses.length > 0 ? clauses : void 0;
+};
+const parseTablePageOrderBy = (raw) => {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const { column, direction } = raw;
+  if (typeof column !== "string" || column === "") {
+    return void 0;
+  }
+  return { column, direction: direction === "desc" ? "desc" : "asc" };
+};
+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 });
+  }
+  return {
+    filters: parseTablePageFilters(args["filters"]),
+    limit: typeof args["limit"] === "number" ? args["limit"] : void 0,
+    search: typeof args["search"] === "string" ? args["search"] : void 0,
+    table
+  };
+};
+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 });
+  }
+  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 });
+  }
+  return { outcome };
+};
+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 });
+  }
+  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
+    });
+  }
+  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();
+  return {
+    functionPath: `container:${container}`,
+    level,
+    message: detail === void 0 || detail === "" ? event : `${event}: ${detail}`,
+    timestamp
+  };
+};
+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 });
+  }
+  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 });
+  }
+  if (userId.trim() === "") {
+    throw Object.assign(new Error("runAs: `userId` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  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 });
+  }
+  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 });
+  }
+  return {
+    args: rawArgs === void 0 ? {} : rawArgs,
+    functionPath,
+    userId,
+    ...rawIdentity === void 0 ? {} : { identity: rawIdentity }
+  };
+};
+const parseRecordMailArgs = (args) => {
+  const bad = (message) => {
+    throw Object.assign(new Error(`recordMail: ${message}`), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  };
+  const { bcc, cc, from, headers, html, replyTo, subject, text, to } = args;
+  if (typeof subject !== "string") {
+    bad("`subject` must be a string");
+  }
+  const toOk = typeof to === "string" || Array.isArray(to) && to.every((entry) => typeof entry === "string");
+  if (!toOk) {
+    bad("`to` must be a string or string[]");
+  }
+  const optionalStringList = (value, label) => {
+    if (value === void 0) {
+      return void 0;
+    }
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+      bad(`\`${label}\` must be a string[]`);
+    }
+    return value;
+  };
+  const optionalString = (value, label) => {
+    if (value !== void 0 && typeof value !== "string") {
+      bad(`\`${label}\` must be a string`);
+    }
+    return value;
+  };
+  return {
+    bcc: optionalStringList(bcc, "bcc"),
+    cc: optionalStringList(cc, "cc"),
+    from: optionalString(from, "from"),
+    headers: headers !== void 0 && typeof headers === "object" && headers !== null ? headers : void 0,
+    html: optionalString(html, "html"),
+    replyTo: optionalString(replyTo, "replyTo"),
+    subject,
+    text: optionalString(text, "text"),
+    to
+  };
+};
+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 });
+  }
+  const recipient = to ?? TEST_MAIL_DEFAULT_TO;
+  const link = "https://example.test/verify?token=demo";
+  return {
+    from: "Lunora <noreply@lunora.sh>",
+    html: `<p>This is a test email from the Lunora dev mail catcher.</p><p><a href="${link}">Verify your email</a></p>`,
+    subject: "Lunora test email",
+    text: `This is a test email from the Lunora dev mail catcher.
+
+Verify your email: ${link}`,
+    to: recipient
+  };
+};
+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 });
+  }
+  if (index.trim() === "") {
+    throw Object.assign(new Error("rankBefore: `index` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  if (typeof args["partitionKey"] !== "string") {
+    throw Object.assign(new Error("rankBefore: `partitionKey` must be a string"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  if (rowId.trim() === "") {
+    throw Object.assign(new Error("rankBefore: `rowId` is required"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  if (!Array.isArray(args["sortValues"])) {
+    throw Object.assign(new Error("rankBefore: `sortValues` must be an array"), { code: "BAD_REQUEST", name: "LunoraError", status: 400 });
+  }
+  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 });
+};
+const requireNonEmptyString = (value, field) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    badRequest(`rankPage: \`${field}\` is required`);
+  }
+  return value;
+};
+const parseRankPageAfter = (raw) => {
+  if (raw === void 0) {
+    return void 0;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    badRequest("rankPage: `after` must be an object");
+  }
+  const record = raw;
+  if (typeof record["partitionKey"] !== "string" || typeof record["rowId"] !== "string" || !Array.isArray(record["sortValues"])) {
+    badRequest("rankPage: `after` must have a string partitionKey, string rowId, and array sortValues");
+  }
+  return { partitionKey: record["partitionKey"], rowId: record["rowId"], sortValues: record["sortValues"] };
+};
+const parseRankPageArgs = (args) => {
+  const table = requireNonEmptyString(args["table"], "table");
+  const index = requireNonEmptyString(args["index"], "index");
+  if (args["take"] !== void 0 && typeof args["take"] !== "number") {
+    badRequest("rankPage: `take` must be a number");
+  }
+  if (args["cursor"] !== void 0 && args["cursor"] !== null && typeof args["cursor"] !== "string") {
+    badRequest("rankPage: `cursor` must be a string or null");
+  }
+  if (args["partitionKey"] !== void 0 && typeof args["partitionKey"] !== "string") {
+    badRequest("rankPage: `partitionKey` must be a string");
+  }
+  if (args["directions"] !== void 0 && !Array.isArray(args["directions"])) {
+    badRequest("rankPage: `directions` must be an array");
+  }
+  const directions = args["directions"] === void 0 ? void 0 : args["directions"].map((d) => d === "desc" ? "desc" : "asc");
+  return {
+    after: parseRankPageAfter(args["after"]),
+    cursor: typeof args["cursor"] === "string" ? args["cursor"] : void 0,
+    directions,
+    index,
+    partitionKey: typeof args["partitionKey"] === "string" ? args["partitionKey"] : void 0,
+    take: typeof args["take"] === "number" ? args["take"] : void 0,
+    table
+  };
+};
+const decodeIndexHitKey = (key) => {
+  try {
+    const parsed = JSON.parse(key);
+    if (Array.isArray(parsed) && typeof parsed[0] === "string" && typeof parsed[1] === "string") {
+      return { index: parsed[1], table: parsed[0] };
+    }
+  } catch {
+  }
+  return void 0;
+};
+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 });
+  }
+  const changes = raw.map((entry, index) => {
+    const record = entry;
+    const { op } = record;
+    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
+      });
+    }
+    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
+      });
+    }
+    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
+      });
+    }
+    return {
+      doc: document,
+      id,
+      op,
+      seq: typeof record["seq"] === "number" ? record["seq"] : 0,
+      table,
+      ts: typeof record["ts"] === "number" ? record["ts"] : 0
+    };
+  });
+  return { changes };
+};
+const parseCdcSyncArgs = (args) => {
+  const toCount = (value) => {
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : void 0;
+  };
+  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 parseIdentityHeader = (raw) => {
+  if (!raw) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+};
+const tablesFromDeps = (deps) => {
+  const tables = /* @__PURE__ */ new Set();
+  for (const dep of deps) {
+    const table = tableFromDepKey(dep);
+    if (table !== "") {
+      tables.add(table);
+    }
+  }
+  return tables;
+};
+const parsePositiveInt = (raw) => {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value > 0 ? value : void 0;
+};
+const parseEmit = (raw, devDefault) => {
+  if (raw === "1" || raw === "true") {
+    return true;
+  }
+  if (raw === "0" || raw === "false") {
+    return false;
+  }
+  return devDefault;
+};
+const parseSampleRate = (raw) => {
+  if (raw === void 0) {
+    return 1;
+  }
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 1;
+};
+const sampleHit = (rate) => {
+  if (rate >= 1) {
+    return true;
+  }
+  if (rate <= 0) {
+    return false;
+  }
+  return Math.random() < rate;
+};
+const extractBearerToken = (authorization) => {
+  if (!authorization) {
+    return void 0;
+  }
+  const [scheme, ...rest] = authorization.split(" ");
+  if (scheme?.toLowerCase() !== "bearer") {
+    return void 0;
+  }
+  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
+   * pins an `AbortController` + the user's async generator + any buffered
+   * chunks on the WS — letting a client open hundreds of streams in
+   * parallel would let it pin DO memory without ever sending a message.
+   * 8 is generous for legitimate clients (the studio rarely opens more
+   * than 2-3 simultaneously) and small enough that the worst-case memory
+   * footprint stays bounded.
+   */
+  static MAX_STREAMS_PER_SOCKET = 8;
+  /**
+   * Per-socket subscription cap. Each subscription is stored in the
+   * hibernation attachment (which is serialized JSON), and runaway
+   * subscribe loops would let a single client wedge the attachment past
+   * the runtime's size budget — keep the per-socket ceiling well below
+   * that. 32 is enough for any reasonable client (one per visible
+   * panel/query) and small enough that an attachment serialization
+   * failure stays unlikely.
+   */
+  static MAX_SUBSCRIPTIONS_PER_SOCKET = 32;
+  /**
+   * Per-socket whisper-topic cap. Topic membership rides the same hibernation
+   * attachment as `subs`, so bound it for the same reason — a runaway
+   * `whisper_subscribe` loop must not wedge the attachment past the runtime's
+   * size budget. Over-cap joins are silently ignored (whispering is
+   * best-effort, never acked).
+   */
+  static MAX_WHISPER_TOPICS_PER_SOCKET = 64;
+  /**
+   * Cap on the serialized size (bytes) of a whisper `data` payload. Whispers
+   * carry small awareness blobs (cursor, typing flag); bounding the payload
+   * stops a client from turning the fan-out into a bandwidth-amplification
+   * vector. An over-limit whisper is dropped (best-effort, never acked).
+   */
+  static MAX_WHISPER_BYTES = 4096;
+  /**
+   * Whisper-rate token bucket: each socket may burst {@link ShardDO.WHISPER_RATE_BURST}
+   * whispers, refilling at {@link ShardDO.WHISPER_RATE_PER_SEC}/s. Without this a single
+   * client could loop `whisper` frames, each costing O(connections) to fan out
+   * — an O(N) CPU + egress amplification the per-message byte cap alone doesn't
+   * close. In-memory (resets to full burst on hibernation, which is the
+   * conservative direction).
+   */
+  static WHISPER_RATE_BURST = 50;
+  static WHISPER_RATE_PER_SEC = 25;
+  /**
+   * Set once the very first `__root__` warning has been emitted. Static so
+   * a hot DO cannot spam the log on every write; the v0.1 lifetime of a DO
+   * exceeds any reasonable cooldown so a single warning is sufficient. The
+   * test suite resets this via `resetRootSizeWarning` for isolation.
+   */
+  static rootSizeWarned = false;
+  /** Test-only: reset the static "warned once" flag. */
+  static resetRootSizeWarning() {
+    ShardDO.rootSizeWarned = false;
+  }
+  state;
+  env;
+  /**
+   * Opt-in per-shard reactive query cache. When the subclass passes
+   * `ReactiveCacheOptions` to `super(state, env, { reactiveCache: { … } })`
+   * the cache is instantiated here and exposed to subclasses via
+   * `runCachedQuery`; when omitted (today's default) it stays
+   * undefined and the dispatch path runs with zero cache overhead.
+   *
+   * The cache is per-shard and in-memory only — it is lost on DO restart
+   * and on workerd hibernation. That's fine: a cold shard simply re-runs
+   * the query on the first call, just like it does today.
+   */
+  reactiveCache;
+  /**
+   * Lazily-built drizzle handle over `state.storage`. Memoised so a single
+   * DO instance reuses the same dialect across handler calls. The drizzle
+   * DO driver only touches `storage.sql`, so test doubles only need to
+   * supply that field — see {@link ShardDOState}.
+   */
+  drizzleHandle;
+  /**
+   * Tracks BEGIN/COMMIT nesting so we can reject nested transactions —
+   * SQLite-in-DO does not support them and the runtime would crash with
+   * "cannot start a transaction within a transaction".
+   */
+  transactionDepth = 0;
+  /**
+   * Per-request D1 Sessions API bookmark, read from the inbound
+   * `x-d1-bookmark` header at the top of `fetch` and exposed to handlers
+   * via `getInboundBookmark`. Cleared between requests so a stale
+   * bookmark from a previous client never leaks into the next session.
+   */
+  currentRequestBookmark;
+  /**
+   * Per-request D1 bookmark to echo on the outbound response. Handlers
+   * call `setOutboundBookmark` after a global-table write so the
+   * client can pin subsequent reads on the same replica.
+   */
+  currentResponseBookmark;
+  /**
+   * Per-request userId forwarded from the runtime via the
+   * `x-lunora-userid` header. Surfaced to handlers via
+   * `getCurrentUserId`. Cleared in the `finally` block of `fetch`
+   * so a stale identity from a previous client never leaks into the
+   * next request.
+   */
+  currentRequestUserId;
+  /**
+   * Per-request caller IP forwarded from the runtime via the
+   * `x-lunora-client-ip` header (sourced server-side from Cloudflare's trusted
+   * `CF-Connecting-IP`). Surfaced to handlers as `ctx.ip` via `getCurrentIp`;
+   * cleared in the `finally` block of `fetch` like the other per-request fields.
+   */
+  currentRequestIp;
+  /**
+   * 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
+   * by `(currentRequestUserId, mutationId)`: a replay short-circuits to the
+   * cached result, and `persistIdempotentResult` records the result right
+   * after the handler's writes commit so the dedup row is durable iff the
+   * writes are. Absent on queries and legacy clients. Cleared in the `fetch`
+   * `finally` block.
+   */
+  currentRequestMutationId;
+  /**
+   * Wall-clock millis of the last `__idempotency` GC sweep on this warm
+   * instance. The dedup write throttles `trimIdempotent` to at most once an
+   * hour off this field (in-memory, so a fresh instance just sweeps on its
+   * first mutation) — keeping the 24h-retention cleanup off the per-mutation
+   * hot path without needing a separate alarm/cron.
+   */
+  lastIdempotencyTrimAt = 0;
+  /**
+   * Per-request identity envelope forwarded from the runtime via the
+   * `x-lunora-identity` JSON header. Stores claims like `email`,
+   * `name`, or custom roles populated by `resolveIdentity` on the
+   * worker. Surfaced to handlers via `getCurrentIdentity`.
+   */
+  currentRequestIdentity;
+  /**
+   * Whether the in-flight `/rpc` call is a trusted server-initiated dispatch
+   * (scheduler/cron), signalled by the `x-lunora-system` header that only the
+   * worker's authorized dispatch path sets. When true, `handleRpc` may invoke
+   * `internal` functions; client RPCs never carry it, so internals stay
+   * unreachable across the external boundary. Cleared in `fetch`'s `finally`.
+   */
+  currentRequestSystem = false;
+  /**
+   * Tables written during the in-flight RPC, accumulated by
+   * `recordChangedTable`. Drained after `handleRpc` returns to drive
+   * `refreshSubscriptions`. `null` when no write has happened yet so
+   * the common read-only path allocates nothing.
+   */
+  pendingChangedTables = void 0;
+  /**
+   * Last pushed result per `(socket, subId)`, keyed by socket. Lets
+   * `refreshSubscriptions` skip re-running queries whose tables were
+   * untouched and suppress pushes when the re-run result is unchanged. Held
+   * in memory only — it does not survive hibernation, which is safe: a cold
+   * memo simply forces one re-run and (at most) one redundant push.
+   */
+  subMemos = /* @__PURE__ */ new WeakMap();
+  /** Per-socket whisper-rate token bucket (see {@link ShardDO.WHISPER_RATE_BURST}). In-memory; resets on hibernation. */
+  whisperBuckets = /* @__PURE__ */ new WeakMap();
+  /**
+   * Per-socket {@link AbortController} map keyed by stream id, used to
+   * propagate a client unsubscribe (or a socket close) into the user
+   * handler. In-memory only: a hibernation drops the controllers, which is
+   * fine because the corresponding socket is gone too — the iterator
+   * pumping into it would have nowhere to write.
+   */
+  streamCancellers = /* @__PURE__ */ new WeakMap();
+  /**
+   * Lifetime request counters surfaced by the `__lunora_admin__:getMetrics`
+   * RPC. In-memory only — they reset when the DO hibernates or restarts, which
+   * is the right granularity for a "since this instance woke" health readout
+   * (durable aggregation would be a separate, heavier feature).
+   */
+  metrics = { errors: 0, requests: 0, sinceMs: Date.now() };
+  /**
+   * Declared indexes (`table:index`) a query has exercised since this instance
+   * woke, stamped by `getCtxDbIndexUseHook`. In-memory and reset on
+   * hibernation/restart — drives the `unused_index` runtime advisory.
+   */
+  usedIndexes = /* @__PURE__ */ new Set();
+  /**
+   * Per-function execution counters surfaced by the
+   * `__lunora_admin__:getFunctionStats` RPC, keyed by `&lt;file>:&lt;function>`
+   * path. Shares the `metrics` lifecycle: in-memory, reset on
+   * hibernation/restart. The map is naturally bounded by the app's registered
+   * function count (a finite set), so no eviction is needed. Maintained by
+   * `recordFunctionCall` at the one dispatch site that also bumps the
+   * aggregate `metrics` counters.
+   */
+  functionStats = /* @__PURE__ */ new Map();
+  /**
+   * Recent RPC errors on this shard instance, surfaced by the
+   * `__lunora_admin__:getLogs` RPC. In-memory only and bounded — like
+   * `metrics`, it resets on hibernation/restart. We only capture RPC
+   * dispatch failures here (path + error message), not user `console.*` output:
+   * intercepting the console cheaply isn't possible, so this is honestly a
+   * "recent RPC errors on this instance" feed, not a general application log.
+   */
+  logs = new LogBuffer();
+  /**
+   * In-flight dependency tracker for the currently-executing query. Set by
+   * `runCachedQuery` so the ctx-db hooks (wired via `onRead`) can
+   * stamp deps without threading the tracker explicitly through every
+   * generated handler signature. Cleared in the `finally` of the same
+   * call so a leaked tracker can never bleed into a sibling RPC.
+   */
+  currentTracker;
+  /**
+   * Tables the in-flight dispatch full-scanned (read via `SCAN_DEP`, no index
+   * / point lookup). Allocated at the top of each `/rpc` dispatch and drained
+   * into `recordFunctionCall` once the handler returns, so the durable
+   * `__lunora_metrics_scans` attribution can pin a slow function to the
+   * table(s) it scanned. Independent of `currentTracker` (which only exists
+   * when the reactive cache is enabled), so the causal signal is collected
+   * even on a cache-less shard. Stamped by `getCtxDbReadHook`.
+   */
+  currentScannedTables;
+  /**
+   * Declared indexes the in-flight dispatch exercised (used to narrow a read,
+   * via `onIndexUse`), keyed by `JSON.stringify([table, index])`. Allocated at the top of each
+   * `/rpc` dispatch and drained into `recordFunctionCall` once the handler
+   * returns, so the durable `__lunora_metrics_index` hit counter — the producer
+   * behind the advisor dead-index lint — records on the same dispatch path as
+   * the scan attribution. Stamped by `getCtxDbIndexUseHook`.
+   */
+  currentIndexHits;
+  /**
+   * Read-tables + cache-hit captured for the current `/rpc` dispatch, so the
+   * dispatch site can fold them into the durable request log
+   * (`request-log.ts`). Populated by `runCachedQuery` — the one place that
+   * both holds the per-query dependency tracker AND learns whether the
+   * reactive cache served the result — and reset per request in `fetch`.
+   * `undefined`/empty when the reactive cache is disabled or the path is a
+   * write/action (which doesn't run through the cache), which is exactly why
+   * the request log treats those fields as "unknown" rather than asserting a
+   * read set on the hot path.
+   */
+  currentRequestReadTables;
+  /**
+   * Per-statement SQL samples collected during the current `/rpc` dispatch by
+   * the instrumented `sql` getter. Drained into the durable
+   * `__lunora_metrics_queries` table after the handler returns (same pattern as
+   * `currentScannedTables` / `currentIndexHits`). `undefined` when no dispatch
+   * is in flight; allocated fresh per dispatch so a previous request's samples
+   * never leak into the next one.
+   *
+   * Each entry is `[rawSql, durationMs, rowsRead, rowsWritten]`. DML rows
+   * written is always 0 here — the ctx-db adapter doesn't expose a
+   * `changes()` count through the structural `SqlExec` surface, so we
+   * attribute only SELECT result sizes as `rowsRead`.
+   */
+  currentStmtSamples;
+  /** Whether the current dispatch's cached query was served from cache; `undefined` until `runCachedQuery` resolves one. */
+  currentRequestCacheHit;
+  constructor(state, env, options = {}) {
+    this.state = state;
+    this.env = env;
+    if (options.reactiveCache) {
+      this.reactiveCache = new ReactiveCache(options.reactiveCache);
+    }
+    this.armWebSocketKeepalive();
+  }
+  /** SQLite handle scoped to this Durable Object. */
+  /**
+   * Worker-side fetch entry point. Handles WebSocket upgrades and the
+   * shard-local RPC endpoint forwarded by `@lunora/runtime`.
+   */
+  async fetch(request) {
+    const url = new URL(request.url);
+    if (request.headers.get("Upgrade") === "websocket") {
+      return this.handleWebSocketUpgrade(request);
+    }
+    if (url.pathname !== "/rpc" || request.method !== "POST") {
+      return new Response("Not found", { status: 404 });
+    }
+    let payload;
+    try {
+      payload = await request.json();
+    } catch {
+      return jsonResponse({ error: { code: "BAD_REQUEST", message: "invalid JSON body" } }, 400);
+    }
+    if (payload.functionPath.startsWith(ADMIN_FUNCTION_PREFIX)) {
+      return this.handleAdminRpc(request, payload.functionPath, payload.args ?? {});
+    }
+    this.currentRequestBookmark = request.headers.get("x-d1-bookmark") ?? void 0;
+    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.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.currentRequestReadTables = void 0;
+    this.currentRequestCacheHit = void 0;
+    this.metrics.requests += 1;
+    const dispatchStartedAt = Date.now();
+    this.currentScannedTables = /* @__PURE__ */ new Set();
+    this.currentIndexHits = /* @__PURE__ */ new Set();
+    this.currentStmtSamples = [];
+    try {
+      if (payload.functionPath.startsWith(RELATION_FUNCTION_PREFIX)) {
+        const value = await this.runRelationFanoutRead(payload.functionPath, payload.args ?? {});
+        return jsonResponse(value, 200, this.currentResponseBookmark);
+      }
+      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);
+      }
+      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);
+      await this.flushChangedTables();
+      return response;
+    } catch (error) {
+      this.metrics.errors += 1;
+      const durationMs = Date.now() - dispatchStartedAt;
+      const message = error instanceof Error ? error.message : String(error);
+      const conflicted = error instanceof ConflictError && error.kind === "occ";
+      const code = error?.code;
+      if (code !== "FUNCTION_NOT_FOUND") {
+        this.recordFunctionCall(payload.functionPath, durationMs, message, this.currentScannedTables, this.currentIndexHits, conflicted);
+      }
+      this.flushStmtSamples();
+      this.recordRequestLog(payload.functionPath, payload.args ?? {}, durationMs, "error", [...this.pendingChangedTables ?? []], message);
+      this.logs.push({
+        functionPath: payload.functionPath,
+        level: "error",
+        message,
+        timestamp: Date.now()
+      });
+      return this.errorToResponse(error);
+    } finally {
+      this.currentRequestBookmark = void 0;
+      this.currentResponseBookmark = void 0;
+      this.currentRequestUserId = void 0;
+      this.currentRequestMutationId = void 0;
+      this.currentRequestIdentity = void 0;
+      this.currentRequestIp = void 0;
+      this.currentRequestSystem = false;
+      this.currentScannedTables = void 0;
+      this.currentIndexHits = void 0;
+      this.currentRequestReadTables = void 0;
+      this.currentRequestCacheHit = void 0;
+      this.currentStmtSamples = void 0;
+    }
+  }
+  /**
+   * Hibernation API: invoked by the runtime when a message arrives on a
+   * hibernated socket. Subclasses can override this to intercept; the
+   * default decodes a {@link SubscriptionEnvelope} and updates the registry.
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- Workers hibernation message router: the type/credential/route branching is the wire protocol and stays clearer inline than split across helpers sharing the socket + envelope
+  async webSocketMessage(ws, message) {
+    if (this.isSocketExpired(ws)) {
+      this.dropExpiredSocket(ws);
+      return;
+    }
+    const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+    let envelope;
+    try {
+      envelope = JSON.parse(text);
+    } catch {
+      ws.send(JSON.stringify({ message: "invalid envelope", type: "error" }));
+      return;
+    }
+    if (envelope.type === "connect") {
+      const attachment = this.readAttachment(ws);
+      if (attachment.connected === true) {
+        return;
+      }
+      if (envelope.context !== void 0) {
+        attachment.context = envelope.context;
+      }
+      attachment.connected = true;
+      try {
+        ws.serializeAttachment?.(attachment);
+      } catch {
+      }
+      await this.dispatchLifecycle("connect", this.lifecycleInfo(attachment));
+      return;
+    }
+    if (envelope.type === "subscribe" && envelope.query) {
+      const { functionPath } = envelope.query;
+      const isAdmin = functionPath?.startsWith(ADMIN_FUNCTION_PREFIX) === true;
+      if (isAdmin && this.readAttachment(ws).admin !== true) {
+        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);
+      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";
+        try {
+          ws.send(JSON.stringify({ code, error: { code, message: errorMessage }, id: envelope.id, type: "error" }));
+        } catch {
+        }
+        return;
+      }
+      ws.send(JSON.stringify({ id: envelope.id, type: "ack" }));
+      if (functionPath) {
+        await this.seedSubscription(ws, envelope.id, envelope.query, functionPath, isAdmin);
+      }
+      return;
+    }
+    if (envelope.type === "stream" && envelope.query?.functionPath) {
+      if (envelope.query.functionPath.startsWith(ADMIN_FUNCTION_PREFIX)) {
+        ws.send(JSON.stringify({ id: envelope.id, message: "streams must be public", type: "error" }));
+        return;
+      }
+      this.handleStream(ws, envelope.id, envelope.query.functionPath, envelope.query.args ?? {}).catch(() => {
+      });
+      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");
+      }
+      return;
+    }
+    if (envelope.type === "whisper") {
+      if (typeof envelope.topic === "string" && envelope.topic.length > 0) {
+        this.broadcastWhisper(ws, envelope.topic, envelope.data);
+      }
+      return;
+    }
+    if (envelope.type === "unsubscribe") {
+      const cancellers = this.streamCancellers.get(ws);
+      const controller = cancellers?.get(envelope.id);
+      if (controller) {
+        controller.abort();
+        cancellers?.delete(envelope.id);
+      }
+      this.unsubscribe(ws, envelope.id);
+      ws.send(JSON.stringify({ id: envelope.id, type: "ack" }));
+    }
+  }
+  /**
+   * Hibernation API: invoked on socket close. The runtime has already
+   * closed the socket by the time we're called — calling `ws.close()`
+   * again would throw "WebSocket has been closed" in the Workers runtime.
+   */
+  async webSocketClose(ws, _code, _reason, _wasClean) {
+    const attachment = this.readAttachment(ws);
+    if (attachment.connectionId !== void 0) {
+      await this.dispatchLifecycle("disconnect", this.lifecycleInfo(attachment));
+    }
+    const cancellers = this.streamCancellers.get(ws);
+    if (cancellers) {
+      for (const controller of cancellers.values()) {
+        controller.abort();
+      }
+      this.streamCancellers.delete(ws);
+    }
+    this.subMemos.delete(ws);
+    ws.serializeAttachment?.(void 0);
+  }
+  /** Hibernation API: invoked on socket error. */
+  // eslint-disable-next-line class-methods-use-this -- Workers hibernation handler: the platform invokes it on the instance; the signature must stay an instance method
+  webSocketError(_ws, _error) {
+  }
+  /**
+   * The registered function paths to dispatch when a socket connects/disconnects.
+   * Base default is empty; the codegen subclass overrides it to return the
+   * generated lifecycle manifest keyed by `event`. Kept as a data hook (like
+   * `tableRefs`/`rlsMetadata`) so the security-load-bearing dispatch — running
+   * each hook under the verified identity + system dispatch — stays here in the
+   * base and can't be mis-wired by generated code.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass returns the generated lifecycle manifest
+  lifecycleHookPaths(_event) {
+    return [];
+  }
+  /**
+   * Run every registered `connect`/`disconnect` hook for a socket, each under
+   * the connecting user's verified identity and a trusted system dispatch (so
+   * the internal hooks are permitted). A hook that throws is swallowed (logged)
+   * — a disconnect must never fail the hibernation close path, and one hook's
+   * failure must not skip the rest. Hooks run sequentially so they share the
+   * DO's single-threaded write snapshot deterministically.
+   */
+  async dispatchLifecycle(event, info) {
+    for (const functionPath of this.lifecycleHookPaths(event)) {
+      try {
+        await this.withRequestIdentity(
+          info.userId,
+          info.identity,
+          () => this.withSystemDispatch(() => this.handleRpc(functionPath, info.event))
+        );
+      } catch (error) {
+        this.logs.push({
+          functionPath,
+          level: "error",
+          message: error instanceof Error ? error.message : String(error),
+          timestamp: Date.now()
+        });
+      }
+    }
+  }
+  /**
+   * Serve a reserved {@link RELATION_FUNCTION_PREFIX} fan-out read/count for
+   * reverse cross-backend relations (a `.global()` parent loading a
+   * shard-local child that spans every shard). Returns a BARE value — the
+   * child-row array for `__lunora_relation__:read`, a number for
+   * `__lunora_relation__:count` — so the coordinator's `concat`/`sum` merge
+   * composes the per-shard results. Runs under the forwarded caller identity
+   * (the `x-lunora-userid` / `x-lunora-identity` headers stashed for the
+   * request), never the admin token.
+   *
+   * The base class is schema-agnostic, so it cannot build the ctx-db needed to
+   * read the child table; the codegen subclass overrides this with a
+   * schema-aware implementation. Reaching the base default means the prefix was
+   * dispatched against a ShardDO with no generated schema bound.
+   */
+  // 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",
+      status: 500
+    });
+  }
+  /**
+   * Instrumented SQL handle. Wraps `state.storage.sql` so that every `exec`
+   * call during a user RPC dispatch is timed and its result size captured into
+   * `currentStmtSamples`. The samples are flushed to the durable
+   * `__lunora_metrics_queries` table after the handler returns (same lifecycle
+   * as `currentScannedTables`/`currentIndexHits`).
+   *
+   * The wrapper is only active when `currentStmtSamples` is defined (i.e.
+   * during a live user RPC dispatch). Admin ops, subscription re-runs, and
+   * any other path that doesn't allocate `currentStmtSamples` pass through to
+   * the raw handle unchanged — recording there would skew leaderboard totals
+   * with internal housekeeping queries.
+   *
+   * IMPORTANT: the instrumented wrapper must NOT call any SQL itself (e.g. to
+   * flush metrics) — it is invoked synchronously inside an `exec` call and
+   * the SQLite connection is not re-entrant in workerd. Samples are flushed
+   * after the handler fully resolves.
+   */
+  get sql() {
+    const rawSql = this.state.storage.sql;
+    const samples = this.currentStmtSamples;
+    if (samples === void 0) {
+      return rawSql;
+    }
+    const rawExec = rawSql.exec;
+    if (typeof rawExec !== "function") {
+      return rawSql;
+    }
+    const instrumentedExec = (query, ...params) => {
+      const start = Date.now();
+      const cursor = rawExec.call(rawSql, query, ...params);
+      if (cursor !== null && typeof cursor === "object") {
+        const c = cursor;
+        if (typeof c["toArray"] === "function") {
+          const originalToArray = c["toArray"].bind(c);
+          c["toArray"] = () => {
+            const rows = originalToArray();
+            const durationMs = Date.now() - start;
+            samples.push([query, durationMs, rows.length, 0]);
+            return rows;
+          };
+        }
+        if (typeof c["one"] === "function") {
+          const originalOne = c["one"].bind(c);
+          c["one"] = () => {
+            const row = originalOne();
+            const durationMs = Date.now() - start;
+            samples.push([query, durationMs, 1, 0]);
+            return row;
+          };
+        }
+        if (typeof c["toArray"] !== "function" && typeof c["one"] !== "function") {
+          const durationMs = Date.now() - start;
+          samples.push([query, durationMs, 0, 0]);
+        }
+      } else {
+        const durationMs = Date.now() - start;
+        samples.push([query, durationMs, 0, 0]);
+      }
+      return cursor;
+    };
+    return /* @__PURE__ */ new Proxy(rawSql, {
+      get(target, prop) {
+        if (prop === "exec") {
+          return instrumentedExec;
+        }
+        return Reflect.get(target, prop, target);
+      }
+    });
+  }
+  /**
+   * Drizzle handle scoped to this Durable Object's SQLite storage. Use this
+   * for typed queries against generated `sqliteTable` schemas. The handle
+   * participates in `runInTransaction` via drizzle's own `transaction`
+   * helper — there is no need to call `db.transaction(...)` directly from
+   * subclasses; wrap your work in `runInTransaction` and use `this.db`
+   * inside the handler instead.
+   */
+  get db() {
+    if (this.drizzleHandle) {
+      return this.drizzleHandle;
+    }
+    this.drizzleHandle = drizzle(this.state.storage, { logger: false });
+    return this.drizzleHandle;
+  }
+  /**
+   * Run `handler` inside a SQLite transaction. Commits if it resolves;
+   * rolls back if it throws. The `ConflictError` re-throw lets the
+   * runtime translate optimistic-concurrency failures into a 409 response.
+   *
+   * Nested calls are refused with a `LunoraError`-shaped object — SQLite
+   * in Durable Objects does not support nested transactions, so we fail
+   * loudly rather than silently flattening them.
+   *
+   * Drizzle queries issued via `db` inside the handler participate
+   * in this transaction implicitly — drizzle and the BEGIN/COMMIT below
+   * both write through the same `state.storage.sql` handle, so the tx
+   * boundary is shared. Do **not** call `this.db.transaction(...)` from
+   * inside a handler; that would attempt a nested SQLite transaction.
+   *
+   * Why raw BEGIN/COMMIT/ROLLBACK strings instead of `this.db.transaction(handler)`?
+   * Two reasons, both verified against drizzle-orm 0.45.2's
+   * `durable-sqlite/session.js`:
+   *
+   * 1. The DO driver does NOT issue BEGIN/COMMIT/ROLLBACK SQL — it
+   * delegates to `state.storage.transactionSync(callback)`, the
+   * DO platform's native transaction primitive. Swapping in
+   * `db.transaction()` would silently change the wire-level
+   * contract observed by tests and any tooling that intercepts
+   * `storage.sql`.
+   *
+   * 2. `transactionSync` invokes the callback synchronously and does
+   * not await its return value. Drizzle's `transaction()` matches
+   * that — it passes the tx handle through and then returns.
+   * Handing it an async handler would let the transaction commit
+   * before the handler resolves, breaking the `() => Promise&lt;T> | T`
+   * contract.
+   *
+   * The raw-SQL approach below is async-safe and gives the
+   * connection-scoped semantics SQLite-in-DO is designed for.
+   */
+  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
+      });
+    }
+    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
+      });
+    }
+    const sqlExec = sqlHandle.exec.bind(sqlHandle);
+    const run = async () => {
+      this.transactionDepth = 1;
+      sqlExec("BEGIN");
+      try {
+        const value = await handler();
+        sqlExec("COMMIT");
+        return value;
+      } catch (error) {
+        try {
+          sqlExec("ROLLBACK");
+        } catch {
+        }
+        throw error;
+      } finally {
+        this.transactionDepth = 0;
+      }
+    };
+    if (typeof this.state.blockConcurrencyWhile === "function") {
+      return this.state.blockConcurrencyWhile(run);
+    }
+    return run();
+  }
+  /**
+   * Returns the D1 Sessions API bookmark forwarded by the client on this
+   * request, or `undefined` when none was supplied. Handlers pass this
+   * into `db.withSession(bookmark)` to opt into read-your-writes
+   * consistency across replicas.
+   */
+  getInboundBookmark() {
+    return this.currentRequestBookmark;
+  }
+  /**
+   * Record the post-write D1 bookmark that should be echoed back to the
+   * client on the outbound `x-d1-bookmark` header. Safe to call multiple
+   * times — the last value wins; only the most recent write's bookmark
+   * is meaningful for downstream read pinning.
+   */
+  setOutboundBookmark(bookmark) {
+    this.currentResponseBookmark = bookmark;
+  }
+  /**
+   * The userId forwarded by the runtime's `resolveIdentity` hook for the
+   * current request, or `undefined` when the request is anonymous. Use
+   * this to populate `ctx.auth.userId` inside `buildCtx`.
+   */
+  getCurrentUserId() {
+    return this.currentRequestUserId;
+  }
+  /**
+   * The caller's IP for the current request (Cloudflare's `CF-Connecting-IP`,
+   * forwarded server-side), or `undefined` when unknown. Use this to populate
+   * `ctx.ip` inside `buildCtx`.
+   */
+  getCurrentIp() {
+    return this.currentRequestIp;
+  }
+  /**
+   * Identity claims (email, name, roles, …) forwarded by the runtime's
+   * `resolveIdentity` hook. Returns `undefined` for anonymous requests
+   * or when no extra claims were attached. Use this to populate the
+   * value returned by `ctx.auth.getIdentity()` inside `buildCtx`.
+   */
+  getCurrentIdentity() {
+    return this.currentRequestIdentity;
+  }
+  /**
+   * Whether the in-flight `/rpc` call is a trusted server-initiated dispatch
+   * (scheduler/cron). A concrete `handleRpc` consults this to decide whether
+   * `internal` functions may run — they may for system dispatch, never for a
+   * client RPC (which never carries the `x-lunora-system` header).
+   */
+  isSystemDispatch() {
+    return this.currentRequestSystem;
+  }
+  /**
+   * Run a data migration by id against this shard, returning the runner's
+   * result. The base class can't reach the project's generated
+   * `LUNORA_MIGRATIONS` registry or build a schema-aware writer, so it reports
+   * the migration as unknown; the codegen-generated subclass overrides this to
+   * look the migration up and invoke `runDataMigration`.
+   */
+  // 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 })
+    );
+  }
+  /**
+   * Lazily provision the shard's physical tables before an operation that
+   * depends on them existing. The base class has no `schema.ts`, so it does
+   * nothing; the codegen subclass overrides this to run `runShardMigrations`
+   * once (guarded by an idempotent `migrated` flag). Kept here so base-class
+   * paths — notably admin introspection — can materialise tables on demand
+   * without knowing the schema, which is what keeps the data browser from
+   * showing an empty shard on first load.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this to run the generated schema's migrations
+  ensureMigrated() {
+  }
+  /**
+   * Foreign-key map for `table`: doc field → target table, for every field
+   * declared `v.id("target")` in the schema, so the data browser can render
+   * those cells as links. The base class can't see the user's `schema.ts`, so
+   * it returns `undefined` (no links); the codegen subclass overrides this with
+   * the schema-derived map.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this and uses `this` to read the generated schema's foreign keys
+  tableRefs(_table) {
+    return void 0;
+  }
+  /**
+   * Declared indexes for `table` (secondary, search, rank, vector), surfaced by
+   * the schema viewer via `__lunora_admin__:listTableIndexes`. Like
+   * {@link tableRefs}, the base class can't see the user's `schema.ts`, so it
+   * reports none; the codegen subclass overrides this with the schema-derived
+   * list. Schema-sourced rather than read from SQLite because lunora's physical
+   * indexes are `json_extract` expressions whose field names PRAGMA can't recover.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this to read the generated schema's index metadata
+  tableIndexes(_table) {
+    return [];
+  }
+  /**
+   * Typed columns for `table` (name, validator-IR type, PK/FK/storage role),
+   * surfaced by the schema viewer's diagram via `__lunora_admin__:describeTable`.
+   * Like {@link tableRefs}/{@link tableIndexes}, the base class can't see the
+   * user's `schema.ts`, so it reports none; the codegen subclass overrides this
+   * with the schema-derived list. Schema-sourced rather than read from SQLite
+   * because lunora stores rows in a `__doc__` JSON blob, so PRAGMA recovers
+   * neither declared types nor PK/FK roles.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the generated schema's column metadata
+  tableColumns(_table) {
+    return [];
+  }
+  /**
+   * Storage-key columns per table (`{ table: [field, …] }`) — every field
+   * declared `v.storage(...)` in the schema, so the admin `storageReferences`
+   * read can join R2 objects back to the rows that own them (and flag orphans).
+   * Like {@link tableRefs}, the base class can't see the user's `schema.ts`, so
+   * it reports none; the codegen subclass overrides this with the schema-derived
+   * map.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the generated storage-column map
+  storageColumns() {
+    return {};
+  }
+  /**
+   * Static schema advisories for this deployment, surfaced via
+   * `__lunora_admin__:getAdvisories`. Computed by `@lunora/advisor` at codegen
+   * time (the only place the schema + query reads are both available) and
+   * emitted into the generated subclass, which overrides this. The base class
+   * can't see the user's `schema.ts`, so it reports none.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the generated advisory list
+  advisories() {
+    return [];
+  }
+  /**
+   * Row-level-security metadata for this deployment, surfaced via
+   * `__lunora_admin__:rlsPolicies` to the studio's read-only RLS inspector:
+   * which `definePolicy`s guard which `(table, on)` and which `defineRole`s
+   * are registered. Statically discovered by `@lunora/codegen` at codegen
+   * time (the only place every `.use(rls(...))` chain is visible) and emitted
+   * into the generated subclass, which overrides this. The base class can't
+   * see the user's `lunora/` sources, so it reports none. Never includes the
+   * `when` predicate — that's an opaque closure whose logic stays in code.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the generated RLS policy + role metadata
+  rlsMetadata() {
+    return { policies: [], roles: [] };
+  }
+  /**
+   * Masking metadata for this deployment, surfaced via
+   * `__lunora_admin__:maskPolicies` to the studio's data-browser mask preview:
+   * which `(table, column)` pairs a `.use(mask(...))` chain redacts and the
+   * declared strategy. Statically discovered by `@lunora/codegen` (the only
+   * place every `.use(mask(...))` chain is visible) and emitted into the
+   * generated subclass, which overrides this. The base class can't see the
+   * user's `lunora/` sources, so it reports none. Never includes the masking
+   * closure — only the column + strategy descriptor.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the generated mask column metadata
+  maskMetadata() {
+    return { columns: [] };
+  }
+  /**
+   * Storage access-rule metadata for this deployment, surfaced via
+   * `__lunora_admin__:storageRules` to the studio's read-only access-rules
+   * view: which `defineStorageRule`s gate which `(bucket, on, prefix)`.
+   * Statically discovered by `@lunora/codegen` from every
+   * `.use(storageRules(...))` chain and emitted into the generated subclass,
+   * which overrides this. The base class can't see the user's `lunora/`
+   * sources, so it reports none. Never includes the `when` predicate.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the generated storage-rule metadata
+  storageRulesMetadata() {
+    return { rules: [] };
+  }
+  /**
+   * Which optional, package-backed features this deployment wires up, surfaced
+   * via `__lunora_admin__:studioFeatures` so the studio hides nav pages whose
+   * backing package isn't enabled (mirroring how auth panels gate on
+   * capabilities). Statically discovered by `@lunora/codegen` from the app's
+   * `lunora/` sources + schema and emitted into the generated subclass, which
+   * overrides this. The base class can't see the user's project, so it reports
+   * every flag `false` — an un-generated `ShardDO` shows no optional pages.
+   */
+  // 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 };
+  }
+  /**
+   * The Cloudflare Workflows declared by this app, surfaced via
+   * `__lunora_admin__:listWorkflows` for the studio's Workflows page. Workflows
+   * are NOT Durable Objects and hold no shard state, so this is pure
+   * declaration metadata statically discovered by `@lunora/codegen` from
+   * `lunora/workflows.ts` and emitted into the generated subclass, which
+   * overrides this. The base class can't see the user's project, so it reports
+   * none — an un-generated `ShardDO` lists zero workflows.
+   */
+  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the statically-discovered workflow metadata
+  workflowsMetadata() {
+    return { workflows: [] };
+  }
+  /**
+   * Runtime advisories derived from observed signal — currently `unused_index`:
+   * a declared index a query has never exercised since this instance woke. To
+   * keep noise down it only inspects tables that have used *some* index (so a
+   * never-queried table never spams findings; a table queried only via full
+   * scan is the `filter_without_index` lint's concern, not this one). The
+   * "since this instance woke" caveat rides in the detail — like the other
+   * in-memory counters, the signal resets on hibernation.
+   */
+  runtimeAdvisories() {
+    const usedTables = new Set([...this.usedIndexes].map((key) => key.slice(0, key.indexOf(":"))));
+    const findings = [];
+    for (const table of usedTables) {
+      for (const index of this.tableIndexes(table)) {
+        if (index.type === "vector" || this.usedIndexes.has(`${table}:${index.name}`)) {
+          continue;
+        }
+        findings.push({
+          cacheKey: `unused_index:${table}:${index.name}`,
+          categories: ["PERFORMANCE"],
+          description: "A declared index has not been exercised by any query since this shard instance started. An unused index costs storage and is maintained on every write for no read benefit.",
+          detail: `Index "${index.name}" on table "${table}" has not been used since this instance woke, though other indexes on "${table}" have — it may be redundant.`,
+          facing: "INTERNAL",
+          level: "INFO",
+          metadata: { index: index.name, indexKind: index.type, since: "instance-woke", table },
+          name: "unused_index",
+          remediation: "Confirm over a representative window, then drop the index if no query needs it.",
+          title: "Unused index"
+        });
+      }
+    }
+    return findings;
+  }
+  /**
+   * Export every row this shard owns across the requested tables (or every
+   * shard-local user table when none are specified) as `{table, doc}` records.
+   * Globals are not the DO's concern; the worker reads those from D1.
+   *
+   * The base class can't build a schema-aware writer without seeing the user's
+   * `schema.ts`, so it returns an empty list; the codegen-generated subclass
+   * overrides this with `exportShardRows(...)` against the live writer.
+   */
+  // 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
+  runShardExport(_args) {
+    return Promise.resolve([]);
+  }
+  /**
+   * Re-insert a batch of `{table, doc}` rows on this shard, returning the
+   * per-table insert counts and a per-row error array. Schema-failed rows do
+   * not abort the batch — they're surfaced in `errors` and the rest land.
+   *
+   * The base class can't build a writer; the codegen subclass overrides this
+   * to call `importShardRows(...)` inside one transaction per batch.
+   */
+  // 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
+  runShardImport(_args) {
+    return Promise.resolve({ conflicts: 0, errors: [], inserted: {} });
+  }
+  /**
+   * Apply a single-row insert/patch/replace/delete through the schema-aware
+   * writer. The base class can't build a writer without the user's `schema.ts`,
+   * so it reports the table as unknown; the codegen-generated subclass overrides
+   * this to run the op against a live `createShardCtxDb(...)` writer (which
+   * maintains the FTS/aggregate/rank shadow tables and runs validators).
+   */
+  // 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 }));
+  }
+  /**
+   * Delete one row by primary key THROUGH the schema-aware writer — the
+   * per-row seam {@link runShardBulkDelete} loops over. Routing each delete
+   * through the writer (not raw SQL) is the whole point: it keeps the FTS /
+   * aggregate / rank shadow tables in sync and fires `onDelete` cascades,
+   * exactly like {@link runShardWrite}'s single-row delete.
+   *
+   * The base class can't build a writer without the user's `schema.ts`, so it
+   * reports the table as unknown; the codegen-generated subclass overrides
+   * this to call `writer.delete(id)` on a live `createShardCtxDb(...)` writer.
+   */
+  // 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 }));
+  }
+  /**
+   * Bulk-delete the rows of `table` matching the active `filters`/`search`
+   * (or every row, for `clearTable`), bounded to {@link SHARD_BULK_DELETE_CAP}
+   * per call. Concrete in the base: it collects the matching ids with the same
+   * predicate {@link readTablePage} previews, then deletes them ONE AT A TIME
+   * through {@link deleteRowThroughWriter} so the FTS / aggregate / rank shadow
+   * tables stay correct. Returns `{ deleted, hasMore }` so the caller loops a
+   * single bounded round-trip rather than deleting an unbounded set at once.
+   *
+   * Deletes are sequential by design — parallel writes to one DO would contend
+   * on OCC — so the per-row `await` is intentional.
+   */
+  async runShardBulkDelete(args) {
+    const limit = Math.min(Math.max(Math.trunc(args.limit ?? SHARD_BULK_DELETE_CAP), 1), SHARD_BULK_DELETE_CAP);
+    const { hasMore, ids } = selectMatchingIds(this.sql, {
+      filters: args.filters,
+      limit,
+      search: args.search,
+      table: args.table
+    });
+    let deleted = 0;
+    for (const id of ids) {
+      await this.deleteRowThroughWriter(args.table, id);
+      deleted += 1;
+    }
+    return { deleted, hasMore };
+  }
+  /**
+   * Count, for the row identified by `rowId`, how many rows precede it under
+   * `index` within `partitionKey` on this shard (`before`) and the partition's
+   * total (`total`). The cross-shard coordinator fans this out to every shard
+   * and sums the results into a global rank.
+   *
+   * The base class can't build a schema-aware writer without the user's
+   * `schema.ts`, so it has no rank shadow tables to count against; the
+   * codegen-generated subclass overrides this to call `rankBefore(...)` on a
+   * live `createShardCtxDb(...)` writer.
+   */
+  // 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 })
+    );
+  }
+  /**
+   * Page this shard's local ranked slice under `index`, each row tagged with
+   * its rank-key tuple (`partitionKey`, `sortValues`, `rowId`). The cross-shard
+   * coordinator (`orchestrateRankPage`) fans this out to every live shard and
+   * k-way merges the slices into one globally-ranked page.
+   *
+   * Same base/codegen split as {@link runShardRankBefore}: the base class has
+   * no schema-aware writer, so the codegen subclass overrides this to call
+   * `rankPageRows(...)` on a live `createShardCtxDb(...)` writer.
+   */
+  // 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 })
+    );
+  }
+  /**
+   * Page this shard's change-data-capture log past `sinceSeq`. Read-only and
+   * schema-free — it only touches the `__cdc_log` table — so the base class
+   * implements it directly (no codegen override needed). Returns an empty
+   * page that leaves the cursor untouched when CDC was never enabled on this
+   * shard, so the coordinator tolerates shards that predate CDC.
+   */
+  runShardCdcSync(args) {
+    const sql = this.sql;
+    const present = sql.exec(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`, CDC_LOG_TABLE).toArray().length > 0;
+    if (!present) {
+      return { changes: [], cursor: args.sinceSeq };
+    }
+    return readCdcChanges(sql, { limit: args.limit, sinceSeq: args.sinceSeq });
+  }
+  /**
+   * The `__cdc_log` high-watermark stamped on outbound `data`/`delta` frames
+   * as their `cursor`, letting a client persist its resume position (Pillar
+   * 1b). Returns `undefined` when CDC was never enabled on this shard — there
+   * is no monotonic cursor to advertise, and the frame omits the field so the
+   * wire stays byte-identical to the pre-cursor format for non-CDC apps.
+   */
+  currentCdcCursor() {
+    return this.cdcEnabled() ? readCdcCursor(this.sql) : void 0;
+  }
+  /**
+   * This shard's current CDC epoch, stamped on `data`/`delta`/`resume` frames
+   * next to the cursor so a reconnecting client can prove it is resuming the
+   * same changelog timeline it cached (see {@link evaluateResume}). Returns
+   * `undefined` when CDC was never enabled — the frame omits the field, keeping
+   * the wire byte-identical to the pre-epoch format for non-CDC apps.
+   */
+  currentCdcEpoch() {
+    return this.cdcEnabled() ? readCdcEpoch(this.sql) : void 0;
+  }
+  /**
+   * Decide whether a reconnecting subscription can resume from `sinceSeq`
+   * without a full snapshot. Returns the current high-watermark `cursor` plus
+   * a `resumable` verdict.
+   *
+   * `resumable: true` means `sinceSeq` is within the CDC retention window and
+   * no table in the query's `readSet` changed in `(sinceSeq, cursor]` — the
+   * client's cached value is still current, so the caller emits a lightweight
+   * `resume` frame instead of re-shipping the snapshot.
+   *
+   * `resumable: false` means either the log was compacted past `sinceSeq` (a
+   * retention gap), a read table changed (the client needs the fresh value),
+   * or CDC is off — the caller falls back to the full-snapshot seed.
+   */
+  evaluateResume(sinceSeq, readSet, sinceEpoch) {
+    const sql = this.sql;
+    if (!this.cdcEnabled()) {
+      return { cursor: void 0, epoch: void 0, resumable: false };
+    }
+    const cursor = readCdcCursor(sql);
+    const epoch = readCdcEpoch(sql);
+    if (sinceEpoch !== epoch) {
+      return { cursor, epoch, resumable: false };
+    }
+    if (sinceSeq > cursor) {
+      return { cursor, epoch, resumable: false };
+    }
+    if (sinceSeq === cursor) {
+      return { cursor, epoch, resumable: true };
+    }
+    const floor = minCdcSeq(sql);
+    if (floor === void 0 || floor > sinceSeq + 1) {
+      return { cursor, epoch, resumable: false };
+    }
+    if (readSet.size === 0) {
+      return { cursor, epoch, resumable: false };
+    }
+    const { changes } = readCdcChanges(sql, { limit: CDC_RESUME_SCAN_LIMIT, sinceSeq });
+    if (changes.length >= CDC_RESUME_SCAN_LIMIT) {
+      return { cursor, epoch, resumable: false };
+    }
+    const touchedReadSet = changes.some((change) => readSet.has(change.table));
+    return { cursor, epoch, resumable: !touchedReadSet };
+  }
+  /**
+   * Look up a previously-committed mutation for the in-flight request's
+   * `(identity, mutationId)`. Returns `{ value }` (the cached, JSON-decoded
+   * handler result) on a hit so the dispatch path can short-circuit, or
+   * `undefined` when `mutationId` is absent (queries / legacy clients) or the
+   * mutation has not run yet. Tolerates a stub `sql` handle without the dedup
+   * table (returns a miss) so unit harnesses that skip migrations still work.
+   * @returns the cached result box on a hit, or `undefined` for a miss or absent mutationId
+   */
+  readIdempotentResult(mutationId) {
+    if (mutationId === void 0) {
+      return void 0;
+    }
+    try {
+      const record = readIdempotent(this.sql, this.currentRequestUserId ?? "", mutationId);
+      return record === void 0 ? void 0 : { value: JSON.parse(record.resultJson) };
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Record the in-flight mutation's result against its `(identity, mutationId)`
+   * so a later replay of the same id short-circuits through
+   * {@link readIdempotentResult} instead of re-running the handler. A no-op
+   * 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.
+   */
+  persistIdempotentResult(result) {
+    if (this.currentRequestMutationId === void 0) {
+      return;
+    }
+    const now = Date.now();
+    try {
+      writeIdempotent(this.sql, this.currentRequestUserId ?? "", this.currentRequestMutationId, JSON.stringify(result) ?? "null", now);
+      if (now - this.lastIdempotencyTrimAt > IDEMPOTENCY_GC_INTERVAL_MS) {
+        trimIdempotent(this.sql, now - IDEMPOTENCY_RETENTION_MS);
+        this.lastIdempotencyTrimAt = now;
+      }
+    } catch {
+    }
+  }
+  /**
+   * Replay a batch of CDC changes into this shard (point-in-time recovery).
+   * Schema-aware — it builds a `createShardCtxDb` writer — so the base class
+   * can't implement it; the codegen-generated subclass overrides this to call
+   * `applyCdcChanges(writer, args.changes)`.
+   */
+  // 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 })
+    );
+  }
+  /**
+   * Register a subscription on the given socket. Stored via
+   * `ws.serializeAttachment` so it survives hibernation.
+   *
+   * Returns a status so the caller can surface a structured error frame
+   * when the cap is hit or the attachment fails to serialize. We never
+   * throw out of this path — the WS hibernation API treats a thrown
+   * `webSocketMessage` as a fatal-channel error.
+   */
+  subscribe(ws, subId, query) {
+    const attachment = this.readAttachment(ws);
+    if (Object.keys(attachment.subs).length >= ShardDO.MAX_SUBSCRIPTIONS_PER_SOCKET) {
+      return "too_many";
+    }
+    attachment.subs[subId] = query;
+    try {
+      ws.serializeAttachment?.(attachment);
+    } catch {
+      delete attachment.subs[subId];
+      return "serialize_failed";
+    }
+    return "ok";
+  }
+  unsubscribe(ws, subId) {
+    const attachment = this.readAttachment(ws);
+    const captured = attachment.subs[subId];
+    delete attachment.subs[subId];
+    try {
+      ws.serializeAttachment?.(attachment);
+    } catch {
+      if (captured !== void 0) {
+        attachment.subs[subId] = captured;
+      }
+      return;
+    }
+    this.subMemos.get(ws)?.delete(subId);
+  }
+  /**
+   * Decide whether a single subscription is interested in a mutation
+   * delta. The default implementation checks the table name, then runs a
+   * shallow-equality predicate over `query.args` against `delta.row`. A
+   * subscription with no `args` matches every row in the table.
+   *
+   * Subclasses can override this to implement range queries, joins, or
+   * full-text matching — anything more elaborate than equality. When
+   * `delta.row` is undefined (delete events without row data) we fall back
+   * to a broadcast so subscribers know to refetch; trying to filter
+   * against missing data would silently drop legitimate notifications.
+   */
+  // eslint-disable-next-line class-methods-use-this -- protected matching hook kept non-static so subclasses can refine subscription/delta matching
+  matchesSubscription(query, delta) {
+    if (query.table !== delta.table) {
+      return false;
+    }
+    const { args } = query;
+    if (!args) {
+      return true;
+    }
+    const { row } = delta;
+    if (!row) {
+      return true;
+    }
+    for (const [key, expected] of Object.entries(args)) {
+      if (row[key] !== expected) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Broadcast a mutation delta to every subscriber whose registered query
+   * targets the affected table _and_ matches its args. The wire payload
+   * includes the per-socket subscription id, so we serialise once per
+   * `(socket, sub)` pair — but the structural delta body itself is
+   * identical, so we build a payload keyed by `subId` lazily.
+   */
+  broadcastDelta(delta) {
+    const sockets = this.state.getWebSockets();
+    const deltaJson = JSON.stringify(delta);
+    for (const ws of sockets) {
+      const attachment = this.readAttachment(ws);
+      for (const [subId, query] of Object.entries(attachment.subs)) {
+        if (!this.matchesSubscription(query, delta)) {
+          continue;
+        }
+        try {
+          ws.send(`{"type":"delta","id":${JSON.stringify(subId)},"delta":${deltaJson}}`);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Re-run a subscription's query and return its current result alongside
+   * the set of tables it read. The base class can't dispatch user functions,
+   * so it returns `null` — the codegen-generated subclass overrides this to
+   * run the handler from the project's function registry. Returning `null`
+   * disables server re-execution and leaves the legacy `broadcastDelta`
+   * path as the only live-update mechanism.
+   *
+   * `identity` is the EXPLICIT subscriber identity the query runs under. It
+   * is passed by value (anonymous by default — see {@link SubscriptionIdentity})
+   * and forwarded straight into the codegen subclass's `buildCtx`, so a
+   * subscription re-run never reads or mutates the shared, per-request
+   * `currentRequestUserId`/`currentRequestIdentity` instance fields from a
+   * deferred (`waitUntil`) or concurrently-interleaved context.
+   */
+  // 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 function map
+  executeSubscription(_functionPath, _args, _identity) {
+    return Promise.resolve(null);
+  }
+  /**
+   * Look up a streaming-query function and return a thunk that produces the
+   * `AsyncIterable&lt;unknown>` when handed an {@link AbortSignal}. The codegen
+   * subclass overrides this to dispatch via `LUNORA_FUNCTIONS`; the base
+   * default returns `null`, which surfaces as `{type:"error", code:"NOT_FOUND"}`
+   * to the client.
+   *
+   * The deferred-iterator shape (`(signal) => AsyncIterable&lt;unknown>`) keeps
+   * the cancel signal pluggable per-call without coupling this signature to
+   * the wire-frame loop in `handleStream`.
+   */
+  // 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 function map
+  executeStream(_functionPath, _args) {
+    return null;
+  }
+  /**
+   * Wrap a query handler in the reactive cache. The subclass passes the
+   * function path, parsed args, and a `run` callback that resolves to the
+   * handler's return value. When the cache is configured we key by
+   * `(functionPath, stable-stringified args)`, allocate a fresh dep
+   * tracker, store it on `this.currentTracker` so `getCtxDbReadHook` reads
+   * stamp into it, and restore the prior tracker in `finally`. When the
+   * cache is absent we just call `run()` — same shape, zero overhead.
+   *
+   * Subclasses should ALSO pass `getCtxDbReadHook()` as the `onRead`
+   * option on their `createShardCtxDb(...)` call so the tracker actually
+   * collects deps. Without that wiring the cache will memoize results
+   * with empty dep sets, so writes never invalidate them and stale
+   * results stick around — the {@link ReactiveCache} class is contract-
+   * neutral about who fills `deps`.
+   */
+  async runCachedQuery(functionPath, args, run) {
+    if (!this.reactiveCache) {
+      return run();
+    }
+    const previous = this.currentTracker;
+    const tracker = createDependencyTracker();
+    this.currentTracker = tracker;
+    const hitsBefore = this.reactiveCache.stats().hits;
+    try {
+      const result = await this.reactiveCache.run(reactiveCacheKey(functionPath, args, this.getCurrentUserId() ?? null), tracker.collect(), run);
+      this.currentRequestCacheHit = this.reactiveCache.stats().hits > hitsBefore;
+      this.currentRequestReadTables = tablesFromDeps(tracker.collect());
+      return result;
+    } finally {
+      this.currentTracker = previous;
+    }
+  }
+  /**
+   * Returns an `onRead` callback suitable to hand to `createShardCtxDb`'s
+   * `onRead` option. The returned function stamps the in-flight tracker (set
+   * by `runCachedQuery`) when one exists and is a no-op otherwise — so
+   * subclasses can wire this hook unconditionally without checking whether
+   * the cache is enabled.
+   *
+   * It ALSO records the table into {@link currentScannedTables} whenever the
+   * read was a full-table scan (the `SCAN_DEP` sentinel). That set is drained
+   * into `recordFunctionCall` after dispatch to build the durable per-function
+   * full-scan attribution — and unlike the tracker, it's collected even when
+   * the reactive cache is off, since the causal signal is independent of
+   * caching.
+   */
+  getCtxDbReadHook() {
+    return (table, idOrScan) => {
+      this.currentTracker?.recordRead(table, idOrScan ?? SCAN_DEP);
+      if (idOrScan === SCAN_DEP) {
+        this.currentScannedTables?.add(table);
+      }
+    };
+  }
+  /**
+   * Read hook recording which declared indexes a query actually exercises.
+   * Two destinations, both stamped here so a single hook serves the live and
+   * durable signals. First, the in-memory `usedIndexes` set behind the
+   * `unused_index` runtime advisory (reset on hibernation/restart — a "since
+   * this instance woke" readout, like the function/scan counters), keyed
+   * `table:index`. Second, the per-dispatch `currentIndexHits` set, drained
+   * into `recordFunctionCall` so the DURABLE `__lunora_metrics_index` hit
+   * counter (the advisor dead-index lint's producer) records one read per
+   * distinct `(table, index)` this dispatch exercised. Passed as `onIndexUse`
+   * to `createShardCtxDb` by the generated subclass.
+   */
+  getCtxDbIndexUseHook() {
+    return (table, indexName) => {
+      this.usedIndexes.add(`${table}:${indexName}`);
+      this.currentIndexHits?.add(JSON.stringify([table, indexName]));
+    };
+  }
+  /**
+   * Record that `table` was written during the current RPC. Wired into the
+   * db adapter's `broadcast` callback by the generated subclass so that
+   * `flushChangedTables` can re-run only the affected subscriptions.
+   */
+  recordChangedTable(table) {
+    this.pendingChangedTables ??= /* @__PURE__ */ new Set();
+    this.pendingChangedTables.add(table);
+  }
+  /**
+   * Per-batch progress hook for the codegen subclass's data-migration runner
+   * (wired via `runDataMigration`'s `onBatch`). The runner persists progress to
+   * the reserved {@link DATA_MIGRATION_STATE_TABLE} through raw SQL the
+   * change-tracker can't observe, so record that table here and flush — that's
+   * what re-runs live `migrationStatus` subscribers mid-run. Centralised in the
+   * base class so subclasses don't have to remember the record-then-flush dance.
+   */
+  async flushMigrationProgress() {
+    this.recordChangedTable(DATA_MIGRATION_STATE_TABLE);
+    await this.flushChangedTables();
+  }
+  /**
+   * Record one `ctx.log.*` call from a handler. Invoked by the generated
+   * `buildCtx` logger closure, which supplies the executing `functionPath` and
+   * the sink resolved from `createShardDO({ observability })` (if any).
+   *
+   * Three destinations, each best-effort so a logging call can NEVER turn a
+   * served request into a failed one. First, the in-memory {@link LogBuffer}
+   * that powers the studio's live Logs panel (it resets on hibernation, like
+   * the metrics counters). Second, a structured `{ source: "lunora", type:
+   * "log" }` console event that rides CF Workers Logs / Logpush to prod sinks
+   * and is pretty-printed by the CLI / Vite dev-server formatter in the
+   * terminal. Third, the optional programmatic `sink.onLog` — the in-process
+   * hook for users who route logs themselves (webhook/Sentry/etc.), mirroring
+   * `onRpc`.
+   *
+   * Unlike request-log args, `ctx.log` args are NOT redacted: the developer
+   * chose to log them, exactly like a raw `console.log`.
+   */
+  recordUserLog(functionPath, level, args, sink) {
+    const event = {
+      args,
+      functionPath,
+      level,
+      message: renderLogMessage(args),
+      shardKey: this.state.id?.name,
+      ts: Date.now(),
+      userId: this.getCurrentUserId()
+    };
+    this.logs.push({ functionPath, level: level === "log" ? "info" : level, message: event.message, timestamp: event.ts });
+    try {
+      emitLogEvent(event);
+    } catch {
+    }
+    if (sink?.onLog) {
+      try {
+        sink.onLog(event);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Assemble the per-socket {@link LifecycleDispatchInfo} from its attachment:
+   * the verified identity to replay and the {@link LifecycleEvent} the hooks
+   * receive as their argument. `shardKey` is this DO's shard name.
+   */
+  lifecycleInfo(attachment) {
+    const event = {
+      connectionId: attachment.connectionId ?? "",
+      shardKey: this.state.id?.name ?? ROOT_SHARD_NAME,
+      // eslint-disable-next-line unicorn/no-null -- LifecycleEvent.userId is `string | null`; null is the contractual anonymous sentinel mirrored on ctx.auth
+      userId: attachment.userId ?? null,
+      ...attachment.context === void 0 ? {} : { context: attachment.context }
+    };
+    return { event, identity: attachment.identity, userId: attachment.userId };
+  }
+  /**
+   * Run `fn` with the trusted-system flag set (restored afterwards), so an
+   * internal function dispatched through `handleRpc` is permitted. Mirrors the
+   * header-driven flag the worker's authorized path sets, without forging a
+   * header. The single toggle primitive for lifecycle-hook dispatch.
+   */
+  async withSystemDispatch(run) {
+    const previous = this.currentRequestSystem;
+    this.currentRequestSystem = true;
+    try {
+      return await run();
+    } finally {
+      this.currentRequestSystem = previous;
+    }
+  }
+  /**
+   * Emit a one-shot console warning when the `__root__` DO's SQLite file
+   * crosses {@link ROOT_DO_SIZE_WARN_BYTES} (1 GiB = 10% of the per-DO
+   * ceiling). We deliberately avoid throwing — apps should keep working;
+   * the warning is the migration signal.
+   */
+  /**
+   * Assemble the health snapshot served by `__lunora_admin__:getMetrics`:
+   * lifetime request/error counts, the live SQLite size, and (when an opt-in
+   * reactive cache is configured) its hit/miss stats.
+   *
+   * `requests`/`errors` now report the **durable** lifetime totals from the
+   * `__lunora_metrics` table (source of truth) so they survive
+   * hibernation/restart; the in-memory counters are used only as a fallback
+   * when the durable read throws. The response is extended additively with
+   * `functions` (per-function persisted rows), `history` (the coarse
+   * time-series buckets), and `indexHits` (the per-`(table, index)` hit
+   * counts) so the studio can read durable per-function metrics, chart
+   * history, and feed the advisor dead-index lint without breaking existing
+   * fields. `indexHits` is shaped exactly as the advisor's `AdvisorIndexHit`
+   * (`{ table, index, reads }`), so the studio passes it straight to
+   * `runLints({ ..., indexHits })` after summing the per-shard arrays.
+   */
+  collectMetrics() {
+    const size = this.state.storage.sql?.databaseSize;
+    let { requests } = this.metrics;
+    let { errors } = this.metrics;
+    try {
+      const totals = readFunctionMetricsTotals(this.state.storage.sql);
+      requests = totals.requests;
+      errors = totals.errors;
+    } catch {
+    }
+    let indexHits = [];
+    try {
+      indexHits = readFunctionMetricIndexHits(this.state.storage.sql);
+    } catch {
+    }
+    let queryStats = [];
+    try {
+      queryStats = readQueryMetrics(this.state.storage.sql);
+    } catch {
+    }
+    return {
+      // eslint-disable-next-line unicorn/no-null -- metrics wire shape: `cache` is `null | {...}`, null reported when the reactive cache is disabled
+      cache: this.reactiveCache ? this.reactiveCache.stats() : null,
+      // eslint-disable-next-line unicorn/no-null -- metrics wire shape: `databaseSize` is `null | number`, null when the runtime doesn't expose a size
+      databaseSize: typeof size === "number" ? size : null,
+      errors,
+      functions: this.collectFunctionStats().functions,
+      history: this.collectFunctionMetricBuckets(),
+      indexHits,
+      queryStats,
+      requests,
+      shard: this.state.id?.name ?? ROOT_SHARD_NAME,
+      sinceMs: this.metrics.sinceMs,
+      uptimeMs: Date.now() - this.metrics.sinceMs
+    };
+  }
+  /**
+   * Fold one dispatch into the per-function counters keyed by `functionPath`,
+   * creating the entry on first sight. `errorMessage` is supplied only when
+   * the handler threw, in which case the failure counters advance too.
+   * `scannedTables` carries the tables the dispatch full-scanned (collected by
+   * `getCtxDbReadHook`), which advance the causal scan attribution.
+   * `indexHits` carries the declared indexes it exercised (collected by
+   * `getCtxDbIndexUseHook`, NUL-free `JSON.stringify([table, index])` keys),
+   * which advance the durable `__lunora_metrics_index` hit counter behind the
+   * dead-index lint. Called once per `/rpc` dispatch alongside the aggregate
+   * `metrics` update.
+   *
+   * Two writes happen here. The in-memory {@link functionStats} map is kept
+   * for the fast warm-instance path, and the durable `__lunora_metrics`
+   * table is upserted so the counters survive hibernation/restart — the
+   * persisted table is the source of truth the admin RPCs read from. The
+   * persist is best-effort: a SQL failure (e.g. a test double without a
+   * `sql` handle) must never turn a successful dispatch into a failed one,
+   * so it is swallowed and the in-memory counters still advance.
+   */
+  recordFunctionCall(functionPath, durationMs, errorMessage, scannedTables, indexHits, conflicted = false) {
+    const now = Date.now();
+    const scanned = scannedTables ? [...scannedTables] : [];
+    const hits = indexHits ? [...indexHits].map((key) => decodeIndexHitKey(key)).filter((hit) => hit !== void 0) : [];
+    try {
+      recordFunctionMetric(this.state.storage.sql, {
+        conflicted,
+        durationMs,
+        errored: errorMessage !== void 0,
+        errorMessage,
+        indexHits: hits,
+        path: functionPath,
+        scannedTables: scanned,
+        ts: now
+      });
+    } catch {
+    }
+    const existing = this.functionStats.get(functionPath);
+    const stat = existing ?? {
+      calls: 0,
+      conflicts: 0,
+      errors: 0,
+      lastCalledAt: now,
+      // eslint-disable-next-line unicorn/no-null -- wire shape: `null` until the function first throws
+      lastErrorAt: null,
+      // eslint-disable-next-line unicorn/no-null -- wire shape: `null` until the function first throws
+      lastErrorMessage: null,
+      maxDurationMs: 0,
+      path: functionPath,
+      scannedTables: [],
+      scans: 0,
+      totalDurationMs: 0
+    };
+    stat.calls += 1;
+    stat.totalDurationMs += durationMs;
+    stat.maxDurationMs = Math.max(stat.maxDurationMs, durationMs);
+    stat.lastCalledAt = now;
+    if (scanned.length > 0) {
+      stat.scans += scanned.length;
+      mergeScanAttribution(stat.scannedTables, scanned);
+    }
+    if (errorMessage !== void 0) {
+      stat.errors += 1;
+      stat.lastErrorAt = now;
+      stat.lastErrorMessage = errorMessage;
+    }
+    if (conflicted) {
+      stat.conflicts += 1;
+    }
+    if (existing === void 0) {
+      this.functionStats.set(functionPath, stat);
+    }
+  }
+  /**
+   * Flush per-statement SQL samples accumulated during the current dispatch
+   * into the durable `__lunora_metrics_queries` table. Called after
+   * `recordFunctionCall` on both the success and error paths.
+   *
+   * Best-effort: a SQL failure (e.g. a test double without a usable `sql`
+   * handle) must never fail the response, so every call is swallowed.
+   * Clearing `currentStmtSamples` happens in the `finally` block of the
+   * dispatch path, not here, so a partial flush (partial error) still
+   * drains the correct slice.
+   */
+  flushStmtSamples() {
+    const samples = this.currentStmtSamples;
+    if (!samples || samples.length === 0) {
+      return;
+    }
+    try {
+      const sqlHandle = this.state.storage.sql;
+      for (const [rawSql, durationMs, rowsRead, rowsWritten] of samples) {
+        try {
+          recordQueryMetric(sqlHandle, rawSql, durationMs, rowsRead, rowsWritten);
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * Assemble the per-function readout served by
+   * `__lunora_admin__:getFunctionStats`, sorted most-recently-called first so
+   * the busiest functions surface at the top of the studio table.
+   *
+   * Reads from the durable `__lunora_metrics` table — the source of truth —
+   * so the counts reflect the function's lifetime, not just calls since this
+   * instance woke. Falls back to the in-memory map only if the durable read
+   * throws (e.g. a test double without a usable `sql` handle), keeping the
+   * warm-instance counters available even then. The wire shape is unchanged
+   * (`{ functions, sinceMs }`), so existing studio/runtime consumers keep
+   * working; the rows are now backed by persisted data.
+   */
+  collectFunctionStats() {
+    try {
+      const functions = readFunctionMetrics(this.state.storage.sql);
+      return { functions, sinceMs: this.metrics.sinceMs };
+    } catch {
+      const functions = [...this.functionStats.values()].toSorted((a, b) => b.lastCalledAt - a.lastCalledAt);
+      return { functions, sinceMs: this.metrics.sinceMs };
+    }
+  }
+  /**
+   * Per-function coarse time-series served additively by the metrics RPC, so
+   * the studio can chart call/error history. Reads the durable
+   * `__lunora_metrics_buckets` table; returns `[]` when persistence is
+   * unavailable so the response stays well-formed.
+   */
+  collectFunctionMetricBuckets() {
+    try {
+      return readFunctionMetricBuckets(this.state.storage.sql);
+    } catch {
+      return [];
+    }
+  }
+  maybeWarnRootSize() {
+    if (ShardDO.rootSizeWarned) {
+      return;
+    }
+    const idName = this.state.id?.name;
+    if (idName !== ROOT_SHARD_NAME) {
+      return;
+    }
+    const size = this.state.storage.sql?.databaseSize;
+    if (typeof size !== "number" || size < ROOT_DO_SIZE_WARN_BYTES) {
+      return;
+    }
+    ShardDO.rootSizeWarned = true;
+    console.warn(
+      `[@lunora/do] __root__ Durable Object SQLite size is ${String(size)} bytes (>= 1 GiB, 10% of the 10 GiB per-DO ceiling). Plan a \`.shardBy()\` migration before you hit the wall. See https://lunora.sh/docs/concepts/sharding for guidance.`
+    );
+  }
+  /**
+   * Map a thrown value to a JSON response. `ValidationError` from
+   * `@lunora/values` becomes a 400 with code `VALIDATION_ERROR`. A
+   * `LunoraError` keeps its declared status/code. Everything else becomes
+   * a 500 with code `RPC_FAILED`.
+   */
+  // 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);
+    }
+    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 (error && typeof error === "object" && error.name === "LunoraError") {
+      const lunoraError = error;
+      const status = typeof lunoraError.status === "number" ? lunoraError.status : 500;
+      return jsonResponse({ error: { code: lunoraError.code ?? "INTERNAL", message: lunoraError.message ?? "internal error" } }, status);
+    }
+    const message = error instanceof Error ? error.message : "unknown error";
+    return jsonResponse({ error: { code: "RPC_FAILED", message } }, 500);
+  }
+  /**
+   * Serve a reserved admin-introspection RPC (`__lunora_admin__:*`) for the
+   * data browser. Gated by `env.LUNORA_ADMIN_TOKEN`: introspection is
+   * **disabled unless the token is configured**, and when it is, the request
+   * must present a matching `Authorization: Bearer` header. The blast radius
+   * is raw table contents, so the default is closed — unlike the WebSocket
+   * upgrade gate, which defaults open for local dev.
+   */
+  async handleAdminRpc(request, functionPath, args) {
+    if (!this.isAdminAuthorized(request)) {
+      return jsonResponse({ error: { code: "ADMIN_FORBIDDEN", message: "admin introspection is disabled or the bearer token is invalid" } }, 403);
+    }
+    try {
+      const read = this.readAdminOp(functionPath, args);
+      if (read) {
+        return jsonResponse({ result: read.result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.runMigration) {
+        const parsed = parseRunMigrationArgs(args);
+        const result = await this.runShardDataMigration(parsed);
+        await this.flushChangedTables();
+        this.recordAudit("runMigration", {
+          id: parsed.id,
+          detail: { changed: result.changed, direction: result.direction, dryRun: result.dryRun, processed: result.processed }
+        });
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.exportShard) {
+        const parsed = parseExportShardArgs(args);
+        const rows = await this.runShardExport({ batchSize: parsed.batchSize, tables: parsed.tables });
+        return jsonResponse({ result: { rows } }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.importShard) {
+        const parsed = parseImportShardArgs(args);
+        const result = await this.runShardImport({ rows: parsed.rows, startLine: parsed.startLine });
+        await this.flushChangedTables();
+        this.recordAudit("importShard", { detail: { conflicts: result.conflicts, errors: result.errors.length, inserted: result.inserted } });
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.writeRow) {
+        const parsed = parseWriteRowArgs(args);
+        const result = await this.runShardWrite(parsed);
+        await this.flushChangedTables();
+        this.recordAudit("writeRow", { table: parsed.table, id: result.id ?? parsed.id, detail: { op: result.op } });
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.deleteRows) {
+        const parsed = parseBulkDeleteArgs(args);
+        const result = await this.runShardBulkDelete(parsed);
+        await this.flushChangedTables();
+        this.recordAudit("deleteRows", { table: parsed.table, detail: { deleted: result.deleted, hasMore: result.hasMore } });
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.clearTable) {
+        const parsed = parseClearTableArgs(args);
+        const result = await this.runShardBulkDelete(parsed);
+        await this.flushChangedTables();
+        this.recordAudit("clearTable", { table: parsed.table, detail: { deleted: result.deleted, hasMore: result.hasMore } });
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.rankBefore) {
+        const result = await this.runShardRankBefore(parseRankBeforeArgs(args));
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.rankPage) {
+        const result = await this.runShardRankPage(parseRankPageArgs(args));
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.cdcSync) {
+        const result = this.runShardCdcSync(parseCdcSyncArgs(args));
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.applyCdc) {
+        const result = await this.runShardApplyCdc(parseApplyCdcArgs(args));
+        await this.flushChangedTables();
+        this.recordAudit("applyCdc", { detail: { applied: result.applied } });
+        return jsonResponse({ result }, 200);
+      }
+      if (functionPath === ADMIN_FUNCTIONS.runAs) {
+        return this.handleRunAs(args);
+      }
+      const handled = await this.handleExtraAdminOp(functionPath, args);
+      if (handled) {
+        return handled;
+      }
+      return jsonResponse({ error: { code: "UNKNOWN_ADMIN_OP", message: `unknown admin op: ${functionPath}` } }, 404);
+    } catch (error) {
+      return this.errorToResponse(error);
+    }
+  }
+  /**
+   * Dispatch the side-effecting / non-read admin ops that `handleAdminRpc`
+   * doesn't handle inline: the auth-event + mail-capture writes and the native
+   * PITR ops. Returns the op's `Response`, or `undefined` when `functionPath`
+   * isn't one of these (so the caller answers 404). Kept out of
+   * `handleAdminRpc` to hold that dispatcher under the complexity budget,
+   * mirroring `handlePitrAdminOp`.
+   */
+  async handleExtraAdminOp(functionPath, args) {
+    if (functionPath === ADMIN_FUNCTIONS.recordAuthEvent) {
+      return this.handleRecordAuthEvent(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.recordContainerEvent) {
+      return this.handleRecordContainerEvent(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.recordMail) {
+      return this.handleRecordMail(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.clearCapturedMail) {
+      return this.handleClearCapturedMail();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.sendTestMail) {
+      return this.handleSendTestMail(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.createWorkflowInstance) {
+      return this.handleCreateWorkflowInstance(args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getWorkflowInstanceStatus) {
+      return this.handleGetWorkflowInstanceStatus(args);
+    }
+    return this.handlePitrAdminOp(functionPath, args);
+  }
+  /**
+   * Record one app-level auth attempt for the auth-failure SLO (PLAN3 §2.3).
+   * The worker calls this fire-and-forget (via `waitUntil`) after a top-level
+   * `/api/auth/*` ATTEMPT route returns, so it never blocks or fails the auth
+   * response. `outcome` is validated up front (400 `BAD_REQUEST` on a bad
+   * value); the durable upsert itself is best-effort — a SQL failure is
+   * swallowed so the SLO signal is simply absent rather than turning the
+   * recording call into an error. Admin-gated by `handleAdminRpc`'s caller.
+   */
+  handleRecordAuthEvent(args) {
+    const parsed = parseRecordAuthEventArgs(args);
+    try {
+      recordAuthEvent(this.state.storage.sql, { outcome: parsed.outcome, ts: Date.now() });
+    } catch {
+    }
+    return jsonResponse({ result: { recorded: true } }, 200);
+  }
+  /**
+   * Append one container lifecycle event to the in-memory {@link LogBuffer}
+   * the `getLogs` admin RPC reads, so a start/stop/error on a Container DO
+   * surfaces in the Studio Logs panel — not just the dev terminal. The
+   * Container DO pushes this best-effort (its `console` print stays the source
+   * of truth), so a missing/garbage envelope is rejected up front (400) rather
+   * than corrupting the buffer. Mapped to `functionPath: "container:&lt;name>"` so
+   * 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) {
+    const entry = parseRecordContainerEventArgs(args);
+    this.logs.push(entry);
+    return jsonResponse({ result: { recorded: true } }, 200);
+  }
+  /**
+   * Serve the `__lunora_admin__:runAs` admin RPC — the studio's "Run as
+   * identity" tool. Dispatches the target `functionPath` through the normal
+   * `handleRpc` path while the per-request identity is forged to the supplied
+   * `userId`/`identity`, so the function (and any RLS middleware it uses)
+   * observes that user instead of the admin caller.
+   *
+   * SECURITY. This op is reachable only after `handleAdminRpc`'s
+   * `isAdminAuthorized` bearer check (the `LUNORA_ADMIN_TOKEN` gate), so an
+   * unauthenticated caller can never forge an identity. The inbound
+   * `x-lunora-userid`/`x-lunora-identity` headers the runtime sets are
+   * overwritten here for the duration of the dispatch and restored after, so
+   * the forge can't leak into a later request. The target path is validated to
+   * be a non-admin function, so it can't be used to re-enter the admin plane.
+   * The studio only surfaces this tool behind a loopback-dev gate.
+   */
+  async handleRunAs(args) {
+    const parsed = parseRunAsArgs(args);
+    const result = await this.withRequestIdentity(parsed.userId, parsed.identity, () => this.handleRpc(parsed.functionPath, parsed.args));
+    await this.flushChangedTables();
+    this.recordAudit("runAs", { detail: { functionPath: parsed.functionPath, runAsUserId: parsed.userId } });
+    return jsonResponse({ result }, 200);
+  }
+  /* eslint-disable no-secrets/no-secrets -- reserved admin RPC names are framework constants, not credentials */
+  /**
+   * Resolve a declared workflow's runtime binding handle from this shard's `env`.
+   * Looks the `exportName` up in {@link workflowsMetadata} (the codegen subclass's
+   * statically-discovered list) to find its generated `WORKFLOW_*` binding, then
+   * reads `env[binding]` and validates it carries the `create`/`get` methods. A
+   * bad export name or a missing/malformed binding throws a 400 `LunoraError` so
+   * the studio surfaces an actionable message instead of a generic 500.
+   */
+  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 });
+    }
+    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
+      });
+    }
+    return binding;
+  }
+  /**
+   * Serve `__lunora_admin__:createWorkflowInstance` — the studio's "Start
+   * instance" button. Resolves the declared workflow's `WORKFLOW_*` binding and
+   * calls `.create({ id?, params })`, returning the new instance's id and initial
+   * status. No SQLite write happens (workflows are not Durable Objects and hold
+   * no shard state), so this only records an audit entry — there's nothing to
+   * flush. Admin-gated by `handleAdminRpc`'s caller.
+   */
+  async handleCreateWorkflowInstance(args) {
+    const parsed = parseCreateWorkflowInstanceArgs(args);
+    const binding = this.resolveWorkflowBinding(parsed.exportName);
+    const instance = await binding.create({ id: parsed.id, params: parsed.params });
+    const snapshot = await instance.status();
+    const result = { id: instance.id, status: toWorkflowInstanceState(snapshot.status) };
+    this.recordAudit("createWorkflowInstance", { id: instance.id, detail: { exportName: parsed.exportName } });
+    return jsonResponse({ result }, 200);
+  }
+  /**
+   * Serve `__lunora_admin__:getWorkflowInstanceStatus` — the studio's instance
+   * observer. Resolves the workflow binding, fetches the instance handle by id,
+   * and reports its current status plus output/error when present. Read-only:
+   * inspecting an instance mutates no shard state, so nothing is flushed or
+   * audited. Admin-gated by `handleAdminRpc`'s caller.
+   */
+  async handleGetWorkflowInstanceStatus(args) {
+    const parsed = parseGetWorkflowInstanceStatusArgs(args);
+    const binding = this.resolveWorkflowBinding(parsed.exportName);
+    const instance = await binding.get(parsed.id);
+    const snapshot = await instance.status();
+    const result = {
+      error: toWorkflowInstanceError(snapshot.error),
+      id: parsed.id,
+      output: snapshot.output,
+      status: toWorkflowInstanceState(snapshot.status)
+    };
+    return jsonResponse({ result }, 200);
+  }
+  /* eslint-enable no-secrets/no-secrets */
+  /**
+   * 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
+   * forced identity can never leak into a later dispatch on this DO instance. The
+   * generated `buildCtx` reads identity via `getCurrentUserId`/`getCurrentIdentity`,
+   * so pinning the fields around the call makes the dispatched function observe the
+   * chosen identity without threading it through the generated signature.
+   *
+   * The single caller is {@link handleRunAs} (pins a forged user — the dev
+   * "Run as identity" tool), which runs synchronously on the request thread
+   * with no intervening concurrent dispatch. Subscriptions deliberately do NOT
+   * use this primitive: they run in deferred/interleaved contexts where
+   * mutating the shared field would race a concurrent RPC, so they thread an
+   * explicit {@link SubscriptionIdentity} into `executeSubscription` instead.
+   */
+  async withRequestIdentity(userId, identity, run) {
+    const previousUserId = this.currentRequestUserId;
+    const previousIdentity = this.currentRequestIdentity;
+    this.currentRequestUserId = userId;
+    this.currentRequestIdentity = identity;
+    try {
+      return await run();
+    } finally {
+      this.currentRequestUserId = previousUserId;
+      this.currentRequestIdentity = previousIdentity;
+    }
+  }
+  /**
+   * Capture one outbound message into the dev mail catcher (`mail-catcher.ts`).
+   * `@lunora/mail`'s capture transport POSTs each rendered, validated send here
+   * (fire-and-forget) so the studio's Mail inbox shows it. Admin-gated by
+   * `handleAdminRpc`'s caller, so only a request bearing `LUNORA_ADMIN_TOKEN`
+   * can record — and the worker only ever calls this when the capture transport
+   * is wired (dev). Validates the payload (400 on a bad shape) and returns the
+   * generated id.
+   *
+   * Note: the gate is the admin token alone — the same trust boundary that
+   * already protects every other admin write (`writeRow`, `clearTable`,
+   * `deleteRows`, `runSql`). A token holder can already mutate the shard
+   * arbitrarily, so a token-gated mailbox insert adds no new privilege; the DO
+   * has no signal for "capture is active", so an inert-unless-capture guard
+   * isn't enforced here (an accepted relaxation of plan 011's STOP condition).
+   */
+  handleRecordMail(args) {
+    const parsed = parseRecordMailArgs(args);
+    const result = recordCapturedMail(this.state.storage.sql, parsed, Date.now());
+    return jsonResponse({ result }, 200);
+  }
+  /** Empty the dev mail-catcher inbox (studio "clear inbox" action). Admin-gated by the caller. */
+  handleClearCapturedMail() {
+    const result = clearCapturedMail(this.state.storage.sql);
+    return jsonResponse({ result }, 200);
+  }
+  /**
+   * Populate the dev mail-catcher inbox with one synthetic message (studio
+   * "Send test" button) so the inbox can be exercised in one click. Builds the
+   * message via {@link buildTestMailInput} (validating the optional `to`) and
+   * records it through the same `recordCapturedMail` path as a real capture.
+   * Admin-gated by `handleAdminRpc`'s caller.
+   */
+  handleSendTestMail(args) {
+    const input = buildTestMailInput(args);
+    const result = recordCapturedMail(this.state.storage.sql, input, Date.now());
+    return jsonResponse({ result }, 200);
+  }
+  /**
+   * Append one durable audit entry for a state-changing admin op that just
+   * succeeded, folding the acting user (from `getCurrentUserId`) into `detail`.
+   * Called only on the success path, so a rejected/validated op leaves no
+   * trace. Best-effort: the write happens after the op's own commit, so it
+   * never blocks or fails the response.
+   */
+  recordAudit(op, fields = {}) {
+    const sql = this.state.storage.sql;
+    const userId = this.getCurrentUserId();
+    const detail = userId === void 0 ? fields.detail : { ...fields.detail, userId };
+    appendAuditEntry(sql, { detail, id: fields.id, op, table: fields.table, ts: Date.now() });
+  }
+  /**
+   * Append one structured entry to the durable request log (`request-log.ts`)
+   * for a `/rpc` dispatch that just completed — the per-request readout
+   * (`&lt;file>:&lt;function>`, shard key, acting user/identity, redacted args,
+   * outcome, duration, tables read/written, cache hit) that Cloudflare cannot
+   * attribute (PLAN3 §1.1). When `LUNORA_REQUEST_LOG_EMIT` is set, the same
+   * entry is ALSO emitted as a structured console event for CF Workers Logs /
+   * Logpush to ship to external SIEMs (PLAN3 §3.3) — see `requestLogConfig`.
+   *
+   * Volume is bounded by two knobs (`requestLogConfig`): SUCCESSFUL dispatches
+   * are sampled at `LUNORA_REQUEST_LOG_SAMPLE` (errors always recorded) and the
+   * durable rows are trimmed to `LUNORA_REQUEST_LOG_RETENTION`. Args/identity
+   * are redacted by default and captured raw only in a dev environment.
+   *
+   * Best-effort, exactly like `recordFunctionCall`'s durable upsert: a SQL
+   * failure (e.g. a test double without a `sql` handle) must NEVER turn a
+   * served request into a failed one, so it is swallowed. Args are redacted
+   * inside `appendRequestLogEntry` so a raw value never reaches the table.
+   *
+   * The correlated fields all come from data the dispatch already holds, with
+   * no extra hot-path bookkeeping. `tablesWritten` is snapshotted from
+   * `pendingChangedTables` by the caller before `flushChangedTables` drains it.
+   * `tablesRead` and `cacheHit` are captured by `runCachedQuery`, so they are
+   * present only for cached query paths — a write/action doesn't run through
+   * the cache, and an instance with the reactive cache disabled never captures
+   * them — and are left empty/`undefined` rather than recomputed here.
+   * `subscriptionsReRun` is left `0`: the write-driven subscription refresh
+   * runs off the response path via `waitUntil` (see `flushChangedTables`), so a
+   * per-request count isn't available synchronously at this site, and threading
+   * one back would add bookkeeping to the deferred fan-out for no correctness
+   * benefit — recorded as `0` with this note rather than faked.
+   */
+  recordRequestLog(functionPath, args, durationMs, outcome, tablesWritten, errorMessage) {
+    const config = this.requestLogConfig();
+    if (outcome === "ok" && !sampleHit(config.sampleRate)) {
+      return;
+    }
+    const entry = {
+      cacheHit: this.currentRequestCacheHit,
+      durationMs,
+      errorMessage,
+      functionPath,
+      identity: this.currentRequestIdentity,
+      outcome,
+      redactedArgs: Object.keys(args).length === 0 ? void 0 : args,
+      shardKey: this.state.id?.name,
+      tablesRead: this.currentRequestReadTables === void 0 ? [] : [...this.currentRequestReadTables],
+      tablesWritten,
+      ts: Date.now(),
+      userId: this.getCurrentUserId()
+    };
+    const writeOptions = { captureRaw: config.captureRaw, retention: config.retention };
+    try {
+      appendRequestLogEntry(this.state.storage.sql, entry, writeOptions);
+    } catch {
+    }
+    if (config.emit || outcome === "error") {
+      try {
+        emitRequestLogEvent(entry, writeOptions);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Resolve the request-log knobs from the Worker `env`, all PLAN3 §3.3 decisions.
+   *
+   * `captureRaw`: raw (un-redacted) args/identity in a dev environment, redacted
+   * in production (`isDevEnvironment`) — default redacted.
+   *
+   * `emit`: also stream each entry as a console event for CF Workers Logs /
+   * Logpush (and the dev-server terminal). Explicit `LUNORA_REQUEST_LOG_EMIT`
+   * (`"1"`/`"true"` vs `"0"`/`"false"`) always wins; unset, it defaults to
+   * `isDevEnvironment` — ON in dev so a developer sees every dispatch, OFF in
+   * production where a line per dispatch is log volume an operator opts into.
+   * Errors stream regardless (see `recordRequestLog`).
+   *
+   * `retention`: durable-row cap override (`LUNORA_REQUEST_LOG_RETENTION`);
+   * `undefined` falls back to the module default.
+   *
+   * `sampleRate`: fraction of SUCCESSFUL dispatches recorded
+   * (`LUNORA_REQUEST_LOG_SAMPLE`, 0..1, default 1.0 = all); errors always record.
+   */
+  requestLogConfig() {
+    const env = this.env ?? {};
+    return {
+      captureRaw: isDevEnvironment(this.env),
+      emit: parseEmit(env.LUNORA_REQUEST_LOG_EMIT, isDevEnvironment(this.env)),
+      retention: parsePositiveInt(env.LUNORA_REQUEST_LOG_RETENTION),
+      sampleRate: parseSampleRate(env.LUNORA_REQUEST_LOG_SAMPLE)
+    };
+  }
+  /**
+   * Native Durable-Object PITR ops (the ≤30-day in-place tier). `getPitrBookmark`
+   * reads the current/for-time bookmark; `pitrRestore` arms a restore to a
+   * bookmark/time (auditing the target + undo bookmark before any restart, so the
+   * undo point survives even if `abort()` drops the response). Returns `null` when
+   * `functionPath` isn't a PITR op so the caller falls through. Kept out of
+   * `handleAdminRpc` to hold that dispatcher under the complexity budget.
+   */
+  async handlePitrAdminOp(functionPath, args) {
+    const time = typeof args.time === "number" || typeof args.time === "string" ? args.time : void 0;
+    if (functionPath === ADMIN_FUNCTIONS.getPitrBookmark) {
+      return jsonResponse({ result: await readBookmark(this.state.storage, time) }, 200);
+    }
+    if (functionPath !== ADMIN_FUNCTIONS.pitrRestore) {
+      return void 0;
+    }
+    const restart = args.restart === true;
+    const bookmark = typeof args.bookmark === "string" ? args.bookmark : void 0;
+    const armed = await armRestore(this.state.storage, { bookmark, time });
+    if (this.cdcEnabled()) {
+      bumpCdcEpoch(this.sql);
+    }
+    this.recordAudit("pitrRestore", { detail: { restart, restoredTo: armed.restoredTo, undoBookmark: armed.undoBookmark } });
+    const response = jsonResponse({ result: { ...armed, restarted: restart } }, 200);
+    if (restart) {
+      this.state.abort?.("lunora PITR restore");
+    }
+    return response;
+  }
+  /**
+   * Run a single read-only admin introspection op, returning its result plus
+   * the table-dependency set the subscription bridge uses to decide when to
+   * re-run it. Write/migration/export ops are NOT handled here — they stay in
+   * `handleAdminRpc` because they mutate state and can't be safely
+   * re-executed on every write-flush. Returns `null` for any non-read op.
+   *
+   * `readTablePage` depends on exactly the table it reads, so a write to an
+   * unrelated table never re-runs it. The counter/log ops (`getMetrics`,
+   * `getLogs`, `listTables`, `migrationStatus`) aren't bound to a single
+   * table; they carry the {@link ADMIN_WILDCARD} sentinel so
+   * `refreshSubscriptions` re-runs them on every write-flush. The
+   * per-socket JSON memo in `pushSubscriptionData` still suppresses
+   * pushes when the recomputed value is byte-identical.
+   * @returns the result and table-dependency set for a read op, or `null` for a write/migration op
+   */
+  readAdminOp(functionPath, args) {
+    this.ensureMigrated();
+    const sql = this.state.storage.sql;
+    const wildcardRead = this.readAdminWildcardOp(functionPath);
+    if (wildcardRead !== void 0) {
+      return { result: wildcardRead, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getAuditLog) {
+      return this.readAdminAuditLog(sql, args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getRequestLog) {
+      return this.readAdminRequestLog(sql, args);
+    }
+    const durable = this.readAdminDurableSignal(functionPath, sql, args);
+    if (durable) {
+      return durable;
+    }
+    if (functionPath === ADMIN_FUNCTIONS.readTablePage) {
+      return this.readAdminTablePage(sql, args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.facetColumn) {
+      return this.readAdminFacetColumn(sql, args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.runSql) {
+      return this.readAdminRunSql(sql, args);
+    }
+    const tableSignal = this.readAdminTableSignal(functionPath, sql, args);
+    if (tableSignal) {
+      return tableSignal;
+    }
+    const storage = this.readAdminStorageSignal(functionPath, sql, args);
+    if (storage) {
+      return storage;
+    }
+    return null;
+  }
+  /**
+   * Resolve the table-scoped introspection reads whose payload is a single
+   * `this.*()` lookup keyed by an optional `table` arg — `listTableIndexes`
+   * (declared indexes), `describeTable` (declared columns) and `migrationStatus`
+   * (the migration ledger). The first two carry their `table` (or the
+   * {@link ADMIN_WILDCARD} sentinel when unscoped); `migrationStatus` is
+   * deployment-wide, so it always carries the wildcard. Returns `undefined` for
+   * any other path so {@link readAdminOp} falls through; folded into one helper
+   * to keep that dispatcher under its complexity budget.
+   * @returns the read result and its table-dependency set, or `undefined` when the path is not owned by this resolver
+   */
+  readAdminTableSignal(functionPath, sql, args) {
+    if (functionPath === ADMIN_FUNCTIONS.listTableIndexes || functionPath === ADMIN_FUNCTIONS.describeTable) {
+      const table = typeof args["table"] === "string" ? args["table"] : "";
+      const result = functionPath === ADMIN_FUNCTIONS.describeTable ? { columns: this.tableColumns(table) } : { indexes: this.tableIndexes(table) };
+      return { result, tables: /* @__PURE__ */ new Set([table === "" ? ADMIN_WILDCARD : table]) };
+    }
+    if (functionPath === ADMIN_FUNCTIONS.describeTables) {
+      const requested = Array.isArray(args["tables"]) ? args["tables"].filter((table) => typeof table === "string") : [];
+      const columnsByTable = Object.fromEntries(requested.map((table) => [table, this.tableColumns(table)]));
+      return { result: { columnsByTable }, tables: new Set(requested.length === 0 ? [ADMIN_WILDCARD] : requested) };
+    }
+    if (functionPath === ADMIN_FUNCTIONS.migrationStatus) {
+      const id = typeof args["id"] === "string" ? args["id"] : void 0;
+      return { result: { migrations: readMigrationStatus(sql, id) }, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+    }
+    return void 0;
+  }
+  /**
+   * Resolve the storage↔schema correlation admin reads — the file browser's
+   * records↔files join (`storageReferences`, object→owning-record + per-key
+   * orphans) and its inverse (`storageOrphans`, dangling references: records
+   * pointing at a missing object). Both scan only the schema's declared
+   * `v.storage()` columns. Returns `undefined` for any other path so
+   * {@link readAdminOp} falls through; folded into one helper to keep that
+   * dispatcher under its complexity budget.
+   * @returns the read result and its table-dependency set, or `undefined` when the path is not owned by this resolver
+   */
+  readAdminStorageSignal(functionPath, sql, args) {
+    if (functionPath === ADMIN_FUNCTIONS.storageReferences) {
+      return this.readAdminStorageReferences(sql, args);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.storageOrphans) {
+      return this.readAdminStorageOrphans(sql, args);
+    }
+    return void 0;
+  }
+  /**
+   * Resolve a `storageReferences` admin read — the file browser's records↔files
+   * join: given the object keys on the page, return the rows that reference each
+   * (via a `v.storage()` column) plus the schema's declared storage columns.
+   * Scans only those columns through {@link findStorageReferences}. Carries the
+   * {@link ADMIN_WILDCARD} (it spans every storage table) so a live subscription
+   * re-runs on any write.
+   */
+  readAdminStorageReferences(sql, args) {
+    const keys = Array.isArray(args["keys"]) ? args["keys"].filter((key) => typeof key === "string") : [];
+    return { result: findStorageReferences(sql, this.storageColumns(), keys), tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+  }
+  /**
+   * Resolve a `storageOrphans` admin read — the inverse of the records↔files
+   * join: given the set of object keys that actually exist in the bucket
+   * (`liveKeys`, the studio's enumerated listing), return every record
+   * `v.storage()` field whose value points at a key the bucket DOES NOT have — a
+   * **dangling reference**. CF's R2 browser can never make this join. Scans only
+   * the schema's declared storage columns through {@link findDanglingReferences},
+   * bounded with a `truncated` flag (logged once when set). Carries the
+   * {@link ADMIN_WILDCARD} (it spans every storage table) so a live subscription
+   * re-runs on any write.
+   */
+  readAdminStorageOrphans(sql, args) {
+    const liveKeys = Array.isArray(args["liveKeys"]) ? args["liveKeys"].filter((key) => typeof key === "string") : [];
+    const result = findDanglingReferences(sql, this.storageColumns(), liveKeys);
+    if (result.truncated) {
+      console.warn(
+        `[@lunora/do] storageOrphans scan truncated after checking ${String(result.scanned)} storage references; reporting the first ${String(result.references.length)} dangling reference(s).`
+      );
+    }
+    return { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+  }
+  /**
+   * Resolve the read-only admin ops whose result isn't bound to a single table
+   * — the in-memory counters (`getMetrics`, `getFunctionStats`), the table list
+   * (`listTables`), the in-memory error buffer (`getLogs`) and the masked
+   * deployment config (`getSettings`). Returns the result value, or `undefined`
+   * for any path it doesn't own (so `readAdminOp` falls through). The caller
+   * wraps each in the {@link ADMIN_WILDCARD} sentinel, keeping that one fact in
+   * a single place and `readAdminOp` under its complexity budget.
+   */
+  readAdminWildcardOp(functionPath) {
+    if (functionPath === ADMIN_FUNCTIONS.listTables) {
+      return listTables(this.state.storage.sql);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getMetrics) {
+      return this.collectMetrics();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getFunctionStats) {
+      return this.collectFunctionStats();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.listSubscriptions) {
+      return this.collectSubscriptions();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getLogs) {
+      return { entries: this.logs.entries() };
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getSettings) {
+      return buildSettings(this.env);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getSecurityAudit) {
+      return buildSecurityAudit(this.env);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getAdvisories) {
+      return { advisories: [...this.advisories(), ...this.runtimeAdvisories()] };
+    }
+    if (functionPath === ADMIN_FUNCTIONS.rlsPolicies) {
+      return this.rlsMetadata();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.maskPolicies) {
+      return this.maskMetadata();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.storageRules) {
+      return this.storageRulesMetadata();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.studioFeatures) {
+      return this.studioFeatures();
+    }
+    if (functionPath === ADMIN_FUNCTIONS.listWorkflows) {
+      return this.workflowsMetadata();
+    }
+    return void 0;
+  }
+  /**
+   * Enumerate every connected WebSocket and the subscriptions it tracks for
+   * the `__lunora_admin__:listSubscriptions` realtime inspector. Reads each
+   * socket's hibernation attachment (admin flag + live `subs` map) and folds
+   * them into a {@link SubscriptionsResult} via {@link summarizeSubscriptions}.
+   * Read-only: it touches no SQLite and mutates no socket state.
+   */
+  collectSubscriptions() {
+    return summarizeSubscriptions(this.state.getWebSockets().map((ws) => this.readAttachment(ws)));
+  }
+  /** 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) {
+    ensureAuditTable(sql);
+    const limit = typeof args["limit"] === "number" ? args["limit"] : void 0;
+    const sinceSeq = typeof args["sinceSeq"] === "number" ? args["sinceSeq"] : void 0;
+    const result = { entries: readAuditLog(sql, { limit, sinceSeq }) };
+    return { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+  }
+  /**
+   * Resolve a `getRequestLog` admin read, parsing the optional correlation
+   * filters (function-path prefix, exact userId/shardKey/outcome, table-touched)
+   * plus the `limit`/`sinceSeq` cursor, and ensuring the reserved table first.
+   * Carries the {@link ADMIN_WILDCARD} like the other log reads so a live Logs
+   * 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 and future per-instance state
+  readAdminRequestLog(sql, args) {
+    ensureRequestLogTable(sql);
+    const outcome = args["outcome"] === "ok" || args["outcome"] === "error" ? args["outcome"] : void 0;
+    const result = {
+      entries: readRequestLog(sql, {
+        functionPathPrefix: typeof args["functionPathPrefix"] === "string" ? args["functionPathPrefix"] : void 0,
+        limit: typeof args["limit"] === "number" ? args["limit"] : void 0,
+        outcome,
+        shardKey: typeof args["shardKey"] === "string" ? args["shardKey"] : void 0,
+        sinceSeq: typeof args["sinceSeq"] === "number" ? args["sinceSeq"] : void 0,
+        tableTouched: typeof args["tableTouched"] === "string" ? args["tableTouched"] : 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
+   * charts (PLAN3 §2.3). Auth runs as a top-level `/api/auth/*` worker route,
+   * NOT through lunora functions, so the worker records each attempt against
+   * the root shard via `recordAuthEvent` and this read surfaces the rollup.
+   *
+   * Best-effort: a SQL failure (e.g. a test double without a real `sql`
+   * handle) returns an empty all-zero {@link AuthMetrics} rather than throwing,
+   * so the SLO signal is simply absent instead of breaking the studio.
+   * Carries the {@link ADMIN_WILDCARD} like the other counter reads so a live
+   * subscription re-runs on every write-flush (the per-socket JSON memo still
+   * suppresses byte-identical pushes).
+   */
+  /**
+   * Resolve the durable app-signal reads that aren't bound to a user table —
+   * the auth-metrics rollup and the dev mail-catcher inbox. Returns the read's
+   * `{ result, tables }`, or `undefined` for any path it doesn't own (so
+   * `readAdminOp` falls through). Keeps `readAdminOp` under its complexity
+   * budget by holding these two in one branch.
+   * @returns the read result and its table-dependency set, or `undefined` when the path is not owned by this resolver
+   */
+  readAdminDurableSignal(functionPath, sql, args) {
+    if (functionPath === ADMIN_FUNCTIONS.getAuthMetrics) {
+      return this.readAdminAuthMetrics(sql);
+    }
+    if (functionPath === ADMIN_FUNCTIONS.getCapturedMail) {
+      return this.readAdminCapturedMail(sql, args);
+    }
+    return void 0;
+  }
+  // eslint-disable-next-line class-methods-use-this -- kept an instance method for symmetry with the other `readAdmin*` resolvers
+  readAdminAuthMetrics(sql) {
+    let result;
+    try {
+      result = readAuthMetrics(sql);
+    } catch {
+      result = { attempts: 0, failureRate: 0, failures: 0, history: [], sinceMs: 0 };
+    }
+    return { result, tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+  }
+  /**
+   * Resolve a `getCapturedMail` admin read — the dev mail catcher's inbox
+   * (`mail-catcher.ts`), newest-first. Best-effort: a SQL failure returns an
+   * empty inbox rather than throwing. Bound to the {@link MAIL_TABLE} so a live
+   * studio subscription re-runs when a new message is recorded (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
+  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 `readTablePage` admin read, parsing the loosely-typed args into the reader's options. */
+  readAdminTablePage(sql, args) {
+    const table = typeof args["table"] === "string" ? args["table"] : "";
+    const page = readTablePage(sql, {
+      filters: parseTablePageFilters(args["filters"]),
+      limit: typeof args["limit"] === "number" ? args["limit"] : void 0,
+      offset: typeof args["offset"] === "number" ? args["offset"] : void 0,
+      orderBy: parseTablePageOrderBy(args["orderBy"]),
+      refs: this.tableRefs(table),
+      search: typeof args["search"] === "string" ? args["search"] : void 0,
+      table
+    });
+    return { result: page, tables: /* @__PURE__ */ new Set([table === "" ? ADMIN_WILDCARD : table]) };
+  }
+  /**
+   * Resolve a `facetColumn` admin read — Datasette-style per-column value/count
+   * summary over the active view. Reuses {@link readTablePage}'s predicate args
+   * (`filters` + `search`) so the facet reflects exactly the previewed rows; the
+   * `column` is validated + bound inside {@link facetColumn} (never interpolated).
+   * Read-only `SELECT … GROUP BY`. Depends on its table like {@link readAdminTablePage}.
+   */
+  // eslint-disable-next-line class-methods-use-this -- instance method for symmetry with the other `readAdmin*` resolvers
+  readAdminFacetColumn(sql, args) {
+    const table = typeof args["table"] === "string" ? args["table"] : "";
+    const result = facetColumn(sql, {
+      column: typeof args["column"] === "string" ? args["column"] : "",
+      filters: parseTablePageFilters(args["filters"]),
+      limit: typeof args["limit"] === "number" ? args["limit"] : void 0,
+      search: typeof args["search"] === "string" ? args["search"] : void 0,
+      table
+    });
+    return { result, tables: /* @__PURE__ */ new Set([table === "" ? ADMIN_WILDCARD : table]) };
+  }
+  /**
+   * Resolve a `runSql` admin read: execute a read-only SQL query against the
+   * shard's SQLite via {@link runReadonlySql} (which rejects every mutating
+   * statement). Carries the {@link ADMIN_WILDCARD} since an arbitrary query can
+   * touch any table; it is a one-shot read, never a live subscription.
+   */
+  // eslint-disable-next-line class-methods-use-this -- instance method for symmetry with the other `readAdmin*` resolvers
+  readAdminRunSql(sql, args) {
+    const query = typeof args["sql"] === "string" ? args["sql"] : "";
+    return { result: runReadonlySql(sql, query), tables: /* @__PURE__ */ new Set([ADMIN_WILDCARD]) };
+  }
+  /**
+   * Seed/refresh hook for `__lunora_admin__:*` subscriptions, mirroring
+   * `executeSubscription` for user functions. Returns `null` for any
+   * path that isn't a read-only admin op so the caller can fall through.
+   * Synchronous — admin reads hit raw SQLite directly, no async dispatch.
+   */
+  executeAdminSubscription(functionPath, args) {
+    const read = this.readAdminOp(functionPath, args);
+    return read ? { result: read.result, tables: read.tables } : null;
+  }
+  /**
+   * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
+   * `false` (closed) when the token is unset so admin introspection is
+   * opt-in rather than exposed by default.
+   */
+  isAdminAuthorized(request) {
+    const env = this.env ?? {};
+    const token = env.LUNORA_ADMIN_TOKEN;
+    if (!token || token.length === 0) {
+      return false;
+    }
+    const supplied = extractBearerToken(request.headers.get("authorization"));
+    return supplied !== void 0 && constantTimeEqual(supplied, token);
+  }
+  /**
+   * Drive a streaming-query iterator end-to-end:
+   * 1. Allocate a per-id {@link AbortController} so a later `unsubscribe`
+   * (or socket close) tears the user iterator down.
+   * 2. Send a `{type:"ack"}` so the client knows the stream started before
+   * any chunks land.
+   * 3. Pump every yielded chunk through a `{type:"chunk"}` frame.
+   * 4. On normal completion send `{type:"complete"}`; on throw send
+   * `{type:"error"}`. Either way drop the controller.
+   */
+  async handleStream(ws, id, functionPath, args) {
+    const iterable = this.executeStream(functionPath, args);
+    if (!iterable) {
+      ws.send(JSON.stringify({ error: { code: "NOT_FOUND", message: `stream not registered: ${functionPath}` }, id, type: "error" }));
+      return;
+    }
+    let cancellers = this.streamCancellers.get(ws);
+    if (!cancellers) {
+      cancellers = /* @__PURE__ */ new Map();
+      this.streamCancellers.set(ws, cancellers);
+    }
+    if (cancellers.size >= ShardDO.MAX_STREAMS_PER_SOCKET) {
+      try {
+        ws.send(
+          JSON.stringify({
+            error: { code: "TOO_MANY_STREAMS", message: `stream cap of ${String(ShardDO.MAX_STREAMS_PER_SOCKET)} reached on this socket` },
+            id,
+            type: "error"
+          })
+        );
+      } catch {
+      }
+      return;
+    }
+    const controller = new AbortController();
+    cancellers.set(id, controller);
+    ws.send(JSON.stringify({ id, type: "ack" }));
+    try {
+      for await (const chunk of iterable.iterator(controller.signal)) {
+        if (controller.signal.aborted) {
+          break;
+        }
+        await awaitWsDrain(ws);
+        ws.send(JSON.stringify({ data: 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);
+      ws.send(
+        JSON.stringify({
+          error: { code: typeof code === "string" ? code : "INTERNAL_SERVER_ERROR", message },
+          id,
+          type: "error"
+        })
+      );
+    } finally {
+      cancellers.delete(id);
+      if (cancellers.size === 0) {
+        this.streamCancellers.delete(ws);
+      }
+    }
+  }
+  /**
+   * Drain the tables written during the in-flight RPC and re-run every
+   * subscription that depends on one of them. Called after `handleRpc`
+   * resolves, and per-batch during a data migration via
+   * `flushMigrationProgress`. No-op when nothing was written.
+   *
+   * When the DO state exposes `waitUntil`, the refresh runs off the
+   * response path so the client doesn't block on subscription fan-out —
+   * a wide subscription set on a hot DO could otherwise add tens of ms
+   * to every write's tail latency. The user-facing write is already
+   * durable by the time we return; subscribers observe the change
+   * shortly after.
+   */
+  async flushChangedTables() {
+    const changed = this.pendingChangedTables;
+    this.pendingChangedTables = void 0;
+    if (!changed || changed.size === 0) {
+      return;
+    }
+    if (typeof this.state.waitUntil === "function") {
+      this.state.waitUntil(this.refreshSubscriptions(changed));
+      return;
+    }
+    await this.refreshSubscriptions(changed);
+  }
+  /**
+   * For every live subscription whose query reads one of `changed`, re-run
+   * the query and push a fresh `{ type: "data" }` frame when the result
+   * differs from the last one sent. Subscriptions with no `functionPath`
+   * (legacy delta-only) are left to `broadcastDelta`.
+   *
+   * The per-socket loop runs in parallel across sockets, bounded so a
+   * shard with thousands of live subscribers doesn't spin up thousands
+   * of `executeSubscription` calls in lockstep and saturate the DO
+   * isolate. Within a single socket we stay sequential — the same
+   * subscription set is small (cap of {@link ShardDO.MAX_SUBSCRIPTIONS_PER_SOCKET}).
+   *
+   * ----------------------------------------------------------------------
+   * Audit finding #5 — N identical subscriptions ⇒ N query runs per change.
+   * ----------------------------------------------------------------------
+   * This loop executes `executeSubscription` once PER (socket, sub). When N
+   * sockets subscribe to the SAME `(functionPath, args)`, a single write that
+   * touches a read table re-runs the identical query N times. The N-runs
+   * fan-out is characterized by the `profile:` case in
+   * `subscription-refresh.integration.test.ts`.
+   *
+   * Cross-socket execution dedup (group identical `(functionPath, args)`, run
+   * + serialize once, fan the same frame to every sharing socket) was
+   * INVESTIGATED and DELIBERATELY NOT implemented here, because it would change
+   * observable behavior rather than being a pure optimization:
+   *
+   * (a) Per-socket memo divergence. The frame a socket receives depends on its
+   * OWN `subMemos` entry (`pushSubscriptionData`): one socket may need a
+   * `{type:"delta"}`, a freshly-subscribed socket a full `{type:"data"}`
+   * snapshot, and an up-to-date socket nothing at all. So only the QUERY RUN +
+   * its result can be shared — `pushSubscriptionData` must still run per socket.
+   * Dedup saves the N-1 redundant runs, not the fan-out.
+   *
+   * (b) Side-effect cardinality. The real `executeSubscription` lives in the
+   * codegen subclass and dispatches the user handler, which records function
+   * metrics, scan attribution, and `ctx.log` lines PER RUN. N subscribers today
+   * produce N metric samples / N log lines; collapsing to one run silently
+   * under-counts those in the studio. The base class can't see inside the
+   * override, so it can't make that trade safely.
+   *
+   * (c) Error attribution. A throwing run is contained per (socket, sub) here
+   * (see the catch below, and the integration test's isolation cases). A shared
+   * run would have to fan one failure to every sharing socket while preserving
+   * the "leave memo untouched ⇒ re-run next flush" contract.
+   *
+   * The framework's INTENDED answer to this fan-out already exists: the opt-in
+   * {@link ReactiveCache} (`ShardDOOptions.reactiveCache`). Refreshes run with
+   * an explicit anonymous {@link SubscriptionIdentity}, so the cache key
+   * `reactiveCacheKey(functionPath, args, null)` is identical across all
+   * sockets — N identical subscriptions collapse to ONE handler run plus N
+   * cache hits, with every per-run side effect honored exactly once by design.
+   * Recommended remediation is to document/enable ReactiveCache for
+   * high-fanout shards rather than bolt a second, semantically-divergent dedup
+   * into this loop.
+   */
+  async refreshSubscriptions(changed) {
+    const sockets = [...this.state.getWebSockets()];
+    const frameCursor = this.currentCdcCursor();
+    const frameEpoch = this.currentCdcEpoch();
+    const refreshOne = async (ws) => {
+      if (this.isSocketExpired(ws)) {
+        this.dropExpiredSocket(ws);
+        return;
+      }
+      const attachment = this.readAttachment(ws);
+      for (const [subId, query] of Object.entries(attachment.subs)) {
+        const { functionPath } = query;
+        if (!functionPath) {
+          continue;
+        }
+        const isAdmin = functionPath.startsWith(ADMIN_FUNCTION_PREFIX);
+        const memo = this.subMemos.get(ws)?.get(subId);
+        if (memo && !memo.tables.has(ADMIN_WILDCARD) && !setsIntersect(memo.tables, changed)) {
+          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 })
+          );
+          if (!outcome) {
+            continue;
+          }
+          await awaitWsDrain(ws);
+          this.pushSubscriptionData(ws, subId, outcome, frameCursor, frameEpoch);
+        } catch {
+          continue;
+        }
+      }
+    };
+    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()));
+  }
+  /**
+   * Seed a freshly-registered subscription with its first value. Runs the
+   * query once, then takes one of two paths.
+   *
+   * The default path ships the full snapshot via {@link pushSubscriptionData}
+   * — a first-time subscribe, an admin sub, or a reconnect whose read-set
+   * changed (or fell outside the CDC retention window) since its cursor.
+   *
+   * The resume path sends a lightweight `resume` frame — a reconnecting client
+   * that supplied `sinceSeq` and is still current keeps its cached value and
+   * only advances its cursor, saving the full-snapshot round-trip.
+   *
+   * Either way the fresh result memoises this socket's diff baseline so later
+   * write-flushes ({@link refreshSubscriptions}) can emit incremental deltas.
+   */
+  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 });
+    if (!outcome) {
+      return;
+    }
+    const { sinceEpoch, sinceSeq } = query;
+    const resume = isAdmin || sinceSeq === void 0 ? void 0 : this.evaluateResume(sinceSeq, outcome.tables, sinceEpoch);
+    const epoch = isAdmin ? void 0 : resume?.epoch ?? this.currentCdcEpoch();
+    if (resume?.resumable) {
+      this.seedSubscriptionMemo(ws, subId, outcome);
+      try {
+        ws.send(`{"type":"resume","id":${JSON.stringify(subId)}${cdcSuffix(resume.cursor ?? 0, epoch)}}`);
+      } catch {
+      }
+      return;
+    }
+    this.pushSubscriptionData(ws, subId, outcome, resume?.cursor ?? this.currentCdcCursor(), epoch);
+  }
+  /**
+   * 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
+   * cached value but the server still needs a baseline so the next
+   * write-flush can diff against it.
+   */
+  seedSubscriptionMemo(ws, subId, outcome) {
+    let memos = this.subMemos.get(ws);
+    if (!memos) {
+      memos = /* @__PURE__ */ new Map();
+      this.subMemos.set(ws, memos);
+    }
+    memos.set(subId, { lastJson: JSON.stringify(outcome.result ?? null), tables: outcome.tables });
+  }
+  /**
+   * Memoise `outcome` for `(ws, subId)` and push it to the socket, unless an
+   * identical result was already sent. Always refreshes the memo's table set
+   * so dependency tracking stays current even when the value is unchanged.
+   *
+   * When the result is a diffable list (Convex-parity live-pagination, gap
+   * #20), emit one `{type:"delta"}` frame per changed row instead of a full
+   * `{type:"data"}` snapshot — see {@link subscriptionListDeltas} for the
+   * five conditions under which deltas are safe. The first send (and any
+   * non-list / large-change result) falls back to the snapshot. The memo is
+   * always advanced to the new `lastJson`/`tables` regardless of path.
+   *
+   * `cursor` (when supplied) is the `__cdc_log` high-watermark this frame
+   * covers; it is appended to the emitted `data`/`delta` JSON so a client can
+   * persist its resume position and replay it as `sinceSeq` on reconnect
+   * (Pillar 1b). Omitted on shards without CDC, keeping the wire byte-identical
+   * to the pre-cursor format.
+   */
+  pushSubscriptionData(ws, subId, outcome, cursor, epoch) {
+    let memos = this.subMemos.get(ws);
+    if (!memos) {
+      memos = /* @__PURE__ */ new Map();
+      this.subMemos.set(ws, memos);
+    }
+    const cursorSuffix = cdcSuffix(cursor, epoch);
+    const json = JSON.stringify(outcome.result ?? null);
+    const existing = memos.get(subId);
+    if (existing?.lastJson === json) {
+      existing.tables = outcome.tables;
+      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 {
+    }
+  }
+  /**
+   * Gate the upgrade request against two complementary controls:
+   *
+   * 1. Origin allowlist via `env.LUNORA_ALLOWED_ORIGINS` (comma-separated).
+   * When unset, any origin is accepted — convenient for local dev,
+   * not suitable for production.
+   * 2. Bearer token via `env.LUNORA_WS_BEARER`. When set, the upgrade
+   * must present a matching token. We accept either an
+   * `Authorization: Bearer &lt;token>` header (preferred) or a
+   * `?token=&lt;token>` query parameter (the only escape hatch for
+   * browsers, which can't customise headers on the WebSocket
+   * constructor). The match runs in constant time to avoid leaking
+   * the token via response-timing differences.
+   *
+   * The `?token=` path is a real risk surface: the token ends up in
+   * 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.
+   */
+  isUpgradeAllowed(request) {
+    const env = this.env ?? {};
+    const allowedOrigins = env.LUNORA_ALLOWED_ORIGINS;
+    if (allowedOrigins && allowedOrigins.trim() !== "") {
+      const origin = request.headers.get("origin");
+      if (!origin) {
+        return false;
+      }
+      const list = allowedOrigins.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+      if (!list.includes(origin)) {
+        return false;
+      }
+    }
+    const expectedBearer = env.LUNORA_WS_BEARER;
+    if (expectedBearer && expectedBearer.length > 0) {
+      const supplied = this.suppliedWsToken(request);
+      if (!supplied || !constantTimeEqual(supplied, expectedBearer) && !this.isAdminSocket(request)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Token presented on a WS upgrade: the `Authorization: Bearer` header when
+   * present, else the `?token=` query parameter (the only channel a browser
+   * `WebSocket` constructor can use). Returns `undefined` when neither is set.
+   * @returns the bearer token string, or `undefined` when no token was supplied
+   */
+  // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method grouped with the upgrade-auth helpers; reads only the request
+  suppliedWsToken(request) {
+    const fromHeader = extractBearerToken(request.headers.get("authorization"));
+    if (fromHeader !== void 0) {
+      return fromHeader;
+    }
+    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.
+   */
+  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);
+  }
+  /**
+   * Register the hibernation-safe ping/pong keepalive. The runtime answers a
+   * {@link WS_KEEPALIVE_PING} text frame with {@link WS_KEEPALIVE_PONG}
+   * WITHOUT waking this Durable Object, keeping idle subscription sockets
+   * alive across hibernation with no billable wakeup and no dispatch. The
+   * auto-response is per-instance, so this re-runs on every construction
+   * (including a post-hibernation wake). Guarded: the API and the
+   * `WebSocketRequestResponsePair` global are absent in the unit harness and
+   * on older runtimes, where it degrades to a no-op.
+   */
+  armWebSocketKeepalive() {
+    const setter = this.state.setWebSocketAutoResponse;
+    if (typeof setter !== "function" || typeof WebSocketRequestResponsePair === "undefined") {
+      return;
+    }
+    setter.call(this.state, new WebSocketRequestResponsePair(WS_KEEPALIVE_PING, WS_KEEPALIVE_PONG));
+  }
+  handleWebSocketUpgrade(request) {
+    if (!this.isUpgradeAllowed(request)) {
+      return new Response("Forbidden", { status: 403 });
+    }
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.state.acceptWebSocket(server);
+    const userId = request.headers.get("x-lunora-userid") ?? void 0;
+    const identity = parseIdentityHeader(request.headers.get("x-lunora-identity"));
+    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),
+      connectionId: crypto.randomUUID(),
+      subs: {},
+      ...expiresAt === void 0 ? {} : { expiresAt },
+      ...identity === void 0 ? {} : { identity },
+      ...userId === void 0 ? {} : { userId }
+    });
+    return new Response(null, { status: 101, webSocket: client });
+  }
+  /**
+   * Whether this shard has a `__cdc_log` table. The single source of the
+   * "is CDC on here?" probe shared by {@link currentCdcCursor},
+   * {@link currentCdcEpoch}, {@link evaluateResume}, and the PITR-restore epoch
+   * bump. Returns `false` (rather than throwing) on a stub `sql` handle (unit
+   * harness double) or a pre-CDC shard, so callers degrade to the no-CDC path.
+   */
+  cdcEnabled() {
+    try {
+      return this.sql.exec(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`, CDC_LOG_TABLE).toArray().length > 0;
+    } catch {
+      return false;
+    }
+  }
+  /** Whether `ws` carries a credential whose expiry (stamped at upgrade) is now past. */
+  isSocketExpired(ws) {
+    const { expiresAt } = this.readAttachment(ws);
+    return typeof expiresAt === "number" && Date.now() >= expiresAt;
+  }
+  /**
+   * Send the `TOKEN_EXPIRED` error frame and close the socket with code 4001 so
+   * the client distinguishes an expired-credential drop from an ordinary one
+   * and refreshes before reconnecting. Best-effort: a throw (socket already
+   * gone) is swallowed — this must never escape the hibernation handlers.
+   */
+  // eslint-disable-next-line class-methods-use-this -- cohesive socket helper grouped with isSocketExpired; operates only on the passed socket
+  dropExpiredSocket(ws) {
+    try {
+      ws.send(JSON.stringify({ code: "TOKEN_EXPIRED", error: { code: "TOKEN_EXPIRED", message: "authentication token expired" }, type: "error" }));
+      ws.close(4001, "token_expired");
+    } catch {
+    }
+  }
+  /**
+   * Join (`join = true`) or leave a whisper `topic` on this socket. Membership rides
+   * the hibernation attachment, bounded by
+   * {@link ShardDO.MAX_WHISPER_TOPICS_PER_SOCKET}. Best-effort and silent:
+   * whispering is never acked, and an over-cap join or a serialize failure is
+   * simply dropped (the join just doesn't take).
+   */
+  setWhisperMembership(ws, topic, join) {
+    const attachment = this.readAttachment(ws);
+    const topics = attachment.whispers ?? [];
+    const has = topics.includes(topic);
+    if (join) {
+      if (has || topics.length >= ShardDO.MAX_WHISPER_TOPICS_PER_SOCKET) {
+        return;
+      }
+      attachment.whispers = [...topics, topic];
+    } else {
+      if (!has) {
+        return;
+      }
+      const next = topics.filter((entry) => entry !== topic);
+      if (next.length === 0) {
+        delete attachment.whispers;
+      } else {
+        attachment.whispers = next;
+      }
+    }
+    try {
+      ws.serializeAttachment?.(attachment);
+    } catch {
+    }
+  }
+  /**
+   * Token-bucket admission for a sender's whisper. Refills lazily from elapsed
+   * wall-clock at {@link ShardDO.WHISPER_RATE_PER_SEC}/s up to a burst of
+   * {@link ShardDO.WHISPER_RATE_BURST}; returns `false` (drop the whisper) when
+   * the bucket is empty. Per-socket, in-memory — a hibernation resets it to a
+   * full burst, which is the safe direction (never under-counts into a denial).
+   */
+  allowWhisper(ws) {
+    const now = Date.now();
+    const bucket = this.whisperBuckets.get(ws) ?? { last: now, tokens: ShardDO.WHISPER_RATE_BURST };
+    const refilled = Math.min(ShardDO.WHISPER_RATE_BURST, bucket.tokens + (now - bucket.last) / 1e3 * ShardDO.WHISPER_RATE_PER_SEC);
+    if (refilled < 1) {
+      this.whisperBuckets.set(ws, { last: now, tokens: refilled });
+      return false;
+    }
+    this.whisperBuckets.set(ws, { last: now, tokens: refilled - 1 });
+    return true;
+  }
+  /**
+   * Fan an ephemeral whisper out to every OTHER socket on this shard that
+   * joined `topic`. No SQLite write, no CDC entry, no query re-run — the
+   * payload is relayed verbatim, so it never touches durable state (the
+   * AnyCable "whisper" primitive: typing indicators, live cursors). The sender
+   * is excluded; an over-limit or over-rate whisper is dropped.
+   *
+   * Authorization note: whisper topics are NOT access-controlled beyond the
+   * shard boundary — any socket on this shard can join and read/inject on any
+   * 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) {
+    if (!this.allowWhisper(sender)) {
+      return;
+    }
+    const dataJson = JSON.stringify(data ?? null);
+    if (dataJson.length > ShardDO.MAX_WHISPER_BYTES) {
+      return;
+    }
+    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}}`;
+    for (const ws of this.state.getWebSockets()) {
+      if (ws === sender || this.readAttachment(ws).whispers?.includes(topic) !== true) {
+        continue;
+      }
+      try {
+        ws.send(frame);
+      } catch {
+      }
+    }
+  }
+  // eslint-disable-next-line class-methods-use-this -- cohesive DO instance method grouped with the hibernation/attachment helpers; reads only the socket
+  readAttachment(ws) {
+    const raw = ws.deserializeAttachment?.();
+    if (raw && typeof raw === "object" && "subs" in raw && raw.subs) {
+      return raw;
+    }
+    return { subs: {} };
+  }
+}
+
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO, subscriptionListDeltas };