@atscript/db 0.1.38 → 0.1.40

package/dist/db-view-ZsoN91-q.mjs

@@ -0,0 +1,2970 @@
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, h as DbError, 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-Dmm1gbZV.mjs";
+import { resolveAlias } from "./agg.mjs";
+import { n as findRemoteFK, t as findFKForRelation } from "./relation-helpers-CLasawQq.mjs";
+import { isDbFieldOp, separateFieldOps } from "./ops.mjs";
+import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/logger.ts
+const NoopLogger = {
+	error: () => {},
+	warn: () => {},
+	log: () => {},
+	info: () => {},
+	debug: () => {}
+};
+//#endregion
+//#region src/table/table-metadata.ts
+const INDEX_PREFIX = "atscript__";
+function indexKey(type, name) {
+	return `${INDEX_PREFIX}${type}__${name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 117 - type.length - 2)}`;
+}
+/**
+* Finds the nearest ancestor of `path` that belongs to `set`.
+* Used by both the build pipeline (in `_classifyFields`) and
+* runtime reconstruction on the Readable.
+*/
+function findAncestorInSet(path, set) {
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+		const ancestor = path.slice(0, pos);
+		if (set.has(ancestor)) return ancestor;
+	}
+}
+/** Returns true if `metadata` indicates a navigation relation field. */
+function isNavRelation(metadata) {
+	return metadata.has("db.rel.to") || metadata.has("db.rel.from") || metadata.has("db.rel.via");
+}
+/**
+* Computed metadata for a database table or view.
+*
+* Contains all field metadata, physical mapping indexes, relation definitions,
+* and constraint information derived from Atscript annotations. Built lazily
+* on first access via {@link build}, then immutable.
+*
+* This class owns the build pipeline that was previously part of
+* `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
+* access to this class.
+*/
+var TableMetadata = class {
+	nestedObjects;
+	flatMap;
+	fieldDescriptors;
+	primaryKeys = [];
+	originalMetaIdFields = [];
+	indexes = /* @__PURE__ */ new Map();
+	foreignKeys = /* @__PURE__ */ new Map();
+	relations = /* @__PURE__ */ new Map();
+	navFields = /* @__PURE__ */ new Set();
+	ignoredFields = /* @__PURE__ */ new Set();
+	uniqueProps = /* @__PURE__ */ new Set();
+	defaults = /* @__PURE__ */ new Map();
+	columnMap = /* @__PURE__ */ new Map();
+	dimensions = [];
+	measures = [];
+	pathToPhysical = /* @__PURE__ */ new Map();
+	physicalToPath = /* @__PURE__ */ new Map();
+	flattenedParents = /* @__PURE__ */ new Set();
+	jsonFields = /* @__PURE__ */ new Set();
+	selectExpansion = /* @__PURE__ */ new Map();
+	booleanFields = /* @__PURE__ */ new Set();
+	decimalFields = /* @__PURE__ */ new Set();
+	allPhysicalFields = [];
+	requiresMappings = false;
+	toStorageFormatters;
+	fromStorageFormatters;
+	/** Leaf field descriptors indexed by physical column name (read path). */
+	leafByPhysical = /* @__PURE__ */ new Map();
+	/** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
+	leafByLogical = /* @__PURE__ */ new Map();
+	_built = false;
+	_collateMap = /* @__PURE__ */ new Map();
+	_columnFromMap = /* @__PURE__ */ new Map();
+	constructor(nestedObjects) {
+		this.nestedObjects = nestedObjects;
+	}
+	get isBuilt() {
+		return this._built;
+	}
+	/**
+	* Runs the full metadata compilation pipeline. Called once by
+	* `AtscriptDbReadable._ensureBuilt()` on first metadata access.
+	*
+	* Pipeline steps:
+	* 1. `adapter.onBeforeFlatten(type)` — adapter hook
+	* 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
+	* 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
+	* 4. Classify fields and build path maps (skipped for nested-objects adapters)
+	* 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
+	* 6. Build field descriptors (TDbFieldMeta[])
+	* 7. Build leaf field indexes (skipped for nested-objects adapters)
+	* 8. Finalize indexes (resolve field names to physical)
+	* 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
+	* 10. Build allPhysicalFields list
+	*/
+	build(type, adapter, logger) {
+		if (this._built) return;
+		adapter.onBeforeFlatten?.(type);
+		const collected = [];
+		this.flatMap = flattenAnnotatedType(type, {
+			topLevelArrayTag: adapter.getTopLevelArrayTag?.() ?? "db.__topLevelArray",
+			excludePhantomTypes: true,
+			onField: (path, fieldType, metadata) => {
+				if (isNavRelation(metadata)) this.navFields.add(path);
+				collected.push({
+					path,
+					type: fieldType,
+					metadata
+				});
+			}
+		});
+		for (const entry of collected) {
+			if (findAncestorInSet(entry.path, this.navFields) !== void 0) continue;
+			this._scanGenericAnnotations(entry.path, entry.type, entry.metadata, logger);
+			adapter.onFieldScanned?.(entry.path, entry.type, entry.metadata);
+		}
+		if (!this.nestedObjects) this._classifyFields();
+		const overrides = adapter.getMetadataOverrides?.(this);
+		if (overrides) this._applyOverrides(overrides);
+		this._buildFieldDescriptors(adapter);
+		if (!this.nestedObjects) this._buildLeafIndexes();
+		this._finalizeIndexes();
+		this._collateMap.clear();
+		this._columnFromMap.clear();
+		this.jsonFields.clear();
+		this._built = true;
+		adapter.onAfterFlatten?.();
+		if (this.nestedObjects && this.flatMap) {
+			for (const path of this.flatMap.keys()) if (path && !this.ignoredFields.has(path)) this.allPhysicalFields.push(path);
+		} else for (const physical of this.pathToPhysical.values()) this.allPhysicalFields.push(physical);
+	}
+	/**
+	* Applies adapter-provided metadata overrides atomically.
+	* Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
+	*/
+	_applyOverrides(overrides) {
+		if (overrides.injectFields) for (const { path, type } of overrides.injectFields) this.flatMap.set(path, type);
+		if (overrides.removePrimaryKeys) for (const field of overrides.removePrimaryKeys) {
+			const idx = this.primaryKeys.indexOf(field);
+			if (idx >= 0) this.primaryKeys.splice(idx, 1);
+		}
+		if (overrides.addPrimaryKeys) {
+			for (const field of overrides.addPrimaryKeys) if (!this.primaryKeys.includes(field)) this.primaryKeys.push(field);
+		}
+		if (overrides.addUniqueFields) for (const field of overrides.addUniqueFields) this.uniqueProps.add(field);
+	}
+	/**
+	* Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+	*/
+	_scanGenericAnnotations(fieldName, fieldType, metadata, logger) {
+		if (metadata.has("meta.id")) {
+			this.primaryKeys.push(fieldName);
+			this.originalMetaIdFields.push(fieldName);
+		}
+		const column = metadata.get("db.column");
+		if (column) this.columnMap.set(fieldName, column);
+		const columnFrom = metadata.get("db.column.renamed");
+		if (columnFrom) this._columnFromMap.set(fieldName, columnFrom);
+		const resolvedDefault = resolveDefaultFromMetadata(metadata);
+		if (resolvedDefault) this.defaults.set(fieldName, resolvedDefault);
+		if (metadata.has("db.ignore")) this.ignoredFields.add(fieldName);
+		if (isNavRelation(metadata)) {
+			this.navFields.add(fieldName);
+			this.ignoredFields.add(fieldName);
+			const direction = metadata.has("db.rel.to") ? "to" : metadata.has("db.rel.from") ? "from" : "via";
+			const raw = direction === "via" ? metadata.get("db.rel.via") : metadata.get(`db.rel.${direction}`);
+			const alias = raw === true || typeof raw === "function" ? void 0 : raw;
+			const isArr = fieldType.type.kind === "array";
+			const elementType = isArr ? fieldType.type.of : fieldType;
+			const resolveTarget = () => elementType?.ref?.type() ?? elementType;
+			this.relations.set(fieldName, {
+				direction,
+				alias,
+				targetType: resolveTarget,
+				isArray: isArr,
+				...direction === "via" ? { viaType: raw } : {}
+			});
+		}
+		if (metadata.has("db.rel.FK")) {
+			const raw = metadata.get("db.rel.FK");
+			const alias = raw === true ? void 0 : raw;
+			if (fieldType.ref) {
+				const refTarget = fieldType.ref.type();
+				const targetTable = refTarget?.metadata?.get("db.table") || refTarget?.id || "";
+				const targetField = fieldType.ref.field;
+				const key = alias || `__auto_${fieldName}`;
+				const existing = this.foreignKeys.get(key);
+				if (existing) {
+					existing.fields.push(fieldName);
+					existing.targetFields.push(targetField);
+				} else this.foreignKeys.set(key, {
+					fields: [fieldName],
+					targetTable,
+					targetFields: [targetField],
+					targetTypeRef: fieldType.ref.type,
+					alias
+				});
+			}
+		}
+		const onDelete = metadata.get("db.rel.onDelete");
+		const onUpdate = metadata.get("db.rel.onUpdate");
+		if (onDelete || onUpdate) {
+			for (const fk of this.foreignKeys.values()) if (fk.fields.includes(fieldName)) {
+				if (onDelete) fk.onDelete = onDelete;
+				if (onUpdate) fk.onUpdate = onUpdate;
+				break;
+			}
+		}
+		for (const index of metadata.get("db.index.plain") || []) {
+			const name = index === true ? fieldName : index?.name || fieldName;
+			const sort = (index === true ? void 0 : index?.sort) || "asc";
+			this._addIndexField("plain", name, fieldName, { sort });
+		}
+		for (const index of metadata.get("db.index.unique") || []) {
+			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
+			this._addIndexField("unique", name, fieldName);
+		}
+		for (const index of metadata.get("db.index.fulltext") || []) {
+			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
+			const weight = index !== true && typeof index === "object" ? index?.weight : void 0;
+			this._addIndexField("fulltext", name, fieldName, { weight });
+		}
+		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");
+		if (metadata.has("db.json")) {
+			this.jsonFields.add(fieldName);
+			if (hasExplicitIndex) logger.warn(`@db.index on a @db.json field "${fieldName}" — most databases cannot index into JSON columns`);
+		}
+		if (metadata.has("db.column.dimension")) {
+			this.dimensions.push(fieldName);
+			if (!hasExplicitIndex) this._addIndexField("plain", fieldName, fieldName);
+		}
+		if (metadata.has("db.column.measure")) this.measures.push(fieldName);
+	}
+	_addIndexField(type, name, field, opts) {
+		const key = indexKey(type, name);
+		const index = this.indexes.get(key);
+		const indexField = {
+			name: field,
+			sort: opts?.sort ?? "asc"
+		};
+		if (opts?.weight !== void 0) indexField.weight = opts.weight;
+		if (index) index.fields.push(indexField);
+		else this.indexes.set(key, {
+			key,
+			name,
+			type,
+			fields: [indexField]
+		});
+	}
+	/**
+	* Classifies each field as column, flattened, json, or parent-object.
+	* Builds the bidirectional pathToPhysical / physicalToPath maps.
+	*/
+	_classifyFields() {
+		for (const [path, type] of this.flatMap.entries()) {
+			if (!path) continue;
+			const designType = resolveDesignType(type);
+			const isJson = this.jsonFields.has(path);
+			const isArray = designType === "array";
+			const isObject = designType === "object";
+			if (isArray) this.jsonFields.add(path);
+			else if (isObject && isJson) {} else if (isObject && !isJson) this.flattenedParents.add(path);
+		}
+		for (const ignoredField of this.ignoredFields) if (this.flattenedParents.has(ignoredField)) {
+			const prefix = `${ignoredField}.`;
+			for (const path of this.flatMap.keys()) if (path.startsWith(prefix)) this.ignoredFields.add(path);
+		}
+		for (const parentPath of this.flattenedParents) if (this.columnMap.has(parentPath)) throw new Error(`@db.column cannot rename a flattened object field "${parentPath}" — apply @db.column to individual nested fields, or use @db.json to store as a single column`);
+		for (const [path] of this.flatMap.entries()) {
+			if (!path) continue;
+			if (this.flattenedParents.has(path)) continue;
+			if (findAncestorInSet(path, this.jsonFields) !== void 0) continue;
+			const isFlattened = findAncestorInSet(path, this.flattenedParents) !== void 0;
+			const columnOverride = this.columnMap.get(path);
+			let physicalName;
+			if (columnOverride) physicalName = isFlattened ? this._flattenedPrefix(path) + columnOverride : columnOverride;
+			else physicalName = isFlattened ? path.replace(/\./g, "__") : path;
+			this.pathToPhysical.set(path, physicalName);
+			this.physicalToPath.set(physicalName, path);
+			const fieldType = this.flatMap.get(path);
+			if (fieldType) {
+				const dt = resolveDesignType(fieldType);
+				if (dt === "boolean") this.booleanFields.add(physicalName);
+				else if (dt === "decimal") this.decimalFields.add(physicalName);
+			}
+		}
+		for (const parentPath of this.flattenedParents) {
+			const prefix = `${parentPath}.`;
+			const leaves = [];
+			for (const [path, physical] of this.pathToPhysical) if (path.startsWith(prefix)) leaves.push(physical);
+			if (leaves.length > 0) this.selectExpansion.set(parentPath, leaves);
+		}
+		this.requiresMappings = this.flattenedParents.size > 0 || this.jsonFields.size > 0;
+	}
+	/** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
+	_flattenedPrefix(path) {
+		const lastDot = path.lastIndexOf(".");
+		return lastDot >= 0 ? `${path.slice(0, lastDot).replace(/\./g, "__")}__` : "";
+	}
+	/**
+	* Indexes `fieldDescriptors` into two lookup maps for unified
+	* read/write field classification in the RelationalFieldMapper.
+	*/
+	_buildLeafIndexes() {
+		for (const fd of this.fieldDescriptors) {
+			if (fd.ignored) continue;
+			this.leafByPhysical.set(fd.physicalName, fd);
+			this.leafByLogical.set(fd.path, fd);
+		}
+	}
+	/**
+	* Builds field descriptors, physical-name lookup, and value formatters.
+	* Called once during build() — everything it needs
+	* (flatMap, indexes, columnMap, etc.) is already populated.
+	*/
+	_buildFieldDescriptors(adapter) {
+		const descriptors = [];
+		const skipFlattening = this.nestedObjects;
+		const indexedFields = /* @__PURE__ */ new Set();
+		for (const index of this.indexes.values()) for (const f of index.fields) indexedFields.add(f.name);
+		for (const [path, type] of this.flatMap.entries()) {
+			if (!path) continue;
+			if (!skipFlattening && this.flattenedParents.has(path)) continue;
+			if (!skipFlattening && findAncestorInSet(path, this.jsonFields) !== void 0) continue;
+			const isJson = this.jsonFields.has(path);
+			const isFlattened = !skipFlattening && findAncestorInSet(path, this.flattenedParents) !== void 0;
+			const designType = isJson ? "json" : resolveDesignType(type);
+			let storage;
+			if (skipFlattening) storage = "column";
+			else if (isJson) storage = "json";
+			else if (isFlattened) storage = "flattened";
+			else storage = "column";
+			const physicalName = skipFlattening ? this.columnMap.get(path) ?? path : this.pathToPhysical.get(path) ?? this.columnMap.get(path) ?? path;
+			const fromLocal = this._columnFromMap.get(path);
+			let renamedFrom;
+			if (fromLocal) renamedFrom = isFlattened ? this._flattenedPrefix(path) + fromLocal : fromLocal;
+			descriptors.push({
+				path,
+				type,
+				physicalName,
+				designType,
+				optional: type.optional === true,
+				isPrimaryKey: this.primaryKeys.includes(path),
+				ignored: this.ignoredFields.has(path),
+				defaultValue: this.defaults.get(path),
+				storage,
+				flattenedFrom: isFlattened ? path : void 0,
+				renamedFrom,
+				collate: this._collateMap.get(path),
+				isIndexed: indexedFields.has(path) || void 0
+			});
+		}
+		this._resolveFkTargetFields(descriptors);
+		const fmtHook = adapter.formatValue?.bind(adapter);
+		if (fmtHook) for (const fd of descriptors) {
+			const fmt = fmtHook(fd);
+			if (fmt) if (typeof fmt === "function") {
+				if (!this.toStorageFormatters) this.toStorageFormatters = /* @__PURE__ */ new Map();
+				this.toStorageFormatters.set(fd.physicalName, fmt);
+			} else {
+				if (fmt.toStorage) {
+					if (!this.toStorageFormatters) this.toStorageFormatters = /* @__PURE__ */ new Map();
+					this.toStorageFormatters.set(fd.physicalName, fmt.toStorage);
+				}
+				if (fmt.fromStorage) {
+					if (!this.fromStorageFormatters) this.fromStorageFormatters = /* @__PURE__ */ new Map();
+					this.fromStorageFormatters.set(fd.physicalName, fmt.fromStorage);
+				}
+			}
+		}
+		Object.freeze(descriptors);
+		this.fieldDescriptors = descriptors;
+	}
+	/**
+	* Resolves `fkTargetField` for FK fields in field descriptors.
+	*/
+	_resolveFkTargetFields(descriptors) {
+		if (this.foreignKeys.size === 0) return;
+		const fkFieldToTarget = /* @__PURE__ */ new Map();
+		for (const fk of this.foreignKeys.values()) {
+			if (!fk.targetTypeRef) continue;
+			for (let i = 0; i < fk.fields.length; i++) fkFieldToTarget.set(fk.fields[i], {
+				targetTypeRef: fk.targetTypeRef,
+				targetField: fk.targetFields[i]
+			});
+		}
+		if (fkFieldToTarget.size === 0) return;
+		const flatCache = /* @__PURE__ */ new Map();
+		for (const descriptor of descriptors) {
+			const target = fkFieldToTarget.get(descriptor.path);
+			if (!target) continue;
+			const targetType = target.targetTypeRef();
+			if (!targetType) continue;
+			let targetFlatMap = flatCache.get(targetType);
+			if (!targetFlatMap) {
+				targetFlatMap = flattenAnnotatedType(targetType);
+				flatCache.set(targetType, targetFlatMap);
+			}
+			const targetFieldType = targetFlatMap.get(target.targetField);
+			if (!targetFieldType) continue;
+			const targetMetadata = targetFieldType.metadata;
+			descriptor.fkTargetField = {
+				path: target.targetField,
+				type: targetFieldType,
+				physicalName: target.targetField,
+				designType: resolveDesignType(targetFieldType),
+				optional: false,
+				isPrimaryKey: targetMetadata?.has("meta.id") ?? false,
+				ignored: false,
+				storage: "column",
+				defaultValue: targetMetadata ? resolveDefaultFromMetadata(targetMetadata) : void 0,
+				collate: targetMetadata?.get("db.column.collate")
+			};
+		}
+	}
+	_finalizeIndexes() {
+		for (const index of this.indexes.values()) if (index.type === "unique" && index.fields.length === 1) this.uniqueProps.add(index.fields[0].name);
+		for (const index of this.indexes.values()) for (const field of index.fields) field.name = this.pathToPhysical.get(field.name) ?? this.columnMap.get(field.name) ?? field.name;
+	}
+};
+//#endregion
+//#region src/query/uniqu-select.ts
+/**
+* Wraps a raw `$select` value and provides lazy-cached conversions
+* to the forms different adapters need.
+*
+* Only instantiated when `$select` is actually provided —
+* `controls.$select` is `UniquSelect | undefined`.
+*
+* For exclusion → inclusion inversion, pass `allFields` (physical field names).
+*/
+var UniquSelect = class UniquSelect {
+	static UNRESOLVED = Symbol("unresolved");
+	_raw;
+	_allFields;
+	_array = UniquSelect.UNRESOLVED;
+	_projection = UniquSelect.UNRESOLVED;
+	_aggregates = UniquSelect.UNRESOLVED;
+	constructor(raw, allFields) {
+		this._raw = raw;
+		this._allFields = allFields;
+	}
+	/** Type guard: checks if a value is an AggregateExpr ({$fn, $field}). */
+	static _isAggregateExpr(v) {
+		return typeof v === "object" && v !== null && "$fn" in v && "$field" in v;
+	}
+	/**
+	* Resolved inclusion array of plain field names (strings only).
+	* AggregateExpr objects are filtered out.
+	* For exclusion form, inverts using `allFields` from constructor.
+	*/
+	get asArray() {
+		if (this._array !== UniquSelect.UNRESOLVED) return this._array;
+		if (Array.isArray(this._raw)) {
+			this._array = this._raw.filter((item) => typeof item === "string");
+			return this._array;
+		}
+		const raw = this._raw;
+		const entries = Object.entries(raw);
+		if (entries.length === 0) {
+			this._array = void 0;
+			return;
+		}
+		if (entries[0][1] === 1) this._array = entries.filter((e) => e[1] === 1).map((e) => e[0]);
+		else if (this._allFields) {
+			const excluded = new Set(entries.filter((e) => e[1] === 0).map((e) => e[0]));
+			this._array = this._allFields.filter((f) => !excluded.has(f));
+		} else this._array = void 0;
+		return this._array;
+	}
+	/**
+	* Record projection preserving original semantics.
+	* Returns original object as-is if raw was object.
+	* Converts `string[]` to `{field: 1}` inclusion object.
+	* AggregateExpr objects in array form are ignored.
+	*/
+	get asProjection() {
+		if (this._projection !== UniquSelect.UNRESOLVED) return this._projection;
+		if (!Array.isArray(this._raw)) {
+			const raw = this._raw;
+			this._projection = Object.keys(raw).length === 0 ? void 0 : raw;
+			return this._projection;
+		}
+		const strings = this.asArray;
+		if (!strings || strings.length === 0) {
+			this._projection = void 0;
+			return;
+		}
+		const result = {};
+		for (const item of strings) result[item] = 1;
+		this._projection = result;
+		return this._projection;
+	}
+	/**
+	* Extracts AggregateExpr entries from array-form $select.
+	* Returns undefined if no aggregates present or if $select is object form.
+	*/
+	get aggregates() {
+		if (this._aggregates !== UniquSelect.UNRESOLVED) return this._aggregates;
+		if (!Array.isArray(this._raw)) {
+			this._aggregates = void 0;
+			return;
+		}
+		const aggs = this._raw.filter((v) => UniquSelect._isAggregateExpr(v));
+		this._aggregates = aggs.length > 0 ? aggs : void 0;
+		return this._aggregates;
+	}
+	/** Whether the $select contains any AggregateExpr entries. */
+	get hasAggregates() {
+		return !!this.aggregates?.length;
+	}
+};
+//#endregion
+//#region src/strategies/field-mapping.ts
+/** Coerces a storage value (0/1/null) back to a JS boolean. */
+function toBool(value) {
+	if (value === null || value === void 0) return value;
+	return !!value;
+}
+function toDecimalString(value) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return value;
+	if (typeof value === "number") return String(value);
+	return value;
+}
+/**
+* Strategy for mapping data between logical field shapes and physical storage.
+* Two implementations: {@link DocumentFieldMapper} (nested objects, NoSQL)
+* and `RelationalFieldMapper` (flattened columns, SQL).
+*/
+var FieldMappingStrategy = class {
+	/**
+	* Recursively walks a filter expression, applying adapter-specific value
+	* formatting via `formatFilterValue`. Shared by both document and relational
+	* mappers (relational adds key-renaming via `translateFilterWithRename`).
+	*/
+	translateFilter(filter, meta) {
+		if (!filter || typeof filter !== "object") return filter;
+		if (!meta.toStorageFormatters) return filter;
+		const result = {};
+		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateFilter(f, meta));
+		else if (key === "$not") result[key] = this.translateFilter(value, meta);
+		else if (key.startsWith("$")) result[key] = value;
+		else result[key] = this.formatFilterValue(key, value, meta);
+		return result;
+	}
+	/**
+	* Coerces field values from storage representation to JS types
+	* (booleans from 0/1, decimals from number to string).
+	*/
+	coerceFieldValues(row, meta) {
+		if (meta.booleanFields.size === 0 && meta.decimalFields.size === 0) return row;
+		for (const field of meta.booleanFields) if (field in row) row[field] = toBool(row[field]);
+		for (const field of meta.decimalFields) if (field in row) row[field] = toDecimalString(row[field]);
+		return row;
+	}
+	/**
+	* Applies adapter-specific fromStorage formatting to a row read from the database.
+	* Converts storage representations back to JS values (e.g. Date → epoch ms).
+	*/
+	applyFromStorageFormatters(row, meta) {
+		if (!meta.fromStorageFormatters) return row;
+		for (const [col, fmt] of meta.fromStorageFormatters) {
+			const val = row[col];
+			if (val !== null && val !== void 0) row[col] = fmt(val);
+		}
+		return row;
+	}
+	/**
+	* Sets a value at a dot-notation path, creating intermediate objects as needed.
+	*/
+	setNestedValue(obj, dotPath, value) {
+		const parts = dotPath.split(".");
+		let current = obj;
+		for (let i = 0; i < parts.length - 1; i++) {
+			const part = parts[i];
+			if (current[part] === void 0 || current[part] === null) current[part] = {};
+			current = current[part];
+		}
+		current[parts[parts.length - 1]] = value;
+	}
+	/**
+	* If all children of a flattened parent are null, collapse the parent to null.
+	*/
+	reconstructNullParent(obj, parentPath, meta) {
+		const parts = parentPath.split(".");
+		let current = obj;
+		for (let i = 0; i < parts.length - 1; i++) {
+			if (current[parts[i]] === void 0) return;
+			current = current[parts[i]];
+		}
+		const lastPart = parts[parts.length - 1];
+		const parentObj = current[lastPart];
+		if (typeof parentObj !== "object" || parentObj === null) return;
+		let allNull = true;
+		const parentKeys = Object.keys(parentObj);
+		for (const k of parentKeys) {
+			const v = parentObj[k];
+			if (v !== null && v !== void 0) {
+				allNull = false;
+				break;
+			}
+		}
+		if (allNull) {
+			const parentType = meta.flatMap?.get(parentPath);
+			current[lastPart] = parentType?.optional ? null : {};
+		}
+	}
+	/**
+	* Applies adapter-specific value formatting to a single filter value.
+	* Handles direct values, operator objects ({$gt: v}), and $in/$nin arrays.
+	*/
+	formatFilterValue(physicalName, value, meta) {
+		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);
+		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));
+		else if (op.startsWith("$") && opVal !== null && opVal !== void 0) formatted[op] = fmt(opVal);
+		else formatted[op] = opVal;
+		return formatted;
+	}
+	/**
+	* Applies adapter-specific value formatting to prepared (physical-named) data.
+	*/
+	formatWriteValues(data, meta) {
+		if (!meta.toStorageFormatters) return data;
+		for (const [col, fmt] of meta.toStorageFormatters) {
+			const val = data[col];
+			if (val !== null && val !== void 0) data[col] = fmt(val);
+		}
+		return data;
+	}
+	/**
+	* Prepares primary key values and strips ignored fields.
+	* Shared pre-processing for both document and relational write paths.
+	*/
+	prepareCommon(data, meta, adapter) {
+		for (const pk of meta.primaryKeys) if (data[pk] !== void 0) {
+			const fieldType = meta.flatMap?.get(pk);
+			if (fieldType) data[pk] = adapter.prepareId(data[pk], fieldType);
+		}
+		for (const field of meta.ignoredFields) if (!field.includes(".")) delete data[field];
+	}
+};
+/**
+* Field mapper for document-oriented adapters (e.g. MongoDB).
+* Nested objects are preserved as-is. Only applies column renames and
+* value coercion.
+*/
+var DocumentFieldMapper = class extends FieldMappingStrategy {
+	reconstructFromRead(row, meta) {
+		return this.applyFromStorageFormatters(this.coerceFieldValues(row, meta), meta);
+	}
+	translateQuery(query, meta) {
+		const controls = query.controls;
+		return {
+			filter: meta.toStorageFormatters ? this.translateFilter(query.filter, meta) : query.filter,
+			controls: {
+				...controls,
+				$with: void 0,
+				$select: controls?.$select ? new UniquSelect(controls.$select, meta.allPhysicalFields) : void 0
+			},
+			insights: query.insights
+		};
+	}
+	translateAggregateQuery(query, meta) {
+		const controls = query.controls;
+		return {
+			filter: meta.toStorageFormatters ? this.translateFilter(query.filter, meta) : query.filter ?? {},
+			controls: {
+				...controls,
+				$with: void 0,
+				$select: controls.$select ? new UniquSelect(controls.$select, meta.allPhysicalFields) : void 0
+			},
+			insights: query.insights
+		};
+	}
+	prepareForWrite(payload, meta, adapter) {
+		const data = { ...payload };
+		this.prepareCommon(data, meta, adapter);
+		for (const [logical, physical] of meta.columnMap.entries()) if (logical in data) {
+			data[physical] = data[logical];
+			delete data[logical];
+		}
+		return this.formatWriteValues(data, meta);
+	}
+	translatePatchKeys(update, meta) {
+		return this.formatWriteValues(update, meta);
+	}
+};
+//#endregion
+//#region src/strategies/relational-field-mapper.ts
+/**
+* Field mapper for relational adapters (e.g. SQLite, MySQL).
+* Flattens nested objects to `__`-separated column names and
+* reconstructs them on read. Applies full physical-name translation
+* for queries, filters, and controls.
+*/
+var RelationalFieldMapper = class extends FieldMappingStrategy {
+	reconstructFromRead(row, meta) {
+		if (!meta.requiresMappings) return this.applyFromStorageFormatters(this.coerceFieldValues(row, meta), meta);
+		const result = {};
+		const fromFmts = meta.fromStorageFormatters;
+		for (const physical of Object.keys(row)) {
+			const fd = meta.leafByPhysical.get(physical);
+			if (!fd) {
+				result[physical] = row[physical];
+				continue;
+			}
+			let raw = row[physical];
+			const fromFmt = fromFmts?.get(physical);
+			if (fromFmt && raw !== null && raw !== void 0) raw = fromFmt(raw);
+			const value = fd.designType === "boolean" ? toBool(raw) : fd.designType === "decimal" ? toDecimalString(raw) : raw;
+			if (fd.storage === "json") this.setNestedValue(result, fd.path, typeof value === "string" ? JSON.parse(value) : value);
+			else if (fd.storage === "flattened") this.setNestedValue(result, fd.path, value);
+			else result[fd.path] = value;
+		}
+		for (const parentPath of meta.flattenedParents) this.reconstructNullParent(result, parentPath, meta);
+		return result;
+	}
+	translateQuery(query, meta) {
+		if (!meta.requiresMappings) {
+			const controls = query.controls;
+			return {
+				filter: meta.toStorageFormatters ? this.translateFilter(query.filter, meta) : query.filter,
+				controls: {
+					...controls,
+					$with: void 0,
+					$select: controls?.$select ? new UniquSelect(controls.$select, meta.allPhysicalFields) : void 0
+				},
+				insights: query.insights
+			};
+		}
+		return {
+			filter: this.translateFilterWithRename(query.filter, meta),
+			controls: query.controls ? this.translateControls(query.controls, meta) : {},
+			insights: query.insights
+		};
+	}
+	translateAggregateQuery(query, meta) {
+		const controls = query.controls;
+		const filter = meta.requiresMappings ? this.translateFilterWithRename(query.filter ?? {}, meta) : meta.toStorageFormatters ? this.translateFilter(query.filter ?? {}, meta) : query.filter ?? {};
+		const groupBy = controls.$groupBy.map((field) => meta.leafByLogical.get(field)?.physicalName ?? field);
+		let select;
+		if (controls.$select) select = controls.$select.map((item) => {
+			if (typeof item === "string") return meta.leafByLogical.get(item)?.physicalName ?? item;
+			if (item.$field === "*") return item;
+			return {
+				...item,
+				$field: meta.leafByLogical.get(item.$field)?.physicalName ?? item.$field
+			};
+		});
+		const aliases = /* @__PURE__ */ new Set();
+		if (controls.$select) {
+			for (const item of controls.$select) if (typeof item !== "string") aliases.add(resolveAlias(item));
+		}
+		let sort;
+		if (controls.$sort) {
+			const translated = {};
+			for (const [key, dir] of Object.entries(controls.$sort)) if (aliases.has(key)) translated[key] = dir;
+			else {
+				const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
+				translated[physical] = dir;
+			}
+			sort = translated;
+		}
+		let having;
+		if (controls.$having) having = meta.requiresMappings ? this.translateFilterWithRename(controls.$having, meta) : meta.toStorageFormatters ? this.translateFilter(controls.$having, meta) : controls.$having;
+		return {
+			filter,
+			controls: {
+				$groupBy: groupBy,
+				$select: select ? new UniquSelect(select, meta.allPhysicalFields) : void 0,
+				$sort: sort,
+				$having: having,
+				$skip: controls.$skip,
+				$limit: controls.$limit,
+				$count: controls.$count
+			},
+			insights: query.insights
+		};
+	}
+	/**
+	* Translates filter with key renaming from logical to physical names.
+	* Used by the relational query path where field paths must be mapped
+	* to `__`-separated column names.
+	*/
+	translateFilterWithRename(filter, meta) {
+		if (!filter || typeof filter !== "object") return filter;
+		const result = {};
+		for (const [key, value] of Object.entries(filter)) if (key === "$and" || key === "$or") result[key] = value.map((f) => this.translateFilterWithRename(f, meta));
+		else if (key === "$not") result[key] = this.translateFilterWithRename(value, meta);
+		else if (key.startsWith("$")) result[key] = value;
+		else {
+			const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
+			result[physical] = this.formatFilterValue(physical, value, meta);
+		}
+		return result;
+	}
+	prepareForWrite(payload, meta, adapter) {
+		const data = { ...payload };
+		this.prepareCommon(data, meta, adapter);
+		if (!meta.requiresMappings) {
+			for (const [logical, physical] of meta.columnMap.entries()) if (logical in data) {
+				data[physical] = data[logical];
+				delete data[logical];
+			}
+			return this.formatWriteValues(data, meta);
+		}
+		return this.formatWriteValues(this.flattenPayload(data, meta), meta);
+	}
+	translatePatchKeys(update, meta) {
+		if (!meta.requiresMappings && !meta.toStorageFormatters) return update;
+		const result = {};
+		const updateKeys = Object.keys(update);
+		for (const key of updateKeys) {
+			const value = update[key];
+			const operatorMatch = key.match(/^(.+?)(\.__\$.+)$/);
+			const basePath = operatorMatch ? operatorMatch[1] : key;
+			const suffix = operatorMatch ? operatorMatch[2] : "";
+			const fd = meta.leafByLogical.get(basePath);
+			const finalKey = (fd?.physicalName ?? basePath) + suffix;
+			if (fd?.storage === "json" && typeof value === "object" && value !== null && !suffix) result[finalKey] = JSON.stringify(value);
+			else result[finalKey] = value;
+		}
+		return this.formatWriteValues(result, meta);
+	}
+	/**
+	* Translates field names in sort and projection controls from
+	* logical dot-paths to physical column names.
+	*/
+	translateControls(controls, meta) {
+		if (!controls) return {};
+		const result = {
+			...controls,
+			$select: void 0,
+			$with: void 0
+		};
+		if (controls.$sort) {
+			const translated = {};
+			const sortObj = controls.$sort;
+			const sortKeys = Object.keys(sortObj);
+			for (const key of sortKeys) {
+				if (meta.flattenedParents.has(key)) continue;
+				const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
+				translated[physical] = sortObj[key];
+			}
+			result.$sort = translated;
+		}
+		if (controls.$select) {
+			let translatedRaw;
+			if (Array.isArray(controls.$select)) {
+				const expanded = [];
+				for (const key of controls.$select) {
+					const expansion = meta.selectExpansion.get(key);
+					if (expansion) expanded.push(...expansion);
+					else expanded.push(meta.leafByLogical.get(key)?.physicalName ?? key);
+				}
+				translatedRaw = expanded;
+			} else {
+				const translated = {};
+				const selectObj = controls.$select;
+				const selectKeys = Object.keys(selectObj);
+				for (const key of selectKeys) {
+					const val = selectObj[key];
+					const expansion = meta.selectExpansion.get(key);
+					if (expansion) for (const leaf of expansion) translated[leaf] = val;
+					else {
+						const physical = meta.leafByLogical.get(key)?.physicalName ?? key;
+						translated[physical] = val;
+					}
+				}
+				translatedRaw = translated;
+			}
+			result.$select = new UniquSelect(translatedRaw, meta.allPhysicalFields);
+		}
+		return result;
+	}
+	/**
+	* Flattens nested object fields into __-separated keys and
+	* JSON-stringifies @db.json / array fields.
+	*/
+	flattenPayload(data, meta) {
+		const result = {};
+		for (const key of Object.keys(data)) this.writeFlattenedField(key, data[key], result, meta);
+		return result;
+	}
+	/**
+	* Classifies and writes a single field to the result object.
+	* Recurses into nested objects that should be flattened.
+	*/
+	writeFlattenedField(path, value, result, meta) {
+		if (meta.ignoredFields.has(path)) return;
+		if (meta.flattenedParents.has(path)) {
+			if (value === null || value === void 0) this.setFlattenedChildrenNull(path, result, meta);
+			else if (typeof value === "object" && !Array.isArray(value)) {
+				const obj = value;
+				for (const key of Object.keys(obj)) this.writeFlattenedField(`${path}.${key}`, obj[key], result, meta);
+			}
+		} else {
+			const fd = meta.leafByLogical.get(path);
+			const physical = fd?.physicalName ?? path.replace(/\./g, "__");
+			if (fd?.storage === "json") result[physical] = value !== void 0 && value !== null ? JSON.stringify(value) : value;
+			else result[physical] = value;
+		}
+	}
+	/**
+	* When a parent object is null/undefined, set all its flattened children to null.
+	*/
+	setFlattenedChildrenNull(parentPath, result, meta) {
+		const prefix = `${parentPath}.`;
+		for (const [path, fd] of meta.leafByLogical.entries()) if (path.startsWith(prefix)) result[fd.physicalName] = null;
+	}
+};
+//#endregion
+//#region src/table/db-readable.ts
+/**
+* Resolves the design type from an annotated type.
+* Encapsulates the `kind === ''` check and fallback logic that
+* otherwise trips up every adapter author.
+*
+* For union types (e.g., from flattened `{...} | {...}` objects):
+* - If all members resolve to the same type → returns that type (strong type)
+* - If members disagree → returns `'union'` (out of scope for type management)
+*/
+function resolveDesignType(fieldType) {
+	if (fieldType.type.kind === "") return fieldType.type.designType ?? "string";
+	if (fieldType.type.kind === "object") return "object";
+	if (fieldType.type.kind === "array") return "array";
+	if (fieldType.type.kind === "union") {
+		const items = fieldType.type.items;
+		if (items.length > 0) {
+			const resolved = items.map((item) => resolveDesignType(item));
+			if (resolved.every((type) => type === resolved[0])) return resolved[0];
+		}
+		return "union";
+	}
+	return "string";
+}
+/**
+* Resolves `@db.default.*` annotations from a metadata map into a {@link TDbDefaultValue}.
+* Used both during normal field descriptor construction and for FK target field resolution.
+*/
+function resolveDefaultFromMetadata(metadata) {
+	const defaultValue = metadata.get("db.default");
+	if (defaultValue !== void 0) return {
+		kind: "value",
+		value: defaultValue
+	};
+	if (metadata.has("db.default.increment")) {
+		const startValue = metadata.get("db.default.increment");
+		return {
+			kind: "fn",
+			fn: "increment",
+			start: typeof startValue === "number" ? startValue : void 0
+		};
+	}
+	if (metadata.has("db.default.uuid")) return {
+		kind: "fn",
+		fn: "uuid"
+	};
+	if (metadata.has("db.default.now")) return {
+		kind: "fn",
+		fn: "now"
+	};
+}
+/**
+* Checks whether an id value is type-compatible with a field's design type.
+* Used by `findById` to skip primary-key lookup when the id clearly can't match,
+* falling through to unique-property search instead.
+*/
+function isIdCompatible(id, fieldType) {
+	switch (resolveDesignType(fieldType)) {
+		case "number":
+			if (typeof id === "number") return true;
+			if (typeof id === "string") return id !== "" && !Number.isNaN(Number(id));
+			return false;
+		case "boolean": return typeof id === "boolean";
+		case "object":
+		case "array": return typeof id === "object" && id !== null;
+		default: return typeof id === "string";
+	}
+}
+/**
+* Shared read-only database abstraction driven by Atscript annotations.
+*
+* Contains all field metadata computation, read operations, query translation,
+* relation loading, and result reconstruction. Extended by both
+* {@link AtscriptDbTable} (adds write operations) and {@link AtscriptDbView}
+* (adds view plan/DDL).
+*/
+var AtscriptDbReadable = class {
+	/** Resolved table/collection/view name. */
+	tableName;
+	/** Database schema/namespace from `@db.schema` (if set). */
+	schema;
+	/** Sync method from `@db.sync.method` ('drop' | 'recreate' | undefined). */
+	_syncMethod;
+	/** Previous table/view name from `@db.table.renamed` or `@db.view.renamed`. */
+	renamedFrom;
+	/** Computed metadata for this table/view. Built lazily on first access. */
+	_meta;
+	/** Strategy for mapping between logical field shapes and physical storage. */
+	_fieldMapper;
+	_writeTableResolver;
+	constructor(_type, adapter, logger = NoopLogger, _tableResolver) {
+		this._type = _type;
+		this.adapter = adapter;
+		this.logger = logger;
+		this._tableResolver = _tableResolver;
+		if (!isAnnotatedType(_type)) throw new Error("Atscript Annotated Type expected");
+		if (_type.type.kind !== "object") throw new Error("Database type must be an object type");
+		const adapterName = adapter.getAdapterTableName?.(_type);
+		const dbTable = _type.metadata.get("db.table");
+		const dbViewName = _type.metadata.get("db.view");
+		const fallbackName = _type.id || "";
+		this.tableName = adapterName || dbTable || dbViewName || fallbackName;
+		if (!this.tableName) throw new Error("@db.table or @db.view annotation expected");
+		this.schema = _type.metadata.get("db.schema");
+		this._syncMethod = _type.metadata.get("db.sync.method");
+		this.renamedFrom = _type.metadata.get("db.table.renamed") ?? _type.metadata.get("db.view.renamed");
+		this._meta = new TableMetadata(adapter.supportsNestedObjects());
+		this._fieldMapper = adapter.supportsNestedObjects() ? new DocumentFieldMapper() : new RelationalFieldMapper();
+		adapter.registerReadable(this, logger);
+	}
+	/** Ensures metadata is built. Called before any metadata access. */
+	_ensureBuilt() {
+		if (!this._meta.isBuilt) this._meta.build(this.type, this.adapter, this.logger);
+	}
+	/** Whether this readable is a view (overridden in AtscriptDbView). */
+	get isView() {
+		return false;
+	}
+	/** Returns the underlying adapter with its concrete type preserved. */
+	getAdapter() {
+		return this.adapter;
+	}
+	/** The raw annotated type. */
+	get type() {
+		return this._type;
+	}
+	/** Lazily-built flat map of all fields (dot-notation paths → annotated types). */
+	get flatMap() {
+		this._ensureBuilt();
+		return this._meta.flatMap;
+	}
+	/** All computed indexes from `@db.index.*` annotations. */
+	get indexes() {
+		this._ensureBuilt();
+		return this._meta.indexes;
+	}
+	/** Primary key field names from `@meta.id`. */
+	get primaryKeys() {
+		this._ensureBuilt();
+		return this._meta.primaryKeys;
+	}
+	/** Original `@meta.id` field names as declared in the schema (before adapter manipulation). */
+	get originalMetaIdFields() {
+		this._ensureBuilt();
+		return this._meta.originalMetaIdFields;
+	}
+	/** Dimension fields from `@db.column.dimension`. */
+	get dimensions() {
+		this._ensureBuilt();
+		return this._meta.dimensions;
+	}
+	/** Measure fields from `@db.column.measure`. */
+	get measures() {
+		this._ensureBuilt();
+		return this._meta.measures;
+	}
+	/** Sync method for structural changes: 'drop' (lossy), 'recreate' (lossless), or undefined (manual). */
+	get syncMethod() {
+		return this._syncMethod;
+	}
+	/** Logical → physical column name mapping from `@db.column`. */
+	get columnMap() {
+		this._ensureBuilt();
+		return this._meta.columnMap;
+	}
+	/** Default values from `@db.default.*`. */
+	get defaults() {
+		this._ensureBuilt();
+		return this._meta.defaults;
+	}
+	/** Fields excluded from DB via `@db.ignore`. */
+	get ignoredFields() {
+		this._ensureBuilt();
+		return this._meta.ignoredFields;
+	}
+	/** Navigational fields (`@db.rel.to` / `@db.rel.from`) — not stored as columns. */
+	get navFields() {
+		this._ensureBuilt();
+		return this._meta.navFields;
+	}
+	/** Single-field unique index properties. */
+	get uniqueProps() {
+		this._ensureBuilt();
+		return this._meta.uniqueProps;
+	}
+	/** Foreign key constraints from `@db.rel.FK` annotations. */
+	get foreignKeys() {
+		this._ensureBuilt();
+		return this._meta.foreignKeys;
+	}
+	/** Navigational relation metadata from `@db.rel.to` / `@db.rel.from`. */
+	get relations() {
+		this._ensureBuilt();
+		return this._meta.relations;
+	}
+	/** The underlying database adapter instance. */
+	get dbAdapter() {
+		return this.adapter;
+	}
+	/**
+	* Enables or disables verbose (debug-level) DB call logging for this table/view.
+	* When disabled (default), no log strings are constructed — zero overhead.
+	*/
+	setVerbose(enabled) {
+		this.adapter.setVerbose(enabled);
+	}
+	/** Precomputed logical dot-path → physical column name map. */
+	get pathToPhysical() {
+		this._ensureBuilt();
+		return this._meta.pathToPhysical;
+	}
+	/** Precomputed physical column name → logical dot-path map (inverse). */
+	get physicalToPath() {
+		this._ensureBuilt();
+		return this._meta.physicalToPath;
+	}
+	/** Descriptor for the primary ID field(s). */
+	getIdDescriptor() {
+		this._ensureBuilt();
+		return {
+			fields: [...this._meta.primaryKeys],
+			isComposite: this._meta.primaryKeys.length > 1
+		};
+	}
+	/**
+	* Pre-computed field metadata for adapter use.
+	*/
+	get fieldDescriptors() {
+		this._ensureBuilt();
+		return this._meta.fieldDescriptors;
+	}
+	/**
+	* Creates a new validator with custom options.
+	*/
+	createValidator(opts) {
+		return this._type.validator(opts);
+	}
+	/**
+	* Finds a single record matching the query.
+	* The return type automatically excludes nav props unless they are
+	* explicitly requested via `$with`.
+	*/
+	async findOne(query) {
+		this._ensureBuilt();
+		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);
+		if (withRelations?.length) await this.loadRelations([row], withRelations);
+		return row;
+	}
+	/**
+	* Finds all records matching the query.
+	* The return type automatically excludes nav props unless they are
+	* explicitly requested via `$with`.
+	*/
+	async findMany(query) {
+		this._ensureBuilt();
+		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));
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return rows;
+	}
+	/**
+	* Counts records matching the query.
+	*/
+	async count(query) {
+		this._ensureBuilt();
+		query ??= {
+			filter: {},
+			controls: {}
+		};
+		return this.adapter.count(this._fieldMapper.translateQuery(query, this._meta));
+	}
+	/**
+	* Finds records and total count in a single logical call.
+	*/
+	async findManyWithCount(query) {
+		this._ensureBuilt();
+		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));
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return {
+			data: rows,
+			count: result.count
+		};
+	}
+	/**
+	* Executes an aggregate query with GROUP BY and aggregate functions.
+	*
+	* Validates:
+	* - Plain fields in $select are a subset of $groupBy
+	* - When dimensions/measures are defined (strict mode): $groupBy fields
+	*   must be dimensions, aggregate $field values must be measures (or '*')
+	*
+	* Translates field names, delegates to adapter.aggregate(),
+	* then reverse-maps and applies fromStorage formatters on results.
+	*/
+	async aggregate(query) {
+		this._ensureBuilt();
+		const { $groupBy, $select } = query.controls;
+		if ($select) {
+			const groupBySet = new Set($groupBy);
+			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new DbError("INVALID_QUERY", [{
+				path: "$select",
+				message: `Plain field "${item}" in $select must also appear in $groupBy`
+			}]);
+		}
+		const { dimensions, measures } = this._meta;
+		if (dimensions.length > 0 || measures.length > 0) {
+			const dimSet = new Set(dimensions);
+			const measSet = new Set(measures);
+			for (const field of $groupBy) if (!dimSet.has(field)) throw new DbError("INVALID_QUERY", [{
+				path: "$groupBy",
+				message: `Field "${field}" is not a dimension`
+			}]);
+			if ($select) {
+				for (const item of $select) if (typeof item !== "string" && item.$field !== "*" && !measSet.has(item.$field)) throw new DbError("INVALID_QUERY", [{
+					path: "$select",
+					message: `Aggregate field "${item.$field}" is not a measure`
+				}]);
+			}
+		}
+		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
+		return (await this.adapter.aggregate(dbQuery)).map((row) => {
+			const mapped = {};
+			for (const [key, value] of Object.entries(row)) {
+				const logical = this._meta.physicalToPath.get(key) ?? key;
+				const fmt = this._meta.fromStorageFormatters?.get(key);
+				mapped[logical] = fmt && value !== null && value !== void 0 ? fmt(value) : value;
+			}
+			return mapped;
+		});
+	}
+	/** Whether the underlying adapter supports text search. */
+	isSearchable() {
+		return this.adapter.isSearchable();
+	}
+	/** Returns available search indexes from the adapter. */
+	getSearchIndexes() {
+		return this.adapter.getSearchIndexes();
+	}
+	/**
+	* Full-text search with query translation and result reconstruction.
+	*/
+	async search(text, query, indexName) {
+		this._ensureBuilt();
+		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));
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return rows;
+	}
+	/**
+	* Full-text search with count for paginated search results.
+	*/
+	async searchWithCount(text, query, indexName) {
+		this._ensureBuilt();
+		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));
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return {
+			data: rows,
+			count: result.count
+		};
+	}
+	/** Whether the underlying adapter supports vector similarity search. */
+	isVectorSearchable() {
+		return this.adapter.isVectorSearchable();
+	}
+	/**
+	* Vector similarity search with query translation and result reconstruction.
+	*
+	* Overloads:
+	* - `vectorSearch(vector, query?)` — uses default vector index
+	* - `vectorSearch(indexName, vector, query?)` — targets a specific vector index
+	*/
+	async vectorSearch(vectorOrIndex, maybeVectorOrQuery, maybeQuery) {
+		const { vector, query, indexName } = this._resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery);
+		this._ensureBuilt();
+		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));
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return rows;
+	}
+	/**
+	* Vector similarity search with count for paginated results.
+	*
+	* Overloads:
+	* - `vectorSearchWithCount(vector, query?)` — uses default vector index
+	* - `vectorSearchWithCount(indexName, vector, query?)` — targets a specific vector index
+	*/
+	async vectorSearchWithCount(vectorOrIndex, maybeVectorOrQuery, maybeQuery) {
+		const { vector, query, indexName } = this._resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery);
+		this._ensureBuilt();
+		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));
+		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		return {
+			data: rows,
+			count: result.count
+		};
+	}
+	/** Resolves overloaded vector search arguments into canonical form. */
+	_resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery) {
+		if (Array.isArray(vectorOrIndex)) return {
+			vector: vectorOrIndex,
+			query: maybeVectorOrQuery,
+			indexName: void 0
+		};
+		return {
+			vector: maybeVectorOrQuery,
+			query: maybeQuery,
+			indexName: vectorOrIndex
+		};
+	}
+	/**
+	* Finds a single record by any type-compatible identifier — primary key
+	* or single-field unique index.
+	* The return type excludes nav props unless `$with` is provided in controls.
+	*
+	* ```typescript
+	* // Without relations — nav props stripped from result
+	* const user = await table.findById('123')
+	*
+	* // With relations — only requested nav props appear
+	* const user = await table.findById('123', { controls: { $with: [{ name: 'posts' }] } })
+	* ```
+	*/
+	async findById(id, query) {
+		this._ensureBuilt();
+		const filter = this._resolveIdFilter(id);
+		if (!filter) return null;
+		return await this.findOne({
+			filter,
+			controls: query?.controls || {}
+		});
+	}
+	/**
+	* Resolves an id value into a filter expression.
+	*/
+	_resolveIdFilter(id) {
+		const orFilters = [];
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 1) {
+			const filter = this._tryFieldFilter(pkFields[0], id);
+			if (filter) orFilters.push(filter);
+		} else if (pkFields.length > 1 && typeof id === "object" && id !== null) {
+			const idObj = id;
+			const compositeFilter = {};
+			let valid = true;
+			for (const field of pkFields) {
+				const fieldType = this.flatMap.get(field);
+				if (fieldType && !isIdCompatible(idObj[field], fieldType)) {
+					valid = false;
+					break;
+				}
+				try {
+					compositeFilter[field] = fieldType ? this.adapter.prepareId(idObj[field], fieldType) : idObj[field];
+				} catch {
+					valid = false;
+					break;
+				}
+			}
+			if (valid) orFilters.push(compositeFilter);
+		}
+		for (const prop of this.uniqueProps) {
+			const filter = this._tryFieldFilter(prop, id);
+			if (filter) orFilters.push(filter);
+		}
+		if (typeof id === "object" && id !== null && orFilters.length === 0) {
+			const idObj = id;
+			for (const index of this._meta.indexes.values()) {
+				if (index.type !== "unique" || index.fields.length < 2) continue;
+				const compoundFilter = {};
+				let valid = true;
+				for (const indexField of index.fields) {
+					const fieldName = indexField.name;
+					if (idObj[fieldName] === void 0) {
+						valid = false;
+						break;
+					}
+					const fieldType = this.flatMap.get(fieldName);
+					if (fieldType && !isIdCompatible(idObj[fieldName], fieldType)) {
+						valid = false;
+						break;
+					}
+					try {
+						compoundFilter[fieldName] = fieldType ? this.adapter.prepareId(idObj[fieldName], fieldType) : idObj[fieldName];
+					} catch {
+						valid = false;
+						break;
+					}
+				}
+				if (valid) orFilters.push(compoundFilter);
+			}
+		}
+		if (orFilters.length === 0) return null;
+		if (orFilters.length === 1) return orFilters[0];
+		return { $or: orFilters };
+	}
+	/**
+	* Attempts to build a single-field filter `{ field: preparedId }`.
+	*/
+	_tryFieldFilter(field, id) {
+		const fieldType = this.flatMap.get(field);
+		if (fieldType && !isIdCompatible(id, fieldType)) return null;
+		try {
+			const prepared = fieldType ? this.adapter.prepareId(id, fieldType) : id;
+			return { [field]: prepared };
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Public entry point for relation loading. Used by adapters for nested $with delegation.
+	*/
+	async loadRelations(rows, withRelations) {
+		const { loadRelationsImpl } = await import("./relation-loader-BEOTXNcq.mjs").then((n) => n.n);
+		return loadRelationsImpl(rows, withRelations, this);
+	}
+	/**
+	* Finds the FK entry that connects a `@db.rel.to` relation to its target.
+	* Thin wrapper — delegates to relation-loader for shared use with db-table.ts write path.
+	*/
+	_findFKForRelation(relation) {
+		return findFKForRelation(relation, this._meta.foreignKeys);
+	}
+	/**
+	* Finds a FK on a remote table that points back to this table.
+	* Thin wrapper — delegates to relation-loader for shared use with db-table.ts write path.
+	*/
+	_findRemoteFK(targetTable, thisTableName, alias) {
+		return findRemoteFK(targetTable, thisTableName, alias);
+	}
+};
+//#endregion
+//#region src/strategies/integrity.ts
+/**
+* Strategy for referential integrity enforcement.
+* Two implementations: {@link NativeIntegrity} (DB handles FK constraints)
+* and `ApplicationIntegrity` (generic layer validates + cascades).
+*/
+var IntegrityStrategy = class {};
+/**
+* Integrity strategy for adapters with native FK support (e.g. SQLite, MySQL).
+* All operations are no-ops — the database engine enforces constraints.
+*/
+var NativeIntegrity = class extends IntegrityStrategy {
+	async validateForeignKeys() {}
+	async cascadeBeforeDelete() {}
+	needsCascade() {
+		return false;
+	}
+};
+//#endregion
+//#region src/base-adapter.ts
+const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
+const txStorage = new AsyncLocalStorage();
+/**
+* Abstract base class for database adapters.
+*
+* Adapter instances are 1:1 with readable instances (tables or views).
+* When an {@link AtscriptDbReadable} is created with an adapter, it calls
+* {@link registerReadable} to establish a bidirectional relationship:
+*
+* ```
+* AtscriptDbReadable ──delegates ops──▶ BaseDbAdapter
+*                    ◀──reads metadata── (via this._table)
+* ```
+*
+* Adapter authors can access all computed metadata through `this._table`:
+* - `this._table.tableName` — resolved table/collection/view name
+* - `this._table.flatMap` — all fields as dot-notation paths
+* - `this._table.indexes` — computed index definitions
+* - `this._table.primaryKeys` — primary key field names
+* - `this._table.columnMap` — logical → physical column mappings
+* - `this._table.defaults` — default value configurations
+* - `this._table.ignoredFields` — fields excluded from DB
+* - `this._table.uniqueProps` — single-field unique index properties
+* - `this._table.isView` — whether this is a view (vs a table)
+*/
+var BaseDbAdapter = class {
+	_table;
+	_metaIdPhysical;
+	/**
+	* Returns the physical column name of the single @meta.id field (if any).
+	* Used to return the user's logical ID instead of the DB-generated ID on insert.
+	*/
+	_getMetaIdPhysical() {
+		if (this._metaIdPhysical === void 0) {
+			const fields = this._table.originalMetaIdFields;
+			if (fields.length === 1) {
+				const field = fields[0];
+				this._metaIdPhysical = this._table.columnMap.get(field) ?? field;
+			} else this._metaIdPhysical = null;
+		}
+		return this._metaIdPhysical;
+	}
+	/**
+	* Resolves the correct insertedId: prefers the user-supplied PK value
+	* from the data over the DB-generated fallback (e.g. rowid, _id).
+	*/
+	_resolveInsertedId(data, dbGeneratedId) {
+		const metaIdPhysical = this._getMetaIdPhysical();
+		return metaIdPhysical ? data[metaIdPhysical] ?? dbGeneratedId : dbGeneratedId;
+	}
+	/** Logger instance — set via {@link registerReadable} from the readable's logger. */
+	logger = NoopLogger;
+	/** When true, adapter logs DB calls via `logger.debug`. Off by default. */
+	_verbose = false;
+	/**
+	* Called by {@link AtscriptDbReadable} constructor. Gives the adapter access
+	* to the readable's computed metadata for internal use in query rendering,
+	* index sync, etc.
+	*/
+	registerReadable(readable, logger) {
+		this._table = readable;
+		if (logger) this.logger = logger;
+	}
+	/**
+	* Enables or disables verbose (debug-level) logging for this adapter.
+	* When disabled, no log strings are constructed — zero overhead.
+	*/
+	setVerbose(enabled) {
+		this._verbose = enabled;
+	}
+	/**
+	* Logs a debug message if verbose mode is enabled.
+	* Adapters call this to log DB operations with zero overhead when disabled.
+	*/
+	_log(...args) {
+		if (!this._verbose) return;
+		this.logger.debug(...args);
+	}
+	/**
+	* Runs `fn` inside a database transaction. Nested calls (from related tables
+	* within the same async chain) reuse the existing transaction automatically.
+	*
+	* The generic layer handles nesting detection via `AsyncLocalStorage`.
+	* Adapters override `_beginTransaction`, `_commitTransaction`, and
+	* `_rollbackTransaction` to provide raw DB-specific transaction primitives.
+	*/
+	async withTransaction(fn) {
+		if (txStorage.getStore()) return fn();
+		const ctx = { state: void 0 };
+		ctx.state = await this._beginTransaction();
+		return txStorage.run(ctx, async () => {
+			try {
+				const result = await fn();
+				await this._commitTransaction(ctx.state);
+				return result;
+			} catch (error) {
+				try {
+					await this._rollbackTransaction(ctx.state);
+				} catch {}
+				throw error;
+			}
+		});
+	}
+	/**
+	* Returns the opaque transaction state from the current async context.
+	* Adapters use this to retrieve DB-specific state (e.g., MongoDB `ClientSession`).
+	*/
+	_getTransactionState() {
+		return txStorage.getStore()?.state;
+	}
+	/**
+	* Runs `fn` inside the transaction ALS context with the given state.
+	* Adapters that override `withTransaction` (e.g., to use MongoDB's
+	* `session.withTransaction()` Convenient API) use this to set up the
+	* shared context so that nested adapters see the same session.
+	* If a context already exists (nesting), it's reused.
+	*/
+	_runInTransactionContext(state, fn) {
+		if (txStorage.getStore()) return fn();
+		return txStorage.run({ state }, fn);
+	}
+	/**
+	* Starts a raw transaction. Returns opaque state stored in the async context.
+	* Override in adapters that support transactions.
+	*/
+	async _beginTransaction() {}
+	/** Commits the raw transaction. Override in adapters that support transactions. */
+	async _commitTransaction(_state) {}
+	/** Rolls back the raw transaction. Override in adapters that support transactions. */
+	async _rollbackTransaction(_state) {}
+	/**
+	* Returns additional validator plugins for this adapter.
+	* These are merged with the built-in Atscript validators.
+	*
+	* Example: MongoDB adapter returns ObjectId validation plugin.
+	*/
+	getValidatorPlugins() {
+		return [];
+	}
+	/**
+	* Transforms an ID value for the database.
+	* Override to convert string → ObjectId, parse numeric IDs, etc.
+	*
+	* @param id - The raw ID value.
+	* @param fieldType - The annotated type of the ID field.
+	* @returns The transformed ID value.
+	*/
+	prepareId(id, _fieldType) {
+		return id;
+	}
+	/**
+	* Whether this adapter supports native patch operations.
+	* When `true`, {@link AtscriptDbTable} delegates patch payloads to
+	* {@link nativePatch} instead of using the generic decomposition.
+	*/
+	supportsNativePatch() {
+		return false;
+	}
+	/**
+	* Whether this adapter handles nested objects natively.
+	* When `true`, the generic layer skips flattening and
+	* passes nested objects as-is to the adapter.
+	* MongoDB returns `true`; relational adapters return `false` (default).
+	*/
+	supportsNestedObjects() {
+		return false;
+	}
+	/**
+	* Whether the DB engine handles static `@db.default "value"` natively
+	* via column-level DEFAULT clauses in CREATE TABLE.
+	* When `true`, `_applyDefaults()` skips client-side value defaults,
+	* letting the DB apply its own DEFAULT. SQL adapters return `true`;
+	* document stores (MongoDB) return `false` and apply defaults client-side.
+	*/
+	supportsNativeValueDefaults() {
+		return false;
+	}
+	/**
+	* Function default names handled natively by this adapter's DB engine.
+	* Fields with these defaults are omitted from INSERT when no value is provided,
+	* letting the DB apply its own DEFAULT expression (e.g. CURRENT_TIMESTAMP, UUID()).
+	*
+	* Override in adapters whose DB engine supports function defaults.
+	* The generic layer checks this in `_applyDefaults()` to decide whether
+	* to generate the value client-side or leave it for the DB.
+	*/
+	nativeDefaultFns() {
+		return EMPTY_DEFAULT_FNS;
+	}
+	/**
+	* Whether this adapter enforces foreign key constraints natively.
+	* When `true`, the generic layer skips application-level cascade/setNull
+	* on delete — the DB engine handles it (e.g. SQLite `ON DELETE CASCADE`).
+	* When `false` (default), the generic layer implements cascade logic
+	* by finding child records and deleting/nullifying them before the parent.
+	*/
+	supportsNativeForeignKeys() {
+		return false;
+	}
+	/**
+	* Whether this adapter handles `$with` relation loading natively.
+	* When `true`, the table layer delegates to {@link loadRelations}
+	* instead of using the generic batch-loading strategy.
+	*
+	* Adapters can use this to implement SQL JOINs, MongoDB `$lookup`,
+	* or other DB-native relation loading optimizations.
+	*
+	* Default: `false` — the table layer uses application-level batch loading.
+	*/
+	supportsNativeRelations() {
+		return false;
+	}
+	/**
+	* Loads relations onto result rows using adapter-native operations.
+	* Only called when {@link supportsNativeRelations} returns `true`.
+	*
+	* The adapter receives the rows to enrich, the `$with` relation specs,
+	* and the table's relation/FK metadata for resolution.
+	*
+	* @param rows - The result rows to enrich (mutable — add relation properties in place).
+	* @param withRelations - The `$with` specs from the query.
+	* @param relations - This table's relation metadata (from `@db.rel.to`/`@db.rel.from`).
+	* @param foreignKeys - This table's FK metadata (from `@db.rel.FK`).
+	* @param tableResolver - Optional callback to resolve annotated types to table metadata (needed for FROM/VIA relations).
+	*/
+	async loadRelations(_rows, _withRelations, _relations, _foreignKeys, _tableResolver) {
+		throw new Error("Native relation loading not supported by this adapter");
+	}
+	/**
+	* Applies a patch payload using native database operations.
+	* Only called when {@link supportsNativePatch} returns `true`.
+	*
+	* @param filter - Filter identifying the record to patch.
+	* @param patch - The patch payload with array operations.
+	* @returns Update result.
+	*/
+	async nativePatch(_filter, _patch, _ops) {
+		throw new Error("Native patch not supported by this adapter");
+	}
+	/**
+	* Resolves the full table name, optionally including the schema prefix.
+	* Override for databases that don't support schemas (e.g., SQLite).
+	*
+	* @param includeSchema - Whether to prepend `schema.` prefix (default: true).
+	*/
+	resolveTableName(includeSchema = true) {
+		const schema = this._table.schema;
+		const name = this._table.tableName;
+		return includeSchema && schema ? `${schema}.${name}` : name;
+	}
+	/**
+	* Template method for index synchronization.
+	* Implements the diff algorithm (list → compare → create/drop).
+	* Adapters provide the three DB-specific primitives.
+	*
+	* @example
+	* ```typescript
+	* async syncIndexes() {
+	*   await this.syncIndexesWithDiff({
+	*     listExisting: async () => this.driver.all('PRAGMA index_list(...)'),
+	*     createIndex: async (index) => this.driver.exec('CREATE INDEX ...'),
+	*     dropIndex: async (name) => this.driver.exec('DROP INDEX ...'),
+	*     shouldSkipType: (type) => type === 'fulltext',
+	*   })
+	* }
+	* ```
+	*/
+	async syncIndexesWithDiff(opts) {
+		const prefix = opts.prefix ?? "atscript__";
+		const existing = await opts.listExisting();
+		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.shouldSkipType?.(index.type)) continue;
+			desiredNames.add(index.key);
+			if (!existingNames.has(index.key)) await opts.createIndex(index);
+		}
+		for (const name of existingNames) if (!desiredNames.has(name)) await opts.dropIndex(name);
+	}
+	/**
+	* Returns available search indexes for this adapter.
+	* UI uses this to show index picker. Override in adapters that support search.
+	*/
+	getSearchIndexes() {
+		return [];
+	}
+	/**
+	* Whether this adapter supports text search.
+	* Default: `true` when {@link getSearchIndexes} returns any entries.
+	*/
+	isSearchable() {
+		return this.getSearchIndexes().length > 0;
+	}
+	/**
+	* Whether this adapter supports vector similarity search.
+	* Override in adapters that support vector search.
+	*/
+	isVectorSearchable() {
+		return false;
+	}
+	/**
+	* Full-text search. Override in adapters that support search.
+	*
+	* @param text - Search text.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional search index to target.
+	*/
+	async search(_text, _query, _indexName) {
+		throw new Error("Search not supported by this adapter");
+	}
+	/**
+	* Full-text search with count (for paginated search results).
+	*
+	* @param text - Search text.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional search index to target.
+	*/
+	async searchWithCount(_text, _query, _indexName) {
+		throw new Error("Search not supported by this adapter");
+	}
+	/**
+	* Vector similarity search. Override in adapters that support vector search.
+	*
+	* @param vector - Pre-computed embedding vector.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional vector index to target (for multi-vector documents).
+	*/
+	async vectorSearch(_vector, _query, _indexName) {
+		throw new Error("Vector search not supported by this adapter");
+	}
+	/**
+	* Vector similarity search with count (for paginated results).
+	*
+	* @param vector - Pre-computed embedding vector.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional vector index to target (for multi-vector documents).
+	*/
+	async vectorSearchWithCount(_vector, _query, _indexName) {
+		throw new Error("Vector 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.
+	*/
+	async findManyWithCount(query) {
+		const [data, count] = await Promise.all([this.findMany(query), this.count(query)]);
+		return {
+			data,
+			count
+		};
+	}
+	/**
+	* Executes an aggregate query (GROUP BY + aggregate functions).
+	* Default throws — override in adapters that support aggregation.
+	*/
+	async aggregate(_query) {
+		throw new Error("Aggregation not supported by this adapter");
+	}
+	/**
+	* When true, the adapter can handle column type changes in-place
+	* (e.g. MySQL's ALTER TABLE MODIFY COLUMN) without requiring table recreation.
+	* The generic sync layer will delegate type changes to {@link syncColumns}
+	* instead of requiring `@db.sync.method "recreate"` or `"drop"`.
+	*/
+	supportsColumnModify;
+};
+//#endregion
+//#region src/strategies/application-integrity.ts
+const MAX_CASCADE_DEPTH = 100;
+const cascadeStorage = new AsyncLocalStorage();
+/**
+* Integrity strategy for adapters without native FK support (e.g. MongoDB).
+* Validates FK constraints and executes cascade/setNull actions at
+* the application level.
+*/
+var ApplicationIntegrity = class extends IntegrityStrategy {
+	/**
+	* Validates FK constraints by querying target tables for referenced records.
+	* Collects unique FK values across items, batches them into target-table
+	* lookups, and throws FK_VIOLATION if any references are missing.
+	*/
+	async validateForeignKeys(items, meta, fkLookupResolver, writeTableResolver, partial, excludeTargetTable) {
+		if (!fkLookupResolver) return;
+		const checks = [];
+		for (const [, fk] of meta.foreignKeys) {
+			if (excludeTargetTable && fk.targetTable === excludeTargetTable) continue;
+			const valueSets = fk.fields.map(() => /* @__PURE__ */ new Set());
+			for (const item of items) {
+				if (partial && !fk.fields.some((f) => f in item)) continue;
+				let allPresent = true;
+				const vals = [];
+				for (const field of fk.fields) {
+					const v = item[field];
+					if (v === null || v === void 0) {
+						allPresent = false;
+						break;
+					}
+					vals.push(v);
+				}
+				if (!allPresent) continue;
+				for (let i = 0; i < vals.length; i++) valueSets[i].add(vals[i]);
+			}
+			if (valueSets[0].size === 0) continue;
+			let target = fkLookupResolver(fk.targetTable);
+			if (!target && fk.targetTypeRef && writeTableResolver) {
+				const resolved = writeTableResolver(fk.targetTypeRef());
+				if (resolved) target = { count: (filter) => resolved.count({ filter }) };
+			}
+			if (!target) continue;
+			const filter = {};
+			let firstValues = [];
+			for (let i = 0; i < fk.targetFields.length; i++) {
+				const values = [...valueSets[i]];
+				if (i === 0) firstValues = values;
+				filter[fk.targetFields[i]] = values.length === 1 ? values[0] : { $in: values };
+			}
+			const expectedCount = firstValues.length;
+			checks.push(async () => {
+				if (await target.count(filter) < expectedCount) {
+					const sample = firstValues.slice(0, 3).join(", ");
+					const suffix = firstValues.length > 3 ? `, ... (${firstValues.length} total)` : "";
+					throw new DbError("FK_VIOLATION", [{
+						path: fk.fields.join(", "),
+						message: `FK constraint violation: "${fk.fields.join(", ")}" references non-existent record in "${fk.targetTable}" (values: ${sample}${suffix})`
+					}]);
+				}
+			});
+		}
+		if (checks.length > 0) await Promise.all(checks.map((fn) => fn()));
+	}
+	/**
+	* Applies cascade/setNull actions on child tables before deleting parent records.
+	* Finds all records matching `filter`, extracts their PK values, then for each
+	* child table with a FK pointing to this table:
+	* - `restrict`: throws if any children exist
+	* - `cascade`: recursively deletes child records
+	* - `setNull`: sets FK fields to null
+	*/
+	async cascadeBeforeDelete(filter, tableName, meta, cascadeResolver, translateFilter, adapter) {
+		const parentCtx = cascadeStorage.getStore();
+		const visited = parentCtx?.visited ?? /* @__PURE__ */ new Set();
+		const depth = (parentCtx?.depth ?? 0) + 1;
+		if (depth > MAX_CASCADE_DEPTH) throw new DbError("CASCADE_CYCLE", [{
+			path: tableName,
+			message: `Cascade delete aborted: chain exceeded ${MAX_CASCADE_DEPTH} levels, likely caused by a circular or deeply nested cascade relationship`
+		}]);
+		const targets = cascadeResolver(tableName);
+		if (targets.length === 0) return;
+		const neededLogical = /* @__PURE__ */ new Set();
+		for (const t of targets) for (const tf of t.fk.targetFields) neededLogical.add(tf);
+		for (const pk of meta.primaryKeys) neededLogical.add(pk);
+		const physicalToLogical = /* @__PURE__ */ new Map();
+		const physicalFields = [];
+		for (const logical of neededLogical) {
+			const physical = meta.pathToPhysical.get(logical) ?? meta.columnMap.get(logical) ?? logical;
+			physicalFields.push(physical);
+			physicalToLogical.set(physical, logical);
+		}
+		const rawRecords = await adapter.findMany({
+			filter: translateFilter(filter),
+			controls: { $select: new UniquSelect(physicalFields) }
+		});
+		if (rawRecords.length === 0) return;
+		const allRecords = rawRecords.map((r) => {
+			const mapped = {};
+			for (const [key, val] of Object.entries(r)) mapped[physicalToLogical.get(key) ?? key] = val;
+			return mapped;
+		});
+		const pkFields = meta.primaryKeys;
+		const addedKeys = [];
+		const records = [];
+		for (const record of allRecords) {
+			const key = this.recordKey(tableName, pkFields, record);
+			if (visited.has(key)) continue;
+			visited.add(key);
+			addedKeys.push(key);
+			records.push(record);
+		}
+		if (records.length === 0) return;
+		try {
+			await cascadeStorage.run({
+				visited,
+				depth
+			}, async () => {
+				const restrictChecks = [];
+				for (const target of targets) {
+					if (target.fk.onDelete !== "restrict") continue;
+					const childFilter = this.buildCascadeChildFilter(records, target.fk);
+					if (!childFilter) continue;
+					restrictChecks.push(target.count(childFilter).then((count) => {
+						if (count > 0) throw new DbError("CONFLICT", [{
+							path: tableName,
+							message: `Cannot delete from "${tableName}": ${count} record(s) in "${target.childTable}" (${target.fk.fields.join(", ")}) reference it (RESTRICT)`
+						}]);
+					}));
+				}
+				if (restrictChecks.length > 0) await Promise.all(restrictChecks);
+				for (const target of targets) {
+					const action = target.fk.onDelete;
+					if (!action || action === "noAction" || action === "restrict") continue;
+					const childFilter = this.buildCascadeChildFilter(records, target.fk);
+					if (!childFilter) continue;
+					switch (action) {
+						case "cascade":
+							await target.deleteMany(childFilter);
+							break;
+						case "setNull": {
+							const nullData = {};
+							for (const f of target.fk.fields) nullData[f] = null;
+							await target.updateMany(childFilter, nullData);
+							break;
+						}
+					}
+				}
+			});
+		} finally {
+			for (const key of addedKeys) visited.delete(key);
+		}
+	}
+	needsCascade(cascadeResolver) {
+		return !!cascadeResolver;
+	}
+	recordKey(tableName, pkFields, record) {
+		let key = tableName;
+		for (const f of pkFields) {
+			const v = record[f];
+			key += `\0${v === null || v === void 0 ? "" : String(v)}`;
+		}
+		return key;
+	}
+	/**
+	* Builds a filter for child records whose FK matches the deleted parent's PK values.
+	*/
+	buildCascadeChildFilter(parentRecords, fk) {
+		if (fk.fields.length === 1 && fk.targetFields.length === 1) {
+			const pkField = fk.targetFields[0];
+			const values = parentRecords.map((r) => r[pkField]).filter((v) => v !== void 0 && v !== null);
+			if (values.length === 0) return;
+			return values.length === 1 ? { [fk.fields[0]]: values[0] } : { [fk.fields[0]]: { $in: values } };
+		}
+		const orFilters = [];
+		for (const record of parentRecords) {
+			const condition = {};
+			let valid = true;
+			for (let i = 0; i < fk.fields.length; i++) {
+				const val = record[fk.targetFields[i]];
+				if (val === void 0 || val === null) {
+					valid = false;
+					break;
+				}
+				condition[fk.fields[i]] = val;
+			}
+			if (valid) orFilters.push(condition);
+		}
+		if (orFilters.length === 0) return;
+		return orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
+	}
+};
+//#endregion
+//#region src/patch/patch-types.ts
+/**
+* Extracts `@expect.array.key` properties from an array-of-objects type.
+* These keys uniquely identify an element inside the array and are used
+* for `$update`, `$remove`, and `$upsert` operations.
+*
+* @param def - Atscript array type definition.
+* @returns Set of property names marked as keys; empty set if none.
+*/
+function getKeyProps(def) {
+	if (def.type.of.type.kind === "object") {
+		const objType = def.type.of.type;
+		const keyProps = /* @__PURE__ */ new Set();
+		for (const [key, val] of objType.props.entries()) if (val.metadata.get("expect.array.key")) keyProps.add(key);
+		return keyProps;
+	}
+	return /* @__PURE__ */ new Set();
+}
+//#endregion
+//#region src/db-validator-plugin.ts
+/** Set of recognised array‑patch operator keys. */
+const PATCH_OPS = new Set([
+	"$replace",
+	"$insert",
+	"$upsert",
+	"$update",
+	"$remove"
+]);
+/**
+* Returns `true` when `value` looks like a patch‑operator object
+* (at least one key is a recognised operator and no unknown keys).
+*/
+function isPatchOperatorObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length === 0) return false;
+	return keys.every((k) => PATCH_OPS.has(k));
+}
+/**
+* Validator plugin for database operations.
+*
+* Handles navigation field constraints and delegates to the standard validator
+* for type checking. The annotated type tree already includes nav fields with
+* their full target types — this plugin controls WHEN recursion is allowed
+* based on the operation mode (insert/replace/patch).
+*
+* Replaces the old `navFieldsValidatorPlugin` (which blindly skipped all nav
+* fields) and `_checkNavProps()` (which validated constraints separately).
+*/
+function createDbValidatorPlugin() {
+	return (ctx, def, value) => {
+		const dbCtx = ctx.context;
+		if (!dbCtx) return;
+		const isTo = def.metadata.has("db.rel.to");
+		const isFrom = def.metadata.has("db.rel.from");
+		const isVia = def.metadata.has("db.rel.via");
+		if (isTo || isFrom || isVia) return handleNavField(ctx, def, value, dbCtx, isTo, isFrom, isVia);
+		if (dbCtx.mode === "patch" && isDbFieldOp(value)) return true;
+		if (dbCtx.mode === "patch" && def.type.kind === "array" && dbCtx.flatMap) {
+			const flatEntry = dbCtx.flatMap.get(ctx.path);
+			if (flatEntry?.metadata?.has("db.__topLevelArray") && !flatEntry.metadata.has("db.json")) return handleArrayPatch(ctx, def, value);
+		}
+	};
+}
+function handleNavField(ctx, def, value, dbCtx, isTo, isFrom, isVia) {
+	const pathParts = ctx.path.split(".");
+	const fieldName = pathParts[pathParts.length - 1] || ctx.path;
+	if (value === null) {
+		ctx.error(`Cannot process null navigation property '${fieldName}'`);
+		return false;
+	}
+	if (value === void 0) return true;
+	if (dbCtx.mode === "patch") {
+		if (isFrom || isVia) {
+			if (isPatchOperatorObject(value)) return validateNavPatchOps(ctx, def, value, fieldName);
+			const relType = isFrom ? "1:N" : "M:N";
+			ctx.error(`Cannot patch ${relType} relation '${fieldName}' with a plain value — use patch operators ({ $insert, $remove, $replace, $update, $upsert })`);
+			return false;
+		}
+	}
+	if (isVia) return true;
+}
+/**
+* Validates patch operator values against the nav field's target array type.
+* Each operator's items are validated against the element type.
+*/
+function validateNavPatchOps(ctx, def, ops, fieldName) {
+	if (def.type.kind !== "array") {
+		ctx.error(`Cannot use patch operators on non-array relation '${fieldName}'`);
+		return false;
+	}
+	const arrayDef = def;
+	for (const op of [
+		"$replace",
+		"$insert",
+		"$upsert"
+	]) if (ops[op] !== void 0) {
+		if (!ctx.validateAnnotatedType(arrayDef, ops[op])) return false;
+	}
+	for (const op of ["$update", "$remove"]) if (ops[op] !== void 0) {
+		if (!validatePartialItems(ctx, arrayDef, ops[op], op, true)) return false;
+	}
+	return true;
+}
+/**
+* Handles patch‑mode validation for top‑level embedded arrays.
+*
+* When the incoming value is:
+* - A plain array → falls through to default array validation ($replace semantics)
+* - A patch operator object → validates each operator's payload individually
+*/
+function handleArrayPatch(ctx, def, value) {
+	if (Array.isArray(value)) return;
+	if (typeof value !== "object" || value === null) return;
+	const ops = value;
+	const keys = Object.keys(ops);
+	if (keys.length === 0 || !keys.every((k) => PATCH_OPS.has(k))) {
+		if (keys.some((k) => PATCH_OPS.has(k))) {
+			const unknown = keys.filter((k) => !PATCH_OPS.has(k));
+			ctx.error(`Unknown patch operator(s): ${unknown.join(", ")}. Allowed: $replace, $insert, $upsert, $update, $remove`);
+			return false;
+		}
+		return;
+	}
+	for (const op of [
+		"$replace",
+		"$insert",
+		"$upsert"
+	]) if (ops[op] !== void 0) {
+		if (!ctx.validateAnnotatedType(def, ops[op])) return false;
+	}
+	const isMerge = def.metadata.get("db.patch.strategy") === "merge";
+	for (const op of ["$update", "$remove"]) if (ops[op] !== void 0) {
+		if (!validatePartialItems(ctx, def, ops[op], op, isMerge)) return false;
+	}
+	return true;
+}
+/**
+* Validates `$update` / `$remove` items.
+*
+* Each item must be an object. For object arrays with `@expect.array.key` fields,
+* key properties are required and non‑key properties are validated but optional.
+* For primitive arrays, items are validated directly against the element type.
+*/
+function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
+	if (!Array.isArray(items)) {
+		ctx.error(`${op} must be an array`);
+		return false;
+	}
+	const elementDef = arrayDef.type.of;
+	if (elementDef.type.kind !== "object") return ctx.validateAnnotatedType(arrayDef, items);
+	const keyProps = getKeyProps(arrayDef);
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (typeof item !== "object" || item === null || Array.isArray(item)) {
+			ctx.error(`${op}[${i}]: expected object`);
+			return false;
+		}
+		const rec = item;
+		if (keyProps.size > 0) {
+			for (const kp of keyProps) if (rec[kp] === void 0 || rec[kp] === null) {
+				ctx.error(`${op}[${i}]: key field '${kp}' is required`);
+				return false;
+			}
+		}
+		const objType = elementDef.type;
+		for (const [key, val] of Object.entries(rec)) {
+			const propDef = objType.props.get(key);
+			if (propDef) {
+				if (!ctx.validateAnnotatedType(propDef, val)) return false;
+			}
+		}
+		if (op === "$update" && isMerge !== true) {
+			for (const [propName, propDef] of objType.props) if (!propDef.optional && !keyProps.has(propName) && rec[propName] === void 0) {
+				ctx.error(`${op}[${i}]: field '${propName}' is required (replace strategy)`);
+				return false;
+			}
+		}
+	}
+	return true;
+}
+//#endregion
+//#region src/patch/array-ops-resolver.ts
+/**
+* Resolves array patch operator keys (`__$insert`, `__$remove`, `__$upsert`,
+* `__$update`, `__$keys`) in a decomposed update into plain resolved arrays.
+*
+* This is the generic fallback for adapters that don't support native patch
+* operations (e.g., SQLite). It performs a read‑modify‑write:
+*
+* 1. Detects `__$` operator keys in the update object
+* 2. Reads the current record to get existing array values
+* 3. Applies operations in‑memory
+* 4. Replaces operator keys with resolved plain values
+*
+* @param update - The decomposed update (from `decomposePatch`), potentially
+*   containing `field.__$insert`, `field.__$remove`, etc.
+* @param currentRecord - The current record fetched from the database (only the
+*   fields that have array ops). Can be `null` if the record doesn't exist.
+* @param table - The AtscriptDbTable for metadata access (key props, unique items).
+* @returns A new update object with all `__$` keys resolved to plain values.
+*/
+function resolveArrayOps(update, currentRecord, table) {
+	const resolved = {};
+	const opsMap = /* @__PURE__ */ new Map();
+	const seenOpsFields = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(update)) {
+		const match = key.match(/^(.+?)\.__\$(.+)$/);
+		if (!match) {
+			resolved[key] = value;
+			continue;
+		}
+		const field = match[1];
+		const op = match[2];
+		seenOpsFields.add(field);
+		let fieldOps = opsMap.get(field);
+		if (!fieldOps) {
+			fieldOps = {};
+			opsMap.set(field, fieldOps);
+		}
+		switch (op) {
+			case "insert":
+				fieldOps.insert = value;
+				break;
+			case "remove":
+				fieldOps.remove = value;
+				break;
+			case "upsert":
+				fieldOps.upsert = value;
+				break;
+			case "update":
+				fieldOps.update = value;
+				break;
+			case "keys":
+				fieldOps.keys = value;
+				break;
+		}
+	}
+	for (const [field, ops] of opsMap) {
+		const raw = currentRecord?.[field] ?? [];
+		const current = typeof raw === "string" ? JSON.parse(raw) : raw;
+		const arrayType = table.flatMap.get(field);
+		const keyProps = arrayType ? getKeyProps(arrayType) : /* @__PURE__ */ new Set();
+		const uniqueItems = arrayType?.metadata?.get("expect.array.uniqueItems");
+		const mergeStrategy = arrayType?.metadata?.get("db.patch.strategy") === "merge";
+		resolved[field] = applyOps(current, ops, ops.keys && ops.keys.length > 0 ? new Set(ops.keys) : keyProps, !!uniqueItems, mergeStrategy);
+	}
+	return resolved;
+}
+/**
+* Extracts the set of field names that have array ops in the update.
+* Used to determine which fields need to be fetched from the current record.
+*/
+function getArrayOpsFields(update) {
+	const fields = /* @__PURE__ */ new Set();
+	for (const key of Object.keys(update)) {
+		const match = key.match(/^(.+?)\.__\$(.+)$/);
+		if (match) fields.add(match[1]);
+	}
+	return fields;
+}
+/**
+* Applies patch operations to an array in‑memory.
+* Order: remove → update → upsert → insert (most intuitive semantics).
+*/
+function applyOps(current, ops, keyProps, uniqueItems, mergeStrategy) {
+	let result = [...current];
+	if (ops.remove) result = applyRemove(result, ops.remove, keyProps);
+	if (ops.update) result = applyUpdate(result, ops.update, keyProps);
+	if (ops.upsert) result = applyUpsert(result, ops.upsert, keyProps, mergeStrategy);
+	if (ops.insert) result = applyInsert(result, ops.insert, keyProps, uniqueItems);
+	return result;
+}
+function applyRemove(arr, items, keyProps) {
+	if (keyProps.size === 0) {
+		const removeSet = new Set(items.map((i) => JSON.stringify(i)));
+		return arr.filter((el) => !removeSet.has(JSON.stringify(el)));
+	}
+	return arr.filter((el) => {
+		const elObj = el;
+		return !items.some((item) => matchByKeys(elObj, item, keyProps));
+	});
+}
+function applyUpdate(arr, items, keyProps) {
+	if (keyProps.size === 0) return arr;
+	return arr.map((el) => {
+		const elObj = el;
+		const match = items.find((item) => matchByKeys(elObj, item, keyProps));
+		if (match) return {
+			...elObj,
+			...match
+		};
+		return el;
+	});
+}
+function applyUpsert(arr, items, keyProps, mergeStrategy) {
+	const result = [...arr];
+	for (const item of items) if (keyProps.size === 0) {
+		const idx = result.findIndex((el) => JSON.stringify(el) === JSON.stringify(item));
+		if (idx >= 0) result[idx] = item;
+		else result.push(item);
+	} else {
+		const itemObj = item;
+		const idx = result.findIndex((el) => matchByKeys(el, itemObj, keyProps));
+		if (idx >= 0) result[idx] = mergeStrategy ? {
+			...result[idx],
+			...itemObj
+		} : itemObj;
+		else result.push(item);
+	}
+	return result;
+}
+function applyInsert(arr, items, keyProps, uniqueItems) {
+	if (!uniqueItems) return [...arr, ...items];
+	const result = [...arr];
+	for (const item of items) if (!(keyProps.size > 0 ? result.some((el) => matchByKeys(el, item, keyProps)) : result.some((el) => JSON.stringify(el) === JSON.stringify(item)))) result.push(item);
+	return result;
+}
+function matchByKeys(a, b, keys) {
+	for (const key of keys) if (a[key] !== b[key]) return false;
+	return true;
+}
+//#endregion
+//#region src/patch/patch-decomposer.ts
+/**
+* Decomposes a patch payload into a flat update object for adapters
+* that don't support native patch operations.
+*
+* Handles:
+* - Top-level array patches (`$replace`, `$insert`, `$upsert`, `$update`, `$remove`)
+* - Merge strategy for nested objects
+* - Simple field sets
+*
+* For adapters with native patch support (e.g., MongoDB aggregation pipelines),
+* use {@link BaseDbAdapter.nativePatch} instead.
+*
+* @param payload - The patch payload from the user.
+* @param table - The AtscriptDbTable instance for metadata access.
+* @returns A flat update object suitable for a basic `updateOne` call.
+*/
+function decomposePatch(payload, table) {
+	const update = {};
+	flattenPatchPayload(payload, "", update, table, "db.__topLevelArray");
+	return update;
+}
+function flattenPatchPayload(payload, prefix, update, table, topLevelArrayTag) {
+	for (const [_key, value] of Object.entries(payload)) {
+		const key = prefix ? `${prefix}.${_key}` : _key;
+		if (table.primaryKeys.includes(key)) continue;
+		const flatType = table.flatMap.get(key);
+		const isTopLevelArray = flatType?.metadata?.get(topLevelArrayTag);
+		if (typeof value === "object" && value !== null && !Array.isArray(value) && isTopLevelArray && !flatType?.metadata?.has("db.json")) decomposeArrayPatch(key, value, flatType, update, table);
+		else if (typeof value === "object" && value !== null && !Array.isArray(value) && flatType?.metadata?.get("db.patch.strategy") === "merge") flattenPatchPayload(value, key, update, table, topLevelArrayTag);
+		else update[key] = value;
+	}
+}
+/**
+* Decomposes array patch operators into simple field updates.
+*
+* For adapters without native array operations, this does a best-effort
+* decomposition:
+* - `$replace` → direct set
+* - `$insert` → value to append (adapter must handle)
+* - `$upsert` → value to upsert by key (adapter must handle)
+* - `$update` → value to update by key (adapter must handle)
+* - `$remove` → value to remove by key (adapter must handle)
+*
+* Note: For full correctness with `$insert`/`$upsert`/`$update`/`$remove`,
+* the adapter should implement native patch support. This generic decomposition
+* handles `$replace` directly and stores the other operations in a structured
+* format the adapter can interpret.
+*/
+function decomposeArrayPatch(key, value, fieldType, update, _table) {
+	const keyProps = fieldType.type.kind === "array" ? getKeyProps(fieldType) : /* @__PURE__ */ new Set();
+	if (value.$replace !== void 0) {
+		update[key] = value.$replace;
+		return;
+	}
+	if (value.$insert !== void 0) update[`${key}.__$insert`] = value.$insert;
+	if (value.$upsert !== void 0) update[`${key}.__$upsert`] = value.$upsert;
+	if (value.$update !== void 0) update[`${key}.__$update`] = value.$update;
+	if (value.$remove !== void 0) update[`${key}.__$remove`] = value.$remove;
+	if (keyProps.size > 0 && (value.$upsert !== void 0 || value.$update !== void 0 || value.$remove !== void 0)) update[`${key}.__$keys`] = [...keyProps];
+}
+//#endregion
+//#region src/table/db-table.ts
+/**
+* Generic database table abstraction driven by Atscript `@db.*` annotations.
+*
+* Extends {@link AtscriptDbReadable} (read operations, field metadata, query
+* translation, relation loading) with write operations, validators, and
+* schema management.
+*
+* ```typescript
+* const adapter = new MongoAdapter(db)
+* const users = new AtscriptDbTable(UsersType, adapter)
+* await users.insertOne({ name: 'John', email: 'john@example.com' })
+* ```
+*
+* @typeParam T - The Atscript annotated type for this table.
+* @typeParam DataType - The inferred data shape from the annotated type.
+*/
+/** Zero-allocation emptiness check for objects. */
+function _isEmptyObj(obj) {
+	for (const _ in obj) return false;
+	return true;
+}
+/** Translates a single ops record from logical to physical column names. */
+function _translateOpsRecord(rec, meta) {
+	const out = {};
+	for (const key in rec) out[meta.leafByLogical.get(key)?.physicalName ?? key] = rec[key];
+	return out;
+}
+/** Translates ops keys from logical field names to physical column names. */
+function _translateOpsKeys(ops, meta) {
+	return {
+		inc: ops.inc ? _translateOpsRecord(ops.inc, meta) : void 0,
+		mul: ops.mul ? _translateOpsRecord(ops.mul, meta) : void 0
+	};
+}
+/**
+* Forces nav fields non-optional so the plugin handles null/undefined
+* checks (validator skips optional+null before plugins run).
+*/
+function forceNavNonOptional(type) {
+	if (type.metadata?.has("db.rel.to") || type.metadata?.has("db.rel.from") || type.metadata?.has("db.rel.via")) return type.optional ? {
+		...type,
+		optional: false
+	} : type;
+	return type;
+}
+/** Makes PK, defaulted, and FK fields optional; forces nav fields non-optional. */
+function insertReplace(type) {
+	if (type.metadata?.has("meta.id") || type.metadata?.has("db.default") || type.metadata?.has("db.default.increment") || type.metadata?.has("db.default.uuid") || type.metadata?.has("db.default.now") || type.metadata?.has("db.rel.FK")) return {
+		...type,
+		optional: true
+	};
+	return forceNavNonOptional(type);
+}
+var AtscriptDbTable = class extends AtscriptDbReadable {
+	_cascadeResolver;
+	_fkLookupResolver;
+	_integrity;
+	validators = /* @__PURE__ */ new Map();
+	constructor(_type, adapter, logger, _tableResolver, _writeTableResolver) {
+		super(_type, adapter, logger, _tableResolver);
+		if (_writeTableResolver) this._writeTableResolver = _writeTableResolver;
+		this._integrity = adapter.supportsNativeForeignKeys() ? new NativeIntegrity() : new ApplicationIntegrity();
+	}
+	/**
+	* Sets the cascade resolver for application-level cascade deletes.
+	* Called by DbSpace after table creation.
+	*/
+	setCascadeResolver(resolver) {
+		this._cascadeResolver = resolver;
+	}
+	/**
+	* Sets the FK lookup resolver for application-level FK validation.
+	* Called by DbSpace after table creation.
+	*/
+	setFkLookupResolver(resolver) {
+		this._fkLookupResolver = resolver;
+	}
+	/**
+	* Returns a cached validator for the given purpose.
+	* Built with adapter plugins from {@link BaseDbAdapter.getValidatorPlugins}.
+	*
+	* Standard purposes: `'insert'`, `'update'`, `'patch'`.
+	* Adapters may define additional purposes.
+	*/
+	getValidator(purpose) {
+		if (!this.validators.has(purpose)) {
+			const validator = this._buildValidator(purpose);
+			this.validators.set(purpose, validator);
+		}
+		return this.validators.get(purpose);
+	}
+	/**
+	* Inserts a single record. Delegates to {@link insertMany} for unified
+	* nested creation support.
+	*/
+	async insertOne(payload, opts) {
+		return { insertedId: (await this.insertMany([payload], opts)).insertedIds[0] };
+	}
+	/**
+	* Inserts multiple records with batch-optimized nested creation.
+	*
+	* Supports **nested creation**: if payloads include data for navigation
+	* fields (`@db.rel.to` / `@db.rel.from`), related records are created
+	* automatically in batches. TO dependencies are batch-created first
+	* (their PKs become our FKs), FROM dependents are batch-created after
+	* (they receive our PKs as their FKs). Fully recursive — nested records
+	* with their own nav data trigger further batch inserts at each level.
+	* Recursive up to `maxDepth` (default 3).
+	*/
+	async insertMany(payloads, opts) {
+		this._ensureBuilt();
+		const maxDepth = opts?.maxDepth ?? 3;
+		const depth = opts?._depth ?? 0;
+		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
+		if (!canNest && this._meta.navFields.size > 0) checkDepthOverflow(payloads, maxDepth, this._meta);
+		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
+			const items = payloads.map((p) => this._applyDefaults({ ...p }));
+			validateBatch(this.getValidator("insert"), items, { mode: "insert" });
+			const host = this;
+			if (canNest) await batchInsertNestedTo(host, items, maxDepth, depth);
+			const prepared = [];
+			for (const data of items) {
+				for (const navField of this._meta.navFields) delete data[navField];
+				prepared.push(this._fieldMapper.prepareForWrite(data, this._meta, this.adapter));
+			}
+			await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver);
+			if (canNest) await preValidateNestedFrom(host, payloads);
+			const result = await this.adapter.insertMany(prepared);
+			if (canNest) await batchInsertNestedFrom(host, payloads, result.insertedIds, maxDepth, depth);
+			if (canNest) await batchInsertNestedVia(host, payloads, result.insertedIds, maxDepth, depth);
+			return result;
+		}));
+	}
+	/**
+	* Replaces a single record identified by primary key(s).
+	* Delegates to {@link bulkReplace} for unified nested relation support.
+	*/
+	async replaceOne(payload, opts) {
+		return this.bulkReplace([payload], opts);
+	}
+	/**
+	* Replaces multiple records with deep nested relation support.
+	*
+	* Supports all relation types (TO, FROM, VIA). TO dependencies are
+	* replaced first (their PKs become our FKs), FROM dependents are replaced
+	* after (they receive our PKs as their FKs), VIA relations clear and
+	* re-create junction rows. Fully recursive up to `maxDepth` (default 3).
+	*/
+	async bulkReplace(payloads, opts) {
+		this._ensureBuilt();
+		const maxDepth = opts?.maxDepth ?? 3;
+		const depth = opts?._depth ?? 0;
+		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
+		if (!canNest && this._meta.navFields.size > 0) checkDepthOverflow(payloads, maxDepth, this._meta);
+		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
+			const items = payloads.map((p) => this._applyDefaults({ ...p }));
+			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
+			validateBatch(this.getValidator("bulkReplace"), items, { mode: "replace" });
+			const host = this;
+			if (canNest) await batchReplaceNestedTo(host, items, maxDepth, depth);
+			await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver);
+			if (canNest) await preValidateNestedFrom(host, originals);
+			let matchedCount = 0;
+			let modifiedCount = 0;
+			for (const data of items) {
+				for (const navField of this._meta.navFields) delete data[navField];
+				const filter = this._extractPrimaryKeyFilter(data);
+				const prepared = this._fieldMapper.prepareForWrite(data, this._meta, this.adapter);
+				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared);
+				matchedCount += result.matchedCount;
+				modifiedCount += result.modifiedCount;
+			}
+			if (canNest) await batchReplaceNestedFrom(host, originals, maxDepth, depth);
+			if (canNest) await batchReplaceNestedVia(host, originals, maxDepth, depth);
+			return {
+				matchedCount,
+				modifiedCount
+			};
+		}));
+	}
+	/**
+	* Partially updates a single record identified by primary key(s).
+	* Delegates to {@link bulkUpdate} for unified nested relation support.
+	*/
+	async updateOne(payload, opts) {
+		return this.bulkUpdate([payload], opts);
+	}
+	/**
+	* Partially updates multiple records with deep nested relation support.
+	*
+	* Only TO relations (1:1, N:1) are supported for patching. FROM/VIA
+	* relations will error — use {@link bulkReplace} for those.
+	* Recursive up to `maxDepth` (default 3).
+	*/
+	async bulkUpdate(payloads, opts) {
+		this._ensureBuilt();
+		const maxDepth = opts?.maxDepth ?? 3;
+		const depth = opts?._depth ?? 0;
+		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
+		if (!canNest && this._meta.navFields.size > 0) checkDepthOverflow(payloads, maxDepth, this._meta);
+		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
+			validateBatch(this.getValidator("bulkUpdate"), payloads, {
+				mode: "patch",
+				flatMap: this.flatMap
+			});
+			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
+			const host = this;
+			if (canNest) await batchPatchNestedTo(host, payloads, maxDepth, depth);
+			await this._integrity.validateForeignKeys(payloads, this._meta, this._fkLookupResolver, this._writeTableResolver, true);
+			let matchedCount = 0;
+			let modifiedCount = 0;
+			for (const payload of payloads) {
+				const data = { ...payload };
+				for (const navField of this._meta.navFields) delete data[navField];
+				const filter = this._extractPrimaryKeyFilter(data);
+				for (const pk of this._meta.primaryKeys) delete data[pk];
+				const ops = separateFieldOps(data);
+				if (_isEmptyObj(data) && !ops) {
+					matchedCount += 1;
+					modifiedCount += 0;
+					continue;
+				}
+				let result;
+				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
+				const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
+				if (this.adapter.supportsNativePatch()) result = await this.adapter.nativePatch(translatedFilter, data, translatedOps);
+				else {
+					const update = decomposePatch(data, this);
+					const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
+					if (getArrayOpsFields(translatedUpdate).size > 0) {
+						const resolved = resolveArrayOps(translatedUpdate, await this.adapter.findOne({
+							filter: translatedFilter,
+							controls: {}
+						}), this);
+						result = await this.adapter.updateOne(translatedFilter, resolved, translatedOps);
+					} else result = await this.adapter.updateOne(translatedFilter, translatedUpdate, translatedOps);
+				}
+				matchedCount += result.matchedCount;
+				modifiedCount += result.modifiedCount;
+			}
+			if (canNest) await batchPatchNestedFrom(host, originals, maxDepth, depth);
+			if (canNest) await batchPatchNestedVia(host, originals, maxDepth, depth);
+			return {
+				matchedCount,
+				modifiedCount
+			};
+		}));
+	}
+	/**
+	* Deletes a single record by any type-compatible identifier — primary key
+	* or single-field unique index. Uses the same resolution logic as `findById`.
+	*
+	* When the adapter does not support native foreign keys (e.g. MongoDB),
+	* cascade and setNull actions are applied before the delete.
+	*/
+	async deleteOne(id) {
+		this._ensureBuilt();
+		const filter = this._resolveIdFilter(id);
+		if (!filter) return { deletedCount: 0 };
+		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.deleteOne(this._fieldMapper.translateFilter(filter, this._meta));
+		}));
+		return remapDeleteFkViolation(this.tableName, () => this.adapter.deleteOne(this._fieldMapper.translateFilter(filter, this._meta)));
+	}
+	async updateMany(filter, data) {
+		this._ensureBuilt();
+		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
+		const dataCopy = { ...data };
+		const ops = separateFieldOps(dataCopy);
+		const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
+		return enrichFkViolation(this._meta, () => this.adapter.updateMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite(dataCopy, this._meta, this.adapter), translatedOps));
+	}
+	async replaceMany(filter, data) {
+		this._ensureBuilt();
+		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)));
+	}
+	async deleteMany(filter) {
+		this._ensureBuilt();
+		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));
+		}));
+		return remapDeleteFkViolation(this.tableName, () => this.adapter.deleteMany(this._fieldMapper.translateFilter(filter, this._meta)));
+	}
+	/**
+	* Synchronizes indexes between Atscript definitions and the database.
+	*/
+	async syncIndexes() {
+		this._ensureBuilt();
+		return this.adapter.syncIndexes();
+	}
+	/**
+	* Ensures the table/collection exists in the database.
+	*/
+	async ensureTable() {
+		this._ensureBuilt();
+		return this.adapter.ensureTable();
+	}
+	/**
+	* Applies default values for fields that are missing from the payload.
+	* Defaults handled natively by the DB engine are skipped — the field stays
+	* absent so the DB's own DEFAULT clause applies.
+	*/
+	_applyDefaults(data) {
+		const nativeValues = this.adapter.supportsNativeValueDefaults();
+		const nativeFns = this.adapter.nativeDefaultFns();
+		for (const [field, def] of this._meta.defaults.entries()) if (data[field] === void 0) {
+			if (def.kind === "value" && !nativeValues) {
+				const fieldType = this._meta.flatMap?.get(field);
+				data[field] = (fieldType?.type.kind === "" && fieldType.type.designType) === "string" ? def.value : JSON.parse(def.value);
+			} else if (def.kind === "fn" && !nativeFns.has(def.fn)) switch (def.fn) {
+				case "now":
+					data[field] = Date.now();
+					break;
+				case "uuid":
+					data[field] = crypto.randomUUID();
+					break;
+			}
+		}
+		return data;
+	}
+	/**
+	* Extracts primary key field(s) from a payload to build a filter.
+	*/
+	_extractPrimaryKeyFilter(payload) {
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 0) throw new DbError("NOT_FOUND", [{
+			path: "",
+			message: "No primary key defined — cannot extract filter"
+		}]);
+		const filter = {};
+		for (const field of pkFields) {
+			if (payload[field] === void 0) throw new DbError("NOT_FOUND", [{
+				path: field,
+				message: `Missing primary key field "${field}" in payload`
+			}]);
+			const fieldType = this.flatMap.get(field);
+			filter[field] = fieldType ? this.adapter.prepareId(payload[field], fieldType) : payload[field];
+		}
+		return filter;
+	}
+	/**
+	* Pre-validate items (type validation + FK constraints) without inserting them.
+	* Used by parent tables to validate FROM children before the main insert,
+	* ensuring errors are caught before the parent is committed.
+	*
+	* @param opts.excludeFkTargetTable - Skip FK validation to this table (the parent).
+	*/
+	async preValidateItems(items, opts) {
+		this._ensureBuilt();
+		validateBatch(this.getValidator("insert"), items.map((raw) => this._applyDefaults({ ...raw })), { mode: "insert" });
+		await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver, false, opts?.excludeFkTargetTable);
+	}
+	/**
+	* Builds a validator for a given purpose with adapter plugins.
+	*
+	* Uses annotation-based `replace` callback to make `@meta.id` and
+	* `@db.default` fields optional — works at all nesting levels
+	* (including inside nav field target types).
+	*/
+	_buildValidator(purpose) {
+		const dbPlugin = createDbValidatorPlugin();
+		const plugins = [...this.adapter.getValidatorPlugins(), dbPlugin];
+		switch (purpose) {
+			case "insert": return this.createValidator({
+				plugins,
+				replace: insertReplace
+			});
+			case "patch": return this.createValidator({
+				plugins,
+				partial: true,
+				replace: forceNavNonOptional
+			});
+			case "bulkReplace": return this.createValidator({
+				plugins,
+				replace: insertReplace
+			});
+			case "bulkUpdate": {
+				const navFields = this._meta.navFields;
+				return this.createValidator({
+					plugins,
+					partial: (_def, path) => {
+						if (path === "") return true;
+						const root = path.split(".")[0];
+						if (navFields.has(root)) return true;
+						return _def.metadata.get("db.patch.strategy") === "merge";
+					},
+					replace: forceNavNonOptional
+				});
+			}
+			default: return this.createValidator({ plugins });
+		}
+	}
+};
+//#endregion
+//#region src/table/db-view.ts
+/**
+* Database view abstraction driven by Atscript `@db.view.*` annotations.
+*
+* Extends {@link AtscriptDbReadable} with view plan resolution — entry table,
+* joins, filter, and materialization flag. Read operations are inherited;
+* write operations are not available on views.
+*
+* ```typescript
+* const adapter = new SqliteAdapter(db)
+* const activeUsers = new AtscriptDbView(ActiveUsersType, adapter)
+* const users = await activeUsers.findMany({ filter: {}, controls: {} })
+* ```
+*/
+var AtscriptDbView = class extends AtscriptDbReadable {
+	_viewPlan;
+	get isView() {
+		return true;
+	}
+	/**
+	* Whether this is an external view — declared with `@db.view` only,
+	* without `@db.view.for`. External views reference pre-existing DB views
+	* and are not managed (created/dropped) by schema sync.
+	*/
+	get isExternal() {
+		return !this._type.metadata.has("db.view.for");
+	}
+	/**
+	* Lazily resolves the view plan from `@db.view.*` metadata.
+	*
+	* - `db.view.for` → entry type ref (required)
+	* - `db.view.joins` → array of `{ target, condition }` (optional, multiple)
+	* - `db.view.filter` → query tree (optional)
+	* - `db.view.materialized` → boolean (optional)
+	*/
+	get viewPlan() {
+		if (this._viewPlan) return this._viewPlan;
+		if (this.isExternal) throw new Error(`Cannot compute view plan for external view "${this.tableName}". External views (declared without @db.view.for) reference pre-existing DB views.`);
+		const metadata = this._type.metadata;
+		const forRef = metadata.get("db.view.for");
+		const entryType = typeof forRef === "function" ? forRef : forRef.type;
+		const entryTypeResolved = entryType();
+		const entryTable = entryTypeResolved?.metadata?.get("db.table") || entryTypeResolved?.id || "";
+		const rawJoins = metadata.get("db.view.joins");
+		const joins = [];
+		if (rawJoins) for (const join of rawJoins) {
+			const targetRef = join.target;
+			const targetType = typeof targetRef === "function" ? targetRef : targetRef.type;
+			const targetTypeResolved = targetType();
+			const targetTable = targetTypeResolved?.metadata?.get("db.table") || targetTypeResolved?.id || "";
+			joins.push({
+				targetType,
+				targetTable,
+				condition: join.condition
+			});
+		}
+		this._viewPlan = {
+			entryType,
+			entryTable,
+			joins,
+			filter: metadata.get("db.view.filter"),
+			having: metadata.get("db.view.having"),
+			materialized: metadata.has("db.view.materialized")
+		};
+		return this._viewPlan;
+	}
+	/**
+	* Resolves a query field ref to a quoted `table.column` SQL fragment.
+	*
+	* @param ref - The field reference from the query tree.
+	* @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
+	*             Defaults to double-quote wrapping for backwards compatibility.
+	*/
+	resolveFieldRef(ref, qi = (n) => `"${n}"`) {
+		if (!ref.type) {
+			const plan = this.viewPlan;
+			return `${qi(plan.entryTable)}.${qi(ref.field)}`;
+		}
+		const resolved = ref.type();
+		return `${qi(resolved?.metadata?.get("db.table") || resolved?.id || "")}.${qi(ref.field)}`;
+	}
+	/**
+	* Maps each view field to its source table and column via ref chain.
+	* Fields without refs (inline definitions) map to the entry table with the same name.
+	*/
+	getViewColumnMappings() {
+		const plan = this.viewPlan;
+		const mappings = [];
+		if (this._type.type.kind !== "object") return mappings;
+		const aggKeys = [
+			"db.agg.sum",
+			"db.agg.avg",
+			"db.agg.count",
+			"db.agg.min",
+			"db.agg.max"
+		];
+		for (const [fieldName, fieldType] of this._type.type.props.entries()) {
+			let aggFn;
+			let aggField;
+			for (const key of aggKeys) {
+				const val = fieldType.metadata?.get(key);
+				if (val !== void 0) {
+					aggFn = key.split(".")[2];
+					aggField = typeof val === "string" ? val : "*";
+					break;
+				}
+			}
+			if (fieldType.ref) {
+				const resolved = fieldType.ref.type();
+				const sourceTable = resolved?.metadata?.get("db.table") || resolved?.id || "";
+				const sourceColumn = fieldType.ref.field || fieldName;
+				mappings.push({
+					viewColumn: fieldName,
+					sourceTable,
+					sourceColumn,
+					aggFn,
+					aggField
+				});
+			} else {
+				const sourceColumn = aggField && aggField !== "*" ? aggField : fieldName;
+				mappings.push({
+					viewColumn: fieldName,
+					sourceTable: plan.entryTable,
+					sourceColumn,
+					aggFn,
+					aggField
+				});
+			}
+		}
+		return mappings;
+	}
+};
+//#endregion
+export { NoopLogger as _, getKeyProps as a, IntegrityStrategy as c, resolveDesignType as d, RelationalFieldMapper as f, TableMetadata as g, UniquSelect as h, createDbValidatorPlugin as i, NativeIntegrity as l, FieldMappingStrategy as m, AtscriptDbTable as n, ApplicationIntegrity as o, DocumentFieldMapper as p, decomposePatch as r, BaseDbAdapter as s, AtscriptDbView as t, AtscriptDbReadable as u };