@atscript/db 0.1.128 → 0.1.130

package/dist/agg.cjs

@@ -4,5 +4,36 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 function resolveAlias(expr) {
 	return expr.$as ?? `${expr.$fn}_${expr.$field}`;
 }
+/**
+* Reads the `$search` / `$index` controls of an aggregate query.
+*
+* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+* shapes what is left. Every adapter must therefore apply the search predicate
+* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+* describe rows that matched. An adapter that silently ignored the term would
+* report totals for rows the same search excludes from the leaf list.
+*
+* Two rules the leaf search path applies and the grouped path must NOT:
+* - **No implicit relevance ordering.** Relevance is a property of a row, not
+*   of a group; after `$group` there is no per-row score left to sort on.
+*   Grouped results order by `$sort` or not at all.
+* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+*   rows; applying that before `$group` would silently truncate group counts.
+*
+* Returns `undefined` when there is nothing to search for, so callers fall
+* straight through to the plain grouped path.
+*/
+function resolveAggregateSearch(controls) {
+	const raw = controls?.$search;
+	if (typeof raw !== "string") return;
+	const text = raw.trim();
+	if (!text) return;
+	const index = controls?.$index;
+	return {
+		text,
+		indexName: typeof index === "string" && index ? index : void 0
+	};
+}
 //#endregion
+exports.resolveAggregateSearch = resolveAggregateSearch;
 exports.resolveAlias = resolveAlias;

package/dist/agg.d.cts

@@ -3,5 +3,34 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
 //#region src/agg.d.ts
 /** Resolves output alias: $as if provided, otherwise `{fn}_{field}`. */
 declare function resolveAlias(expr: AggregateExpr$1): string;
+/** The text-search request a grouped query carries, once normalised. */
+interface TAggregateSearch {
+  /** Non-empty, trimmed search term. */
+  text: string;
+  /** Named search index to target, when the caller picked one. */
+  indexName?: string;
+}
+/**
+ * Reads the `$search` / `$index` controls of an aggregate query.
+ *
+ * Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+ * shapes what is left. Every adapter must therefore apply the search predicate
+ * BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+ * describe rows that matched. An adapter that silently ignored the term would
+ * report totals for rows the same search excludes from the leaf list.
+ *
+ * Two rules the leaf search path applies and the grouped path must NOT:
+ * - **No implicit relevance ordering.** Relevance is a property of a row, not
+ *   of a group; after `$group` there is no per-row score left to sort on.
+ *   Grouped results order by `$sort` or not at all.
+ * - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+ *   rows; applying that before `$group` would silently truncate group counts.
+ *
+ * Returns `undefined` when there is nothing to search for, so callers fall
+ * straight through to the plain grouped path.
+ */
+declare function resolveAggregateSearch(controls: {
+  [key: `$${string}`]: unknown;
+} | undefined): TAggregateSearch | undefined;
 //#endregion
-export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAlias };
+export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAggregateSearch, resolveAlias };

package/dist/agg.d.mts

@@ -3,5 +3,34 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
 //#region src/agg.d.ts
 /** Resolves output alias: $as if provided, otherwise `{fn}_{field}`. */
 declare function resolveAlias(expr: AggregateExpr$1): string;
+/** The text-search request a grouped query carries, once normalised. */
+interface TAggregateSearch {
+  /** Non-empty, trimmed search term. */
+  text: string;
+  /** Named search index to target, when the caller picked one. */
+  indexName?: string;
+}
+/**
+ * Reads the `$search` / `$index` controls of an aggregate query.
+ *
+ * Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+ * shapes what is left. Every adapter must therefore apply the search predicate
+ * BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+ * describe rows that matched. An adapter that silently ignored the term would
+ * report totals for rows the same search excludes from the leaf list.
+ *
+ * Two rules the leaf search path applies and the grouped path must NOT:
+ * - **No implicit relevance ordering.** Relevance is a property of a row, not
+ *   of a group; after `$group` there is no per-row score left to sort on.
+ *   Grouped results order by `$sort` or not at all.
+ * - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+ *   rows; applying that before `$group` would silently truncate group counts.
+ *
+ * Returns `undefined` when there is nothing to search for, so callers fall
+ * straight through to the plain grouped path.
+ */
+declare function resolveAggregateSearch(controls: {
+  [key: `$${string}`]: unknown;
+} | undefined): TAggregateSearch | undefined;
 //#endregion
-export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAlias };
+export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, resolveAggregateSearch, resolveAlias };

package/dist/agg.mjs

@@ -3,5 +3,35 @@
 function resolveAlias(expr) {
 	return expr.$as ?? `${expr.$fn}_${expr.$field}`;
 }
+/**
+* Reads the `$search` / `$index` controls of an aggregate query.
+*
+* Search and grouping are orthogonal: `$search` narrows the ROWS, `$groupBy`
+* shapes what is left. Every adapter must therefore apply the search predicate
+* BEFORE grouping, so the groups — and `$count`, which counts them — only ever
+* describe rows that matched. An adapter that silently ignored the term would
+* report totals for rows the same search excludes from the leaf list.
+*
+* Two rules the leaf search path applies and the grouped path must NOT:
+* - **No implicit relevance ordering.** Relevance is a property of a row, not
+*   of a group; after `$group` there is no per-row score left to sort on.
+*   Grouped results order by `$sort` or not at all.
+* - **No implicit row cap.** The leaf runners cap an unbounded search at 1000
+*   rows; applying that before `$group` would silently truncate group counts.
+*
+* Returns `undefined` when there is nothing to search for, so callers fall
+* straight through to the plain grouped path.
+*/
+function resolveAggregateSearch(controls) {
+	const raw = controls?.$search;
+	if (typeof raw !== "string") return;
+	const text = raw.trim();
+	if (!text) return;
+	const index = controls?.$index;
+	return {
+		text,
+		indexName: typeof index === "string" && index ? index : void 0
+	};
+}
 //#endregion
-export { resolveAlias };
+export { resolveAggregateSearch, resolveAlias };

package/dist/{db-error-DXwEzmYJ.cjs → db-error-C4JuLcvb.cjs}

@@ -50,6 +50,27 @@ var CasExhaustedError = class extends DbError {
 		this.lastSeenVersion = lastSeenVersion;
 	}
 };
+/**
+* Thrown by `AtscriptDbTable.touchMany` (`require: 'all'`, the default) when
+* fewer rows than keys matched their expected version — at least one row is
+* stale or missing. Nothing was written (the pre-count refused before the
+* first statement, or the SQL transaction rolled every bump back). Surfaced
+* as HTTP 409 by moost-db.
+*/
+var CasMismatchError = class extends DbError {
+	matched;
+	expected;
+	name = "CasMismatchError";
+	constructor(matched, expected) {
+		const message = `touchMany: ${matched} of ${expected} rows matched — stale or missing rows`;
+		super("CAS_MISMATCH", [{
+			path: "$cas",
+			message
+		}], message);
+		this.matched = matched;
+		this.expected = expected;
+	}
+};
 //#endregion
 Object.defineProperty(exports, "CasExhaustedError", {
 	enumerable: true,
@@ -57,6 +78,12 @@ Object.defineProperty(exports, "CasExhaustedError", {
 		return CasExhaustedError;
 	}
 });
+Object.defineProperty(exports, "CasMismatchError", {
+	enumerable: true,
+	get: function() {
+		return CasMismatchError;
+	}
+});
 Object.defineProperty(exports, "DbError", {
 	enumerable: true,
 	get: function() {

package/dist/{db-error-BHPXOKzc.mjs → db-error-COrO58t5.mjs}

@@ -50,5 +50,26 @@ var CasExhaustedError = class extends DbError {
 		this.lastSeenVersion = lastSeenVersion;
 	}
 };
+/**
+* Thrown by `AtscriptDbTable.touchMany` (`require: 'all'`, the default) when
+* fewer rows than keys matched their expected version — at least one row is
+* stale or missing. Nothing was written (the pre-count refused before the
+* first statement, or the SQL transaction rolled every bump back). Surfaced
+* as HTTP 409 by moost-db.
+*/
+var CasMismatchError = class extends DbError {
+	matched;
+	expected;
+	name = "CasMismatchError";
+	constructor(matched, expected) {
+		const message = `touchMany: ${matched} of ${expected} rows matched — stale or missing rows`;
+		super("CAS_MISMATCH", [{
+			path: "$cas",
+			message
+		}], message);
+		this.matched = matched;
+		this.expected = expected;
+	}
+};
 //#endregion
-export { DbError as n, DepthLimitExceededError as r, CasExhaustedError as t };
+export { DepthLimitExceededError as i, CasMismatchError as n, DbError as r, CasExhaustedError as t };

package/dist/{db-readable-CkbZn_z-.d.cts → db-readable-B7eYWS5q.d.cts}

@@ -828,6 +828,15 @@ interface TDbRemoveGuardContext<Row = Record<string, unknown>> {
 type TDbWriteGuard<Row = Record<string, unknown>> = (ctx: TDbWriteGuardContext<Row>) => void | Promise<void>;
 /** A validated-stage delete guard — see {@link TDeleteOptions.guard}. */
 type TDbRemoveGuard<Row = Record<string, unknown>> = (ctx: TDbRemoveGuardContext<Row>) => void | Promise<void>;
+/** Options of `AtscriptDbTable.touchMany` (since 0.1.129). */
+interface TTouchManyOptions {
+  /**
+   * `'all'` (default): every key must match its stored version — a stale or
+   * missing row throws `DbError("CAS_MISMATCH")` and no version moves.
+   * `'any'`: bump whatever matches and report the honest counts.
+   */
+  require?: "all" | "any";
+}
 /** Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`. */
 interface TWriteOptions<Row = Record<string, unknown>> {
   /** Nested-relation write recursion limit (default 3). */
@@ -2006,4 +2015,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TDbWriteAction as $, TCrudPermissions as A, isGeoIndexableType as At, TDbForeignKey as B, NullableOptional as C, TWriteTableResolver as Ct, TCascadeTarget as D, WithRelation$1 as Dt, TCascadeResolver as E, UniqueryControls$1 as Et, TDbCollation as F, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, NoopLogger as Mt, TDbActionLevel as N, TGenericLogger as Nt, TColumnDiff as O, TableMetadata as Ot, TDbActionProcessor as P, UniquSelect as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TWriteOptions as St, PrimaryKeyOf$1 as T, Uniquery$1 as Tt, TDbIndexType as U, TDbIndex as V, TDbInsertManyResult as W, TDbRemoveGuardContext as X, TDbRemoveGuard as Y, TDbStorageType as Z, DbQuery as _, TSearchIndexInfo as _t, TDbEncryptionOptions as a, TExistingForeignKey as at, FilterExpr$1 as b, TTableResolver as bt, BaseDbAdapter as c, TFkLookupResolver as ct, AggregateFn as d, TIdentification as dt, TDbWriteGuard as et, AggregateQuery$1 as f, TMetaResponse as ft, DbPatch as g, TRelationInfo as gt, DbControls as h, TReferencingForeignKey as ht, DbEncryption as i, TExistingColumn as it, TDbActionInfo as j, isGeoPointType as jt, TCrudOp as k, findAncestorInSet as kt, AggregateControls as l, TFkLookupTarget as lt, AtscriptDbWritable as m, TPrimaryKeyChange as mt, DbResponse as n, TDeleteOptions as nt, DocumentFieldMapper as o, TExistingTableOption as ot, AggregateResult as p, TMetadataOverrides as pt, TDbReferentialAction as q, resolveDesignType as r, TEnsureTableOptions as rt, FieldMappingStrategy as s, TFieldMeta as st, AtscriptDbReadable as t, TDbWriteGuardContext as tt, AggregateExpr$1 as u, TIdDescriptor as ut, DbRow as v, TSyncColumnResult as vt, OwnPropsOf$1 as w, TypedWithRelation as wt, FlatOf$1 as x, TValueFormatterPair as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };
+export { TDbWriteAction as $, TCrudPermissions as A, findAncestorInSet as At, TDbForeignKey as B, NullableOptional as C, TWriteOptions as Ct, TCascadeTarget as D, UniqueryControls$1 as Dt, TCascadeResolver as E, Uniquery$1 as Et, TDbCollation as F, UniquSelect as Ft, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, isGeoPointType as Mt, TDbActionLevel as N, NoopLogger as Nt, TColumnDiff as O, WithRelation$1 as Ot, TDbActionProcessor as P, TGenericLogger as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TValueFormatterPair as St, PrimaryKeyOf$1 as T, TypedWithRelation as Tt, TDbIndexType as U, TDbIndex as V, TDbInsertManyResult as W, TDbRemoveGuardContext as X, TDbRemoveGuard as Y, TDbStorageType as Z, DbQuery as _, TSearchIndexInfo as _t, TDbEncryptionOptions as a, TExistingForeignKey as at, FilterExpr$1 as b, TTableResolver as bt, BaseDbAdapter as c, TFkLookupResolver as ct, AggregateFn as d, TIdentification as dt, TDbWriteGuard as et, AggregateQuery$1 as f, TMetaResponse as ft, DbPatch as g, TRelationInfo as gt, DbControls as h, TReferencingForeignKey as ht, DbEncryption as i, TExistingColumn as it, TDbActionInfo as j, isGeoIndexableType as jt, TCrudOp as k, TableMetadata as kt, AggregateControls as l, TFkLookupTarget as lt, AtscriptDbWritable as m, TPrimaryKeyChange as mt, DbResponse as n, TDeleteOptions as nt, DocumentFieldMapper as o, TExistingTableOption as ot, AggregateResult as p, TMetadataOverrides as pt, TDbReferentialAction as q, resolveDesignType as r, TEnsureTableOptions as rt, FieldMappingStrategy as s, TFieldMeta as st, AtscriptDbReadable as t, TDbWriteGuardContext as tt, AggregateExpr$1 as u, TIdDescriptor as ut, DbRow as v, TSyncColumnResult as vt, OwnPropsOf$1 as w, TWriteTableResolver as wt, FlatOf$1 as x, TTouchManyOptions as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };

package/dist/{db-readable-BTl4NzNN.d.mts → db-readable-Bn1bV_eC.d.mts}

@@ -828,6 +828,15 @@ interface TDbRemoveGuardContext<Row = Record<string, unknown>> {
 type TDbWriteGuard<Row = Record<string, unknown>> = (ctx: TDbWriteGuardContext<Row>) => void | Promise<void>;
 /** A validated-stage delete guard — see {@link TDeleteOptions.guard}. */
 type TDbRemoveGuard<Row = Record<string, unknown>> = (ctx: TDbRemoveGuardContext<Row>) => void | Promise<void>;
+/** Options of `AtscriptDbTable.touchMany` (since 0.1.129). */
+interface TTouchManyOptions {
+  /**
+   * `'all'` (default): every key must match its stored version — a stale or
+   * missing row throws `DbError("CAS_MISMATCH")` and no version moves.
+   * `'any'`: bump whatever matches and report the honest counts.
+   */
+  require?: "all" | "any";
+}
 /** Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`. */
 interface TWriteOptions<Row = Record<string, unknown>> {
   /** Nested-relation write recursion limit (default 3). */
@@ -2006,4 +2015,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TDbWriteAction as $, TCrudPermissions as A, isGeoIndexableType as At, TDbForeignKey as B, NullableOptional as C, TWriteTableResolver as Ct, TCascadeTarget as D, WithRelation$1 as Dt, TCascadeResolver as E, UniqueryControls$1 as Et, TDbCollation as F, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, NoopLogger as Mt, TDbActionLevel as N, TGenericLogger as Nt, TColumnDiff as O, TableMetadata as Ot, TDbActionProcessor as P, UniquSelect as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TWriteOptions as St, PrimaryKeyOf$1 as T, Uniquery$1 as Tt, TDbIndexType as U, TDbIndex as V, TDbInsertManyResult as W, TDbRemoveGuardContext as X, TDbRemoveGuard as Y, TDbStorageType as Z, DbQuery as _, TSearchIndexInfo as _t, TDbEncryptionOptions as a, TExistingForeignKey as at, FilterExpr$1 as b, TTableResolver as bt, BaseDbAdapter as c, TFkLookupResolver as ct, AggregateFn as d, TIdentification as dt, TDbWriteGuard as et, AggregateQuery$1 as f, TMetaResponse as ft, DbPatch as g, TRelationInfo as gt, DbControls as h, TReferencingForeignKey as ht, DbEncryption as i, TExistingColumn as it, TDbActionInfo as j, isGeoPointType as jt, TCrudOp as k, findAncestorInSet as kt, AggregateControls as l, TFkLookupTarget as lt, AtscriptDbWritable as m, TPrimaryKeyChange as mt, DbResponse as n, TDeleteOptions as nt, DocumentFieldMapper as o, TExistingTableOption as ot, AggregateResult as p, TMetadataOverrides as pt, TDbReferentialAction as q, resolveDesignType as r, TEnsureTableOptions as rt, FieldMappingStrategy as s, TFieldMeta as st, AtscriptDbReadable as t, TDbWriteGuardContext as tt, AggregateExpr$1 as u, TIdDescriptor as ut, DbRow as v, TSyncColumnResult as vt, OwnPropsOf$1 as w, TypedWithRelation as wt, FlatOf$1 as x, TValueFormatterPair as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };
+export { TDbWriteAction as $, TCrudPermissions as A, findAncestorInSet as At, TDbForeignKey as B, NullableOptional as C, TWriteOptions as Ct, TCascadeTarget as D, UniqueryControls$1 as Dt, TCascadeResolver as E, Uniquery$1 as Et, TDbCollation as F, UniquSelect as Ft, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, isGeoPointType as Mt, TDbActionLevel as N, NoopLogger as Nt, TColumnDiff as O, WithRelation$1 as Ot, TDbActionProcessor as P, TGenericLogger as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TValueFormatterPair as St, PrimaryKeyOf$1 as T, TypedWithRelation as Tt, TDbIndexType as U, TDbIndex as V, TDbInsertManyResult as W, TDbRemoveGuardContext as X, TDbRemoveGuard as Y, TDbStorageType as Z, DbQuery as _, TSearchIndexInfo as _t, TDbEncryptionOptions as a, TExistingForeignKey as at, FilterExpr$1 as b, TTableResolver as bt, BaseDbAdapter as c, TFkLookupResolver as ct, AggregateFn as d, TIdentification as dt, TDbWriteGuard as et, AggregateQuery$1 as f, TMetaResponse as ft, DbPatch as g, TRelationInfo as gt, DbControls as h, TReferencingForeignKey as ht, DbEncryption as i, TExistingColumn as it, TDbActionInfo as j, isGeoIndexableType as jt, TCrudOp as k, TableMetadata as kt, AggregateControls as l, TFkLookupTarget as lt, AtscriptDbWritable as m, TPrimaryKeyChange as mt, DbResponse as n, TDeleteOptions as nt, DocumentFieldMapper as o, TExistingTableOption as ot, AggregateResult as p, TMetadataOverrides as pt, TDbReferentialAction as q, resolveDesignType as r, TEnsureTableOptions as rt, FieldMappingStrategy as s, TFieldMeta as st, AtscriptDbReadable as t, TDbWriteGuardContext as tt, AggregateExpr$1 as u, TIdDescriptor as ut, DbRow as v, TSyncColumnResult as vt, OwnPropsOf$1 as w, TWriteTableResolver as wt, FlatOf$1 as x, TTouchManyOptions as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };

package/dist/{db-space-BEB5Jl8M.d.mts → db-space-C2UCnGHd.d.cts}

@@ -1,6 +1,6 @@
-import { C as NullableOptional, Ct as TWriteTableResolver, E as TCascadeResolver, G as TDbInsertResult, Nt as TGenericLogger, Ot as TableMetadata, Q as TDbUpdateResult, R as TDbDeleteResult, St as TWriteOptions, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow } from "./db-readable-BTl4NzNN.mjs";
-import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { C as NullableOptional, Ct as TWriteOptions, E as TCascadeResolver, G as TDbInsertResult, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, kt as TableMetadata, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow, wt as TWriteTableResolver, xt as TTouchManyOptions } from "./db-readable-B7eYWS5q.cjs";
 import { FilterExpr } from "@uniqu/core";
+import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -103,6 +103,32 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * present, `$cas` removed) — see {@link TWriteOptions}.
    */
   bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
+  /**
+   * Batch versioned touch (since 0.1.129): bumps the version of every listed
+   * row by exactly one, each row guarded by its own expected version. This is
+   * the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
+   * empty patch is a no-op since then and takes no lock).
+   *
+   * Each key carries the primary key field(s) (composite supported) plus the
+   * version column and NOTHING else — a touch has no payload. Unique indexes
+   * do not identify a touch key. `undefined`-valued properties are ignored,
+   * like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
+   *
+   * `require: 'all'` (default): one count over the whole key set runs FIRST;
+   * a stale or missing row throws {@link CasMismatchError} before any write.
+   * The bumps then run as `updateMany(orFilter, {})` chunks of at most
+   * {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
+   * `matchedCount` short of `keys.length` (a row moved between the count and
+   * the bump) throws the same error — SQL engines roll every bump back. The
+   * pre-count is therefore a deliberate double check on SQL: it is what makes
+   * the guarantee hold on adapters whose `withTransaction` is a passthrough
+   * (the memory adapter, a Mongo standalone topology) — there it covers the
+   * common stale case and the residual race window is accepted.
+   * `require: 'any'`: no pre-count, the honest summed result is returned.
+   *
+   * No `guard`, no `onWrite`; not exposed over HTTP.
+   */
+  touchMany(keys: Array<DbPatch<DataType>>, opts?: TTouchManyOptions): Promise<TDbUpdateResult>;
   /**
    * Deletes a single record by any type-compatible identifier — primary key
    * or single-field unique index. Uses the same resolution logic as `findById`.

package/dist/{db-space-BevOyVrC.d.cts → db-space-DdIPYD0Q.d.mts}

@@ -1,6 +1,6 @@
-import { C as NullableOptional, Ct as TWriteTableResolver, E as TCascadeResolver, G as TDbInsertResult, Nt as TGenericLogger, Ot as TableMetadata, Q as TDbUpdateResult, R as TDbDeleteResult, St as TWriteOptions, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow } from "./db-readable-CkbZn_z-.cjs";
-import { FilterExpr } from "@uniqu/core";
+import { C as NullableOptional, Ct as TWriteOptions, E as TCascadeResolver, G as TDbInsertResult, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, kt as TableMetadata, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow, wt as TWriteTableResolver, xt as TTouchManyOptions } from "./db-readable-Bn1bV_eC.mjs";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { FilterExpr } from "@uniqu/core";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -103,6 +103,32 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * present, `$cas` removed) — see {@link TWriteOptions}.
    */
   bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
+  /**
+   * Batch versioned touch (since 0.1.129): bumps the version of every listed
+   * row by exactly one, each row guarded by its own expected version. This is
+   * the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
+   * empty patch is a no-op since then and takes no lock).
+   *
+   * Each key carries the primary key field(s) (composite supported) plus the
+   * version column and NOTHING else — a touch has no payload. Unique indexes
+   * do not identify a touch key. `undefined`-valued properties are ignored,
+   * like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
+   *
+   * `require: 'all'` (default): one count over the whole key set runs FIRST;
+   * a stale or missing row throws {@link CasMismatchError} before any write.
+   * The bumps then run as `updateMany(orFilter, {})` chunks of at most
+   * {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
+   * `matchedCount` short of `keys.length` (a row moved between the count and
+   * the bump) throws the same error — SQL engines roll every bump back. The
+   * pre-count is therefore a deliberate double check on SQL: it is what makes
+   * the guarantee hold on adapters whose `withTransaction` is a passthrough
+   * (the memory adapter, a Mongo standalone topology) — there it covers the
+   * common stale case and the residual race window is accepted.
+   * `require: 'any'`: no pre-count, the honest summed result is returned.
+   *
+   * No `guard`, no `onWrite`; not exposed over HTTP.
+   */
+  touchMany(keys: Array<DbPatch<DataType>>, opts?: TTouchManyOptions): Promise<TDbUpdateResult>;
   /**
    * Deletes a single record by any type-compatible identifier — primary key
    * or single-field unique index. Uses the same resolution logic as `findById`.

package/dist/{db-view-Ck0I-PMI.mjs → db-view-BkF2xEGd.mjs}

@@ -1,7 +1,7 @@
-import { n as DbError } from "./db-error-BHPXOKzc.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-eKYWf3xf.mjs";
+import { n as CasMismatchError, r as DbError } from "./db-error-COrO58t5.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-CeD_fqyW.mjs";
 import { resolveAlias } from "./agg.mjs";
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-DI-HeTky.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CkDo-ZfH.mjs";
 import { separateCas, separateFieldOps } from "./ops.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -1027,13 +1027,11 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 		return {
 			filter,
 			controls: {
+				...controls,
 				$groupBy: groupBy,
 				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
 				$sort: sort,
-				$having: having,
-				$skip: controls.$skip,
-				$limit: controls.$limit,
-				$count: controls.$count
+				$having: having
 			},
 			insights: query.insights
 		};
@@ -2047,6 +2045,11 @@ var AtscriptDbReadable = class {
 				}]);
 			}
 		}
+		const searchTerm = query.controls.$search;
+		if (typeof searchTerm === "string" && searchTerm) {
+			this._ensureSearchable();
+			if (!searchTerm.trim()) return query.controls.$count ? [{ count: 0 }] : [];
+		}
 		guardAggregate(this._meta, this.adapter, query);
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
@@ -2345,7 +2348,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await import("./relation-loader-BmeOMj0b.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-CUGcxJ18.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -3504,6 +3507,15 @@ function _translateOpsKeys(ops, meta) {
 		mul: ops.mul ? _translateOpsRecord(ops.mul, meta) : void 0
 	};
 }
+/** Upper bound of keys per `touchMany` UPDATE statement (parameter-count safety). */
+const TOUCH_MANY_CHUNK = 500;
+/** `touchMany` input rejection — always `INVALID_QUERY`, path names the key. */
+function invalidTouchKey(path, message) {
+	return new DbError("INVALID_QUERY", [{
+		path,
+		message
+	}]);
+}
 var AtscriptDbTable = class extends AtscriptDbReadable {
 	_cascadeResolver;
 	_fkLookupResolver;
@@ -3783,6 +3795,84 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		}));
 	}
 	/**
+	* Batch versioned touch (since 0.1.129): bumps the version of every listed
+	* row by exactly one, each row guarded by its own expected version. This is
+	* the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
+	* empty patch is a no-op since then and takes no lock).
+	*
+	* Each key carries the primary key field(s) (composite supported) plus the
+	* version column and NOTHING else — a touch has no payload. Unique indexes
+	* do not identify a touch key. `undefined`-valued properties are ignored,
+	* like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
+	*
+	* `require: 'all'` (default): one count over the whole key set runs FIRST;
+	* a stale or missing row throws {@link CasMismatchError} before any write.
+	* The bumps then run as `updateMany(orFilter, {})` chunks of at most
+	* {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
+	* `matchedCount` short of `keys.length` (a row moved between the count and
+	* the bump) throws the same error — SQL engines roll every bump back. The
+	* pre-count is therefore a deliberate double check on SQL: it is what makes
+	* the guarantee hold on adapters whose `withTransaction` is a passthrough
+	* (the memory adapter, a Mongo standalone topology) — there it covers the
+	* common stale case and the residual race window is accepted.
+	* `require: 'any'`: no pre-count, the honest summed result is returned.
+	*
+	* No `guard`, no `onWrite`; not exposed over HTTP.
+	*/
+	async touchMany(keys, opts) {
+		this._ensureBuilt();
+		const versionField = this._meta.versionField;
+		if (versionField === void 0) throw invalidTouchKey("", "touchMany requires @db.column.version");
+		if (keys.length === 0) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
+		const pkFields = this.primaryKeys;
+		const seen = /* @__PURE__ */ new Set();
+		const pairs = [];
+		for (const [i, key] of keys.entries()) {
+			const pair = {};
+			for (const pk of pkFields) {
+				if (key[pk] === void 0) throw invalidTouchKey(`[${i}].${pk}`, `touchMany: each key must carry its "${pk}"`);
+				pair[pk] = key[pk];
+			}
+			const version = key[versionField];
+			if (typeof version !== "number" || !Number.isFinite(version)) throw invalidTouchKey(`[${i}].${versionField}`, `touchMany: each key must carry its expected "${versionField}" (number)`);
+			for (const [prop, value] of Object.entries(key)) if (value !== void 0 && prop !== versionField && !(prop in pair)) throw invalidTouchKey(`[${i}].${prop}`, `touchMany: a touch carries no payload — keys hold the primary key and "${versionField}" only, got "${prop}"`);
+			const identity = JSON.stringify(pair);
+			if (seen.has(identity)) throw invalidTouchKey(`[${i}]`, `touchMany: duplicate key ${identity}`);
+			seen.add(identity);
+			pair[versionField] = version;
+			pairs.push(pair);
+		}
+		const orFilter = { $or: pairs };
+		this._guardMutationFilter(orFilter);
+		const translated = this._fieldMapper.translateFilter(orFilter, this._meta).$or;
+		const requireAll = (opts?.require ?? "all") === "all";
+		if (requireAll) {
+			const matched = await this.adapter.count({
+				filter: { $or: translated },
+				controls: {}
+			});
+			if (matched < keys.length) throw new CasMismatchError(matched, keys.length);
+		}
+		return this.adapter.withTransaction(async () => {
+			let matchedCount = 0;
+			let modifiedCount = 0;
+			for (let start = 0; start < translated.length; start += TOUCH_MANY_CHUNK) {
+				const chunk = translated.slice(start, start + TOUCH_MANY_CHUNK);
+				const result = await this.adapter.updateMany({ $or: chunk }, {}, void 0);
+				matchedCount += result.matchedCount;
+				modifiedCount += result.modifiedCount;
+			}
+			if (requireAll && matchedCount !== keys.length) throw new CasMismatchError(matchedCount, keys.length);
+			return {
+				matchedCount,
+				modifiedCount
+			};
+		});
+	}
+	/**
 	* Deletes a single record by any type-compatible identifier — primary key
 	* or single-field unique index. Uses the same resolution logic as `findById`.
 	*