@lunora/do 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/packem_shared/ROOT_DO_SIZE_WARN_BYTES-2DxWrdla.mjs

@@ -1,3958 +0,0 @@
-import { drizzle } from 'drizzle-orm/durable-sqlite';
-import { parseExportShardArgs, parseImportShardArgs } from './exportShardRows-DZEhUeyI.mjs';
-import { recordAuthEvent, readAuthMetrics } from './AUTH_METRICS_BUCKETS_TABLE-CiHHYeJi.mjs';
-import { DATA_MIGRATION_STATE_TABLE, readMigrationStatus } from './DATA_MIGRATION_STATE_TABLE-PTtTiQ7U.mjs';
-import { SCAN_DEP, createDependencyTracker, tableFromDepKey } from './SCAN_DEP-DLJF8dsj.mjs';
-import { readFunctionMetricsTotals, readFunctionMetricIndexHits, recordFunctionMetric, mergeScanAttribution, readFunctionMetrics, readFunctionMetricBuckets } from './FUNCTION_METRICS_BUCKETS_TABLE-UDNVD7FS.mjs';
-import { ADMIN_FUNCTION_PREFIX, RELATION_FUNCTION_PREFIX, selectMatchingIds, ADMIN_FUNCTIONS, findStorageReferences, listTables, summarizeSubscriptions, readTablePage, facetColumn, MAX_PAGE_SIZE } from './ADMIN_FUNCTIONS-CHcC8fKV.mjs';
-import { LogBuffer } from './LogBuffer-B_Ezju_N.mjs';
-import { recordCapturedMail, clearCapturedMail, readCapturedMail, MAIL_TABLE } from './MAIL_RETENTION-CPpgl-dX.mjs';
-import { readBookmark, armRestore } from './armRestore-BJk53Ro8.mjs';
-import { ReactiveCache, reactiveCacheKey } from './ReactiveCache-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 './MAX_SQL_ROWS-dDcFE1YZ.mjs';
-import { trySendFrame, subscriptionListDeltas, sendDeltaFrames } from './subscriptionListDeltas-ce84gpwL.mjs';
-import { ConflictError } from './ConflictError-C0STs6bU.mjs';
-import { CDC_LOG_TABLE, readCdcChanges, readCdcCursor, readCdcEpoch, minCdcSeq, bumpCdcEpoch } from './CDC_LOG_TABLE-Ctdmxmrv.mjs';
-import { r as readIdempotent, w as writeIdempotent, t as trimIdempotent } from './ctx-db-idempotency-DkC9rP91.mjs';
-
-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 UNDELIVERED_BASELINE = "<undelivered>";
-const ROOT_DO_SIZE_WARN_BYTES = 1073741824;
-const CDC_RESUME_SCAN_LIMIT = 1e4;
-const IDEMPOTENCY_RETENTION_MS = 864e5;
-const IDEMPOTENCY_GC_INTERVAL_MS = 36e5;
-const ROOT_SHARD_NAME = "__root__";
-const ADMIN_WILDCARD = "*";
-const awaitWsDrain = async (ws) => {
-  let attempts = 0;
-  while (attempts < 100) {
-    attempts += 1;
-    const buffered = ws.bufferedAmount;
-    if (typeof buffered !== "number" || buffered < 1048576) {
-      return;
-    }
-    await new Promise((resolve) => {
-      setTimeout(resolve, 20);
-    });
-  }
-};
-const cdcSuffix = (cursor, epoch) => (cursor === void 0 ? "" : `,"cursor":${String(cursor)}`) + (epoch === void 0 ? "" : `,"epoch":${JSON.stringify(epoch)}`);
-const setsIntersect = (a, b) => {
-  const [small, large] = a.size <= b.size ? [a, b] : [b, a];
-  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;
-  /**
-   * Coalesced set of tables awaiting a subscription-refresh pass, merged
-   * across every {@link ShardDO.flushChangedTables} call that lands while a
-   * pass is already draining. The single drain loop
-   * ({@link ShardDO.drainSubscriptionRefreshes}) owns this set; a burst of N
-   * writes to the same table therefore collapses into one (or two) refresh
-   * passes instead of N, so each affected subscription's handler re-runs once
-   * per burst rather than once per write. `undefined` when nothing is pending.
-   */
-  pendingRefreshTables = void 0;
-  /** True while {@link ShardDO.drainSubscriptionRefreshes} is running; the single-waiter gate that coalesces concurrent flushes. */
-  refreshInFlight = false;
-  /**
-   * Last pushed result per `(socket, subId)`, keyed by socket. Lets
-   * `refreshSubscriptions` skip re-running queries whose tables were
-   * 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 transactionalStorage = this.state.storage;
-    const run = async () => {
-      this.transactionDepth = 1;
-      try {
-        if (typeof transactionalStorage?.transaction === "function") {
-          return await transactionalStorage.transaction(async () => handler());
-        }
-        return await handler();
-      } 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, queues: false, scheduler: false, storage: false, vectors: false, workflows: false };
-  }
-  /**
-   * The Cloudflare Queues declared by this app, surfaced via
-   * `__lunora_admin__:listQueues` for the studio's Queues page. Queues are NOT
-   * Durable Objects and hold no shard state, so this is pure declaration
-   * metadata statically discovered by `@lunora/codegen` from `lunora/queues.ts`
-   * and emitted into the generated subclass, which overrides this. The base
-   * class can't see the user's project, so it reports none.
-   */
-  // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass overrides this with the statically-discovered queue metadata
-  queuesMetadata() {
-    return { queues: [] };
-  }
-  /**
-   * The Cloudflare Workflows declared by this app, surfaced via
-   * `__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;
-        }
-        trySendFrame(ws, `{"type":"delta","id":${JSON.stringify(subId)},"delta":${deltaJson}}`);
-      }
-    }
-  }
-  /**
-   * 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();
-    }
-    if (functionPath === ADMIN_FUNCTIONS.listQueues) {
-      return this.queuesMetadata();
-    }
-    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 (this.pendingRefreshTables) {
-      for (const table of changed) {
-        this.pendingRefreshTables.add(table);
-      }
-    } else {
-      this.pendingRefreshTables = changed;
-    }
-    if (this.refreshInFlight) {
-      return;
-    }
-    if (typeof this.state.waitUntil === "function") {
-      this.state.waitUntil(this.drainSubscriptionRefreshes());
-      return;
-    }
-    await this.drainSubscriptionRefreshes();
-  }
-  /**
-   * Drain {@link ShardDO.pendingRefreshTables} one coalesced batch at a time
-   * until it is empty, then release the {@link ShardDO.refreshInFlight} gate.
-   * Tables merged by a `flushChangedTables` that lands mid-pass are picked up
-   * by the next loop iteration, so every committed write is observed by a
-   * refresh that runs after it — bursts simply share a pass. The post-write
-   * high-watermark and live-socket set are re-read inside each
-   * `refreshSubscriptions` call, so a later batch always reflects the latest
-   * committed state.
-   */
-  async drainSubscriptionRefreshes() {
-    if (this.refreshInFlight) {
-      return;
-    }
-    this.refreshInFlight = true;
-    try {
-      let batch = this.pendingRefreshTables;
-      while (batch && batch.size > 0) {
-        this.pendingRefreshTables = void 0;
-        await this.refreshSubscriptions(batch);
-        batch = this.pendingRefreshTables;
-      }
-    } finally {
-      this.refreshInFlight = false;
-    }
-  }
-  /**
-   * 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);
-    const delivered = deltas === void 0 ? trySendFrame(ws, `{"type":"data","id":${JSON.stringify(subId)},"data":${json}${cursorSuffix}}`) : sendDeltaFrames(ws, subId, deltaFrames, cursorSuffix);
-    memos.set(subId, { lastJson: delivered ? json : existing?.lastJson ?? UNDELIVERED_BASELINE, tables: outcome.tables });
-  }
-  /**
-   * Gate the upgrade request against two complementary controls:
-   *
-   * 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;
-      }
-      trySendFrame(ws, frame);
-    }
-  }
-  // 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 };