@lunora/do 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/packem_shared/{assertValidClientId-CBZ1zC96.mjs → NotUniqueError-BigrdT_W.mjs}

@@ -1,27 +1,30 @@
+import { LunoraError } from '@lunora/errors';
 import { sql } from 'drizzle-orm';
-import { matchesStaticWhere, aggregateSqlFunction, normalizeCountArgument, throwingScheduler } from './matchesStaticWhere-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 './applyCdcChanges-Ctdmxmrv.mjs';
-export { CDC_LOG_TABLE, CDC_META_TABLE, applyCdcChanges, bumpCdcEpoch, migrateCdcLog, migrateCdcMeta, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './applyCdcChanges-Ctdmxmrv.mjs';
+import { mergeWhere, CountRlsUnsupportedError, selectIndexForGroupBy, selectIndexForCount, selectIndexForAggregate } from './CountRlsUnsupportedError-BGxj0pgS.mjs';
+import { appendCdcChange } from './CDC_LOG_TABLE-DjJEHiM2.mjs';
+export { CDC_LOG_TABLE, applyCdcChanges, bumpCdcEpoch, minCdcSeq, readCdcChanges, readCdcCursor, readCdcEpoch, trimCdcChanges } from './CDC_LOG_TABLE-DjJEHiM2.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 { 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 { stringifySearchText, ftsTableName, tokenizeSearch, buildFtsMatch, scoreDocument } from './ftsTableName-BLEMawrp.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 './assertFlatPredicate-DyVYReuT.mjs';
-import { runRowValidators, resolveWith, applyOnDelete } from './applyOnDelete-CMif2RKw.mjs';
-import { guardWriter } from './guardWriter-u3UlnCH5.mjs';
-import { createSystemReader } from './createSystemReader-8CzSZP9V.mjs';
-import { ConflictError } from './ConflictError-C0STs6bU.mjs';
-import { runTriggers } from './runTriggers-5N6_Fx0A.mjs';
-import { compileWhereSql } from './compileWhereSql-CXrhFA3G.mjs';
-export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-BF5eL7kW.mjs';
-export { I as IDEMPOTENCY_TABLE, m as migrateIdempotency, r as readIdempotent, t as trimIdempotent, w as writeIdempotent } from './ctx-db-idempotency-DkC9rP91.mjs';
-export { runShardMigrations } from './runShardMigrations-C3bn5r93.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-DE6yfRcQ.mjs';
+export { backfillAggregateIndexes, backfillRankIndexes } from './backfillAggregateIndexes-DDoT-UUI.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-BGx4v2B6.mjs';
+export { a as selectShapeMemberIds, s as selectShapeRows } from './ctx-db-shapes-Cz9dHyh1.mjs';
 
 const rankIndexFieldsUnchanged = (index, previous, next) => {
   const fields = [...index.partitionBy ?? [], ...index.sortBy.map((key) => key.field), ...index.where ? Object.keys(index.where) : []];
@@ -420,11 +423,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 +475,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 +483,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 +519,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 +540,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 +550,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 +567,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 +576,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 `)}`;
@@ -660,11 +672,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 +710,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 +729,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 +743,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;
     }
@@ -766,6 +778,9 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
     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 `)}`;
@@ -811,9 +826,9 @@ 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);
+      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) {
@@ -830,7 +845,7 @@ const buildReader = (sql$1, schema, tableName, onIndexUse = () => void 0) => {
     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 +858,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 +872,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 +914,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 +997,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 +1012,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 +1035,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)) {
@@ -1115,7 +1160,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 +1172,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 +1214,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 +1246,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 +1269,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,6 +1283,25 @@ 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);
+        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,
@@ -1253,6 +1325,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 +1362,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 +1375,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 +1413,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 +1422,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 +1439,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 +1477,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 +1528,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 +1561,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 +1574,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 +1610,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 +1633,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 +1659,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);
@@ -1592,6 +1697,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 +1741,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 +1786,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 +1827,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);
@@ -1742,4 +1893,4 @@ const createShardCtxDb = (options) => {
   return options.enforceRls === true ? guardWriter(writer, schema, (id, expectedTable) => locateRowById(id, expectedTable)?.tableName) : writer;
 };
 
-export { NotUniqueError, appendCdcChange, assertValidClientId, createShardCtxDb, normalizeIdStructurally };
+export { NotUniqueError, assertValidClientId, createShardCtxDb, normalizeIdStructurally };