@atscript/db 0.1.127 → 0.1.129

package/dist/{db-view-BP0Qbeux.cjs → db-view-CRBgkEp0.cjs}

@@ -1,8 +1,8 @@
-const require_db_error = require("./db-error-DXwEzmYJ.cjs");
+const require_db_error = require("./db-error-C4JuLcvb.cjs");
+const require_validator = require("./validator-lkCJKuoo.cjs");
 const require_agg = require("./agg.cjs");
-const require_nested_writer = require("./nested-writer-DoDhl3X3.cjs");
+const require_nested_writer = require("./nested-writer-DxPhmWFz.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-CSGug4vg.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let node_async_hooks = require("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 (!require_validator.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 require_db_error.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(require_agg.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);
 }
-/** Aggregate-path guard: $groupBy / $select / $having refs + filter + $sort. */
+/**
+* `$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 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 require_db_error.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 Promise.resolve().then(() => require("./relation-loader-BnUgJsUG.cjs")).then((n) => n.relation_loader_exports);
+		const { loadRelationsImpl } = await Promise.resolve().then(() => require("./relation-loader-C8GOpNYJ.cjs")).then((n) => n.relation_loader_exports);
 		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 node_async_hooks.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 node_async_hooks.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 (require_validator.isPlainObject(el) || Array.isArray(el)) {
+				const c = _cloneWriteValue(el);
+				if (c !== el) {
+					cloned ??= value.slice();
+					cloned[i] = c;
+				}
+			}
+		}
+		return cloned ?? value;
+	}
+	return require_validator.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 require_db_error.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) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		return require_nested_writer.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);
 			require_nested_writer.validateBatch(validator, items, ctx);
+			if (guard) {
+				await guard(new WriteGuardContext(_action ?? "insertMany", items, Array.from({ length: items.length }), this));
+				require_nested_writer.validateBatch(validator, items, ctx);
+			}
 			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await require_nested_writer.batchInsertNestedTo(host, items, maxDepth, depth);
@@ -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 require_nested_writer.preValidateNestedFrom(host, payloads);
+			if (canNest) await require_nested_writer.preValidateNestedFrom(host, originals);
 			const result = await this.adapter.insertMany(prepared);
-			if (canNest) await require_nested_writer.batchInsertNestedFrom(host, payloads, result.insertedIds, maxDepth, depth);
-			if (canNest) await require_nested_writer.batchInsertNestedVia(host, payloads, result.insertedIds, maxDepth, depth);
+			if (canNest) await require_nested_writer.batchInsertNestedFrom(host, originals, result.insertedIds, maxDepth, depth);
+			if (canNest) await require_nested_writer.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) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		return require_nested_writer.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] = require_ops.separateCas(clone, versionColumn);
-				return this._applyDefaults(clone);
+				const c = clone(p);
+				expectedVersions[i] = require_ops.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);
 			require_nested_writer.validateBatch(validator, items, ctx);
+			if (guard) {
+				await guard(new WriteGuardContext(_action ?? "replaceMany", items, expectedVersions, this));
+				require_nested_writer.validateBatch(validator, items, ctx);
+			}
 			await this._encryptItems(items, "write");
 			const host = this;
 			if (canNest) await require_nested_writer.batchReplaceNestedTo(host, items, maxDepth, depth);
@@ -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) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		return require_nested_writer.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] = require_ops.separateCas(c, versionColumn);
 				return c;
 			});
@@ -3240,6 +3733,10 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			require_nested_writer.validateBatch(validator, cloned, ctx);
+			if (guard) {
+				await guard(new WriteGuardContext(_action ?? "updateMany", cloned, expectedVersions, this));
+				require_nested_writer.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 (require_validator.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 = require_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 require_db_error.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 require_db_error.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 require_nested_writer.remapDeleteFkViolation(this.tableName, () => this.adapter.withTransaction(async () => {
-			await this._integrity.cascadeBeforeDelete(filter, this.tableName, this._meta, this._cascadeResolver, (f) => this._fieldMapper.translateFilter(f, this._meta), this.adapter);
-			return this.adapter.deleteOne(this._fieldMapper.translateFilter(filter, this._meta));
-		}));
-		return require_nested_writer.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 require_nested_writer.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 require_db_error.DbError("INVALID_QUERY", [{
 			path: "$cas",
@@ -3324,13 +3911,21 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const ops = require_ops.separateFieldOps(update);
 		const translatedOps = ops ? _translateOpsKeys(ops, this._meta) : void 0;
 		const translatedUpdate = this._fieldMapper.translatePatchKeys(update, this._meta);
-		return require_nested_writer.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 && require_validator.isEmptyObject(translatedUpdate)) return {
+			matchedCount: await this.adapter.count({
+				filter: translatedFilter,
+				controls: {}
+			}),
+			modifiedCount: 0
+		};
+		return require_nested_writer.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 require_nested_writer.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
 		};
-		require_nested_writer.validateBatch(validator, items.map((raw) => this._applyDefaults({ ...raw })), ctx);
+		require_nested_writer.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, require_validator.dbPlugin] : [require_validator.dbPlugin];
-				return this.createValidator({
-					plugins,
-					partial: mode === "patch" ? require_validator.buildPatchPartial(this._meta.navFields) : false,
-					replace: (def, path) => {
-						const transformed = require_validator.forceNavNonOptional(def);
-						if (path === versionField && !transformed.optional) return {
-							...transformed,
-							optional: true
-						};
-						return transformed;
-					}
-				});
-			}
 			return require_validator.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,6 +4320,18 @@ 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
 Object.defineProperty(exports, "ApplicationIntegrity", {
 	enumerable: true,
@@ -3791,6 +4423,24 @@ Object.defineProperty(exports, "assertNoVersionWrites", {
 		return assertNoVersionWrites;
 	}
 });
+Object.defineProperty(exports, "checkHavingKeys", {
+	enumerable: true,
+	get: function() {
+		return checkHavingKeys;
+	}
+});
+Object.defineProperty(exports, "classifyQueryPath", {
+	enumerable: true,
+	get: function() {
+		return classifyQueryPath;
+	}
+});
+Object.defineProperty(exports, "collectQueryPaths", {
+	enumerable: true,
+	get: function() {
+		return collectQueryPaths;
+	}
+});
 Object.defineProperty(exports, "createFailureCollector", {
 	enumerable: true,
 	get: function() {
@@ -3803,6 +4453,12 @@ Object.defineProperty(exports, "decomposePatch", {
 		return decomposePatch;
 	}
 });
+Object.defineProperty(exports, "findAncestorInSet", {
+	enumerable: true,
+	get: function() {
+		return findAncestorInSet;
+	}
+});
 Object.defineProperty(exports, "guardAggregate", {
 	enumerable: true,
 	get: function() {
@@ -3815,12 +4471,30 @@ Object.defineProperty(exports, "guardFilter", {
 		return guardFilter;
 	}
 });
+Object.defineProperty(exports, "guardPath", {
+	enumerable: true,
+	get: function() {
+		return guardPath;
+	}
+});
+Object.defineProperty(exports, "guardPaths", {
+	enumerable: true,
+	get: function() {
+		return guardPaths;
+	}
+});
 Object.defineProperty(exports, "guardQuery", {
 	enumerable: true,
 	get: function() {
 		return guardQuery;
 	}
 });
+Object.defineProperty(exports, "isAtscriptDbView", {
+	enumerable: true,
+	get: function() {
+		return isAtscriptDbView;
+	}
+});
 Object.defineProperty(exports, "isGeoIndexableType", {
 	enumerable: true,
 	get: function() {
@@ -3839,3 +4513,15 @@ Object.defineProperty(exports, "resolveDesignType", {
 		return resolveDesignType;
 	}
 });
+Object.defineProperty(exports, "sortFieldNames", {
+	enumerable: true,
+	get: function() {
+		return sortFieldNames;
+	}
+});
+Object.defineProperty(exports, "unsupportedOperatorMessage", {
+	enumerable: true,
+	get: function() {
+		return unsupportedOperatorMessage;
+	}
+});