@lunora/sql-store 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/createSqlCtxDb-BlGq23Wp.mjs

@@ -0,0 +1,1784 @@
+import { aggregateTableName, rankTableName, ftsTableName, hasTrigger, runRowValidators, assertFlatPredicate, mergeWhere, sortColumnName, resolveRankPartition, encodePartitionKey, decodeCursor, RANK_TIEBREAK, CountRlsUnsupportedError, normalizeIdStructurally, assertValidClientId, aggregateSqlFunction, softDeleteScope, compileWhereSql, normalizeOrderKeys, buildSeekWhere, resolveRelationPredicates, resolveWith, applySelect, encodeCursor, NotFoundError, applyOnDelete, ConflictError, normalizeCountArgument, selectIndexForCount, encodeAggregateKey, selectIndexForAggregate, readAggregateValue, renderSql, runTriggers, matchesRankStaticWhere, stringifySearchText, selectIndexForGroupBy, fanOutScalarCounts, matchesStaticWhere, coerceAggregateNumber, foldAggregateTally, NotUniqueError, throwingScheduler, tokenizeSearch, buildFtsMatch, scoreDocument } from '@lunora/do';
+import { sql } from 'drizzle-orm';
+import { sqliteDecode, effectiveColumnKind, sqliteEncode } from './decodeBigint-Dedu92k4.mjs';
+
+const physicalColumn = (field) => field === "_id" || field === "id" ? "id" : field;
+const columnRefSql = (field) => sql`${sql.identifier(physicalColumn(field))}`;
+const ID_ORDER_FIELDS = /* @__PURE__ */ new Set(["_id", "id"]);
+const nullSafeEqualsSql = (engine, reference, value) => {
+  if (engine === "postgres") {
+    return sql`${reference} IS NOT DISTINCT FROM ${value}`;
+  }
+  if (engine === "mysql") {
+    return sql`${reference} <=> ${value}`;
+  }
+  return sql`${reference} IS ${value}`;
+};
+const compileOrderBySql = (keys) => {
+  const parts = keys.map((key) => sql`${columnRefSql(key.field)} ${sql.raw(key.direction === "desc" ? "DESC" : "ASC")}`);
+  if (!keys.some((key) => ID_ORDER_FIELDS.has(key.field))) {
+    parts.push(sql`${columnRefSql("id")} ASC`);
+  }
+  return sql.join(parts, sql`, `);
+};
+const queryAll = (exec, dialect, query) => {
+  const { params, sql: text } = renderSql(dialect.name, query);
+  return exec.all(text, params);
+};
+const queryRun = (exec, dialect, query) => {
+  const { params, sql: text } = renderSql(dialect.name, query);
+  return exec.run(text, params);
+};
+const createIndexIfNotExists = async (exec, dialect, spec) => {
+  const unique = spec.unique ? sql`UNIQUE ` : sql``;
+  if (dialect.name === "mysql") {
+    try {
+      await queryRun(exec, dialect, sql`CREATE ${unique}INDEX ${sql.identifier(spec.name)} ON ${sql.identifier(spec.table)} (${spec.columns})`);
+    } catch (error) {
+      if (error.errno !== 1061) {
+        throw error;
+      }
+    }
+    return;
+  }
+  await queryRun(exec, dialect, sql`CREATE ${unique}INDEX IF NOT EXISTS ${sql.identifier(spec.name)} ON ${sql.identifier(spec.table)} (${spec.columns})`);
+};
+const MAX_TRIGGER_DEPTH = 50;
+const serializeColumnValue = sqliteEncode;
+const ftsAvailabilityCache = /* @__PURE__ */ new WeakMap();
+const isFtsAvailable = (exec) => {
+  const cached = ftsAvailabilityCache.get(exec);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const probe = (async () => {
+    let available;
+    try {
+      await exec.run(`CREATE VIRTUAL TABLE IF NOT EXISTS "__lunora_fts_probe" USING fts5(x)`, []);
+      available = true;
+    } catch {
+      available = false;
+    } finally {
+      try {
+        await exec.run(`DROP TABLE IF EXISTS "__lunora_fts_probe"`, []);
+      } catch {
+      }
+    }
+    return available;
+  })();
+  ftsAvailabilityCache.set(exec, probe);
+  return probe;
+};
+const tableColumns = (definition) => {
+  const columns = [];
+  for (const [field, validator] of Object.entries(definition.shape)) {
+    const column = validator._meta?.column;
+    if (column) {
+      columns.push([field, column]);
+    }
+  }
+  return columns;
+};
+const decodeGlobalRow = (definition, row) => {
+  const decoded = {};
+  for (const [field, validator] of Object.entries(definition.shape)) {
+    const raw = row[field];
+    if (raw === void 0) {
+      continue;
+    }
+    decoded[field] = sqliteDecode(raw, effectiveColumnKind(validator));
+  }
+  decoded["_id"] = row["id"];
+  decoded["_creationTime"] = row["_creationTime"];
+  return decoded;
+};
+const decodeRow = (definition, row) => {
+  if (!row) {
+    return null;
+  }
+  return decodeGlobalRow(definition, row);
+};
+const applyInsertDefaults = (definition, document, auth) => {
+  const result = { ...document };
+  for (const [field, column] of tableColumns(definition)) {
+    if (column.serverDefault) {
+      result[field] = column.serverDefault({ auth });
+      continue;
+    }
+    if (result[field] !== void 0) {
+      continue;
+    }
+    if (column.defaultFn) {
+      result[field] = column.defaultFn();
+    } else if ("defaultValue" in column) {
+      result[field] = column.defaultValue;
+    }
+  }
+  return result;
+};
+const applyOnUpdate = (definition, provided, target, auth) => {
+  for (const [field, column] of tableColumns(definition)) {
+    if (column.serverDefault) {
+      if (field in provided) {
+        target[field] = column.serverDefault({ auth });
+      }
+      continue;
+    }
+    if (column.onUpdateFn && !(field in provided)) {
+      target[field] = column.onUpdateFn();
+    }
+  }
+};
+const TABLE_NAME_CACHE_CAPACITY = 128;
+const createTableNameCache = () => {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    delete: (id) => {
+      map.delete(id);
+    },
+    get: (id) => {
+      const hit = map.get(id);
+      if (hit === void 0) {
+        return void 0;
+      }
+      map.delete(id);
+      map.set(id, hit);
+      return hit;
+    },
+    set: (id, table) => {
+      if (map.has(id)) {
+        map.delete(id);
+      } else if (map.size >= TABLE_NAME_CACHE_CAPACITY) {
+        const oldest = map.keys().next().value;
+        if (oldest !== void 0) {
+          map.delete(oldest);
+        }
+      }
+      map.set(id, table);
+    }
+  };
+};
+const tableNameFromId = async (exec, dialect, schema, id, cache) => {
+  const cached = cache.get(id);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const candidates = [];
+  for (const [tableName, definition] of Object.entries(schema.tables)) {
+    if (definition.shardMode !== void 0 && definition.shardMode.kind !== "global") {
+      continue;
+    }
+    candidates.push(tableName);
+  }
+  const probes = await Promise.all(
+    candidates.map(async (tableName) => {
+      const rows = await queryAll(exec, dialect, sql`SELECT 1 FROM ${sql.identifier(tableName)} WHERE ${sql.identifier("id")} = ${id} LIMIT 1`);
+      return { found: rows.length > 0, tableName };
+    })
+  );
+  for (const result of probes) {
+    if (result.found) {
+      cache.set(id, result.tableName);
+      return result.tableName;
+    }
+  }
+  return void 0;
+};
+const aggregateScalar = (value) => value === null || value === void 0 ? null : Number(value);
+const mapGroupByRows = (by, rows) => rows.map((row) => {
+  const key = {};
+  for (const field of by) {
+    key[field] = row[field] ?? null;
+  }
+  return { key, value: aggregateScalar(row.value) };
+});
+const decodeRows = (definition, rows) => {
+  const documents = [];
+  for (const row of rows) {
+    const decoded = decodeRow(definition, row);
+    if (decoded) {
+      documents.push(decoded);
+    }
+  }
+  return documents;
+};
+const searchViaFts = async (exec, dialect, definition, tableName, search, limit) => {
+  const tokens = tokenizeSearch(search.query);
+  if (tokens.length === 0) {
+    return [];
+  }
+  const ftName = ftsTableName(tableName, search.indexName);
+  const conditions = [sql`f.${sql.identifier("__text__")} MATCH ${buildFtsMatch(tokens)}`];
+  for (const filter of search.filters) {
+    conditions.push(sql`m.${columnRefSql(filter.field)} = ${serializeColumnValue(filter.value)}`);
+  }
+  if (definition.softDeleteMode) {
+    conditions.push(sql`m.${columnRefSql(definition.softDeleteMode.field)} IS NULL`);
+  }
+  let query = sql`SELECT m.* FROM ${sql.identifier(ftName)} f JOIN ${sql.identifier(tableName)} m ON m.${sql.identifier("id")} = f.${sql.identifier("__id__")} WHERE ${sql.join(conditions, sql` AND `)} ORDER BY f.rank, m.${sql.identifier("_creationTime")} DESC`;
+  if (typeof limit === "number") {
+    query = sql`${query} LIMIT ${sql.raw(String(Math.max(0, Math.floor(limit))))}`;
+  }
+  const rows = await queryAll(exec, dialect, query);
+  return decodeRows(definition, rows);
+};
+const searchViaScan = async (exec, dialect, definition, tableName, search, limit) => {
+  const tokens = tokenizeSearch(search.query);
+  if (tokens.length === 0) {
+    return [];
+  }
+  const conditions = search.filters.map((filter) => sql`${columnRefSql(filter.field)} = ${serializeColumnValue(filter.value)}`);
+  if (definition.softDeleteMode) {
+    conditions.push(sql`${columnRefSql(definition.softDeleteMode.field)} IS NULL`);
+  }
+  let query = sql`SELECT * FROM ${sql.identifier(tableName)}`;
+  if (conditions.length > 0) {
+    query = sql`${query} WHERE ${sql.join(conditions, sql` AND `)}`;
+  }
+  const rows = await queryAll(exec, dialect, query);
+  const scored = [];
+  for (const record of decodeRows(definition, rows)) {
+    const score = scoreDocument(stringifySearchText(record[search.field]), tokens);
+    if (score > 0) {
+      scored.push({ creationTime: typeof record["_creationTime"] === "number" ? record["_creationTime"] : 0, doc: record, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score || b.creationTime - a.creationTime);
+  const documents = scored.map((entry) => entry.doc);
+  return typeof limit === "number" ? documents.slice(0, Math.max(0, Math.floor(limit))) : documents;
+};
+const createSearchBuilder = (search, tableName) => {
+  const builder = {
+    eq: (field, value) => {
+      if (!search.definition.filterFields?.includes(field)) {
+        throw new Error(`field "${field}" is not a filter field of search index "${search.indexName}" on table "${tableName}"`);
+      }
+      search.filters.push({ field, value });
+      return builder;
+    },
+    search: (field, query) => {
+      if (field !== search.definition.field) {
+        throw new Error(`search index "${search.indexName}" on table "${tableName}" indexes "${search.definition.field}", not "${field}"`);
+      }
+      const stage = search;
+      stage.field = field;
+      stage.query = query;
+      stage.hasQuery = true;
+      return builder;
+    }
+  };
+  return builder;
+};
+const andBranch = (conditions) => conditions.length === 1 ? conditions[0] : sql`(${sql.join(conditions, sql` AND `)})`;
+const buildRankBeforeBranches = (engine, index, sortColumns, own, rowId) => {
+  const branches = [];
+  for (let pivot = 0; pivot < sortColumns.length + 1; pivot += 1) {
+    const conditions = sortColumns.slice(0, pivot).map((prefixColumn) => nullSafeEqualsSql(engine, sql`${sql.identifier(prefixColumn)}`, own[prefixColumn]));
+    const column = sortColumns[pivot];
+    const sortKey = index.sortBy[pivot];
+    if (pivot < sortColumns.length && column !== void 0 && sortKey !== void 0) {
+      conditions.push(sql`${sql.identifier(column)} ${sql.raw(sortKey.direction === "desc" ? ">" : "<")} ${own[column]}`);
+    } else {
+      conditions.push(sql`${sql.identifier(RANK_TIEBREAK)} < ${rowId}`);
+    }
+    branches.push(andBranch(conditions));
+  }
+  return branches.length > 0 ? sql.join(branches, sql` OR `) : void 0;
+};
+const buildRankCursorSeek = (engine, columns, decoded) => {
+  if (decoded.length !== columns.length) {
+    return void 0;
+  }
+  const branches = [];
+  for (const [pivot, col] of columns.entries()) {
+    const conditions = [];
+    for (let prefix = 0; prefix < pivot; prefix += 1) {
+      const prefixCol = columns[prefix];
+      if (prefixCol === void 0) {
+        continue;
+      }
+      conditions.push(nullSafeEqualsSql(engine, sql`${sql.identifier(prefixCol.column)}`, decoded[prefix]));
+    }
+    conditions.push(sql`${sql.identifier(col.column)} ${sql.raw(col.direction === "desc" ? "<" : ">")} ${decoded[pivot]}`);
+    branches.push(andBranch(conditions));
+  }
+  return sql`(${sql.join(branches, sql` OR `)})`;
+};
+const rankPageColumns = (index, sortColumns) => {
+  if (index.sortBy.length === 0) {
+    throw new Error(`rankIndex "${index.name}" requires at least one "sortBy" column for stable pagination`);
+  }
+  const columns = [{ column: "__partition__", direction: "asc" }];
+  for (const [i, sortKey] of index.sortBy.entries()) {
+    columns.push({ column: sortColumns[i] ?? sortColumnName(i), direction: sortKey.direction });
+  }
+  columns.push({ column: RANK_TIEBREAK, direction: "asc" });
+  return columns;
+};
+const hydrateRankRows = async (exec, dialect, definition, tableName, ids) => {
+  const IN_CHUNK_SIZE = 50;
+  const chunks = [];
+  for (let cursor = 0; cursor < ids.length; cursor += IN_CHUNK_SIZE) {
+    chunks.push(ids.slice(cursor, cursor + IN_CHUNK_SIZE));
+  }
+  const fetched = await Promise.all(
+    chunks.map(async (chunk) => {
+      const list = sql.join(
+        chunk.map((value) => sql`${value}`),
+        sql`, `
+      );
+      return queryAll(exec, dialect, sql`SELECT * FROM ${sql.identifier(tableName)} WHERE ${sql.identifier("id")} IN (${list})`);
+    })
+  );
+  const byId = /* @__PURE__ */ new Map();
+  for (const rows of fetched) {
+    for (const row of rows) {
+      byId.set(row["id"], row);
+    }
+  }
+  const documents = [];
+  for (const id of ids) {
+    const decoded = decodeRow(definition, byId.get(id));
+    if (decoded) {
+      documents.push(decoded);
+    }
+  }
+  return documents;
+};
+const encodeRankCursor = (cursorValues) => {
+  const json = JSON.stringify(cursorValues);
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCodePoint(byte);
+  }
+  return btoa(binary);
+};
+const BACKFILL_BATCH_SIZE = 500;
+const forEachRowPaged = async (exec, dialect, definition, tableName, onDoc) => {
+  let cursorId;
+  let hasMore = true;
+  while (hasMore) {
+    const pageRows = cursorId === void 0 ? (
+      // eslint-disable-next-line no-await-in-loop -- keyset paging is inherently sequential: each page's WHERE depends on the prior page's last id.
+      await queryAll(
+        exec,
+        dialect,
+        sql`SELECT * FROM ${sql.identifier(tableName)} ORDER BY ${sql.identifier("id")} ASC LIMIT ${sql.raw(String(BACKFILL_BATCH_SIZE))}`
+      )
+    ) : (
+      // eslint-disable-next-line no-await-in-loop -- keyset paging is inherently sequential: each page's WHERE depends on the prior page's last id.
+      await queryAll(
+        exec,
+        dialect,
+        sql`SELECT * FROM ${sql.identifier(tableName)} WHERE ${sql.identifier("id")} > ${cursorId} ORDER BY ${sql.identifier("id")} ASC LIMIT ${sql.raw(String(BACKFILL_BATCH_SIZE))}`
+      )
+    );
+    for (const row of pageRows) {
+      const decoded = decodeRow(definition, row);
+      if (decoded) {
+        onDoc(decoded);
+      }
+    }
+    cursorId = pageRows.at(-1)?.["id"];
+    hasMore = pageRows.length === BACKFILL_BATCH_SIZE;
+  }
+};
+const globalColumnAffinity = (validator, dialect) => dialect.columnType(effectiveColumnKind(validator));
+const globalTableColumnsDdl = (definition, dialect) => {
+  const fieldColumns = [];
+  for (const [field, validator] of Object.entries(definition.shape)) {
+    if (!validator._meta?.column) {
+      continue;
+    }
+    const notNull = validator._meta.column.notNull && validator.kind !== "optional" ? " NOT NULL" : "";
+    fieldColumns.push(sql`${sql.identifier(field)} ${sql.raw(`${globalColumnAffinity(validator, dialect)}${notNull}`)}`);
+  }
+  const frameworkColumns = dialect.frameworkColumns().map((column) => sql`${sql.identifier(column.name)} ${sql.raw(column.type)}`);
+  return sql.join([...frameworkColumns, ...fieldColumns], sql`, `);
+};
+const createGlobalTableIndexes = async (exec, tableName, definition, dialect) => {
+  const indexRef = (field) => {
+    const reference = columnRefSql(field);
+    const validator = definition.shape[field];
+    const prefix = validator && dialect.indexKeyPrefix ? dialect.indexKeyPrefix(effectiveColumnKind(validator)) : void 0;
+    return prefix === void 0 ? reference : sql`${reference}(${sql.raw(String(prefix))})`;
+  };
+  for (const index of definition.indexes) {
+    const expressions = sql.join(
+      index.fields.map((field) => indexRef(field)),
+      sql`, `
+    );
+    await createIndexIfNotExists(exec, dialect, {
+      columns: expressions,
+      name: `${tableName}_${index.name}`,
+      table: tableName,
+      unique: index.unique ?? false
+    });
+  }
+  for (const [field, column] of tableColumns(definition)) {
+    if (!column.unique) {
+      continue;
+    }
+    await createIndexIfNotExists(exec, dialect, { columns: indexRef(field), name: `${tableName}_unique_${field}`, table: tableName, unique: true });
+  }
+};
+const runSqlGlobalTableMigrations = async (exec, schema, dialect) => {
+  for (const [tableName, definition] of Object.entries(schema.tables)) {
+    if (definition.shardMode?.kind !== "global") {
+      continue;
+    }
+    const columns = globalTableColumnsDdl(definition, dialect);
+    await queryRun(exec, dialect, sql`CREATE TABLE IF NOT EXISTS ${sql.identifier(tableName)} (${columns})`);
+    await createGlobalTableIndexes(exec, tableName, definition, dialect);
+  }
+};
+const runSqlAggregateMigrations = async (exec, schema, dialect) => {
+  const { integer, key, real } = dialect.companionTypes;
+  for (const [tableName, definition] of Object.entries(schema.tables)) {
+    const indexes = definition.aggregateIndexes;
+    if (!indexes || indexes.length === 0) {
+      continue;
+    }
+    for (const index of indexes) {
+      const aggTable = aggregateTableName(tableName, index.name);
+      await queryRun(
+        exec,
+        dialect,
+        sql`CREATE TABLE IF NOT EXISTS ${sql.identifier(aggTable)} (${sql.identifier("__key__")} ${sql.raw(key)} PRIMARY KEY, ${sql.identifier("__value__")} ${sql.raw(real)}, ${sql.identifier("__count__")} ${sql.raw(integer)} NOT NULL DEFAULT 0)`
+      );
+      if (dialect.name === "sqlite") {
+        const columns = await queryAll(exec, dialect, sql`PRAGMA table_info(${sql.identifier(aggTable)})`);
+        if (!columns.some((column) => column["name"] === "__count__")) {
+          await queryRun(
+            exec,
+            dialect,
+            sql`ALTER TABLE ${sql.identifier(aggTable)} ADD COLUMN ${sql.identifier("__count__")} ${sql.raw(integer)} NOT NULL DEFAULT 0`
+          );
+        }
+      }
+    }
+  }
+};
+const rankIndexColumn = (dialect, column, direction, needsPrefix) => {
+  const reference = dialect.name === "mysql" && needsPrefix ? sql`${sql.identifier(column)}(191)` : sql`${sql.identifier(column)}`;
+  return sql`${reference} ${sql.raw(direction)}`;
+};
+const rankBtreeColumns = (dialect, index, definition) => {
+  const columns = [rankIndexColumn(dialect, "__partition__", "ASC", true)];
+  for (const [i, sortKey] of index.sortBy.entries()) {
+    const validator = definition.shape[sortKey.field];
+    const needsPrefix = validator !== void 0 && dialect.indexKeyPrefix?.(effectiveColumnKind(validator)) !== void 0;
+    columns.push(rankIndexColumn(dialect, sortColumnName(i), sortKey.direction === "desc" ? "DESC" : "ASC", needsPrefix));
+  }
+  columns.push(rankIndexColumn(dialect, "__id__", "ASC", true));
+  return columns;
+};
+const rankSortColumnDefs = (dialect, index, definition) => index.sortBy.map((sortKey, i) => {
+  const validator = definition.shape[sortKey.field];
+  const columnType = dialect.columnType(validator ? effectiveColumnKind(validator) : void 0);
+  return sql`${sql.identifier(sortColumnName(i))} ${sql.raw(columnType)}`;
+});
+const runSqlRankMigrations = async (exec, schema, dialect) => {
+  const { key } = dialect.companionTypes;
+  for (const [tableName, definition] of Object.entries(schema.tables)) {
+    const indexes = definition.rankIndexes;
+    if (!indexes || indexes.length === 0) {
+      continue;
+    }
+    for (const index of indexes) {
+      const rankTable = rankTableName(tableName, index.name);
+      const sortColumnDefs = rankSortColumnDefs(dialect, index, definition);
+      const columnPart = sortColumnDefs.length > 0 ? sql`, ${sql.join(sortColumnDefs, sql`, `)}` : sql``;
+      await queryRun(
+        exec,
+        dialect,
+        sql`CREATE TABLE IF NOT EXISTS ${sql.identifier(rankTable)} (${sql.identifier("__id__")} ${sql.raw(key)} PRIMARY KEY, ${sql.identifier("__partition__")} ${sql.raw(key)} NOT NULL${columnPart})`
+      );
+      const orderedColumns = rankBtreeColumns(dialect, index, definition);
+      const btreeName = `${tableName}__rank_${index.name}__btree`;
+      await createIndexIfNotExists(exec, dialect, {
+        columns: sql.join(orderedColumns, sql`, `),
+        name: btreeName,
+        table: rankTable,
+        unique: false
+      });
+    }
+  }
+};
+const runSqlSearchMigrations = async (exec, schema, dialect) => {
+  if (!await isFtsAvailable(exec)) {
+    return;
+  }
+  for (const [tableName, definition] of Object.entries(schema.tables)) {
+    const indexes = definition.searchIndexes;
+    if (!indexes || indexes.length === 0) {
+      continue;
+    }
+    for (const index of indexes) {
+      const ftName = ftsTableName(tableName, index.name);
+      await queryRun(
+        exec,
+        dialect,
+        sql`CREATE VIRTUAL TABLE IF NOT EXISTS ${sql.identifier(ftName)} USING fts5(${sql.identifier("__text__")}, ${sql.identifier("__id__")} UNINDEXED)`
+      );
+    }
+  }
+};
+const CDC_LOG_TABLE = "__cdc_log";
+const runSqlCdcMigration = async (exec, dialect) => {
+  const { autoincrementPrimaryKey, key, real, text } = dialect.companionTypes;
+  await queryRun(
+    exec,
+    dialect,
+    sql`CREATE TABLE IF NOT EXISTS ${sql.identifier(CDC_LOG_TABLE)} (${sql.identifier("seq")} ${sql.raw(autoincrementPrimaryKey)}, ${sql.identifier("ts")} ${sql.raw(real)} NOT NULL, ${sql.identifier("table")} ${sql.raw(key)} NOT NULL, ${sql.identifier("id")} ${sql.raw(key)} NOT NULL, ${sql.identifier("op")} ${sql.raw(key)} NOT NULL, ${sql.identifier("doc")} ${sql.raw(text)})`
+  );
+};
+const appendSqlCdcChange = async (exec, ts, table, id, op, doc, dialect) => {
+  await queryRun(
+    exec,
+    dialect,
+    sql`INSERT INTO ${sql.identifier(CDC_LOG_TABLE)} (${sql.identifier("ts")}, ${sql.identifier("table")}, ${sql.identifier("id")}, ${sql.identifier("op")}, ${sql.identifier("doc")}) VALUES (${ts}, ${table}, ${id}, ${op}, ${// eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct post-image for a delete; the `id` identifies the removed row.
+    doc === void 0 ? null : JSON.stringify(doc)})`
+  );
+};
+const readSqlCdcChanges = async (exec, options, dialect) => {
+  const sinceSeq = options.sinceSeq ?? 0;
+  const limit = Math.max(1, Math.min(options.limit ?? 1e3, 1e4));
+  const rows = await queryAll(
+    exec,
+    dialect,
+    sql`SELECT seq, ts, ${sql.identifier("table")}, id, op, doc FROM ${sql.identifier(CDC_LOG_TABLE)} WHERE seq > ${sinceSeq} ORDER BY seq ASC LIMIT ${sql.raw(String(limit))}`
+  );
+  const changes = rows.map((row) => {
+    const { doc } = row;
+    const base = { id: String(row.id), op: String(row.op), seq: Number(row.seq), table: String(row.table), ts: Number(row.ts) };
+    return typeof doc === "string" ? { ...base, doc: JSON.parse(doc) } : base;
+  });
+  return { changes, cursor: changes.at(-1)?.seq ?? sinceSeq };
+};
+const trimSqlCdcChanges = async (exec, throughSeq, dialect) => {
+  await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(CDC_LOG_TABLE)} WHERE ${sql.identifier("seq")} <= ${throughSeq}`);
+};
+const createSqlCtxDb = (options) => {
+  const { crossShardCounter, crossShardReader, exec, maxRelationKeys, schema } = options;
+  const { dialect } = options;
+  const { isUniqueViolation } = dialect;
+  const whereSqlStrategy = {
+    fieldRef: columnRefSql,
+    serialize: serializeColumnValue,
+    // MySQL has no `||` string concat; the rest use the portable form compileWhereSql defaults to.
+    ...dialect.name === "mysql" ? { likeContains: (reference, term) => sql`${reference} LIKE CONCAT('%', ${term}, '%')` } : {}
+  };
+  const nullSafeEquals = (reference, value) => nullSafeEqualsSql(dialect.name, reference, value);
+  const upsertSql = (config) => {
+    const columnList = sql.join(
+      config.columns.map((column) => sql`${sql.identifier(column)}`),
+      sql`, `
+    );
+    const valueList = sql.join(
+      config.values.map((value) => sql`${value}`),
+      sql`, `
+    );
+    const excluded = (column) => dialect.name === "mysql" ? sql`VALUES(${sql.identifier(column)})` : sql`excluded.${sql.identifier(column)}`;
+    const current = (column) => dialect.name === "postgres" ? sql`${sql.identifier(config.table)}.${sql.identifier(column)}` : sql`${sql.identifier(column)}`;
+    const assignments = sql.join(
+      Object.entries(config.set(excluded, current)).map(([column, expression]) => sql`${sql.identifier(column)} = ${expression}`),
+      sql`, `
+    );
+    const conflict = dialect.name === "mysql" ? sql`ON DUPLICATE KEY UPDATE ${assignments}` : sql`ON CONFLICT(${sql.identifier(config.conflictKey)}) DO UPDATE SET ${assignments}`;
+    return sql`INSERT INTO ${sql.identifier(config.table)} (${columnList}) VALUES (${valueList}) ${conflict}`;
+  };
+  const clock = options.clock ?? (() => Date.now());
+  const generateId = options.idGenerator ?? (() => crypto.randomUUID());
+  const cdcEnabled = options.cdc ?? false;
+  const auth = options.auth ?? { identity: null, userId: null };
+  const recordCdc = async (table, id, op, doc) => {
+    if (cdcEnabled) {
+      await appendSqlCdcChange(exec, clock(), table, id, op, doc, dialect);
+    }
+  };
+  const scheduler = options.scheduler ?? throwingScheduler;
+  const tableNameCache = createTableNameCache();
+  let triggerDepth = 0;
+  let migratedPromise;
+  const ensureMigrated = async () => {
+    migratedPromise ??= (async () => {
+      await runSqlGlobalTableMigrations(exec, schema, dialect);
+      await runSqlAggregateMigrations(exec, schema, dialect);
+      await runSqlRankMigrations(exec, schema, dialect);
+      await runSqlSearchMigrations(exec, schema, dialect);
+      if (cdcEnabled) {
+        await runSqlCdcMigration(exec, dialect);
+      }
+    })().catch((error) => {
+      migratedPromise = void 0;
+      throw error;
+    });
+    return migratedPromise;
+  };
+  const resolveTableName = async (id, expectedTable) => {
+    await ensureMigrated();
+    const tableName = await tableNameFromId(exec, dialect, schema, id, tableNameCache);
+    if (expectedTable !== void 0 && tableName !== expectedTable) {
+      return void 0;
+    }
+    return tableName;
+  };
+  const backfilled = /* @__PURE__ */ new Map();
+  const counterTableExists = async (table, indexName) => {
+    const aggTable = aggregateTableName(table, indexName);
+    const rows = await queryAll(exec, dialect, dialect.tableExists(aggTable));
+    return rows.length > 0;
+  };
+  const ensureBackfilled = async (tableName, index) => {
+    const cacheKey = `${tableName}::${index.name}`;
+    const cached = backfilled.get(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const exists = await counterTableExists(tableName, index.name);
+    if (!exists) {
+      backfilled.set(cacheKey, false);
+      return false;
+    }
+    const definition = schema.tables[tableName];
+    if (!definition) {
+      backfilled.set(cacheKey, false);
+      return false;
+    }
+    const by = index.by ?? [];
+    const tallies = /* @__PURE__ */ new Map();
+    await forEachRowPaged(exec, dialect, definition, tableName, (document) => {
+      if (index.where && !matchesStaticWhere(document, index.where)) {
+        return;
+      }
+      const encoded = encodeAggregateKey(by, document);
+      foldAggregateTally(tallies, encoded, index, document);
+    });
+    const aggTable = aggregateTableName(tableName, index.name);
+    await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(aggTable)}`);
+    for (const [encoded, tally] of tallies) {
+      await queryRun(
+        exec,
+        dialect,
+        sql`INSERT INTO ${sql.identifier(aggTable)} (${sql.identifier("__key__")}, ${sql.identifier("__value__")}, ${sql.identifier("__count__")}) VALUES (${encoded}, ${tally.value}, ${tally.count})`
+      );
+    }
+    backfilled.set(cacheKey, true);
+    return true;
+  };
+  const recomputeExtreme = async (tableName, index, document) => {
+    const sqlFunction = aggregateSqlFunction(index.op);
+    const field = index.field ?? "";
+    const conditions = [];
+    for (const key of index.by ?? []) {
+      const value = serializeColumnValue(document[key] ?? null);
+      conditions.push(value === null ? sql`${columnRefSql(key)} IS NULL` : sql`${columnRefSql(key)} = ${value}`);
+    }
+    for (const [key, expected] of Object.entries(index.where ?? {})) {
+      const literal = expected !== null && typeof expected === "object" && !Array.isArray(expected) ? expected.eq : expected;
+      const value = serializeColumnValue(literal);
+      conditions.push(value === null ? sql`${columnRefSql(key)} IS NULL` : sql`${columnRefSql(key)} = ${value}`);
+    }
+    const query = sql`SELECT ${sql.raw(sqlFunction)}(${columnRefSql(field)}) AS value FROM ${sql.identifier(tableName)}`;
+    const rows = await queryAll(exec, dialect, conditions.length > 0 ? sql`${query} WHERE ${sql.join(conditions, sql` AND `)}` : query);
+    return aggregateScalar(rows[0]?.["value"]);
+  };
+  const pruneEmptyGroup = async (aggTable, encoded) => {
+    await queryRun(
+      exec,
+      dialect,
+      sql`DELETE FROM ${sql.identifier(aggTable)} WHERE ${sql.identifier("__key__")} = ${encoded} AND ${sql.identifier("__count__")} <= 0`
+    );
+  };
+  const applyAggregateDelta = async (tableName, index, previous, next) => {
+    const aggTable = aggregateTableName(tableName, index.name);
+    const { op } = index;
+    const field = index.field ?? "";
+    const removes = previous && (!index.where || matchesStaticWhere(previous, index.where)) ? previous : void 0;
+    const adds = next && (!index.where || matchesStaticWhere(next, index.where)) ? next : void 0;
+    if (!removes && !adds) {
+      return;
+    }
+    if (op === "count") {
+      const touched = /* @__PURE__ */ new Set();
+      for (const [document, delta] of [
+        [removes, -1],
+        [adds, 1]
+      ]) {
+        if (!document) {
+          continue;
+        }
+        const encoded = encodeAggregateKey(index.by ?? [], document);
+        touched.add(encoded);
+        await queryRun(
+          exec,
+          dialect,
+          upsertSql({
+            columns: ["__key__", "__value__", "__count__"],
+            conflictKey: "__key__",
+            set: (excluded, current) => {
+              return {
+                __count__: sql`${current("__count__")} + ${excluded("__count__")}`,
+                __value__: sql`${current("__value__")} + ${excluded("__value__")}`
+              };
+            },
+            table: aggTable,
+            values: [encoded, delta, delta]
+          })
+        );
+      }
+      for (const encoded of touched) {
+        await pruneEmptyGroup(aggTable, encoded);
+      }
+      return;
+    }
+    if (op === "sum" || op === "avg") {
+      const touched = /* @__PURE__ */ new Set();
+      for (const [document, sign] of [
+        [removes, -1],
+        [adds, 1]
+      ]) {
+        if (!document) {
+          continue;
+        }
+        const numeric = coerceAggregateNumber(document[field]);
+        if (numeric === void 0) {
+          continue;
+        }
+        const encoded = encodeAggregateKey(index.by ?? [], document);
+        touched.add(encoded);
+        await queryRun(
+          exec,
+          dialect,
+          upsertSql({
+            columns: ["__key__", "__value__", "__count__"],
+            conflictKey: "__key__",
+            set: (excluded, current) => {
+              return {
+                __count__: sql`${current("__count__")} + ${excluded("__count__")}`,
+                __value__: sql`COALESCE(${current("__value__")}, 0) + ${excluded("__value__")}`
+              };
+            },
+            table: aggTable,
+            values: [encoded, sign * numeric, sign]
+          })
+        );
+      }
+      for (const encoded of touched) {
+        await pruneEmptyGroup(aggTable, encoded);
+      }
+      return;
+    }
+    if (removes) {
+      const encoded = encodeAggregateKey(index.by ?? [], removes);
+      const removedValue = coerceAggregateNumber(removes[field]);
+      const existingRows = await queryAll(
+        exec,
+        dialect,
+        sql`SELECT ${sql.identifier("__value__")} AS value, ${sql.identifier("__count__")} AS count FROM ${sql.identifier(aggTable)} WHERE ${sql.identifier("__key__")} = ${encoded}`
+      );
+      const existing = existingRows[0];
+      const existingValue = aggregateScalar(existing?.value);
+      const remainingCount = (existing?.count ?? 0) - 1;
+      if (remainingCount <= 0) {
+        await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(aggTable)} WHERE ${sql.identifier("__key__")} = ${encoded}`);
+      } else if (existing && removedValue !== void 0 && existingValue !== null && removedValue === existingValue) {
+        const recomputed = await recomputeExtreme(tableName, index, removes);
+        await queryRun(
+          exec,
+          dialect,
+          sql`UPDATE ${sql.identifier(aggTable)} SET ${sql.identifier("__value__")} = ${recomputed}, ${sql.identifier("__count__")} = ${remainingCount} WHERE ${sql.identifier("__key__")} = ${encoded}`
+        );
+      } else {
+        await queryRun(
+          exec,
+          dialect,
+          sql`UPDATE ${sql.identifier(aggTable)} SET ${sql.identifier("__count__")} = ${sql.identifier("__count__")} - 1 WHERE ${sql.identifier("__key__")} = ${encoded}`
+        );
+      }
+    }
+    if (adds) {
+      const encoded = encodeAggregateKey(index.by ?? [], adds);
+      const addedValue = coerceAggregateNumber(adds[field]);
+      if (addedValue === void 0) {
+        await queryRun(
+          exec,
+          dialect,
+          upsertSql({
+            columns: ["__key__", "__value__", "__count__"],
+            conflictKey: "__key__",
+            set: (_excluded, current) => {
+              return { __count__: sql`${current("__count__")} + 1` };
+            },
+            table: aggTable,
+            // eslint-disable-next-line unicorn/no-null -- seeds an extreme-less group with NULL value; the literal 1 seeds the count
+            values: [encoded, null, 1]
+          })
+        );
+      } else {
+        const op2 = op === "min" ? "MIN" : "MAX";
+        await queryRun(
+          exec,
+          dialect,
+          upsertSql({
+            columns: ["__key__", "__value__", "__count__"],
+            conflictKey: "__key__",
+            set: (excluded, current) => {
+              return {
+                __count__: sql`${current("__count__")} + 1`,
+                __value__: sql`${sql.raw(op2)}(COALESCE(${current("__value__")}, ${excluded("__value__")}), ${excluded("__value__")})`
+              };
+            },
+            table: aggTable,
+            values: [encoded, addedValue, 1]
+          })
+        );
+      }
+    }
+  };
+  const ensureBackfilledForTable = async (tableName) => {
+    const indexes = schema.tables[tableName]?.aggregateIndexes;
+    if (!indexes || indexes.length === 0) {
+      return;
+    }
+    for (const index of indexes) {
+      await ensureBackfilled(tableName, index);
+    }
+  };
+  const syncAggregates = async (tableName, previous, next) => {
+    const indexes = schema.tables[tableName]?.aggregateIndexes;
+    if (!indexes || indexes.length === 0) {
+      return;
+    }
+    for (const index of indexes) {
+      const cacheKey = `${tableName}::${index.name}`;
+      const cached = backfilled.get(cacheKey);
+      const exists = cached ?? await counterTableExists(tableName, index.name);
+      if (!exists) {
+        continue;
+      }
+      await applyAggregateDelta(tableName, index, previous, next);
+    }
+  };
+  const rankBackfilled = /* @__PURE__ */ new Map();
+  const rankTableExists = async (table, indexName) => {
+    const rankTable = rankTableName(table, indexName);
+    const rows = await queryAll(exec, dialect, dialect.tableExists(rankTable));
+    return rows.length > 0;
+  };
+  const ensureRankBackfilled = async (tableName, index) => {
+    const cacheKey = `${tableName}::rank::${index.name}`;
+    const cached = rankBackfilled.get(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const exists = await rankTableExists(tableName, index.name);
+    if (!exists) {
+      rankBackfilled.set(cacheKey, false);
+      return false;
+    }
+    const definition = schema.tables[tableName];
+    if (!definition) {
+      rankBackfilled.set(cacheKey, false);
+      return false;
+    }
+    const rankTable = rankTableName(tableName, index.name);
+    await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(rankTable)}`);
+    const sortColumns = index.sortBy.map((_, i) => sortColumnName(i));
+    const insertColumnList = sql.join(
+      ["__id__", "__partition__", ...sortColumns].map((column) => sql`${sql.identifier(column)}`),
+      sql`, `
+    );
+    const rankTuples = [];
+    await forEachRowPaged(exec, dialect, definition, tableName, (document) => {
+      if (index.where && !matchesRankStaticWhere(document, index.where)) {
+        return;
+      }
+      const partitionKey = encodePartitionKey(index.partitionBy ?? [], document);
+      const sortValues = index.sortBy.map((key) => serializeColumnValue(document[key.field] ?? null));
+      rankTuples.push([document["_id"], partitionKey, ...sortValues]);
+    });
+    for (const tuple of rankTuples) {
+      const valueList = sql.join(
+        tuple.map((value) => sql`${value}`),
+        sql`, `
+      );
+      await queryRun(exec, dialect, sql`INSERT INTO ${sql.identifier(rankTable)} (${insertColumnList}) VALUES (${valueList})`);
+    }
+    rankBackfilled.set(cacheKey, true);
+    return true;
+  };
+  const ensureRankBackfilledForTable = async (tableName) => {
+    const indexes = schema.tables[tableName]?.rankIndexes;
+    if (!indexes || indexes.length === 0) {
+      return;
+    }
+    for (const index of indexes) {
+      await ensureRankBackfilled(tableName, index);
+    }
+  };
+  const syncRanks = async (tableName, id, previous, next) => {
+    const indexes = schema.tables[tableName]?.rankIndexes;
+    if (!indexes || indexes.length === 0) {
+      return;
+    }
+    for (const index of indexes) {
+      const cacheKey = `${tableName}::rank::${index.name}`;
+      const cached = rankBackfilled.get(cacheKey);
+      const exists = cached ?? await rankTableExists(tableName, index.name);
+      if (!exists) {
+        continue;
+      }
+      const rankTable = rankTableName(tableName, index.name);
+      if (previous) {
+        await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(rankTable)} WHERE ${sql.identifier("__id__")} = ${id}`);
+      }
+      if (next) {
+        if (index.where && !matchesRankStaticWhere(next, index.where)) {
+          continue;
+        }
+        const sortColumns = index.sortBy.map((_, i) => sortColumnName(i));
+        const columnList = sql.join(
+          ["__id__", "__partition__", ...sortColumns].map((column) => sql`${sql.identifier(column)}`),
+          sql`, `
+        );
+        const partitionKey = encodePartitionKey(index.partitionBy ?? [], next);
+        const sortValues = index.sortBy.map((key) => serializeColumnValue(next[key.field] ?? null));
+        const valueList = sql.join(
+          [id, partitionKey, ...sortValues].map((value) => sql`${value}`),
+          sql`, `
+        );
+        await queryRun(exec, dialect, sql`INSERT INTO ${sql.identifier(rankTable)} (${columnList}) VALUES (${valueList})`);
+      }
+    }
+  };
+  const syncSearch = async (tableName, id, document) => {
+    const indexes = schema.tables[tableName]?.searchIndexes;
+    if (!indexes || indexes.length === 0 || !await isFtsAvailable(exec)) {
+      return;
+    }
+    for (const index of indexes) {
+      const ftName = ftsTableName(tableName, index.name);
+      await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(ftName)} WHERE ${sql.identifier("__id__")} = ${id}`);
+      if (document) {
+        await queryRun(
+          exec,
+          dialect,
+          sql`INSERT INTO ${sql.identifier(ftName)} (${sql.identifier("__text__")}, ${sql.identifier("__id__")}) VALUES (${stringifySearchText(document[index.field])}, ${id})`
+        );
+      }
+    }
+  };
+  const triggerMatchers = /* @__PURE__ */ new Set();
+  for (const [tableName, definition] of Object.entries(schema.tables)) {
+    for (const trigger of Object.values(definition.triggerMap ?? {})) {
+      triggerMatchers.add(`${tableName} ${trigger.timing} ${trigger.op}`);
+    }
+  }
+  const hasMatchingTrigger = (tableName, timing, op) => triggerMatchers.has(`${tableName} ${timing} ${op}`);
+  let triggerContext;
+  const fireTriggers = async (timing, op, event) => {
+    triggerDepth += 1;
+    if (triggerDepth > MAX_TRIGGER_DEPTH) {
+      triggerDepth -= 1;
+      throw new ConflictError(
+        `trigger recursion exceeded ${String(MAX_TRIGGER_DEPTH)} levels on "${event.table}" — check for a self-triggering write`,
+        "trigger"
+      );
+    }
+    try {
+      await runTriggers({ ctx: triggerContext, event, op, schema, tableName: event.table, timing });
+    } finally {
+      triggerDepth -= 1;
+    }
+  };
+  const runWrite = async (table, query) => {
+    try {
+      await queryRun(exec, dialect, query);
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new ConflictError(`unique constraint violation on "${table}"`, "unique");
+      }
+      throw error;
+    }
+  };
+  const rawRow = async (tableName, id) => {
+    const rows = await queryAll(exec, dialect, sql`SELECT * FROM ${sql.identifier(tableName)} WHERE ${sql.identifier("id")} = ${id}`);
+    return rows[0];
+  };
+  const runGuardedWrite = async (table, verb, setClause, snapshot) => {
+    if (snapshot === void 0) {
+      return;
+    }
+    const guardClause = sql.join(
+      Object.keys(snapshot).map((column) => nullSafeEquals(sql`${sql.identifier(column)}`, snapshot[column])),
+      sql` AND `
+    );
+    const base = verb === "UPDATE" ? sql`UPDATE ${sql.identifier(table)} SET ${setClause} WHERE ${guardClause}` : sql`DELETE FROM ${sql.identifier(table)} WHERE ${guardClause}`;
+    const occConflict = () => {
+      throw new ConflictError(`optimistic concurrency conflict on "${table}" — the row changed during this mutation; refetch and retry`, "occ");
+    };
+    try {
+      if (dialect.supportsReturning) {
+        const returned = await queryAll(exec, dialect, sql`${base} RETURNING ${sql.identifier("id")}`);
+        if (returned.length === 0) {
+          occConflict();
+        }
+      } else {
+        const result = await queryRun(exec, dialect, base);
+        const affected = dialect.affectedRows ? dialect.affectedRows(result ?? { rowsAffected: 0 }) : 0;
+        if (affected === 0) {
+          occConflict();
+        }
+      }
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new ConflictError(`unique constraint violation on "${table}"`, "unique");
+      }
+      throw error;
+    }
+  };
+  const columnTuple = (definition, id, creationTime, document) => {
+    const fields = Object.keys(definition.shape);
+    return {
+      // Raw (unquoted) column names — the INSERT quotes them via `sql.identifier`.
+      columns: ["id", "_creationTime", ...fields],
+      // eslint-disable-next-line unicorn/no-null -- SQL bind value: an absent column must bind `null`, not undefined.
+      values: [id, creationTime, ...fields.map((field) => serializeColumnValue(document[field] ?? null))]
+    };
+  };
+  const tryIndexedGroupBy = async (tableName, aggregateIndexes, agg, groupOptions) => {
+    const planned = selectIndexForGroupBy(aggregateIndexes, agg.op, agg.field, groupOptions.by, groupOptions.where);
+    if (!planned) {
+      return void 0;
+    }
+    const counterReady = await ensureBackfilled(tableName, planned.index);
+    if (!counterReady) {
+      return void 0;
+    }
+    const aggTable = aggregateTableName(tableName, planned.index.name);
+    const partialKeys = Object.keys(planned.partial);
+    if (partialKeys.length === (planned.index.by ?? []).length && partialKeys.length > 0) {
+      const encoded = encodeAggregateKey(planned.index.by ?? [], planned.partial);
+      const rowsIndexed2 = await queryAll(
+        exec,
+        dialect,
+        sql`SELECT ${sql.identifier("__value__")} AS value, ${sql.identifier("__count__")} AS count FROM ${sql.identifier(aggTable)} WHERE ${sql.identifier("__key__")} = ${encoded}`
+      );
+      if (rowsIndexed2.length === 0) {
+        return [];
+      }
+      const row = rowsIndexed2[0];
+      return [{ key: { ...planned.partial }, value: readAggregateValue(agg.op, { count: row.count, value: aggregateScalar(row.value) }) }];
+    }
+    const rowsIndexed = await queryAll(
+      exec,
+      dialect,
+      sql`SELECT ${sql.identifier("__key__")} AS key, ${sql.identifier("__value__")} AS value, ${sql.identifier("__count__")} AS count FROM ${sql.identifier(aggTable)}`
+    );
+    return rowsIndexed.map((row) => {
+      const typed = row;
+      return {
+        key: JSON.parse(typed.key),
+        value: readAggregateValue(agg.op, { count: typed.count, value: aggregateScalar(typed.value) })
+      };
+    });
+  };
+  const isShardLocalTarget = (childTable) => {
+    const kind = schema.tables[childTable]?.shardMode?.kind;
+    return kind === "shardBy" || kind === "root";
+  };
+  const crossBackendUnsupported = (childTable) => {
+    throw new Error(
+      `cross-backend relation: a global table cannot load the shard-local relation '${childTable}' (it spans every shard) — wire a cross-shard reader to support it`
+    );
+  };
+  const relationPredicateFetcher = (childTable, childArgs) => {
+    if (!isShardLocalTarget(childTable)) {
+      return writer.findMany(childTable, childArgs);
+    }
+    return crossShardReader ? crossShardReader(childTable, childArgs) : crossBackendUnsupported(childTable);
+  };
+  const resolveAggregateRelations = (where, predicateTable, relationBaseWhere) => resolveRelationPredicates(where, {
+    fetcher: relationPredicateFetcher,
+    maxRelationKeys,
+    relationBaseWhere,
+    schema,
+    tableName: predicateTable
+  });
+  const writer = {
+    // eslint-disable-next-line sonarjs/cognitive-complexity -- routes count/sum/avg/min/max through the indexed companion vs scan fallback; the branching reads clearer inline than split across per-op helpers
+    async aggregate(tableName, aggOptions) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      await ensureMigrated();
+      aggregateSqlFunction(aggOptions.op);
+      if (aggOptions.op === "count") {
+        return writer.count(tableName, {
+          baseWhere: aggOptions.baseWhere,
+          relationBaseWhere: aggOptions.relationBaseWhere,
+          restrictsCounts: aggOptions.restrictsCounts,
+          where: aggOptions.where
+        });
+      }
+      if (!aggOptions.field) {
+        throw new Error(`aggregate(${tableName}, { op: "${aggOptions.op}" }): "field" is required for non-count reducers`);
+      }
+      const aggScope = softDeleteScope(definition.softDeleteMode, void 0);
+      const effective = mergeWhere(mergeWhere(aggOptions.baseWhere, aggOptions.where), aggScope);
+      const resolved = await resolveAggregateRelations(effective, tableName, aggOptions.relationBaseWhere);
+      const hasRelation = resolved !== effective;
+      if (definition.aggregateIndexes && !aggOptions.baseWhere && !hasRelation && !aggScope) {
+        const planned = selectIndexForAggregate(definition.aggregateIndexes, aggOptions.op, aggOptions.field, aggOptions.where);
+        if (planned) {
+          const counterReady = await ensureBackfilled(tableName, planned.index);
+          if (counterReady) {
+            const encoded = encodeAggregateKey(planned.index.by ?? [], planned.key);
+            const aggTable = aggregateTableName(tableName, planned.index.name);
+            const rows2 = await queryAll(
+              exec,
+              dialect,
+              sql`SELECT ${sql.identifier("__value__")} AS value, ${sql.identifier("__count__")} AS count FROM ${sql.identifier(aggTable)} WHERE ${sql.identifier("__key__")} = ${encoded}`
+            );
+            const row = rows2[0];
+            return readAggregateValue(aggOptions.op, row === void 0 ? void 0 : { count: row.count, value: aggregateScalar(row.value) });
+          }
+        }
+      }
+      const whereCondition = compileWhereSql(resolved, whereSqlStrategy);
+      const aggregateFunction = sql.raw(aggregateSqlFunction(aggOptions.op));
+      const query = sql`SELECT ${aggregateFunction}(${columnRefSql(aggOptions.field)}) AS value FROM ${sql.identifier(tableName)}`;
+      const rows = await queryAll(exec, dialect, whereCondition ? sql`${query} WHERE ${whereCondition}` : query);
+      const value = rows[0]?.["value"];
+      return value === null || value === void 0 ? null : Number(value);
+    },
+    async count(tableName, whereOrOptions) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      await ensureMigrated();
+      const countOptions = normalizeCountArgument(whereOrOptions);
+      if (countOptions.restrictsCounts) {
+        throw new CountRlsUnsupportedError(tableName);
+      }
+      const countScope = softDeleteScope(definition.softDeleteMode, void 0);
+      const effective = mergeWhere(mergeWhere(countOptions.baseWhere, countOptions.where), countScope);
+      const resolved = await resolveAggregateRelations(effective, tableName, countOptions.relationBaseWhere);
+      const hasRelation = resolved !== effective;
+      if (definition.aggregateIndexes && !countOptions.baseWhere && !hasRelation && !countScope) {
+        const planned = selectIndexForCount(definition.aggregateIndexes, countOptions.where);
+        if (planned) {
+          const counterReady = await ensureBackfilled(tableName, planned.index);
+          if (counterReady) {
+            const encoded = encodeAggregateKey(planned.index.by ?? [], planned.key);
+            const aggTable = aggregateTableName(tableName, planned.index.name);
+            const rows2 = await queryAll(
+              exec,
+              dialect,
+              sql`SELECT ${sql.identifier("__value__")} AS value FROM ${sql.identifier(aggTable)} WHERE ${sql.identifier("__key__")} = ${encoded}`
+            );
+            return Number(rows2[0]?.["value"] ?? 0);
+          }
+        }
+      }
+      const whereCondition = compileWhereSql(resolved, whereSqlStrategy);
+      const query = sql`SELECT COUNT(*) AS count FROM ${sql.identifier(tableName)}`;
+      const rows = await queryAll(exec, dialect, whereCondition ? sql`${query} WHERE ${whereCondition}` : query);
+      return Number(rows[0]?.["count"] ?? 0);
+    },
+    async delete(id, expectedTable, deleteOptions) {
+      const tableName = await resolveTableName(id, expectedTable);
+      if (!tableName) {
+        return;
+      }
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        return;
+      }
+      const snapshot = await rawRow(tableName, id);
+      const existing = decodeRow(definition, snapshot);
+      const hard = deleteOptions?.hard === true;
+      const softField = !hard && definition.softDeleteMode ? definition.softDeleteMode.field : void 0;
+      if (softField && (!existing || existing[softField] !== null && existing[softField] !== void 0)) {
+        return;
+      }
+      if (hasMatchingTrigger(tableName, "before", "delete")) {
+        await fireTriggers("before", "delete", { id, op: "delete", previous: existing ?? void 0, table: tableName });
+      }
+      await applyOnDelete({
+        deletedId: id,
+        deletedReference: (references) => existing?.[references],
+        findHolders: async (holderTable, field, value) => {
+          if (schema.tables[holderTable]?.shardMode?.kind === "shardBy") {
+            throw new Error(
+              `cross-backend cascade from global '${tableName}' into shardBy '${holderTable}' is not supported — would require Query Coordinator fan-out across shards`
+            );
+          }
+          const holders = await writer.findMany(holderTable, { includeDeleted: hard, where: { [field]: value } });
+          return holders.page;
+        },
+        onCascade: (_holderTable, holderId) => writer.delete(holderId, void 0, deleteOptions),
+        onRestrict: (message) => {
+          throw new ConflictError(message, "restrict");
+        },
+        // eslint-disable-next-line unicorn/no-null -- onSetNull writes a SQL NULL into the holder column; that is the literal value being persisted.
+        onSetNull: (_holderTable, holderId, field) => writer.patch(holderId, { [field]: null }),
+        schema,
+        tableName
+      });
+      await ensureBackfilledForTable(tableName);
+      await ensureRankBackfilledForTable(tableName);
+      if (softField && existing) {
+        const merged = { ...existing, [softField]: clock() };
+        const assignments = sql.join(
+          // eslint-disable-next-line unicorn/no-null -- SQL bind value: an absent column binds `null`, matching the patch path.
+          Object.keys(definition.shape).map((field) => sql`${sql.identifier(field)} = ${serializeColumnValue(merged[field] ?? null)}`),
+          sql`, `
+        );
+        await runGuardedWrite(tableName, "UPDATE", assignments, snapshot);
+        await syncAggregates(tableName, existing, merged);
+        await syncRanks(tableName, id, existing, void 0);
+        await syncSearch(tableName, id, merged);
+        await recordCdc(tableName, id, "update", merged);
+        if (hasMatchingTrigger(tableName, "after", "delete")) {
+          await fireTriggers("after", "delete", { id, op: "delete", previous: existing, table: tableName });
+        }
+        return;
+      }
+      await runGuardedWrite(tableName, "DELETE", void 0, snapshot);
+      tableNameCache.delete(id);
+      await syncAggregates(tableName, existing ?? void 0, void 0);
+      await syncRanks(tableName, id, existing ?? void 0, void 0);
+      await syncSearch(tableName, id, void 0);
+      await recordCdc(tableName, id, "delete");
+      if (hasMatchingTrigger(tableName, "after", "delete")) {
+        await fireTriggers("after", "delete", { id, op: "delete", previous: existing ?? void 0, table: tableName });
+      }
+    },
+    async findFirst(tableName, args = {}) {
+      const result = await writer.findMany(tableName, { ...args, limit: 1 });
+      return result.page[0] ?? null;
+    },
+    async findFirstOrThrow(tableName, args = {}) {
+      const document = await writer.findFirst(tableName, args);
+      if (document === null) {
+        throw new NotFoundError(`findFirstOrThrow: no "${tableName}" document matched`);
+      }
+      return document;
+    },
+    async findMany(tableName, args = {}) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      await ensureMigrated();
+      const orderKeys = normalizeOrderKeys(args.orderBy);
+      const seek = args.cursor ? buildSeekWhere(orderKeys, decodeCursor(args.cursor)) : void 0;
+      const relationFetcher = relationPredicateFetcher;
+      const relationGroupedCounter = async (childTable, whereField, values, policyWhere) => {
+        if (isShardLocalTarget(childTable)) {
+          if (!crossShardCounter) {
+            return crossBackendUnsupported(childTable);
+          }
+          return fanOutScalarCounts(crossShardCounter, childTable, whereField, values, policyWhere);
+        }
+        const childDefinition = schema.tables[childTable];
+        if (!childDefinition) {
+          throw new Error(`unknown table: ${childTable}`);
+        }
+        const softScope = softDeleteScope(childDefinition.softDeleteMode, void 0);
+        const inFilter = { [whereField]: { in: values } };
+        const combined = mergeWhere(mergeWhere(inFilter, policyWhere), softScope);
+        const resolvedCombined = await resolveAggregateRelations(combined, childTable, void 0);
+        const whereCondition2 = compileWhereSql(resolvedCombined, whereSqlStrategy);
+        const fieldRef = columnRefSql(whereField);
+        let groupQuery = sql`SELECT ${fieldRef} AS __fk__, COUNT(*) AS count FROM ${sql.identifier(childTable)}`;
+        if (whereCondition2) {
+          groupQuery = sql`${groupQuery} WHERE ${whereCondition2}`;
+        }
+        groupQuery = sql`${groupQuery} GROUP BY ${fieldRef}`;
+        const groupRows = await queryAll(exec, dialect, groupQuery);
+        const result = /* @__PURE__ */ new Map();
+        for (const row of groupRows) {
+          result.set(row["__fk__"], Number(row["count"] ?? 0));
+        }
+        return result;
+      };
+      let predicate = mergeWhere(args.baseWhere, args.where);
+      predicate = mergeWhere(predicate, softDeleteScope(definition.softDeleteMode, args.includeDeleted));
+      predicate = await resolveRelationPredicates(predicate, {
+        fetcher: relationFetcher,
+        maxRelationKeys,
+        relationBaseWhere: args.relationBaseWhere,
+        schema,
+        tableName
+      });
+      if (seek) {
+        predicate = predicate ? { AND: [predicate, seek] } : seek;
+      }
+      const whereCondition = compileWhereSql(predicate, whereSqlStrategy);
+      const orderBy = compileOrderBySql(orderKeys);
+      let query = sql`SELECT * FROM ${sql.identifier(tableName)}`;
+      if (whereCondition) {
+        query = sql`${query} WHERE ${whereCondition}`;
+      }
+      query = sql`${query} ORDER BY ${orderBy}`;
+      const limit = typeof args.limit === "number" ? Math.max(0, Math.floor(args.limit)) : void 0;
+      if (limit !== void 0) {
+        query = sql`${query} LIMIT ${sql.raw(String(limit + 1))}`;
+      }
+      const rows = await queryAll(exec, dialect, query);
+      const documents = decodeRows(definition, rows);
+      if (limit === void 0) {
+        if (args.with) {
+          await resolveWith({
+            fetcher: relationFetcher,
+            groupedCounter: relationGroupedCounter,
+            parents: documents,
+            schema,
+            tableName,
+            with: args.with
+          });
+        }
+        return { continueCursor: null, isDone: true, page: applySelect(documents, args.select, args.with) };
+      }
+      const hasMore = documents.length > limit;
+      const page = hasMore ? documents.slice(0, limit) : documents;
+      const last = page.at(-1);
+      if (args.with) {
+        await resolveWith({ fetcher: relationFetcher, groupedCounter: relationGroupedCounter, parents: page, schema, tableName, with: args.with });
+      }
+      return {
+        // The cursor is encoded from `last` (the full, unprojected row), so
+        // `applySelect` only trims the returned payload — paging is intact.
+        // eslint-disable-next-line unicorn/no-null -- public return shape: `continueCursor` is `string | null`; `null` marks the final page.
+        continueCursor: hasMore && last ? encodeCursor(last, orderKeys) : null,
+        isDone: !hasMore,
+        page: applySelect(page, args.select, args.with)
+      };
+    },
+    async get(id, expectedTable) {
+      const tableName = await resolveTableName(id, expectedTable);
+      if (!tableName) {
+        return null;
+      }
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        return null;
+      }
+      const rows = await queryAll(exec, dialect, sql`SELECT * FROM ${sql.identifier(tableName)} WHERE ${sql.identifier("id")} = ${id}`);
+      return decodeRow(definition, rows[0]);
+    },
+    async groupBy(tableName, groupOptions) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      await ensureMigrated();
+      const agg = groupOptions.agg ?? { op: "count" };
+      aggregateSqlFunction(agg.op);
+      if (agg.op !== "count" && !agg.field) {
+        throw new Error(`groupBy(${tableName}, { agg: { op: "${agg.op}" } }): "field" is required for non-count reducers`);
+      }
+      const groupScope = softDeleteScope(definition.softDeleteMode, void 0);
+      const effective = mergeWhere(mergeWhere(groupOptions.baseWhere, groupOptions.where), groupScope);
+      const resolved = await resolveAggregateRelations(effective, tableName, groupOptions.relationBaseWhere);
+      const hasRelation = resolved !== effective;
+      if (definition.aggregateIndexes && !groupOptions.baseWhere && !hasRelation && !groupScope) {
+        const indexed = await tryIndexedGroupBy(tableName, definition.aggregateIndexes, agg, groupOptions);
+        if (indexed !== void 0) {
+          return indexed;
+        }
+      }
+      const whereCondition = compileWhereSql(resolved, whereSqlStrategy);
+      const select = groupOptions.by.map((field) => sql`${columnRefSql(field)} AS ${sql.identifier(field)}`);
+      if (agg.op === "count") {
+        select.push(sql`COUNT(*) AS value`);
+      } else {
+        if (!agg.field) {
+          throw new Error(`groupBy(${tableName}, { agg: { op: "${agg.op}" } }): "field" is required for non-count reducers`);
+        }
+        select.push(sql`${sql.raw(aggregateSqlFunction(agg.op))}(${columnRefSql(agg.field)}) AS value`);
+      }
+      const groupBy = sql.join(
+        groupOptions.by.map((field) => columnRefSql(field)),
+        sql`, `
+      );
+      let query = sql`SELECT ${sql.join(select, sql`, `)} FROM ${sql.identifier(tableName)}`;
+      if (whereCondition) {
+        query = sql`${query} WHERE ${whereCondition}`;
+      }
+      query = sql`${query} GROUP BY ${groupBy}`;
+      const rows = await queryAll(exec, dialect, query);
+      return mapGroupByRows(groupOptions.by, rows);
+    },
+    /**
+     * Insert a document. A client-chosen `_id` is **ignored** by default —
+     * a caller able to pick its own id can collide with peer rows, defeat
+     * unique constraints, and forge references in foreign tables.
+     *
+     * Two opt-ins override that: a validated `options.clientId` (public —
+     * a UUID an optimistic client supplies so a sync engine can reconcile by
+     * key) or `options.allowExplicitId` (the trusted dev/admin import path,
+     * honoring a verbatim `_id` on `document`). Otherwise a fresh id is
+     * minted even if a handler forwards a raw client payload.
+     */
+    async insert(tableName, document, insertOptions) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      await ensureMigrated();
+      const withDefaults = applyInsertDefaults(definition, document, auth);
+      runRowValidators(definition, withDefaults);
+      let id;
+      let usedExplicitId = true;
+      if (insertOptions?.clientId !== void 0) {
+        assertValidClientId(insertOptions.clientId);
+        id = insertOptions.clientId;
+      } else if (insertOptions?.allowExplicitId && typeof withDefaults["_id"] === "string") {
+        id = withDefaults["_id"];
+      } else {
+        id = generateId();
+        usedExplicitId = false;
+      }
+      const creationTime = typeof withDefaults["_creationTime"] === "number" ? withDefaults["_creationTime"] : clock();
+      const documentWithMeta = { ...withDefaults, _creationTime: creationTime, _id: id };
+      if (hasMatchingTrigger(tableName, "before", "insert")) {
+        await fireTriggers("before", "insert", { doc: { ...documentWithMeta }, id, op: "insert", table: tableName });
+      }
+      await ensureBackfilledForTable(tableName);
+      await ensureRankBackfilledForTable(tableName);
+      const { columns, values } = columnTuple(definition, id, creationTime, withDefaults);
+      const columnList = sql.join(
+        columns.map((column) => sql`${sql.identifier(column)}`),
+        sql`, `
+      );
+      const valueList = sql.join(
+        values.map((value) => sql`${value}`),
+        sql`, `
+      );
+      await runWrite(tableName, sql`INSERT INTO ${sql.identifier(tableName)} (${columnList}) VALUES (${valueList})`);
+      if (usedExplicitId) {
+        tableNameCache.set(id, tableName);
+      }
+      await syncAggregates(tableName, void 0, documentWithMeta);
+      await syncRanks(tableName, id, void 0, documentWithMeta);
+      await syncSearch(tableName, id, documentWithMeta);
+      await recordCdc(tableName, id, "insert", documentWithMeta);
+      if (hasMatchingTrigger(tableName, "after", "insert")) {
+        await fireTriggers("after", "insert", { doc: documentWithMeta, id, op: "insert", table: tableName });
+      }
+      return id;
+    },
+    normalizeId(tableName, id) {
+      return normalizeIdStructurally(schema, tableName, id);
+    },
+    async patch(id, patch, expectedTable) {
+      const tableName = await resolveTableName(id, expectedTable);
+      if (!tableName) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const snapshot = await rawRow(tableName, id);
+      const existing = decodeRow(definition, snapshot);
+      if (!existing) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const merged = { ...existing, ...patch, _id: id };
+      applyOnUpdate(definition, patch, merged, auth);
+      runRowValidators(definition, merged);
+      if (hasMatchingTrigger(tableName, "before", "update")) {
+        await fireTriggers("before", "update", { doc: { ...merged }, id, op: "update", previous: existing, table: tableName });
+      }
+      await ensureBackfilledForTable(tableName);
+      await ensureRankBackfilledForTable(tableName);
+      const fields = Object.keys(definition.shape);
+      const assignments = sql.join(
+        // eslint-disable-next-line unicorn/no-null -- SQL bind value: an absent column must bind `null`, not undefined.
+        fields.map((field) => sql`${sql.identifier(field)} = ${serializeColumnValue(merged[field] ?? null)}`),
+        sql`, `
+      );
+      await runGuardedWrite(tableName, "UPDATE", assignments, snapshot);
+      await syncAggregates(tableName, existing, merged);
+      await syncRanks(tableName, id, existing, merged);
+      await syncSearch(tableName, id, merged);
+      await recordCdc(tableName, id, "update", merged);
+      if (hasMatchingTrigger(tableName, "after", "update")) {
+        await fireTriggers("after", "update", { doc: merged, id, op: "update", previous: existing, table: tableName });
+      }
+    },
+    async restore(id, expectedTable) {
+      const tableName = await resolveTableName(id, expectedTable);
+      if (!tableName) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const definition = schema.tables[tableName];
+      const field = definition?.softDeleteMode?.field;
+      if (!definition || !field) {
+        throw new Error(`ctx.db.restore: table "${tableName}" is not a .softDelete() table`);
+      }
+      const snapshot = await rawRow(tableName, id);
+      const wasDeleted = snapshot?.[field] !== null && snapshot?.[field] !== void 0;
+      await writer.patch(id, { [field]: null }, expectedTable);
+      if (wasDeleted) {
+        const row = decodeRow(definition, snapshot);
+        if (row !== null) {
+          await syncRanks(tableName, id, void 0, row);
+        }
+      }
+    },
+    query(tableName) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      const LEGACY_READER_ERROR = "the legacy query()/withIndex() reader is not available on the D1 (global) backend; use findMany";
+      const runSearch = async (stage, limit) => {
+        await ensureMigrated();
+        return await isFtsAvailable(exec) ? searchViaFts(exec, dialect, definition, tableName, stage, limit) : searchViaScan(exec, dialect, definition, tableName, stage, limit);
+      };
+      const buildReader = (stage) => {
+        const reader = {
+          async collect() {
+            if (!stage) {
+              throw new Error(LEGACY_READER_ERROR);
+            }
+            return runSearch(stage, void 0);
+          },
+          filter() {
+            throw new Error(LEGACY_READER_ERROR);
+          },
+          async first() {
+            if (!stage) {
+              throw new Error(LEGACY_READER_ERROR);
+            }
+            const rows = await runSearch(stage, 1);
+            return rows[0] ?? null;
+          },
+          order() {
+            return reader;
+          },
+          // eslint-disable-next-line @typescript-eslint/require-await -- TableReaderLike.paginate returns a Promise; search queries don't support pagination on either backend
+          async paginate() {
+            if (stage) {
+              throw new Error("pagination is not supported on search queries; use .take(n) or .collect()");
+            }
+            throw new Error(LEGACY_READER_ERROR);
+          },
+          async take(limit) {
+            if (!stage) {
+              throw new Error(LEGACY_READER_ERROR);
+            }
+            return runSearch(stage, limit);
+          },
+          async unique() {
+            if (!stage) {
+              throw new Error(LEGACY_READER_ERROR);
+            }
+            const rows = await runSearch(stage, 2);
+            if (rows.length > 1) {
+              throw new NotUniqueError(`unique() on table "${tableName}" matched ${String(rows.length)} documents; expected at most one`);
+            }
+            return rows[0] ?? null;
+          },
+          withIndex() {
+            throw new Error(LEGACY_READER_ERROR);
+          },
+          withSearchIndex(indexName, search) {
+            const searchDefinition = (definition.searchIndexes ?? []).find((index) => index.name === indexName);
+            if (!searchDefinition) {
+              throw new Error(`unknown search index "${indexName}" on table "${tableName}"`);
+            }
+            const searchStage = {
+              definition: searchDefinition,
+              field: searchDefinition.field,
+              filters: [],
+              hasQuery: false,
+              indexName,
+              query: ""
+            };
+            search(createSearchBuilder(searchStage, tableName));
+            if (!searchStage.hasQuery) {
+              throw new Error(`search index "${indexName}" on table "${tableName}" requires a .search(field, query) call`);
+            }
+            return buildReader(searchStage);
+          }
+        };
+        return reader;
+      };
+      return buildReader(void 0);
+    },
+    async rank(tableName, indexName, rankOptions) {
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      const index = definition.rankIndexes?.find((i) => i.name === indexName);
+      if (!index) {
+        throw new Error(`unknown rankIndex "${indexName}" on table "${tableName}"`);
+      }
+      if (rankOptions.restrictsCounts) {
+        throw new CountRlsUnsupportedError(tableName);
+      }
+      await ensureMigrated();
+      const counterReady = await ensureRankBackfilled(tableName, index);
+      if (!counterReady) {
+        return null;
+      }
+      const rowId = typeof rankOptions.row === "string" ? rankOptions.row : rankOptions.row["_id"];
+      if (!rowId) {
+        return null;
+      }
+      const rankTable = rankTableName(tableName, index.name);
+      const sortColumns = index.sortBy.map((_, i) => sortColumnName(i));
+      const selectList = sql.join([sql`${sql.identifier("__partition__")}`, ...sortColumns.map((column) => sql`${sql.identifier(column)}`)], sql`, `);
+      const ownRows = await queryAll(
+        exec,
+        dialect,
+        sql`SELECT ${selectList} FROM ${sql.identifier(rankTable)} WHERE ${sql.identifier("__id__")} = ${rowId}`
+      );
+      const own = ownRows[0];
+      if (!own) {
+        return null;
+      }
+      const partitionKey = own["__partition__"];
+      const effective = mergeWhere(rankOptions.baseWhere, rankOptions.where);
+      assertFlatPredicate(effective, schema, tableName, "rank");
+      const partitionFromWhere = resolveRankPartition(index, effective);
+      if (partitionFromWhere) {
+        const requestedKey = encodePartitionKey(index.partitionBy ?? [], partitionFromWhere);
+        if (requestedKey !== partitionKey) {
+          return null;
+        }
+      }
+      const beforeClause = buildRankBeforeBranches(dialect.name, index, sortColumns, own, rowId);
+      const beforeRows = await queryAll(
+        exec,
+        dialect,
+        sql`SELECT COUNT(*) AS c FROM ${sql.identifier(rankTable)} WHERE ${sql.identifier("__partition__")} = ${partitionKey}${beforeClause ? sql` AND (${beforeClause})` : sql``}`
+      );
+      const totalRows = await queryAll(
+        exec,
+        dialect,
+        sql`SELECT COUNT(*) AS c FROM ${sql.identifier(rankTable)} WHERE ${sql.identifier("__partition__")} = ${partitionKey}`
+      );
+      return { position: Number(beforeRows[0]?.["c"] ?? 0) + 1, total: Number(totalRows[0]?.["c"] ?? 0) };
+    },
+    async rankPage(tableName, indexName, rankPageOptions = {}) {
+      assertFlatPredicate(mergeWhere(rankPageOptions.baseWhere, rankPageOptions.where), schema, tableName, "rankPage");
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`unknown table: ${tableName}`);
+      }
+      const index = definition.rankIndexes?.find((i) => i.name === indexName);
+      if (!index) {
+        throw new Error(`unknown rankIndex "${indexName}" on table "${tableName}"`);
+      }
+      await ensureMigrated();
+      const counterReady = await ensureRankBackfilled(tableName, index);
+      if (!counterReady) {
+        return { continueCursor: null, isDone: true, page: [] };
+      }
+      const rankTable = rankTableName(tableName, index.name);
+      const sortColumns = index.sortBy.map((_, i) => sortColumnName(i));
+      const take = Math.max(1, Math.min(1e3, Math.floor(rankPageOptions.take ?? 100)));
+      const effective = mergeWhere(rankPageOptions.baseWhere, rankPageOptions.where);
+      const partitionFromWhere = resolveRankPartition(index, effective);
+      const rankColumns = rankPageColumns(index, sortColumns);
+      const orderBy = sql.join(
+        rankColumns.map((col) => sql`${sql.identifier(col.column)} ${sql.raw(col.direction === "desc" ? "DESC" : "ASC")}`),
+        sql`, `
+      );
+      const whereClauses = [];
+      if (partitionFromWhere) {
+        whereClauses.push(sql`${sql.identifier("__partition__")} = ${encodePartitionKey(index.partitionBy ?? [], partitionFromWhere)}`);
+      }
+      if (rankPageOptions.cursor) {
+        const seek = buildRankCursorSeek(dialect.name, rankColumns, decodeCursor(rankPageOptions.cursor));
+        if (seek !== void 0) {
+          whereClauses.push(seek);
+        }
+      }
+      const selectColumns = sql.join(
+        [
+          sql`${sql.identifier(RANK_TIEBREAK)}`,
+          sql`${sql.identifier("__partition__")}`,
+          ...sortColumns.map((column) => sql`${sql.identifier(column)}`)
+        ],
+        sql`, `
+      );
+      let query = sql`SELECT ${selectColumns} FROM ${sql.identifier(rankTable)}`;
+      if (whereClauses.length > 0) {
+        query = sql`${query} WHERE ${sql.join(whereClauses, sql` AND `)}`;
+      }
+      query = sql`${query} ORDER BY ${orderBy} LIMIT ${sql.raw(String(take + 1))}`;
+      const rankRows = await queryAll(exec, dialect, query);
+      const hasMore = rankRows.length > take;
+      const usable = hasMore ? rankRows.slice(0, take) : rankRows;
+      const ids = usable.map((rankRow) => rankRow[RANK_TIEBREAK]);
+      const documents = await hydrateRankRows(exec, dialect, definition, tableName, ids);
+      let continueCursor = null;
+      const last = usable.at(-1);
+      if (hasMore && last !== void 0) {
+        const cursorValues = [last["__partition__"], ...sortColumns.map((column) => last[column]), last[RANK_TIEBREAK]];
+        continueCursor = encodeRankCursor(cursorValues);
+      }
+      return { continueCursor, isDone: !hasMore, page: documents };
+    },
+    async replace(id, document, expectedTable) {
+      const tableName = await resolveTableName(id, expectedTable);
+      if (!tableName) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const definition = schema.tables[tableName];
+      if (!definition) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const snapshot = await rawRow(tableName, id);
+      if (snapshot === void 0) {
+        throw new Error(`document not found: ${id}`);
+      }
+      const needsPrevious = hasTrigger(schema, tableName, "update") || (definition.aggregateIndexes ?? []).length > 0 || (definition.rankIndexes ?? []).length > 0;
+      const previous = needsPrevious ? decodeRow(definition, snapshot) ?? void 0 : void 0;
+      const creationTime = typeof document["_creationTime"] === "number" ? document["_creationTime"] : clock();
+      const replaced = { ...document, _creationTime: creationTime, _id: id };
+      applyOnUpdate(definition, document, replaced, auth);
+      runRowValidators(definition, replaced);
+      if (hasMatchingTrigger(tableName, "before", "update")) {
+        await fireTriggers("before", "update", { doc: { ...replaced }, id, op: "update", previous, table: tableName });
+      }
+      await ensureBackfilledForTable(tableName);
+      await ensureRankBackfilledForTable(tableName);
+      const fields = Object.keys(definition.shape);
+      const assignments = sql.join(
+        [
+          sql`${sql.identifier("_creationTime")} = ${creationTime}`,
+          // eslint-disable-next-line unicorn/no-null -- SQL bind value: an absent column must bind `null`, not undefined.
+          ...fields.map((field) => sql`${sql.identifier(field)} = ${serializeColumnValue(replaced[field] ?? null)}`)
+        ],
+        sql`, `
+      );
+      await runGuardedWrite(tableName, "UPDATE", assignments, snapshot);
+      await syncAggregates(tableName, previous, replaced);
+      await syncRanks(tableName, id, previous, replaced);
+      await syncSearch(tableName, id, replaced);
+      await recordCdc(tableName, id, "update", replaced);
+      if (hasMatchingTrigger(tableName, "after", "update")) {
+        await fireTriggers("after", "update", { doc: replaced, id, op: "update", previous, table: tableName });
+      }
+    }
+  };
+  triggerContext = { db: writer, scheduler };
+  return writer;
+};
+
+export { createSqlCtxDb, decodeGlobalRow, readSqlCdcChanges, runSqlAggregateMigrations, runSqlCdcMigration, runSqlGlobalTableMigrations, runSqlRankMigrations, runSqlSearchMigrations, trimSqlCdcChanges };