@atscript/db 0.1.103 → 0.1.104

package/dist/{db-view-Sq4wCceR.mjs → db-view-TyzB5VFb.mjs}

@@ -2,7 +2,7 @@ import { n as DbError } from "./db-error-BHPXOKzc.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 { separateCas, separateFieldOps } from "./ops.mjs";
-import { i as forceNavNonOptional, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-bLsSgi0N.mjs";
+import { i as forceNavNonOptional, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-C7plt6Kf.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/logger.ts
@@ -35,6 +35,24 @@ function findAncestorInSet(path, set) {
 function isNavRelation(metadata) {
 	return metadata.has("db.rel.to") || metadata.has("db.rel.from") || metadata.has("db.rel.via");
 }
+/** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
+function isGeoPointType(fieldType) {
+	return fieldType.type.tags?.has("geoPoint") === true;
+}
+/**
+* Returns true if the annotated type is acceptable for `@db.index.geo`:
+* the `db.geoPoint` primitive or a structurally identical `number[]`
+* (excluding `db.vector`, which is semantically an embedding).
+*/
+function isGeoIndexableType(fieldType) {
+	if (isGeoPointType(fieldType)) return true;
+	if (fieldType.type.tags?.has("vector")) return false;
+	if (fieldType.type.kind === "array") {
+		const of = fieldType.type.of;
+		return !!of && resolveDesignType(of) === "number";
+	}
+	return false;
+}
 /**
 * Computed metadata for a database table or view.
 *
@@ -67,6 +85,8 @@ var TableMetadata = class {
 	versionField;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	quantityRefByField = /* @__PURE__ */ new Map();
+	/** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
+	encryptedFields = /* @__PURE__ */ new Set();
 	pathToPhysical = /* @__PURE__ */ new Map();
 	physicalToPath = /* @__PURE__ */ new Map();
 	flattenedParents = /* @__PURE__ */ new Set();
@@ -135,6 +155,7 @@ var TableMetadata = class {
 			this._scanGenericAnnotations(entry.path, entry.type, entry.metadata, logger);
 			adapter.onFieldScanned?.(entry.path, entry.type, entry.metadata);
 		}
+		for (const path of this.encryptedFields) if (findAncestorInSet(path, this.encryptedFields) !== void 0) this.encryptedFields.delete(path);
 		if (!this.nestedObjects) this._classifyFields();
 		const overrides = adapter.getMetadataOverrides?.(this);
 		if (overrides) this._applyOverrides(overrides);
@@ -247,6 +268,16 @@ var TableMetadata = class {
 			const weight = index !== true && typeof index === "object" ? index?.weight : void 0;
 			this._addIndexField("fulltext", name, fieldName, { weight });
 		}
+		if (metadata.has("db.index.geo")) {
+			const raw = metadata.get("db.index.geo");
+			const name = typeof raw === "string" && raw ? raw : fieldName;
+			this._validateGeoIndexField(fieldName, fieldType, metadata);
+			this._addIndexField("geo", name, fieldName);
+		}
+		if (metadata.has("db.encrypted")) {
+			this._validateEncryptedField(fieldName, metadata);
+			this.encryptedFields.add(fieldName);
+		}
 		const collate = metadata.get("db.column.collate");
 		if (collate) this._collateMap.set(fieldName, collate);
 		const hasExplicitIndex = metadata.has("db.index.plain") || metadata.has("db.index.unique") || metadata.has("db.index.fulltext");
@@ -268,6 +299,37 @@ var TableMetadata = class {
 			});
 		}
 	}
+	/**
+	* Build-time diagnostics for `@db.encrypted` (§6 of the field-encryption
+	* spec). Mirrors the compile-time AnnotationSpec validation so models built
+	* from pre-compiled types still fail fast.
+	*/
+	_validateEncryptedField(fieldName, metadata) {
+		const reject = (what, why) => {
+			throw new Error(`@db.encrypted on "${fieldName}" cannot coexist with ${what} — ${why}`);
+		};
+		if (metadata.has("meta.id")) reject("@meta.id", "the primary key must be addressable");
+		if (metadata.has("db.rel.FK")) reject("@db.rel.FK", "joins are impossible over ciphertext");
+		if (metadata.has("db.index.plain") || metadata.has("db.index.unique") || metadata.has("db.index.fulltext") || metadata.has("db.index.geo")) reject("@db.index.*", "indexes over ciphertext are meaningless");
+		if (metadata.has("db.search.vector") || metadata.has("db.search.filter")) reject("@db.search.*", "search over ciphertext is impossible");
+		if (metadata.has("db.mongo.search.text") || metadata.has("db.mongo.search.autocomplete")) reject("@db.mongo.search.*", "Atlas Search over ciphertext is impossible");
+		if (metadata.has("db.column.version")) reject("@db.column.version", "the OCC filter needs cleartext equality");
+		if (metadata.has("db.default.increment") || metadata.has("db.default.now")) reject("@db.default.increment / @db.default.now", "engine-side defaults bypass the encryption transform");
+		if (metadata.get("db.patch.strategy") === "merge") reject("@db.patch.strategy \"merge\"", "ciphertext is opaque — partial merges would silently drop omitted keys");
+	}
+	/** Build-time diagnostics for `@db.index.geo` (§3 of the geo-index spec). */
+	_validateGeoIndexField(fieldName, fieldType, metadata) {
+		const reject = (why) => {
+			throw new Error(`@db.index.geo on "${fieldName}": ${why}`);
+		};
+		if (!isGeoIndexableType(fieldType)) reject("the field type must resolve to db.geoPoint (a [lng, lat] number tuple)");
+		if (fieldName.includes(".")) reject("geo indexes are only supported on top-level fields in v1");
+		if (metadata.has("db.encrypted")) reject("@db.index.geo is mutually exclusive with @db.encrypted");
+		if (metadata.has("db.json")) reject("@db.index.geo is mutually exclusive with @db.json");
+		if (metadata.has("meta.id")) reject("geo fields cannot be part of the primary key");
+		if (metadata.has("db.index.unique")) reject("geo fields cannot be part of a unique index");
+		if (metadata.has("db.rel.FK")) reject("geo fields cannot be foreign keys");
+	}
 	_addIndexField(type, name, field, opts) {
 		const key = indexKey(type, name);
 		const index = this.indexes.get(key);
@@ -291,6 +353,7 @@ var TableMetadata = class {
 	_classifyFields() {
 		for (const [path, type] of this.flatMap.entries()) {
 			if (!path) continue;
+			if (this.encryptedFields.has(path) || findAncestorInSet(path, this.encryptedFields)) continue;
 			const designType = resolveDesignType(type);
 			const isJson = this.jsonFields.has(path);
 			const isArray = designType === "array";
@@ -307,6 +370,7 @@ var TableMetadata = class {
 			if (!path) continue;
 			if (this.flattenedParents.has(path)) continue;
 			if (findAncestorInSet(path, this.jsonFields) !== void 0) continue;
+			if (findAncestorInSet(path, this.encryptedFields) !== void 0) continue;
 			const isFlattened = findAncestorInSet(path, this.flattenedParents) !== void 0;
 			const columnOverride = this.columnMap.get(path);
 			let physicalName;
@@ -315,7 +379,7 @@ var TableMetadata = class {
 			this.pathToPhysical.set(path, physicalName);
 			this.physicalToPath.set(physicalName, path);
 			const fieldType = this.flatMap.get(path);
-			if (fieldType) {
+			if (fieldType && !this.encryptedFields.has(path)) {
 				const dt = resolveDesignType(fieldType);
 				if (dt === "boolean") this.booleanFields.add(physicalName);
 				else if (dt === "decimal") this.decimalFields.add(physicalName);
@@ -371,11 +435,15 @@ var TableMetadata = class {
 			if (!path) continue;
 			if (!skipFlattening && this.flattenedParents.has(path)) continue;
 			if (!skipFlattening && findAncestorInSet(path, this.jsonFields) !== void 0) continue;
+			const isEncrypted = this.encryptedFields.has(path);
+			const underEncrypted = findAncestorInSet(path, this.encryptedFields) !== void 0;
+			if (!skipFlattening && underEncrypted) continue;
 			const isJson = this.jsonFields.has(path);
 			const isFlattened = !skipFlattening && findAncestorInSet(path, this.flattenedParents) !== void 0;
-			const designType = isJson ? "json" : resolveDesignType(type);
+			const designType = isEncrypted ? "string" : isJson ? "json" : resolveDesignType(type);
 			let storage;
 			if (skipFlattening) storage = "column";
+			else if (isEncrypted) storage = isFlattened ? "flattened" : "column";
 			else if (isJson) storage = "json";
 			else if (isFlattened) storage = "flattened";
 			else storage = "column";
@@ -406,7 +474,9 @@ var TableMetadata = class {
 				currencyCode,
 				currencyRefField,
 				unitCode,
-				unitRefField
+				unitRefField,
+				encrypted: isEncrypted || underEncrypted || void 0,
+				isGeoPoint: isGeoPointType(type) || void 0
 			});
 		}
 		this._resolveFkTargetFields(descriptors);
@@ -458,6 +528,7 @@ var TableMetadata = class {
 			const targetFieldType = targetFlatMap.get(target.targetField);
 			if (!targetFieldType) continue;
 			const targetMetadata = targetFieldType.metadata;
+			if (targetMetadata?.has("db.encrypted")) throw new Error(`FK field "${descriptor.path}" references encrypted field "${target.targetField}" — joins are impossible over ciphertext`);
 			descriptor.fkTargetField = {
 				path: target.targetField,
 				type: targetFieldType,
@@ -749,7 +820,7 @@ var FieldMappingStrategy = class {
 		const fmt = meta.toStorageFormatters?.get(physicalName);
 		if (!fmt) return value;
 		if (value === null || value === void 0) return value;
-		if (typeof value !== "object") return fmt(value);
+		if (typeof value !== "object" || Array.isArray(value)) return fmt(value);
 		const ops = value;
 		const formatted = {};
 		for (const [op, opVal] of Object.entries(ops)) if ((op === "$in" || op === "$nin") && Array.isArray(opVal)) formatted[op] = opVal.map((v) => v === null || v === void 0 ? v : fmt(v));
@@ -1080,6 +1151,104 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 	}
 };
 //#endregion
+//#region src/query/query-guards.ts
+/**
+* Engine-agnostic query-time guards, applied in the core layer BEFORE filter
+* translation (field-encryption spec §6, geo-index spec §4.2):
+*
+* - filters referencing an `@db.encrypted` field (incl. nested paths into an
+*   encrypted object) → `ENC_FIELD_FILTER`
+* - `$sort` on an encrypted field → `ENC_FIELD_SORT`
+* - `$groupBy` / aggregate refs on an encrypted field → `ENC_FIELD_AGG`
+* - `$geoWithin` on a non-geoPoint field → `FILTER_TYPE_MISMATCH`
+* - `$geoWithin` with a malformed circle → `INVALID_QUERY`
+* - `$geoWithin` on an adapter without geo support → `GEO_NOT_SUPPORTED`
+*/
+/** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
+function assertGeoPoint(point, path) {
+	if (!(Array.isArray(point) && point.length === 2 && typeof point[0] === "number" && typeof point[1] === "number" && Number.isFinite(point[0]) && Number.isFinite(point[1]) && point[0] >= -180 && point[0] <= 180 && point[1] >= -90 && point[1] <= 90)) throw new DbError("INVALID_QUERY", [{
+		path,
+		message: `Invalid geo point at "${path}" — expected [lng, lat] with lng ∈ [-180, 180], lat ∈ [-90, 90]`
+	}]);
+}
+function isEncryptedRef(meta, field) {
+	return meta.encryptedFields.has(field) || findAncestorInSet(field, meta.encryptedFields) !== void 0;
+}
+function encryptedRefError(code, field, what) {
+	return new DbError(code, [{
+		path: field,
+		message: `Cannot ${what} encrypted field "${field}"`
+	}]);
+}
+function guardGeoWithin(meta, adapter, field, value) {
+	const fieldType = meta.flatMap?.get(field);
+	if (!fieldType || !isGeoPointType(fieldType)) throw new DbError("FILTER_TYPE_MISMATCH", [{
+		path: field,
+		message: `$geoWithin requires a db.geoPoint field; "${field}" is not one`
+	}]);
+	const circle = value;
+	if (typeof circle !== "object" || circle === null || Array.isArray(circle)) throw new DbError("INVALID_QUERY", [{
+		path: field,
+		message: "$geoWithin expects { center: [lng, lat], radius: meters }"
+	}]);
+	assertGeoPoint(circle.center, `${field}.$geoWithin.center`);
+	if (typeof circle.radius !== "number" || !Number.isFinite(circle.radius) || circle.radius <= 0) throw new DbError("INVALID_QUERY", [{
+		path: field,
+		message: "$geoWithin radius must be a positive number of meters"
+	}]);
+	if (!adapter.isGeoSearchable()) throw new DbError("GEO_NOT_SUPPORTED", [{
+		path: field,
+		message: "$geoWithin is not supported by this adapter"
+	}]);
+}
+/**
+* Walks a filter expression, rejecting encrypted-field references and
+* validating `$geoWithin` operator nodes.
+*/
+function guardFilter(meta, adapter, filter, encCode = "ENC_FIELD_FILTER") {
+	if (!filter || typeof filter !== "object") return;
+	const hasEncrypted = meta.encryptedFields.size > 0;
+	for (const [key, value] of Object.entries(filter)) {
+		if (key === "$and" || key === "$or") {
+			for (const child of value ?? []) guardFilter(meta, adapter, child, encCode);
+			continue;
+		}
+		if (key === "$not") {
+			guardFilter(meta, adapter, value, encCode);
+			continue;
+		}
+		if (key.startsWith("$")) continue;
+		if (hasEncrypted && isEncryptedRef(meta, key)) throw encryptedRefError(encCode, key, "filter on");
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+			for (const [op, opValue] of Object.entries(value)) if (op === "$geoWithin") guardGeoWithin(meta, adapter, key, opValue);
+		}
+	}
+}
+/** Rejects `$sort` keys referencing encrypted fields. */
+function guardSort(meta, sort) {
+	if (!sort || typeof sort !== "object" || meta.encryptedFields.size === 0) return;
+	for (const key of Object.keys(sort)) if (isEncryptedRef(meta, key)) throw encryptedRefError("ENC_FIELD_SORT", key, "sort by");
+}
+/** Shared read-path guard: filter + $sort. */
+function guardQuery(meta, adapter, query) {
+	if (!query) return;
+	guardFilter(meta, adapter, query.filter);
+	guardSort(meta, query.controls?.$sort);
+}
+/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+function guardAggregate(meta, adapter, query) {
+	guardFilter(meta, adapter, query.filter);
+	if (meta.encryptedFields.size === 0) return;
+	const controls = query.controls;
+	for (const field of controls.$groupBy ?? []) if (isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "group by");
+	if (controls.$select) for (const item of controls.$select) {
+		const field = typeof item === "string" ? item : item.$field;
+		if (field !== "*" && isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "aggregate over");
+	}
+	if (controls.$having) guardFilter(meta, adapter, controls.$having, "ENC_FIELD_AGG");
+	guardSort(meta, controls.$sort);
+}
+//#endregion
 //#region src/table/db-readable.ts
 /**
 * Resolves the design type from an annotated type.
@@ -1174,6 +1343,8 @@ var AtscriptDbReadable = class {
 	/** Strategy for mapping between logical field shapes and physical storage. */
 	_fieldMapper;
 	_writeTableResolver;
+	/** Encryption service for `@db.encrypted` fields — set by `DbSpace` from its options. */
+	_encryption;
 	_metaIdPhysical;
 	constructor(_type, adapter, logger = NoopLogger, _tableResolver) {
 		this._type = _type;
@@ -1195,9 +1366,21 @@ var AtscriptDbReadable = class {
 		this._fieldMapper = adapter.supportsNestedObjects() ? new DocumentFieldMapper() : new RelationalFieldMapper();
 		adapter.registerReadable(this, logger);
 	}
+	/**
+	* Sets the encryption service used for `@db.encrypted` fields.
+	* Called by `DbSpace` after table/view creation when the space was
+	* configured with an `encryption` options block.
+	*/
+	setEncryption(encryption) {
+		this._encryption = encryption;
+	}
 	/** Ensures metadata is built. Called before any metadata access. */
 	_ensureBuilt() {
 		if (!this._meta.isBuilt) this._meta.build(this.type, this.adapter, this.logger);
+		if (this._meta.encryptedFields.size > 0 && !this._encryption) throw new DbError("ENC_CONFIG_MISSING", [{
+			path: "",
+			message: `Table "${this.tableName}" declares @db.encrypted fields but the DbSpace has no encryption configuration — pass { encryption: { defaultKeyId, keys } } to the DbSpace options`
+		}]);
 	}
 	/**
 	* Built table metadata. Triggers a lazy build on first access — safe to call
@@ -1214,6 +1397,65 @@ var AtscriptDbReadable = class {
 			message: `Table "${this.tableName}" has no search indexes defined`
 		}]);
 	}
+	/** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
+	_guardQuery(query) {
+		guardQuery(this._meta, this.adapter, query);
+	}
+	_encryptedPathsCache;
+	/** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
+	get _encryptedPaths() {
+		return this._encryptedPathsCache ??= [...this._meta.encryptedFields].map((path) => {
+			const segments = path.split(".");
+			return {
+				path,
+				segments,
+				leaf: segments[segments.length - 1]
+			};
+		});
+	}
+	/**
+	* Walks all but the last of `segments` down from `root`, returning the
+	* object holding the leaf — or `undefined` when the path is unreachable
+	* (a missing, non-object, or array step). With `cloneParents`, every
+	* traversed object is shallow-cloned and re-linked so caller-shared
+	* nested objects are never mutated.
+	*/
+	_walkToLeafParent(root, segments, cloneParents) {
+		let parent = root;
+		for (let i = 0; i < segments.length - 1; i++) {
+			const next = parent[segments[i]];
+			if (next === null || typeof next !== "object" || Array.isArray(next)) return;
+			let child = next;
+			if (cloneParents) {
+				child = { ...child };
+				parent[segments[i]] = child;
+			}
+			parent = child;
+		}
+		return parent;
+	}
+	/**
+	* Decrypts `@db.encrypted` fields on reconstructed rows (in place).
+	* Non-envelope stored values follow the configured `onUnencrypted` policy.
+	*/
+	async _decryptRows(rows) {
+		const enc = this._encryption;
+		if (this._meta.encryptedFields.size === 0 || rows.length === 0 || !enc) return;
+		for (const row of rows) for (const { path, segments, leaf } of this._encryptedPaths) {
+			const parent = this._walkToLeafParent(row, segments, false);
+			if (!parent) continue;
+			const value = parent[leaf];
+			if (value === void 0 || value === null) continue;
+			if (enc.isEnvelope(value)) parent[leaf] = await enc.decrypt(value, {
+				table: this.tableName,
+				field: path
+			});
+			else if (enc.onUnencrypted === "error") throw new DbError("ENC_NOT_ENCRYPTED", [{
+				path,
+				message: `Field "${path}" on "${this.tableName}" holds a non-encrypted value while @db.encrypted is declared — set encryption.onUnencrypted: 'passthrough' to read legacy plaintext during a migration window`
+			}]);
+		}
+	}
 	/** Whether this readable is a view (overridden in AtscriptDbView). */
 	get isView() {
 		return false;
@@ -1412,11 +1654,13 @@ var AtscriptDbReadable = class {
 	*/
 	async findOne(query) {
 		this._ensureBuilt();
+		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translatedQuery = this._fieldMapper.translateQuery(query, this._meta);
 		const result = await this.adapter.findOne(translatedQuery);
 		if (!result) return null;
 		const row = this._fieldMapper.reconstructFromRead(result, this._meta);
+		await this._decryptRows([row]);
 		if (withRelations?.length) await this.loadRelations([row], withRelations);
 		return row;
 	}
@@ -1427,9 +1671,11 @@ var AtscriptDbReadable = class {
 	*/
 	async findMany(query) {
 		this._ensureBuilt();
+		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translatedQuery = this._fieldMapper.translateQuery(query, this._meta);
 		const rows = (await this.adapter.findMany(translatedQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
 	}
@@ -1442,6 +1688,7 @@ var AtscriptDbReadable = class {
 			filter: {},
 			controls: {}
 		};
+		this._guardQuery(query);
 		return this.adapter.count(this._fieldMapper.translateQuery(query, this._meta));
 	}
 	/**
@@ -1449,10 +1696,12 @@ var AtscriptDbReadable = class {
 	*/
 	async findManyWithCount(query) {
 		this._ensureBuilt();
+		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translated = this._fieldMapper.translateQuery(query, this._meta);
 		const result = await this.adapter.findManyWithCount(translated);
 		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
 			data: rows,
@@ -1508,6 +1757,7 @@ var AtscriptDbReadable = class {
 				}]);
 			}
 		}
+		guardAggregate(this._meta, this.adapter, query);
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => {
 			const mapped = {};
@@ -1541,9 +1791,11 @@ var AtscriptDbReadable = class {
 	async search(text, query, indexName) {
 		this._ensureBuilt();
 		this._ensureSearchable();
+		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translated = this._fieldMapper.translateQuery(query, this._meta);
 		const rows = (await this.adapter.search(text, translated, indexName)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
 	}
@@ -1553,10 +1805,12 @@ var AtscriptDbReadable = class {
 	async searchWithCount(text, query, indexName) {
 		this._ensureBuilt();
 		this._ensureSearchable();
+		this._guardQuery(query);
 		const withRelations = query.controls?.$with;
 		const translated = this._fieldMapper.translateQuery(query, this._meta);
 		const result = await this.adapter.searchWithCount(text, translated, indexName);
 		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
 			data: rows,
@@ -1577,9 +1831,11 @@ var AtscriptDbReadable = class {
 	async vectorSearch(vectorOrIndex, maybeVectorOrQuery, maybeQuery) {
 		const { vector, query, indexName } = this._resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery);
 		this._ensureBuilt();
+		this._guardQuery(query);
 		const withRelations = (query?.controls)?.$with;
 		const translated = this._fieldMapper.translateQuery(query || {}, this._meta);
 		const rows = (await this.adapter.vectorSearch(vector, translated, indexName)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return rows;
 	}
@@ -1593,10 +1849,12 @@ var AtscriptDbReadable = class {
 	async vectorSearchWithCount(vectorOrIndex, maybeVectorOrQuery, maybeQuery) {
 		const { vector, query, indexName } = this._resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery);
 		this._ensureBuilt();
+		this._guardQuery(query);
 		const withRelations = (query?.controls)?.$with;
 		const translated = this._fieldMapper.translateQuery(query || {}, this._meta);
 		const result = await this.adapter.vectorSearchWithCount(vector, translated, indexName);
 		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
 		if (withRelations?.length) await this.loadRelations(rows, withRelations);
 		return {
 			data: rows,
@@ -1616,6 +1874,96 @@ var AtscriptDbReadable = class {
 			indexName: vectorOrIndex
 		};
 	}
+	/** Whether the underlying adapter supports geospatial search. */
+	isGeoSearchable() {
+		return this.adapter.isGeoSearchable();
+	}
+	/**
+	* Distance-ranked geospatial search (mirrors {@link vectorSearch}).
+	* Results are sorted by distance ascending; each row carries a computed
+	* `$distance` field (meters from the query point). `$maxDistance` /
+	* `$minDistance` (meters) ride in `query.controls`; user `$sort` is rejected.
+	*
+	* Overloads:
+	* - `geoSearch(point, query?)` — uses the table's only geo index
+	* - `geoSearch(indexName, point, query?)` — targets a specific geo index
+	*/
+	async geoSearch(pointOrIndex, maybePointOrQuery, maybeQuery) {
+		const { point, query, indexName } = this._resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery);
+		const { translated, withRelations } = this._prepareGeoSearch(point, query, indexName);
+		const rows = (await this.adapter.geoSearch(point, translated, indexName)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return rows;
+	}
+	/**
+	* Distance-ranked geospatial search with count for paginated results.
+	*
+	* Overloads:
+	* - `geoSearchWithCount(point, query?)` — uses the table's only geo index
+	* - `geoSearchWithCount(indexName, point, query?)` — targets a specific geo index
+	*/
+	async geoSearchWithCount(pointOrIndex, maybePointOrQuery, maybeQuery) {
+		const { point, query, indexName } = this._resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery);
+		const { translated, withRelations } = this._prepareGeoSearch(point, query, indexName);
+		const result = await this.adapter.geoSearchWithCount(point, translated, indexName);
+		const rows = result.data.map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
+		await this._decryptRows(rows);
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return {
+			data: rows,
+			count: result.count
+		};
+	}
+	/** Resolves overloaded geo search arguments into canonical form. */
+	_resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery) {
+		if (Array.isArray(pointOrIndex)) return {
+			point: pointOrIndex,
+			query: maybePointOrQuery,
+			indexName: void 0
+		};
+		return {
+			point: maybePointOrQuery,
+			query: maybeQuery,
+			indexName: pointOrIndex
+		};
+	}
+	/** Shared geoSearch validation + query translation. */
+	_prepareGeoSearch(point, query, indexName) {
+		this._ensureBuilt();
+		if (!this.adapter.isGeoSearchable()) throw new DbError("GEO_NOT_SUPPORTED", [{
+			path: "",
+			message: `Geo search is not supported by the adapter behind table "${this.tableName}"`
+		}]);
+		const geoIndexes = [...this._meta.indexes.values()].filter((index) => index.type === "geo");
+		if (geoIndexes.length === 0) throw new DbError("GEO_INDEX_MISSING", [{
+			path: "",
+			message: `Table "${this.tableName}" declares no @db.index.geo — geoSearch requires a geo index`
+		}]);
+		if (indexName !== void 0 && !geoIndexes.some((index) => index.name === indexName)) throw new DbError("GEO_INDEX_MISSING", [{
+			path: indexName,
+			message: `Geo index "${indexName}" not found on table "${this.tableName}"`
+		}]);
+		assertGeoPoint(point, "$center");
+		const controls = query?.controls ?? {};
+		if (controls.$sort) throw new DbError("INVALID_QUERY", [{
+			path: "$sort",
+			message: "geoSearch results are distance-ordered — $sort is not allowed on this path"
+		}]);
+		for (const key of ["$maxDistance", "$minDistance"]) {
+			const v = controls[key];
+			if (v !== void 0 && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) throw new DbError("INVALID_QUERY", [{
+				path: key,
+				message: `${key} must be a non-negative number of meters`
+			}]);
+		}
+		this._guardQuery(query);
+		const withRelations = (query?.controls)?.$with;
+		return {
+			translated: this._fieldMapper.translateQuery(query || {}, this._meta),
+			withRelations
+		};
+	}
 	/**
 	* Finds a single record by any type-compatible identifier — primary key
 	* or single-field unique index.
@@ -1952,6 +2300,7 @@ var BaseDbAdapter = class {
 	* even when the field carries `@db.column.filterable`.
 	*/
 	canFilterField(fd) {
+		if (fd.encrypted) return false;
 		return fd.storage !== "json";
 	}
 	/**
@@ -1961,6 +2310,7 @@ var BaseDbAdapter = class {
 	* stays conservative even for adapters that technically support it.
 	*/
 	canSortField(fd) {
+		if (fd.encrypted || fd.isGeoPoint) return false;
 		return fd.storage !== "json";
 	}
 	/**
@@ -2037,6 +2387,10 @@ var BaseDbAdapter = class {
 		const existingNames = new Set(existing.filter((i) => i.name.startsWith(prefix)).map((i) => i.name));
 		const desiredNames = /* @__PURE__ */ new Set();
 		for (const index of this._table.indexes.values()) {
+			if (opts.warnUnsupportedTypes?.types.includes(index.type)) {
+				this.logger.warn(`[${opts.warnUnsupportedTypes.adapter}] ${index.type} index "${index.name}" declared but not supported by this adapter — skipped`);
+				continue;
+			}
 			if (opts.shouldSkipType?.(index.type)) continue;
 			desiredNames.add(index.key);
 			if (!existingNames.has(index.key)) await opts.createIndex(index);
@@ -2105,6 +2459,41 @@ var BaseDbAdapter = class {
 		throw new Error("Vector search not supported by this adapter");
 	}
 	/**
+	* Whether this adapter supports geospatial search (`geoSearch()` and the
+	* `$geoWithin` filter operator). Override in adapters that do (MongoDB in v1).
+	*/
+	isGeoSearchable() {
+		return false;
+	}
+	/**
+	* Distance-ranked geospatial search. Results sorted by distance ascending;
+	* each row carries a `$distance` field (meters from the query point).
+	* `$maxDistance` / `$minDistance` (meters) ride in `query.controls`.
+	*
+	* @param point - `[lng, lat]` query point (GeoJSON coordinate order).
+	* @param query - Filter, select, skip/limit, $maxDistance/$minDistance.
+	* @param indexName - Optional geo index to target (multi-geo documents).
+	*/
+	async geoSearch(_point, _query, _indexName) {
+		throw new DbError("GEO_NOT_SUPPORTED", [{
+			path: "",
+			message: "Geo search not supported by this adapter"
+		}]);
+	}
+	/**
+	* Distance-ranked geospatial search with count (for paginated results).
+	*
+	* @param point - `[lng, lat]` query point (GeoJSON coordinate order).
+	* @param query - Filter, select, skip/limit, $maxDistance/$minDistance.
+	* @param indexName - Optional geo index to target (multi-geo documents).
+	*/
+	async geoSearchWithCount(_point, _query, _indexName) {
+		throw new DbError("GEO_NOT_SUPPORTED", [{
+			path: "",
+			message: "Geo search not supported by this adapter"
+		}]);
+	}
+	/**
 	* Fetches records and total count in one call.
 	* Default: two parallel calls. Adapters may override for single-query optimization.
 	*/
@@ -2566,6 +2955,12 @@ function assertNoVersionWrites(data, versionColumn) {
 }
 //#endregion
 //#region src/table/db-table.ts
+/** Returns true when `value` is a plain object carrying any `$`-prefixed key (an operator object). */
+function _hasOperatorKeys(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	for (const key in value) if (key.startsWith("$")) return true;
+	return false;
+}
 /**
 * Generic database table abstraction driven by Atscript `@db.*` annotations.
 *
@@ -2673,6 +3068,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, items, ctx);
+			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await batchInsertNestedTo(host, items, maxDepth, depth);
 			const prepared = [];
@@ -2725,6 +3121,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, items, ctx);
+			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await batchReplaceNestedTo(host, items, maxDepth, depth);
 			await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver);
@@ -2786,6 +3183,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, cloned, ctx);
 			const originals = canNest ? cloned.map((p) => ({ ...p })) : [];
+			await this._encryptItems(cloned, "patch");
 			const host = this;
 			if (canNest) await batchPatchNestedTo(host, cloned, maxDepth, depth);
 			await this._integrity.validateForeignKeys(cloned, this._meta, this._fkLookupResolver, this._writeTableResolver, true);
@@ -2854,6 +3252,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	}
 	async updateMany(filter, data) {
 		this._ensureBuilt();
+		this._guardMutationFilter(filter);
 		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
 		const dataCopy = { ...data };
 		const versionColumn = this.versionColumn;
@@ -2862,6 +3261,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			message: "$cas is not supported on updateMany — use bulkUpdate with per-row $cas for version-locked batch updates"
 		}]);
 		if (versionColumn !== void 0) assertNoVersionWrites(dataCopy, versionColumn);
+		await this._encryptItems([dataCopy], "patch");
 		const update = decomposePatch(dataCopy, this);
 		const ops = separateFieldOps(update);
 		const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
@@ -2870,11 +3270,15 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	}
 	async replaceMany(filter, data) {
 		this._ensureBuilt();
+		this._guardMutationFilter(filter);
 		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver);
-		return enrichFkViolation(this._meta, () => this.adapter.replaceMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite({ ...data }, this._meta, this.adapter)));
+		const dataCopy = { ...data };
+		await this._encryptItems([dataCopy], "write");
+		return enrichFkViolation(this._meta, () => this.adapter.replaceMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite(dataCopy, this._meta, this.adapter)));
 	}
 	async deleteMany(filter) {
 		this._ensureBuilt();
+		this._guardMutationFilter(filter);
 		if (this._integrity.needsCascade(this._cascadeResolver)) return remapDeleteFkViolation(this.tableName, () => this.adapter.withTransaction(async () => {
 			await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
 			return this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta));
@@ -2895,6 +3299,37 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		this._ensureBuilt();
 		return this.adapter.ensureTable();
 	}
+	/** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
+	_guardMutationFilter(filter) {
+		guardFilter(this._meta, this.adapter, filter);
+	}
+	/**
+	* Encrypts `@db.encrypted` field values in place on (already validated)
+	* write payloads — between validation and `prepareForWrite`, so adapters
+	* only ever see envelope strings.
+	*
+	* Parent objects along an encrypted path are shallow-cloned before
+	* mutation so caller-shared nested objects are never modified.
+	*
+	* In `patch` mode, operator objects (`$inc`, `$insert`, …) targeting an
+	* encrypted field are rejected with `ENC_FIELD_PATCH_OP` — ciphertext is
+	* opaque; only plain re-assignment (which re-encrypts) is allowed.
+	*/
+	async _encryptItems(items, mode) {
+		const enc = this._encryption;
+		if (this._meta.encryptedFields.size === 0 || !enc) return;
+		for (const item of items) for (const { path, segments, leaf } of this._encryptedPaths) {
+			const parent = this._walkToLeafParent(item, segments, true);
+			if (!parent) continue;
+			const value = parent[leaf];
+			if (value === void 0 || value === null) continue;
+			if (mode === "patch" && _hasOperatorKeys(value)) throw new DbError("ENC_FIELD_PATCH_OP", [{
+				path,
+				message: `Operator patch ops are not allowed on encrypted field "${path}" — assign a plain value instead (it re-encrypts)`
+			}]);
+			parent[leaf] = await enc.encrypt(value);
+		}
+	}
 	/**
 	* Applies default values for fields that are missing from the payload.
 	* Defaults handled natively by the DB engine are skipped — the field stays
@@ -3214,4 +3649,4 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 	}
 };
 //#endregion
-export { ApplicationIntegrity as a, NativeIntegrity as c, RelationalFieldMapper as d, DocumentFieldMapper as f, NoopLogger as g, TableMetadata as h, decomposePatch as i, AtscriptDbReadable as l, UniquSelect as m, AtscriptDbTable as n, BaseDbAdapter as o, FieldMappingStrategy as p, assertNoVersionWrites as r, IntegrityStrategy as s, AtscriptDbView as t, resolveDesignType as u };
+export { NoopLogger as S, FieldMappingStrategy as _, ApplicationIntegrity as a, isGeoIndexableType as b, NativeIntegrity as c, assertGeoPoint as d, guardAggregate as f, DocumentFieldMapper as g, RelationalFieldMapper as h, decomposePatch as i, AtscriptDbReadable as l, guardQuery as m, AtscriptDbTable as n, BaseDbAdapter as o, guardFilter as p, assertNoVersionWrites as r, IntegrityStrategy as s, AtscriptDbView as t, resolveDesignType as u, UniquSelect as v, isGeoPointType as x, TableMetadata as y };