@atscript/db 0.1.103 → 0.1.104

package/dist/{db-view-GcbegVBD.cjs → db-view-Bw_hlrWw.cjs}

@@ -2,7 +2,7 @@ const require_db_error = require("./db-error-DXwEzmYJ.cjs");
 const require_agg = require("./agg.cjs");
 const require_nested_writer = require("./nested-writer-DoDhl3X3.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-f43UcYiY.cjs");
+const require_validator = require("./validator-BSk8lPH1.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let node_async_hooks = require("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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.DbError("INVALID_QUERY", [{
+		path: field,
+		message: "$geoWithin radius must be a positive number of meters"
+	}]);
+	if (!adapter.isGeoSearchable()) throw new require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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 require_db_error.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);
 			require_nested_writer.validateBatch(validator, items, ctx);
+			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await require_nested_writer.batchInsertNestedTo(host, items, maxDepth, depth);
 			const prepared = [];
@@ -2725,6 +3121,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			require_nested_writer.validateBatch(validator, items, ctx);
+			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await require_nested_writer.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);
 			require_nested_writer.validateBatch(validator, cloned, ctx);
 			const originals = canNest ? cloned.map((p) => ({ ...p })) : [];
+			await this._encryptItems(cloned, "patch");
 			const host = this;
 			if (canNest) await require_nested_writer.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 = require_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 require_nested_writer.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 require_nested_writer.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 require_nested_writer.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 require_db_error.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
@@ -3292,6 +3727,12 @@ Object.defineProperty(exports, "UniquSelect", {
 		return UniquSelect;
 	}
 });
+Object.defineProperty(exports, "assertGeoPoint", {
+	enumerable: true,
+	get: function() {
+		return assertGeoPoint;
+	}
+});
 Object.defineProperty(exports, "assertNoVersionWrites", {
 	enumerable: true,
 	get: function() {
@@ -3304,6 +3745,36 @@ Object.defineProperty(exports, "decomposePatch", {
 		return decomposePatch;
 	}
 });
+Object.defineProperty(exports, "guardAggregate", {
+	enumerable: true,
+	get: function() {
+		return guardAggregate;
+	}
+});
+Object.defineProperty(exports, "guardFilter", {
+	enumerable: true,
+	get: function() {
+		return guardFilter;
+	}
+});
+Object.defineProperty(exports, "guardQuery", {
+	enumerable: true,
+	get: function() {
+		return guardQuery;
+	}
+});
+Object.defineProperty(exports, "isGeoIndexableType", {
+	enumerable: true,
+	get: function() {
+		return isGeoIndexableType;
+	}
+});
+Object.defineProperty(exports, "isGeoPointType", {
+	enumerable: true,
+	get: function() {
+		return isGeoPointType;
+	}
+});
 Object.defineProperty(exports, "resolveDesignType", {
 	enumerable: true,
 	get: function() {