@atscript/db 0.1.141 → 0.1.143

package/dist/{column-diff-CmFNXV8C.mjs → column-diff-e2oHc71_.mjs}

@@ -1,10 +1,11 @@
 import { n as CasMismatchError, r as DbError } from "./db-error-D5uilS_A.mjs";
 import { i as SUPPORTED_AGGREGATE_FNS, n as BASE_AGGREGATE_FNS } from "./aggregate-fns-CfsveE1w.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, v as tableNameOf } from "./nested-writer-BO3vhbkP.mjs";
+import { C as findRemoteFK, S as findFKForRelation, T as tableNameOf, _ as remapDeleteFkViolation, a as batchPatchNestedFrom, b as sameKey, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, g as enrichFkViolation, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, v as pkTupleKey, x as findFKEntryForRelation, y as rowMatchesKey } from "./nested-writer-CnOOAehr.mjs";
 import { i as isJsonLeafType, n as DERIVED_INCOMPATIBLE } from "./derived-rules-0sKn4f5C.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, d as getPath, f as isEmptyObject, i as dbPlugin, l as deletePath, m as selfOrAncestor, n as buildPatchPartial, p as isPlainObject, t as buildDbValidator, u as findAncestorInSet } from "./validator-D8bPsXPN.mjs";
+import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-TkiJQ-Dp.mjs";
 import { resolveAlias } from "./agg.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-Clu2q_7z.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { BUCKET_UNITS, isAggregateExpr, isBucketExpr, isPrimitive, resolveBuckets } from "@uniqu/core";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -197,6 +198,33 @@ function sourceIndex(type) {
 	return idx;
 }
 /**
+* The read seals a view column inherits from the source path it reads
+* (since 0.1.143): `writeOnly` when the path or any ancestor object is
+* `@db.writeOnly` (a leaf of a sealed object is sealed too); `encrypted` when
+* the path itself is `@db.encrypted` (it reads the ciphertext column).
+* Reads the source's live field metadata, so a source VIEW whose own fields
+* inherited a seal (see `inheritViewFieldSeals`) passes it on.
+* @since 0.1.143
+*/
+function sourceFieldSeals(sourceType, logicalPath) {
+	const { flatMap } = sourceIndex(sourceType);
+	const props = sourceType.type.kind === "object" ? sourceType.type.props : void 0;
+	const seals = {
+		writeOnly: false,
+		encrypted: false
+	};
+	let prefix = "";
+	for (const segment of logicalPath.split(".")) {
+		const node = prefix ? flatMap.get(`${prefix}.${segment}`) : props?.get(segment);
+		prefix = prefix ? `${prefix}.${segment}` : segment;
+		const metadata = node?.metadata;
+		if (!metadata) break;
+		if (metadata.has("db.writeOnly")) seals.writeOnly = true;
+		if (prefix === logicalPath && metadata.has("db.encrypted")) seals.encrypted = true;
+	}
+	return seals;
+}
+/**
 * Resolves a LOGICAL path of a source table (a view field's chain ref, an
 * aggregate's field, a predicate operand) to where it is physically stored.
 * Internal — `AtscriptDbView.resolveRefSource` is the public entry.
@@ -2362,6 +2390,37 @@ function guardBucketUnits(adapter, buckets) {
 	}]);
 }
 //#endregion
+//#region src/shared/index-messages.ts
+/**
+* Wording of the "index not found" errors — one source for the core, every
+* adapter and the HTTP layer, so a request naming a hidden index reads
+* exactly like one naming a nonexistent index.
+*/
+/**
+* `Search index "<name>" not found`, or — without a name — the "no default
+* text index" message.
+* @since 0.1.143
+*/
+function searchIndexNotFoundMessage(indexName) {
+	return indexName ? `Search index "${indexName}" not found` : "No search index available";
+}
+/**
+* `Vector index "<name>" not found`, or — without a name — the "no vector
+* index" message.
+* @since 0.1.143
+*/
+function vectorIndexNotFoundMessage(indexName) {
+	return indexName ? `Vector index "${indexName}" not found` : "No vector index available";
+}
+/**
+* `Geo index "<name>" not found on table "<table>"`, or — without a name —
+* the "table declares no geo index" message.
+* @since 0.1.143
+*/
+function geoIndexNotFoundMessage(tableName, indexName) {
+	return indexName === void 0 ? `Table "${tableName}" declares no @db.index.geo — geoSearch requires a geo index` : `Geo index "${indexName}" not found on table "${tableName}"`;
+}
+//#endregion
 //#region src/table/db-readable.ts
 /**
 * Resolves the design type from an annotated type.
@@ -2722,6 +2781,34 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		return this._meta.relations;
 	}
+	/**
+	* The `@db.rel.FK` entry a `@db.rel.to` relation is backed by — paired
+	* exactly like relation loading and nested writes pair them: by the
+	* relation's alias when it has one, else by the target table. `undefined`
+	* for an unknown name, a `@db.rel.from` / `@db.rel.via` relation (their key
+	* lives on the other table) or a TO relation without a matching FK.
+	*
+	* @since 0.1.143
+	*/
+	foreignKeyOf(relationName) {
+		const relation = this.relations.get(relationName);
+		if (relation?.direction !== "to") return void 0;
+		return findFKEntryForRelation(relation, this._meta.foreignKeys);
+	}
+	/**
+	* Logical paths stored as ONE JSON column (`storage: "json"` — `@db.json`
+	* fields and nested objects / arrays a relational adapter serializes): the
+	* engine cannot address a sub-path of such a column in a projection,
+	* filter or sort, so a permission layer treats it atomically (visible whole
+	* or not at all). Navigation fields excluded; empty on document adapters
+	* (they store nested values natively).
+	*
+	* @since 0.1.143
+	*/
+	get jsonParents() {
+		this._ensureBuilt();
+		return this._meta.jsonParents;
+	}
 	/** The underlying database adapter instance. */
 	get dbAdapter() {
 		return this.adapter;
@@ -2760,6 +2847,100 @@ var AtscriptDbReadable = class {
 		return this._fieldMapper.reconstructRows(rows, this._meta, controls);
 	}
 	/**
+	* Translates a read query for the adapter. A `$select` that leaves out a
+	* key a `$with` relation joins on — a TO relation's foreign key, the key a
+	* FROM / VIA relation is looked up by — is widened with it for the read
+	* (since 0.1.143), and {@link _finishRead} strips it again once the
+	* relations are loaded: the joined object never reads `null` just because
+	* its key was not selected.
+	*/
+	_translateRead(query) {
+		let readQuery = query ?? {};
+		const controls = readQuery.controls;
+		const withRelations = controls?.$with;
+		let widened = [];
+		if (withRelations?.length && controls?.$select) {
+			const widen = this._widenSelectForWith(controls.$select, withRelations);
+			if (widen) {
+				readQuery = {
+					...readQuery,
+					controls: {
+						...controls,
+						$select: widen.select
+					}
+				};
+				widened = widen.added;
+			}
+		}
+		return {
+			translated: this._fieldMapper.translateQuery(readQuery, this._meta),
+			controls: readQuery.controls,
+			withRelations,
+			widened
+		};
+	}
+	/** Reconstructs + decrypts a read's rows, loads its `$with` relations and strips widened keys. */
+	async _finishRead(results, read) {
+		const rows = this._fromRead(results, read.controls);
+		await this._decryptRows(rows);
+		if (read.withRelations?.length) {
+			await this.loadRelations(rows, read.withRelations);
+			for (const key of read.widened) for (const row of rows) deletePath(row, key);
+		}
+		return rows;
+	}
+	/** `$select` plus the join keys of `withRelations` it leaves out — `undefined` when none is missing. */
+	_widenSelectForWith(select, withRelations) {
+		const keys = /* @__PURE__ */ new Set();
+		for (const rel of withRelations) for (const key of this._joinKeysOf(rel.name)) keys.add(key);
+		if (keys.size === 0) return void 0;
+		if (isExclusionProjection(select)) {
+			const added = [...keys].filter((key) => key in select);
+			if (added.length === 0) return void 0;
+			const next = { ...select };
+			for (const key of added) delete next[key];
+			return {
+				select: next,
+				added
+			};
+		}
+		const named = new Set(Array.isArray(select) ? select.filter((key) => typeof key === "string") : Object.keys(select).filter((key) => select[key]));
+		if (named.size === 0) return void 0;
+		const added = [...keys].filter((key) => selfOrAncestor(key, named) === void 0);
+		if (added.length === 0) return void 0;
+		return {
+			select: Array.isArray(select) ? [...select, ...added] : {
+				...select,
+				...Object.fromEntries(added.map((k) => [k, 1]))
+			},
+			added
+		};
+	}
+	_joinKeysCache;
+	/**
+	* The keys of THIS table a `$with` relation joins on: a TO relation's
+	* foreign-key fields; the fields a FROM relation's (or a VIA junction's)
+	* foreign key references — typically the primary key. An adapter that
+	* loads relations natively re-reads the rows by primary key, so it is
+	* always included there. Empty for an unknown or nested (`a.b`) name.
+	*/
+	_joinKeysOf(relName) {
+		const cache = this._joinKeysCache ??= /* @__PURE__ */ new Map();
+		let keys = cache.get(relName);
+		if (keys === void 0) {
+			keys = [];
+			const relation = this._meta.relations.get(relName);
+			if (relation?.direction === "to") keys = this._findFKForRelation(relation)?.localFields ?? [];
+			else if (relation && this._tableResolver) {
+				const remote = relation.direction === "from" ? this._tableResolver(relation.targetType()) : relation.viaType && this._tableResolver(relation.viaType());
+				keys = (remote && this._findRemoteFK(remote, this.tableName, relation.direction === "from" ? relation.alias : void 0))?.targetFields ?? [];
+			}
+			if (relation && this.adapter.supportsNativeRelations()) keys = [...new Set([...keys, ...this.primaryKeys])];
+			cache.set(relName, keys);
+		}
+		return keys;
+	}
+	/**
 	* Pre-computed field metadata for adapter use.
 	*/
 	get fieldDescriptors() {
@@ -2842,13 +3023,10 @@ var AtscriptDbReadable = class {
 	async findOne(query) {
 		this._ensureBuilt();
 		this._guardQuery(query);
-		const withRelations = query.controls?.$with;
-		const translatedQuery = this._fieldMapper.translateQuery(query, this._meta);
-		const result = await this.adapter.findOne(translatedQuery);
+		const read = this._translateRead(query);
+		const result = await this.adapter.findOne(read.translated);
 		if (!result) return null;
-		const [row] = this._fromRead([result], query.controls);
-		await this._decryptRows([row]);
-		if (withRelations?.length) await this.loadRelations([row], withRelations);
+		const [row] = await this._finishRead([result], read);
 		return row;
 	}
 	/**
@@ -2859,13 +3037,8 @@ var AtscriptDbReadable = class {
 	async findMany(query) {
 		this._ensureBuilt();
 		this._guardQuery(query);
-		const withRelations = query.controls?.$with;
-		const translatedQuery = this._fieldMapper.translateQuery(query, this._meta);
-		const results = await this.adapter.findMany(translatedQuery);
-		const rows = this._fromRead(results, query.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
-		return rows;
+		const read = this._translateRead(query);
+		return await this._finishRead(await this.adapter.findMany(read.translated), read);
 	}
 	/**
 	* Counts records matching the query.
@@ -2885,14 +3058,10 @@ var AtscriptDbReadable = class {
 	async findManyWithCount(query) {
 		this._ensureBuilt();
 		this._guardQuery(query);
-		const withRelations = query.controls?.$with;
-		const translated = this._fieldMapper.translateQuery(query, this._meta);
-		const result = await this.adapter.findManyWithCount(translated);
-		const rows = this._fromRead(result.data, query.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		const read = this._translateRead(query);
+		const result = await this.adapter.findManyWithCount(read.translated);
 		return {
-			data: rows,
+			data: await this._finishRead(result.data, read),
 			count: result.count
 		};
 	}
@@ -3003,13 +3172,9 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		this._ensureSearchable();
 		this._guardQuery(query);
-		const withRelations = query.controls?.$with;
-		const translated = this._fieldMapper.translateQuery(query, this._meta);
-		const results = await this.adapter.search(text, translated, indexName);
-		const rows = this._fromRead(results, query.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
-		return rows;
+		const read = this._translateRead(query);
+		const results = await this.adapter.search(text, read.translated, indexName);
+		return await this._finishRead(results, read);
 	}
 	/**
 	* Full-text search with count for paginated search results.
@@ -3018,14 +3183,10 @@ var AtscriptDbReadable = class {
 		this._ensureBuilt();
 		this._ensureSearchable();
 		this._guardQuery(query);
-		const withRelations = query.controls?.$with;
-		const translated = this._fieldMapper.translateQuery(query, this._meta);
-		const result = await this.adapter.searchWithCount(text, translated, indexName);
-		const rows = this._fromRead(result.data, query.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		const read = this._translateRead(query);
+		const result = await this.adapter.searchWithCount(text, read.translated, indexName);
 		return {
-			data: rows,
+			data: await this._finishRead(result.data, read),
 			count: result.count
 		};
 	}
@@ -3044,13 +3205,9 @@ var AtscriptDbReadable = class {
 		const { vector, query, indexName } = this._resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery);
 		this._ensureBuilt();
 		this._guardQuery(query);
-		const withRelations = (query?.controls)?.$with;
-		const translated = this._fieldMapper.translateQuery(query || {}, this._meta);
-		const results = await this.adapter.vectorSearch(vector, translated, indexName);
-		const rows = this._fromRead(results, query?.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
-		return rows;
+		const read = this._translateRead(query);
+		const results = await this.adapter.vectorSearch(vector, read.translated, indexName);
+		return await this._finishRead(results, read);
 	}
 	/**
 	* Vector similarity search with count for paginated results.
@@ -3063,14 +3220,10 @@ var AtscriptDbReadable = class {
 		const { vector, query, indexName } = this._resolveVectorSearchArgs(vectorOrIndex, maybeVectorOrQuery, maybeQuery);
 		this._ensureBuilt();
 		this._guardQuery(query);
-		const withRelations = (query?.controls)?.$with;
-		const translated = this._fieldMapper.translateQuery(query || {}, this._meta);
-		const result = await this.adapter.vectorSearchWithCount(vector, translated, indexName);
-		const rows = this._fromRead(result.data, query?.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		const read = this._translateRead(query);
+		const result = await this.adapter.vectorSearchWithCount(vector, read.translated, indexName);
 		return {
-			data: rows,
+			data: await this._finishRead(result.data, read),
 			count: result.count
 		};
 	}
@@ -3103,12 +3256,9 @@ var AtscriptDbReadable = class {
 	*/
 	async geoSearch(pointOrIndex, maybePointOrQuery, maybeQuery) {
 		const { point, query, indexName } = this._resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery);
-		const { translated, withRelations } = this._prepareGeoSearch(point, query, indexName);
-		const results = await this.adapter.geoSearch(point, translated, indexName);
-		const rows = this._fromRead(results, query?.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
-		return rows;
+		const read = this._prepareGeoSearch(point, query, indexName);
+		const results = await this.adapter.geoSearch(point, read.translated, indexName);
+		return await this._finishRead(results, read);
 	}
 	/**
 	* Distance-ranked geospatial search with count for paginated results.
@@ -3119,13 +3269,10 @@ var AtscriptDbReadable = class {
 	*/
 	async geoSearchWithCount(pointOrIndex, maybePointOrQuery, maybeQuery) {
 		const { point, query, indexName } = this._resolveGeoSearchArgs(pointOrIndex, maybePointOrQuery, maybeQuery);
-		const { translated, withRelations } = this._prepareGeoSearch(point, query, indexName);
-		const result = await this.adapter.geoSearchWithCount(point, translated, indexName);
-		const rows = this._fromRead(result.data, query?.controls);
-		await this._decryptRows(rows);
-		if (withRelations?.length) await this.loadRelations(rows, withRelations);
+		const read = this._prepareGeoSearch(point, query, indexName);
+		const result = await this.adapter.geoSearchWithCount(point, read.translated, indexName);
 		return {
-			data: rows,
+			data: await this._finishRead(result.data, read),
 			count: result.count
 		};
 	}
@@ -3145,18 +3292,18 @@ var AtscriptDbReadable = class {
 	/** Shared geoSearch validation + query translation. */
 	_prepareGeoSearch(point, query, indexName) {
 		this._ensureBuilt();
-		if (!this.adapter.isGeoSearchable()) throw new DbError("GEO_NOT_SUPPORTED", [{
-			path: "",
-			message: `Geo search is not supported by the adapter behind table "${this.tableName}"`
-		}]);
 		const geoIndexes = [...this._meta.indexes.values()].filter((index) => index.type === "geo");
 		if (geoIndexes.length === 0) throw new DbError("GEO_INDEX_MISSING", [{
 			path: "",
-			message: `Table "${this.tableName}" declares no @db.index.geo — geoSearch requires a geo index`
+			message: geoIndexNotFoundMessage(this.tableName)
 		}]);
 		if (indexName !== void 0 && !geoIndexes.some((index) => index.name === indexName)) throw new DbError("GEO_INDEX_MISSING", [{
 			path: indexName,
-			message: `Geo index "${indexName}" not found on table "${this.tableName}"`
+			message: geoIndexNotFoundMessage(this.tableName, indexName)
+		}]);
+		if (!this.adapter.isGeoSearchable()) throw new DbError("GEO_NOT_SUPPORTED", [{
+			path: "",
+			message: `Geo search is not supported by the adapter behind table "${this.tableName}"`
 		}]);
 		assertGeoPoint(point, "$center");
 		const controls = query?.controls ?? {};
@@ -3172,17 +3319,17 @@ var AtscriptDbReadable = class {
 			}]);
 		}
 		this._guardQuery(query);
-		const withRelations = (query?.controls)?.$with;
-		return {
-			translated: this._fieldMapper.translateQuery(query || {}, this._meta),
-			withRelations
-		};
+		return this._translateRead(query);
 	}
 	/**
 	* Finds a single record by any type-compatible identifier — primary key
 	* or single-field unique index.
 	* The return type excludes nav props unless `$with` is provided in controls.
 	*
+	* The id addresses exactly ONE row, primary key first (since 0.1.143) —
+	* see {@link resolveRowFilter}: when a scalar id equals one row's primary
+	* key and another row's unique key, the primary-key row is returned.
+	*
 	* ```typescript
 	* // Without relations — nav props stripped from result
 	* const user = await table.findById('123')
@@ -3192,61 +3339,194 @@ var AtscriptDbReadable = class {
 	* ```
 	*/
 	async findById(id, query) {
+		return this.findOneByRow(id, { controls: query?.controls });
+	}
+	/**
+	* Reads the ONE row an id addresses — resolved exactly like
+	* {@link resolveRowFilter} (primary key first, `opts.scope` /
+	* `opts.isFieldVisible` as there) — with `opts.controls` applied, in one
+	* step: the identifications are probed in order with the caller's
+	* controls and the first row found wins, so no pin-then-reread. The row
+	* must also match `opts.scope` (an out-of-scope row answers `null` like a
+	* missing one).
+	*
+	* @since 0.1.143
+	*/
+	async findOneByRow(id, opts) {
 		this._ensureBuilt();
-		const filter = this._resolveIdFilter(id);
-		if (!filter) return null;
-		return await this.findOne({
-			filter,
-			controls: query?.controls || {}
-		});
+		const controls = opts?.controls ?? {};
+		for (const candidate of this._idCandidates(id, opts)) {
+			const row = await this.findOne({
+				filter: this._andScope(candidate, opts?.scope),
+				controls
+			});
+			if (row) return row;
+		}
+		return null;
 	}
 	/**
 	* Resolve an id value (scalar or object) into a {@link FilterExpr} using the
-	* same identification resolution as {@link findById}. Public so callers can
+	* same identifications as {@link findById}. Public so callers can
 	* AND-combine the id-filter with a row-level read overlay before issuing
 	* `findOne` (avoiding the existence leak that `findById` would cause).
 	* `opts.isFieldVisible` (since 0.1.134) drops unique indexes over hidden
 	* fields — see {@link identificationsVisibleTo}.
+	*
+	* The result is a plain `$or` over every identification the id is
+	* type-compatible with (a scalar can equal one row's primary key AND
+	* another row's unique key), so it may match more than one row. Code that
+	* must address exactly one row — writes, pre-images, `/one` reads — uses
+	* {@link resolveRowFilter} instead.
 	*/
 	resolveIdFilter(id, opts) {
 		return this._resolveIdFilter(id, opts);
 	}
 	/**
-	* Resolve an id value into a filter expression.
+	* Resolve an id value (scalar or object) into a filter that matches exactly
+	* ONE row, deterministically and primary key first (since 0.1.143):
+	*
+	* - an id that yields a single identification (e.g. a numeric PK with no
+	*   type-compatible unique key) resolves to it without a read;
+	* - an object id carrying the complete primary key resolves by the primary
+	*   key alone — exactly like a write payload is identified;
+	* - otherwise the identifications are tried in order (primary key first,
+	*   then each unique index): the first one that matches a row wins and the
+	*   result is that row's exact primary-key filter;
+	* - when none matches, the first identification is returned (it matches
+	*   nothing, so callers answer "not found" as usual).
+	*
+	* `null` when the id resolves to no identification at all. Every write
+	* (`deleteOne`, the guards' `current()`) and `findById` go through this
+	* resolution; call it inside the write's transaction when the answer must
+	* stay pinned. `opts.isFieldVisible` as in {@link resolveIdFilter}.
+	*
+	* `opts.scope` (a row-level overlay) restricts which rows count as matches
+	* while the identifications are tried — a row outside it never shadows one
+	* inside it, so the answer is the same as if that row did not exist. AND
+	* the scope onto the result to exclude an out-of-scope row the id names
+	* unambiguously. See {@link TRowResolveOptions}.
+	*/
+	async resolveRowFilter(id, opts) {
+		this._ensureBuilt();
+		return this._pinIdCandidates(this._idCandidates(id, opts), opts?.scope);
+	}
+	/**
+	* Resolve an id value into a filter expression (the `$or` of
+	* {@link _idCandidates}; a single candidate is returned as-is).
+	*/
+	_resolveIdFilter(id, opts) {
+		const candidates = this._idCandidates(id, opts, false);
+		if (candidates.length === 0) return null;
+		if (candidates.length === 1) return candidates[0];
+		return { $or: candidates };
+	}
+	/**
+	* The ordered identification filters an id value can resolve through —
+	* primary key first, then each unique index.
 	*
 	* When `preferredId` differs from the PK, scalar ids resolve only against
 	* the preferred field (deterministic addressing). Otherwise scalars try PK
 	* + every single-field unique index; objects try PK + compound unique
 	* indexes. With `opts.isFieldVisible`, only the identifications
-	* {@link identificationsVisibleTo} keeps are tried.
+	* {@link identificationsVisibleTo} keeps are tried. With `pkWins` (the
+	* default), an object id carrying the complete primary key yields the
+	* primary-key filter alone.
 	*/
-	_resolveIdFilter(id, opts) {
+	_idCandidates(id, opts, pkWins = true) {
 		const pkFields = this.primaryKeys;
 		const preferredFields = this.preferredId;
 		const isExplicitPreferred = preferredFields.length !== pkFields.length || preferredFields.some((f, i) => f !== pkFields[i]);
 		const isScalar = id === null || typeof id !== "object";
-		if (isScalar && isExplicitPreferred && preferredFields.length === 1) return this._tryFieldFilter(preferredFields[0], id);
+		if (isScalar && isExplicitPreferred && preferredFields.length === 1) {
+			const filter = this._tryFieldFilter(preferredFields[0], id);
+			return filter ? [filter] : [];
+		}
+		const idObj = isScalar ? null : id;
+		if (idObj && pkWins && pkFields.length > 0) {
+			const pkFilter = this._tryCompoundFilter(pkFields, idObj);
+			if (pkFilter) return [pkFilter];
+		}
 		const tryScalarOrField = (field) => {
-			const value = isScalar ? id : id[field];
+			const value = isScalar ? id : idObj[field];
 			return value === void 0 ? null : this._tryFieldFilter(field, value);
 		};
-		const orFilters = [];
-		const idObj = isScalar ? null : id;
+		const candidates = [];
 		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
 		for (const ident of identifications) {
 			if (ident.fields.length !== 1) continue;
 			const filter = tryScalarOrField(ident.fields[0]);
-			if (filter) orFilters.push(filter);
+			if (filter) candidates.push(filter);
 		}
 		if (idObj) for (const ident of identifications) {
 			if (ident.fields.length < 2) continue;
-			if (ident.source !== "primaryKey" && orFilters.length > 0) break;
+			if (ident.source !== "primaryKey" && candidates.length > 0) break;
 			const filter = this._tryCompoundFilter(ident.fields, idObj);
-			if (filter) orFilters.push(filter);
+			if (filter) candidates.push(filter);
+		}
+		return candidates;
+	}
+	/**
+	* Picks the one row a list of identification candidates addresses — see
+	* {@link resolveRowFilter}. A lone candidate needs no read. With a
+	* non-empty `scope`, only rows matching it count as matches.
+	*/
+	async _pinIdCandidates(candidates, scope) {
+		if (candidates.length === 0) return null;
+		if (candidates.length === 1) return candidates[0];
+		const pkFields = this.primaryKeys;
+		const select = new Set(pkFields);
+		for (const candidate of candidates) for (const field in candidate) select.add(field);
+		const rows = await this.findMany({
+			filter: this._andScope({ $or: candidates }, scope),
+			controls: { $select: [...select] }
+		});
+		if (rows.length === 0) return candidates[0];
+		for (const candidate of candidates) {
+			const row = rows.find((r) => rowMatchesKey(r, candidate));
+			if (row) return this._pkFilterFrom(row) ?? candidate;
+		}
+		return this._probeIdCandidates(candidates, scope);
+	}
+	/** Sequential fallback of {@link _pinIdCandidates}: first candidate matching a row wins. */
+	async _probeIdCandidates(candidates, scope) {
+		for (const candidate of candidates) {
+			const pinned = await this._readPkFilter(candidate, scope);
+			if (pinned) return pinned;
 		}
-		if (orFilters.length === 0) return null;
-		if (orFilters.length === 1) return orFilters[0];
-		return { $or: orFilters };
+		return candidates[0];
+	}
+	/**
+	* The exact primary-key filter of `row` (values prepared like ids) — `null`
+	* when the table has no primary key or `row` lacks a key field.
+	*/
+	_pkFilterFrom(row) {
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 0) return null;
+		const filter = {};
+		for (const field of pkFields) {
+			const value = row[field];
+			if (value === void 0) return null;
+			const fieldType = this.flatMap.get(field);
+			filter[field] = fieldType ? this.adapter.prepareId(value, fieldType) : value;
+		}
+		return filter;
+	}
+	/**
+	* Reads the row `filter` (AND `scope`) matches and returns its exact
+	* primary-key filter (`filter` itself on a table without one); `undefined`
+	* when no row matches.
+	*/
+	async _readPkFilter(filter, scope) {
+		const pkFields = this.primaryKeys;
+		const row = await this.findOne({
+			filter: this._andScope(filter, scope),
+			controls: pkFields.length > 0 ? { $select: [...pkFields] } : {}
+		});
+		return row ? this._pkFilterFrom(row) ?? filter : void 0;
+	}
+	/** `filter` AND a row scope — `filter` itself when the scope is absent or empty. */
+	_andScope(filter, scope) {
+		return scope === void 0 || isEmptyObject(scope) ? filter : { $and: [filter, scope] };
 	}
 	/** Build a single-key filter from `idObj` over `fields`, or null if any field is missing/incompatible. */
 	_tryCompoundFilter(fields, idObj) {
@@ -3281,7 +3561,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-CuhEBzFU.mjs").then((n) => n.n);
+		const { loadRelationsImpl } = await import("./relation-loader-D9XuXaMv.mjs").then((n) => n.n);
 		return loadRelationsImpl(rows, withRelations, this);
 	}
 	/**
@@ -3485,6 +3765,16 @@ var BaseDbAdapter = class {
 		return findTxContext(this._transactionOwner())?.state;
 	}
 	/**
+	* `true` when the current async context runs inside a REAL transaction of
+	* this adapter (its owner) — one a throw rolls back (since 0.1.143).
+	* `false` outside any transaction and inside a pass-through
+	* `withTransaction` (adapters without transaction primitives such as the
+	* in-memory one, a standalone MongoDB topology).
+	*/
+	isInTransaction() {
+		return this._getTransactionState() !== void 0;
+	}
+	/**
 	* 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
@@ -3763,6 +4053,25 @@ var BaseDbAdapter = class {
 	getSearchIndexes() {
 		return [];
 	}
+	_physicalToLogical;
+	/**
+	* The LOGICAL field paths an index reads (its `fields` carry physical
+	* names) — what adapters report as {@link TSearchIndexInfo.fields}. A
+	* derived column never shadows the regular field sharing its physical name.
+	* @since 0.1.143
+	*/
+	_indexLogicalPaths(index) {
+		let logical = this._physicalToLogical;
+		if (!logical) {
+			logical = /* @__PURE__ */ new Map();
+			for (const fd of this._table.fieldDescriptors) {
+				if (fd.ignored || fd.derived && logical.has(fd.physicalName)) continue;
+				logical.set(fd.physicalName, fd.path);
+			}
+			this._physicalToLogical = logical;
+		}
+		return index.fields.map((field) => logical.get(field.name) ?? field.name);
+	}
 	/**
 	* Whether this adapter can run TEXT search — `search()`, `searchWithCount()`
 	* and the grouped `$search` path all gate on it. Vector capability is a
@@ -3844,7 +4153,7 @@ var BaseDbAdapter = class {
 		const column = (indexName ? geoIndexes.find((candidate) => candidate.name === indexName) : geoIndexes[0])?.fields[0]?.name;
 		if (!column) throw new DbError("GEO_INDEX_MISSING", [{
 			path: indexName ?? "",
-			message: `No geo index${indexName ? ` "${indexName}"` : ""} on "${this._table.tableName}"`
+			message: geoIndexNotFoundMessage(this._table.tableName, indexName)
 		}]);
 		return column;
 	}
@@ -4466,30 +4775,99 @@ function _shallowPrunedClone(source) {
 	}
 	return out;
 }
+/** Same keys, same key values (across driver representations). */
+function sameFilter(a, b) {
+	const aKeys = Object.keys(a);
+	return aKeys.length === Object.keys(b).length && aKeys.every((key) => sameKey(a[key], b[key]));
+}
 /**
-* {@link TDbWriteGuardContext} handed to a write guard: a sparse per-index
-* cache of pre-image reads, allocated only when `current(i)` is first used.
+* {@link TDbWriteGuardContext} handed to a write guard: sparse per-index
+* caches of record filters and pre-image reads, allocated on first use.
+* The write reuses a read for its own target pin ({@link readFor}).
 */
 var WriteGuardContext = class {
 	action;
 	rows;
 	expectedVersions;
 	_table;
-	_pending;
-	constructor(action, rows, expectedVersions, _table) {
+	_opts;
+	_filters;
+	_reads;
+	constructor(action, rows, expectedVersions, _table, _opts) {
 		this.action = action;
 		this.rows = rows;
 		this.expectedVersions = expectedVersions;
 		this._table = _table;
+		this._opts = _opts;
+	}
+	filterFor(i) {
+		const filters = this._filters ??= [];
+		let filter = filters[i];
+		if (filter === void 0) {
+			filter = this._table._recordFilterOrNull(this.rows[i], this._opts);
+			filters[i] = filter;
+		}
+		return filter;
 	}
 	current(i) {
-		const cache = this._pending ??= [];
-		let pending = cache[i];
-		if (!pending) {
-			pending = this._table._readPreImage(this.rows[i]);
-			cache[i] = pending;
+		const reads = this._reads ??= [];
+		let read = reads[i];
+		if (!read) {
+			const filter = this.filterFor(i);
+			read = filter ? this._table.findOne({
+				filter,
+				controls: {}
+			}) : Promise.resolve(null);
+			reads[i] = read;
+		}
+		return read;
+	}
+	currentAll() {
+		const reads = this._reads ??= [];
+		const pending = [];
+		for (let i = 0; i < this.rows.length; i++) {
+			if (reads[i]) continue;
+			if (this.filterFor(i)) pending.push(i);
+			else reads[i] = Promise.resolve(null);
+		}
+		if (pending.length > 0) {
+			const found = this._readMany(pending.map((i) => this.filterFor(i)));
+			pending.forEach((i, k) => {
+				reads[i] = found.then((rows) => rows[k]);
+			});
 		}
-		return pending;
+		return Promise.all(this.rows.map((_, i) => reads[i]));
+	}
+	/**
+	* One `findMany` for the `filters` (full rows, like `current(i)`), matched
+	* back in memory; a filter the store matched differently (e.g. a
+	* case-insensitive collation) is re-read on its own.
+	*/
+	async _readMany(filters) {
+		const table = this._table;
+		const rows = await table.findMany({
+			filter: filters.length === 1 ? filters[0] : { $or: filters },
+			controls: {}
+		});
+		const used = /* @__PURE__ */ new Set();
+		const out = filters.map((filter) => {
+			const row = rows.find((r) => rowMatchesKey(r, filter));
+			if (row) used.add(row);
+			return row ?? null;
+		});
+		if (used.size < rows.length) {
+			for (let k = 0; k < filters.length; k++) if (out[k] === null) out[k] = await table.findOne({
+				filter: filters[k],
+				controls: {}
+			});
+		}
+		return out;
+	}
+	/** The pre-image `current(i)` read by exactly `filter`, if the guard asked for it. */
+	readFor(i, filter) {
+		const read = this._reads?.[i];
+		const readBy = this._filters?.[i];
+		return read && readBy && sameFilter(readBy, filter) ? read : void 0;
 	}
 };
 /** {@link TDbRemoveGuardContext} handed to a delete guard (one memoised pre-image read). */
@@ -4511,6 +4889,23 @@ var RemoveGuardContext = class {
 		return this._pending;
 	}
 };
+/** Number of `true` entries. */
+function countTrue(flags) {
+	let n = 0;
+	for (const flag of flags) if (flag) n++;
+	return n;
+}
+/**
+* A write item matched nothing although its row was relied upon — a replace
+* whose nested TO rows were already written, or a nested child re-parented
+* since the plan. The row changed meanwhile; thrown to roll back.
+*/
+function concurrentChange() {
+	return new DbError("CONFLICT", [{
+		path: "",
+		message: "The record changed during the write — nothing was written, retry"
+	}]);
+}
 /** 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. */
@@ -4581,11 +4976,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 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}.
+	* defaults + validation, with the prepared rows; `opts.check` (since
+	* 0.1.143) runs once after every phase with the inserted rows' primary-key
+	* filters — see {@link TWriteOptions}.
 	*/
 	async insertMany(payloads, opts) {
 		this._ensureBuilt();
-		const { _depth, _action, maxDepth: userMax, guard } = opts ?? {};
+		const { _depth, _action, maxDepth: userMax, guard, check } = opts ?? {};
 		const maxDepth = userMax ?? 3;
 		const depth = _depth ?? 0;
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
@@ -4602,7 +4999,7 @@ 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));
+				await guard(new WriteGuardContext(_action ?? "insertMany", items, Array.from({ length: items.length }), this, opts));
 				validateBatch(validator, items, ctx);
 			}
 			await this._encryptItems(items, "write");
@@ -4618,6 +5015,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			const result = await this.adapter.insertMany(prepared);
 			if (canNest) await batchInsertNestedFrom(host, originals, result.insertedIds, maxDepth, depth);
 			if (canNest) await batchInsertNestedVia(host, originals, result.insertedIds, maxDepth, depth);
+			if (check) await this._runWriteCheck(check, _action ?? "insertMany", this._insertedPkFilters(items, prepared, result.insertedIds));
 			return result;
 		}));
 	}
@@ -4640,11 +5038,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	* 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}.
+	* `$cas` extraction, defaults + validation; `opts.check` (since 0.1.143)
+	* after every phase — see {@link TWriteOptions}. The nested phases run only
+	* for the rows the main replace matched.
 	*/
 	async bulkReplace(payloads, opts) {
 		this._ensureBuilt();
-		const { _depth, _action, maxDepth: userMax, guard } = opts ?? {};
+		const { _depth, _action, _ownedBy, maxDepth: userMax, guard, check } = opts ?? {};
 		const maxDepth = userMax ?? 3;
 		const depth = _depth ?? 0;
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
@@ -4666,31 +5066,40 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, items, ctx);
+			let guardCtx;
 			if (guard) {
-				await guard(new WriteGuardContext(_action ?? "replaceMany", items, expectedVersions, this));
+				guardCtx = new WriteGuardContext(_action ?? "replaceMany", items, expectedVersions, this, opts);
+				await guard(guardCtx);
 				validateBatch(validator, items, ctx);
 			}
 			await this._encryptItems(items, "write");
 			const host = this;
-			if (canNest) await batchReplaceNestedTo(host, items, maxDepth, depth);
+			const rowFilters = this._rowFilters(items, opts);
+			const nestedPlan = canNest ? await planNestedFromVia(host, originals, "replace") : void 0;
+			const nestedTo = canNest ? items.map((item) => this._carriesNestedTo(item)) : [];
+			const targets = await this._pinTargets(rowFilters, (i) => nestedTo[i] || check !== void 0 && !this._isPkFilter(rowFilters[i]), guardCtx);
+			const toApplied = this._gateNestedTo(items, nestedTo, targets, expectedVersions);
+			if (toApplied.some(Boolean)) await batchReplaceNestedTo(host, items, maxDepth, depth);
 			await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver);
 			if (canNest) await preValidateNestedFrom(host, originals);
-			let matchedCount = 0;
 			let modifiedCount = 0;
+			const matched = [];
 			for (let i = 0; i < items.length; i++) {
 				const data = items[i];
 				for (const navField of this._meta.navFields) delete data[navField];
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
-				const filter = this._extractRecordFilter(data, opts);
 				const prepared = this._fieldMapper.prepareForWrite(data, this._meta, this.adapter);
-				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(filter, this._meta), prepared, expectedVersions[i]);
-				matchedCount += result.matchedCount;
+				const result = await this.adapter.replaceOne(this._fieldMapper.translateFilter(rowFilters[i], this._meta), prepared, expectedVersions[i]);
 				modifiedCount += result.modifiedCount;
+				matched[i] = result.matchedCount > 0;
+				if (!matched[i] && (toApplied[i] || _ownedBy?.strict?.[i])) throw concurrentChange();
 			}
-			if (canNest) await batchReplaceNestedFrom(host, originals, maxDepth, depth);
-			if (canNest) await batchReplaceNestedVia(host, originals, maxDepth, depth);
+			const matchedOriginals = canNest ? originals.filter((_, i) => matched[i]) : [];
+			if (matchedOriginals.length > 0) await batchReplaceNestedFrom(host, matchedOriginals, maxDepth, depth, nestedPlan);
+			if (matchedOriginals.length > 0) await batchReplaceNestedVia(host, matchedOriginals, maxDepth, depth);
+			if (check) await this._runWriteCheck(check, _action ?? "replaceMany", this._writtenPkFilters(rowFilters, targets, matched));
 			return {
-				matchedCount,
+				matchedCount: countTrue(matched),
 				modifiedCount
 			};
 		}));
@@ -4714,11 +5123,14 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*
 	* `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}.
+	* present, `$cas` removed); `opts.check` (since 0.1.143) after every
+	* phase — see {@link TWriteOptions}. The nested phases run only for the
+	* rows the main patch matched; a nested TO object patches the row the
+	* STORED foreign key references.
 	*/
 	async bulkUpdate(payloads, opts) {
 		this._ensureBuilt();
-		const { _depth, _action, maxDepth: userMax, guard } = opts ?? {};
+		const { _depth, _action, _ownedBy, maxDepth: userMax, guard, check } = opts ?? {};
 		const maxDepth = userMax ?? 3;
 		const depth = _depth ?? 0;
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
@@ -4740,33 +5152,39 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 			};
 			this._applyDepthCtx(ctx, depth);
 			validateBatch(validator, cloned, ctx);
+			let guardCtx;
 			if (guard) {
-				await guard(new WriteGuardContext(_action ?? "updateMany", cloned, expectedVersions, this));
+				guardCtx = new WriteGuardContext(_action ?? "updateMany", cloned, expectedVersions, this, opts);
+				await guard(guardCtx);
 				validateBatch(validator, cloned, ctx);
 			}
 			const originals = canNest ? cloned.map((p) => ({ ...p })) : [];
 			await this._encryptItems(cloned, "patch");
 			const host = this;
-			if (canNest) await batchPatchNestedTo(host, cloned, maxDepth, depth);
+			const rowFilters = this._rowFilters(cloned, opts);
+			const nestedPlan = canNest ? await planNestedFromVia(host, originals, "patch") : void 0;
+			const nestedTo = canNest ? cloned.map((payload) => this._carriesNestedTo(payload)) : [];
+			const targets = await this._pinTargets(rowFilters, (i) => nestedTo[i] || check !== void 0 && !this._isPkFilter(rowFilters[i]), guardCtx);
+			const toPlans = nestedTo.includes(true) ? await planPatchNestedTo(host, cloned, targets) : [];
 			await this._integrity.validateForeignKeys(cloned, this._meta, this._fkLookupResolver, this._writeTableResolver, true);
-			let matchedCount = 0;
 			let modifiedCount = 0;
+			const matched = [];
 			for (let i = 0; i < cloned.length; i++) {
 				const payload = cloned[i];
 				const expectedVersion = expectedVersions[i];
 				const data = { ...payload };
 				for (const navField of this._meta.navFields) delete data[navField];
-				const filter = this._extractRecordFilter(data, opts);
+				const filter = rowFilters[i];
 				for (const key of Object.keys(filter)) delete data[key];
 				this._meta.stripDerived(data);
 				if (versionColumn !== void 0) assertNoVersionWrites(data, versionColumn);
 				const translatedFilter = this._fieldMapper.translateFilter(filter, this._meta);
 				if (isEmptyObject(data) && expectedVersion === void 0) {
-					const exists = await this.adapter.count({
+					matched[i] = await this.adapter.count({
 						filter: translatedFilter,
 						controls: {}
-					});
-					matchedCount += exists > 0 ? 1 : 0;
+					}) > 0;
+					if (!matched[i] && _ownedBy?.strict?.[i]) throw concurrentChange();
 					continue;
 				}
 				let result;
@@ -4788,13 +5206,17 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 						result = await this.adapter.updateOne(translatedFilter, resolved, translatedOps, expectedVersion);
 					} else result = await this.adapter.updateOne(translatedFilter, translatedUpdate, translatedOps, expectedVersion);
 				}
-				matchedCount += result.matchedCount;
 				modifiedCount += result.modifiedCount;
+				matched[i] = result.matchedCount > 0;
+				if (!matched[i] && _ownedBy?.strict?.[i]) throw concurrentChange();
 			}
-			if (canNest) await batchPatchNestedFrom(host, originals, maxDepth, depth);
-			if (canNest) await batchPatchNestedVia(host, originals, maxDepth, depth);
+			if (toPlans.length > 0) await applyPatchNestedTo(toPlans, maxDepth, depth, matched);
+			const matchedOriginals = canNest ? originals.filter((_, i) => matched[i]) : [];
+			if (matchedOriginals.length > 0) await batchPatchNestedFrom(host, matchedOriginals, maxDepth, depth, nestedPlan);
+			if (matchedOriginals.length > 0) await batchPatchNestedVia(host, matchedOriginals, maxDepth, depth, nestedPlan);
+			if (check) await this._runWriteCheck(check, _action ?? "updateMany", this._writtenPkFilters(rowFilters, targets, matched));
 			return {
-				matchedCount,
+				matchedCount: countTrue(matched),
 				modifiedCount
 			};
 		}));
@@ -4879,29 +5301,40 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	}
 	/**
 	* Deletes a single record by any type-compatible identifier — primary key
-	* or single-field unique index. Uses the same resolution logic as `findById`.
+	* or single-field unique index. Uses the same resolution logic as `findById`:
+	* the id addresses exactly ONE row, primary key first (since 0.1.143 — see
+	* {@link resolveRowFilter}); an id that could name several rows is pinned
+	* inside the transaction, so the guard, the cascade and the delete all see
+	* the same row.
 	*
 	* 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}.
+	* `opts.scope` (since 0.1.143) is a row scope: an ambiguous id is pinned
+	* among in-scope rows only (see {@link TRowResolveOptions}) and the delete
+	* — guard `current()` and cascade included — targets the row only while it
+	* matches the scope, so an out-of-scope row answers `{ deletedCount: 0 }`
+	* exactly like a missing one.
 	* An id that resolves to no filter answers `{ deletedCount: 0 }` without
 	* calling the guard.
 	*/
 	async deleteOne(id, opts) {
 		this._ensureBuilt();
-		const filter = this._resolveIdFilter(id, opts);
-		if (!filter) return { deletedCount: 0 };
+		const candidates = this._idCandidates(id, opts);
+		if (candidates.length === 0) return { deletedCount: 0 };
 		const guard = opts?.guard;
 		const needsCascade = this._integrity.needsCascade(this._cascadeResolver);
-		const translated = this._fieldMapper.translateFilter(filter, this._meta);
 		const run = async () => {
+			const pinned = await this._pinIdCandidates(candidates, opts?.scope);
+			const filter = this._andScope(pinned, opts?.scope);
+			const translated = this._fieldMapper.translateFilter(filter, this._meta);
 			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());
+		return remapDeleteFkViolation(this.tableName, () => guard || needsCascade || candidates.length > 1 ? this.adapter.withTransaction(run) : run());
 	}
 	async updateMany(filter, data) {
 		this._ensureBuilt();
@@ -4994,23 +5427,188 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		}
 	}
 	/**
-	* 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.
+	* The record filter a guard's `current(i)` reads its pre-image by: `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. Identified
+	* exactly like the write itself (primary key first, then a unique index —
+	* since 0.1.143), so it is always the row the write targets.
 	* @internal
 	*/
-	async _readPreImage(row) {
-		if (!row) return null;
-		let filter;
+	_recordFilterOrNull(row, opts) {
+		if (!row || typeof row !== "object") return null;
 		try {
-			filter = this._resolveIdFilter(row);
+			return this._extractRecordFilter(row, opts);
 		} catch {
 			return null;
 		}
-		if (!filter) return null;
-		return await this.findOne({
-			filter,
-			controls: {}
+	}
+	/**
+	* Each item's record filter (see {@link _extractRecordFilter}). A nested
+	* FROM re-entry (`_ownedBy`) also pins the child's foreign key to its
+	* parent, so the write never touches a child of another parent.
+	*/
+	_rowFilters(items, opts) {
+		const owner = opts?._ownedBy?.field;
+		return items.map((item) => {
+			const filter = this._extractRecordFilter(item, opts);
+			return owner === void 0 || item[owner] === void 0 ? filter : {
+				...filter,
+				[owner]: this._prepareFilterValue(owner, item[owner])
+			};
+		});
+	}
+	/** Whether `filter` names every primary-key field (so it IS the row's exact key). */
+	_isPkFilter(filter) {
+		const pkFields = this.primaryKeys;
+		return pkFields.length > 0 && pkFields.every((f) => filter[f] !== void 0);
+	}
+	/**
+	* The TO relations with their single-field local foreign key (lazily
+	* listed) — what a write pins per item for its nested TO phase.
+	*/
+	_toRelationsCache;
+	_toRelations() {
+		if (!this._toRelationsCache) {
+			const out = [];
+			for (const [navField, relation] of this._meta.relations) {
+				if (relation.direction !== "to") continue;
+				const fk = this._findFKForRelation(relation);
+				out.push({
+					navField,
+					fkField: fk?.localFields.length === 1 ? fk.localFields[0] : void 0
+				});
+			}
+			this._toRelationsCache = out;
+		}
+		return this._toRelationsCache;
+	}
+	/** Whether `item` carries a nested TO object (Phase 1 work). */
+	_carriesNestedTo(item) {
+		return this._toRelations().some(({ navField }) => {
+			const nested = item[navField];
+			return !!nested && typeof nested === "object" && !Array.isArray(nested);
+		});
+	}
+	/**
+	* Reads — once per write call, inside its transaction — the stored row
+	* each item `need`s, by the item's record filter: its primary key, version
+	* and single-field TO foreign keys, in ONE read for the batch. A pre-image
+	* the guard's `current(i)` already read by the same filter is reused.
+	* `null` = no such row; `undefined` = not needed.
+	*/
+	async _pinTargets(rowFilters, need, guardCtx) {
+		const targets = [];
+		const pending = [];
+		for (let i = 0; i < rowFilters.length; i++) {
+			if (!need(i)) continue;
+			const read = guardCtx?.readFor(i, rowFilters[i]);
+			if (read) targets[i] = await read;
+			else pending.push(i);
+		}
+		if (pending.length === 0) return targets;
+		const select = new Set(this.primaryKeys);
+		const versionField = this._meta.versionField;
+		if (versionField !== void 0) select.add(versionField);
+		for (const { fkField } of this._toRelations()) if (fkField !== void 0) select.add(fkField);
+		for (const i of pending) for (const field in rowFilters[i]) select.add(field);
+		const controls = { $select: [...select] };
+		const filters = pending.map((i) => rowFilters[i]);
+		const rows = await this.findMany({
+			filter: filters.length === 1 ? filters[0] : { $or: filters },
+			controls
+		});
+		const used = /* @__PURE__ */ new Set();
+		for (const i of pending) {
+			const row = rows.find((r) => rowMatchesKey(r, rowFilters[i]));
+			targets[i] = row ?? null;
+			if (row) used.add(row);
+		}
+		if (used.size < rows.length) {
+			for (const i of pending) if (targets[i] === null) targets[i] = await this.findOne({
+				filter: rowFilters[i],
+				controls
+			});
+		}
+		return targets;
+	}
+	/**
+	* The exact primary-key filter of every row the write matched: the record
+	* filter itself when it is the primary key, else the pinned row's key.
+	*/
+	_writtenPkFilters(rowFilters, targets, matched) {
+		const out = [];
+		for (let i = 0; i < rowFilters.length; i++) {
+			if (!matched[i]) continue;
+			const target = targets[i];
+			const filter = this._isPkFilter(rowFilters[i]) ? rowFilters[i] : target ? this._pkFilterFrom(target) : null;
+			if (filter) out.push(filter);
+		}
+		return out;
+	}
+	/** Invokes a {@link TWriteOptions.check} with de-duplicated PK filters (inside the transaction). */
+	async _runWriteCheck(check, action, filters) {
+		const pkFields = this.primaryKeys;
+		const seen = /* @__PURE__ */ new Set();
+		const unique = [];
+		for (const filter of filters) {
+			const key = pkTupleKey(filter, pkFields);
+			if (seen.has(key)) continue;
+			seen.add(key);
+			unique.push(filter);
+		}
+		await check({
+			action,
+			filters: unique,
+			transactional: this.adapter.isInTransaction(),
+			count: (filter) => this.count({
+				filter,
+				controls: {}
+			})
+		});
+	}
+	/**
+	* The exact primary-key filter of each inserted row: the logical key from
+	* the row (SDK defaults applied), else the stored key the adapter wrote into
+	* the prepared row (e.g. a driver-assigned `_id`), else — single-field keys
+	* only — the adapter's `insertedIds` (auto-increment).
+	*/
+	_insertedPkFilters(items, prepared, insertedIds) {
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 0 && items.length > 0) throw new DbError("INVALID_QUERY", [{
+			path: "",
+			message: "Write check requires a primary key on the table"
+		}]);
+		return items.map((item, i) => {
+			const key = {};
+			for (const field of pkFields) {
+				let value = item[field];
+				if (value === void 0) value = prepared[i]?.[this._meta.columnMap.get(field) ?? field];
+				if (value === void 0 && pkFields.length === 1) value = insertedIds[i];
+				if (value === void 0 || value === null) throw new DbError("INVALID_QUERY", [{
+					path: field,
+					message: `Write check: cannot resolve the primary key of inserted row [${i}]`
+				}]);
+				key[field] = value;
+			}
+			return this._pkFilterFrom(key);
+		});
+	}
+	/**
+	* Drops the nested TO objects of every replace item whose main replace
+	* cannot match (pinned row missing, or stale `$cas`) so Phase 1 never
+	* writes a related row for a replace that does nothing. Returns, per item,
+	* whether its TO objects stay (a later 0-match for such an item is a
+	* concurrent change and rolls back).
+	*/
+	_gateNestedTo(items, nestedTo, targets, expectedVersions) {
+		const versionField = this._meta.versionField;
+		return items.map((item, i) => {
+			if (!nestedTo[i]) return false;
+			const row = targets[i];
+			const expected = expectedVersions[i];
+			const kept = !!row && (expected === void 0 || versionField === void 0 || sameKey(row[versionField], expected));
+			if (!kept) for (const { navField } of this._toRelations()) delete item[navField];
+			return kept;
 		});
 	}
 	/**
@@ -5059,6 +5657,19 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		}
 	}
 	/**
+	* The filter an `updateOne` / `replaceOne` of `payload` targets its row by
+	* — the write's own resolution (primary key first, then a unique index;
+	* see {@link _extractRecordFilter}), so a caller explaining a write's
+	* outcome (e.g. a CAS mismatch) reads exactly the row the write addressed.
+	* Throws `NOT_FOUND` when the payload carries no identifying fields.
+	*
+	* @since 0.1.143
+	*/
+	recordFilter(payload, opts) {
+		this._ensureBuilt();
+		return this._extractRecordFilter(payload, opts);
+	}
+	/**
 	* Extracts a record-identifying filter from a payload.
 	*
 	* Resolution order:
@@ -5072,18 +5683,8 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	_extractRecordFilter(payload, opts) {
 		const pkFields = this.primaryKeys;
-		if (pkFields.length > 0) {
-			let allPresent = true;
-			for (const field of pkFields) if (payload[field] === void 0) {
-				allPresent = false;
-				break;
-			}
-			if (allPresent) {
-				const filter = {};
-				for (const field of pkFields) filter[field] = this._prepareFilterValue(field, payload[field]);
-				return filter;
-			}
-		}
+		const pkFilter = this._pkFilterFrom(payload);
+		if (pkFilter) return pkFilter;
 		const identifications = this.identificationsVisibleTo(opts?.isFieldVisible);
 		const singleFields = /* @__PURE__ */ new Set();
 		for (const ident of identifications) if (ident.source !== "primaryKey" && ident.fields.length === 1) singleFields.add(ident.fields[0]);
@@ -5221,6 +5822,81 @@ function readViewAgg(metadata) {
 		};
 	}
 }
+/** The type getter of a `@db.view.for` / join / chain ref (a bare getter or `{ type }`). */
+function refType(ref) {
+	return typeof ref === "function" ? ref : ref.type;
+}
+/**
+* Where a view field reads from: its chain ref, else — on the entry table —
+* the aggregate's field, else the same-named field. `sourceType` is
+* `undefined` for an external view's untyped field (no entry table).
+*/
+function viewFieldSource(fieldName, fieldType, entryType) {
+	const agg = readViewAgg(fieldType.metadata);
+	const chainRef = fieldType.ref?.field ? fieldType.ref : void 0;
+	if (chainRef) return {
+		agg,
+		chained: true,
+		sourceType: chainRef.type(),
+		sourcePath: chainRef.field
+	};
+	const aggField = agg?.aggField;
+	return {
+		agg,
+		chained: false,
+		sourceType: entryType?.(),
+		sourcePath: aggField && aggField !== "*" ? aggField : fieldName
+	};
+}
+/** View types whose fields already carry their inherited seals. */
+const sealedViews = /* @__PURE__ */ new WeakSet();
+/**
+* Whether `type` declares a view (managed `@db.view.for` or external
+* `@db.view`) — how `DbSpace.get` tells views from tables.
+* @since 0.1.143
+*/
+function isViewType(type) {
+	return type.metadata.has("db.view") || type.metadata.has("db.view.for");
+}
+/**
+* Carries the read seals of each view column's source field onto the view
+* type's own field metadata (since 0.1.143), so a view never exposes a value
+* differently from the table it reads:
+*
+* - `@db.writeOnly` — a column reading a write-only field (or a leaf of a
+*   write-only object), or aggregating one, is write-only on the view too, so
+*   HTTP layers seal it exactly as on the table.
+* - `@db.encrypted` — a column reading an encrypted field reads its
+*   ciphertext, so it is encrypted on the view too: rows come back decrypted
+*   and filters / sorts on it are rejected, as on the table. An aggregate over
+*   an encrypted field is rejected (the table refuses it as well).
+*
+* The source is resolved exactly like {@link AtscriptDbView.getViewColumnMappings}
+* does ({@link viewFieldSource}); a source that is itself a view is sealed
+* first. Runs once per view type, when a view over it is first built.
+*/
+function inheritViewFieldSeals(viewType) {
+	if (sealedViews.has(viewType) || viewType.type.kind !== "object") return;
+	sealedViews.add(viewType);
+	try {
+		const forRef = viewType.metadata.get("db.view.for");
+		const entryType = forRef && refType(forRef);
+		for (const [fieldName, fieldType] of viewType.type.props.entries()) {
+			const { agg, sourceType, sourcePath } = viewFieldSource(fieldName, fieldType, entryType);
+			if (agg?.aggField === "*" || !sourceType) continue;
+			const source = viewSourceOf(sourceType).type;
+			if (isViewType(source)) inheritViewFieldSeals(source);
+			const seals = sourceFieldSeals(source, sourcePath);
+			if (seals.writeOnly) fieldType.metadata.set("db.writeOnly", true);
+			if (!seals.encrypted) continue;
+			if (agg) throw new Error(`View "${tableNameOf(viewType)}" field "${fieldName}": @db.agg.${agg.aggFn} over the @db.encrypted field "${sourcePath}" — ciphertext cannot be aggregated`);
+			fieldType.metadata.set("db.encrypted", true);
+		}
+	} catch (error) {
+		sealedViews.delete(viewType);
+		throw error;
+	}
+}
 /**
 * Database view abstraction driven by Atscript `@db.view.*` annotations.
 *
@@ -5241,6 +5917,15 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		return true;
 	}
 	/**
+	* Builds the view's metadata — first stamping its fields with their
+	* sources' read seals (`inheritViewFieldSeals`, once per view type), so
+	* every metadata consumer sees the sealed type.
+	*/
+	_ensureBuilt() {
+		if (!this._meta.isBuilt) inheritViewFieldSeals(this._type);
+		super._ensureBuilt();
+	}
+	/**
 	* Whether this is an external view — declared with `@db.view` only,
 	* without `@db.view.for`. External views reference pre-existing DB views
 	* and are not managed (created/dropped) by schema sync.
@@ -5260,16 +5945,14 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		if (this._viewPlan) return this._viewPlan;
 		if (this.isExternal) throw new Error(`Cannot compute view plan for external view "${this.tableName}". External views (declared without @db.view.for) reference pre-existing DB views.`);
 		const metadata = this._type.metadata;
-		const forRef = metadata.get("db.view.for");
-		const entryType = typeof forRef === "function" ? forRef : forRef.type;
+		const entryType = refType(metadata.get("db.view.for"));
 		const entry = viewSourceOf(entryType());
 		if (entry.alias) throw new Error(`View "${this.tableName}": @db.view.for "${entry.name}" is a @db.alias — a join alias cannot be the entry table`);
 		const entryTable = entry.table;
 		const rawJoins = metadata.get("db.view.joins");
 		const joins = [];
 		if (rawJoins) for (const join of rawJoins) {
-			const targetRef = join.target;
-			const targetType = typeof targetRef === "function" ? targetRef : targetRef.type;
+			const targetType = refType(join.target);
 			const target = viewSourceOf(targetType());
 			joins.push({
 				targetType,
@@ -5368,23 +6051,13 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 		const leftJoined = new Set(plan.joins.filter((j) => j.kind === "left").map((j) => j.scope));
 		for (const [fieldName, fieldType] of this._type.type.props.entries()) {
 			if (ignored.has(fieldName)) continue;
-			const agg = readViewAgg(fieldType.metadata);
+			const { agg, chained, sourceType, sourcePath } = viewFieldSource(fieldName, fieldType, plan.entryType);
 			const aggField = agg?.aggField;
 			if (aggField === "*" && agg?.aggFn !== "count") fail(fieldName, `aggregate "${agg?.aggFn}" needs a field — only count accepts *`);
-			let sourceType;
-			let sourcePath;
-			const chainRef = fieldType.ref?.field ? fieldType.ref : void 0;
-			if (chainRef) {
-				sourceType = chainRef.type();
-				sourcePath = chainRef.field;
-			} else {
-				sourceType = plan.entryType();
-				sourcePath = aggField && aggField !== "*" ? aggField : fieldName;
-			}
 			const src = viewSourceOf(sourceType);
 			const sourceTable = src.name;
 			const joinNullable = leftJoined.has(sourceTable);
-			if (aggField === "*" && !chainRef) {
+			if (aggField === "*" && !chained) {
 				mappings.push({
 					viewColumn: viewName(fieldName) ?? fieldName,
 					viewPath: fieldName,
@@ -5845,4 +6518,4 @@ function computeColumnDiff(desired, existing, typeMapper, opts) {
 	return diff;
 }
 //#endregion
-export { isJsonValueField as $, assertGeoPoint as A, guardQuery as B, IntegrityStrategy as C, ADAPTER_FILTER_REASON as D, resolveDesignType as E, collectQueryPaths as F, DocumentFieldMapper as G, sortFieldNames as H, guardAggregate as I, TableMetadata as J, FieldMappingStrategy as K, guardFilter as L, canFilterLeaf as M, checkHavingKeys as N, ENCRYPTED_REASON as O, classifyQueryPath as P, isBucketableField as Q, guardPath as R, createFailureCollector as S, AtscriptDbReadable as T, unsupportedOperatorMessage as U, narrowerFilterOps as V, RelationalFieldMapper as W, isGeoPointType as X, isGeoIndexableType as Y, aliasTargetOf as Z, assertNoVersionWrites as _, hasForeignKeyChanges as a, ALL_BUCKET_UNITS as b, computeTableHash as c, snapshotToExistingColumns as d, jsonValueAncestor as et, snapshotToExistingTableOptions as f, AtscriptDbTable as g, isAtscriptDbView as h, fkKey as i, bucketSourceVerdict as j, acceptedOperatorsHint as k, computeTableSnapshot as l, AtscriptDbView as m, isColumnTypeChanged as n, resolveCalendarBuckets as nt, canonicalizeQueryNode as o, viewSnapshotSources as p, UniquSelect as q, computeForeignKeyDiff as r, NoopLogger as rt, computeSchemaHash as s, computeColumnDiff as t, normalizeComputedSelect as tt, computeViewSnapshot as u, decomposePatch as v, NativeIntegrity as w, BaseDbAdapter as x, ApplicationIntegrity as y, guardPaths as z };
+export { isGeoIndexableType as $, vectorIndexNotFoundMessage as A, guardAggregate as B, createFailureCollector as C, resolveDesignType as D, AtscriptDbReadable as E, bucketSourceVerdict as F, narrowerFilterOps as G, guardPath as H, canFilterLeaf as I, RelationalFieldMapper as J, sortFieldNames as K, checkHavingKeys as L, ENCRYPTED_REASON as M, acceptedOperatorsHint as N, geoIndexNotFoundMessage as O, assertGeoPoint as P, TableMetadata as Q, classifyQueryPath as R, BaseDbAdapter as S, NativeIntegrity as T, guardPaths as U, guardFilter as V, guardQuery as W, FieldMappingStrategy as X, DocumentFieldMapper as Y, UniquSelect as Z, AtscriptDbTable as _, hasForeignKeyChanges as a, normalizeComputedSelect as at, ApplicationIntegrity as b, computeTableHash as c, snapshotToExistingColumns as d, isGeoPointType as et, snapshotToExistingTableOptions as f, isViewType as g, isAtscriptDbView as h, fkKey as i, jsonValueAncestor as it, ADAPTER_FILTER_REASON as j, searchIndexNotFoundMessage as k, computeTableSnapshot as l, AtscriptDbView as m, isColumnTypeChanged as n, isBucketableField as nt, canonicalizeQueryNode as o, resolveCalendarBuckets as ot, viewSnapshotSources as p, unsupportedOperatorMessage as q, computeForeignKeyDiff as r, isJsonValueField as rt, computeSchemaHash as s, NoopLogger as st, computeColumnDiff as t, aliasTargetOf as tt, computeViewSnapshot as u, assertNoVersionWrites as v, IntegrityStrategy as w, ALL_BUCKET_UNITS as x, decomposePatch as y, collectQueryPaths as z };