@atscript/db-mongo 0.1.161 → 0.1.163

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_mongo_accumulator = require("./mongo-accumulator-BW-RNFg0.cjs");
+const require_search_messages = require("./search-messages-BqLxxrb8.cjs");
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
 let _atscript_db_agg = require("@atscript/db/agg");
@@ -79,6 +80,19 @@ function containsAggregationExpr(v) {
 	return false;
 }
 /**
+* A field's current value in an aggregation pipeline update — a missing field
+* counts as `0`, like the `$inc` / `$mul` update operators (the pipeline
+* `$add` / `$multiply` would yield `null`) — so a document written before an
+* `@db.onUpdate.inc` counter existed starts counting.
+*/
+function fieldOpCurrent(field) {
+	return { $ifNull: [`$${field}`, 0] };
+}
+/** Aggregation expression adding `by` to `field` (an `$inc` in a pipeline update). */
+function incExpr(field, by) {
+	return { $add: [fieldOpCurrent(field), by] };
+}
+/**
 * CollectionPatcher is a small helper that converts a *patch payload* produced
 * by Atscript into a shape that the official MongoDB driver understands – a
 * triple of `(filter, update, options)` to be fed to `collection.updateOne()`.
@@ -143,9 +157,9 @@ var CollectionPatcher = class {
 			updateOptions: this.optionsObj
 		};
 	}
-	/** Builds a MongoDB aggregation expression for an $inc or $mul field op. */
+	/** Aggregation expression of an `$inc` / `$mul` field op (see {@link fieldOpCurrent}). */
 	_fieldOpExpr(key, op, value) {
-		return op === "inc" ? { $add: [`$${key}`, value] } : { $multiply: [`$${key}`, value] };
+		return op === "inc" ? incExpr(key, value) : { $multiply: [fieldOpCurrent(key), value] };
 	}
 	/**
 	* Helper – lazily create `$set` section and assign *key* → *value*.
@@ -1840,8 +1854,12 @@ const PK_INDEX = mongoIndexKey("unique", "__pk");
 * index of a skipped key rebuild, the indexes over a column whose type change
 * is pending (its present-only filter is typed).
 */
-async function syncIndexesImpl(host, opts) {
-	await host.ensureCollectionExists();
+async function syncIndexesImpl(host, opts, dryRun = false) {
+	/** Indexes dropped because their definition drifted — their re-creation is a rebuild. */
+	const replaced = /* @__PURE__ */ new Set();
+	if (dryRun) {
+		if (!await host.db.listCollections({ name: host.collection.collectionName }, { nameOnly: true }).hasNext()) return [];
+	} else await host.ensureCollectionExists();
 	const allIndexes = /* @__PURE__ */ new Map();
 	for (const [key, index] of host._table.indexes.entries()) {
 		const fields = {};
@@ -1888,6 +1906,7 @@ async function syncIndexesImpl(host, opts) {
 	for (const remote of existingIndexes) if (isKept(remote.name, remote.key, remote.weights)) kept.add(remote.name);
 	for (const name of kept) indexesToCreate.delete(name);
 	const { attempt, throwIfAny } = (0, _atscript_db.createFailureCollector)("index sync");
+	const { changes, apply } = (0, _atscript_db.createChangeRecorder)(dryRun, attempt);
 	let defaultCollation;
 	const collectionDefaultCollation = async () => {
 		if (defaultCollation === void 0) defaultCollation = (await host.db.listCollections({ name: host.collection.collectionName }).next())?.options?.collation ?? null;
@@ -1906,16 +1925,21 @@ async function syncIndexesImpl(host, opts) {
 				if (fieldsMatch && weightsMatch && optionsMatch) indexesToCreate.delete(remote.name);
 				else if (violation !== void 0) {
 					indexesToCreate.delete(remote.name);
+					if (dryRun) continue;
 					await attempt(`replace unique index "${remote.name}"`, () => Promise.reject(/* @__PURE__ */ new Error(`existing documents violate the new index (duplicate key ${JSON.stringify(violation)}); the current index is kept`)));
-				} else {
+				} else if (dryRun) replaced.add(remote.name);
+				else {
 					host._log("dropIndex", remote.name);
-					await attempt(`drop index "${remote.name}"`, () => host.collection.dropIndex(remote.name));
+					if (await attempt(`drop index "${remote.name}"`, () => host.collection.dropIndex(remote.name))) replaced.add(remote.name);
 				}
 			}
-		} else {
+		} else await apply({
+			name: remote.name,
+			action: "drop"
+		}, `drop index "${remote.name}"`, () => {
 			host._log("dropIndex", remote.name);
-			await attempt(`drop index "${remote.name}"`, () => host.collection.dropIndex(remote.name));
-		}
+			return host.collection.dropIndex(remote.name);
+		});
 	}
 	for (const [key, value] of allIndexes.entries()) {
 		if (!isPlainIndex(value) || !indexesToCreate.has(key)) continue;
@@ -1955,8 +1979,12 @@ async function syncIndexesImpl(host, opts) {
 				indexOptions = { name: key };
 				break;
 		}
-		await attempt(label, () => host.collection.createIndex(value.fields, indexOptions));
+		await apply({
+			name: key,
+			action: replaced.has(key) ? "rebuild" : "add"
+		}, label, () => host.collection.createIndex(value.fields, indexOptions));
 	}
+	const search = (0, _atscript_db.createChangeRecorder)(dryRun);
 	try {
 		const toUpdate = /* @__PURE__ */ new Set();
 		const existingSearchIndexes = await host.collection.listSearchIndexes().toArray();
@@ -1979,31 +2007,41 @@ async function syncIndexesImpl(host, opts) {
 						break;
 					default:
 				}
-			} else if (remote.status !== "DELETING") {
+			} else if (remote.status !== "DELETING") await search.apply({
+				name: remote.name,
+				action: "drop"
+			}, remote.name, () => {
 				host._log("dropSearchIndex", remote.name);
-				await host.collection.dropSearchIndex(remote.name);
-			}
+				return host.collection.dropSearchIndex(remote.name);
+			});
 		}
 		for (const [key, value] of indexesToCreate.entries()) switch (value.type) {
 			case "dynamic_text":
 			case "search_text":
-			case "vector":
-				if (toUpdate.has(key)) {
-					host._log("updateSearchIndex", key, value.definition);
-					await host.collection.updateSearchIndex(key, value.definition);
-				} else {
+			case "vector": {
+				const update = toUpdate.has(key);
+				await search.apply({
+					name: key,
+					action: update ? "rebuild" : "add"
+				}, key, () => {
+					if (update) {
+						host._log("updateSearchIndex", key, value.definition);
+						return host.collection.updateSearchIndex(key, value.definition);
+					}
 					host._log("createSearchIndex", key, value.type);
-					await host.collection.createSearchIndex({
+					return host.collection.createSearchIndex({
 						name: key,
 						type: value.type === "vector" ? "vectorSearch" : "search",
 						definition: value.definition
 					});
-				}
+				});
 				break;
+			}
 			default:
 		}
 	} catch {}
 	throwIfAny();
+	return [...changes, ...search.changes];
 }
 /**
 * The collation a plain / unique index is built with (since 0.1.151): the
@@ -2273,22 +2311,33 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 	* Uses MongoDB's Convenient Transaction API (`session.withTransaction()`).
 	* This handles txnNumber management and automatic retry for
 	* `TransientTransactionError` / `UnknownTransactionCommitResult`.
+	*
+	* `opts.isolation` (since 0.1.162): a MongoDB transaction reads one
+	* snapshot, which satisfies `'read committed'` and `'repeatable read'`;
+	* `'serializable'` throws `ISOLATION_NOT_SUPPORTED` (snapshot isolation
+	* allows write skew), and so does any level on a topology without
+	* transactions (standalone), where `fn` would run without one.
 	*/
-	async withTransaction(fn) {
+	async withTransaction(fn, opts) {
+		const isolation = this._checkIsolation(opts);
 		if (this._getTransactionState()) return fn();
-		if (this._txDisabled || !this._client) return fn();
+		const passThrough = () => {
+			if (isolation) throw this._isolationNotSupported(`Isolation '${isolation}' needs a MongoDB transaction — this topology (standalone) has none`);
+			return fn();
+		};
+		if (this._txDisabled || !this._client) return passThrough();
 		try {
 			const topology = this._client.topology;
 			if (topology) {
 				const type = (topology.description ?? topology.s?.description)?.type;
 				if (type === "Single" || type === "Unknown") {
 					this._txDisabled = true;
-					return fn();
+					return passThrough();
 				}
 			}
 		} catch {
 			this._txDisabled = true;
-			return fn();
+			return passThrough();
 		}
 		const session = this._client.startSession();
 		try {
@@ -2303,6 +2352,17 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 			} catch {}
 		}
 	}
+	static _ISOLATION_LEVELS = new Set(["read committed", "repeatable read"]);
+	/**
+	* `'read committed'` and `'repeatable read'` — a transaction's snapshot
+	* read satisfies both. No `'serializable'` (snapshot isolation allows
+	* write skew). Locking reads are not supported (`supportsReadLocks()` is
+	* false → `LOCK_NOT_SUPPORTED`): use `$cas` / `withOptimisticRetry`.
+	* @since 0.1.162
+	*/
+	isolationLevels() {
+		return MongoAdapter._ISOLATION_LEVELS;
+	}
 	static _noSession = Object.freeze({});
 	/** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
 	_getSessionOpts() {
@@ -2670,6 +2730,8 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 		for (const field of this._pendingUniqueFields) this._addMongoIndexField("unique", "__pk", meta.documentPath(field));
 		for (const pending of this._pendingSearchFields) this._addFieldToSearchIndex("search_text", pending.indexName, pending.field, pending.mappings);
 		this._pendingSearchFields = [];
+		const [encrypted] = meta.encryptedFields;
+		if (encrypted !== void 0 && [...this._mongoIndexes.values()].some((i) => i.type === "dynamic_text")) throw new Error(require_search_messages.dynamicSearchEncryptedMessage(encrypted));
 		const textBearing = [...this._table.indexes.values()].filter((i) => i.type === "fulltext" && i.fields.some((f) => !f.integer));
 		if (textBearing.length > 1) throw new Error(`MongoDB allows one text index per collection: "${this._table.tableName}" declares ${textBearing.length} @db.index.fulltext names with text fields (${textBearing.map((i) => `"${i.name}"`).join(", ")}). Merge them into one name; integer-only fulltext indexes may be declared separately.`);
 		for (const fulltext of this._table.indexes.values()) {
@@ -3150,12 +3212,14 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 			modifiedCount: 0
 		};
 		const versionColumn = this._table.versionColumnPhysical;
+		const counters = this._table.onUpdateIncPhysical;
 		this._log("replaceOne", mongoFilter, data);
-		if (versionColumn !== void 0) {
-			const pipeline = [{ $replaceWith: {
-				...data,
-				[versionColumn]: { $add: [`$${versionColumn}`, 1] }
-			} }];
+		if (versionColumn !== void 0 || counters.length > 0) {
+			const replacement = {};
+			for (const [key, value] of Object.entries(data)) replacement[key] = { $literal: value };
+			for (const col of counters) replacement[col] = incExpr(col, 1);
+			if (versionColumn !== void 0) replacement[versionColumn] = { $add: [`$${versionColumn}`, 1] };
+			const pipeline = [{ $replaceWith: replacement }];
 			return this._wrapUpdate(() => this.collection.updateOne(mongoFilter, pipeline, this._getSessionOpts()));
 		}
 		return this._wrapUpdate(() => this.collection.replaceOne(mongoFilter, data, this._getSessionOpts()));
@@ -3174,7 +3238,7 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 		});
 	}
 	async replaceMany(filter, data) {
-		const updateDoc = buildMongoUpdateDoc(data, void 0, this._table.versionColumnPhysical);
+		const updateDoc = buildMongoUpdateDoc(data, this._onUpdateIncOps(), this._table.versionColumnPhysical);
 		return this._updateMatching(filter, (mongoFilter) => {
 			this._log("replaceMany", mongoFilter, updateDoc);
 			return this._wrapUpdate(() => this.collection.updateMany(mongoFilter, updateDoc, this._getSessionOpts()));
@@ -3215,8 +3279,8 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 	* `__pk` index first (`dropIndexesForColumns`).
 	*/
 	async rebuildPrimaryKey(_change) {}
-	async syncIndexes(opts) {
-		return syncIndexesImpl(this, opts);
+	async _syncIndexes(dryRun, opts) {
+		return syncIndexesImpl(this, opts, dryRun);
 	}
 	async syncColumns(diff) {
 		return syncColumnsImpl(this, diff);
@@ -3605,6 +3669,7 @@ exports.buildMongoFilter = require_mongo_accumulator.buildMongoFilter;
 exports.buildMongoQuery = require_mongo_accumulator.buildMongoQuery;
 exports.collationOfAdapter = require_mongo_accumulator.collationOfAdapter;
 exports.createAdapter = createAdapter;
+exports.incExpr = incExpr;
 exports.mongoFilterStages = require_mongo_accumulator.mongoFilterStages;
 exports.mongoIndexKey = mongoIndexKey;
 exports.planStages = require_mongo_accumulator.planStages;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { a as buildMongoFilter, c as mongoFilterStages, i as TMongoFilterPlan, l as planStages, n as TMongoFieldCollation, o as buildMongoQuery, r as TMongoFilterOptions, s as collationOfAdapter, t as REL_FILTER_TEMP_PREFIX } from "./mongo-filter-CGd9ryOD.cjs";
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbCollation, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateOptions, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TSyncIndexesOptions, TTableResolver, TViewCapability, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbCollation, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbIsolationLevel, TDbObjectKind, TDbRelation, TDbUpdateOptions, TDbUpdateResult, TExistingTableOption, TFieldOps, TIndexChange, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TSyncIndexesOptions, TTableResolver, TTransactionOptions, TViewCapability, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
 import { AggregateOptions, AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
 import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 import { AggregateFn, BucketUnit } from "@uniqu/core";
@@ -14,6 +14,8 @@ interface TCollectionPatcherContext {
   prepareId(id: any): any;
   createValidator(opts?: Partial<TValidatorOptions>): Validator<any>;
 }
+/** Aggregation expression adding `by` to `field` (an `$inc` in a pipeline update). */
+declare function incExpr(field: string, by: number): Document;
 /**
  * CollectionPatcher is a small helper that converts a *patch payload* produced
  * by Atscript into a shape that the official MongoDB driver understands – a
@@ -64,7 +66,7 @@ declare class CollectionPatcher {
     updateFilter: Document[];
     updateOptions: UpdateOptions;
   };
-  /** Builds a MongoDB aggregation expression for an $inc or $mul field op. */
+  /** Aggregation expression of an `$inc` / `$mul` field op (see {@link fieldOpCurrent}). */
   private _fieldOpExpr;
   /**
    * Helper – lazily create `$set` section and assign *key* → *value*.
@@ -327,8 +329,23 @@ declare class MongoAdapter extends BaseDbAdapter {
    * Uses MongoDB's Convenient Transaction API (`session.withTransaction()`).
    * This handles txnNumber management and automatic retry for
    * `TransientTransactionError` / `UnknownTransactionCommitResult`.
-   */
-  withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+   *
+   * `opts.isolation` (since 0.1.162): a MongoDB transaction reads one
+   * snapshot, which satisfies `'read committed'` and `'repeatable read'`;
+   * `'serializable'` throws `ISOLATION_NOT_SUPPORTED` (snapshot isolation
+   * allows write skew), and so does any level on a topology without
+   * transactions (standalone), where `fn` would run without one.
+   */
+  withTransaction<T>(fn: () => Promise<T>, opts?: TTransactionOptions): Promise<T>;
+  private static readonly _ISOLATION_LEVELS;
+  /**
+   * `'read committed'` and `'repeatable read'` — a transaction's snapshot
+   * read satisfies both. No `'serializable'` (snapshot isolation allows
+   * write skew). Locking reads are not supported (`supportsReadLocks()` is
+   * false → `LOCK_NOT_SUPPORTED`): use `$cas` / `withOptimisticRetry`.
+   * @since 0.1.162
+   */
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
   private static readonly _noSession;
   /** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
   protected _getSessionOpts(): {
@@ -596,7 +613,7 @@ declare class MongoAdapter extends BaseDbAdapter {
    * `__pk` index first (`dropIndexesForColumns`).
    */
   rebuildPrimaryKey(_change: TPrimaryKeyChange): Promise<void>;
-  syncIndexes(opts?: TSyncIndexesOptions): Promise<void>;
+  protected _syncIndexes(dryRun: boolean, opts?: TSyncIndexesOptions): Promise<TIndexChange[]>;
   syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
   dropColumns(columns: string[]): Promise<void>;
   dropIndexesForColumns(columns: string[]): Promise<void>;
@@ -697,4 +714,4 @@ declare const validateMongoIdPlugin: TValidatorPlugin;
 /** A {@link DbSpace} over the database of `connection`; `options` go to every {@link MongoAdapter}. */
 declare function createAdapter(connection: string, options?: TMongoAdapterOptions): DbSpace;
 //#endregion
-export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, TCollectionPatcherContext, TMongoAdapterOptions, TMongoFieldCollation, TMongoFilterOptions, TMongoFilterPlan, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };
+export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, TCollectionPatcherContext, TMongoAdapterOptions, TMongoFieldCollation, TMongoFilterOptions, TMongoFilterPlan, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, incExpr, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { a as buildMongoFilter, c as mongoFilterStages, i as TMongoFilterPlan, l as planStages, n as TMongoFieldCollation, o as buildMongoQuery, r as TMongoFilterOptions, s as collationOfAdapter, t as REL_FILTER_TEMP_PREFIX } from "./mongo-filter-CGd9ryOD.mjs";
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbCollation, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbRelation, TDbUpdateOptions, TDbUpdateResult, TExistingTableOption, TFieldOps, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TSyncIndexesOptions, TTableResolver, TViewCapability, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbCollation, TDbDeleteResult, TDbFieldMeta, TDbForeignKey, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbIsolationLevel, TDbObjectKind, TDbRelation, TDbUpdateOptions, TDbUpdateResult, TExistingTableOption, TFieldOps, TIndexChange, TMetadataOverrides, TPrimaryKeyChange, TSearchIndexInfo, TSyncColumnResult, TSyncIndexesOptions, TTableResolver, TTransactionOptions, TViewCapability, TableMetadata, WithRelation, getKeyProps } from "@atscript/db";
 import { AggregateOptions, AggregationCursor, ClientSession, Collection, Db, Document, Filter, MongoClient, ObjectId, UpdateFilter, UpdateOptions } from "mongodb";
 import { AggregateFn, BucketUnit } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
@@ -14,6 +14,8 @@ interface TCollectionPatcherContext {
   prepareId(id: any): any;
   createValidator(opts?: Partial<TValidatorOptions>): Validator<any>;
 }
+/** Aggregation expression adding `by` to `field` (an `$inc` in a pipeline update). */
+declare function incExpr(field: string, by: number): Document;
 /**
  * CollectionPatcher is a small helper that converts a *patch payload* produced
  * by Atscript into a shape that the official MongoDB driver understands – a
@@ -64,7 +66,7 @@ declare class CollectionPatcher {
     updateFilter: Document[];
     updateOptions: UpdateOptions;
   };
-  /** Builds a MongoDB aggregation expression for an $inc or $mul field op. */
+  /** Aggregation expression of an `$inc` / `$mul` field op (see {@link fieldOpCurrent}). */
   private _fieldOpExpr;
   /**
    * Helper – lazily create `$set` section and assign *key* → *value*.
@@ -327,8 +329,23 @@ declare class MongoAdapter extends BaseDbAdapter {
    * Uses MongoDB's Convenient Transaction API (`session.withTransaction()`).
    * This handles txnNumber management and automatic retry for
    * `TransientTransactionError` / `UnknownTransactionCommitResult`.
-   */
-  withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+   *
+   * `opts.isolation` (since 0.1.162): a MongoDB transaction reads one
+   * snapshot, which satisfies `'read committed'` and `'repeatable read'`;
+   * `'serializable'` throws `ISOLATION_NOT_SUPPORTED` (snapshot isolation
+   * allows write skew), and so does any level on a topology without
+   * transactions (standalone), where `fn` would run without one.
+   */
+  withTransaction<T>(fn: () => Promise<T>, opts?: TTransactionOptions): Promise<T>;
+  private static readonly _ISOLATION_LEVELS;
+  /**
+   * `'read committed'` and `'repeatable read'` — a transaction's snapshot
+   * read satisfies both. No `'serializable'` (snapshot isolation allows
+   * write skew). Locking reads are not supported (`supportsReadLocks()` is
+   * false → `LOCK_NOT_SUPPORTED`): use `$cas` / `withOptimisticRetry`.
+   * @since 0.1.162
+   */
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
   private static readonly _noSession;
   /** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
   protected _getSessionOpts(): {
@@ -596,7 +613,7 @@ declare class MongoAdapter extends BaseDbAdapter {
    * `__pk` index first (`dropIndexesForColumns`).
    */
   rebuildPrimaryKey(_change: TPrimaryKeyChange): Promise<void>;
-  syncIndexes(opts?: TSyncIndexesOptions): Promise<void>;
+  protected _syncIndexes(dryRun: boolean, opts?: TSyncIndexesOptions): Promise<TIndexChange[]>;
   syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
   dropColumns(columns: string[]): Promise<void>;
   dropIndexesForColumns(columns: string[]): Promise<void>;
@@ -697,4 +714,4 @@ declare const validateMongoIdPlugin: TValidatorPlugin;
 /** A {@link DbSpace} over the database of `connection`; `options` go to every {@link MongoAdapter}. */
 declare function createAdapter(connection: string, options?: TMongoAdapterOptions): DbSpace;
 //#endregion
-export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, TCollectionPatcherContext, TMongoAdapterOptions, TMongoFieldCollation, TMongoFilterOptions, TMongoFilterPlan, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };
+export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, TCollectionPatcherContext, TMongoAdapterOptions, TMongoFieldCollation, TMongoFilterOptions, TMongoFilterPlan, type TMongoIndex, type TMongoSearchIndexDefinition, type TPlainIndex, type TSearchIndex, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, incExpr, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { a as buildMongoQuery, c as planStages, f as sortStages, g as queryNodeToExpr, h as orNull, i as buildMongoFilter, l as correlate, n as distinctCountExpr, o as collationOfAdapter, p as exprToMongo, r as REL_FILTER_TEMP_PREFIX, s as mongoFilterStages, t as buildAccumulator, u as hasNullsPlacement } from "./mongo-accumulator-DMPFOscc.mjs";
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, andFilters, bucketTimeZoneUnavailable, computeInsights, containsRelationFilter, createFailureCollector, defaultFulltextIndex, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, isAtscriptDbView, isFieldRef, isPlainObject, isViewType, queryReadColumns, relationStaticFilter, resolveDesignType, searchIndexNotFoundMessage, searchTermInteger, tableNameOf, translateQueryTree, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
+import { t as dynamicSearchEncryptedMessage } from "./search-messages-mQSpJ4GD.mjs";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, andFilters, bucketTimeZoneUnavailable, computeInsights, containsRelationFilter, createChangeRecorder, createFailureCollector, defaultFulltextIndex, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, isAtscriptDbView, isFieldRef, isPlainObject, isViewType, queryReadColumns, relationStaticFilter, resolveDesignType, searchIndexNotFoundMessage, searchTermInteger, tableNameOf, translateQueryTree, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { MongoBulkWriteError, MongoClient, MongoServerError, ObjectId } from "mongodb";
 import { resolveAggregateSearch } from "@atscript/db/agg";
 //#region src/lib/path-utils.ts
@@ -78,6 +79,19 @@ function containsAggregationExpr(v) {
 	return false;
 }
 /**
+* A field's current value in an aggregation pipeline update — a missing field
+* counts as `0`, like the `$inc` / `$mul` update operators (the pipeline
+* `$add` / `$multiply` would yield `null`) — so a document written before an
+* `@db.onUpdate.inc` counter existed starts counting.
+*/
+function fieldOpCurrent(field) {
+	return { $ifNull: [`$${field}`, 0] };
+}
+/** Aggregation expression adding `by` to `field` (an `$inc` in a pipeline update). */
+function incExpr(field, by) {
+	return { $add: [fieldOpCurrent(field), by] };
+}
+/**
 * CollectionPatcher is a small helper that converts a *patch payload* produced
 * by Atscript into a shape that the official MongoDB driver understands – a
 * triple of `(filter, update, options)` to be fed to `collection.updateOne()`.
@@ -142,9 +156,9 @@ var CollectionPatcher = class {
 			updateOptions: this.optionsObj
 		};
 	}
-	/** Builds a MongoDB aggregation expression for an $inc or $mul field op. */
+	/** Aggregation expression of an `$inc` / `$mul` field op (see {@link fieldOpCurrent}). */
 	_fieldOpExpr(key, op, value) {
-		return op === "inc" ? { $add: [`$${key}`, value] } : { $multiply: [`$${key}`, value] };
+		return op === "inc" ? incExpr(key, value) : { $multiply: [fieldOpCurrent(key), value] };
 	}
 	/**
 	* Helper – lazily create `$set` section and assign *key* → *value*.
@@ -1839,8 +1853,12 @@ const PK_INDEX = mongoIndexKey("unique", "__pk");
 * index of a skipped key rebuild, the indexes over a column whose type change
 * is pending (its present-only filter is typed).
 */
-async function syncIndexesImpl(host, opts) {
-	await host.ensureCollectionExists();
+async function syncIndexesImpl(host, opts, dryRun = false) {
+	/** Indexes dropped because their definition drifted — their re-creation is a rebuild. */
+	const replaced = /* @__PURE__ */ new Set();
+	if (dryRun) {
+		if (!await host.db.listCollections({ name: host.collection.collectionName }, { nameOnly: true }).hasNext()) return [];
+	} else await host.ensureCollectionExists();
 	const allIndexes = /* @__PURE__ */ new Map();
 	for (const [key, index] of host._table.indexes.entries()) {
 		const fields = {};
@@ -1887,6 +1905,7 @@ async function syncIndexesImpl(host, opts) {
 	for (const remote of existingIndexes) if (isKept(remote.name, remote.key, remote.weights)) kept.add(remote.name);
 	for (const name of kept) indexesToCreate.delete(name);
 	const { attempt, throwIfAny } = createFailureCollector("index sync");
+	const { changes, apply } = createChangeRecorder(dryRun, attempt);
 	let defaultCollation;
 	const collectionDefaultCollation = async () => {
 		if (defaultCollation === void 0) defaultCollation = (await host.db.listCollections({ name: host.collection.collectionName }).next())?.options?.collation ?? null;
@@ -1905,16 +1924,21 @@ async function syncIndexesImpl(host, opts) {
 				if (fieldsMatch && weightsMatch && optionsMatch) indexesToCreate.delete(remote.name);
 				else if (violation !== void 0) {
 					indexesToCreate.delete(remote.name);
+					if (dryRun) continue;
 					await attempt(`replace unique index "${remote.name}"`, () => Promise.reject(/* @__PURE__ */ new Error(`existing documents violate the new index (duplicate key ${JSON.stringify(violation)}); the current index is kept`)));
-				} else {
+				} else if (dryRun) replaced.add(remote.name);
+				else {
 					host._log("dropIndex", remote.name);
-					await attempt(`drop index "${remote.name}"`, () => host.collection.dropIndex(remote.name));
+					if (await attempt(`drop index "${remote.name}"`, () => host.collection.dropIndex(remote.name))) replaced.add(remote.name);
 				}
 			}
-		} else {
+		} else await apply({
+			name: remote.name,
+			action: "drop"
+		}, `drop index "${remote.name}"`, () => {
 			host._log("dropIndex", remote.name);
-			await attempt(`drop index "${remote.name}"`, () => host.collection.dropIndex(remote.name));
-		}
+			return host.collection.dropIndex(remote.name);
+		});
 	}
 	for (const [key, value] of allIndexes.entries()) {
 		if (!isPlainIndex(value) || !indexesToCreate.has(key)) continue;
@@ -1954,8 +1978,12 @@ async function syncIndexesImpl(host, opts) {
 				indexOptions = { name: key };
 				break;
 		}
-		await attempt(label, () => host.collection.createIndex(value.fields, indexOptions));
+		await apply({
+			name: key,
+			action: replaced.has(key) ? "rebuild" : "add"
+		}, label, () => host.collection.createIndex(value.fields, indexOptions));
 	}
+	const search = createChangeRecorder(dryRun);
 	try {
 		const toUpdate = /* @__PURE__ */ new Set();
 		const existingSearchIndexes = await host.collection.listSearchIndexes().toArray();
@@ -1978,31 +2006,41 @@ async function syncIndexesImpl(host, opts) {
 						break;
 					default:
 				}
-			} else if (remote.status !== "DELETING") {
+			} else if (remote.status !== "DELETING") await search.apply({
+				name: remote.name,
+				action: "drop"
+			}, remote.name, () => {
 				host._log("dropSearchIndex", remote.name);
-				await host.collection.dropSearchIndex(remote.name);
-			}
+				return host.collection.dropSearchIndex(remote.name);
+			});
 		}
 		for (const [key, value] of indexesToCreate.entries()) switch (value.type) {
 			case "dynamic_text":
 			case "search_text":
-			case "vector":
-				if (toUpdate.has(key)) {
-					host._log("updateSearchIndex", key, value.definition);
-					await host.collection.updateSearchIndex(key, value.definition);
-				} else {
+			case "vector": {
+				const update = toUpdate.has(key);
+				await search.apply({
+					name: key,
+					action: update ? "rebuild" : "add"
+				}, key, () => {
+					if (update) {
+						host._log("updateSearchIndex", key, value.definition);
+						return host.collection.updateSearchIndex(key, value.definition);
+					}
 					host._log("createSearchIndex", key, value.type);
-					await host.collection.createSearchIndex({
+					return host.collection.createSearchIndex({
 						name: key,
 						type: value.type === "vector" ? "vectorSearch" : "search",
 						definition: value.definition
 					});
-				}
+				});
 				break;
+			}
 			default:
 		}
 	} catch {}
 	throwIfAny();
+	return [...changes, ...search.changes];
 }
 /**
 * The collation a plain / unique index is built with (since 0.1.151): the
@@ -2272,22 +2310,33 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	* Uses MongoDB's Convenient Transaction API (`session.withTransaction()`).
 	* This handles txnNumber management and automatic retry for
 	* `TransientTransactionError` / `UnknownTransactionCommitResult`.
+	*
+	* `opts.isolation` (since 0.1.162): a MongoDB transaction reads one
+	* snapshot, which satisfies `'read committed'` and `'repeatable read'`;
+	* `'serializable'` throws `ISOLATION_NOT_SUPPORTED` (snapshot isolation
+	* allows write skew), and so does any level on a topology without
+	* transactions (standalone), where `fn` would run without one.
 	*/
-	async withTransaction(fn) {
+	async withTransaction(fn, opts) {
+		const isolation = this._checkIsolation(opts);
 		if (this._getTransactionState()) return fn();
-		if (this._txDisabled || !this._client) return fn();
+		const passThrough = () => {
+			if (isolation) throw this._isolationNotSupported(`Isolation '${isolation}' needs a MongoDB transaction — this topology (standalone) has none`);
+			return fn();
+		};
+		if (this._txDisabled || !this._client) return passThrough();
 		try {
 			const topology = this._client.topology;
 			if (topology) {
 				const type = (topology.description ?? topology.s?.description)?.type;
 				if (type === "Single" || type === "Unknown") {
 					this._txDisabled = true;
-					return fn();
+					return passThrough();
 				}
 			}
 		} catch {
 			this._txDisabled = true;
-			return fn();
+			return passThrough();
 		}
 		const session = this._client.startSession();
 		try {
@@ -2302,6 +2351,17 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			} catch {}
 		}
 	}
+	static _ISOLATION_LEVELS = new Set(["read committed", "repeatable read"]);
+	/**
+	* `'read committed'` and `'repeatable read'` — a transaction's snapshot
+	* read satisfies both. No `'serializable'` (snapshot isolation allows
+	* write skew). Locking reads are not supported (`supportsReadLocks()` is
+	* false → `LOCK_NOT_SUPPORTED`): use `$cas` / `withOptimisticRetry`.
+	* @since 0.1.162
+	*/
+	isolationLevels() {
+		return MongoAdapter._ISOLATION_LEVELS;
+	}
 	static _noSession = Object.freeze({});
 	/** Returns `{ session }` opts if inside a transaction, empty object otherwise. */
 	_getSessionOpts() {
@@ -2669,6 +2729,8 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		for (const field of this._pendingUniqueFields) this._addMongoIndexField("unique", "__pk", meta.documentPath(field));
 		for (const pending of this._pendingSearchFields) this._addFieldToSearchIndex("search_text", pending.indexName, pending.field, pending.mappings);
 		this._pendingSearchFields = [];
+		const [encrypted] = meta.encryptedFields;
+		if (encrypted !== void 0 && [...this._mongoIndexes.values()].some((i) => i.type === "dynamic_text")) throw new Error(dynamicSearchEncryptedMessage(encrypted));
 		const textBearing = [...this._table.indexes.values()].filter((i) => i.type === "fulltext" && i.fields.some((f) => !f.integer));
 		if (textBearing.length > 1) throw new Error(`MongoDB allows one text index per collection: "${this._table.tableName}" declares ${textBearing.length} @db.index.fulltext names with text fields (${textBearing.map((i) => `"${i.name}"`).join(", ")}). Merge them into one name; integer-only fulltext indexes may be declared separately.`);
 		for (const fulltext of this._table.indexes.values()) {
@@ -3149,12 +3211,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			modifiedCount: 0
 		};
 		const versionColumn = this._table.versionColumnPhysical;
+		const counters = this._table.onUpdateIncPhysical;
 		this._log("replaceOne", mongoFilter, data);
-		if (versionColumn !== void 0) {
-			const pipeline = [{ $replaceWith: {
-				...data,
-				[versionColumn]: { $add: [`$${versionColumn}`, 1] }
-			} }];
+		if (versionColumn !== void 0 || counters.length > 0) {
+			const replacement = {};
+			for (const [key, value] of Object.entries(data)) replacement[key] = { $literal: value };
+			for (const col of counters) replacement[col] = incExpr(col, 1);
+			if (versionColumn !== void 0) replacement[versionColumn] = { $add: [`$${versionColumn}`, 1] };
+			const pipeline = [{ $replaceWith: replacement }];
 			return this._wrapUpdate(() => this.collection.updateOne(mongoFilter, pipeline, this._getSessionOpts()));
 		}
 		return this._wrapUpdate(() => this.collection.replaceOne(mongoFilter, data, this._getSessionOpts()));
@@ -3173,7 +3237,7 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		});
 	}
 	async replaceMany(filter, data) {
-		const updateDoc = buildMongoUpdateDoc(data, void 0, this._table.versionColumnPhysical);
+		const updateDoc = buildMongoUpdateDoc(data, this._onUpdateIncOps(), this._table.versionColumnPhysical);
 		return this._updateMatching(filter, (mongoFilter) => {
 			this._log("replaceMany", mongoFilter, updateDoc);
 			return this._wrapUpdate(() => this.collection.updateMany(mongoFilter, updateDoc, this._getSessionOpts()));
@@ -3214,8 +3278,8 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	* `__pk` index first (`dropIndexesForColumns`).
 	*/
 	async rebuildPrimaryKey(_change) {}
-	async syncIndexes(opts) {
-		return syncIndexesImpl(this, opts);
+	async _syncIndexes(dryRun, opts) {
+		return syncIndexesImpl(this, opts, dryRun);
 	}
 	async syncColumns(diff) {
 		return syncColumnsImpl(this, diff);
@@ -3596,4 +3660,4 @@ function createAdapter(connection, options) {
 	return new DbSpace(() => new MongoAdapter(db, client, options), { onClose: () => client.close() });
 }
 //#endregion
-export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };
+export { CollectionPatcher, INDEX_PREFIX, MongoAdapter, REL_FILTER_TEMP_PREFIX, buildMongoFilter, buildMongoQuery, collationOfAdapter, createAdapter, incExpr, mongoFilterStages, mongoIndexKey, planStages, validateMongoIdPlugin };

package/dist/plugin.cjs

@@ -2,7 +2,9 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
+const require_search_messages = require("./search-messages-BqLxxrb8.cjs");
 let _atscript_core = require("@atscript/core");
+let _atscript_db_shared = require("@atscript/db/shared");
 //#region src/plugin/annotations.ts
 const analyzers = [
 	"lucene.standard",
@@ -50,7 +52,7 @@ const fuzzyDescription = "Maximum typo tolerance, applied **at query time** to t
 */
 const annotations = {
 	collection: new _atscript_core.AnnotationSpec({
-		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		description: (0, _atscript_core.annotationExample)("Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.", "@db.table \"users\"", "@db.mongo.collection", "export interface User {", "    _id: mongo.objectId", "    email: string.email", "}"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		validate(token, args, doc) {
@@ -90,7 +92,7 @@ const annotations = {
 		}
 	}),
 	capped: new _atscript_core.AnnotationSpec({
-		description: "Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.\n\n**Example:**\n```atscript\n@db.table \"logs\"\n@db.mongo.collection\n@db.mongo.capped 10485760, 10000\n@db.sync.method \"drop\"\nexport interface LogEntry {\n    message: string\n    timestamp: number\n}\n```\n",
+		description: (0, _atscript_core.annotationExample)("Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.", "@db.table \"logs\"", "@db.mongo.collection", "@db.mongo.capped 10485760, 10000", "@db.sync.method \"drop\"", "export interface LogEntry {", "    message: string", "    timestamp: number", "}"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -108,10 +110,19 @@ const annotations = {
 	}),
 	search: {
 		dynamic: new _atscript_core.AnnotationSpec({
-			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			description: (0, _atscript_core.annotationExample)("Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.", "@db.mongo.search.dynamic \"lucene.english\", 1", "export interface MongoCollection {}"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			multiple: false,
+			validate(token, _args, doc) {
+				const encrypted = (0, _atscript_db_shared.findStoredField)(token.parentNode, doc, (prop, path) => prop.countAnnotations("db.encrypted") > 0 ? path : void 0);
+				if (!encrypted) return [];
+				return [{
+					message: require_search_messages.dynamicSearchEncryptedMessage(encrypted),
+					severity: 1,
+					range: token.range
+				}];
+			},
 			argument: [{
 				optional: true,
 				name: "analyzer",
@@ -126,7 +137,7 @@ const annotations = {
 			}]
 		}),
 		static: new _atscript_core.AnnotationSpec({
-			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			description: (0, _atscript_core.annotationExample)("Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.", "@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"", "export interface MongoCollection {}"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			multiple: true,
@@ -160,8 +171,9 @@ const annotations = {
 			]
 		}),
 		text: new _atscript_core.AnnotationSpec({
-			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			description: (0, _atscript_core.annotationExample)("Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.", "@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"", "firstName: string"),
 			nodeType: ["prop"],
+			validate: (0, _atscript_db_shared.refuseCiphertext)("@db.mongo.search.text"),
 			passedWhenReferred: false,
 			multiple: true,
 			argument: [{
@@ -178,8 +190,9 @@ const annotations = {
 			}]
 		}),
 		autocomplete: new _atscript_core.AnnotationSpec({
-			description: "Marks a field for **prefix / typeahead (as-you-type)** matching in a MongoDB Atlas Search Index.\n\n- Indexes the field as the Atlas **`autocomplete`** type, **and** double-maps it as `string` so exact-word hits still rank.\n- Lets `search()` match partial words: with the default `edgeGram` tokenization, `\"art\"` matches `\"Artem\"` **as you type** (no whole word required).\n- Use `nGram` tokenization for true mid-word (infix/substring) matching at higher index cost.\n- Like `@db.mongo.search.text`, the field joins the index named by `indexName` (or the default index).\n\n**Example:**\n```atscript\n@db.mongo.search.autocomplete \"users\"\nusername: string\n```\n",
+			description: (0, _atscript_core.annotationExample)("Marks a field for **prefix / typeahead (as-you-type)** matching in a MongoDB Atlas Search Index.\n\n- Indexes the field as the Atlas **`autocomplete`** type, **and** double-maps it as `string` so exact-word hits still rank.\n- Lets `search()` match partial words: with the default `edgeGram` tokenization, `\"art\"` matches `\"Artem\"` **as you type** (no whole word required).\n- Use `nGram` tokenization for true mid-word (infix/substring) matching at higher index cost.\n- Like `@db.mongo.search.text`, the field joins the index named by `indexName` (or the default index).", "@db.mongo.search.autocomplete \"users\"", "username: string"),
 			nodeType: ["prop"],
+			validate: (0, _atscript_db_shared.refuseCiphertext)("@db.mongo.search.autocomplete"),
 			passedWhenReferred: false,
 			multiple: true,
 			argument: [
@@ -229,7 +242,7 @@ const annotations = {
 //#region src/plugin/primitives.ts
 const primitives = { mongo: { extensions: { objectId: {
 	type: "string",
-	documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
+	documentation: (0, _atscript_core.annotationExample)("Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.", "userId: mongo.objectId"),
 	annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
 } } } };
 //#endregion

package/dist/plugin.mjs

@@ -1,4 +1,6 @@
-import { AnnotationSpec, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import { t as dynamicSearchEncryptedMessage } from "./search-messages-mQSpJ4GD.mjs";
+import { AnnotationSpec, annotationExample, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import { findStoredField, refuseCiphertext } from "@atscript/db/shared";
 //#region src/plugin/annotations.ts
 const analyzers = [
 	"lucene.standard",
@@ -46,7 +48,7 @@ const fuzzyDescription = "Maximum typo tolerance, applied **at query time** to t
 */
 const annotations = {
 	collection: new AnnotationSpec({
-		description: "Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.\n\n**Example:**\n```atscript\n@db.table \"users\"\n@db.mongo.collection\nexport interface User {\n    _id: mongo.objectId\n    email: string.email\n}\n```\n",
+		description: annotationExample("Marks an interface as a **MongoDB collection**.\n\n- Use together with `@db.table \"name\"` which provides the collection name.\n- Automatically injects a **non-optional** `_id` field if not explicitly defined.\n- `_id` must be of type **`string`**, **`number`**, or **`mongo.objectId`**.", "@db.table \"users\"", "@db.mongo.collection", "export interface User {", "    _id: mongo.objectId", "    email: string.email", "}"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		validate(token, args, doc) {
@@ -86,7 +88,7 @@ const annotations = {
 		}
 	}),
 	capped: new AnnotationSpec({
-		description: "Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.\n\n**Example:**\n```atscript\n@db.table \"logs\"\n@db.mongo.collection\n@db.mongo.capped 10485760, 10000\n@db.sync.method \"drop\"\nexport interface LogEntry {\n    message: string\n    timestamp: number\n}\n```\n",
+		description: annotationExample("Creates a **capped collection** with a fixed maximum size.\n\n- Capped collections have fixed size and maintain insertion order.\n- Ideal for logs, event streams, and cache-like data.\n- Changing the cap size requires dropping and recreating the collection — use `@db.sync.method \"drop\"` to allow this.", "@db.table \"logs\"", "@db.mongo.collection", "@db.mongo.capped 10485760, 10000", "@db.sync.method \"drop\"", "export interface LogEntry {", "    message: string", "    timestamp: number", "}"),
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		multiple: false,
@@ -104,10 +106,19 @@ const annotations = {
 	}),
 	search: {
 		dynamic: new AnnotationSpec({
-			description: "Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.\n\n**Example:**\n```atscript\n@db.mongo.search.dynamic \"lucene.english\", 1\nexport interface MongoCollection {}\n```\n",
+			description: annotationExample("Creates a **dynamic MongoDB Search Index** that applies to the entire collection.\n\n- **Indexes all text fields automatically** (no need to specify fields).\n- Supports **language analyzers** for text tokenization.\n- Enables **fuzzy search** (typo tolerance) if needed.", "@db.mongo.search.dynamic \"lucene.english\", 1", "export interface MongoCollection {}"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			multiple: false,
+			validate(token, _args, doc) {
+				const encrypted = findStoredField(token.parentNode, doc, (prop, path) => prop.countAnnotations("db.encrypted") > 0 ? path : void 0);
+				if (!encrypted) return [];
+				return [{
+					message: dynamicSearchEncryptedMessage(encrypted),
+					severity: 1,
+					range: token.range
+				}];
+			},
 			argument: [{
 				optional: true,
 				name: "analyzer",
@@ -122,7 +133,7 @@ const annotations = {
 			}]
 		}),
 		static: new AnnotationSpec({
-			description: "Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.\n\n**Example:**\n```atscript\n@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"\nexport interface MongoCollection {}\n```\n",
+			description: annotationExample("Defines a **MongoDB Atlas Search Index** for the collection. The props can refer to this index using `@db.mongo.search.text` annotation.\n\n- **Creates a named search index** for full-text search.\n- **Specify analyzers and fuzzy search** behavior at the index level.\n- **Fields must explicitly use `@db.mongo.search.text`** to be included in this search index.", "@db.mongo.search.static \"lucene.english\", 1, \"mySearchIndex\"", "export interface MongoCollection {}"),
 			nodeType: ["interface"],
 			passedWhenReferred: false,
 			multiple: true,
@@ -156,8 +167,9 @@ const annotations = {
 			]
 		}),
 		text: new AnnotationSpec({
-			description: "Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.\n\n**Example:**\n```atscript\n@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"\nfirstName: string\n```\n",
+			description: annotationExample("Marks a field to be **included in a MongoDB Atlas Search Index** defined by `@db.mongo.search.static`.\n\n- **The field has to reference an existing search index name**.\n- If index name is not defined, a new search index with default attributes will be created.", "@db.mongo.search.text \"lucene.english\", \"mySearchIndex\"", "firstName: string"),
 			nodeType: ["prop"],
+			validate: refuseCiphertext("@db.mongo.search.text"),
 			passedWhenReferred: false,
 			multiple: true,
 			argument: [{
@@ -174,8 +186,9 @@ const annotations = {
 			}]
 		}),
 		autocomplete: new AnnotationSpec({
-			description: "Marks a field for **prefix / typeahead (as-you-type)** matching in a MongoDB Atlas Search Index.\n\n- Indexes the field as the Atlas **`autocomplete`** type, **and** double-maps it as `string` so exact-word hits still rank.\n- Lets `search()` match partial words: with the default `edgeGram` tokenization, `\"art\"` matches `\"Artem\"` **as you type** (no whole word required).\n- Use `nGram` tokenization for true mid-word (infix/substring) matching at higher index cost.\n- Like `@db.mongo.search.text`, the field joins the index named by `indexName` (or the default index).\n\n**Example:**\n```atscript\n@db.mongo.search.autocomplete \"users\"\nusername: string\n```\n",
+			description: annotationExample("Marks a field for **prefix / typeahead (as-you-type)** matching in a MongoDB Atlas Search Index.\n\n- Indexes the field as the Atlas **`autocomplete`** type, **and** double-maps it as `string` so exact-word hits still rank.\n- Lets `search()` match partial words: with the default `edgeGram` tokenization, `\"art\"` matches `\"Artem\"` **as you type** (no whole word required).\n- Use `nGram` tokenization for true mid-word (infix/substring) matching at higher index cost.\n- Like `@db.mongo.search.text`, the field joins the index named by `indexName` (or the default index).", "@db.mongo.search.autocomplete \"users\"", "username: string"),
 			nodeType: ["prop"],
+			validate: refuseCiphertext("@db.mongo.search.autocomplete"),
 			passedWhenReferred: false,
 			multiple: true,
 			argument: [
@@ -225,7 +238,7 @@ const annotations = {
 //#region src/plugin/primitives.ts
 const primitives = { mongo: { extensions: { objectId: {
 	type: "string",
-	documentation: "Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.\n\n**Example:**\n```atscript\nuserId: mongo.objectId\n```\n",
+	documentation: annotationExample("Represents a **MongoDB ObjectId**.\n\n- Stored as a **string** but can be converted to an ObjectId at runtime.\n- Useful for handling `_id` fields and queries that require ObjectId conversion.\n- Automatically converts string `_id` values into **MongoDB ObjectId** when needed.", "userId: mongo.objectId"),
 	annotations: { "expect.pattern": { pattern: "^[a-fA-F0-9]{24}$" } }
 } } } };
 //#endregion

package/dist/search-messages-BqLxxrb8.cjs

@@ -0,0 +1,16 @@
+//#region src/lib/search-messages.ts
+/**
+* The refusal of `@db.mongo.search.dynamic` on a collection storing an
+* `@db.encrypted` field (at `path`) — shared by the compile-time check and
+* its runtime mirror.
+*/
+function dynamicSearchEncryptedMessage(path) {
+	return `@db.mongo.search.dynamic indexes every field, including the @db.encrypted field "${path}" — Atlas Search over ciphertext is impossible; use @db.mongo.search.static with @db.mongo.search.text fields`;
+}
+//#endregion
+Object.defineProperty(exports, "dynamicSearchEncryptedMessage", {
+	enumerable: true,
+	get: function() {
+		return dynamicSearchEncryptedMessage;
+	}
+});

package/dist/search-messages-mQSpJ4GD.mjs

@@ -0,0 +1,11 @@
+//#region src/lib/search-messages.ts
+/**
+* The refusal of `@db.mongo.search.dynamic` on a collection storing an
+* `@db.encrypted` field (at `path`) — shared by the compile-time check and
+* its runtime mirror.
+*/
+function dynamicSearchEncryptedMessage(path) {
+	return `@db.mongo.search.dynamic indexes every field, including the @db.encrypted field "${path}" — Atlas Search over ciphertext is impossible; use @db.mongo.search.static with @db.mongo.search.text fields`;
+}
+//#endregion
+export { dynamicSearchEncryptedMessage as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.161",
+  "version": "0.1.163",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -46,19 +46,19 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.108",
-    "@atscript/typescript": "^0.1.108",
+    "@atscript/core": "^0.1.109",
+    "@atscript/typescript": "^0.1.109",
     "@uniqu/core": "^0.1.15",
     "mongodb": "^6.17.0",
     "mongodb-memory-server-core": "^10.0.0",
-    "unplugin-atscript": "^0.1.108"
+    "unplugin-atscript": "^0.1.109"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.108",
-    "@atscript/typescript": "^0.1.108",
+    "@atscript/core": "^0.1.109",
+    "@atscript/typescript": "^0.1.109",
     "@uniqu/core": "^0.1.15",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.161"
+    "@atscript/db": "^0.1.163"
   },
   "scripts": {
     "build": "vp pack",