@lunora/sql-store 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/packem_shared/{createSqlCtxDb-WI84CQ7K.mjs → createSqlCtxDb-BPEyi1Yl.mjs}

@@ -1,6 +1,17 @@
-import { aggregateTableName, rankTableName, ftsTableName, hasTrigger, runRowValidators, assertFlatPredicate, mergeWhere, sortColumnName, resolveRankPartition, encodePartitionKey, decodeCursor, RANK_TIEBREAK, CountRlsUnsupportedError, normalizeIdStructurally, assertValidClientId, aggregateSqlFunction, compileWhereSql, normalizeOrderKeys, buildSeekWhere, resolveRelationPredicates, resolveWith, encodeCursor, NotFoundError, applyOnDelete, ConflictError, normalizeCountArgument, selectIndexForCount, encodeAggregateKey, selectIndexForAggregate, readAggregateValue, renderSql, runTriggers, matchesRankStaticWhere, stringifySearchText, selectIndexForGroupBy, matchesStaticWhere, coerceAggregateNumber, foldAggregateTally, NotUniqueError, throwingScheduler, tokenizeSearch, buildFtsMatch, scoreDocument } from '@lunora/do';
+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 { LunoraError } from '@lunora/errors';
 import { sql } from 'drizzle-orm';
-import { sqliteDecode, effectiveColumnKind, sqliteEncode } from './decodeBigint-Dedu92k4.mjs';
+import { sqliteDecode, sqliteEncode, effectiveColumnKind } from './decodeBigint-Dedu92k4.mjs';
+
+const evictOldestEntry = (map, capacity) => {
+  if (map.size < capacity) {
+    return;
+  }
+  const oldest = map.keys().next().value;
+  if (oldest !== void 0) {
+    map.delete(oldest);
+  }
+};
 
 const physicalColumn = (field) => field === "_id" || field === "id" ? "id" : field;
 const columnRefSql = (field) => sql`${sql.identifier(physicalColumn(field))}`;
@@ -79,14 +90,23 @@ const tableColumns = (definition) => {
   }
   return columns;
 };
+const columnKindCache = /* @__PURE__ */ new WeakMap();
+const columnKinds = (definition) => {
+  let kinds = columnKindCache.get(definition);
+  if (kinds === void 0) {
+    kinds = Object.entries(definition.shape).map(([field, validator]) => [field, effectiveColumnKind(validator)]);
+    columnKindCache.set(definition, kinds);
+  }
+  return kinds;
+};
 const decodeGlobalRow = (definition, row) => {
   const decoded = {};
-  for (const [field, validator] of Object.entries(definition.shape)) {
+  for (const [field, kind] of columnKinds(definition)) {
     const raw = row[field];
     if (raw === void 0) {
       continue;
     }
-    decoded[field] = sqliteDecode(raw, effectiveColumnKind(validator));
+    decoded[field] = sqliteDecode(raw, kind);
   }
   decoded["_id"] = row["id"];
   decoded["_creationTime"] = row["_creationTime"];
@@ -148,11 +168,8 @@ const createTableNameCache = () => {
     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);
-        }
+      } else {
+        evictOldestEntry(map, TABLE_NAME_CACHE_CAPACITY);
       }
       map.set(id, table);
     }
@@ -212,6 +229,9 @@ const searchViaFts = async (exec, dialect, definition, tableName, search, limit)
   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))))}`;
@@ -225,6 +245,9 @@ const searchViaScan = async (exec, dialect, definition, tableName, search, limit
     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 `)}`;
@@ -245,14 +268,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;
@@ -263,6 +289,10 @@ const createSearchBuilder = (search, tableName) => {
   };
   return builder;
 };
+const rankIndexFieldsUnchanged = (index, previous, next) => {
+  const fields = [...index.partitionBy ?? [], ...index.sortBy.map((key) => key.field), ...index.where ? Object.keys(index.where) : []];
+  return fields.every((field) => previous[field] === next[field]);
+};
 const andBranch = (conditions) => conditions.length === 1 ? conditions[0] : sql`(${sql.join(conditions, sql` AND `)})`;
 const buildRankBeforeBranches = (engine, index, sortColumns, own, rowId) => {
   const branches = [];
@@ -300,7 +330,7 @@ const buildRankCursorSeek = (engine, columns, decoded) => {
 };
 const rankPageColumns = (index, sortColumns) => {
   if (index.sortBy.length === 0) {
-    throw new Error(`rankIndex "${index.name}" requires at least one "sortBy" column for stable pagination`);
+    throw new LunoraError("INTERNAL", `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()) {
@@ -562,7 +592,12 @@ const createSqlCtxDb = (options) => {
     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}, '%')` } : {}
+    // The term is wildcard-escaped by compileContains, so pair it with a backslash `ESCAPE` for literal
+    // matching. MySQL treats backslash as a string-literal escape, so the SQL text must contain a DOUBLED
+    // backslash (`ESCAPE '\\'`) to denote one literal backslash; drizzle's `sql` tag uses the COOKED
+    // template string, so `'\\\\'` here renders `'\\'` in the SQL (a single `'\'` would escape the closing
+    // quote and raise a syntax error). SQLite/Postgres take backslash literally and use the portable default.
+    ...dialect.name === "mysql" ? { likeContains: (reference, term) => sql`${reference} LIKE CONCAT('%', ${term}, '%') ESCAPE '\\\\'` } : {}
   };
   const nullSafeEquals = (reference, value) => nullSafeEqualsSql(dialect.name, reference, value);
   const upsertSql = (config) => {
@@ -914,11 +949,18 @@ const createSqlCtxDb = (options) => {
     }
   };
   const syncRanks = async (tableName, id, previous, next) => {
-    const indexes = schema.tables[tableName]?.rankIndexes;
+    const definition = schema.tables[tableName];
+    const indexes = definition?.rankIndexes;
     if (!indexes || indexes.length === 0) {
       return;
     }
+    const softField = definition?.softDeleteMode?.field;
+    const nextFieldValue = softField === void 0 || next === void 0 ? void 0 : next[softField];
+    const nextSoftDeleted = nextFieldValue !== null && nextFieldValue !== void 0;
     for (const index of indexes) {
+      if (previous !== void 0 && next !== void 0 && rankIndexFieldsUnchanged(index, previous, next)) {
+        continue;
+      }
       const cacheKey = `${tableName}::rank::${index.name}`;
       const cached = rankBackfilled.get(cacheKey);
       const exists = cached ?? await rankTableExists(tableName, index.name);
@@ -929,7 +971,7 @@ const createSqlCtxDb = (options) => {
       if (previous) {
         await queryRun(exec, dialect, sql`DELETE FROM ${sql.identifier(rankTable)} WHERE ${sql.identifier("__id__")} = ${id}`);
       }
-      if (next) {
+      if (next && !nextSoftDeleted) {
         if (index.where && !matchesRankStaticWhere(next, index.where)) {
           continue;
         }
@@ -1067,6 +1109,9 @@ const createSqlCtxDb = (options) => {
       const row = rowsIndexed2[0];
       return [{ key: { ...planned.partial }, value: readAggregateValue(agg.op, { count: row.count, value: aggregateScalar(row.value) }) }];
     }
+    if (partialKeys.length > 0) {
+      return void 0;
+    }
     const rowsIndexed = await queryAll(
       exec,
       dialect,
@@ -1085,7 +1130,8 @@ const createSqlCtxDb = (options) => {
     return kind === "shardBy" || kind === "root";
   };
   const crossBackendUnsupported = (childTable) => {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `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`
     );
   };
@@ -1107,7 +1153,7 @@ const createSqlCtxDb = (options) => {
     async aggregate(tableName, aggOptions) {
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       await ensureMigrated();
       aggregateSqlFunction(aggOptions.op);
@@ -1120,12 +1166,13 @@ const createSqlCtxDb = (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`);
       }
-      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) {
           const counterReady = await ensureBackfilled(tableName, planned.index);
@@ -1152,17 +1199,18 @@ const createSqlCtxDb = (options) => {
     async count(tableName, whereOrOptions) {
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       await ensureMigrated();
       const countOptions = normalizeCountArgument(whereOrOptions);
       if (countOptions.restrictsCounts) {
         throw new CountRlsUnsupportedError(tableName);
       }
-      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) {
           const counterReady = await ensureBackfilled(tableName, planned.index);
@@ -1183,7 +1231,7 @@ const createSqlCtxDb = (options) => {
       const rows = await queryAll(exec, dialect, whereCondition ? sql`${query} WHERE ${whereCondition}` : query);
       return Number(rows[0]?.["count"] ?? 0);
     },
-    async delete(id, expectedTable) {
+    async delete(id, expectedTable, deleteOptions) {
       const tableName = await resolveTableName(id, expectedTable);
       if (!tableName) {
         return;
@@ -1194,6 +1242,11 @@ const createSqlCtxDb = (options) => {
       }
       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 });
       }
@@ -1202,14 +1255,15 @@ const createSqlCtxDb = (options) => {
         deletedReference: (references) => existing?.[references],
         findHolders: async (holderTable, field, value) => {
           if (schema.tables[holderTable]?.shardMode?.kind === "shardBy") {
-            throw new Error(
+            throw new LunoraError(
+              "INTERNAL",
               `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, { where: { [field]: value } });
+          const holders = await writer.findMany(holderTable, { includeDeleted: hard, where: { [field]: value } });
           return holders.page;
         },
-        onCascade: (_holderTable, holderId) => writer.delete(holderId),
+        onCascade: (_holderTable, holderId) => writer.delete(holderId, void 0, deleteOptions),
         onRestrict: (message) => {
           throw new ConflictError(message, "restrict");
         },
@@ -1220,6 +1274,23 @@ const createSqlCtxDb = (options) => {
       });
       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);
@@ -1244,19 +1315,43 @@ const createSqlCtxDb = (options) => {
     async findMany(tableName, args = {}) {
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `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 relationCounter = (childTable, where) => {
-        if (!isShardLocalTarget(childTable)) {
-          return writer.count(childTable, where);
+      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 LunoraError("INTERNAL", `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}`;
         }
-        return crossShardCounter ? crossShardCounter(childTable, where) : crossBackendUnsupported(childTable);
+        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,
@@ -1282,21 +1377,30 @@ const createSqlCtxDb = (options) => {
       const documents = decodeRows(definition, rows);
       if (limit === void 0) {
         if (args.with) {
-          await resolveWith({ counter: relationCounter, fetcher: relationFetcher, parents: documents, schema, tableName, with: args.with });
+          await resolveWith({
+            fetcher: relationFetcher,
+            groupedCounter: relationGroupedCounter,
+            parents: documents,
+            schema,
+            tableName,
+            with: args.with
+          });
         }
-        return { continueCursor: null, isDone: true, page: documents };
+        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({ counter: relationCounter, fetcher: relationFetcher, parents: page, schema, tableName, with: 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
+        page: applySelect(page, args.select, args.with)
       };
     },
     async get(id, expectedTable) {
@@ -1314,18 +1418,19 @@ const createSqlCtxDb = (options) => {
     async groupBy(tableName, groupOptions) {
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `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`);
+        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 indexed = await tryIndexedGroupBy(tableName, definition.aggregateIndexes, agg, groupOptions);
         if (indexed !== void 0) {
           return indexed;
@@ -1337,7 +1442,7 @@ const createSqlCtxDb = (options) => {
         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`);
+          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))}(${columnRefSql(agg.field)}) AS value`);
       }
@@ -1367,7 +1472,7 @@ const createSqlCtxDb = (options) => {
     async insert(tableName, document, insertOptions) {
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `unknown table: ${tableName}`);
       }
       await ensureMigrated();
       const withDefaults = applyInsertDefaults(definition, document, auth);
@@ -1383,7 +1488,7 @@ const createSqlCtxDb = (options) => {
         id = generateId();
         usedExplicitId = false;
       }
-      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 });
@@ -1418,16 +1523,16 @@ const createSqlCtxDb = (options) => {
     async patch(id, patch, expectedTable) {
       const tableName = await resolveTableName(id, expectedTable);
       if (!tableName) {
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const snapshot = await rawRow(tableName, id);
       const existing = decodeRow(definition, snapshot);
       if (!existing) {
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const merged = { ...existing, ...patch, _id: id };
       applyOnUpdate(definition, patch, merged, auth);
@@ -1452,10 +1557,30 @@ const createSqlCtxDb = (options) => {
         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 LunoraError("INTERNAL", `document not found: ${id}`);
+      }
+      const definition = schema.tables[tableName];
+      const field = definition?.softDeleteMode?.field;
+      if (!definition || !field) {
+        throw new LunoraError("INTERNAL", `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, [field]: null });
+        }
+      }
+    },
     query(tableName) {
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`unknown table: ${tableName}`);
+        throw new LunoraError("INTERNAL", `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) => {
@@ -1466,16 +1591,16 @@ const createSqlCtxDb = (options) => {
         const reader = {
           async collect() {
             if (!stage) {
-              throw new Error(LEGACY_READER_ERROR);
+              throw new LunoraError("INTERNAL", LEGACY_READER_ERROR);
             }
             return runSearch(stage, void 0);
           },
           filter() {
-            throw new Error(LEGACY_READER_ERROR);
+            throw new LunoraError("INTERNAL", LEGACY_READER_ERROR);
           },
           async first() {
             if (!stage) {
-              throw new Error(LEGACY_READER_ERROR);
+              throw new LunoraError("INTERNAL", LEGACY_READER_ERROR);
             }
             const rows = await runSearch(stage, 1);
             return rows[0] ?? null;
@@ -1486,19 +1611,19 @@ const createSqlCtxDb = (options) => {
           // 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 LunoraError("INTERNAL", "pagination is not supported on search queries; use .take(n) or .collect()");
             }
-            throw new Error(LEGACY_READER_ERROR);
+            throw new LunoraError("INTERNAL", LEGACY_READER_ERROR);
           },
           async take(limit) {
             if (!stage) {
-              throw new Error(LEGACY_READER_ERROR);
+              throw new LunoraError("INTERNAL", LEGACY_READER_ERROR);
             }
             return runSearch(stage, limit);
           },
           async unique() {
             if (!stage) {
-              throw new Error(LEGACY_READER_ERROR);
+              throw new LunoraError("INTERNAL", LEGACY_READER_ERROR);
             }
             const rows = await runSearch(stage, 2);
             if (rows.length > 1) {
@@ -1506,13 +1631,19 @@ const createSqlCtxDb = (options) => {
             }
             return rows[0] ?? null;
           },
+          withGeoIndex() {
+            throw new LunoraError(
+              "INTERNAL",
+              `geo indexes are not supported on \`.global()\` tables (table "${tableName}") — geospatial queries run only on sharded tables`
+            );
+          },
           withIndex() {
-            throw new Error(LEGACY_READER_ERROR);
+            throw new LunoraError("INTERNAL", 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}"`);
+              throw new LunoraError("INTERNAL", `unknown search index "${indexName}" on table "${tableName}"`);
             }
             const searchStage = {
               definition: searchDefinition,
@@ -1524,7 +1655,7 @@ const createSqlCtxDb = (options) => {
             };
             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 buildReader(searchStage);
           }
@@ -1536,11 +1667,11 @@ const createSqlCtxDb = (options) => {
     async rank(tableName, indexName, rankOptions) {
       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 (rankOptions.restrictsCounts) {
         throw new CountRlsUnsupportedError(tableName);
@@ -1593,11 +1724,11 @@ const createSqlCtxDb = (options) => {
       assertFlatPredicate(mergeWhere(rankPageOptions.baseWhere, rankPageOptions.where), schema, tableName, "rankPage");
       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}"`);
       }
       await ensureMigrated();
       const counterReady = await ensureRankBackfilled(tableName, index);
@@ -1650,22 +1781,22 @@ const createSqlCtxDb = (options) => {
       }
       return { continueCursor, isDone: !hasMore, page: documents };
     },
-    async replace(id, document, expectedTable) {
+    async replace(id, document, expectedTable, replaceOptions) {
       const tableName = await resolveTableName(id, expectedTable);
       if (!tableName) {
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const definition = schema.tables[tableName];
       if (!definition) {
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `document not found: ${id}`);
       }
       const snapshot = await rawRow(tableName, id);
       if (snapshot === void 0) {
-        throw new Error(`document not found: ${id}`);
+        throw new LunoraError("INTERNAL", `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 creationTime = replaceOptions?.allowExplicitId && typeof document["_creationTime"] === "number" ? document["_creationTime"] : clock();
       const replaced = { ...document, _creationTime: creationTime, _id: id };
       applyOnUpdate(definition, document, replaced, auth);
       runRowValidators(definition, replaced);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/sql-store",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.41",
   "description": "Internal dialect-parameterized SQL store core for Lunora .global() backends (D1, PlanetScale)",
   "keywords": [
     "cloudflare",
@@ -25,7 +25,7 @@
     "directory": "packages/sql-store"
   },
   "files": [
-    "dist",
+    "./dist",
     "README.md",
     "LICENSE.md",
     "__assets__"
@@ -50,7 +50,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/do": "1.0.0-alpha.4",
+    "@lunora/do": "1.0.0-alpha.44",
+    "@lunora/errors": "1.0.0-alpha.8",
     "drizzle-orm": "^0.45.2"
   },
   "engines": {