@atscript/moost-db 0.1.132 → 0.1.134

package/dist/index.cjs

@@ -1155,16 +1155,12 @@ function resolveBoundReadable(ctor) {
 }
 //#endregion
 //#region src/meta/field-capabilities.ts
-const ADAPTER_FILTER = "adapter cannot filter on this storage type";
-const REASON_ADAPTER_FILTER = `${ADAPTER_FILTER}.`;
+const REASON_ADAPTER_FILTER = `${_atscript_db.ADAPTER_FILTER_REASON}.`;
 const REASON_ADAPTER_SORT = "adapter cannot sort on this storage type.";
 const REASON_WRITE_ONLY = "field is @db.writeOnly.";
-const REASON_ENCRYPTED = "field is @db.encrypted (ciphertext cannot be compared or ordered).";
+const REASON_ENCRYPTED = `${_atscript_db.ENCRYPTED_REASON}.`;
 const REASON_ANNOTATION_FILTER = "add @db.column.filterable to enable.";
 const REASON_ANNOTATION_SORT = "add @db.column.sortable to enable.";
-const REASON_NOT_TIMESTAMP = "not a timestamp field (declare it number.timestamp).";
-const REASON_NOT_DIMENSION = "not a dimension.";
-const REASON_NO_BUCKETS = "adapter has no calendar buckets.";
 /** Sentence subject per op ("Filtering on field …"). */
 const OP_SUBJECT = {
 	filter: "Filtering on",
@@ -1185,6 +1181,13 @@ const OP_VERB = {
 	aggregate: "aggregate over",
 	bucket: "bucket"
 };
+/** The one "nonexistent path" verdict — hidden paths answer with it byte for byte. */
+function unknownField(path) {
+	return {
+		path,
+		message: `Unknown field "${path}"`
+	};
+}
 function leafHint(leaves) {
 	if (leaves.length === 0) return "no leaf fields";
 	const shown = leaves.slice(0, 5).join(", ");
@@ -1235,14 +1238,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	_entries = /* @__PURE__ */ new Map();
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
 	_objectParents = /* @__PURE__ */ new Map();
-	/**
-	* Declared dimensions when the table is strict (declares dimensions or
-	* measures), else `undefined` — the core rule: a grouping source, a
-	* bucketed field included, must then be a dimension.
-	*/
-	_dimensions;
-	/** Paths of every JSON-value descriptor (`isJsonValueField`) — see `jsonValueAncestor`. */
-	_jsonValueParents;
+	/** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
+	_bucketTable;
 	/** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
 	get leaves() {
 		return this._entries;
@@ -1259,7 +1256,6 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		this.signature = FieldCapabilityIndex.adapterSignature(source);
 		const units = source.calendarBucketUnits();
 		this.bucketUnits = _uniqu_core.BUCKET_UNITS.filter((unit) => units.has(unit));
-		this._dimensions = source.dimensions.length > 0 || source.measures.length > 0 ? new Set(source.dimensions) : void 0;
 		const physicalNames = /* @__PURE__ */ new Set();
 		const jsonValueParents = /* @__PURE__ */ new Set();
 		for (const fd of source.fieldDescriptors) {
@@ -1267,7 +1263,11 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			if ((0, _atscript_db.isJsonValueField)(fd)) jsonValueParents.add(fd.path);
 		}
 		this.physicalNames = physicalNames;
-		this._jsonValueParents = jsonValueParents;
+		this._bucketTable = {
+			jsonValueParents,
+			dimensions: source.dimensions,
+			measures: source.measures
+		};
 		const nav = new Set(source.navFields);
 		if (nav.size === 0) for (const name of source.relations.keys()) nav.add(name);
 		this.navFields = nav;
@@ -1324,18 +1324,14 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 			geo: verdict("geo", true)
 		};
 		const filterOps = filterBy.compare === REASON_ADAPTER_FILTER && !filterPolicyBlocked ? (0, _atscript_db.narrowerFilterOps)(fd, source) : [];
-		if (filterOps.length > 0) filterBy.compare = `${ADAPTER_FILTER}${(0, _atscript_db.acceptedOperatorsHint)(filterOps)}.`;
+		if (filterOps.length > 0) filterBy.compare = `${_atscript_db.ADAPTER_FILTER_REASON}${(0, _atscript_db.acceptedOperatorsHint)(filterOps)}.`;
 		const physicalReason = verdict("compare", false);
 		let sortReason = source.canSortField(fd) ? void 0 : REASON_ADAPTER_SORT;
 		if (fd.encrypted) sortReason = REASON_ENCRYPTED;
 		if (isWriteOnly) sortReason = REASON_WRITE_ONLY;
 		if (!sortReason && this.sortableManual && !annotated(fd, "db.column.sortable")) sortReason = REASON_ANNOTATION_SORT;
-		let bucketReason = physicalReason;
-		const jsonAncestor = (0, _atscript_db.jsonValueAncestor)(fd.path, this._jsonValueParents);
-		if (!bucketReason && jsonAncestor !== void 0) bucketReason = `inside JSON-stored column "${jsonAncestor}".`;
-		if (!bucketReason && !(0, _atscript_db.isBucketableField)(fd)) bucketReason = REASON_NOT_TIMESTAMP;
-		if (!bucketReason && this._dimensions && !this._dimensions.has(fd.path)) bucketReason = REASON_NOT_DIMENSION;
-		if (!bucketReason && this.bucketUnits.length === 0) bucketReason = REASON_NO_BUCKETS;
+		const bucket = isWriteOnly ? void 0 : (0, _atscript_db.bucketSourceVerdict)(fd, this._bucketTable, source);
+		const bucketReason = !bucket ? REASON_WRITE_ONLY : bucket.ok ? void 0 : `${bucket.reason}.`;
 		const cap = {
 			filterable: filterBy.compare === void 0,
 			sortable: sortReason === void 0,
@@ -1369,21 +1365,29 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	}
 	/**
 	* Gate check for one path in one position. Returns `undefined` when the
-	* path is accepted. Order: navigation paths first (a nav path "exists" on
-	* the target table but is never a column here), then a listed leaf's
-	* capability (no existence lookup needed — every listed leaf is a real
-	* field), then `exists` (the readable's `isValidFieldPath`) and, for paths
-	* that exist but are not leaves, the storage classification.
+	* path is accepted.
 	*
-	* Existence deliberately runs BEFORE the JSON / encrypted classification:
-	* an untyped descendant of a JSON column (`address.nope`) is reported as
-	* `Unknown field`, not as "inside JSON-stored column" — clients pin that
-	* wording, so do not "align" it with the core backstop's text.
+	* `exists` runs FIRST, for every path (since 0.1.133): it is the
+	* controller's `hasField`, the visibility hook subclasses narrow per
+	* request (e.g. a projection-scoped viewer). A path it rejects answers
+	* `Unknown field "x"` exactly like a nonexistent one — never a capability
+	* or navigation hint, which would reveal the field and let a filter or
+	* sort on it act as a value oracle. Before 0.1.133 listed leaves and
+	* navigation paths skipped it.
+	*
+	* Then: navigation paths (a nav path exists on the target table but is
+	* never a column here), a listed leaf's capability, and for other paths
+	* the storage classification. Existence also runs BEFORE the JSON /
+	* encrypted classification: an untyped descendant of a JSON column
+	* (`address.nope`) is reported as `Unknown field`, not as "inside
+	* JSON-stored column" — clients pin that wording, so do not "align" it
+	* with the core backstop's text.
 	*
 	* `predicate` is a filter entry's class (`collectQueryPaths` records it per
 	* occurrence); it only matters for `op === "filter"` on a listed leaf.
 	*/
 	check(path, op, exists, predicate = "compare") {
+		if (!exists(path)) return unknownField(path);
 		const { kind, parent } = (0, _atscript_db.classifyQueryPath)(this, path);
 		if (kind === "nav") {
 			if (parent === void 0) return {
@@ -1423,17 +1427,17 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 				};
 			}
 		}
-		if (!exists(path)) return {
-			path,
-			message: `Unknown field "${path}"`
-		};
 		switch (kind) {
-			case "objectParent":
+			case "objectParent": {
 				if (op === "select") return void 0;
+				const all = this._objectParents.get(path);
+				const leaves = all.filter(exists);
+				if (leaves.length === 0 && all.length > 0) return unknownField(path);
 				return {
 					path,
-					message: `"${path}" is a nested object — filter or sort on one of its leaves (${leafHint(this._objectParents.get(path))})`
+					message: `"${path}" is a nested object — filter or sort on one of its leaves (${leafHint(leaves)})`
 				};
+			}
 			case "jsonDescendant": return {
 				path,
 				message: `"${path}" is inside JSON-stored column "${parent}" — this adapter cannot ${OP_VERB[op]} JSON paths; select "${parent}" and read the value client-side.`
@@ -1445,10 +1449,7 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 				path,
 				message: `Cannot ${OP_VERB[op]} encrypted field "${path}"`
 			};
-			default: return {
-				path,
-				message: `Unknown field "${path}"`
-			};
+			default: return unknownField(path);
 		}
 	}
 };
@@ -1490,6 +1491,7 @@ const GEO_CONTROLS = [
 ];
 //#endregion
 //#region src/as-db-readable.controller.ts
+var _AsDbReadableController;
 /** Gate positions checked after the filter entries, in order; `refs[op]` are their paths. */
 const PATH_OPS = [
 	"sort",
@@ -1499,7 +1501,7 @@ const PATH_OPS = [
 	"aggregate",
 	"bucket"
 ];
-let AsDbReadableController = class AsDbReadableController extends AsReadableController {
+let AsDbReadableController = _AsDbReadableController = class AsDbReadableController extends AsReadableController {
 	/** Reference to the underlying readable (table or view). */
 	readable;
 	/**
@@ -1537,8 +1539,17 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	metaCacheKey() {
 		return this.capabilities;
 	}
-	/** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+	/** Bound once: the visibility check ({@link hasField}) the gate hands to `capabilities.check`. */
 	_exists = (path) => this.hasField(path);
+	/**
+	* Id-resolution options (since 0.1.134): `{ isFieldVisible: hasField }`
+	* when a subclass overrides {@link hasField}, else `undefined` (the default
+	* accepts every real path, so resolution stays unfiltered). A unique index
+	* over a hidden field is never an identification.
+	*/
+	_idOpts;
+	/** Narrowed id sources, one stable object per distinct visible-identification set. */
+	_idSources = /* @__PURE__ */ new Map();
 	_preferredIdSet;
 	_overlayIsNoOp;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
@@ -1564,6 +1575,29 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		this._quantityRefByPath = this._collectQuantityRefs();
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
+		this._idOpts = this.hasField === _AsDbReadableController.prototype.hasField ? void 0 : { isFieldVisible: this._exists };
+	}
+	/**
+	* The identifications this request may address rows through (since
+	* 0.1.134): the readable's own, minus unique indexes over fields
+	* {@link hasField} hides. Used by `/one?…`, `DELETE /?…` and action `ids`.
+	* Stable per distinct outcome, so per-source caches keyed on it hit.
+	*/
+	get idSource() {
+		const opts = this._idOpts;
+		if (!opts) return this.readable;
+		const visible = this.readable.identificationsVisibleTo(opts.isFieldVisible);
+		if (visible.length === this.readable.identifications.length) return this.readable;
+		const key = visible.map((ident) => ident.source).join("");
+		let source = this._idSources.get(key);
+		if (!source) {
+			source = {
+				identifications: visible,
+				fieldDescriptors: this.readable.fieldDescriptors
+			};
+			this._idSources.set(key, source);
+		}
+		return source;
 	}
 	_collectInvertibleFields() {
 		const out = [];
@@ -1590,6 +1624,24 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		for (const [path, entry] of this.readable.flatMap) if (entry?.metadata?.has?.(annotation)) out.add(path);
 		return out;
 	}
+	/**
+	* THE field-visibility hook: every gated path consults it before any
+	* capability check (since 0.1.133) — filter keys (inside `$and` / `$or` /
+	* `$not`, existence predicates included), `$sort`, `$select`,
+	* `$groupBy`, `$having` keys, aggregate and calendar-bucket `$field`s,
+	* `$with` relation names and sub-query paths, and the `$search` fallback
+	* fields. A path it rejects is answered exactly like a nonexistent one
+	* (`Unknown field "x"` / `Unknown relation "x"`), so override it to hide
+	* fields per request (read scopes). Since 0.1.134 it also governs row
+	* identification — a unique index over a hidden field is not an
+	* identification for `/one/:id`, `/one?…`, `DELETE`, a PK-less `PATCH` or
+	* an action id (primary key and `preferredId` always are) — and the
+	* nested-object 400 hint lists visible leaves only. The default accepts every real path
+	* (`isValidFieldPath`). `/meta` does NOT consult it — prune hidden fields
+	* there with `applyMetaOverlay`. Native text search and vector search
+	* (`$vector` names an index) run inside the engine over its indexes, out of
+	* this hook's reach — keep hidden fields out of those indexes.
+	*/
 	hasField(path) {
 		if (typeof this.readable.isValidFieldPath === "function") return this.readable.isValidFieldPath(path);
 		return this.readable.flatMap.has(path);
@@ -1677,7 +1729,13 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		const withRelations = parsed.controls.$with;
 		if (withRelations?.length) {
 			const relations = this.readable.relations;
-			for (const rel of withRelations) if (!rel.name.includes(".") && !relations.has(rel.name)) return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${[...relations.keys()].join(", ") || "(none)"}`);
+			for (const rel of withRelations) {
+				const dot = rel.name.indexOf(".");
+				if (!(dot === -1 ? relations.has(rel.name) && this.hasField(rel.name) : this.hasField(rel.name.slice(0, dot)))) {
+					const visible = [...relations.keys()].filter((name) => this.hasField(name));
+					return badRequest("$with", `Unknown relation "${rel.name}"`, `Unknown relation "${rel.name}" in $with. Available relations: ${visible.join(", ") || "(none)"}`);
+				}
+			}
 		}
 	}
 	/**
@@ -1752,11 +1810,26 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			return widened;
 		}
 		const widened = {};
-		for (const path of this._invertibleFields) if (!excluded.has(path)) widened[path] = 1;
+		for (const path of this._invertExclusion(excluded)) widened[path] = 1;
 		for (const field of this._preferredIdSet) widened[field] = 1;
 		return widened;
 	}
 	/**
+	* The logical paths an exclusion keeps. A path goes when it, an ancestor
+	* or a descendant is excluded: excluding an object parent excludes its
+	* whole subtree, and a kept parent would carry an excluded child back
+	* (its other leaves stay listed on their own). Before 0.1.134 only the
+	* exact paths were dropped, so `$select=-a` still returned `a`'s leaves.
+	*/
+	_invertExclusion(excluded) {
+		return this._invertibleFields.filter((path) => {
+			if (excluded.has(path) || (0, _atscript_db.findAncestorInSet)(path, excluded) !== void 0) return false;
+			const prefix = `${path}.`;
+			for (const key of excluded) if (key.startsWith(prefix)) return false;
+			return true;
+		});
+	}
+	/**
 	* Auto-includes the sibling-ref field whenever its `@db.amount.currency.ref`
 	* / `@db.unit.ref` quantity is selected — UI must never get a value without
 	* its dimension. No-op when `$select` is undefined (full row covers it).
@@ -1819,10 +1892,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		for (const [k, v] of Object.entries(obj)) if (v === 1 || v === true) included.push(k);
 		else if (v === 0 || v === false) excluded.push(k);
 		if (included.length > 0 && excluded.length === 0) return included;
-		if (excluded.length > 0 && included.length === 0) {
-			const excludedSet = new Set(excluded);
-			return this._invertibleFields.filter((path) => !excludedSet.has(path));
-		}
+		if (excluded.length > 0 && included.length === 0) return this._invertExclusion(new Set(excluded));
 		throw new _moostjs_event_http.HttpError(500, "[moost-db] mixed inclusion/exclusion projection reached augmenter; widenPreferredIdProjection should have rejected it");
 	}
 	/** WHY: filter row/rows envelopes by the per-request `applyMetaOverlay` action set; skip `meta()` when overlay is identity. */
@@ -1914,10 +1984,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	/** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
 	_findWriteOnlyInAggregate(groupBy, select) {
 		if (this._writeOnlySet.size === 0) return void 0;
-		for (const f of groupBy) if (this._writeOnlySet.has(f)) return f;
+		const sealed = (f) => this._writeOnlySet.has(f) && this.hasField(f);
+		for (const f of groupBy) if (sealed(f)) return f;
 		if (Array.isArray(select)) for (const item of select) {
 			const field = typeof item === "string" ? item : item.$field;
-			if (field && this._writeOnlySet.has(field)) return field;
+			if (field && sealed(field)) return field;
 		}
 	}
 	/**
@@ -1929,9 +2000,11 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
 		if (!term || controls.$vector !== void 0) return filter;
-		if (this.readable.isSearchable() || this._searchFallbackFields.length === 0) return filter;
+		if (this.readable.isSearchable()) return filter;
+		const fields = this._searchFallbackFields.filter((f) => this.hasField(f));
+		if (fields.length === 0) return filter;
 		const rx = `/${term.replace(/[.*+?^${}()|[\]\\/]/g, String.raw`\$&`)}/i`;
-		const fragment = { $or: this._searchFallbackFields.map((f) => ({ [f]: { $regex: rx } })) };
+		const fragment = { $or: fields.map((f) => ({ [f]: { $regex: rx } })) };
 		return filter && Object.keys(filter).length > 0 ? { $and: [filter, fragment] } : fragment;
 	}
 	/**
@@ -2000,9 +2073,14 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 		});
 		return result;
 	}
-	/** Pick the first identification (PK or unique index) whose fields are all present in the query. */
+	/**
+	* Pick the first identification (PK or unique index) whose fields are all
+	* present in the query. A unique index over a field {@link hasField} hides
+	* is not a candidate (since 0.1.134) — `?hidden=x` answers exactly like
+	* `?nope=x`, so it cannot probe whether a row with that value exists.
+	*/
 	extractIdShape(query) {
-		for (const id of this.readable.identifications) {
+		for (const id of this.idSource.identifications) {
 			const idObj = {};
 			let allPresent = true;
 			for (const field of id.fields) {
@@ -2239,7 +2317,7 @@ let AsDbReadableController = class AsDbReadableController extends AsReadableCont
 			...parsedControls,
 			$select: initialSelect
 		};
-		const idFilter = this.readable.resolveIdFilter(id);
+		const idFilter = this.readable.resolveIdFilter(id, this._idOpts);
 		let row = null;
 		if (idFilter) {
 			const overlay = await this.transformOne({});
@@ -2362,7 +2440,7 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [typeof Record === "undefined" ? Object : Record, String]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsDbReadableController.prototype, "getOneComposite", null);
-AsDbReadableController = __decorate([
+AsDbReadableController = _AsDbReadableController = __decorate([
 	(0, moost.Inherit)(),
 	__decorateParam(1, (0, moost.Inject)(READABLE_DEF)),
 	__decorateParam(1, (0, moost.Optional)()),
@@ -2394,6 +2472,9 @@ function hasWriteShape(data, many) {
 let AsDbController = _AsDbController = class AsDbController extends AsDbReadableController {
 	constructor(app, table) {
 		super(app, table);
+		const proto = _AsDbController.prototype;
+		this._writeArgs = this._hookArgs(this.guardWrite !== proto.guardWrite ? (ctx) => this.guardWrite(ctx) : void 0);
+		this._removeArgs = this._hookArgs(this.guardRemove !== proto.guardRemove ? (ctx) => this.guardRemove(ctx) : void 0);
 	}
 	buildCrud() {
 		return {
@@ -2461,19 +2542,20 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	withTransaction(fn) {
 		return this.table.getAdapter().withTransaction(fn);
 	}
+	/** The table write call's trailing options — see {@link _hookArgs}. */
+	_writeArgs;
+	/** `deleteOne`'s trailing options — see {@link _hookArgs}. */
+	_removeArgs;
 	/**
-	* The table write call's trailing options: `[{ guard }]` only when
-	* `guardWrite` is overridden, else nothing (the table is called exactly as
-	* an unmodified controller always called it).
+	* A table call's trailing options, built once: `guard` only when the guard
+	* hook is overridden, `isFieldVisible` only when `hasField` is (an id or a
+	* PK-less payload never resolves through a hidden unique key) — else
+	* nothing, so an unmodified controller calls the table exactly as before.
 	*/
-	_writeArgs() {
-		if (this.guardWrite === _AsDbController.prototype.guardWrite) return [];
-		return [{ guard: (ctx) => this.guardWrite(ctx) }];
-	}
-	/** `deleteOne`'s trailing options: `[{ guard }]` only when `guardRemove` is overridden. */
-	_removeArgs() {
-		if (this.guardRemove === _AsDbController.prototype.guardRemove) return [];
-		return [{ guard: (ctx) => this.guardRemove(ctx) }];
+	_hookArgs(guard) {
+		const opts = { ...this._idOpts };
+		if (guard) opts.guard = guard;
+		return Object.keys(opts).length > 0 ? [opts] : [];
 	}
 	/** Resolves a hook result: `undefined` aborts with `abortMessage`, an `Error` is thrown, anything else passes. */
 	async _checkHook(pending, abortMessage) {
@@ -2523,7 +2605,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	}
 	/** Deletes by id (guard forwarded when overridden) and maps "nothing deleted" to 404. */
 	async _deleteOrThrow(id) {
-		const result = await this.table.deleteOne(id, ...this._removeArgs());
+		const result = await this.table.deleteOne(id, ...this._removeArgs);
 		if (result.deletedCount < 1) throw new _moostjs_event_http.HttpError(404);
 		return result;
 	}
@@ -2534,10 +2616,10 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		assertWriteShape(payload);
 		if (Array.isArray(payload)) {
 			const rows = await this._writeBody("insertMany", payload, true);
-			return this.table.insertMany(rows, ...this._writeArgs());
+			return this.table.insertMany(rows, ...this._writeArgs);
 		}
 		const row = await this._writeBody("insert", payload, false);
-		return this.table.insertOne(row, ...this._writeArgs());
+		return this.table.insertOne(row, ...this._writeArgs);
 	}
 	/**
 	* **PUT /** — fully replaces one or many records matched by primary key.
@@ -2554,11 +2636,11 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		if (Array.isArray(payload)) {
 			const rows = await this._writeBody("replaceMany", payload, true);
 			this._resolveBulkCas(rows, versionColumn);
-			return this.table.bulkReplace(rows, ...this._writeArgs());
+			return this.table.bulkReplace(rows, ...this._writeArgs);
 		}
 		const row = await this._writeBody("replace", payload, false);
 		const hadCas = this._resolveCas(row, versionColumn);
-		const result = await this.table.replaceOne(row, ...this._writeArgs());
+		const result = await this.table.replaceOne(row, ...this._writeArgs);
 		if (hadCas && result.matchedCount === 0) throw await this._disambiguateMismatch(row, versionColumn);
 		return result;
 	}
@@ -2575,11 +2657,11 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 		if (Array.isArray(payload)) {
 			const rows = await this._writeBody("updateMany", payload, true);
 			this._resolveBulkCas(rows, versionColumn);
-			return this.table.bulkUpdate(rows, ...this._writeArgs());
+			return this.table.bulkUpdate(rows, ...this._writeArgs);
 		}
 		const row = await this._writeBody("update", payload, false);
 		const hadCas = this._resolveCas(row, versionColumn);
-		const result = await this.table.updateOne(row, ...this._writeArgs());
+		const result = await this.table.updateOne(row, ...this._writeArgs);
 		if (hadCas && result.matchedCount === 0) throw await this._disambiguateMismatch(row, versionColumn);
 		return result;
 	}
@@ -2590,7 +2672,7 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* but the supplied version is stale (§6.3). Callers throw the result.
 	*/
 	async _disambiguateMismatch(data, versionColumn) {
-		const filter = this.table.resolveIdFilter(data);
+		const filter = this.table.resolveIdFilter(data, this._idOpts);
 		const row = filter ? await this.table.findOne({
 			filter,
 			controls: {}
@@ -3139,8 +3221,11 @@ function isPlainObject(value) {
 //#endregion
 //#region src/actions/id-cache.ts
 const boundTableKey = (0, _wooksjs_event_core.key)("atscript_db_action_bound_table");
+function controllerOf(ctx) {
+	return (0, moost.useControllerContext)(ctx).getController();
+}
 function controllerTable(ctx) {
-	const ctrl = (0, moost.useControllerContext)(ctx).getController();
+	const ctrl = controllerOf(ctx);
 	return ctrl?.readable ?? ctrl?.table ?? null;
 }
 function getActionTable(ctx) {
@@ -3161,11 +3246,22 @@ function noTableError(ctx) {
 		code: "ACTION_TABLE_NOT_BOUND"
 	});
 }
+/**
+* Validates the body's `ids` against the action table's identifications. For
+* the controller's own table that is its `idSource` (since 0.1.134): a unique
+* index over a field `hasField` hides neither addresses a row nor appears in
+* the "must exactly match one of" message. An `opts.table` binding has no
+* visibility hook.
+*/
 async function resolveValidatedId(ctx, validate) {
-	const table = getActionTable(ctx);
-	if (!isIdValidationSource(table)) throw noTableError(ctx);
+	let source = ctx.has(boundTableKey) ? ctx.get(boundTableKey) : void 0;
+	if (!source) {
+		const ctrl = controllerOf(ctx);
+		source = ctrl?.idSource ?? ctrl?.readable ?? ctrl?.table ?? null;
+	}
+	if (!isIdValidationSource(source)) throw noTableError(ctx);
 	const env = await ctx.get(dbActionBodySlot);
-	validate(env.ids, table);
+	validate(env.ids, source);
 	return env.ids;
 }
 const dbActionIdSlot = (0, _wooksjs_event_core.cached)((ctx) => resolveValidatedId(ctx, validateSingleId));