@atscript/db 0.1.127 → 0.1.129

package/dist/{db-view-C8rZM5_N.mjs → db-view-Dl0aDTiT.mjs}

@@ -1,8 +1,8 @@
-import { n as DbError } from "./db-error-BHPXOKzc.mjs";
+import { n as CasMismatchError, r as DbError } from "./db-error-COrO58t5.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, l as isEmptyObject, n as buildPatchPartial, t as buildDbValidator, u as isPlainObject } from "./validator-CeD_fqyW.mjs";
 import { resolveAlias } from "./agg.mjs";
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-DI-HeTky.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CkDo-ZfH.mjs";
 import { separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, t as buildDbValidator } from "./validator-0vRXN51D.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/logger.ts
@@ -108,6 +108,22 @@ var TableMetadata = class {
 	leafByPhysical = /* @__PURE__ */ new Map();
 	/** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
 	leafByLogical = /* @__PURE__ */ new Map();
+	/**
+	* Non-ignored field descriptors keyed by logical path, excluding navigation
+	* relations and their descendants. Unlike `leafByLogical` (relational
+	* adapters only) this is built for every adapter, so the core path guard
+	* (`guardPaths`) can answer "does this path have physical storage here?"
+	* on nested-object adapters too.
+	*/
+	descriptorByPath = /* @__PURE__ */ new Map();
+	/**
+	* Logical paths stored as a single JSON column (`storage === 'json'`,
+	* non-ignored descriptors). Retained after build — unlike the build-time
+	* `jsonFields` set — so the path guard can classify JSON descendants on
+	* relational adapters. Empty on nested-object adapters (they keep native
+	* dotted paths as descriptors).
+	*/
+	jsonParents = /* @__PURE__ */ new Set();
 	_built = false;
 	_identifications;
 	_collateMap = /* @__PURE__ */ new Map();
@@ -160,6 +176,7 @@ var TableMetadata = class {
 		const overrides = adapter.getMetadataOverrides?.(this);
 		if (overrides) this._applyOverrides(overrides);
 		this._buildFieldDescriptors(adapter);
+		this._buildGuardIndexes();
 		if (!this.nestedObjects) this._buildLeafIndexes();
 		this._buildIdentifications();
 		this._resolvePreferredId(type);
@@ -399,6 +416,23 @@ var TableMetadata = class {
 		const lastDot = path.lastIndexOf(".");
 		return lastDot >= 0 ? `${path.slice(0, lastDot).replace(/\./g, "__")}__` : "";
 	}
+	/** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
+	/**
+	* Indexes non-ignored descriptors by logical path and retains the JSON-parent
+	* set. Navigation relations and their descendants are skipped even when the
+	* adapter keeps them as descriptors (nested-object adapters do) — they are
+	* loaded with `$with`, never addressed as columns of this table.
+	*/
+	_buildGuardIndexes() {
+		const jsonParents = /* @__PURE__ */ new Set();
+		for (const fd of this.fieldDescriptors) {
+			if (fd.ignored) continue;
+			if (this.navFields.has(fd.path) || findAncestorInSet(fd.path, this.navFields) !== void 0) continue;
+			this.descriptorByPath.set(fd.path, fd);
+			if (fd.storage === "json") jsonParents.add(fd.path);
+		}
+		this.jsonParents = jsonParents;
+	}
 	/**
 	* Indexes `fieldDescriptors` into two lookup maps for unified
 	* read/write field classification in the RelationalFieldMapper.
@@ -821,8 +855,7 @@ var FieldMappingStrategy = class {
 		if (!fmt) return value;
 		if (value === null || value === void 0) return value;
 		if (typeof value !== "object" || Array.isArray(value)) return fmt(value);
-		const proto = Object.getPrototypeOf(value);
-		if (proto !== Object.prototype && proto !== null) return fmt(value);
+		if (!isPlainObject(value)) return fmt(value);
 		const ops = value;
 		const formatted = {};
 		for (const [op, opVal] of Object.entries(ops)) if ((op === "$in" || op === "$nin") && Array.isArray(opVal)) formatted[op] = opVal.map((v) => v === null || v === void 0 ? v : fmt(v));
@@ -1165,6 +1198,11 @@ var RelationalFieldMapper = class extends FieldMappingStrategy {
 * - `$geoWithin` on a non-geoPoint field → `FILTER_TYPE_MISMATCH`
 * - `$geoWithin` with a malformed circle → `INVALID_QUERY`
 * - `$geoWithin` on an adapter without geo support → `GEO_NOT_SUPPORTED`
+* - every filter / `$sort` / `$select` / `$groupBy` / `$having` / aggregate
+*   path must resolve to physical storage on THIS adapter and pass the
+*   adapter's `canFilterField` / `canSortField` → `INVALID_QUERY`
+*   (see {@link guardPaths}). Runs after the checks above so `ENC_*` codes
+*   keep firing first for encrypted subtrees.
 */
 /** Validates a `[lng, lat]` tuple (GeoJSON coordinate order). */
 function assertGeoPoint(point, path) {
@@ -1231,24 +1269,274 @@ function guardSort(meta, sort) {
 	if (!sort || typeof sort !== "object" || meta.encryptedFields.size === 0) return;
 	for (const key of Object.keys(sort)) if (isEncryptedRef(meta, key)) throw encryptedRefError("ENC_FIELD_SORT", key, "sort by");
 }
-/** Shared read-path guard: filter + $sort. */
+const OP_VERB = {
+	filter: "filter on",
+	sort: "sort by",
+	select: "select",
+	groupBy: "group by",
+	having: "filter ($having) on",
+	aggregate: "aggregate over"
+};
+function pathError(path, message) {
+	return new DbError("INVALID_QUERY", [{
+		path,
+		message
+	}]);
+}
+/**
+* The one wording for a filter-node `$`-key that is not `$and` / `$or` /
+* `$not` (uniqu's walker would treat it as a field named `$…`). The core
+* guard and the HTTP gate both answer with it; `path` is the operator itself.
+*/
+function unsupportedOperatorMessage(op) {
+	return `Unsupported filter operator "${op}" — use $and, $or or $not`;
+}
+/**
+* Normalizes every accepted `$sort` form (`"a,-b"`, `["a", "-b"]`,
+* `[{ a: 1 }]`, `{ a: 1 }`) into its field names. Mirrors the HTTP layer's
+* walker so programmatic callers get the same acceptance set.
+*/
+function sortFieldNames(sort) {
+	if (!sort) return [];
+	if (typeof sort === "string") {
+		const out = [];
+		for (const part of sort.split(",")) {
+			const name = part.trim().replace(/^[-+]/, "").split(":")[0];
+			if (name) out.push(name);
+		}
+		return out;
+	}
+	if (Array.isArray(sort)) {
+		const out = [];
+		for (const entry of sort) if (typeof entry === "string") out.push(entry.replace(/^[-+]/, ""));
+		else if (entry && typeof entry === "object") out.push(...Object.keys(entry));
+		return out;
+	}
+	if (typeof sort === "object") return Object.keys(sort);
+	return [];
+}
+function collectFilterKeys(filter, out, geo, skip, refs) {
+	if (!filter || typeof filter !== "object" || Array.isArray(filter)) return;
+	for (const [key, value] of Object.entries(filter)) {
+		if (refs.unsupportedOperator) return;
+		if (key === "$and" || key === "$or") {
+			if (Array.isArray(value)) for (const child of value) collectFilterKeys(child, out, geo, skip, refs);
+			continue;
+		}
+		if (key === "$not") {
+			collectFilterKeys(value, out, geo, skip, refs);
+			continue;
+		}
+		if (key.startsWith("$")) {
+			refs.unsupportedOperator = key;
+			return;
+		}
+		if (skip?.has(key)) continue;
+		(geo !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) && "$geoWithin" in value ? geo : out).push(key);
+	}
+}
+/**
+* Walks the PARSED query structure (not the flattened insights map, which
+* cannot tell `$select=assignee.name` from `$with=assignee($select=name)`)
+* and returns the root paths per position. `$with` sub-trees are not
+* visited — they are validated against their target relation separately.
+*
+* Aggregate mode is `aggregate` when given, else the presence of `$groupBy`.
+* In aggregate mode `$select` entries are aggregate expressions whose
+* `$field` is collected and whose alias (`$as`, else `fn_field` — the core's
+* `resolveAlias`) is exempted from `$sort` / `$having`; outside it non-string
+* `$select` entries are ignored (the projection seal handles them).
+*/
+function collectQueryPaths(query, aggregate) {
+	const refs = {
+		filter: [],
+		geoFilter: [],
+		sort: [],
+		select: [],
+		groupBy: [],
+		having: [],
+		aggregate: [],
+		aggregateMode: false
+	};
+	collectFilterKeys(query.filter, refs.filter, refs.geoFilter, void 0, refs);
+	const controls = query.controls ?? {};
+	const rawGroupBy = controls.$groupBy;
+	const groupBy = Array.isArray(rawGroupBy) ? rawGroupBy.filter((f) => typeof f === "string") : typeof rawGroupBy === "string" ? [rawGroupBy] : [];
+	refs.aggregateMode = aggregate ?? groupBy.length > 0;
+	refs.groupBy = groupBy;
+	const aliases = /* @__PURE__ */ new Set();
+	const select = controls.$select;
+	if (Array.isArray(select)) {
+		for (const item of select) if (typeof item === "string") refs.select.push(item);
+		else if (refs.aggregateMode && item && typeof item === "object" && "$field" in item) {
+			const expr = item;
+			aliases.add(resolveAlias(expr));
+			if (expr.$field !== "*") refs.aggregate.push(expr.$field);
+		}
+	} else if (select && typeof select === "object") refs.select.push(...Object.keys(select));
+	for (const name of sortFieldNames(controls.$sort)) if (!aliases.has(name)) refs.sort.push(name);
+	if (refs.aggregateMode) collectFilterKeys(controls.$having, refs.having, void 0, aliases, refs);
+	return refs;
+}
+/**
+* Classifies one logical path. The rules exist once, in this order, for the
+* core backstop ({@link guardPath}) and the HTTP capability gate alike:
+*
+* 1. navigation relations (and anything under them) — `parent` is the nav
+*    head when the path is a descendant;
+* 2. a stored leaf;
+* 3. a nested-object parent;
+* 4. a descendant of a JSON-stored column — `parent` names the column;
+* 5. a descendant of an `@db.encrypted` field — `parent` names the field;
+* 6. unknown.
+*/
+function classifyQueryPath(source, path) {
+	if (source.navFields.has(path)) return { kind: "nav" };
+	const navHead = findAncestorInSet(path, source.navFields);
+	if (navHead !== void 0) return {
+		kind: "nav",
+		parent: navHead
+	};
+	if (source.leaves.has(path)) return { kind: "leaf" };
+	if (source.objectParents.has(path)) return { kind: "objectParent" };
+	const jsonParent = findAncestorInSet(path, source.jsonParents);
+	if (jsonParent !== void 0) return {
+		kind: "jsonDescendant",
+		parent: jsonParent
+	};
+	const encryptedParent = findAncestorInSet(path, source.encryptedFields);
+	if (encryptedParent !== void 0) return {
+		kind: "encryptedDescendant",
+		parent: encryptedParent
+	};
+	return { kind: "unknown" };
+}
+/** `TableMetadata` as a {@link TQueryPathSource} (descriptors are the leaves, flattened parents the object parents). */
+function pathSourceOf(meta) {
+	return {
+		navFields: meta.navFields,
+		leaves: meta.descriptorByPath,
+		objectParents: meta.flattenedParents,
+		jsonParents: meta.jsonParents,
+		encryptedFields: meta.encryptedFields
+	};
+}
+/**
+* Validates ONE logical path for ONE query position against this table's
+* metadata and adapter capability — the classification of
+* {@link classifyQueryPath} plus the position's physical requirement:
+*
+* - a leaf → physical capability (`canFilterField` / `canSortField`;
+*   `$select` always passes);
+* - a nested-object parent → only `$select`, and only when it expands to
+*   leaf columns (`selectExpansion`);
+* - everything else is rejected.
+*
+* `geoPredicate` marks a filter entry whose operator is `$geoWithin`: its
+* shape and index support were already validated by {@link guardFilter}, so
+* the adapter's scalar `canFilterField` veto does not apply.
+*
+* Messages are the short programmatic forms; the HTTP wording (moost-db's
+* `FieldCapabilityIndex`, with `$with` hints and leaf lists) is what clients
+* see and is authoritative — the HTTP gate always answers first.
+*/
+function guardPath(meta, adapter, path, op, geoPredicate = false) {
+	const verb = OP_VERB[op];
+	const { kind, parent } = classifyQueryPath(pathSourceOf(meta), path);
+	switch (kind) {
+		case "nav": throw pathError(path, `Cannot ${verb} "${path}" — navigation path`);
+		case "leaf": {
+			if (op === "select") return;
+			const fd = meta.descriptorByPath.get(path);
+			if (op === "sort") {
+				if (!adapter.canSortField(fd)) throw pathError(path, `Cannot sort by "${path}" — adapter cannot sort on this storage type`);
+				return;
+			}
+			if (geoPredicate) return;
+			if (!adapter.canFilterField(fd)) throw pathError(path, `Cannot ${verb} "${path}" — adapter cannot filter on this storage type`);
+			return;
+		}
+		case "objectParent":
+			if (op === "select" && meta.selectExpansion.has(path)) return;
+			throw pathError(path, `Cannot ${verb} "${path}" — nested object; use one of its leaf fields`);
+		case "jsonDescendant": throw pathError(path, `Cannot ${verb} "${path}" — inside JSON-stored column "${parent}"`);
+		case "encryptedDescendant": throw pathError(path, op === "select" ? `Cannot select "${path}" — inside encrypted field "${parent}"; select "${parent}" instead` : `Cannot ${verb} encrypted field "${path}"`);
+		default: throw pathError(path, `Unknown field "${path}"`);
+	}
+}
+/**
+* Core backstop for every read / aggregate / mutation-filter entry point:
+* each referenced path (see {@link collectQueryPaths}) must exist on THIS
+* adapter with the physical capability the position needs (see
+* {@link guardPath}). Adapters may therefore assume every path they receive
+* is physical.
+*
+* In aggregate mode (`aggregate = true`) `$select` entries are aggregate
+* expressions whose `$field` is checked, `$groupBy` fields are checked, and
+* aggregate aliases (`$as` or `fn_field`) are exempt in `$sort` / `$having`.
+*
+* Returns the collected refs so callers can run further structural rules
+* (see {@link checkHavingKeys}) without walking the query again.
+*/
+function guardPaths(meta, adapter, query, aggregate = false) {
+	if (!query) return;
+	const refs = collectQueryPaths(query, aggregate);
+	if (refs.unsupportedOperator !== void 0) throw pathError(refs.unsupportedOperator, unsupportedOperatorMessage(refs.unsupportedOperator));
+	for (const path of refs.filter) guardPath(meta, adapter, path, "filter");
+	for (const path of refs.geoFilter) guardPath(meta, adapter, path, "filter", true);
+	for (const path of refs.sort) guardPath(meta, adapter, path, "sort");
+	for (const path of refs.select) guardPath(meta, adapter, path, "select");
+	for (const path of refs.aggregate) guardPath(meta, adapter, path, "aggregate");
+	for (const path of refs.groupBy) guardPath(meta, adapter, path, "groupBy");
+	for (const path of refs.having) guardPath(meta, adapter, path, "having");
+	return refs;
+}
+/** Shared read-path guard: filter + $sort encryption checks, then the path guard. */
 function guardQuery(meta, adapter, query) {
 	if (!query) return;
 	guardFilter(meta, adapter, query.filter);
 	guardSort(meta, query.controls?.$sort);
+	guardPaths(meta, adapter, query);
+}
+/**
+* `$having` is a post-aggregation filter, so a key is either an aggregate
+* alias (`$as`, else `fn_field` — already exempt in {@link collectQueryPaths})
+* or a `$groupBy` field (exact logical-path match: `metadata.clicks` grouped
+* stays valid). Any other key — a real but non-grouped column included — is
+* rejected here, once, for SDK and HTTP callers alike, instead of by the
+* engine (PostgreSQL / MySQL error, SQLite tolerance, Mongo `[]`). Returns
+* the first offending key as an error entry (`path` = the bare key, as the
+* `Unknown field` rejection uses); `undefined` when every key is valid.
+*/
+function checkHavingKeys(refs) {
+	if (refs.having.length === 0) return;
+	const grouped = new Set(refs.groupBy);
+	for (const key of refs.having) if (!grouped.has(key)) return {
+		path: key,
+		message: `$having key "${key}" must be an aggregate alias or a $groupBy field`
+	};
 }
-/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+/**
+* Aggregate-path guard: $groupBy / $select / $having encryption refs + filter
+* + $sort, then the path guard, then the `$having` key rule
+* ({@link checkHavingKeys} — after the path guard so an unknown key still
+* reads `Unknown field`).
+*/
 function guardAggregate(meta, adapter, query) {
 	guardFilter(meta, adapter, query.filter);
-	if (meta.encryptedFields.size === 0) return;
 	const controls = query.controls;
-	for (const field of controls.$groupBy ?? []) if (isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "group by");
-	if (controls.$select) for (const item of controls.$select) {
-		const field = typeof item === "string" ? item : item.$field;
-		if (field !== "*" && isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "aggregate over");
+	if (meta.encryptedFields.size > 0) {
+		for (const field of controls.$groupBy ?? []) if (isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "group by");
+		if (controls.$select) for (const item of controls.$select) {
+			const field = typeof item === "string" ? item : item.$field;
+			if (field !== "*" && isEncryptedRef(meta, field)) throw encryptedRefError("ENC_FIELD_AGG", field, "aggregate over");
+		}
+		if (controls.$having) guardFilter(meta, adapter, controls.$having, "ENC_FIELD_AGG");
+		guardSort(meta, controls.$sort);
 	}
-	if (controls.$having) guardFilter(meta, adapter, controls.$having, "ENC_FIELD_AGG");
-	guardSort(meta, controls.$sort);
+	const refs = guardPaths(meta, adapter, query, true);
+	const having = refs ? checkHavingKeys(refs) : void 0;
+	if (having) throw new DbError("INVALID_QUERY", [having]);
 }
 //#endregion
 //#region src/table/db-readable.ts
@@ -1761,15 +2049,7 @@ var AtscriptDbReadable = class {
 		}
 		guardAggregate(this._meta, this.adapter, query);
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
-		return (await this.adapter.aggregate(dbQuery)).map((row) => {
-			const mapped = {};
-			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;
-		});
+		return (await this.adapter.aggregate(dbQuery)).map((row) => this._fieldMapper.reconstructFromRead(row, this._meta));
 	}
 	/** Whether the underlying adapter supports text search. */
 	isSearchable() {
@@ -2065,7 +2345,7 @@ var AtscriptDbReadable = class {
 	* Public entry point for relation loading. Used by adapters for nested $with delegation.
 	*/
 	async loadRelations(rows, withRelations) {
-		const { loadRelationsImpl } = await import("./relation-loader-BmeOMj0b.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-CUGcxJ18.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -2131,6 +2411,10 @@ function createFailureCollector(what) {
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
 const txStorage = new AsyncLocalStorage();
+/** The innermost open transaction of `owner` in the current async chain. */
+function findTxContext(owner) {
+	for (let ctx = txStorage.getStore(); ctx; ctx = ctx.parent) if (ctx.owner === owner) return ctx;
+}
 /**
 * Abstract base class for database adapters.
 *
@@ -2155,6 +2439,15 @@ const txStorage = new AsyncLocalStorage();
 * - `this._table.isView` — whether this is a view (vs a table)
 */
 var BaseDbAdapter = class {
+	/**
+	* The readable this adapter serves. UNSET on an administrative adapter:
+	* `DbSpace` creates one from the factory without a readable for the
+	* name-taking schema-sync primitives (`dropTableByName`, `dropViewByName`,
+	* `dropTablesByName`, `getReferencingForeignKeys`, `getObjectKind`,
+	* `getExistingColumnsForTable`, `hasRows(tableName)`), so those must derive
+	* everything — the schema included — from the driver/connection, never from
+	* `this._table`.
+	*/
 	_table;
 	/**
 	* Resolves the correct insertedId: prefers the user-supplied PK value
@@ -2194,15 +2487,22 @@ var BaseDbAdapter = class {
 	}
 	/**
 	* Runs `fn` inside a database transaction. Nested calls (from related tables
-	* within the same async chain) reuse the existing transaction automatically.
+	* within the same async chain) reuse the existing transaction automatically
+	* — "existing" meaning a transaction of the same {@link _transactionOwner};
+	* inside another adapter family's transaction this opens its own.
 	*
 	* 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 };
+		const owner = this._transactionOwner();
+		if (findTxContext(owner)) return fn();
+		const ctx = {
+			owner,
+			state: void 0,
+			parent: txStorage.getStore()
+		};
 		ctx.state = await this._beginTransaction();
 		return txStorage.run(ctx, async () => {
 			try {
@@ -2218,22 +2518,39 @@ var BaseDbAdapter = class {
 		});
 	}
 	/**
-	* Returns the opaque transaction state from the current async context.
+	* The object a transaction state is branded with (since 0.1.128). Every
+	* adapter instance that returns the same owner shares one transaction —
+	* override to return the driver / pool / client the adapter was constructed
+	* with, so all tables of a space join it. The default (the adapter class)
+	* suits adapters without a connection object (in-memory, mocks).
+	*/
+	_transactionOwner() {
+		return this.constructor;
+	}
+	/**
+	* Returns the opaque transaction state of THIS adapter's owner from the
+	* current async context — `undefined` when no transaction is open or only
+	* another adapter family's transaction is (its state is never handed out).
 	* Adapters use this to retrieve DB-specific state (e.g., MongoDB `ClientSession`).
 	*/
 	_getTransactionState() {
-		return txStorage.getStore()?.state;
+		return findTxContext(this._transactionOwner())?.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.
+	* If a context of the same owner already exists (nesting), it's reused.
 	*/
 	_runInTransactionContext(state, fn) {
-		if (txStorage.getStore()) return fn();
-		return txStorage.run({ state }, fn);
+		const owner = this._transactionOwner();
+		if (findTxContext(owner)) return fn();
+		return txStorage.run({
+			owner,
+			state,
+			parent: txStorage.getStore()
+		}, fn);
 	}
 	/**
 	* Starts a raw transaction. Returns opaque state stored in the async context.
@@ -2282,11 +2599,14 @@ var BaseDbAdapter = class {
 		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.
+	* Whether the DB engine carries static `@db.default "value"` defaults in
+	* its DDL (`DEFAULT` clauses in `CREATE TABLE`).
+	*
+	* @deprecated since 0.1.128 — no longer consulted: the table layer fills
+	* static value defaults SDK-side on every adapter before validation, and the
+	* SQL adapters emit their DDL `DEFAULT` clauses regardless of this flag.
+	* Kept as a capability hint for tooling; nothing in the generic layer
+	* branches on it.
 	*/
 	supportsNativeValueDefaults() {
 		return false;
@@ -2332,12 +2652,16 @@ var BaseDbAdapter = class {
 	}
 	/**
 	* Whether this adapter can sort by a given field.
-	* Default: scalar columns yes, JSON-stored columns no. Mongo's array sort
-	* (min/max element) is a footgun for generic UI sort headers, so the default
-	* stays conservative even for adapters that technically support it.
+	* Default: scalar columns yes; JSON-stored columns, `@db.json` objects and
+	* arrays no. Mongo's array sort (min/max element) is a footgun for generic
+	* UI sort headers, so the default stays conservative even for adapters that
+	* technically support it — the veto keys on `designType` as well as
+	* `storage` because nested-object adapters keep arrays / `@db.json` values
+	* inline as `storage: 'column'` (since 0.1.128).
 	*/
 	canSortField(fd) {
 		if (fd.encrypted || fd.isGeoPoint) return false;
+		if (fd.designType === "json" || fd.designType === "array") return false;
 		return fd.storage !== "json";
 	}
 	/**
@@ -2387,6 +2711,7 @@ var BaseDbAdapter = class {
 	* @param includeSchema - Whether to prepend `schema.` prefix (default: true).
 	*/
 	resolveTableName(includeSchema = true) {
+		if (!this._table) throw new Error("Adapter has no registered readable: table-scoped operations need a table/view; on an administrative adapter use the name-taking primitives (dropTableByName, hasRows(tableName), …)");
 		const schema = this._table.schema;
 		const name = this._table.tableName;
 		return includeSchema && schema ? `${schema}.${name}` : name;
@@ -2428,7 +2753,7 @@ var BaseDbAdapter = class {
 			}
 			if (index.type === "plain" || index.type === "unique") {
 				const liveColumns = existingColumns.get(index.key);
-				const desiredColumns = index.fields.map((f) => f.name);
+				const desiredColumns = index.fields.map((f) => opts.renderDesiredColumn?.(index, f) ?? f.name);
 				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) await attempt(`rebuild index "${index.key}"`, async () => {
 					await opts.dropIndex(index.key);
 					await opts.createIndex(index);
@@ -2576,6 +2901,39 @@ var BaseDbAdapter = class {
 	* instead of requiring `@db.sync.method "recreate"` or `"drop"`.
 	*/
 	supportsColumnModify;
+	/**
+	* Drops several tables that reference each other (a foreign-key cycle) as
+	* one operation. Schema sync only calls this for cycles whose members are
+	* ALL being removed. Default: {@link dropTableByName} in the given order —
+	* enough for engines that tolerate it (SQLite with FK checks off, MySQL with
+	* FOREIGN_KEY_CHECKS=0); PostgreSQL overrides it with one multi-table
+	* `DROP TABLE a, b` statement.
+	* @since 0.1.128
+	*/
+	async dropTablesByName(tableNames) {
+		for (const name of tableNames) await this.dropTableByName?.(name);
+	}
+	/**
+	* Whether the table has at least one row. Schema sync uses it in the
+	* pre-flight phase to refuse a primary-key change on a populated table.
+	* Override with an EXISTS/LIMIT 1 probe — this default is `count() > 0`,
+	* a full scan on some engines, and it can only answer for the adapter's
+	* OWN table: for another `tableName` (or on an administrative adapter
+	* without a readable) it returns `undefined` ("cannot tell"), which schema
+	* sync treats as a refusal.
+	*
+	* @param tableName - Check this table instead of the adapter's own (schema
+	*   sync passes the OLD name of a table that is about to be renamed).
+	* @returns `true`/`false`, or `undefined` when the adapter cannot tell.
+	* @since 0.1.128
+	*/
+	async hasRows(tableName) {
+		if (tableName !== void 0 && tableName !== this._table?.tableName) return;
+		return await this.count({
+			filter: {},
+			controls: {}
+		}) > 0;
+	}
 };
 //#endregion
 //#region src/strategies/application-integrity.ts
@@ -3035,11 +3393,104 @@ function _hasOperatorKeys(value) {
 * @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;
+/**
+* Clones a write payload while dropping every own key whose value is
+* `=== undefined` (`undefined` ≡ absent; `null` stays an explicit NULL), so
+* that defaults, validation, encryption and decomposition never see an
+* `undefined` prop.
+*
+* Recurses into plain objects and into arrays at any depth (plain-object
+* elements are cloned, elements are never dropped or reordered) and never
+* into class instances (`Date`, `Uint8Array`/`Buffer`, `ObjectId`, …), which
+* are kept by reference. Arrays without plain-object elements anywhere below
+* them are kept by reference too. The caller's payload tree is never mutated.
+* @internal exported for the core spec only — not part of the package surface.
+*/
+function _cloneWritePayload(source) {
+	if (typeof source !== "object" || source === null) return { ...source };
+	const out = {};
+	for (const key of Object.keys(source)) {
+		const value = source[key];
+		if (value === void 0) continue;
+		out[key] = _cloneWriteValue(value);
+	}
+	return out;
 }
+function _cloneWriteValue(value) {
+	if (Array.isArray(value)) {
+		let cloned;
+		for (let i = 0; i < value.length; i++) {
+			const el = value[i];
+			if (isPlainObject(el) || Array.isArray(el)) {
+				const c = _cloneWriteValue(el);
+				if (c !== el) {
+					cloned ??= value.slice();
+					cloned[i] = c;
+				}
+			}
+		}
+		return cloned ?? value;
+	}
+	return isPlainObject(value) ? _cloneWritePayload(value) : value;
+}
+/**
+* The clone for a nested re-entry (`_depth > 0`) and for `preValidateItems`:
+* the root call already deep-pruned the whole tree, so only the row's own
+* keys are (re-)pruned — no recursion, no per-level re-cloning of subtrees.
+*/
+function _shallowPrunedClone(source) {
+	const out = {};
+	for (const key in source) {
+		const value = source[key];
+		if (value !== void 0) out[key] = value;
+	}
+	return out;
+}
+/**
+* {@link TDbWriteGuardContext} handed to a write guard: a sparse per-index
+* cache of pre-image reads, allocated only when `current(i)` is first used.
+*/
+var WriteGuardContext = class {
+	action;
+	rows;
+	expectedVersions;
+	_table;
+	_pending;
+	constructor(action, rows, expectedVersions, _table) {
+		this.action = action;
+		this.rows = rows;
+		this.expectedVersions = expectedVersions;
+		this._table = _table;
+	}
+	current(i) {
+		const cache = this._pending ??= [];
+		let pending = cache[i];
+		if (!pending) {
+			pending = this._table._readPreImage(this.rows[i]);
+			cache[i] = pending;
+		}
+		return pending;
+	}
+};
+/** {@link TDbRemoveGuardContext} handed to a delete guard (one memoised pre-image read). */
+var RemoveGuardContext = class {
+	id;
+	filter;
+	_table;
+	_pending;
+	constructor(id, filter, _table) {
+		this.id = id;
+		this.filter = filter;
+		this._table = _table;
+	}
+	current() {
+		this._pending ??= this._table.findOne({
+			filter: this.filter,
+			controls: {}
+		});
+		return this._pending;
+	}
+};
 /** Translates a single ops record from logical to physical column names. */
 function _translateOpsRecord(rec, meta) {
 	const out = {};
@@ -3053,6 +3504,15 @@ function _translateOpsKeys(ops, meta) {
 		mul: ops.mul ? _translateOpsRecord(ops.mul, meta) : void 0
 	};
 }
+/** Upper bound of keys per `touchMany` UPDATE statement (parameter-count safety). */
+const TOUCH_MANY_CHUNK = 500;
+/** `touchMany` input rejection — always `INVALID_QUERY`, path names the key. */
+function invalidTouchKey(path, message) {
+	return new DbError("INVALID_QUERY", [{
+		path,
+		message
+	}]);
+}
 var AtscriptDbTable = class extends AtscriptDbReadable {
 	_cascadeResolver;
 	_fkLookupResolver;
@@ -3097,7 +3557,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* nested creation support.
 	*/
 	async insertOne(payload, opts) {
-		return { insertedId: (await this.insertMany([payload], opts)).insertedIds[0] };
+		return { insertedId: (await this.insertMany([payload], {
+			...opts,
+			_action: "insert"
+		})).insertedIds[0] };
 	}
 	/**
 	* Inserts multiple records with batch-optimized nested creation.
@@ -3109,16 +3572,21 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* (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).
+	*
+	* `opts.guard` (since 0.1.128) runs once inside the transaction, after
+	* defaults + validation, with the prepared rows — see {@link TWriteOptions}.
 	*/
 	async insertMany(payloads, opts) {
 		this._ensureBuilt();
-		const { _depth, maxDepth: userMax } = opts ?? {};
+		const { _depth, _action, maxDepth: userMax, guard } = opts ?? {};
 		const maxDepth = userMax ?? 3;
 		const depth = _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 clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
+			const items = payloads.map((p) => this._applyDefaults(clone(p)));
+			const originals = canNest ? items.map((item) => ({ ...item })) : [];
 			const validator = this.getValidator("insert");
 			const ctx = {
 				mode: "insert",
@@ -3126,6 +3594,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, items, ctx);
+			if (guard) {
+				await guard(new WriteGuardContext(_action ?? "insertMany", items, Array.from({ length: items.length }), this));
+				validateBatch(validator, items, ctx);
+			}
 			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await batchInsertNestedTo(host, items, maxDepth, depth);
@@ -3135,10 +3607,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				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);
+			if (canNest) await preValidateNestedFrom(host, originals);
 			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);
+			if (canNest) await batchInsertNestedFrom(host, originals, result.insertedIds, maxDepth, depth);
+			if (canNest) await batchInsertNestedVia(host, originals, result.insertedIds, maxDepth, depth);
 			return result;
 		}));
 	}
@@ -3147,7 +3619,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* Delegates to {@link bulkReplace} for unified nested relation support.
 	*/
 	async replaceOne(payload, opts) {
-		return this.bulkReplace([payload], opts);
+		return this.bulkReplace([payload], {
+			...opts,
+			_action: "replace"
+		});
 	}
 	/**
 	* Replaces multiple records with deep nested relation support.
@@ -3156,22 +3631,27 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 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).
+	*
+	* `opts.guard` (since 0.1.128) runs once inside the transaction, after
+	* `$cas` extraction, defaults + validation — see {@link TWriteOptions}.
 	*/
 	async bulkReplace(payloads, opts) {
 		this._ensureBuilt();
-		const maxDepth = opts?.maxDepth ?? 3;
-		const depth = opts?._depth ?? 0;
+		const { _depth, _action, maxDepth: userMax, guard } = opts ?? {};
+		const maxDepth = userMax ?? 3;
+		const depth = _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 versionColumn = this.versionColumn;
 			const expectedVersions = Array.from({ length: payloads.length });
+			const clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
 			const items = payloads.map((p, i) => {
-				const clone = { ...p };
-				expectedVersions[i] = separateCas(clone, versionColumn);
-				return this._applyDefaults(clone);
+				const c = clone(p);
+				expectedVersions[i] = separateCas(c, versionColumn);
+				return this._applyDefaults(c);
 			});
-			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
+			const originals = canNest ? items.map((item) => ({ ...item })) : [];
 			const validator = this.getValidator("bulkReplace");
 			const ctx = {
 				mode: "replace",
@@ -3179,6 +3659,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, items, ctx);
+			if (guard) {
+				await guard(new WriteGuardContext(_action ?? "replaceMany", items, expectedVersions, this));
+				validateBatch(validator, items, ctx);
+			}
 			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await batchReplaceNestedTo(host, items, maxDepth, depth);
@@ -3209,7 +3693,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* Delegates to {@link bulkUpdate} for unified nested relation support.
 	*/
 	async updateOne(payload, opts) {
-		return this.bulkUpdate([payload], opts);
+		return this.bulkUpdate([payload], {
+			...opts,
+			_action: "update"
+		});
 	}
 	/**
 	* Partially updates multiple records with deep nested relation support.
@@ -3217,18 +3704,24 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 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).
+	*
+	* `opts.guard` (since 0.1.128) runs once inside the transaction, after
+	* `$cas` extraction and validation, with the patches (identifying fields
+	* present, `$cas` removed) — see {@link TWriteOptions}.
 	*/
 	async bulkUpdate(payloads, opts) {
 		this._ensureBuilt();
-		const maxDepth = opts?.maxDepth ?? 3;
-		const depth = opts?._depth ?? 0;
+		const { _depth, _action, maxDepth: userMax, guard } = opts ?? {};
+		const maxDepth = userMax ?? 3;
+		const depth = _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 versionColumn = this.versionColumn;
 			const expectedVersions = Array.from({ length: payloads.length });
+			const clone = depth === 0 ? _cloneWritePayload : _shallowPrunedClone;
 			const cloned = payloads.map((p, i) => {
-				const c = { ...p };
+				const c = clone(p);
 				expectedVersions[i] = separateCas(c, versionColumn);
 				return c;
 			});
@@ -3240,6 +3733,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, cloned, ctx);
+			if (guard) {
+				await guard(new WriteGuardContext(_action ?? "updateMany", cloned, expectedVersions, this));
+				validateBatch(validator, cloned, ctx);
+			}
 			const originals = canNest ? cloned.map((p) => ({ ...p })) : [];
 			await this._encryptItems(cloned, "patch");
 			const host = this;
@@ -3255,13 +3752,16 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				const filter = this._extractRecordFilter(data);
 				for (const key of Object.keys(filter)) delete data[key];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
-				if (_isEmptyObj(data)) {
-					matchedCount += 1;
-					modifiedCount += 0;
+				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
+				if (isEmptyObject(data) && expectedVersion === void 0) {
+					const exists = await this.adapter.count({
+						filter: translatedFilter,
+						controls: {}
+					});
+					matchedCount += exists > 0 ? 1 : 0;
 					continue;
 				}
 				let result;
-				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
 				if (this.adapter.supportsNativePatch()) {
 					const ops = separateFieldOps(data);
 					const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
@@ -3292,27 +3792,114 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		}));
 	}
 	/**
+	* Batch versioned touch (since 0.1.129): bumps the version of every listed
+	* row by exactly one, each row guarded by its own expected version. This is
+	* the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
+	* empty patch is a no-op since then and takes no lock).
+	*
+	* Each key carries the primary key field(s) (composite supported) plus the
+	* version column and NOTHING else — a touch has no payload. Unique indexes
+	* do not identify a touch key. `undefined`-valued properties are ignored,
+	* like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
+	*
+	* `require: 'all'` (default): one count over the whole key set runs FIRST;
+	* a stale or missing row throws {@link CasMismatchError} before any write.
+	* The bumps then run as `updateMany(orFilter, {})` chunks of at most
+	* {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
+	* `matchedCount` short of `keys.length` (a row moved between the count and
+	* the bump) throws the same error — SQL engines roll every bump back. The
+	* pre-count is therefore a deliberate double check on SQL: it is what makes
+	* the guarantee hold on adapters whose `withTransaction` is a passthrough
+	* (the memory adapter, a Mongo standalone topology) — there it covers the
+	* common stale case and the residual race window is accepted.
+	* `require: 'any'`: no pre-count, the honest summed result is returned.
+	*
+	* No `guard`, no `onWrite`; not exposed over HTTP.
+	*/
+	async touchMany(keys, opts) {
+		this._ensureBuilt();
+		const versionField = this._meta.versionField;
+		if (versionField === void 0) throw invalidTouchKey("", "touchMany requires @db.column.version");
+		if (keys.length === 0) return {
+			matchedCount: 0,
+			modifiedCount: 0
+		};
+		const pkFields = this.primaryKeys;
+		const seen = /* @__PURE__ */ new Set();
+		const pairs = [];
+		for (const [i, key] of keys.entries()) {
+			const pair = {};
+			for (const pk of pkFields) {
+				if (key[pk] === void 0) throw invalidTouchKey(`[${i}].${pk}`, `touchMany: each key must carry its "${pk}"`);
+				pair[pk] = key[pk];
+			}
+			const version = key[versionField];
+			if (typeof version !== "number" || !Number.isFinite(version)) throw invalidTouchKey(`[${i}].${versionField}`, `touchMany: each key must carry its expected "${versionField}" (number)`);
+			for (const [prop, value] of Object.entries(key)) if (value !== void 0 && prop !== versionField && !(prop in pair)) throw invalidTouchKey(`[${i}].${prop}`, `touchMany: a touch carries no payload — keys hold the primary key and "${versionField}" only, got "${prop}"`);
+			const identity = JSON.stringify(pair);
+			if (seen.has(identity)) throw invalidTouchKey(`[${i}]`, `touchMany: duplicate key ${identity}`);
+			seen.add(identity);
+			pair[versionField] = version;
+			pairs.push(pair);
+		}
+		const orFilter = { $or: pairs };
+		this._guardMutationFilter(orFilter);
+		const translated = this._fieldMapper.translateFilter(orFilter, this._meta).$or;
+		const requireAll = (opts?.require ?? "all") === "all";
+		if (requireAll) {
+			const matched = await this.adapter.count({
+				filter: { $or: translated },
+				controls: {}
+			});
+			if (matched < keys.length) throw new CasMismatchError(matched, keys.length);
+		}
+		return this.adapter.withTransaction(async () => {
+			let matchedCount = 0;
+			let modifiedCount = 0;
+			for (let start = 0; start < translated.length; start += TOUCH_MANY_CHUNK) {
+				const chunk = translated.slice(start, start + TOUCH_MANY_CHUNK);
+				const result = await this.adapter.updateMany({ $or: chunk }, {}, void 0);
+				matchedCount += result.matchedCount;
+				modifiedCount += result.modifiedCount;
+			}
+			if (requireAll && matchedCount !== keys.length) throw new CasMismatchError(matchedCount, keys.length);
+			return {
+				matchedCount,
+				modifiedCount
+			};
+		});
+	}
+	/**
 	* Deletes a single record by any type-compatible identifier — primary key
 	* or single-field unique index. Uses the same resolution logic as `findById`.
 	*
 	* When the adapter does not support native foreign keys (e.g. MongoDB),
 	* cascade and setNull actions are applied before the delete.
+	*
+	* `opts.guard` (since 0.1.128) runs inside the transaction once the id has
+	* resolved to a filter, before cascade / delete — see {@link TDeleteOptions}.
+	* An id that resolves to no filter answers `{ deletedCount: 0 }` without
+	* calling the guard.
 	*/
-	async deleteOne(id) {
+	async deleteOne(id, opts) {
 		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)));
+		const guard = opts?.guard;
+		const needsCascade = this._integrity.needsCascade(this._cascadeResolver);
+		const translated = this._fieldMapper.translateFilter(filter, this._meta);
+		const run = async () => {
+			if (guard) await guard(new RemoveGuardContext(id, filter, this));
+			if (needsCascade) await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
+			return this.adapter.deleteOne(translated);
+		};
+		return remapDeleteFkViolation(this.tableName, () => guard || needsCascade ? this.adapter.withTransaction(run) : run());
 	}
 	async updateMany(filter, data) {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
 		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver, true);
-		const dataCopy = { ...data };
+		const dataCopy = _cloneWritePayload(data);
 		const versionColumn = this.versionColumn;
 		if ("$cas" in dataCopy) throw new DbError("INVALID_QUERY", [{
 			path: "$cas",
@@ -3324,13 +3911,21 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const ops = separateFieldOps(update);
 		const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
 		const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
-		return enrichFkViolation(this._meta, () => this.adapter.updateMany(this._fieldMapper.translateFilter(filter, this._meta), translatedUpdate, translatedOps));
+		const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
+		if (translatedOps === void 0 && isEmptyObject(translatedUpdate)) return {
+			matchedCount: await this.adapter.count({
+				filter: translatedFilter,
+				controls: {}
+			}),
+			modifiedCount: 0
+		};
+		return enrichFkViolation(this._meta, () => this.adapter.updateMany(translatedFilter, translatedUpdate, translatedOps));
 	}
 	async replaceMany(filter, data) {
 		this._ensureBuilt();
 		this._guardMutationFilter(filter);
 		await this._integrity.validateForeignKeys([data], this._meta, this._fkLookupResolver, this._writeTableResolver);
-		const dataCopy = { ...data };
+		const dataCopy = _cloneWritePayload(data);
 		await this._encryptItems([dataCopy], "write");
 		return enrichFkViolation(this._meta, () => this.adapter.replaceMany(this._fieldMapper.translateFilter(filter, this._meta), this._fieldMapper.prepareForWrite(dataCopy, this._meta, this.adapter)));
 	}
@@ -3360,6 +3955,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	/** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
 	_guardMutationFilter(filter) {
 		guardFilter(this._meta, this.adapter, filter);
+		guardPaths(this._meta, this.adapter, { filter });
 	}
 	/**
 	* Encrypts `@db.encrypted` field values in place on (already validated)
@@ -3389,21 +3985,43 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		}
 	}
 	/**
-	* 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.
+	* Lazy pre-image read for a guard's `current(i)`: `null` when the row has
+	* no identifying key (e.g. an auto-increment insert) or the key cannot be
+	* resolved — never throws for a missing key.
+	* @internal
+	*/
+	async _readPreImage(row) {
+		if (!row) return null;
+		let filter;
+		try {
+			filter = this._resolveIdFilter(row);
+		} catch {
+			return null;
+		}
+		if (!filter) return null;
+		return await this.findOne({
+			filter,
+			controls: {}
+		});
+	}
+	/**
+	* Applies `@db.default` values in place to a row's absent fields — the
+	* defaults pass every insert / replace path runs before validation.
+	* Static value defaults (`@db.default 'x'`) are filled on EVERY adapter
+	* (since 0.1.128 — writing the column's own default explicitly is
+	* equivalent to leaving it to the DDL `DEFAULT`, and write guards see the
+	* full row). Function defaults (`now` / `uuid` / `increment` / custom) the
+	* adapter handles natively are NOT filled — the field stays absent so the
+	* engine's own default applies. The version column is never touched.
 	*/
 	_applyDefaults(data) {
-		const nativeValues = this.adapter.supportsNativeValueDefaults();
 		const nativeFns = this.adapter.nativeDefaultFns();
 		const versionField = this._meta.versionField;
 		for (const [field, def] of this._meta.defaults.entries()) {
 			if (field === versionField) continue;
 			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) {
+				if (def.kind === "value") data[field] = this._parseValueDefault(field, def.value);
+				else if (def.kind === "fn" && !nativeFns.has(def.fn)) switch (def.fn) {
 					case "now":
 						data[field] = Date.now();
 						break;
@@ -3416,6 +4034,22 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		return data;
 	}
 	/**
+	* The JS value for a `@db.default 'literal'`: strings (including unions of
+	* string literals) are used as-is, every other design type is parsed as
+	* JSON — the same value the SQL adapters put into the DDL `DEFAULT` clause.
+	* A literal that is not valid JSON falls back to the raw string so the
+	* validator reports it against the field instead of a bare `SyntaxError`.
+	*/
+	_parseValueDefault(field, literal) {
+		const fieldType = this._meta.flatMap?.get(field);
+		if ((fieldType ? resolveDesignType(fieldType) : "string") === "string") return literal;
+		try {
+			return JSON.parse(literal);
+		} catch {
+			return literal;
+		}
+	}
+	/**
 	* Extracts a record-identifying filter from a payload.
 	*
 	* Resolution order:
@@ -3521,7 +4155,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			mode: "insert",
 			navFields: this._meta.navFields
 		};
-		validateBatch(validator, items.map((raw) => this._applyDefaults({ ...raw })), ctx);
+		validateBatch(validator, items.map((raw) => this._applyDefaults(_shallowPrunedClone(raw))), ctx);
 		await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver, false, opts?.excludeFkTargetTable);
 	}
 	/**
@@ -3535,22 +4169,6 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const adapterPlugins = this.adapter.getValidatorPlugins();
 		if (purpose === "insert" || purpose === "patch" || purpose === "bulkReplace") {
 			const mode = purpose === "bulkReplace" ? "replace" : purpose;
-			const versionField = this._meta.versionField;
-			if (versionField !== void 0) {
-				const plugins = adapterPlugins.length ? [...adapterPlugins, dbPlugin] : [dbPlugin];
-				return this.createValidator({
-					plugins,
-					partial: mode === "patch" ? buildPatchPartial(this._meta.navFields) : false,
-					replace: (def, path) => {
-						const transformed = forceNavNonOptional(def);
-						if (path === versionField && !transformed.optional) return {
-							...transformed,
-							optional: true
-						};
-						return transformed;
-					}
-				});
-			}
 			return buildDbValidator(this.type, mode, adapterPlugins);
 		}
 		if (purpose === "bulkUpdate") {
@@ -3664,7 +4282,9 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 			"db.agg.min",
 			"db.agg.max"
 		];
+		const ignored = this.ignoredFields;
 		for (const [fieldName, fieldType] of this._type.type.props.entries()) {
+			if (ignored.has(fieldName)) continue;
 			let aggFn;
 			let aggField;
 			for (const key of aggKeys) {
@@ -3700,5 +4320,17 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		return mappings;
 	}
 };
+/**
+* Structural type guard for views: `true` when the readable reports
+* `isView`, whether or not it is an `AtscriptDbView` instance of THIS copy
+* of `@atscript/db`. Adapters must use this (or `readable.isView`) instead of
+* `instanceof AtscriptDbView` — in a bundle that carries two copies of the
+* core (app bundle + external adapter), `instanceof` is false and the adapter
+* would create an empty physical table under the view's name.
+* @since 0.1.128
+*/
+function isAtscriptDbView(readable) {
+	return readable.isView;
+}
 //#endregion
-export { NoopLogger as C, isGeoPointType as S, DocumentFieldMapper as _, ApplicationIntegrity as a, TableMetadata as b, IntegrityStrategy as c, resolveDesignType as d, assertGeoPoint as f, RelationalFieldMapper as g, guardQuery as h, decomposePatch as i, NativeIntegrity as l, guardFilter as m, AtscriptDbTable as n, BaseDbAdapter as o, guardAggregate as p, assertNoVersionWrites as r, createFailureCollector as s, AtscriptDbView as t, AtscriptDbReadable as u, FieldMappingStrategy as v, isGeoIndexableType as x, UniquSelect as y };
+export { isGeoIndexableType as A, unsupportedOperatorMessage as C, UniquSelect as D, FieldMappingStrategy as E, NoopLogger as M, TableMetadata as O, sortFieldNames as S, DocumentFieldMapper as T, guardAggregate as _, decomposePatch as a, guardPaths as b, createFailureCollector as c, AtscriptDbReadable as d, resolveDesignType as f, collectQueryPaths as g, classifyQueryPath as h, assertNoVersionWrites as i, isGeoPointType as j, findAncestorInSet as k, IntegrityStrategy as l, checkHavingKeys as m, isAtscriptDbView as n, ApplicationIntegrity as o, assertGeoPoint as p, AtscriptDbTable as r, BaseDbAdapter as s, AtscriptDbView as t, NativeIntegrity as u, guardFilter as v, RelationalFieldMapper as w, guardQuery as x, guardPath as y };