@atscript/moost-db 0.1.148 → 0.1.149

package/dist/index.cjs

@@ -71,6 +71,13 @@ function insightError(insights, message) {
 	const entry = insightPaths.get(insights);
 	return entry?.message === message ? badRequest(entry.path, message) : new _moostjs_event_http.HttpError(400, message);
 }
+/**
+* The 400 envelope of a `ValidatorError`; `undefined` for any other error.
+* @internal Not part of the public API (not re-exported from the barrel).
+*/
+function validatorErrorToHttp(error) {
+	return error instanceof _atscript_typescript_utils.ValidatorError ? errorEnvelope(400, error.message, error.errors) : void 0;
+}
 //#endregion
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = {
@@ -81,7 +88,8 @@ const dbErrorCodeToStatus = {
 	BUCKET_TZ_UNAVAILABLE: 501
 };
 function transformValidationError(error, reply) {
-	if (error instanceof _atscript_typescript_utils.ValidatorError) reply(errorEnvelope(400, error.message, error.errors));
+	const validation = validatorErrorToHttp(error);
+	if (validation) reply(validation);
 	else if (error instanceof _atscript_db.DbError) reply(errorEnvelope(dbErrorCodeToStatus[error.code] ?? 400, error.message, error.errors));
 }
 const validationErrorTransform = () => (0, moost.defineInterceptor)({ error: transformValidationError }, moost.TInterceptorPriority.BEFORE_ALL);
@@ -4192,6 +4200,17 @@ const PATH_OPS = [
 	"aggregate",
 	"bucket"
 ];
+/** The controller of the event that owns the route params (nearest ancestor that set them). */
+function routedController(ctx) {
+	for (let c = ctx; c; c = c.parent) {
+		try {
+			c.getOwn(_wooksjs_event_core.routeParamsKey);
+		} catch {
+			continue;
+		}
+		return controllerOf(c);
+	}
+}
 /** The 400 of a filter / sort on a `@db.writeOnly` field. */
 function writeOnlyError(path, op) {
 	const verdict = writeOnlyVerdict(path, op);
@@ -4467,7 +4486,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* (`$vector`) or a geo index (`/geo`, `$index`) reading a hidden path
 	* answers exactly like a nonexistent index (400); a hidden DEFAULT text
 	* index falls back to the `@db.column.searchable` substring search over
-	* visible fields (or ignores the term when there are none). A
+	* visible fields (or ignores the term when there are none — on list
+	* endpoints; query targets, delegated targets and {@link resolveQuery}
+	* answer 400 `TARGET_INVALID` instead). A
 	* `@db.column.derived` field is visible only while its source path is,
 	* and one whose source is hidden is sealed out of every read projection
 	* for the request, like a `@db.writeOnly` field. The same holds for a
@@ -5070,6 +5091,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* {@link checkCapabilities}, {@link hasField}), where the client
 	* predicates' {@link transformRelationFilter} also runs: a query target
 	* never filters on, nor counts by, a field the caller can't read.
+	* {@link resolveQuery} does not call it (there is no action of this
+	* controller to scope).
 	*
 	* @since 0.1.147
 	*/
@@ -5406,18 +5429,76 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	async [RESOLVE_TARGET](req) {
 		const { action } = req;
 		const body = parseQueryTargetBody(action, req.query);
+		const { rows, filter, findMany, exclude, visibleOf, cap } = await this._resolveMatching({
+			label: action,
+			body,
+			cap: req.cap,
+			maxExclude: req.maxExclude,
+			overlay: req.overlay,
+			scopeByAction: true,
+			select: [...new Set(req.select)],
+			sortBy: req.select,
+			excludeShapes: req.excludeShapes,
+			visibleOf: req.visibleOf
+		});
+		const byIds = (read, ids, scope, select) => findRowsByIds({ findMany: (q) => read({
+			...q,
+			controls: {
+				...q.controls,
+				$limit: Math.max(ids.length, cap + 1)
+			}
+		}) }, ids, scope, select);
+		const snapshotFields = new Set(req.select);
+		let first = true;
+		return {
+			matched: rows.length,
+			rows,
+			dryRun: body.dryRun === true,
+			exclude,
+			visibleOf,
+			load: (ids, select) => {
+				if (!first) return byIds(findMany, ids, filter, select);
+				first = false;
+				const fields = [...select];
+				if (!fields.every((f) => snapshotFields.has(f))) {
+					const plain = (q) => this.readable.findMany(q);
+					return byIds(plain, ids, void 0, fields);
+				}
+				return Promise.resolve(alignRowsToIds(rows, ids).map((row, i) => row ? projectRow$2(row, new Set([...fields, ...Object.keys(ids[i])])) : void 0));
+			}
+		};
+	}
+	/**
+	* The shared resolver behind query targets and {@link resolveQuery}: the
+	* query body validated, checked and run as a READ of this controller, then
+	* ONE read of `select` ordered by `sort` — `filter (+ $search) ∧ overlay ∧
+	* scope ∧ ¬exclude`, at most `cap + 1` rows. More than `cap` → 400
+	* `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+	* `TARGET_CHANGED`.
+	*
+	* Everything that depends on the read's visibility — the `$search`
+	* fallback, the native-search memo, the un-appliable-term refusal and the
+	* delegated identity — is computed INSIDE the read child, where the
+	* permission layer's per-request state is the read's.
+	*/
+	async _resolveMatching(spec) {
+		const { label, body } = spec;
+		const cap = Math.min(spec.cap, body.maxRows ?? Infinity);
 		const parsed = this.parseUrlOr400(body.q.startsWith("?") ? body.q.slice(1) : body.q);
 		const controls = {};
 		for (const [k, v] of Object.entries(parsed.controls ?? {})) {
 			if (v === void 0) continue;
-			if (k !== "$search" && k !== "$index") throw targetInvalid(action, `A query target takes a filter, $search and $index only — "${k}" is not accepted`);
-			if (k === "$search" && typeof v !== "string" && typeof v !== "number") throw targetInvalid(action, "$search must be a search term");
+			if (k !== "$search" && k !== "$index") throw targetInvalid(label, `A query target takes a filter, $search and $index only — "${k}" is not accepted`);
+			if (k === "$search" && typeof v !== "string" && typeof v !== "number") throw targetInvalid(label, "$search must be a search term");
 			controls[k] = k === "$search" ? `${v}` : v;
 		}
-		if (controls.$index !== void 0 && typeof controls.$index !== "string") throw targetInvalid(action, "$index must be an index name");
+		if (controls.$index !== void 0 && typeof controls.$index !== "string") throw targetInvalid(label, "$index must be an index name");
 		const exclude = body.exclude ?? [];
-		const shapes = req.excludeShapes ?? [];
+		const shapes = spec.excludeShapes ?? [];
+		const sealedSet = () => new Set([...this.fieldVisibility.sealedFor(this.readable), ...this._leavesOf(this.readable).filter((leaf) => !this.fieldVisibility.isVisible(leaf))]);
 		const check = () => {
+			let sealed;
+			const readableLeaf = (leaf) => !(sealed ??= sealedSet()).has(leaf);
 			const controlsError = this.validateControls(controls, "query");
 			if (controlsError) throw new _moostjs_event_http.HttpError(400, controlsError);
 			const gateError = this.checkCapabilities({
@@ -5425,71 +5506,160 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				controls
 			});
 			if (gateError) throw gateError;
-			if (exclude.length > 0) validateMultiId(exclude, shapes.length === 0 ? this.idSource : {
-				identifications: [...this.idSource.identifications, ...shapes.map((fields) => ({
-					fields,
-					source: "target"
-				}))],
-				fieldDescriptors: this.readable.fieldDescriptors
-			}, req.maxExclude);
+			if (exclude.length > 0) {
+				const source = shapes.length === 0 ? this.idSource : {
+					identifications: [...this.idSource.identifications, ...shapes.map((fields) => ({
+						fields,
+						source: "target"
+					}))],
+					fieldDescriptors: this.readable.fieldDescriptors
+				};
+				try {
+					validateMultiId(exclude, source, spec.maxExclude);
+				} catch (error) {
+					throw validatorErrorToHttp(error) ?? error;
+				}
+			}
+			const nav = FieldCapabilityIndex.navPathsOf(this.readable);
+			for (const path of spec.selectGate ?? []) {
+				if (this.capabilities.decorationCap(path) || (0, _atscript_db.selfOrAncestor)(path, nav) !== void 0) throw badRequest(path, `Unknown field "${path}"`);
+				const verdict = this.capabilities.check(path, "select", this.fieldVisibility.isVisible);
+				if (verdict) throw badRequest(verdict.path, verdict.message);
+				if (this._writeOnlySet.has(path)) throw badRequest(path, `Field "${path}" is @db.writeOnly`);
+				const prefix = `${path}.`;
+				const leaves = this._leavesOf(this.readable).filter((leaf) => leaf.startsWith(prefix));
+				if (leaves.length > 0 && !leaves.some((leaf) => readableLeaf(leaf))) throw badRequest(path, `Unknown field "${path}"`);
+			}
+			for (const path of spec.sortGate ?? []) {
+				const verdict = this.capabilities.check(path, "sort", this.fieldVisibility.isVisible);
+				if (verdict) throw targetInvalid(label, verdict.message);
+			}
 		};
-		const ownScope = req.overlay === "action" || this.queryTargetScope !== _AsDbReadableController.prototype.queryTargetScope;
-		const [[base, scope], overlay] = await Promise.all([this._asRead(controls, parsed.filter, async () => {
+		const ownScope = spec.scopeByAction === true && (spec.overlay === "action" || this.queryTargetScope !== _AsDbReadableController.prototype.queryTargetScope);
+		const [read, overlay] = await Promise.all([this._asRead(controls, parsed.filter, async () => {
 			check();
-			const [clientFilter, readScope] = await Promise.all([this._relationOverlay(parsed), ownScope ? this.queryTargetScope(action) : void 0]);
-			return [req.overlay === "read" ? await this.transformFilter(clientFilter ?? {}) : clientFilter, readScope];
-		}), req.overlay === "action" ? this.rowOverlay() : void 0]);
-		const filter = (0, _atscript_db.andFilters)(this.applySearchFallback(base, controls), overlay, scope, exclude.length > 0 ? { $not: { $or: exclude } } : void 0);
-		const strategy = await this._resolveReadStrategy(controls);
+			const [clientFilter, readScope, strategy] = await Promise.all([
+				this._relationOverlay(parsed),
+				ownScope ? this.queryTargetScope(label) : void 0,
+				this._resolveReadStrategy(controls)
+			]);
+			const base = spec.overlay === "action" ? clientFilter : await this.transformFilter(clientFilter ?? {});
+			const searched = this.applySearchFallback(base, controls);
+			if (controls.$search && strategy.kind !== "search" && searched === base) throw targetInvalid(label, "$search is not available here");
+			const visibleOf = spec.visibleOf?.filter((f) => this.fieldVisibility.isVisible(f));
+			let select = spec.select;
+			if (spec.selectGate) {
+				const sealed = sealedSet();
+				for (const id of spec.identity ?? []) sealed.delete(id);
+				select = this._sealSelect([...spec.select], sealed, this.readable);
+			}
+			return {
+				searched,
+				readScope,
+				strategy,
+				visibleOf,
+				select
+			};
+		}, spec.routeParams), spec.overlay === "action" ? this.rowOverlay() : void 0]);
+		const { strategy } = read;
+		const filter = (0, _atscript_db.andFilters)(read.searched, overlay, read.readScope, spec.scope, exclude.length > 0 ? { $not: { $or: exclude } } : void 0);
 		const findMany = (q) => strategy.kind === "search" ? this.readable.search(strategy.term, q, strategy.index) : this.readable.findMany(q);
-		const cap = Math.min(req.cap, body.maxRows ?? Infinity);
-		const sort = {};
-		for (const f of req.select) sort[f] = 1;
 		const rows = await findMany({
 			filter,
 			controls: {
-				$select: [...new Set(req.select)],
-				$sort: sort,
+				$select: [...read.select],
+				$sort: Object.fromEntries(spec.sortBy.map((f) => [f, 1])),
 				$limit: cap + 1
 			}
 		});
-		if (rows.length > cap) throw new ActionTargetError("TARGET_TOO_LARGE", action, `The query matches more than ${cap} rows`, { cap });
-		if (body.expectCount !== void 0 && body.expectCount !== rows.length) throw new ActionTargetError("TARGET_CHANGED", action, `The query now matches ${rows.length} rows (expected ${body.expectCount})`, { matched: rows.length });
-		const byIds = (read, ids, scope, select) => findRowsByIds({ findMany: (q) => read({
-			...q,
-			controls: {
-				...q.controls,
-				$limit: Math.max(ids.length, cap + 1)
-			}
-		}) }, ids, scope, select);
-		const snapshotFields = new Set(req.select);
-		let first = true;
+		if (rows.length > cap) throw new ActionTargetError("TARGET_TOO_LARGE", label, `The query matches more than ${cap} rows`, { cap });
+		if (body.expectCount !== void 0 && body.expectCount !== rows.length) throw new ActionTargetError("TARGET_CHANGED", label, `The query now matches ${rows.length} rows (expected ${body.expectCount})`, { matched: rows.length });
 		return {
-			matched: rows.length,
 			rows,
-			dryRun: body.dryRun === true,
+			filter,
+			findMany,
 			exclude,
-			load: (ids, select) => {
-				if (!first) return byIds(findMany, ids, filter, select);
-				first = false;
-				const fields = [...select];
-				if (!fields.every((f) => snapshotFields.has(f))) {
-					const plain = (q) => this.readable.findMany(q);
-					return byIds(plain, ids, void 0, fields);
-				}
-				return Promise.resolve(alignRowsToIds(rows, ids).map((row, i) => row ? projectRow$2(row, new Set([...fields, ...Object.keys(ids[i])])) : void 0));
-			}
+			visibleOf: read.visibleOf,
+			cap,
+			select: read.select
 		};
 	}
 	/**
+	* Rows of THIS controller matching `q`, resolved as a READ of it for the
+	* current event's caller (since 0.1.149) — from your own command, e.g. to
+	* act on "every issue matching this search". `q` is a `GET /query` string
+	* (`$search` / `$index` and a filter only) or a query-target envelope
+	* `{ q, exclude?, expectCount?, maxRows? }` (no `dryRun`).
+	*
+	* The read runs under this controller's full read policy
+	* ({@link prepareRequest} with `endpoint: "query"`, {@link hasField},
+	* {@link validateControls}, the capability / index gate and the
+	* {@link transformFilter} overlay) with the current event's identity.
+	* Route interceptors and guards of the `query` route do not run; read
+	* authorization belongs in {@link prepareRequest}. {@link queryTargetScope}
+	* is not called. Hooks see no route params of the caller (only a call from
+	* the routed event's own controller instance keeps its params); pass route-derived
+	* restrictions as `opts.scope`. Joins the caller's open transaction.
+	*
+	* Rows are ordered by identity (`preferredId`, else the primary key) and
+	* carry the identity fields plus `opts.select` (gated like `/query`
+	* `$select`; `transformProjection` is not applied — hide fields with
+	* {@link hasField}; decoration keys and navigation paths are refused). An
+	* identity-less readable is ordered by `select` (each path sortable, else
+	* `TARGET_INVALID`). More than `opts.cap` (default 1000) rows → 400
+	* `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+	* `TARGET_CHANGED`; a `$search` that can't be applied → 400
+	* `TARGET_INVALID`. Must be awaited inside a running event handler.
+	*/
+	async resolveQuery(q, opts = {}) {
+		let caller;
+		try {
+			caller = (0, _wooksjs_event_core.current)();
+		} catch {
+			throw new Error("[moost-db] resolveQuery must be awaited inside an event handler");
+		}
+		const cap = opts.cap ?? 1e3;
+		if (!Number.isInteger(cap) || cap < 1) throw new Error("[moost-db] resolveQuery: `cap` must be a positive integer");
+		const select = opts.select ?? [];
+		if (!Array.isArray(select) || select.some((p) => typeof p !== "string")) throw new Error("[moost-db] resolveQuery: `select` must be an array of field paths");
+		const ids = this.readable.preferredId?.length ? this.readable.preferredId : this.readable.primaryKeys;
+		const order = ids.length > 0 ? ids : select;
+		if (order.length === 0) throw new Error("[moost-db] resolveQuery: this readable has no identity — pass `select` (rows are ordered by it)");
+		const label = readCurrentActionMeta(caller)?.name ?? "";
+		const body = parseQueryTargetBody(label, typeof q === "string" ? { q } : q);
+		if (body.dryRun !== void 0) throw targetInvalid(label, "resolveQuery takes no `dryRun` — read `query.dryRun` yourself");
+		let sameRoute = false;
+		try {
+			sameRoute = controllerOf(caller) === this && routedController(caller) === this;
+		} catch {}
+		const fields = [...new Set([...ids, ...select])];
+		const { rows, select: sealedSelect } = await this._resolveMatching({
+			label,
+			body,
+			cap,
+			maxExclude: DEFAULT_MAX_ACTION_IDS,
+			overlay: "read",
+			scope: opts.scope,
+			select: fields,
+			sortBy: order,
+			selectGate: select,
+			identity: ids,
+			sortGate: ids.length > 0 ? void 0 : order,
+			routeParams: sameRoute ? void 0 : {}
+		});
+		return rows.map((row) => projectRow$2(row, sealedSelect));
+	}
+	/**
 	* Runs `fn` as a READ of this controller (since 0.1.147): in a child of
 	* the current event whose controller context is this controller's `query`
 	* handler, after `prepareRequest({ endpoint: "query", controls, filter })` — the
 	* request-scoped state a permission layer builds there (read grant, field
-	* visibility) is the read's and stays in the child.
+	* visibility) is the read's and stays in the child. `routeParams` (since
+	* 0.1.149) replaces the route params the child's hooks read.
 	*/
-	_asRead(controls, filter, fn) {
+	_asRead(controls, filter, fn, routeParams) {
 		return runAsController(this, "query", async () => {
+			if (routeParams) (0, _wooksjs_event_core.current)().set(_wooksjs_event_core.routeParamsKey, routeParams);
 			if (typeof this.prepareRequest === "function") await this.prepareRequest(readRequestContext("query", controls, filter));
 			return fn();
 		});
@@ -5573,7 +5743,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* with the existing filter. Applies only when native search does not serve
 	* the request (no native search, or — since 0.1.143 — its default index
 	* reads a field {@link hasField} hides) and the request isn't a vector
-	* search (`$vector` consumes the term).
+	* search (`$vector` consumes the term). Lenient on list endpoints: a term
+	* nothing can apply is ignored. Resolvers (query targets, `resolveQuery`)
+	* refuse it — a subclass override that applies the term must return a new
+	* filter object.
 	*/
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
@@ -6363,7 +6536,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			maxExclude: limits.maxIds,
 			overlay: "read",
 			select: [...new Set([...identity, ...delegation.paths])],
-			excludeShapes: [delegation.paths]
+			excludeShapes: [delegation.paths],
+			visibleOf: identity
 		});
 		if (resolved.dryRun) return { matched: resolved.matched };
 		const summary = {
@@ -6373,7 +6547,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			failed: []
 		};
 		const { ids, index } = mapToSourceIds(resolved.rows, delegation.idMap);
-		const visibleIdentity = identity.filter((f) => this.fieldVisibility.isVisible(f));
+		const visibleIdentity = resolved.visibleOf ?? [];
 		for (let i = 0; i < index.length; i++) {
 			if (index[i] >= 0) continue;
 			const row = resolved.rows[i];

package/dist/index.d.cts

@@ -385,6 +385,12 @@ type TDbQueryTargetOpts = boolean | {
  * registered symbol, like `ACTION_OVERLAY`).
  */
 declare const RESOLVE_TARGET: unique symbol;
+/**
+ * `q` of {@link AsDbReadableController.resolveQuery}: a `GET /query` string, or a
+ * query-target envelope without `dryRun`.
+ * @since 0.1.149
+ */
+type TDbResolveQueryInput = string | Omit<TDbActionQueryTarget, "dryRun">;
 /** What {@link RESOLVE_TARGET} resolves. */
 interface TTargetRequest {
   action: string;
@@ -400,6 +406,8 @@ interface TTargetRequest {
    * rows); `"read"` — `transformFilter` (a view resolving rows it delegates).
    */
   overlay: "action" | "read";
+  /** Identity fields to report the READ-visible subset of ({@link TResolvedTarget.visibleOf}). */
+  visibleOf?: readonly string[];
   /** Fields of the phase-1 read (sorted by the first identification's fields). */
   select: readonly string[];
   /** Key sets `exclude` entries may use besides the controller's identifications. */
@@ -414,6 +422,8 @@ interface TResolvedTarget {
   dryRun: boolean;
   /** The validated `exclude` entries (already applied to {@link rows}). */
   exclude: Record<string, unknown>[];
+  /** {@link TTargetRequest.visibleOf} filtered by the read's field visibility. */
+  visibleOf?: readonly string[];
   /**
    * The rows `ids` address that STILL match the target (filter, search,
    * overlay, `queryTargetScope`, `exclude`), aligned with `ids`; `select`
@@ -940,6 +950,15 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
+/** Options of {@link AsDbReadableController.resolveQuery}. @since 0.1.149 */
+interface TDbResolveQueryOpts<K extends string = string> {
+  /** Fields to return besides the identity. Gated like `/query` `$select` under `hasField`. */
+  select?: readonly K[];
+  /** Most rows (default 1000); `q.maxRows` can only lower it. */
+  cap?: number;
+  /** Server-side restriction, ANDed in. Trusted: not gated, not shown to `prepareRequest`. */
+  scope?: FilterExpr;
+}
 /** Read endpoint a {@link AsDbReadableController.decorateRows} call serves. */
 type TDbDecorateEndpoint = "query" | "pages" | "geo" | "one";
 /**
@@ -1168,7 +1187,9 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * (`$vector`) or a geo index (`/geo`, `$index`) reading a hidden path
    * answers exactly like a nonexistent index (400); a hidden DEFAULT text
    * index falls back to the `@db.column.searchable` substring search over
-   * visible fields (or ignores the term when there are none). A
+   * visible fields (or ignores the term when there are none — on list
+   * endpoints; query targets, delegated targets and {@link resolveQuery}
+   * answer 400 `TARGET_INVALID` instead). A
    * `@db.column.derived` field is visible only while its source path is,
    * and one whose source is hidden is sealed out of every read projection
    * for the request, like a `@db.writeOnly` field. The same holds for a
@@ -1451,6 +1472,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * {@link checkCapabilities}, {@link hasField}), where the client
    * predicates' {@link transformRelationFilter} also runs: a query target
    * never filters on, nor counts by, a field the caller can't read.
+   * {@link resolveQuery} does not call it (there is no action of this
+   * controller to scope).
    *
    * @since 0.1.147
    */
@@ -1567,12 +1590,55 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * the first batch, which directly follows the snapshot.
    */
   [RESOLVE_TARGET](req: TTargetRequest): Promise<TResolvedTarget>;
+  /**
+   * The shared resolver behind query targets and {@link resolveQuery}: the
+   * query body validated, checked and run as a READ of this controller, then
+   * ONE read of `select` ordered by `sort` — `filter (+ $search) ∧ overlay ∧
+   * scope ∧ ¬exclude`, at most `cap + 1` rows. More than `cap` → 400
+   * `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+   * `TARGET_CHANGED`.
+   *
+   * Everything that depends on the read's visibility — the `$search`
+   * fallback, the native-search memo, the un-appliable-term refusal and the
+   * delegated identity — is computed INSIDE the read child, where the
+   * permission layer's per-request state is the read's.
+   */
+  private _resolveMatching;
+  /**
+   * Rows of THIS controller matching `q`, resolved as a READ of it for the
+   * current event's caller (since 0.1.149) — from your own command, e.g. to
+   * act on "every issue matching this search". `q` is a `GET /query` string
+   * (`$search` / `$index` and a filter only) or a query-target envelope
+   * `{ q, exclude?, expectCount?, maxRows? }` (no `dryRun`).
+   *
+   * The read runs under this controller's full read policy
+   * ({@link prepareRequest} with `endpoint: "query"`, {@link hasField},
+   * {@link validateControls}, the capability / index gate and the
+   * {@link transformFilter} overlay) with the current event's identity.
+   * Route interceptors and guards of the `query` route do not run; read
+   * authorization belongs in {@link prepareRequest}. {@link queryTargetScope}
+   * is not called. Hooks see no route params of the caller (only a call from
+   * the routed event's own controller instance keeps its params); pass route-derived
+   * restrictions as `opts.scope`. Joins the caller's open transaction.
+   *
+   * Rows are ordered by identity (`preferredId`, else the primary key) and
+   * carry the identity fields plus `opts.select` (gated like `/query`
+   * `$select`; `transformProjection` is not applied — hide fields with
+   * {@link hasField}; decoration keys and navigation paths are refused). An
+   * identity-less readable is ordered by `select` (each path sortable, else
+   * `TARGET_INVALID`). More than `opts.cap` (default 1000) rows → 400
+   * `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+   * `TARGET_CHANGED`; a `$search` that can't be applied → 400
+   * `TARGET_INVALID`. Must be awaited inside a running event handler.
+   */
+  resolveQuery<K extends string = never>(q: TDbResolveQueryInput, opts?: TDbResolveQueryOpts<K>): Promise<Array<Pick<DataType, K & keyof DataType> & Record<string, unknown>>>;
   /**
    * Runs `fn` as a READ of this controller (since 0.1.147): in a child of
    * the current event whose controller context is this controller's `query`
    * handler, after `prepareRequest({ endpoint: "query", controls, filter })` — the
    * request-scoped state a permission layer builds there (read grant, field
-   * visibility) is the read's and stays in the child.
+   * visibility) is the read's and stays in the child. `routeParams` (since
+   * 0.1.149) replaces the route params the child's hooks read.
    */
   private _asRead;
   /**
@@ -1598,7 +1664,10 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * with the existing filter. Applies only when native search does not serve
    * the request (no native search, or — since 0.1.143 — its default index
    * reads a field {@link hasField} hides) and the request isn't a vector
-   * search (`$vector` consumes the term).
+   * search (`$vector` consumes the term). Lenient on list endpoints: a term
+   * nothing can apply is ignored. Resolvers (query targets, `resolveQuery`)
+   * refuse it — a subclass override that applies the term must return a new
+   * filter object.
    */
   protected applySearchFallback(filter: FilterExpr | undefined, controls: Record<string, unknown>): FilterExpr | undefined;
   /**
@@ -3419,4 +3488,4 @@ declare const REL_FILTER_CLIENT_MAX_DEPTH = 3;
  */
 declare const REL_FILTER_CLIENT_MAX_NODES = 8;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, type TDbDecorationsOpts, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbRowIdInput, type TDbRowIdPurpose, type TDbRowIdsContext, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type TGateOp, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, type TDbDecorationsOpts, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbResolveQueryInput, TDbResolveQueryOpts, type TDbRowIdInput, type TDbRowIdPurpose, type TDbRowIdsContext, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type TGateOp, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };

package/dist/index.d.mts

@@ -385,6 +385,12 @@ type TDbQueryTargetOpts = boolean | {
  * registered symbol, like `ACTION_OVERLAY`).
  */
 declare const RESOLVE_TARGET: unique symbol;
+/**
+ * `q` of {@link AsDbReadableController.resolveQuery}: a `GET /query` string, or a
+ * query-target envelope without `dryRun`.
+ * @since 0.1.149
+ */
+type TDbResolveQueryInput = string | Omit<TDbActionQueryTarget, "dryRun">;
 /** What {@link RESOLVE_TARGET} resolves. */
 interface TTargetRequest {
   action: string;
@@ -400,6 +406,8 @@ interface TTargetRequest {
    * rows); `"read"` — `transformFilter` (a view resolving rows it delegates).
    */
   overlay: "action" | "read";
+  /** Identity fields to report the READ-visible subset of ({@link TResolvedTarget.visibleOf}). */
+  visibleOf?: readonly string[];
   /** Fields of the phase-1 read (sorted by the first identification's fields). */
   select: readonly string[];
   /** Key sets `exclude` entries may use besides the controller's identifications. */
@@ -414,6 +422,8 @@ interface TResolvedTarget {
   dryRun: boolean;
   /** The validated `exclude` entries (already applied to {@link rows}). */
   exclude: Record<string, unknown>[];
+  /** {@link TTargetRequest.visibleOf} filtered by the read's field visibility. */
+  visibleOf?: readonly string[];
   /**
    * The rows `ids` address that STILL match the target (filter, search,
    * overlay, `queryTargetScope`, `exclude`), aligned with `ids`; `select`
@@ -940,6 +950,15 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
+/** Options of {@link AsDbReadableController.resolveQuery}. @since 0.1.149 */
+interface TDbResolveQueryOpts<K extends string = string> {
+  /** Fields to return besides the identity. Gated like `/query` `$select` under `hasField`. */
+  select?: readonly K[];
+  /** Most rows (default 1000); `q.maxRows` can only lower it. */
+  cap?: number;
+  /** Server-side restriction, ANDed in. Trusted: not gated, not shown to `prepareRequest`. */
+  scope?: FilterExpr;
+}
 /** Read endpoint a {@link AsDbReadableController.decorateRows} call serves. */
 type TDbDecorateEndpoint = "query" | "pages" | "geo" | "one";
 /**
@@ -1168,7 +1187,9 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * (`$vector`) or a geo index (`/geo`, `$index`) reading a hidden path
    * answers exactly like a nonexistent index (400); a hidden DEFAULT text
    * index falls back to the `@db.column.searchable` substring search over
-   * visible fields (or ignores the term when there are none). A
+   * visible fields (or ignores the term when there are none — on list
+   * endpoints; query targets, delegated targets and {@link resolveQuery}
+   * answer 400 `TARGET_INVALID` instead). A
    * `@db.column.derived` field is visible only while its source path is,
    * and one whose source is hidden is sealed out of every read projection
    * for the request, like a `@db.writeOnly` field. The same holds for a
@@ -1451,6 +1472,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * {@link checkCapabilities}, {@link hasField}), where the client
    * predicates' {@link transformRelationFilter} also runs: a query target
    * never filters on, nor counts by, a field the caller can't read.
+   * {@link resolveQuery} does not call it (there is no action of this
+   * controller to scope).
    *
    * @since 0.1.147
    */
@@ -1567,12 +1590,55 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * the first batch, which directly follows the snapshot.
    */
   [RESOLVE_TARGET](req: TTargetRequest): Promise<TResolvedTarget>;
+  /**
+   * The shared resolver behind query targets and {@link resolveQuery}: the
+   * query body validated, checked and run as a READ of this controller, then
+   * ONE read of `select` ordered by `sort` — `filter (+ $search) ∧ overlay ∧
+   * scope ∧ ¬exclude`, at most `cap + 1` rows. More than `cap` → 400
+   * `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+   * `TARGET_CHANGED`.
+   *
+   * Everything that depends on the read's visibility — the `$search`
+   * fallback, the native-search memo, the un-appliable-term refusal and the
+   * delegated identity — is computed INSIDE the read child, where the
+   * permission layer's per-request state is the read's.
+   */
+  private _resolveMatching;
+  /**
+   * Rows of THIS controller matching `q`, resolved as a READ of it for the
+   * current event's caller (since 0.1.149) — from your own command, e.g. to
+   * act on "every issue matching this search". `q` is a `GET /query` string
+   * (`$search` / `$index` and a filter only) or a query-target envelope
+   * `{ q, exclude?, expectCount?, maxRows? }` (no `dryRun`).
+   *
+   * The read runs under this controller's full read policy
+   * ({@link prepareRequest} with `endpoint: "query"`, {@link hasField},
+   * {@link validateControls}, the capability / index gate and the
+   * {@link transformFilter} overlay) with the current event's identity.
+   * Route interceptors and guards of the `query` route do not run; read
+   * authorization belongs in {@link prepareRequest}. {@link queryTargetScope}
+   * is not called. Hooks see no route params of the caller (only a call from
+   * the routed event's own controller instance keeps its params); pass route-derived
+   * restrictions as `opts.scope`. Joins the caller's open transaction.
+   *
+   * Rows are ordered by identity (`preferredId`, else the primary key) and
+   * carry the identity fields plus `opts.select` (gated like `/query`
+   * `$select`; `transformProjection` is not applied — hide fields with
+   * {@link hasField}; decoration keys and navigation paths are refused). An
+   * identity-less readable is ordered by `select` (each path sortable, else
+   * `TARGET_INVALID`). More than `opts.cap` (default 1000) rows → 400
+   * `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+   * `TARGET_CHANGED`; a `$search` that can't be applied → 400
+   * `TARGET_INVALID`. Must be awaited inside a running event handler.
+   */
+  resolveQuery<K extends string = never>(q: TDbResolveQueryInput, opts?: TDbResolveQueryOpts<K>): Promise<Array<Pick<DataType, K & keyof DataType> & Record<string, unknown>>>;
   /**
    * Runs `fn` as a READ of this controller (since 0.1.147): in a child of
    * the current event whose controller context is this controller's `query`
    * handler, after `prepareRequest({ endpoint: "query", controls, filter })` — the
    * request-scoped state a permission layer builds there (read grant, field
-   * visibility) is the read's and stays in the child.
+   * visibility) is the read's and stays in the child. `routeParams` (since
+   * 0.1.149) replaces the route params the child's hooks read.
    */
   private _asRead;
   /**
@@ -1598,7 +1664,10 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * with the existing filter. Applies only when native search does not serve
    * the request (no native search, or — since 0.1.143 — its default index
    * reads a field {@link hasField} hides) and the request isn't a vector
-   * search (`$vector` consumes the term).
+   * search (`$vector` consumes the term). Lenient on list endpoints: a term
+   * nothing can apply is ignored. Resolvers (query targets, `resolveQuery`)
+   * refuse it — a subclass override that applies the term must return a new
+   * filter object.
    */
   protected applySearchFallback(filter: FilterExpr | undefined, controls: Record<string, unknown>): FilterExpr | undefined;
   /**
@@ -3419,4 +3488,4 @@ declare const REL_FILTER_CLIENT_MAX_DEPTH = 3;
  */
 declare const REL_FILTER_CLIENT_MAX_NODES = 8;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, type TDbDecorationsOpts, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbRowIdInput, type TDbRowIdPurpose, type TDbRowIdsContext, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type TGateOp, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, type TDbDecorationsOpts, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbResolveQueryInput, TDbResolveQueryOpts, type TDbRowIdInput, type TDbRowIdPurpose, type TDbRowIdsContext, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type TGateOp, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { Body, Delete, Get, HttpError, MoostHttp, Patch, Post, Put, Query, Url }
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Pipe, Provide, Resolve, TInterceptorPriority, TPipePriority, defineBeforeInterceptor, defineInterceptor, definePipeFn, getMoostMate, useControllerContext, withControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
 import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, aliasTargetOf, andFilters, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, containsRelationFilter, findAncestorInSet, geoIndexNotFoundMessage, groupSourceVerdict, hasRelationOp, isEmptyObject, isJsonValueField, isPlainObject, isRelationOp, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, searchIndexNotFoundMessage, selfOrAncestor, unsupportedOperatorMessage, vectorIndexNotFoundMessage } from "@atscript/db";
-import { cached, current, defineWook, key, useRouteParams } from "@wooksjs/event-core";
+import { cached, current, defineWook, key, routeParamsKey, useRouteParams } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
 import { BUCKET_UNITS } from "@uniqu/core";
 import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
@@ -70,6 +70,13 @@ function insightError(insights, message) {
 	const entry = insightPaths.get(insights);
 	return entry?.message === message ? badRequest(entry.path, message) : new HttpError(400, message);
 }
+/**
+* The 400 envelope of a `ValidatorError`; `undefined` for any other error.
+* @internal Not part of the public API (not re-exported from the barrel).
+*/
+function validatorErrorToHttp(error) {
+	return error instanceof ValidatorError ? errorEnvelope(400, error.message, error.errors) : void 0;
+}
 //#endregion
 //#region src/validation-interceptor.ts
 const dbErrorCodeToStatus = {
@@ -80,7 +87,8 @@ const dbErrorCodeToStatus = {
 	BUCKET_TZ_UNAVAILABLE: 501
 };
 function transformValidationError(error, reply) {
-	if (error instanceof ValidatorError) reply(errorEnvelope(400, error.message, error.errors));
+	const validation = validatorErrorToHttp(error);
+	if (validation) reply(validation);
 	else if (error instanceof DbError) reply(errorEnvelope(dbErrorCodeToStatus[error.code] ?? 400, error.message, error.errors));
 }
 const validationErrorTransform = () => defineInterceptor({ error: transformValidationError }, TInterceptorPriority.BEFORE_ALL);
@@ -4189,6 +4197,17 @@ const PATH_OPS = [
 	"aggregate",
 	"bucket"
 ];
+/** The controller of the event that owns the route params (nearest ancestor that set them). */
+function routedController(ctx) {
+	for (let c = ctx; c; c = c.parent) {
+		try {
+			c.getOwn(routeParamsKey);
+		} catch {
+			continue;
+		}
+		return controllerOf(c);
+	}
+}
 /** The 400 of a filter / sort on a `@db.writeOnly` field. */
 function writeOnlyError(path, op) {
 	const verdict = writeOnlyVerdict(path, op);
@@ -4464,7 +4483,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* (`$vector`) or a geo index (`/geo`, `$index`) reading a hidden path
 	* answers exactly like a nonexistent index (400); a hidden DEFAULT text
 	* index falls back to the `@db.column.searchable` substring search over
-	* visible fields (or ignores the term when there are none). A
+	* visible fields (or ignores the term when there are none — on list
+	* endpoints; query targets, delegated targets and {@link resolveQuery}
+	* answer 400 `TARGET_INVALID` instead). A
 	* `@db.column.derived` field is visible only while its source path is,
 	* and one whose source is hidden is sealed out of every read projection
 	* for the request, like a `@db.writeOnly` field. The same holds for a
@@ -5067,6 +5088,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* {@link checkCapabilities}, {@link hasField}), where the client
 	* predicates' {@link transformRelationFilter} also runs: a query target
 	* never filters on, nor counts by, a field the caller can't read.
+	* {@link resolveQuery} does not call it (there is no action of this
+	* controller to scope).
 	*
 	* @since 0.1.147
 	*/
@@ -5403,18 +5426,76 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	async [RESOLVE_TARGET](req) {
 		const { action } = req;
 		const body = parseQueryTargetBody(action, req.query);
+		const { rows, filter, findMany, exclude, visibleOf, cap } = await this._resolveMatching({
+			label: action,
+			body,
+			cap: req.cap,
+			maxExclude: req.maxExclude,
+			overlay: req.overlay,
+			scopeByAction: true,
+			select: [...new Set(req.select)],
+			sortBy: req.select,
+			excludeShapes: req.excludeShapes,
+			visibleOf: req.visibleOf
+		});
+		const byIds = (read, ids, scope, select) => findRowsByIds({ findMany: (q) => read({
+			...q,
+			controls: {
+				...q.controls,
+				$limit: Math.max(ids.length, cap + 1)
+			}
+		}) }, ids, scope, select);
+		const snapshotFields = new Set(req.select);
+		let first = true;
+		return {
+			matched: rows.length,
+			rows,
+			dryRun: body.dryRun === true,
+			exclude,
+			visibleOf,
+			load: (ids, select) => {
+				if (!first) return byIds(findMany, ids, filter, select);
+				first = false;
+				const fields = [...select];
+				if (!fields.every((f) => snapshotFields.has(f))) {
+					const plain = (q) => this.readable.findMany(q);
+					return byIds(plain, ids, void 0, fields);
+				}
+				return Promise.resolve(alignRowsToIds(rows, ids).map((row, i) => row ? projectRow$1(row, new Set([...fields, ...Object.keys(ids[i])])) : void 0));
+			}
+		};
+	}
+	/**
+	* The shared resolver behind query targets and {@link resolveQuery}: the
+	* query body validated, checked and run as a READ of this controller, then
+	* ONE read of `select` ordered by `sort` — `filter (+ $search) ∧ overlay ∧
+	* scope ∧ ¬exclude`, at most `cap + 1` rows. More than `cap` → 400
+	* `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+	* `TARGET_CHANGED`.
+	*
+	* Everything that depends on the read's visibility — the `$search`
+	* fallback, the native-search memo, the un-appliable-term refusal and the
+	* delegated identity — is computed INSIDE the read child, where the
+	* permission layer's per-request state is the read's.
+	*/
+	async _resolveMatching(spec) {
+		const { label, body } = spec;
+		const cap = Math.min(spec.cap, body.maxRows ?? Infinity);
 		const parsed = this.parseUrlOr400(body.q.startsWith("?") ? body.q.slice(1) : body.q);
 		const controls = {};
 		for (const [k, v] of Object.entries(parsed.controls ?? {})) {
 			if (v === void 0) continue;
-			if (k !== "$search" && k !== "$index") throw targetInvalid(action, `A query target takes a filter, $search and $index only — "${k}" is not accepted`);
-			if (k === "$search" && typeof v !== "string" && typeof v !== "number") throw targetInvalid(action, "$search must be a search term");
+			if (k !== "$search" && k !== "$index") throw targetInvalid(label, `A query target takes a filter, $search and $index only — "${k}" is not accepted`);
+			if (k === "$search" && typeof v !== "string" && typeof v !== "number") throw targetInvalid(label, "$search must be a search term");
 			controls[k] = k === "$search" ? `${v}` : v;
 		}
-		if (controls.$index !== void 0 && typeof controls.$index !== "string") throw targetInvalid(action, "$index must be an index name");
+		if (controls.$index !== void 0 && typeof controls.$index !== "string") throw targetInvalid(label, "$index must be an index name");
 		const exclude = body.exclude ?? [];
-		const shapes = req.excludeShapes ?? [];
+		const shapes = spec.excludeShapes ?? [];
+		const sealedSet = () => new Set([...this.fieldVisibility.sealedFor(this.readable), ...this._leavesOf(this.readable).filter((leaf) => !this.fieldVisibility.isVisible(leaf))]);
 		const check = () => {
+			let sealed;
+			const readableLeaf = (leaf) => !(sealed ??= sealedSet()).has(leaf);
 			const controlsError = this.validateControls(controls, "query");
 			if (controlsError) throw new HttpError(400, controlsError);
 			const gateError = this.checkCapabilities({
@@ -5422,71 +5503,160 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				controls
 			});
 			if (gateError) throw gateError;
-			if (exclude.length > 0) validateMultiId(exclude, shapes.length === 0 ? this.idSource : {
-				identifications: [...this.idSource.identifications, ...shapes.map((fields) => ({
-					fields,
-					source: "target"
-				}))],
-				fieldDescriptors: this.readable.fieldDescriptors
-			}, req.maxExclude);
+			if (exclude.length > 0) {
+				const source = shapes.length === 0 ? this.idSource : {
+					identifications: [...this.idSource.identifications, ...shapes.map((fields) => ({
+						fields,
+						source: "target"
+					}))],
+					fieldDescriptors: this.readable.fieldDescriptors
+				};
+				try {
+					validateMultiId(exclude, source, spec.maxExclude);
+				} catch (error) {
+					throw validatorErrorToHttp(error) ?? error;
+				}
+			}
+			const nav = FieldCapabilityIndex.navPathsOf(this.readable);
+			for (const path of spec.selectGate ?? []) {
+				if (this.capabilities.decorationCap(path) || selfOrAncestor(path, nav) !== void 0) throw badRequest(path, `Unknown field "${path}"`);
+				const verdict = this.capabilities.check(path, "select", this.fieldVisibility.isVisible);
+				if (verdict) throw badRequest(verdict.path, verdict.message);
+				if (this._writeOnlySet.has(path)) throw badRequest(path, `Field "${path}" is @db.writeOnly`);
+				const prefix = `${path}.`;
+				const leaves = this._leavesOf(this.readable).filter((leaf) => leaf.startsWith(prefix));
+				if (leaves.length > 0 && !leaves.some((leaf) => readableLeaf(leaf))) throw badRequest(path, `Unknown field "${path}"`);
+			}
+			for (const path of spec.sortGate ?? []) {
+				const verdict = this.capabilities.check(path, "sort", this.fieldVisibility.isVisible);
+				if (verdict) throw targetInvalid(label, verdict.message);
+			}
 		};
-		const ownScope = req.overlay === "action" || this.queryTargetScope !== _AsDbReadableController.prototype.queryTargetScope;
-		const [[base, scope], overlay] = await Promise.all([this._asRead(controls, parsed.filter, async () => {
+		const ownScope = spec.scopeByAction === true && (spec.overlay === "action" || this.queryTargetScope !== _AsDbReadableController.prototype.queryTargetScope);
+		const [read, overlay] = await Promise.all([this._asRead(controls, parsed.filter, async () => {
 			check();
-			const [clientFilter, readScope] = await Promise.all([this._relationOverlay(parsed), ownScope ? this.queryTargetScope(action) : void 0]);
-			return [req.overlay === "read" ? await this.transformFilter(clientFilter ?? {}) : clientFilter, readScope];
-		}), req.overlay === "action" ? this.rowOverlay() : void 0]);
-		const filter = andFilters(this.applySearchFallback(base, controls), overlay, scope, exclude.length > 0 ? { $not: { $or: exclude } } : void 0);
-		const strategy = await this._resolveReadStrategy(controls);
+			const [clientFilter, readScope, strategy] = await Promise.all([
+				this._relationOverlay(parsed),
+				ownScope ? this.queryTargetScope(label) : void 0,
+				this._resolveReadStrategy(controls)
+			]);
+			const base = spec.overlay === "action" ? clientFilter : await this.transformFilter(clientFilter ?? {});
+			const searched = this.applySearchFallback(base, controls);
+			if (controls.$search && strategy.kind !== "search" && searched === base) throw targetInvalid(label, "$search is not available here");
+			const visibleOf = spec.visibleOf?.filter((f) => this.fieldVisibility.isVisible(f));
+			let select = spec.select;
+			if (spec.selectGate) {
+				const sealed = sealedSet();
+				for (const id of spec.identity ?? []) sealed.delete(id);
+				select = this._sealSelect([...spec.select], sealed, this.readable);
+			}
+			return {
+				searched,
+				readScope,
+				strategy,
+				visibleOf,
+				select
+			};
+		}, spec.routeParams), spec.overlay === "action" ? this.rowOverlay() : void 0]);
+		const { strategy } = read;
+		const filter = andFilters(read.searched, overlay, read.readScope, spec.scope, exclude.length > 0 ? { $not: { $or: exclude } } : void 0);
 		const findMany = (q) => strategy.kind === "search" ? this.readable.search(strategy.term, q, strategy.index) : this.readable.findMany(q);
-		const cap = Math.min(req.cap, body.maxRows ?? Infinity);
-		const sort = {};
-		for (const f of req.select) sort[f] = 1;
 		const rows = await findMany({
 			filter,
 			controls: {
-				$select: [...new Set(req.select)],
-				$sort: sort,
+				$select: [...read.select],
+				$sort: Object.fromEntries(spec.sortBy.map((f) => [f, 1])),
 				$limit: cap + 1
 			}
 		});
-		if (rows.length > cap) throw new ActionTargetError("TARGET_TOO_LARGE", action, `The query matches more than ${cap} rows`, { cap });
-		if (body.expectCount !== void 0 && body.expectCount !== rows.length) throw new ActionTargetError("TARGET_CHANGED", action, `The query now matches ${rows.length} rows (expected ${body.expectCount})`, { matched: rows.length });
-		const byIds = (read, ids, scope, select) => findRowsByIds({ findMany: (q) => read({
-			...q,
-			controls: {
-				...q.controls,
-				$limit: Math.max(ids.length, cap + 1)
-			}
-		}) }, ids, scope, select);
-		const snapshotFields = new Set(req.select);
-		let first = true;
+		if (rows.length > cap) throw new ActionTargetError("TARGET_TOO_LARGE", label, `The query matches more than ${cap} rows`, { cap });
+		if (body.expectCount !== void 0 && body.expectCount !== rows.length) throw new ActionTargetError("TARGET_CHANGED", label, `The query now matches ${rows.length} rows (expected ${body.expectCount})`, { matched: rows.length });
 		return {
-			matched: rows.length,
 			rows,
-			dryRun: body.dryRun === true,
+			filter,
+			findMany,
 			exclude,
-			load: (ids, select) => {
-				if (!first) return byIds(findMany, ids, filter, select);
-				first = false;
-				const fields = [...select];
-				if (!fields.every((f) => snapshotFields.has(f))) {
-					const plain = (q) => this.readable.findMany(q);
-					return byIds(plain, ids, void 0, fields);
-				}
-				return Promise.resolve(alignRowsToIds(rows, ids).map((row, i) => row ? projectRow$1(row, new Set([...fields, ...Object.keys(ids[i])])) : void 0));
-			}
+			visibleOf: read.visibleOf,
+			cap,
+			select: read.select
 		};
 	}
 	/**
+	* Rows of THIS controller matching `q`, resolved as a READ of it for the
+	* current event's caller (since 0.1.149) — from your own command, e.g. to
+	* act on "every issue matching this search". `q` is a `GET /query` string
+	* (`$search` / `$index` and a filter only) or a query-target envelope
+	* `{ q, exclude?, expectCount?, maxRows? }` (no `dryRun`).
+	*
+	* The read runs under this controller's full read policy
+	* ({@link prepareRequest} with `endpoint: "query"`, {@link hasField},
+	* {@link validateControls}, the capability / index gate and the
+	* {@link transformFilter} overlay) with the current event's identity.
+	* Route interceptors and guards of the `query` route do not run; read
+	* authorization belongs in {@link prepareRequest}. {@link queryTargetScope}
+	* is not called. Hooks see no route params of the caller (only a call from
+	* the routed event's own controller instance keeps its params); pass route-derived
+	* restrictions as `opts.scope`. Joins the caller's open transaction.
+	*
+	* Rows are ordered by identity (`preferredId`, else the primary key) and
+	* carry the identity fields plus `opts.select` (gated like `/query`
+	* `$select`; `transformProjection` is not applied — hide fields with
+	* {@link hasField}; decoration keys and navigation paths are refused). An
+	* identity-less readable is ordered by `select` (each path sortable, else
+	* `TARGET_INVALID`). More than `opts.cap` (default 1000) rows → 400
+	* `TARGET_TOO_LARGE`; a count other than `expectCount` → 409
+	* `TARGET_CHANGED`; a `$search` that can't be applied → 400
+	* `TARGET_INVALID`. Must be awaited inside a running event handler.
+	*/
+	async resolveQuery(q, opts = {}) {
+		let caller;
+		try {
+			caller = current();
+		} catch {
+			throw new Error("[moost-db] resolveQuery must be awaited inside an event handler");
+		}
+		const cap = opts.cap ?? 1e3;
+		if (!Number.isInteger(cap) || cap < 1) throw new Error("[moost-db] resolveQuery: `cap` must be a positive integer");
+		const select = opts.select ?? [];
+		if (!Array.isArray(select) || select.some((p) => typeof p !== "string")) throw new Error("[moost-db] resolveQuery: `select` must be an array of field paths");
+		const ids = this.readable.preferredId?.length ? this.readable.preferredId : this.readable.primaryKeys;
+		const order = ids.length > 0 ? ids : select;
+		if (order.length === 0) throw new Error("[moost-db] resolveQuery: this readable has no identity — pass `select` (rows are ordered by it)");
+		const label = readCurrentActionMeta(caller)?.name ?? "";
+		const body = parseQueryTargetBody(label, typeof q === "string" ? { q } : q);
+		if (body.dryRun !== void 0) throw targetInvalid(label, "resolveQuery takes no `dryRun` — read `query.dryRun` yourself");
+		let sameRoute = false;
+		try {
+			sameRoute = controllerOf(caller) === this && routedController(caller) === this;
+		} catch {}
+		const fields = [...new Set([...ids, ...select])];
+		const { rows, select: sealedSelect } = await this._resolveMatching({
+			label,
+			body,
+			cap,
+			maxExclude: DEFAULT_MAX_ACTION_IDS,
+			overlay: "read",
+			scope: opts.scope,
+			select: fields,
+			sortBy: order,
+			selectGate: select,
+			identity: ids,
+			sortGate: ids.length > 0 ? void 0 : order,
+			routeParams: sameRoute ? void 0 : {}
+		});
+		return rows.map((row) => projectRow$1(row, sealedSelect));
+	}
+	/**
 	* Runs `fn` as a READ of this controller (since 0.1.147): in a child of
 	* the current event whose controller context is this controller's `query`
 	* handler, after `prepareRequest({ endpoint: "query", controls, filter })` — the
 	* request-scoped state a permission layer builds there (read grant, field
-	* visibility) is the read's and stays in the child.
+	* visibility) is the read's and stays in the child. `routeParams` (since
+	* 0.1.149) replaces the route params the child's hooks read.
 	*/
-	_asRead(controls, filter, fn) {
+	_asRead(controls, filter, fn, routeParams) {
 		return runAsController(this, "query", async () => {
+			if (routeParams) current().set(routeParamsKey, routeParams);
 			if (typeof this.prepareRequest === "function") await this.prepareRequest(readRequestContext("query", controls, filter));
 			return fn();
 		});
@@ -5570,7 +5740,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* with the existing filter. Applies only when native search does not serve
 	* the request (no native search, or — since 0.1.143 — its default index
 	* reads a field {@link hasField} hides) and the request isn't a vector
-	* search (`$vector` consumes the term).
+	* search (`$vector` consumes the term). Lenient on list endpoints: a term
+	* nothing can apply is ignored. Resolvers (query targets, `resolveQuery`)
+	* refuse it — a subclass override that applies the term must return a new
+	* filter object.
 	*/
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
@@ -6360,7 +6533,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			maxExclude: limits.maxIds,
 			overlay: "read",
 			select: [...new Set([...identity, ...delegation.paths])],
-			excludeShapes: [delegation.paths]
+			excludeShapes: [delegation.paths],
+			visibleOf: identity
 		});
 		if (resolved.dryRun) return { matched: resolved.matched };
 		const summary = {
@@ -6370,7 +6544,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			failed: []
 		};
 		const { ids, index } = mapToSourceIds(resolved.rows, delegation.idMap);
-		const visibleIdentity = identity.filter((f) => this.fieldVisibility.isVisible(f));
+		const visibleIdentity = resolved.visibleOf ?? [];
 		for (let i = 0; i < index.length; i++) {
 			if (index[i] >= 0) continue;
 			const row = resolved.rows[i];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.148",
+  "version": "0.1.149",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@uniqu/url": "^0.1.13",
-    "@atscript/db-memory": "^0.1.148"
+    "@atscript/db-memory": "^0.1.149"
   },
   "devDependencies": {
     "@atscript/core": "^0.1.100",
@@ -57,7 +57,7 @@
     "better-sqlite3": "^12.6.2",
     "moost": "^0.6.45",
     "unplugin-atscript": "^0.1.100",
-    "@atscript/db-sqlite": "^0.1.148"
+    "@atscript/db-sqlite": "^0.1.149"
   },
   "peerDependencies": {
     "@atscript/typescript": "^0.1.100",
@@ -66,7 +66,7 @@
     "@wooksjs/event-core": "^0.7.26",
     "@wooksjs/http-body": "^0.7.26",
     "moost": "^0.6.45",
-    "@atscript/db": "^0.1.148"
+    "@atscript/db": "^0.1.149"
   },
   "scripts": {
     "postinstall": "asc -f dts",