@atscript/moost-db 0.1.149 → 0.1.150

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotate
 import { Body, Delete, Get, HttpError, MoostHttp, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 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 { 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, searchMemberKind, selfOrAncestor, unsupportedOperatorMessage, vectorIndexNotFoundMessage } from "@atscript/db";
 import { cached, current, defineWook, key, routeParamsKey, useRouteParams } from "@wooksjs/event-core";
 import { useBody } from "@wooksjs/http-body";
 import { BUCKET_UNITS } from "@uniqu/core";
@@ -2107,6 +2107,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 (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: () => 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 ApplyDecorators(getAtscriptDbMate().decorate((classMeta) => {
+		classMeta.atscript_db_readable_binding = meta;
+		return classMeta;
+	}), Provide(READABLE_DEF, () => meta.resolve()), Controller(prefix), 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);
@@ -2139,19 +2526,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) => {
@@ -2162,22 +2559,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 = 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 useControllerContext().instantiate(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`)
@@ -2187,10 +2602,31 @@ let AsReadableController = class AsReadableController {
 	* serialize exactly as before.
 	*/
 	serializeForMeta(type) {
-		const options = this.getSerializeOptions();
+		const options = this._effectiveSerializeOptions();
 		return applyTerminalRefs(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() {}
@@ -2388,7 +2824,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 = 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
@@ -2400,12 +2882,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
@@ -2428,9 +2915,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 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;
@@ -2512,6 +3003,7 @@ AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMeta
 	Object,
 	String,
 	typeof Moost === "undefined" ? Object : Moost,
+	Object,
 	Object
 ])], AsReadableController);
 //#endregion
@@ -3922,9 +4414,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`. */
@@ -4011,153 +4508,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 (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: () => 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 ApplyDecorators(getAtscriptDbMate().decorate((classMeta) => {
-		classMeta.atscript_db_readable_binding = meta;
-		return classMeta;
-	}), Provide(READABLE_DEF, () => meta.resolve()), Controller(prefix), 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
@@ -4808,9 +5158,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) && selfOrAncestor(path, this._writeOnlySet) === void 0);
 	}
 	/**
 	* Native text search serves this request: the adapter searches natively
@@ -4829,7 +5186,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);
@@ -4843,7 +5200,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");
@@ -4875,7 +5232,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);
@@ -5672,6 +6029,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 searchMemberKind(fd.type) === "object") continue;
 			if (!this.capabilities.isPhysicallyFilterable(fd.path)) continue;
 			out.push(fd.path);
 		}
@@ -5744,6 +6102,14 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* 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;
@@ -5782,6 +6148,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;
@@ -5836,21 +6247,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 useControllerContext().instantiate(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) => useControllerContext().instantiate(ctor)
 		});
@@ -6208,24 +6611,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 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) {
@@ -6252,16 +6653,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const filter = this.applySearchFallback(transformedFilter, controls);
 		const projected = finish();
 		if (projected instanceof 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) {
@@ -6742,7 +7139,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,
@@ -7025,7 +7422,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;
@@ -7237,8 +7635,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 = [];
@@ -7454,7 +7852,8 @@ __decorate([
 AsValueHelpController = __decorate([Inherit(), __decorateMetadata("design:paramtypes", [
 	Object,
 	String,
-	typeof Moost === "undefined" ? Object : Moost
+	typeof Moost === "undefined" ? Object : Moost,
+	Object
 ])], AsValueHelpController);
 registerAsValueHelpController(AsValueHelpController);
 //#endregion
@@ -7462,9 +7861,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;
@@ -7539,7 +7938,8 @@ AsJsonValueHelpController = __decorate([Inherit(), __decorateMetadata("design:pa
 	Object,
 	Array,
 	typeof Moost === "undefined" ? Object : Moost,
-	String
+	String,
+	Object
 ])], AsJsonValueHelpController);
 //#endregion
 //#region src/assert-exposed.ts
@@ -7583,7 +7983,7 @@ function assertExposed(app, models, options) {
 	const missing = [];
 	for (const model of models) {
 		if (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);