@atscript/moost-db 0.1.148 → 0.1.150

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);
@@ -2100,6 +2108,393 @@ function walk(node, def, shallow) {
 	}
 }
 //#endregion
+//#region src/http-path-design-time.ts
+const KEY$1 = "db.http.path";
+/** The `@db.http.path` value a model carried before moost-db first wrote its published path. */
+const designTime = /* @__PURE__ */ new WeakMap();
+/**
+* Remembers the model's own `@db.http.path` (or its absence) before the first
+* published path is mirrored into its runtime metadata. Idempotent.
+*
+* @since 0.1.150
+*/
+function captureDesignTime(type) {
+	if (!designTime.has(type)) designTime.set(type, type.metadata.get(KEY$1));
+}
+/**
+* The route hint a model declares with `@db.http.path` — never the path
+* moost-db mirrored into the runtime metadata afterwards. Decorators and
+* `assertExposed` read this.
+*
+* @since 0.1.150
+*/
+function designTimeHttpPath(type) {
+	return designTime.has(type) ? designTime.get(type) : type.metadata.get(KEY$1);
+}
+/** The captured design-time value (`undefined` when none was captured or declared). */
+function getDesignTime(type) {
+	return designTime.get(type);
+}
+//#endregion
+//#region src/decorators.ts
+/**
+* DI token under which the {@link AtscriptDbReadable} instance
+* is exposed to the readable controller's constructor via `@Inject`.
+*/
+const READABLE_DEF = "__atscript_db_readable_def";
+/**
+* DI token under which the {@link AtscriptDbTable} instance
+* is exposed to the controller's constructor via `@Inject`.
+* Points to the same token as READABLE_DEF for backward compatibility.
+*/
+const TABLE_DEF = READABLE_DEF;
+function normalizeOptions(prefixOrOptions) {
+	if (typeof prefixOrOptions === "string") return { prefix: prefixOrOptions };
+	return prefixOrOptions ?? {};
+}
+/**
+* Builds the shared binding metadata for a decorator invocation: classifies
+* the binding form, computes the static route prefix, and packages a uniform
+* `resolve()` used by both the DI provide factory and the base controller's
+* `super(app)` fallback.
+*/
+function buildBinding(binding, options, decoratorName) {
+	const canonical = options.canonical;
+	if ((0, _atscript_typescript_utils.isAnnotatedType)(binding)) {
+		const model = binding;
+		const space = options.space ?? model.metadata.get("db.space");
+		const hinted = designTimeHttpPath(model);
+		const prefix = options.prefix || hinted || model.metadata.get("db.table") || model.metadata.get("db.view") || model.id || "";
+		const prefixSource = options.prefix ? "option" : hinted ? "annotation" : "name";
+		if (!prefix) throw new Error(`[moost-db] @${decoratorName}: cannot derive a route prefix from the model token (no @db.http.path / @db.table / @db.view and no type id). Pass an explicit prefix.`);
+		return {
+			meta: {
+				model,
+				resolve: () => require_db_space_registry.resolveDbSpace(space).get(model),
+				prefix,
+				prefixSource,
+				canonical
+			},
+			prefix
+		};
+	}
+	if (typeof binding === "function") {
+		if (!options.prefix) throw new Error(`[moost-db] @${decoratorName}: the lazy factory form needs an explicit route prefix (the readable is not created until app.init()). Pass a prefix, or use the model token form which derives it from @db.http.path / @db.table.`);
+		return {
+			meta: {
+				resolve: binding,
+				prefix: options.prefix,
+				prefixSource: "option",
+				canonical
+			},
+			prefix: options.prefix
+		};
+	}
+	const readable = binding;
+	const hinted = designTimeHttpPath(readable.type);
+	const prefix = options.prefix || hinted || readable.tableName;
+	return {
+		meta: {
+			model: readable.type,
+			resolve: () => readable,
+			prefix,
+			prefixSource: options.prefix ? "option" : hinted ? "annotation" : "name",
+			canonical
+		},
+		prefix
+	};
+}
+function bindReadableController(binding, prefixOrOptions, decoratorName) {
+	const { meta, prefix } = buildBinding(binding, normalizeOptions(prefixOrOptions), decoratorName);
+	return (0, moost.ApplyDecorators)(getAtscriptDbMate().decorate((classMeta) => {
+		classMeta.atscript_db_readable_binding = meta;
+		return classMeta;
+	}), (0, moost.Provide)(READABLE_DEF, () => meta.resolve()), (0, moost.Controller)(prefix), (0, moost.Inherit)());
+}
+/**
+* Combines the boilerplate needed to turn an {@link AsDbController}
+* subclass into a fully wired HTTP controller for a given `@db.table` model.
+*
+* Internally applies three decorators:
+* 1. **Provide** — registers the readable resolver under {@link TABLE_DEF}.
+* 2. **Controller** — registers the class as a Moost HTTP controller
+*    with an optional route prefix (defaults to `@db.http.path`, then the
+*    table name).
+* 3. **Inherit** — copies metadata (routes, guards, etc.) from the
+*    parent class so they stay active in the derived controller.
+*
+* All three binding forms are supported (see {@link TReadableBinding}):
+*
+* ```ts
+* ‎@TableController(User)                      // model token (preferred)
+* ‎@TableController(User, { space: "analytics" })
+* ‎@TableController(() => db.getTable(User), "users") // lazy factory
+* ‎@TableController(usersTable)                // instance (legacy)
+* export class UsersController extends AsDbController<typeof User> {}
+* ```
+*
+* Token and factory forms resolve lazily at first controller instantiation
+* (during `app.init()`), so the `DbSpace` does not have to exist when the
+* controller module is imported. For the token form, register the space with
+* `provideDbSpace(db)` before `app.init()`.
+*
+* @param binding Model token, lazy factory, or {@link AtscriptDbTable} instance.
+* @param prefixOrOptions Route prefix string, or {@link TControllerBindingOptions}.
+*/
+const TableController = (binding, prefixOrOptions) => bindReadableController(binding, prefixOrOptions, "TableController");
+/**
+* Combines the boilerplate needed to turn an {@link AsDbReadableController}
+* subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
+*
+* Accepts the same three binding forms as {@link TableController}.
+*
+* @param binding Model token, lazy factory, or {@link AtscriptDbReadable} instance.
+* @param prefixOrOptions Route prefix string, or {@link TControllerBindingOptions}.
+*
+* @example
+* ```ts
+* ‎@ReadableController(ActiveTasks)
+* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+* ```
+*/
+const ReadableController = (binding, prefixOrOptions) => bindReadableController(binding, prefixOrOptions, "ReadableController");
+/**
+* Alias for {@link ReadableController} — use with view-backed controllers.
+*
+* @example
+* ```ts
+* ‎@ViewController(ActiveTasks)
+* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+* ```
+*/
+const ViewController = ReadableController;
+/**
+* Finds the readable binding written by `@TableController` /
+* `@ReadableController` / `@ViewController` on a controller class, walking the
+* prototype chain so intermediate undecorated classes don't hide the binding
+* (nearest decorated ancestor wins).
+*/
+function findReadableBinding(ctor) {
+	const mate = getAtscriptDbMate();
+	let current = ctor;
+	while (typeof current === "function") {
+		const binding = mate.read(current)?.atscript_db_readable_binding;
+		if (binding) return binding;
+		current = Object.getPrototypeOf(current);
+	}
+}
+/**
+* Resolves the readable bound to a controller class via
+* {@link findReadableBinding}, throwing with wiring guidance when none is
+* found.
+*
+* Used by {@link AsDbReadableController}'s constructor when `readable` is
+* `undefined` — i.e. a subclass with its own constructor called
+* `super(app)` instead of forwarding an injected instance.
+*/
+function resolveBoundReadable(ctor) {
+	const binding = findReadableBinding(ctor);
+	if (binding) return binding.resolve();
+	throw new Error(`[moost-db] ${ctor?.name || "controller"}: no readable bound. Either pass a table/view to super(...), or decorate the class with @TableController / @ReadableController (model token, lazy factory, or instance form).`);
+}
+//#endregion
+//#region src/http-path.ts
+const KEY = "db.http.path";
+/**
+* Normalizes a controller prefix into a public path: one leading slash, no
+* empty segments, no trailing slash.
+*
+* @since 0.1.150
+*/
+function normalizeHttpPath(prefix) {
+	return `/${prefix.split("/").filter(Boolean).join("/")}`;
+}
+/** A path with a route parameter or a wildcard cannot be a static picker URL. */
+function isParametricPath(path) {
+	return path.split("/").some((s) => s.startsWith(":") || s.includes("*"));
+}
+/** Per app (the constructor's `app` argument): another app's construction never alters this app's records. */
+const bound = /* @__PURE__ */ new WeakMap();
+/**
+* Process-wide records per ctor: the fallback for an app that never
+* constructed the class itself (a DI singleton reused across apps), read only
+* when it holds exactly one model.
+*/
+const boundAny = /* @__PURE__ */ new WeakMap();
+let boundVersion = 0;
+/**
+* Records that `ctor` serves `type` inside `app` (called by the readable base constructor).
+* Pure bookkeeping — nothing is written to the model. Only a NEW pair bumps
+* the version that invalidates per-app scopes.
+*/
+function recordBoundType(app, ctor, type, canonical) {
+	let ofApp = bound.get(app);
+	if (!ofApp) {
+		ofApp = /* @__PURE__ */ new WeakMap();
+		bound.set(app, ofApp);
+	}
+	let models = ofApp.get(ctor);
+	if (!models) {
+		models = /* @__PURE__ */ new Map();
+		ofApp.set(ctor, models);
+	}
+	let any = boundAny.get(ctor);
+	if (!any) {
+		any = /* @__PURE__ */ new Map();
+		boundAny.set(ctor, any);
+	}
+	any.set(type, canonical);
+	if (!models.has(type) || models.get(type) !== canonical) {
+		models.set(type, canonical);
+		boundVersion++;
+	}
+}
+const apps = /* @__PURE__ */ new WeakMap();
+function stateOf(app) {
+	let s = apps.get(app);
+	if (!s) {
+		s = {
+			version: -1,
+			published: false,
+			hookAdded: false,
+			warned: /* @__PURE__ */ new Set()
+		};
+		apps.set(app, s);
+	}
+	return s;
+}
+const idOf = (type) => type.id ?? "(unnamed model)";
+const hasOverview = (app) => !!app && typeof app.getControllersOverview === "function";
+function endsWithSegments(path, suffix) {
+	const a = path.split("/").filter(Boolean);
+	const b = suffix.split("/").filter(Boolean);
+	if (b.length > a.length) return false;
+	return b.every((seg, i) => a[a.length - b.length + i] === seg);
+}
+function warnOnce(app, s, key, message) {
+	if (s.warned.has(key)) return;
+	s.warned.add(key);
+	try {
+		app.getLogger?.("moost-db")?.warn(message);
+	} catch {}
+}
+function buildScope(app, s) {
+	const mounts = /* @__PURE__ */ new Map();
+	for (const o of app.getControllersOverview()) {
+		if (typeof o.computedPrefix !== "string") continue;
+		const ctor = o.type;
+		const binding = findReadableBinding(ctor);
+		let recorded = bound.get(app)?.get(ctor);
+		if (!recorded) {
+			const any = boundAny.get(ctor);
+			if (any?.size === 1) recorded = any;
+		}
+		const models = recorded?.size ? [...recorded] : binding?.model ? [[binding.model, void 0]] : [];
+		if (models.length === 0) continue;
+		if (models.length > 1) {
+			warnOnce(app, s, `multi-model|${ctor.name}`, `[moost-db] ${ctor.name} serves several models; none of them gets a published value-help path (db.http.path).`);
+			continue;
+		}
+		const [model, recordedCanonical] = models[0];
+		const path = normalizeHttpPath(o.computedPrefix);
+		const ownPrefix = o.meta?.controller?.prefix ?? "";
+		const fromAnnotation = binding?.prefixSource === "annotation" && ownPrefix === binding.prefix && endsWithSegments(path, binding.prefix ?? "");
+		const list = mounts.get(model) ?? [];
+		list.push({
+			ctor,
+			path,
+			canonical: binding?.canonical ?? recordedCanonical,
+			fromAnnotation,
+			parametric: isParametricPath(path)
+		});
+		mounts.set(model, list);
+	}
+	const paths = /* @__PURE__ */ new Map();
+	for (const [model, list] of mounts) paths.set(model, resolveCanonical(app, s, model, list));
+	return { paths };
+}
+const distinct = (list) => [...new Set(list.map((m) => m.path))];
+function resolveCanonical(app, s, model, list) {
+	const cands = list.filter((m) => !m.parametric && m.canonical !== false);
+	const marked = distinct(cands.filter((m) => m.canonical === true));
+	if (marked.length === 1) return marked[0];
+	if (marked.length > 1) return ambiguous(app, s, model, cands, "has several canonical mounts");
+	const all = distinct(cands);
+	if (all.length === 0) return null;
+	if (all.length === 1) return all[0];
+	const derived = distinct(cands.filter((m) => m.fromAnnotation));
+	if (derived.length === 1) return derived[0];
+	return ambiguous(app, s, model, cands, "is served by several controllers on different routes");
+}
+function ambiguous(app, s, model, cands, what) {
+	const where = cands.map((m) => `${m.ctor.name} at ${m.path}`);
+	const id = idOf(model);
+	warnOnce(app, s, `${id}|${distinct(cands).toSorted().join(",")}|${what}`, `[moost-db] Model "${id}" ${what}:\n  ${where.join(", ")}.\nIts value-help path (db.http.path) is left unset, so references to it render no picker.\nMark the controller that serves its value help with \`canonical: true\`\n(@TableController(${id}, { canonical: true }), or a value-help controller's \`{ canonical: true }\`\nconstructor option) or \`canonical: false\` on the others, or declare @db.http.path on the\nmodel and mount that controller without an explicit prefix.`);
+	return null;
+}
+/**
+* The scope of `app`: built lazily, rebuilt on publish or when a new
+* controller → model pair was recorded. A hit never polls the overview.
+* `undefined` when `app` has no controller overview (mock apps).
+*/
+function httpPathScopeFor(app) {
+	if (!hasOverview(app)) return void 0;
+	const s = stateOf(app);
+	if (!s.scope || s.version !== boundVersion) {
+		s.scope = buildScope(app, s);
+		s.version = boundVersion;
+	}
+	return s.scope;
+}
+/** Models whose runtime metadata a publish wrote, with the value written. */
+const mirrored = /* @__PURE__ */ new Map();
+/** (Re)builds the scope of `app`, warns on ambiguity and writes the global compat mirror. */
+function publishDbHttpPaths(app) {
+	if (!hasOverview(app)) return;
+	const s = stateOf(app);
+	s.published = true;
+	s.scope = buildScope(app, s);
+	s.version = boundVersion;
+	const { paths } = s.scope;
+	for (const [type, value] of paths) {
+		captureDesignTime(type);
+		if (value === null) type.metadata.delete(KEY);
+		else type.metadata.set(KEY, value);
+		mirrored.set(type, value ?? void 0);
+	}
+	for (const [type, written] of mirrored) {
+		if (paths.has(type)) continue;
+		if (type.metadata.get(KEY) === written) {
+			const original = getDesignTime(type);
+			if (original === void 0) type.metadata.delete(KEY);
+			else type.metadata.set(KEY, original);
+		}
+		mirrored.delete(type);
+	}
+}
+/** Lazy fallback for apps that never ran the hook (singletons reused across apps). */
+function ensurePublished(app) {
+	if (!hasOverview(app)) return;
+	if (!stateOf(app).published) publishDbHttpPaths(app);
+}
+/** Registers the publish hook once per app (no-op on mock apps without `addInitHook`). */
+function addPublishHook(app) {
+	if (!app || typeof app.addInitHook !== "function") return;
+	const s = stateOf(app);
+	if (s.hookAdded) return;
+	s.hookAdded = true;
+	app.addInitHook((a) => publishDbHttpPaths(a), { priority: Number.MIN_SAFE_INTEGER });
+}
+/**
+* The `annotationOverrides` contribution for `scope`: the only way a path
+* reaches the wire. Models the app does not serve pass through at their
+* design-time value (never another app's mirror).
+*/
+function httpPathOverrides(scope, type) {
+	if (scope.paths.has(type)) return { [KEY]: scope.paths.get(type) ?? void 0 };
+	if (mirrored.has(type) && type.metadata.get(KEY) === mirrored.get(type)) return { [KEY]: getDesignTime(type) };
+}
+//#endregion
 //#region \0@oxc-project+runtime@0.133.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
@@ -2132,19 +2527,29 @@ let AsReadableController = class AsReadableController {
 	app;
 	/** Cached serialized type definition (lazy, computed on first access). */
 	_serializedType;
+	/** App scope every cache below was built for; a different scope drops them all ({@link enterScope}). */
+	_cacheScope;
+	/** Scope of the synchronous build in flight — instance-local, cleared in `finally`. */
+	_buildScope;
 	/** Cached full meta response (computed lazily on first meta() call). */
 	_metaResponse;
 	/** {@link metaCacheKey} the cached response was built for. */
 	_metaResponseKey;
 	/** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
 	_formSchemas = /* @__PURE__ */ new Map();
-	constructor(boundType, controllerName, app, kindTag = "readable") {
+	/**
+	* @param opts.canonical Multi-mount models only: marks (`true`) or excludes
+	*   (`false`) this controller as the model's published value-help route
+	*   (since 0.1.150). Decorator-bound controllers use the decorator option.
+	*/
+	constructor(boundType, controllerName, app, kindTag = "readable", opts) {
 		this.boundType = boundType;
 		this.controllerName = controllerName;
 		this.app = app;
 		this.logger = app.getLogger(`db [${controllerName}]`);
 		this.logger.info(`Initializing ${kindTag} controller`);
-		this._resolveHttpPath();
+		recordBoundType(app, this.constructor, boundType, opts?.canonical);
+		addPublishHook(app);
 		try {
 			const p = this.init();
 			if (p instanceof Promise) p.catch((error) => {
@@ -2155,22 +2560,40 @@ let AsReadableController = class AsReadableController {
 			throw error;
 		}
 	}
-	/** Sets @db.http.path on the type metadata from the controller's computed prefix. */
-	_resolveHttpPath() {
-		let prefix;
+	/**
+	* The app of the current event, through DI — never the one this
+	* (singleton) instance was constructed in, which may be gone (a re-booted
+	* app, a hot reload). Outside an event it is {@link app}.
+	*
+	* @since 0.1.150
+	*/
+	async currentApp() {
 		try {
-			prefix = (0, moost.useControllerContext)().getPrefix();
-		} catch {}
-		if (!prefix) prefix = (this.app.getControllersOverview?.()?.find((o) => o.type === this.constructor))?.computedPrefix;
-		if (prefix) {
-			if (!prefix.startsWith("/")) prefix = `/${prefix}`;
-			this.boundType.metadata.set("db.http.path", prefix);
+			return await (0, moost.useControllerContext)().instantiate(moost.Moost);
+		} catch {
+			return this.app;
 		}
 	}
-	/** Lazily serializes the bound type (after all controllers have set @db.http.path). */
+	/** Lazily serializes the bound type (dropped with the other caches on a scope change). */
 	getSerializedType() {
-		if (!this._serializedType) this._serializedType = this.serializeForMeta(this.boundType);
-		return this._serializedType;
+		return this._serializedType ??= this.serializeForMeta(this.boundType);
+	}
+	/** Drops every scope-dependent cache when `scope` is not the one they were built for. */
+	enterScope(scope) {
+		if (scope === this._cacheScope) return;
+		this._cacheScope = scope;
+		this._serializedType = void 0;
+		this._metaResponse = void 0;
+		this._formSchemas.clear();
+	}
+	/** Runs a synchronous build with `scope`'s `db.http.path` overrides applied. */
+	buildScoped(scope, build) {
+		this._buildScope = scope;
+		try {
+			return build();
+		} finally {
+			this._buildScope = void 0;
+		}
 	}
 	/**
 	* Serializes a type for the meta surfaces (`/meta`, `/meta/form/:name`)
@@ -2180,10 +2603,31 @@ let AsReadableController = class AsReadableController {
 	* serialize exactly as before.
 	*/
 	serializeForMeta(type) {
-		const options = this.getSerializeOptions();
+		const options = this._effectiveSerializeOptions();
 		return applyTerminalRefs((0, _atscript_typescript_utils.serializeAnnotatedType)(type, options), type, options);
 	}
 	/**
+	* {@link getSerializeOptions} plus the current build's per-app `db.http.path`
+	* overrides (a subclass's own `annotationOverrides` entry wins for the same key).
+	*/
+	_effectiveSerializeOptions() {
+		const base = this.getSerializeOptions();
+		const scope = this._buildScope;
+		if (!scope) return base;
+		const own = base.annotationOverrides;
+		return {
+			...base,
+			annotationOverrides: (t) => {
+				const ours = httpPathOverrides(scope, t);
+				const theirs = own?.(t);
+				return ours || theirs ? {
+					...ours,
+					...theirs
+				} : void 0;
+			}
+		};
+	}
+	/**
 	* One-time initialization hook. Override to seed data, register watchers, etc.
 	*/
 	init() {}
@@ -2381,7 +2825,53 @@ let AsReadableController = class AsReadableController {
 	*/
 	async meta() {
 		await this.parseRequest("meta");
-		return this.resolveMeta();
+		return this._withOwnHttpPath(await this.resolveMeta());
+	}
+	/**
+	* The root of a controller's own `/meta` carries its own mount as
+	* `db.http.path` (a secondary mount answers with its own route; references to
+	* the model elsewhere carry the canonical one). Left alone for parametric
+	* mounts and when the serialize options strip the key. Never mutates the
+	* cached envelope.
+	*/
+	_withOwnHttpPath(meta) {
+		const KEY = "db.http.path";
+		let prefix;
+		try {
+			prefix = (0, moost.useControllerContext)().getPrefix();
+		} catch {
+			return meta;
+		}
+		if (prefix === void 0 || prefix === null) return meta;
+		const own = normalizeHttpPath(prefix);
+		if (isParametricPath(own)) return meta;
+		const options = this.getSerializeOptions();
+		if (options.ignoreAnnotations?.includes(KEY)) return meta;
+		let key = KEY;
+		let value = own;
+		if (options.processAnnotation) {
+			const out = options.processAnnotation({
+				key: KEY,
+				value: own,
+				path: [],
+				kind: "object"
+			});
+			if (!out) return meta;
+			key = out.key;
+			value = out.value;
+		}
+		const type = meta.type;
+		if (!type || type.metadata?.[key] === value) return meta;
+		return {
+			...meta,
+			type: {
+				...meta.type,
+				metadata: {
+					...type.metadata,
+					[key]: value
+				}
+			}
+		};
 	}
 	/**
 	* The `/meta` payload for the current request — the cached envelope
@@ -2393,12 +2883,17 @@ let AsReadableController = class AsReadableController {
 	* @since 0.1.143
 	*/
 	resolveMeta() {
-		const key = this.metaCacheKey();
-		if (!this._metaResponse || key !== this._metaResponseKey) {
-			this._metaResponse = this.buildMetaResponse();
-			this._metaResponseKey = key;
-		}
-		return this.applyMetaOverlay(this._metaResponse);
+		return this.currentApp().then((app) => {
+			ensurePublished(app);
+			const scope = httpPathScopeFor(app);
+			this.enterScope(scope);
+			const key = this.metaCacheKey();
+			if (!this._metaResponse || key !== this._metaResponseKey) {
+				this._metaResponse = this.buildScoped(scope, () => this.buildMetaResponse());
+				this._metaResponseKey = key;
+			}
+			return this.applyMetaOverlay(this._metaResponse);
+		});
 	}
 	/**
 	* Identity of the inputs the cached `/meta` envelope is built from — a new
@@ -2421,9 +2916,13 @@ let AsReadableController = class AsReadableController {
 		const envelopes = discoverActions(this.constructor, this.app, this.logger);
 		const formType = getControllerFormType(this.constructor, name);
 		if (!formType || !await this.authorizeForm(name, envelopes.filter((e) => e.info.inputForm === name).map((e) => e.info.name))) throw new _moostjs_event_http.HttpError(404, `Unknown form "${name}"`);
+		const app = await this.currentApp();
+		ensurePublished(app);
+		const scope = httpPathScopeFor(app);
+		this.enterScope(scope);
 		let cached = this._formSchemas.get(name);
 		if (!cached) {
-			cached = this.serializeForMeta(formType);
+			cached = this.buildScoped(scope, () => this.serializeForMeta(formType));
 			this._formSchemas.set(name, cached);
 		}
 		return cached;
@@ -2505,6 +3004,7 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 	Object,
 	String,
 	typeof moost.Moost === "undefined" ? Object : moost.Moost,
+	Object,
 	Object
 ])], AsReadableController);
 //#endregion
@@ -3917,9 +4417,14 @@ var DecorationPlanner = class {
 		if (memoize) memo.meta.set(meta, out);
 		return out;
 	}
-	/** The declared interface serialized for `/meta.decorations`, once per class. */
-	serialized(serialize) {
-		return this.index.memo.serialized ??= serialize();
+	/** The declared interface serialized for `/meta.decorations`, once per class and app scope. */
+	serialized(scope, serialize) {
+		const { memo } = this.index;
+		if (!memo.serialized || memo.serializedScope !== scope) {
+			memo.serialized = serialize();
+			memo.serializedScope = scope;
+		}
+		return memo.serialized;
 	}
 };
 /** Removes what a read must not carry — the unserved declared keys and the hook-only paths — from `rows`. */
@@ -4006,153 +4511,6 @@ function stripsNothing(read) {
 	return read === void 0 || read.dropKeys.length === 0 && read.dropPaths.length === 0;
 }
 //#endregion
-//#region src/decorators.ts
-/**
-* DI token under which the {@link AtscriptDbReadable} instance
-* is exposed to the readable controller's constructor via `@Inject`.
-*/
-const READABLE_DEF = "__atscript_db_readable_def";
-/**
-* DI token under which the {@link AtscriptDbTable} instance
-* is exposed to the controller's constructor via `@Inject`.
-* Points to the same token as READABLE_DEF for backward compatibility.
-*/
-const TABLE_DEF = READABLE_DEF;
-function normalizeOptions(prefixOrOptions) {
-	if (typeof prefixOrOptions === "string") return { prefix: prefixOrOptions };
-	return prefixOrOptions ?? {};
-}
-/**
-* Builds the shared binding metadata for a decorator invocation: classifies
-* the binding form, computes the static route prefix, and packages a uniform
-* `resolve()` used by both the DI provide factory and the base controller's
-* `super(app)` fallback.
-*/
-function buildBinding(binding, options, decoratorName) {
-	if ((0, _atscript_typescript_utils.isAnnotatedType)(binding)) {
-		const model = binding;
-		const space = options.space ?? model.metadata.get("db.space");
-		const prefix = options.prefix || model.metadata.get("db.http.path") || model.metadata.get("db.table") || model.metadata.get("db.view") || model.id || "";
-		if (!prefix) throw new Error(`[moost-db] @${decoratorName}: cannot derive a route prefix from the model token (no @db.http.path / @db.table / @db.view and no type id). Pass an explicit prefix.`);
-		return {
-			meta: {
-				model,
-				resolve: () => require_db_space_registry.resolveDbSpace(space).get(model)
-			},
-			prefix
-		};
-	}
-	if (typeof binding === "function") {
-		if (!options.prefix) throw new Error(`[moost-db] @${decoratorName}: the lazy factory form needs an explicit route prefix (the readable is not created until app.init()). Pass a prefix, or use the model token form which derives it from @db.http.path / @db.table.`);
-		return {
-			meta: { resolve: binding },
-			prefix: options.prefix
-		};
-	}
-	const readable = binding;
-	const prefix = options.prefix || readable.type.metadata.get("db.http.path") || readable.tableName;
-	return {
-		meta: {
-			model: readable.type,
-			resolve: () => readable
-		},
-		prefix
-	};
-}
-function bindReadableController(binding, prefixOrOptions, decoratorName) {
-	const { meta, prefix } = buildBinding(binding, normalizeOptions(prefixOrOptions), decoratorName);
-	return (0, moost.ApplyDecorators)(getAtscriptDbMate().decorate((classMeta) => {
-		classMeta.atscript_db_readable_binding = meta;
-		return classMeta;
-	}), (0, moost.Provide)(READABLE_DEF, () => meta.resolve()), (0, moost.Controller)(prefix), (0, moost.Inherit)());
-}
-/**
-* Combines the boilerplate needed to turn an {@link AsDbController}
-* subclass into a fully wired HTTP controller for a given `@db.table` model.
-*
-* Internally applies three decorators:
-* 1. **Provide** — registers the readable resolver under {@link TABLE_DEF}.
-* 2. **Controller** — registers the class as a Moost HTTP controller
-*    with an optional route prefix (defaults to `@db.http.path`, then the
-*    table name).
-* 3. **Inherit** — copies metadata (routes, guards, etc.) from the
-*    parent class so they stay active in the derived controller.
-*
-* All three binding forms are supported (see {@link TReadableBinding}):
-*
-* ```ts
-* ‎@TableController(User)                      // model token (preferred)
-* ‎@TableController(User, { space: "analytics" })
-* ‎@TableController(() => db.getTable(User), "users") // lazy factory
-* ‎@TableController(usersTable)                // instance (legacy)
-* export class UsersController extends AsDbController<typeof User> {}
-* ```
-*
-* Token and factory forms resolve lazily at first controller instantiation
-* (during `app.init()`), so the `DbSpace` does not have to exist when the
-* controller module is imported. For the token form, register the space with
-* `provideDbSpace(db)` before `app.init()`.
-*
-* @param binding Model token, lazy factory, or {@link AtscriptDbTable} instance.
-* @param prefixOrOptions Route prefix string, or {@link TControllerBindingOptions}.
-*/
-const TableController = (binding, prefixOrOptions) => bindReadableController(binding, prefixOrOptions, "TableController");
-/**
-* Combines the boilerplate needed to turn an {@link AsDbReadableController}
-* subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
-*
-* Accepts the same three binding forms as {@link TableController}.
-*
-* @param binding Model token, lazy factory, or {@link AtscriptDbReadable} instance.
-* @param prefixOrOptions Route prefix string, or {@link TControllerBindingOptions}.
-*
-* @example
-* ```ts
-* ‎@ReadableController(ActiveTasks)
-* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
-* ```
-*/
-const ReadableController = (binding, prefixOrOptions) => bindReadableController(binding, prefixOrOptions, "ReadableController");
-/**
-* Alias for {@link ReadableController} — use with view-backed controllers.
-*
-* @example
-* ```ts
-* ‎@ViewController(ActiveTasks)
-* export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
-* ```
-*/
-const ViewController = ReadableController;
-/**
-* Finds the readable binding written by `@TableController` /
-* `@ReadableController` / `@ViewController` on a controller class, walking the
-* prototype chain so intermediate undecorated classes don't hide the binding
-* (nearest decorated ancestor wins).
-*/
-function findReadableBinding(ctor) {
-	const mate = getAtscriptDbMate();
-	let current = ctor;
-	while (typeof current === "function") {
-		const binding = mate.read(current)?.atscript_db_readable_binding;
-		if (binding) return binding;
-		current = Object.getPrototypeOf(current);
-	}
-}
-/**
-* Resolves the readable bound to a controller class via
-* {@link findReadableBinding}, throwing with wiring guidance when none is
-* found.
-*
-* Used by {@link AsDbReadableController}'s constructor when `readable` is
-* `undefined` — i.e. a subclass with its own constructor called
-* `super(app)` instead of forwarding an injected instance.
-*/
-function resolveBoundReadable(ctor) {
-	const binding = findReadableBinding(ctor);
-	if (binding) return binding.resolve();
-	throw new Error(`[moost-db] ${ctor?.name || "controller"}: no readable bound. Either pass a table/view to super(...), or decorate the class with @TableController / @ReadableController (model token, lazy factory, or instance form).`);
-}
-//#endregion
 //#region src/permissions/crud-controls.ts
 /**
 * Static control whitelists per read op. Each list is the matching DTO's
@@ -4192,6 +4550,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 +4836,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
@@ -4790,9 +5161,16 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		return out;
 	}
+	/**
+	* The index visibility gate applies: {@link hasField} is overridden, or the
+	* model has `@db.writeOnly` fields (never readable through a search hit).
+	*/
+	get _indexGateActive() {
+		return this._hasFieldOverridden || this._writeOnlySet.size > 0;
+	}
 	/** Every path `entry` reads is visible to this request. */
 	_indexVisible(entry) {
-		return entry.fields.every(this.fieldVisibility.isVisible);
+		return entry.fields.every((path) => this.fieldVisibility.isVisible(path) && (0, _atscript_db.selfOrAncestor)(path, this._writeOnlySet) === void 0);
 	}
 	/**
 	* Native text search serves this request: the adapter searches natively
@@ -4811,7 +5189,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	}
 	_resolveNativeSearch(controls) {
 		if (!this.readable.isSearchable()) return false;
-		if (!this._hasFieldOverridden) return true;
+		if (!this._indexGateActive) return true;
 		if (typeof controls.$index === "string" && controls.$index) return true;
 		const def = this.indexFieldPaths().find((e) => e.type === "text" && e.isDefault);
 		return def === void 0 || this._indexVisible(def);
@@ -4825,7 +5203,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* nonexistent index (the core's wording).
 	*/
 	_checkIndexGate(controls) {
-		if (!this._hasFieldOverridden) return void 0;
+		if (!this._indexGateActive) return void 0;
 		const name = typeof controls.$index === "string" ? controls.$index : void 0;
 		if (controls.$center !== void 0) {
 			const geoIndexes = this.indexFieldPaths().filter((e) => e.type === "geo");
@@ -4857,7 +5235,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* `@db.column.searchable` fallback when any of its fields is visible).
 	*/
 	_applyIndexVisibility(meta) {
-		if (!this._hasFieldOverridden) return meta;
+		if (!this._indexGateActive) return meta;
 		const entries = this.indexFieldPaths();
 		const visibleDefault = (type) => {
 			const def = entries.find((e) => e.type === type && e.isDefault);
@@ -5070,6 +5448,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 +5786,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 +5863,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();
 		});
@@ -5505,6 +6032,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		for (const fd of this.readable.fieldDescriptors) {
 			if (fd.ignored) continue;
 			if (!fd.type?.metadata?.has?.("db.column.searchable")) continue;
+			if (typeof (0, _atscript_db.searchMemberKind)(fd.type) === "object") continue;
 			if (!this.capabilities.isPhysicallyFilterable(fd.path)) continue;
 			out.push(fd.path);
 		}
@@ -5573,7 +6101,18 @@ 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.
+	*
+	* A string field matches when the term is a substring of its text; an
+	* INTEGER field (`number.int` and its sizes, `@expect.int`,
+	* `@db.default.increment`) when it is a substring of the number's decimal
+	* text — `2946` finds `29461277` (since 0.1.150). To search numeric IDs
+	* declare `@db.column.searchable` (fallback) or `@db.index.fulltext`
+	* (native, exact number) on the integer field — override this hook only for
+	* search rules the annotations cannot express.
 	*/
 	applySearchFallback(filter, controls) {
 		const term = controls.$search;
@@ -5612,6 +6151,51 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		delete rest.$index;
 		return rest;
 	}
+	/**
+	* `$count` of a native text / vector search: the adapter's own count, so it
+	* agrees with `/query` and `/pages`. A text search counts every match (the
+	* single returned row is discarded); a vector search counts the nearest
+	* neighbours up to `$limit` (default 1000), as `/query` returns them.
+	*/
+	async _countSearched(strategy, filter, controls, sealedControls) {
+		const { $count: _count, ...sealed } = sealedControls;
+		if (strategy.kind === "search") {
+			const q = {
+				filter,
+				controls: this._searchReadControls(controls, sealed, sealed.$select, {
+					$skip: void 0,
+					$limit: 1
+				})
+			};
+			const { count } = await this.readable.searchWithCount(strategy.term, q, strategy.index);
+			return count;
+		}
+		const q = {
+			filter,
+			controls: this._searchReadControls(controls, sealed, sealed.$select, {
+				$skip: void 0,
+				$limit: controls.$limit || 1e3
+			})
+		};
+		const { count } = await (strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q));
+		return count;
+	}
+	/**
+	* The controls a native search / vector read is run with: the request's
+	* sealed controls (so every search control — `$fuzzy`, … — reaches the
+	* adapter) plus the select, the threshold and the caller's paging. ONE
+	* builder for `/query`, `/pages` and the native `$count`, so they can't
+	* disagree about what a search matches.
+	*/
+	_searchReadControls(controls, sealed, select, paging) {
+		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
+		return {
+			...sealed,
+			$select: select,
+			...paging,
+			$threshold: threshold
+		};
+	}
 	async _resolveReadStrategy(controls) {
 		const searchTerm = controls.$search;
 		const indexName = controls.$index;
@@ -5666,21 +6250,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (decorated === void 0) return strip();
 		return Promise.resolve(decorated).then(strip);
 	}
-	/**
-	* The app of the current event, through DI — never the one this
-	* (singleton) instance was constructed in, which may be gone (a re-booted
-	* app, a hot reload).
-	*/
-	_currentApp() {
-		return (0, moost.useControllerContext)().instantiate(moost.Moost);
-	}
 	/** The class's `@DbActionsFrom` delegations, validated on first use (per app). */
 	async _delegations() {
 		if (!this._hasDelegations) return [];
 		return discoverDelegations({
 			ctor: this.constructor,
 			readable: this.readable,
-			app: await this._currentApp(),
+			app: await this.currentApp(),
 			logger: this.logger,
 			instantiate: (ctor) => (0, moost.useControllerContext)().instantiate(ctor)
 		});
@@ -6038,24 +6614,22 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		const [transformedFilter, { sealed, finish }] = await Promise.all([this.transformFilter(clientFilter), this._projectRead(controls)]);
 		const filter = this.applySearchFallback(transformedFilter, controls);
-		if (controls.$count) return this.readable.count({
-			filter,
-			controls: {
-				...controls,
-				$select: sealed.$select
-			}
-		});
+		if (controls.$count) {
+			const strategy = await this._resolveReadStrategy(controls);
+			if (strategy.kind === "plain") return this.readable.count({
+				filter,
+				controls: {
+					...controls,
+					$select: sealed.$select
+				}
+			});
+			return this._countSearched(strategy, filter, controls, sealed);
+		}
 		const projected = finish();
 		if (projected instanceof _moostjs_event_http.HttpError) return projected;
-		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const queryObj = {
 			filter,
-			controls: {
-				...sealed,
-				$select: projected.select,
-				$limit: controls.$limit || 1e3,
-				$threshold: threshold
-			}
+			controls: this._searchReadControls(controls, sealed, projected.select, { $limit: controls.$limit || 1e3 })
 		};
 		return (await this._runReadWithActions("query", queryObj, controls, projected, async (q, strategy) => {
 			switch (strategy.kind) {
@@ -6082,16 +6656,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const filter = this.applySearchFallback(transformedFilter, controls);
 		const projected = finish();
 		if (projected instanceof _moostjs_event_http.HttpError) return projected;
-		const threshold = controls.$threshold ? Number(controls.$threshold) : void 0;
 		const query = {
 			filter,
-			controls: {
-				...sealed,
-				$select: projected.select,
+			controls: this._searchReadControls(controls, sealed, projected.select, {
 				$skip: skip,
-				$limit: size,
-				$threshold: threshold
-			}
+				$limit: size
+			})
 		};
 		const result = await this._runReadWithActions("pages", query, controls, projected, async (q, strategy) => {
 			switch (strategy.kind) {
@@ -6363,7 +6933,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 +6944,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];
@@ -6571,7 +7142,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			relations,
 			fields,
 			type: this.getSerializedType(),
-			...this._decorations && { decorations: this._planner.serialized(() => this.serializeForMeta(this._decorations.type)) },
+			...this._decorations && { decorations: this._planner.serialized(this._buildScope, () => this.serializeForMeta(this._decorations.type)) },
 			actions: this.buildActions(),
 			crud: this.buildCrud(),
 			versionColumn: this.readable.versionColumn,
@@ -6854,7 +7425,8 @@ let AsDbController = _AsDbController = class AsDbController extends AsDbReadable
 	* Bulk auto-lift: each item carries its own `version` → `$cas`.
 	* NOTE: per-item conflict disambiguation in the response body is deferred
 	* (§6.4) — the aggregate `{ matchedCount, modifiedCount }` surfaces partial
-	* application; callers can detect mismatches via `modifiedCount < N`.
+	* application; callers can detect mismatches via `matchedCount < N` (`modifiedCount` may
+	* be lower for unchanged values, e.g. a version-exempt patch on MySQL / Mongo).
 	*/
 	_resolveBulkCas(rows, versionColumn) {
 		if (versionColumn === void 0) return;
@@ -7066,8 +7638,8 @@ let AsValueHelpController = class AsValueHelpController extends AsReadableContro
 	searchableFields;
 	/** The `@meta.id` field name on the bound interface, if any. */
 	primaryKey;
-	constructor(boundType, controllerName, app) {
-		super(boundType, controllerName, app, "value-help");
+	constructor(boundType, controllerName, app, opts) {
+		super(boundType, controllerName, app, "value-help", opts);
 		assertNoValueHelpActions(this.constructor);
 		const fieldMeta = /* @__PURE__ */ new Map();
 		const explicitlySearchable = [];
@@ -7283,7 +7855,8 @@ __decorate([
 AsValueHelpController = __decorate([(0, moost.Inherit)(), __decorateMetadata("design:paramtypes", [
 	Object,
 	String,
-	typeof moost.Moost === "undefined" ? Object : moost.Moost
+	typeof moost.Moost === "undefined" ? Object : moost.Moost,
+	Object
 ])], AsValueHelpController);
 registerAsValueHelpController(AsValueHelpController);
 //#endregion
@@ -7291,9 +7864,9 @@ registerAsValueHelpController(AsValueHelpController);
 let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueHelpController {
 	rows;
 	_pkIndex;
-	constructor(boundType, rows, app, controllerName) {
+	constructor(boundType, rows, app, controllerName, opts) {
 		const name = controllerName || boundType.metadata.get("db.table") || "value-help";
-		super(boundType, name, app);
+		super(boundType, name, app, opts);
 		this.rows = rows;
 		if (this.primaryKey) {
 			const pk = this.primaryKey;
@@ -7368,7 +7941,8 @@ AsJsonValueHelpController = __decorate([(0, moost.Inherit)(), __decorateMetadata
 	Object,
 	Array,
 	typeof moost.Moost === "undefined" ? Object : moost.Moost,
-	String
+	String,
+	Object
 ])], AsJsonValueHelpController);
 //#endregion
 //#region src/assert-exposed.ts
@@ -7412,7 +7986,7 @@ function assertExposed(app, models, options) {
 	const missing = [];
 	for (const model of models) {
 		if ((0, _atscript_db.aliasTargetOf)(model)) continue;
-		const httpPath = model.metadata.get("db.http.path");
+		const httpPath = designTimeHttpPath(model);
 		if (!auditAll && httpPath === void 0) continue;
 		if (excluded.has(model) || exposed.has(model)) continue;
 		missing.push(model);