@lunora/do 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/packem_shared/{NotUniqueError-B6tzuDmM.mjs → NotUniqueError-DbtlWwcG.mjs}

@@ -1,27 +1,31 @@
+import { LunoraError } from '@lunora/errors';
 import { sql } from 'drizzle-orm';
-import { matchesStaticWhere, aggregateSqlFunction, normalizeCountArgument, throwingScheduler } from './AGGREGATE_SQL_FUNCTION-CFk6adSu.mjs';
+import { matchesStaticWhere, aggregateSqlFunction, normalizeCountArgument, throwingScheduler } from './AGGREGATE_SQL_FUNCTION-CQsu2Xga.mjs';
 import { encodeAggregateKey, foldAggregateTally, aggregateTableName, coerceAggregateNumber, readAggregateValue } from './aggregateTableName-CxNqY1Sl.mjs';
-import { mergeWhere, CountRlsUnsupportedError, selectIndexForGroupBy, selectIndexForCount, selectIndexForAggregate } from './CountRlsUnsupportedError-28ZvvwKS.mjs';
-import { appendCdcChange } from './CDC_LOG_TABLE-Ctdmxmrv.mjs';
-export { CDC_LOG_TABLE, applyCdcChanges, bumpCdcEpoch, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './CDC_LOG_TABLE-Ctdmxmrv.mjs';
+import { mergeWhere, CountRlsUnsupportedError, selectIndexForGroupBy, selectIndexForCount, selectIndexForAggregate } from './CountRlsUnsupportedError-BGxj0pgS.mjs';
+import { appendCdcChange } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
+export { CDC_LOG_TABLE, applyCdcChanges, bumpCdcEpoch, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './CDC_LOG_TABLE-uwOJxJJZ.mjs';
 import { r as runDrizzle } from './do-exec-5eQy5cEi.mjs';
-import { i as isFtsAvailable, D as DOC_COLUMN$1, r as rowToDocument, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT, d as aggUpsertSql, j as jsonPathSql, q as quoteIdentifier, t as tableColumns, e as qualifiedJsonPathSql } from './do-sql-BCHCWtrD.mjs';
+import { i as isFtsAvailable, D as DOC_COLUMN$1, r as rowToDocument, A as AGG_KEY, a as AGG_VALUE, b as AGG_COUNT, g as geoTableName, d as aggUpsertSql, j as jsonPathSql, q as quoteIdentifier, t as tableColumns, e as qualifiedJsonPathSql } from './do-sql-CGAgiQUz.mjs';
 import { param } from './renderSql-D6eUcn2N.mjs';
-import { s as sortColumnName, m as matchesRankStaticWhere, e as encodePartitionKey, b as serializeSqlValue, r as rankTableName, a as resolveRankPartition, R as RANK_TIEBREAK } from './rank-CrkEIpF4.mjs';
+import { encodeGeohash, GEO_DEFAULT_PRECISION, coveringGeohashes, boundingBoxGeohashes, pointInBoundingBox, haversineMeters } from './GEO_DEFAULT_PRECISION-BWnsNmpP.mjs';
+import { sortColumnName, matchesRankStaticWhere, encodePartitionKey, rankTableName, resolveRankPartition, RANK_TIEBREAK } from './RANK_TIEBREAK-CXhdcA1o.mjs';
 import { stringifySearchText, ftsTableName, tokenizeSearch, buildFtsMatch, scoreDocument } from './buildFtsMatch-BLEMawrp.mjs';
+import { s as serializeSqlValue } from './serialize-sql-BlRUoiQe.mjs';
 import { SCAN_DEP } from './SCAN_DEP-DLJF8dsj.mjs';
-import { decodeCursor, normalizeOrderKeys, buildSeekWhere, encodeCursor, buildSeekBeforeWhere } from './buildSeekWhere-lVsNXSLy.mjs';
-import NotFoundError from './NotFoundError-CMuMZt81.mjs';
-import { assertFlatPredicate, resolveRelationPredicates } from './DEFAULT_MAX_RELATION_KEYS-DyVYReuT.mjs';
-import { runRowValidators, resolveWith, applyOnDelete } from './applyOnDelete-CMif2RKw.mjs';
-import { guardWriter } from './RLS_UNWRAP_SYMBOL-u3UlnCH5.mjs';
-import { createSystemReader } from './createSystemReader-8CzSZP9V.mjs';
-import { ConflictError } from './ConflictError-C0STs6bU.mjs';
+import { decodeCursor, normalizeOrderKeys, buildSeekWhere, applySelect, encodeCursor, softDeleteScope, buildSeekBeforeWhere } from './applySelect-WQY8m62C.mjs';
+import NotFoundError from './NotFoundError-C70b9hLw.mjs';
+import { assertFlatPredicate, resolveRelationPredicates } from './DEFAULT_MAX_RELATION_KEYS-BEan1CRD.mjs';
+import { runRowValidators, resolveWith, applyOnDelete, fanOutScalarCounts } from './applyOnDelete-BXSq3S70.mjs';
+import { guardWriter } from './RLS_UNWRAP_SYMBOL-DTvHvRzY.mjs';
+import { createSystemReader } from './createSystemReader-D12eNH13.mjs';
+import { ConflictError } from './ConflictError-CLoq37xH.mjs';
 import { runTriggers } from './hasTrigger-5N6_Fx0A.mjs';
-import { compileWhereSql } from './compileWhereSql-CXrhFA3G.mjs';
-export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-BbVPvciS.mjs';
-export { I as IDEMPOTENCY_TABLE, r as readIdempotent, t as trimIdempotent, w as writeIdempotent } from './ctx-db-idempotency-DkC9rP91.mjs';
-export { runShardMigrations } from './runShardMigrations-PabobOjF.mjs';
+import { compileWhereSql } from './compileWhereSql-DE6yfRcQ.mjs';
+export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-BGTwynwh.mjs';
+export { C as CLIENT_WATERMARK_TABLE, G as GLOBAL_SHAPE_SNAPSHOT_TABLE, I as IDEMPOTENCY_TABLE, c as advanceClientWatermark, d as deleteGlobalShapeSnapshot, e as deleteGlobalShapeSnapshotsForConnection, m as migrateClientWatermark, b as migrateGlobalShapeSnapshot, r as readClientWatermark, f as readGlobalShapeSnapshot, g as readIdempotent, t as trimIdempotent, w as writeGlobalShapeSnapshot, h as writeIdempotent } from './ctx-db-idempotency-BdcNpvY4.mjs';
+export { runShardMigrations } from './runShardMigrations-BVax6rYu.mjs';
+export { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-DTeFiHYS.mjs';
 
 const rankIndexFieldsUnchanged = (index, previous, next) => {
   const fields = [...index.partitionBy ?? [], ...index.sortBy.map((key) => key.field), ...index.where ? Object.keys(index.where) : []];
@@ -311,8 +315,28 @@ const createCompanionSync = (deps) => {
       }
     }
   };
+  const syncGeo = (tableName, id, document) => {
+    const indexes = schema.tables[tableName]?.geoIndexes;
+    if (!indexes || indexes.length === 0) {
+      return;
+    }
+    for (const index of indexes) {
+      const geoTable = geoTableName(tableName, index.name);
+      runDrizzle(sql$1, sql`DELETE FROM ${sql.identifier(geoTable)} WHERE ${sql.identifier("__id__")} = ${id}`);
+      const point = document?.[index.field];
+      if (point !== null && typeof point === "object" && typeof point.lat === "number" && typeof point.lng === "number") {
+        const { lat, lng } = point;
+        const hash = encodeGeohash({ lat, lng }, index.precision ?? GEO_DEFAULT_PRECISION);
+        runDrizzle(
+          sql$1,
+          sql`INSERT INTO ${sql.identifier(geoTable)} (${sql.identifier("__id__")}, ${sql.identifier("__geohash__")}, ${sql.identifier("__lat__")}, ${sql.identifier("__lng__")}) VALUES (${id}, ${hash}, ${lat}, ${lng})`
+        );
+      }
+    }
+  };
   const syncCompanionsForInsert = (tableName, id, document) => {
     syncSearch(tableName, id, document);
+    syncGeo(tableName, id, document);
     syncAggregates(tableName, void 0, document);
     syncRanks(tableName, id, void 0, document);
     invalidateCache(tableName, id);
@@ -326,6 +350,7 @@ const createCompanionSync = (deps) => {
     ensureRankBackfilledForTable,
     syncAggregates,
     syncCompanionsForInsert,
+    syncGeo,
     syncRanks,
     syncSearch
   };
@@ -420,11 +445,11 @@ const computeRankPage = (deps, tableName, indexName, rankPageOptions) => {
   const { assertRankPartitionLocal, ensureRankBackfilled, onRead, schema } = deps;
   const definition = schema.tables[tableName];
   if (!definition) {
-    throw new Error(`unknown table: ${tableName}`);
+    throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
   }
   const index = definition.rankIndexes?.find((i) => i.name === indexName);
   if (!index) {
-    throw new Error(`unknown rankIndex "${indexName}" on table "${tableName}"`);
+    throw new LunoraError("INTERNAL", `unknown rankIndex "${indexName}" on table "${tableName}"`);
   }
   assertRankPartitionLocal(tableName, definition, index);
   onRead(tableName, SCAN_DEP);
@@ -472,7 +497,7 @@ const computeRankPage = (deps, tableName, indexName, rankPageOptions) => {
 const CLIENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
 const assertValidClientId = (clientId) => {
   if (!CLIENT_ID_PATTERN.test(clientId)) {
-    throw new Error(`invalid clientId ${JSON.stringify(clientId)}: a client-supplied row id must be a UUID`);
+    throw new LunoraError("INTERNAL", `invalid clientId ${JSON.stringify(clientId)}: a client-supplied row id must be a UUID`);
   }
 };
 const MAX_TRIGGER_DEPTH = 50;
@@ -480,11 +505,11 @@ const DEFAULT_BATCH_LIMIT = 500;
 const assertBatchLimit = (count, limit, op) => {
   const cap = limit ?? DEFAULT_BATCH_LIMIT;
   if (count > cap) {
-    throw Object.assign(new Error(`${op}: batch of ${String(count)} exceeds the limit of ${String(cap)} (raise options.limit or chunk the call)`), {
-      code: "BATCH_LIMIT_EXCEEDED",
-      name: "LunoraError",
-      status: 400
-    });
+    throw new LunoraError(
+      "BATCH_LIMIT_EXCEEDED",
+      `${op}: batch of ${String(count)} exceeds the limit of ${String(cap)} (raise options.limit or chunk the call)`,
+      { status: 400 }
+    );
   }
 };
 const createRangeBuilder = (stage) => {
@@ -516,14 +541,17 @@ 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}"`);
+        throw new LunoraError("INTERNAL", `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}"`);
+        throw new LunoraError(
+          "INTERNAL",
+          `search index "${search.indexName}" on table "${tableName}" indexes "${search.definition.field}", not "${field}"`
+        );
       }
       const stage = search;
       stage.field = field;
@@ -534,7 +562,7 @@ const createSearchBuilder = (search, tableName) => {
   };
   return builder;
 };
-const searchViaFts = (sql$1, tableName, search, limit) => {
+const searchViaFts = (sql$1, tableName, search, limit, scopeCondition) => {
   const tokens = tokenizeSearch(search.query);
   if (tokens.length === 0) {
     return [];
@@ -544,6 +572,9 @@ const searchViaFts = (sql$1, tableName, search, limit) => {
   for (const filter of search.filters) {
     whereClauses.push(sql`${jsonPathSql(filter.field)} = ${serializeSqlValue(filter.value)}`);
   }
+  if (scopeCondition) {
+    whereClauses.push(scopeCondition);
+  }
   let query = sql`SELECT m.id, m._creationTime, m.${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(ftName)} f JOIN ${sql.identifier(tableName)} m ON m.id = f.${sql.identifier("__id__")} WHERE ${sql.join(whereClauses, sql` AND `)} ORDER BY f.rank, m._creationTime DESC`;
   if (typeof limit === "number") {
     query = sql`${query} LIMIT ${sql.raw(String(Math.max(0, Math.floor(limit))))}`;
@@ -558,7 +589,7 @@ const searchViaFts = (sql$1, tableName, search, limit) => {
   }
   return docs;
 };
-const searchViaScan = (sql$1, tableName, search, limit) => {
+const searchViaScan = (sql$1, tableName, search, limit, scopeCondition) => {
   const tokens = tokenizeSearch(search.query);
   if (tokens.length === 0) {
     return [];
@@ -567,6 +598,9 @@ const searchViaScan = (sql$1, tableName, search, limit) => {
   for (const filter of search.filters) {
     whereClauses.push(sql`${jsonPathSql(filter.field)} = ${serializeSqlValue(filter.value)}`);
   }
+  if (scopeCondition) {
+    whereClauses.push(scopeCondition);
+  }
   let query = sql`SELECT id, _creationTime, ${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(tableName)}`;
   if (whereClauses.length > 0) {
     query = sql`${query} WHERE ${sql.join(whereClauses, sql` AND `)}`;
@@ -587,6 +621,123 @@ const searchViaScan = (sql$1, tableName, search, limit) => {
   const docs = scored.map((entry) => entry.doc);
   return typeof limit === "number" ? docs.slice(0, Math.max(0, Math.floor(limit))) : docs;
 };
+const createGeoBuilder = (geo, tableName) => {
+  const staged = geo;
+  const builder = {
+    near: (point, radiusMeters) => {
+      if (staged.within) {
+        throw new LunoraError("INTERNAL", `geo index "${staged.indexName}" on table "${tableName}": call .near() or .within(), not both`);
+      }
+      staged.near = { point: { lat: point.lat, lng: point.lng }, radiusMeters };
+      return builder;
+    },
+    within: (box) => {
+      if (staged.near) {
+        throw new LunoraError("INTERNAL", `geo index "${staged.indexName}" on table "${tableName}": call .near() or .within(), not both`);
+      }
+      staged.within = { ne: { lat: box.ne.lat, lng: box.ne.lng }, sw: { lat: box.sw.lat, lng: box.sw.lng } };
+      return builder;
+    }
+  };
+  return builder;
+};
+const readGeoPoint = (document, field) => {
+  const value = document[field];
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const { lat, lng } = value;
+  return typeof lat === "number" && typeof lng === "number" ? { lat, lng } : void 0;
+};
+const scoreGeoRow = (record, geo) => {
+  const point = readGeoPoint(record, geo.definition.field);
+  if (!point) {
+    return void 0;
+  }
+  const creationTime = typeof record["_creationTime"] === "number" ? record["_creationTime"] : 0;
+  if (geo.near) {
+    const distance = haversineMeters(geo.near.point, point);
+    return distance <= geo.near.radiusMeters ? { creationTime, distance } : void 0;
+  }
+  return pointInBoundingBox(point, geo.within) ? { creationTime, distance: 0 } : void 0;
+};
+const runGeoFetch = (sql$1, tableName, geo, limit, scopeCondition) => {
+  if (!geo.near && !geo.within) {
+    throw new LunoraError("INTERNAL", `geo index "${geo.indexName}" on table "${tableName}": call .near(point, radius) or .within(box)`);
+  }
+  const prefixes = geo.near ? coveringGeohashes(geo.near.point, geo.near.radiusMeters) : boundingBoxGeohashes(geo.within);
+  const geoTable = geoTableName(tableName, geo.indexName);
+  const prefixClauses = prefixes.map(
+    (prefix) => sql`(g.${sql.identifier("__geohash__")} >= ${prefix} AND g.${sql.identifier("__geohash__")} < ${`${prefix}{`})`
+  );
+  const whereClauses = [sql`(${sql.join(prefixClauses, sql` OR `)})`];
+  if (scopeCondition) {
+    whereClauses.push(scopeCondition);
+  }
+  const query = sql`SELECT m.id, m._creationTime, m.${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(geoTable)} g JOIN ${sql.identifier(tableName)} m ON m.id = g.${sql.identifier("__id__")} WHERE ${sql.join(whereClauses, sql` AND `)}`;
+  const rows = runDrizzle(sql$1, query).toArray();
+  const scored = [];
+  for (const row of rows) {
+    const record = rowToDocument(row);
+    const score = record ? scoreGeoRow(record, geo) : void 0;
+    if (record && score) {
+      scored.push({ creationTime: score.creationTime, distance: score.distance, doc: record });
+    }
+  }
+  scored.sort((a, b) => a.distance - b.distance || b.creationTime - a.creationTime);
+  const docs = scored.map((entry) => entry.doc);
+  return typeof limit === "number" ? docs.slice(0, Math.max(0, Math.floor(limit))) : docs;
+};
+const runGeoTerminal = (sql, tableName, stage, scopeCondition, limit) => {
+  const { geo } = stage;
+  if (!geo) {
+    throw new LunoraError("INTERNAL", "runGeoTerminal called without a staged geo query");
+  }
+  const filtered = stage.inMemoryFilters.length > 0;
+  const docs = runGeoFetch(sql, tableName, geo, filtered ? void 0 : limit, scopeCondition);
+  if (!filtered) {
+    return docs;
+  }
+  const result = [];
+  for (const record of docs) {
+    if (stage.inMemoryFilters.every((predicate) => predicate(record))) {
+      result.push(record);
+      if (typeof limit === "number" && result.length >= limit) {
+        break;
+      }
+    }
+  }
+  return result;
+};
+const runPlainFetch = (sql$1, tableName, stage, scopeCondition, orderClause, limit) => {
+  const whereClauses = [];
+  for (const condition of stage.sqlConditions) {
+    whereClauses.push(sql`${jsonPathSql(condition.field)} ${sql.raw(condition.comparator)} ${serializeSqlValue(condition.value)}`);
+  }
+  if (scopeCondition) {
+    whereClauses.push(scopeCondition);
+  }
+  let query = sql`SELECT id, _creationTime, ${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(tableName)}`;
+  if (whereClauses.length > 0) {
+    query = sql`${query} WHERE ${sql.join(whereClauses, sql` AND `)}`;
+  }
+  query = sql`${query} ORDER BY ${orderClause}`;
+  if (typeof limit === "number" && stage.inMemoryFilters.length === 0) {
+    query = sql`${query} LIMIT ${sql.raw(String(Math.max(0, Math.floor(limit))))}`;
+  }
+  const rows = runDrizzle(sql$1, query).toArray();
+  const docs = [];
+  for (const row of rows) {
+    const record = rowToDocument(row);
+    if (record && stage.inMemoryFilters.every((predicate) => predicate(record))) {
+      docs.push(record);
+      if (typeof limit === "number" && docs.length >= limit) {
+        break;
+      }
+    }
+  }
+  return docs;
+};
 const doWhereSqlStrategy = { fieldRef: jsonPathSql, serialize: serializeSqlValue };
 const makeRelationExistsSqlStrategy = (onRead) => {
   let aliasCounter = 0;
@@ -660,11 +811,12 @@ const scanDocs = (rows, filters, cap) => {
   }
   return docs;
 };
-const paginateStage = (sql$1, tableName, stage, options) => {
+const paginateStage = (sql$1, tableName, stage, options, scopeCondition) => {
   const numberItems = Math.max(0, Math.floor(options.numItems));
   const orderKeys = paginateOrderKeys(stage);
   const bounded = typeof options.endCursor === "string";
-  const whereCondition = compileWhereSql(paginateWhere(stage, orderKeys, options.cursor, options.endCursor), doWhereSqlStrategy);
+  const pageWhere = compileWhereSql(paginateWhere(stage, orderKeys, options.cursor, options.endCursor), doWhereSqlStrategy);
+  const whereCondition = scopeCondition && pageWhere ? sql`${pageWhere} AND ${scopeCondition}` : scopeCondition ?? pageWhere;
   let query = sql`SELECT id, _creationTime, ${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(tableName)}`;
   if (whereCondition) {
     query = sql`${query} WHERE ${whereCondition}`;
@@ -697,19 +849,16 @@ const paginateStage = (sql$1, tableName, stage, options) => {
     page
   };
 };
-class NotUniqueError extends Error {
-  code = "NOT_UNIQUE";
-  status = 400;
+class NotUniqueError extends LunoraError {
   constructor(message = "unique() found more than one matching document") {
-    super(message);
-    this.name = "NotUniqueError";
+    super("NOT_UNIQUE", message, { name: "NotUniqueError" });
   }
 }
 const ID_WHITESPACE_PATTERN = /\s/u;
 const NUL_CHARACTER = String.fromCodePoint(0);
 const normalizeIdStructurally = (schema, tableName, id) => {
   if (!schema.tables[tableName]) {
-    throw new Error(`unknown table: ${tableName}`);
+    throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
   }
   if (typeof id !== "string" || id.length === 0 || ID_WHITESPACE_PATTERN.test(id) || id.includes(NUL_CHARACTER)) {
     return null;
@@ -719,8 +868,10 @@ const normalizeIdStructurally = (schema, tableName, id) => {
 const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
   const tableDefinition = schema.tables[tableName];
   if (!tableDefinition) {
-    throw new Error(`unknown table: ${tableName}`);
+    throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
   }
+  const scopeWhere = softDeleteScope(tableDefinition.softDeleteMode, void 0);
+  const scopeCondition = scopeWhere ? compileWhereSql(scopeWhere, doWhereSqlStrategy) : void 0;
   const stage = {
     indexFields: [],
     indexName: void 0,
@@ -731,11 +882,11 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
   const runSearchFetch = (limit) => {
     const { search } = stage;
     if (!search) {
-      throw new Error("runSearchFetch called without a staged search");
+      throw new LunoraError("INTERNAL", "runSearchFetch called without a staged search");
     }
     const filtered = stage.inMemoryFilters.length > 0;
     const engineLimit = filtered ? void 0 : limit;
-    const docs = isFtsAvailable(sql$1) ? searchViaFts(sql$1, tableName, search, engineLimit) : searchViaScan(sql$1, tableName, search, engineLimit);
+    const docs = isFtsAvailable(sql$1) ? searchViaFts(sql$1, tableName, search, engineLimit, scopeCondition) : searchViaScan(sql$1, tableName, search, engineLimit, scopeCondition);
     if (!filtered) {
       return docs;
     }
@@ -762,33 +913,10 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
     if (stage.search) {
       return runSearchFetch(limit);
     }
-    const whereClauses = [];
-    for (const condition of stage.sqlConditions) {
-      whereClauses.push(sql`${jsonPathSql(condition.field)} ${sql.raw(condition.comparator)} ${serializeSqlValue(condition.value)}`);
-    }
-    let query = sql`SELECT id, _creationTime, ${sql.identifier(DOC_COLUMN$1)} FROM ${sql.identifier(tableName)}`;
-    if (whereClauses.length > 0) {
-      query = sql`${query} WHERE ${sql.join(whereClauses, sql` AND `)}`;
-    }
-    query = sql`${query} ORDER BY ${buildOrderClause()}`;
-    if (typeof limit === "number" && stage.inMemoryFilters.length === 0) {
-      query = sql`${query} LIMIT ${sql.raw(String(Math.max(0, Math.floor(limit))))}`;
+    if (stage.geo) {
+      return runGeoTerminal(sql$1, tableName, stage, scopeCondition, limit);
     }
-    const rows = runDrizzle(sql$1, query).toArray();
-    const docs = [];
-    for (const row of rows) {
-      const record = rowToDocument(row);
-      if (!record) {
-        continue;
-      }
-      if (stage.inMemoryFilters.every((predicate) => predicate(record))) {
-        docs.push(record);
-        if (typeof limit === "number" && docs.length >= limit) {
-          break;
-        }
-      }
-    }
-    return docs;
+    return runPlainFetch(sql$1, tableName, stage, scopeCondition, buildOrderClause(), limit);
   };
   const reader = {
     // eslint-disable-next-line @typescript-eslint/require-await -- TableReaderLike returns Promises (the D1 twin awaits real I/O); the DO impl is synchronous over local SQLite
@@ -811,9 +939,12 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
     // eslint-disable-next-line @typescript-eslint/require-await -- TableReaderLike returns Promises (the D1 twin awaits real I/O); the DO impl is synchronous over local SQLite
     async paginate(options) {
       if (stage.search) {
-        throw new Error("pagination is not supported on search queries; use .take(n) or .collect()");
+        throw new LunoraError("INTERNAL", "pagination is not supported on search queries; use .take(n) or .collect()");
       }
-      return paginateStage(sql$1, tableName, stage, options);
+      if (stage.geo) {
+        throw new LunoraError("INTERNAL", "pagination is not supported on geo queries; use .take(n) or .collect()");
+      }
+      return paginateStage(sql$1, tableName, stage, options, scopeCondition);
     },
     // eslint-disable-next-line @typescript-eslint/require-await -- TableReaderLike returns Promises (the D1 twin awaits real I/O); the DO impl is synchronous over local SQLite
     async take(limit) {
@@ -827,10 +958,24 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
       }
       return rows[0] ?? null;
     },
+    withGeoIndex(indexName, build) {
+      const definition = (tableDefinition.geoIndexes ?? []).find((index) => index.name === indexName);
+      if (!definition) {
+        throw new LunoraError("INTERNAL", `unknown geo index "${indexName}" on table "${tableName}"`);
+      }
+      onIndexUse(tableName, indexName, "geo");
+      const geoStage = { definition, indexName };
+      stage.geo = geoStage;
+      build(createGeoBuilder(geoStage, tableName));
+      if (!geoStage.near && !geoStage.within) {
+        throw new LunoraError("INTERNAL", `geo index "${indexName}" on table "${tableName}" requires a .near(point, radius) or .within(box) call`);
+      }
+      return reader;
+    },
     withIndex(indexName, range) {
       const definition = tableDefinition.indexes.find((index) => index.name === indexName);
       if (!definition) {
-        throw new Error(`unknown index "${indexName}" on table "${tableName}"`);
+        throw new LunoraError("INTERNAL", `unknown index "${indexName}" on table "${tableName}"`);
       }
       onIndexUse(tableName, indexName, "index");
       stage.indexName = indexName;
@@ -843,7 +988,7 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
     withSearchIndex(indexName, search) {
       const definition = (tableDefinition.searchIndexes ?? []).find((index) => index.name === indexName);
       if (!definition) {
-        throw new Error(`unknown search index "${indexName}" on table "${tableName}"`);
+        throw new LunoraError("INTERNAL", `unknown search index "${indexName}" on table "${tableName}"`);
       }
       onIndexUse(tableName, indexName, "search");
       const searchStage = {
@@ -857,7 +1002,7 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
       stage.search = searchStage;
       search(createSearchBuilder(searchStage, tableName));
       if (!searchStage.hasQuery) {
-        throw new Error(`search index "${indexName}" on table "${tableName}" requires a .search(field, query) call`);
+        throw new LunoraError("INTERNAL", `search index "${indexName}" on table "${tableName}" requires a .search(field, query) call`);
       }
       return reader;
     }
@@ -899,7 +1044,10 @@ const applyOnUpdate = (definition, provided, target, auth) => {
 const assertNoExplicitUndefined = (op, document) => {
   for (const field of Object.keys(document)) {
     if (document[field] === void 0) {
-      throw new Error(`Cannot ${op} field '${field}' to undefined — use null to clear a nullable field, or omit the key to leave it unchanged.`);
+      throw new LunoraError(
+        "INTERNAL",
+        `Cannot ${op} field '${field}' to undefined — use null to clear a nullable field, or omit the key to leave it unchanged.`
+      );
     }
   }
 };
@@ -979,7 +1127,10 @@ const createShardCtxDb = (options) => {
   const routeBackend = (table, op) => {
     if (isGlobalTable(table)) {
       if (!globalDb) {
-        throw new Error(`cross-backend ${op} for global table '${table}' requires a globalDb writer — pass one to createShardCtxDb({ globalDb })`);
+        throw new LunoraError(
+          "INTERNAL",
+          `cross-backend ${op} for global table '${table}' requires a globalDb writer — pass one to createShardCtxDb({ globalDb })`
+        );
       }
       return globalDb;
     }
@@ -991,13 +1142,12 @@ const createShardCtxDb = (options) => {
       return void 0;
     }
     if (!globalDb) {
-      throw new Error(`${op} on global table '${tableName}' requires a globalDb writer — pass one to createShardCtxDb({ globalDb })`);
+      throw new LunoraError("INTERNAL", `${op} on global table '${tableName}' requires a globalDb writer — pass one to createShardCtxDb({ globalDb })`);
     }
     return globalDb;
   };
   const globalFallback = () => globalDb;
   const relationFetcher = (relationTable, relationArgs) => routeBackend(relationTable, "relation load").findMany(relationTable, relationArgs);
-  const relationCounter = (relationTable, relationWhere) => routeBackend(relationTable, "relation load").count(relationTable, relationWhere);
   const relationPredicateFetcher = (relationTable, relationArgs) => {
     if (isGlobalTable(relationTable)) {
       onRead(relationTable, SCAN_DEP);
@@ -1015,6 +1165,31 @@ const createShardCtxDb = (options) => {
     schema,
     tableName: predicateTable
   });
+  const relationGroupedCounter = async (relationTable, whereField, values, policyWhere) => {
+    const globalWriter = globalWriterFor(relationTable, "relation grouped count");
+    if (globalWriter) {
+      onRead(relationTable, SCAN_DEP);
+      return fanOutScalarCounts((t, w) => globalWriter.count(t, w), relationTable, whereField, values, policyWhere);
+    }
+    const definition = schema.tables[relationTable];
+    if (!definition) {
+      throw new LunoraError("INTERNAL", `unknown table: ${relationTable}`);
+    }
+    onRead(relationTable, SCAN_DEP);
+    const softScope = softDeleteScope(definition.softDeleteMode, void 0);
+    const inFilter = { [whereField]: { in: values } };
+    const combined = mergeWhere(mergeWhere(inFilter, policyWhere), softScope);
+    const resolvedCombined = await resolveAggregateRelations(combined, relationTable, void 0);
+    const whereCondition = compileWhereSql(resolvedCombined, doWhereSqlStrategy);
+    const fieldSql = jsonPathSql(whereField);
+    let query = sql`SELECT ${fieldSql} AS __fk__, COUNT(*) AS count FROM ${sql.identifier(relationTable)}`;
+    if (whereCondition) {
+      query = sql`${query} WHERE ${whereCondition}`;
+    }
+    query = sql`${query} GROUP BY ${fieldSql}`;
+    const rows = runDrizzle(sql$1, query).toArray();
+    return new Map(rows.map((row) => [row["__fk__"], row.count]));
+  };
   let triggerDepth = 0;
   const triggerMatchers = /* @__PURE__ */ new Set();
   for (const [tableName, definition] of Object.entries(schema.tables)) {
@@ -1045,6 +1220,7 @@ const createShardCtxDb = (options) => {
     ensureRankBackfilledForTable,
     syncAggregates,
     syncCompanionsForInsert,
+    syncGeo,
     syncRanks,
     syncSearch
   } = createCompanionSync({
@@ -1115,7 +1291,7 @@ const createShardCtxDb = (options) => {
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       aggregateSqlFunction(aggOptions.op);
       if (aggOptions.op === "count") {
@@ -1127,13 +1303,14 @@ const createShardCtxDb = (options) => {
         });
       }
       if (!aggOptions.field) {
-        throw new Error(`aggregate(${tableName}, { op: "${aggOptions.op}" }): "field" is required for non-count reducers`);
+        throw new LunoraError("INTERNAL", `aggregate(${tableName}, { op: "${aggOptions.op}" }): "field" is required for non-count reducers`);
       }
       onRead(tableName, SCAN_DEP);
-      const effective = mergeWhere(aggOptions.baseWhere, aggOptions.where);
+      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) {
+      if (definition.aggregateIndexes && !aggOptions.baseWhere && !hasRelation && !aggScope) {
         const planned = selectIndexForAggregate(definition.aggregateIndexes, aggOptions.op, aggOptions.field, aggOptions.where);
         if (planned) {
           ensureBackfilled(tableName, planned.index);
@@ -1168,17 +1345,18 @@ const createShardCtxDb = (options) => {
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       const countOptions = normalizeCountArgument(whereOrOptions);
       if (countOptions.restrictsCounts) {
         throw new CountRlsUnsupportedError(tableName);
       }
       onRead(tableName, SCAN_DEP);
-      const effective = mergeWhere(countOptions.baseWhere, countOptions.where);
+      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) {
+      if (definition.aggregateIndexes && !countOptions.baseWhere && !hasRelation && !countScope) {
         const planned = selectIndexForCount(definition.aggregateIndexes, countOptions.where);
         if (planned) {
           ensureBackfilled(tableName, planned.index);
@@ -1199,16 +1377,22 @@ const createShardCtxDb = (options) => {
       const row = runDrizzle(sql$1, query).one();
       return row.count;
     },
-    async delete(id, expectedTable) {
+    async delete(id, expectedTable, deleteOptions) {
       const located = locateRowById(id, expectedTable);
       if (!located) {
         const global = expectedTable === void 0 ? globalFallback() : void 0;
         if (global) {
-          await global.delete(id);
+          await global.delete(id, void 0, deleteOptions);
         }
         return;
       }
       const { docJson: existingJson, row: existing, tableName } = located;
+      const definition = schema.tables[tableName];
+      const hard = deleteOptions?.hard === true;
+      const softField = !hard && definition?.softDeleteMode ? definition.softDeleteMode.field : void 0;
+      if (softField && existing[softField] !== null && existing[softField] !== void 0) {
+        return;
+      }
       if (hasMatchingTrigger(tableName, "before", "delete")) {
         await fireTriggers("before", "delete", { id, op: "delete", previous: existing, table: tableName });
       }
@@ -1216,10 +1400,10 @@ const createShardCtxDb = (options) => {
         deletedId: id,
         deletedReference: (references) => existing[references],
         findHolders: async (holderTable, field, value) => {
-          const holders = await routeForHolder(holderTable).findMany(holderTable, { where: { [field]: value } });
+          const holders = await routeForHolder(holderTable).findMany(holderTable, { includeDeleted: hard, where: { [field]: value } });
           return holders.page;
         },
-        onCascade: (holderTable, holderId) => routeForHolder(holderTable).delete(holderId),
+        onCascade: (holderTable, holderId) => routeForHolder(holderTable).delete(holderId, void 0, deleteOptions),
         onRestrict: (message) => {
           throw new ConflictError(message, "restrict");
         },
@@ -1230,12 +1414,33 @@ const createShardCtxDb = (options) => {
       });
       ensureBackfilledForTable(tableName);
       ensureRankBackfilledForTable(tableName);
+      if (softField) {
+        const merged = { ...existing, [softField]: clock(), _id: id };
+        runGuardedWrite(
+          sql$1,
+          tableName,
+          sql`UPDATE ${sql.identifier(tableName)} SET ${sql.identifier(DOC_COLUMN$1)} = ${JSON.stringify(merged)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
+        );
+        syncSearch(tableName, id, merged);
+        syncGeo(tableName, id, void 0);
+        syncAggregates(tableName, existing, merged);
+        syncRanks(tableName, id, existing, void 0);
+        cache?.invalidate(tableName, id);
+        recordCdc(tableName, id, "update", merged);
+        broadcast({ key: id, op: "update", row: merged, table: tableName });
+        if (hasMatchingTrigger(tableName, "after", "delete")) {
+          await fireTriggers("after", "delete", { id, op: "delete", previous: existing, table: tableName });
+        }
+        await onWrite({ id, op: "delete", table: tableName });
+        return;
+      }
       runGuardedWrite(
         sql$1,
         tableName,
         sql`DELETE FROM ${sql.identifier(tableName)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
       );
       syncSearch(tableName, id, void 0);
+      syncGeo(tableName, id, void 0);
       syncAggregates(tableName, existing, void 0);
       syncRanks(tableName, id, existing, void 0);
       cache?.invalidate(tableName, id);
@@ -1253,6 +1458,25 @@ const createShardCtxDb = (options) => {
       }
       return { deleted: ids.length };
     },
+    async deleteWhere(tableName, where, batchOptions) {
+      const global = globalWriterFor(tableName, "deleteWhere");
+      let ids;
+      if (global) {
+        const rows = await global.findMany(tableName, { where });
+        ids = rows.page.map((row) => String(row["_id"]));
+      } else {
+        if (!schema.tables[tableName]) {
+          throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
+        }
+        const page = await writer.findMany(tableName, { where });
+        ids = page.page.map((row) => String(row["_id"]));
+      }
+      assertBatchLimit(ids.length, batchOptions?.limit, "deleteWhere");
+      if (writer.deleteMany === void 0) {
+        throw new LunoraError("INTERNAL", `ctx.db.${tableName}.deleteMany is unavailable: this writer has no batch delete`);
+      }
+      return writer.deleteMany(ids, batchOptions);
+    },
     async findFirst(tableName, args = {}) {
       const result = await writer.findMany(tableName, { ...args, limit: 1 });
       return result.page[0] ?? null;
@@ -1271,8 +1495,9 @@ const createShardCtxDb = (options) => {
         onRead(tableName, SCAN_DEP);
         return global.findMany(tableName, args);
       }
-      if (!schema.tables[tableName]) {
-        throw new Error(`unknown table: ${tableName}`);
+      const findManyDefinition = schema.tables[tableName];
+      if (!findManyDefinition) {
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       const isFullScan = !args.where && !args.baseWhere;
       if (isFullScan) {
@@ -1283,6 +1508,7 @@ const createShardCtxDb = (options) => {
       const orderKeys = normalizeOrderKeys(args.orderBy);
       const seek = args.cursor ? buildSeekWhere(orderKeys, decodeCursor(args.cursor)) : void 0;
       let predicate = mergeWhere(args.baseWhere, args.where);
+      predicate = mergeWhere(predicate, softDeleteScope(findManyDefinition.softDeleteMode, args.includeDeleted));
       predicate = await resolveRelationPredicates(predicate, {
         canPushExists: relationExistsPushDownEnabled ? canPushRelationExists : void 0,
         existsPushMode: relationExistsPushDown === "always" ? "always" : "auto",
@@ -1320,7 +1546,7 @@ const createShardCtxDb = (options) => {
       if (limit === void 0) {
         if (args.with) {
           await resolveWith({
-            counter: relationCounter,
+            groupedCounter: relationGroupedCounter,
             fetcher: relationFetcher,
             parents: docs,
             relationBaseWhere: args.relationBaseWhere,
@@ -1329,15 +1555,15 @@ const createShardCtxDb = (options) => {
             with: args.with
           });
         }
-        return { continueCursor: null, isDone: true, page: docs };
+        return { continueCursor: null, isDone: true, page: applySelect(docs, args.select, args.with) };
       }
       const hasMore = docs.length > limit;
       const page = hasMore ? docs.slice(0, limit) : docs;
       const last = page.at(-1);
       if (args.with) {
         await resolveWith({
-          counter: relationCounter,
           fetcher: relationFetcher,
+          groupedCounter: relationGroupedCounter,
           parents: page,
           relationBaseWhere: args.relationBaseWhere,
           schema,
@@ -1346,10 +1572,12 @@ const createShardCtxDb = (options) => {
         });
       }
       return {
+        // The cursor is encoded from `last` (the full, unprojected row) above,
+        // so `applySelect` only trims the returned payload — paging is intact.
         // eslint-disable-next-line unicorn/no-null -- QueryPage.continueCursor is `null | string`: null is the documented "no further page" cursor on the wire
         continueCursor: hasMore && last ? encodeCursor(last, orderKeys) : null,
         isDone: !hasMore,
-        page
+        page: applySelect(page, args.select, args.with)
       };
     },
     async get(id, expectedTable) {
@@ -1382,18 +1610,19 @@ const createShardCtxDb = (options) => {
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       onRead(tableName, SCAN_DEP);
       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`);
+        throw new LunoraError("INTERNAL", `groupBy(${tableName}, { agg: { op: "${agg.op}" } }): "field" is required for non-count reducers`);
       }
-      const effective = mergeWhere(groupOptions.baseWhere, groupOptions.where);
+      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) {
+      if (definition.aggregateIndexes && !groupOptions.baseWhere && !hasRelation && !groupScope) {
         const planned = selectIndexForGroupBy(definition.aggregateIndexes, agg.op, agg.field, groupOptions.by, groupOptions.where);
         if (planned) {
           ensureBackfilled(tableName, planned.index);
@@ -1432,7 +1661,7 @@ const createShardCtxDb = (options) => {
       } else {
         const { field } = agg;
         if (field === void 0) {
-          throw new Error(`groupBy(${tableName}, { agg: { op: "${agg.op}" } }): "field" is required for non-count reducers`);
+          throw new LunoraError("INTERNAL", `groupBy(${tableName}, { agg: { op: "${agg.op}" } }): "field" is required for non-count reducers`);
         }
         select.push(sql`${sql.raw(aggregateSqlFunction(agg.op))}(${jsonPathSql(field)}) AS value`);
       }
@@ -1465,7 +1694,7 @@ const createShardCtxDb = (options) => {
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       const withDefaults = applyInsertDefaults(definition, document, auth);
       runRowValidators(definition, withDefaults);
@@ -1478,7 +1707,7 @@ const createShardCtxDb = (options) => {
       } else {
         id = generateId();
       }
-      const creationTime = typeof withDefaults["_creationTime"] === "number" ? withDefaults["_creationTime"] : clock();
+      const creationTime = insertOptions?.allowExplicitId && 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 });
@@ -1514,14 +1743,14 @@ const createShardCtxDb = (options) => {
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       ensureBackfilledForTable(tableName);
       ensureRankBackfilledForTable(tableName);
       const rows = documents.map((document) => {
         const withDefaults = applyInsertDefaults(definition, document, auth);
         const id = batchOptions?.allowExplicitId === true && typeof withDefaults["_id"] === "string" ? withDefaults["_id"] : generateId();
-        const creationTime = typeof withDefaults["_creationTime"] === "number" ? withDefaults["_creationTime"] : clock();
+        const creationTime = batchOptions?.allowExplicitId === true && typeof withDefaults["_creationTime"] === "number" ? withDefaults["_creationTime"] : clock();
         return { creationTime, document: { ...withDefaults, _creationTime: creationTime, _id: id }, id };
       });
       const valuesSql = sql.join(
@@ -1537,9 +1766,18 @@ const createShardCtxDb = (options) => {
     },
     async insertMany(tableName, documents, batchOptions) {
       assertBatchLimit(documents.length, batchOptions?.limit, "insertMany");
+      const skipDuplicates = batchOptions?.skipDuplicates === true;
       const ids = [];
       for (const document of documents) {
-        ids.push(await writer.insert(tableName, document));
+        try {
+          ids.push(await writer.insert(tableName, document));
+        } catch (error) {
+          if (skipDuplicates && error instanceof ConflictError && error.kind === "unique") {
+            ids.push(null);
+          } else {
+            throw error;
+          }
+        }
       }
       return ids;
     },
@@ -1554,12 +1792,12 @@ const createShardCtxDb = (options) => {
           await global.patch(id, patch);
           return;
         }
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const { docJson: existingJson, row: existing, tableName } = located;
       const tableDefinition = schema.tables[tableName];
       if (!tableDefinition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       onRead(tableName, id);
       assertNoExplicitUndefined("patch", patch);
@@ -1577,6 +1815,7 @@ const createShardCtxDb = (options) => {
         sql`UPDATE ${sql.identifier(tableName)} SET ${sql.identifier(DOC_COLUMN$1)} = ${JSON.stringify(merged)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
       );
       syncSearch(tableName, id, merged);
+      syncGeo(tableName, id, merged);
       syncAggregates(tableName, existing, merged);
       syncRanks(tableName, id, existing, merged);
       cache?.invalidate(tableName, id);
@@ -1592,6 +1831,31 @@ const createShardCtxDb = (options) => {
       for (const entry of patches) {
         await writer.patch(entry.id, entry.patch, expectedTable);
       }
+      return { patched: patches.length };
+    },
+    async patchWhere(tableName, args, batchOptions) {
+      const global = globalWriterFor(tableName, "patchWhere");
+      let patches;
+      if (global) {
+        const rows = await global.findMany(tableName, { where: args.where });
+        patches = rows.page.map((row) => {
+          return { id: String(row["_id"]), patch: args.patch };
+        });
+      } else {
+        if (!schema.tables[tableName]) {
+          throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
+        }
+        const page = await writer.findMany(tableName, { where: args.where });
+        patches = page.page.map((row) => {
+          return { id: String(row["_id"]), patch: args.patch };
+        });
+      }
+      assertBatchLimit(patches.length, batchOptions?.limit, "patchWhere");
+      if (writer.patchMany === void 0) {
+        throw new LunoraError("INTERNAL", `ctx.db.${tableName}.patchMany is unavailable: this writer has no batch patch`);
+      }
+      await writer.patchMany(patches, batchOptions);
+      return { patched: patches.length };
     },
     query(tableName) {
       const global = globalWriterFor(tableName, "query");
@@ -1611,11 +1875,11 @@ const createShardCtxDb = (options) => {
       onIndexUse(tableName, indexName, "rank");
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       const index = definition.rankIndexes?.find((i) => i.name === indexName);
       if (!index) {
-        throw new Error(`unknown rankIndex "${indexName}" on table "${tableName}"`);
+        throw new LunoraError("INTERNAL", `unknown rankIndex "${indexName}" on table "${tableName}"`);
       }
       assertRankPartitionLocal(tableName, definition, index);
       if (rankOptions.restrictsCounts) {
@@ -1656,17 +1920,18 @@ const createShardCtxDb = (options) => {
     // eslint-disable-next-line @typescript-eslint/require-await -- DatabaseWriterLike returns Promises (the D1 twin awaits I/O); the body is synchronous SQLite
     async rankBefore(tableName, indexName, rankBeforeOptions) {
       if (isGlobalTable(tableName)) {
-        throw new Error(
+        throw new LunoraError(
+          "INTERNAL",
           `rankBefore is not supported on the global (.global()) table '${tableName}' — cross-shard rank cursors apply only to sharded tables`
         );
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       const index = definition.rankIndexes?.find((i) => i.name === indexName);
       if (!index) {
-        throw new Error(`unknown rankIndex "${indexName}" on table "${tableName}"`);
+        throw new LunoraError("INTERNAL", `unknown rankIndex "${indexName}" on table "${tableName}"`);
       }
       if (rankBeforeOptions.restrictsCounts) {
         throw new CountRlsUnsupportedError(tableName);
@@ -1696,23 +1961,43 @@ const createShardCtxDb = (options) => {
       const { directions, hasMore, rows } = computeRankPage(rankPageDeps, tableName, indexName, rankPageOptions);
       return { directions, hasMore, rows };
     },
-    async replace(id, document, expectedTable) {
+    async restore(id, expectedTable) {
+      const located = locateRowById(id, expectedTable);
+      if (!located) {
+        const global = expectedTable === void 0 ? globalFallback() : void 0;
+        if (global?.restore) {
+          await global.restore(id);
+          return;
+        }
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
+      }
+      const field = schema.tables[located.tableName]?.softDeleteMode?.field;
+      if (!field) {
+        throw new LunoraError("INTERNAL", `ctx.db.restore: table "${located.tableName}" is not a .softDelete() table`);
+      }
+      const wasDeleted = located.row[field] !== null && located.row[field] !== void 0;
+      await writer.patch(id, { [field]: null }, expectedTable);
+      if (wasDeleted) {
+        syncRanks(located.tableName, id, void 0, located.row);
+      }
+    },
+    async replace(id, document, expectedTable, replaceOptions) {
       const located = locateRowById(id, expectedTable);
       if (!located) {
         const global = expectedTable === void 0 ? globalFallback() : void 0;
         if (global) {
-          await global.replace(id, document);
+          await global.replace(id, document, void 0, replaceOptions);
           return;
         }
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const { docJson: existingJson, row: previous, tableName } = located;
       const tableDefinition = schema.tables[tableName];
       if (!tableDefinition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       assertNoExplicitUndefined("replace", document);
-      const creationTime = typeof document["_creationTime"] === "number" ? document["_creationTime"] : clock();
+      const creationTime = replaceOptions?.allowExplicitId && typeof document["_creationTime"] === "number" ? document["_creationTime"] : clock();
       const replaced = { ...document, _creationTime: creationTime, _id: id };
       applyOnUpdate(tableDefinition, document, replaced, auth);
       runRowValidators(tableDefinition, replaced);
@@ -1727,6 +2012,7 @@ const createShardCtxDb = (options) => {
         sql`UPDATE ${sql.identifier(tableName)} SET _creationTime = ${creationTime}, ${sql.identifier(DOC_COLUMN$1)} = ${JSON.stringify(replaced)} WHERE id = ${id} AND ${sql.identifier(DOC_COLUMN$1)} = ${existingJson}`
       );
       syncSearch(tableName, id, replaced);
+      syncGeo(tableName, id, replaced);
       syncAggregates(tableName, previous, replaced);
       syncRanks(tableName, id, previous, replaced);
       cache?.invalidate(tableName, id);