@atscript/moost-db 0.1.150 → 0.1.152

package/dist/index.cjs

@@ -594,30 +594,83 @@ function identityOf(row, fields, read) {
 	return id;
 }
 /**
+* Sorted field lists per raw key order — every id of one shape sorts its keys
+* once per call, not once per id.
+*/
+var IdShapes = class {
+	/** Raw key order (`Object.keys` joined) → the sorted fields. */
+	byRaw = /* @__PURE__ */ new Map();
+	/** Sorted signature → the sorted fields (one entry per distinct shape). */
+	bySorted = /* @__PURE__ */ new Map();
+	fieldsOf(id) {
+		const keys = Object.keys(id);
+		const raw = `${keys.length}:${keys.join("")}`;
+		let sorted = this.byRaw.get(raw);
+		if (sorted === void 0) {
+			const own = keys.length > 1 ? keys.toSorted() : keys;
+			const sig = `${own.length}:${own.join("")}`;
+			sorted = this.bySorted.get(sig);
+			if (sorted === void 0) this.bySorted.set(sig, sorted = own);
+			this.byRaw.set(raw, sorted);
+		}
+		return sorted;
+	}
+};
+/** A value `$in` matches exactly like the equality `{ field: value }` on every adapter. */
+function isInSafe(value) {
+	const type = typeof value;
+	return type === "string" || type === "bigint" || type === "boolean" || type === "number" && Number.isFinite(value);
+}
+/**
+* The filter matching any of `ids` (deduped): `{ field: { $in } }` when they
+* share one single-field shape with scalar values (one equality for a single
+* id), else `{ $or: ids }`.
+*/
+function idsFilter(ids, shapes) {
+	if (ids.length > 0 && shapes.bySorted.size === 1) {
+		const [fields] = shapes.bySorted.values();
+		if (fields.length === 1) {
+			const field = fields[0];
+			const values = [];
+			for (const id of ids) {
+				const value = id[field];
+				if (!isInSafe(value)) return { $or: ids };
+				values.push(value);
+			}
+			return values.length === 1 ? { [field]: values[0] } : { [field]: { $in: values } };
+		}
+	}
+	return { $or: ids };
+}
+/**
 * The rows `ids` address that also match `scope` (none = every row),
 * aligned with `ids` — `undefined` where nothing matched. One `findMany`
-* over the deduped ids (`{ $or: ids } AND scope`) selecting `select` plus
-* every id field; ids of different identification shapes may be mixed.
-* The action row loader and `$actions` scope check share it.
+* over the deduped ids (`{ field: { $in } }` for single-field ids, else
+* `{ $or: ids }`; AND `scope`) selecting `select` plus every id field; ids of
+* different identification shapes may be mixed. The action row loader and
+* `$actions` scope check share it.
 */
 async function findRowsByIds(source, ids, scope, select) {
 	if (ids.length === 0) return [];
 	const fields = new Set(select);
 	const dedupedIds = [];
 	const seenKeys = /* @__PURE__ */ new Set();
+	const shapes = new IdShapes();
+	const idKeys = [];
 	for (const id of ids) {
-		const sortedFields = Object.keys(id).toSorted();
-		for (const f of sortedFields) fields.add(f);
-		const key = idKey(id, sortedFields);
+		const key = idKey(id, shapes.fieldsOf(id));
+		idKeys.push(key);
 		if (key !== void 0 && !seenKeys.has(key)) {
 			seenKeys.add(key);
 			dedupedIds.push(id);
 		}
 	}
-	return alignRowsToIds(await source.findMany({
-		filter: scope ? { $and: [{ $or: dedupedIds }, scope] } : { $or: dedupedIds },
+	for (const sortedFields of shapes.bySorted.values()) for (const f of sortedFields) fields.add(f);
+	const match = idsFilter(dedupedIds, shapes);
+	return alignByKeys(await source.findMany({
+		filter: scope ? { $and: [match, scope] } : match,
 		controls: { $select: [...fields] }
-	}), ids);
+	}), idKeys, shapes);
 }
 /**
 * `rows` aligned with `ids` — per id, the first row with its key values
@@ -625,16 +678,12 @@ async function findRowsByIds(source, ids, scope, select) {
 * identification shapes may be mixed.
 */
 function alignRowsToIds(rows, ids) {
-	const shapes = /* @__PURE__ */ new Map();
-	const idKeys = [];
-	for (const id of ids) {
-		const sortedFields = Object.keys(id).toSorted();
-		const sig = sortedFields.join("");
-		if (!shapes.has(sig)) shapes.set(sig, sortedFields);
-		idKeys.push(idKey(id, sortedFields));
-	}
+	const shapes = new IdShapes();
+	return alignByKeys(rows, ids.map((id) => idKey(id, shapes.fieldsOf(id))), shapes);
+}
+function alignByKeys(rows, idKeys, shapes) {
 	const rowByKey = /* @__PURE__ */ new Map();
-	for (const row of rows) for (const sortedFields of shapes.values()) {
+	for (const row of rows) for (const sortedFields of shapes.bySorted.values()) {
 		const key = idKey(row, sortedFields);
 		if (key !== void 0 && !rowByKey.has(key)) rowByKey.set(key, row);
 	}
@@ -661,11 +710,43 @@ function exceedsFields(row, fields) {
 	for (const key in row) if (!fields.has(key)) return true;
 	return false;
 }
+/**
+* `row` without its own `keys` — a NEW object (same key order) when it has
+* any of them, else `row` itself. Rows are rebuilt rather than `delete`d
+* from: a deleted key turns an object into a slow dictionary-mode one for
+* everything after (decoration, serialization).
+*/
+function omitKeys(row, keys) {
+	let has = false;
+	for (const key of keys) if (Object.hasOwn(row, key)) {
+		has = true;
+		break;
+	}
+	if (!has) return row;
+	const out = {};
+	for (const key of Object.keys(row)) {
+		if (keys.has(key)) continue;
+		if (key === "__proto__") Object.defineProperty(out, key, {
+			value: row[key],
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+		else out[key] = row[key];
+	}
+	return out;
+}
+/** `fields` split at the dots — pass to {@link projectRow} when projecting many rows. */
+function splitPaths(fields) {
+	const out = [];
+	for (const path of fields) out.push(path.split("."));
+	return out;
+}
 /** `row` narrowed to `fields` (dot paths copied into fresh nested objects). */
 function projectRow$2(row, fields) {
 	const out = {};
 	for (const path of fields) {
-		const parts = path.split(".");
+		const parts = typeof path === "string" ? path.split(".") : path;
 		let src = row;
 		for (const p of parts) src = src?.[p];
 		if (src === void 0) continue;
@@ -1845,13 +1926,13 @@ function copyClientFilter(filter, freeze = false) {
 	} catch {
 		throw badRequest("", "Malformed query: the filter cannot be copied");
 	}
-	if (freeze) deepFreeze(copy);
+	if (freeze) deepFreeze$1(copy);
 	return copy;
 }
-function deepFreeze(v) {
+function deepFreeze$1(v) {
 	if (v === null || typeof v !== "object" || Object.isFrozen(v)) return;
 	Object.freeze(v);
-	for (const child of Object.values(v)) deepFreeze(child);
+	for (const child of Object.values(v)) deepFreeze$1(child);
 }
 /** The predicate operator maps of a filter's own level (through `$and` / `$or` / `$not`). */
 function collectPredicateMaps(filter, out) {
@@ -2108,6 +2189,129 @@ function walk(node, def, shallow) {
 	}
 }
 //#endregion
+//#region src/meta/meta-cache.ts
+/**
+* `/meta` identity memo (since 0.1.151). Each layer that turns the cached
+* envelope into a request's `/meta` object memoizes its output per INPUT
+* identity and per the request-dependent answers it reads (the key), so
+* equal inputs give the same object across requests. The final object is
+* then registered with wooks' `prerenderJson` (JSON serialized once, weak
+* ETag from the bytes).
+*
+* Soundness: a memoized object is never mutated (the `applyMetaOverlay`
+* contract), so its identity implies its bytes; every key covers every
+* request-dependent input its layer reads. Inputs that are not themselves
+* stable (an overlay that builds a fresh object per request) are not memoized —
+* their output is computed per request, as before, and gets no ETag.
+*/
+/** Objects whose identity implies their bytes: cached envelopes and memo outputs derived from one. */
+const stable = /* @__PURE__ */ new WeakSet();
+/**
+* Most memoized variants derived from one root envelope, over all chained
+* layers (planner → index visibility → delegated actions → own path); past it
+* a variant is computed per request (and is not stable).
+*/
+const MAX_VARIANTS_PER_ROOT = 128;
+/** The root envelope each memo output was derived from (for the budget). */
+const rootOf = /* @__PURE__ */ new WeakMap();
+/** Variants memoized so far per root envelope. */
+const rootBudget = /* @__PURE__ */ new WeakMap();
+/** Marks `obj` as identity-stable (never mutated after this point). Returns it. */
+function markStableMeta(obj) {
+	stable.add(obj);
+	return obj;
+}
+/**
+* Marks a `/meta` payload your override memoizes (an `applyMetaOverlay`
+* variant, a `metaForm` projection) as reusable: it is deep-frozen and, when
+* served again, sent from its serialized-once JSON with an `ETag`. Return the
+* same object for the same inputs only — its bytes are fixed from now on.
+*
+* @since 0.1.151
+*/
+function stableMeta(obj) {
+	deepFreeze(obj);
+	return markStableMeta(obj);
+}
+/**
+* `obj` may be memoized on and registered for prerendering: a cached envelope,
+* a memo output, or an object passed to {@link stableMeta}. (Frozenness alone
+* is not enough: `Object.freeze` is shallow.)
+*/
+function isStableMeta(obj) {
+	return stable.has(obj);
+}
+/**
+* The memoized variant of `input` for `key` in `variants` — `compute()` once
+* per (input, key). Keys of different layers must not collide (prefix them).
+* An unstable input is not memoized (computed every time); past
+* {@link MAX_VARIANTS_PER_ROOT} variants of one envelope a variant is computed
+* per request (and is not stable).
+*/
+function metaVariant(variants, input, key, compute) {
+	if (!isStableMeta(input)) return compute();
+	let byKey = variants.get(input);
+	const hit = byKey?.get(key);
+	if (hit) return hit;
+	const out = compute();
+	const root = rootOf.get(input) ?? input;
+	const used = rootBudget.get(root) ?? 0;
+	if (used < MAX_VARIANTS_PER_ROOT) {
+		rootBudget.set(root, used + 1);
+		if (out !== input) {
+			markStableMeta(out);
+			rootOf.set(out, root);
+		}
+		if (!byKey) variants.set(input, byKey = /* @__PURE__ */ new Map());
+		byKey.set(key, out);
+	}
+	return out;
+}
+/** Stable small ids for objects (memo keys over object identities). */
+const ids = /* @__PURE__ */ new WeakMap();
+let nextId = 1;
+/** A per-process id of `obj`'s identity. */
+function identityId(obj) {
+	let id = ids.get(obj);
+	if (id === void 0) ids.set(obj, id = nextId++);
+	return id;
+}
+/** Bit string of `flags` (memo key). */
+function bits(flags) {
+	let out = "";
+	for (const flag of flags) out += flag ? "1" : "0";
+	return out;
+}
+let freezeServed;
+const deepFrozen = /* @__PURE__ */ new WeakSet();
+/**
+* Shared objects are deep-frozen when `NODE_ENV` is `test` or
+* `development`, or `ATSCRIPT_DB_FREEZE_META=1` — an in-place mutation (which
+* would keep serving the old bytes) then throws instead.
+*/
+function shouldFreeze() {
+	if (freezeServed === void 0) {
+		const env = typeof process === "undefined" ? void 0 : process.env;
+		freezeServed = env?.NODE_ENV === "test" || env?.NODE_ENV === "development" || env?.ATSCRIPT_DB_FREEZE_META === "1";
+	}
+	return freezeServed;
+}
+/**
+* Deep-freezes `obj` in dev / test (see {@link shouldFreeze}); a no-op
+* otherwise. For objects shared across requests (served `/meta` payloads,
+* memoized projections), which must never be mutated.
+*/
+function freezeShared(obj) {
+	if (!shouldFreeze()) return;
+	deepFreeze(obj);
+}
+function deepFreeze(value) {
+	if (value === null || typeof value !== "object" || deepFrozen.has(value)) return;
+	deepFrozen.add(value);
+	Object.freeze(value);
+	for (const key of Object.keys(value)) deepFreeze(value[key]);
+}
+//#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. */
@@ -2516,7 +2720,11 @@ function __decorateParam(paramIndex, decorator) {
 }
 //#endregion
 //#region src/as-readable.controller.ts
-let AsReadableController = class AsReadableController {
+var _AsReadableController;
+const DEFAULT_META_CACHE_CONTROL = "private, no-cache";
+const DEFAULT_META_VARY = ["Authorization", "Cookie"];
+const readHttpResponse = () => (0, moost.current)().get(_moostjs_event_http.httpKind.keys.response);
+let AsReadableController = _AsReadableController = class AsReadableController {
 	/** The Atscript interface this controller serves. */
 	boundType;
 	/** Short human-readable name for logging (usually the table/source name). */
@@ -2538,6 +2746,12 @@ let AsReadableController = class AsReadableController {
 	/** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
 	_formSchemas = /* @__PURE__ */ new Map();
 	/**
+	* @internal Memoized `/meta` variants of this controller (own mount path,
+	* index visibility, decorations, delegated actions) — per input object, then
+	* per layer-prefixed key; see `meta/meta-cache.ts`.
+	*/
+	_metaVariants = /* @__PURE__ */ new WeakMap();
+	/**
 	* @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.
@@ -2822,10 +3036,56 @@ let AsReadableController = class AsReadableController {
 	* static envelope is cached (rebuilt when {@link metaCacheKey} changes);
 	* {@link applyMetaOverlay} runs per request so subclasses can prune the
 	* response by principal.
+	*
+	* Since 0.1.151 the response is HTTP-cacheable ({@link metaHttpCaching}):
+	* `Cache-Control: private, no-cache`, `Vary: Authorization, Cookie` and —
+	* when the payload is the same object as for an earlier request with the
+	* same inputs — a weak `ETag` computed from the serialized bytes, so a
+	* matching `If-None-Match` answers `304 Not Modified`. The JSON is then
+	* serialized once, not per request.
 	*/
 	async meta() {
 		await this.parseRequest("meta");
-		return this._withOwnHttpPath(await this.resolveMeta());
+		return this._serveMeta(this._withOwnHttpPath(await this.resolveMeta()), this.meta === _AsReadableController.prototype.meta);
+	}
+	/**
+	* HTTP caching of `GET /meta` and `GET /meta/form/:name` (since 0.1.151).
+	* Default `{}`: `Cache-Control: private, no-cache` (kept when the response
+	* already carries one), `Vary: Authorization, Cookie` (merged into an
+	* existing `Vary`), and a weak `ETag` from the response bytes with `304`
+	* on a matching `If-None-Match`. Return `false` to send none of it (the
+	* pre-0.1.151 response), or override the header values — e.g.
+	* `{ cacheControl: "no-store" }` for deployments where no browser may keep
+	* a copy.
+	*
+	* The `ETag` is a hash of the final bytes, computed after every overlay:
+	* a request whose principal sees a different `/meta` gets a different tag
+	* (a `200`), so a `304` only ever confirms the bytes the client already
+	* holds. A refused request (`prepareRequest` throwing) is answered with its
+	* error, never `304`.
+	*/
+	metaHttpCaching() {
+		return {};
+	}
+	/**
+	* Applies {@link metaHttpCaching} to the current response and — when `body`
+	* is identity-stable (a cached / memoized object) — registers it for
+	* prerendering with an ETag (deep-frozen in dev / test).
+	*/
+	_serveMeta(body, prerender = true) {
+		const caching = this.metaHttpCaching();
+		if (caching === false) return isStableMeta(body) ? { ...body } : body;
+		let response;
+		try {
+			response = readHttpResponse();
+		} catch {}
+		if (!response) return body;
+		applyMetaHeaders(response, caching);
+		if (prerender && isStableMeta(body)) {
+			freezeShared(body);
+			(0, _moostjs_event_http.prerenderJson)(body, { etag: true });
+		}
+		return body;
 	}
 	/**
 	* The root of a controller's own `/meta` carries its own mount as
@@ -2835,7 +3095,6 @@ let AsReadableController = class AsReadableController {
 	* cached envelope.
 	*/
 	_withOwnHttpPath(meta) {
-		const KEY = "db.http.path";
 		let prefix;
 		try {
 			prefix = (0, moost.useControllerContext)().getPrefix();
@@ -2845,6 +3104,11 @@ let AsReadableController = class AsReadableController {
 		if (prefix === void 0 || prefix === null) return meta;
 		const own = normalizeHttpPath(prefix);
 		if (isParametricPath(own)) return meta;
+		return this.getSerializeOptions === _AsReadableController.prototype.getSerializeOptions ? metaVariant(this._metaVariants, meta, `o:${own}`, () => this._ownHttpPathOf(meta, own)) : this._ownHttpPathOf(meta, own);
+	}
+	/** {@link _withOwnHttpPath} for the mount `own`. */
+	_ownHttpPathOf(meta, own) {
+		const KEY = "db.http.path";
 		const options = this.getSerializeOptions();
 		if (options.ignoreAnnotations?.includes(KEY)) return meta;
 		let key = KEY;
@@ -2889,7 +3153,7 @@ let AsReadableController = class AsReadableController {
 			this.enterScope(scope);
 			const key = this.metaCacheKey();
 			if (!this._metaResponse || key !== this._metaResponseKey) {
-				this._metaResponse = this.buildScoped(scope, () => this.buildMetaResponse());
+				this._metaResponse = markStableMeta(this.buildScoped(scope, () => this.buildMetaResponse()));
 				this._metaResponseKey = key;
 			}
 			return this.applyMetaOverlay(this._metaResponse);
@@ -2922,10 +3186,10 @@ let AsReadableController = class AsReadableController {
 		this.enterScope(scope);
 		let cached = this._formSchemas.get(name);
 		if (!cached) {
-			cached = this.buildScoped(scope, () => this.serializeForMeta(formType));
+			cached = markStableMeta(this.buildScoped(scope, () => this.serializeForMeta(formType)));
 			this._formSchemas.set(name, cached);
 		}
-		return cached;
+		return this._serveMeta(cached);
 	}
 	/**
 	* Per-request gate for `GET /meta/form/:name`: return `false` to refuse the
@@ -2982,6 +3246,12 @@ let AsReadableController = class AsReadableController {
 	* composables). The cached envelope MUST NOT be mutated — see
 	* `docs/http/permissions.md` for the full contract, including the
 	* "discoverability only" caveat.
+	*
+	* `/meta`'s serialize-once memo and `ETag` (since 0.1.151) need a stable
+	* object: return the envelope itself when nothing changes, or memoize your
+	* outputs and return them through `stableMeta()` (deep-freezes and marks
+	* them) — never mutate one afterwards. A fresh object per request is
+	* correct, just served without an `ETag`.
 	*/
 	applyMetaOverlay(meta) {
 		return meta;
@@ -3000,13 +3270,36 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [String]),
 	__decorateMetadata("design:returntype", Promise)
 ], AsReadableController.prototype, "metaForm", null);
-AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMetadata("design:paramtypes", [
+AsReadableController = _AsReadableController = __decorate([UseValidationErrorTransform(), __decorateMetadata("design:paramtypes", [
 	Object,
 	String,
 	typeof moost.Moost === "undefined" ? Object : moost.Moost,
 	Object,
 	Object
 ])], AsReadableController);
+/** Sets `/meta`'s `Cache-Control` (unless present) and merges its `Vary` tokens. */
+function applyMetaHeaders(response, caching) {
+	const headers = response.headers();
+	let cacheControlSet = false;
+	let varyKey = "vary";
+	for (const key in headers) {
+		const lower = key.toLowerCase();
+		if (lower === "cache-control") cacheControlSet = true;
+		else if (lower === "vary") varyKey = key;
+	}
+	if (!cacheControlSet) response.setHeader("cache-control", caching.cacheControl ?? DEFAULT_META_CACHE_CONTROL);
+	const wanted = caching.vary ?? DEFAULT_META_VARY;
+	if (wanted.length === 0) return;
+	const existing = headers[varyKey];
+	const tokens = (Array.isArray(existing) ? existing.join(",") : existing ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+	if (tokens.includes("*")) return;
+	const seen = new Set(tokens.map((t) => t.toLowerCase()));
+	for (const token of wanted) if (!seen.has(token.toLowerCase())) {
+		seen.add(token.toLowerCase());
+		tokens.push(token);
+	}
+	response.setHeader(varyKey, tokens.join(", "));
+}
 //#endregion
 //#region src/actions/verdict.ts
 /** Assert that a `disabled` predicate returned an array of the expected length; throws HTTP 500 otherwise. */
@@ -3069,7 +3362,8 @@ function computeStripFields(candidates, resolvedProjection) {
 /**
 * Sets `$actions` on every row (plus `$disabledReasons` on rows where a
 * predicate returned a reason string) and strips the columns fetched only for an
-* action's `requiredFields` — IN PLACE; returns the same array, typed as
+* action's `requiredFields` — IN PLACE in `rows` (a stripped row is replaced
+* by a rebuilt copy, see `omitKeys`); returns the same array, typed as
 * augmented.
 */
 function augmentRowsWithActions(args) {
@@ -3079,7 +3373,11 @@ function augmentRowsWithActions(args) {
 	const verdicts = candidates.map((c) => {
 		if (!c.disabledFn) return void 0;
 		const fields = gateFields?.(c.envelope);
-		const input = fields && rows.some((row) => exceedsFields(row, fields)) ? rows.map((row) => projectRow$2(row, fields)) : rows;
+		let input = rows;
+		if (fields && rows.some((row) => exceedsFields(row, fields))) {
+			const paths = splitPaths(fields);
+			input = rows.map((row) => projectRow$2(row, paths));
+		}
 		return judgeRows(c.envelope.info.name, c.disabledFn, input);
 	});
 	const masks = outOfScope && candidates.map((c) => outOfScope.get(c.envelope.info.name));
@@ -3103,7 +3401,11 @@ function augmentRowsWithActions(args) {
 	}
 	if (resolvedProjection !== null) {
 		const stripFields = computeStripFields(candidates, resolvedProjection);
-		if (stripFields !== null) for (const row of rows) for (const f of stripFields) delete row[f];
+		if (stripFields !== null) for (let i = 0; i < rows.length; i++) {
+			const row = rows[i];
+			if ((0, _atscript_db.isPlainObject)(row)) rows[i] = omitKeys(row, stripFields);
+			else for (const key of stripFields) delete row[key];
+		}
 	}
 	return rows;
 }
@@ -4186,7 +4488,7 @@ function buildDecorationIndex(controller, meta, source) {
 		requires,
 		visibleOn,
 		leavesOf,
-		memo: { meta: /* @__PURE__ */ new WeakMap() }
+		memo: {}
 	};
 }
 //#endregion
@@ -4377,45 +4679,46 @@ var DecorationPlanner = class {
 	* `fields[key]` entry (from its virtual capability-index entry); the others
 	* are pruned, and `decorations` is dropped when none is left. Runs after
 	* `applyMetaOverlay` — an overlay never sees the decoration `fields`
-	* entries. Memoized per input while visibility is not request-scoped.
+	* entries. Memoized per input and per the request's decoration visibility.
 	*/
 	meta(meta) {
-		if (!meta.decorations) return meta;
-		const { memo, keySet } = this.index;
-		const memoize = !this.host.scoped;
-		const hit = memoize ? memo.meta.get(meta) : void 0;
-		if (hit) return hit;
+		const decorations = meta.decorations;
+		if (!decorations) return meta;
+		const { keySet } = this.index;
 		const capabilities = this.host.capabilities();
-		const props = meta.decorations.type.props ?? {};
-		const kept = {};
-		const fields = { ...meta.fields };
-		for (const [key, prop] of Object.entries(props)) {
-			const cap = keySet.has(key) && this.visible(key) ? capabilities.decorationCap(key) : void 0;
-			if (!cap) continue;
-			kept[key] = prop;
-			fields[key] = {
-				sortable: cap.sortable,
-				filterable: cap.filterable,
-				decoration: true
-			};
-		}
-		let out;
-		if (Object.keys(kept).length === 0) {
-			const { decorations: _dropped, ...rest } = meta;
-			out = rest;
-		} else out = {
-			...meta,
-			fields,
-			decorations: {
-				...meta.decorations,
-				type: {
-					...meta.decorations.type,
-					props: kept
-				}
+		const props = decorations.type.props ?? {};
+		const entries = Object.entries(props);
+		const visible = entries.map(([key]) => keySet.has(key) && this.visible(key));
+		return metaVariant(this.host.metaVariants, meta, `p:${identityId(capabilities)}:${bits(visible)}`, () => {
+			const kept = {};
+			const fields = { ...meta.fields };
+			for (let i = 0; i < entries.length; i++) {
+				const [key, prop] = entries[i];
+				const cap = visible[i] ? capabilities.decorationCap(key) : void 0;
+				if (!cap) continue;
+				kept[key] = prop;
+				fields[key] = {
+					sortable: cap.sortable,
+					filterable: cap.filterable,
+					decoration: true
+				};
 			}
-		};
-		if (memoize) memo.meta.set(meta, out);
-		return out;
+			if (Object.keys(kept).length === 0) {
+				const { decorations: _dropped, ...rest } = meta;
+				return rest;
+			}
+			return {
+				...meta,
+				fields,
+				decorations: {
+					...decorations,
+					type: {
+						...decorations.type,
+						props: kept
+					}
+				}
+			};
+		});
 	}
 	/** The declared interface serialized for `/meta.decorations`, once per class and app scope. */
 	serialized(scope, serialize) {
@@ -4427,18 +4730,31 @@ var DecorationPlanner = class {
 		return memo.serialized;
 	}
 };
-/** Removes what a read must not carry — the unserved declared keys and the hook-only paths — from `rows`. */
+/**
+* Removes what a read must not carry — the unserved declared keys and the
+* hook-only paths — from `rows`, in place in the array: a row losing a
+* top-level key is replaced by a rebuilt copy (`omitKeys`); nested paths are
+* deleted inside it.
+*/
 function stripDecorations(rows, read) {
 	const { dropKeys, dropPaths, keepPaths, selectedPaths } = read;
 	if (dropKeys.length === 0 && dropPaths.length === 0) return;
 	const owned = (prefix) => selectedPaths !== void 0 && selectedPaths.some((sel) => prefix.every((part, i) => sel[i] === part));
-	for (const row of rows) {
-		for (const key of dropKeys) delete row[key];
-		dropPaths.forEach((parts, i) => {
+	const topLevel = new Set(dropKeys);
+	const nested = [];
+	dropPaths.forEach((parts, i) => {
+		if (parts.length === 1 && (keepPaths[i] ?? []).length === 0) topLevel.add(parts[0]);
+		else nested.push(i);
+	});
+	for (let r = 0; r < rows.length; r++) {
+		let row = rows[r];
+		if ((0, _atscript_db.isPlainObject)(row)) row = rows[r] = omitKeys(row, topLevel);
+		else for (const key of dropKeys) delete row[key];
+		for (const i of nested) {
 			const keep = keepPaths[i] ?? [];
-			if (keep.length === 0) deleteDescending(row, parts, 0, selectedPaths !== void 0, owned);
-			else pruneExcept(row, parts, 0, keep);
-		});
+			if (keep.length === 0) deleteDescending(row, dropPaths[i], 0, selectedPaths !== void 0, owned);
+			else pruneExcept(row, dropPaths[i], 0, keep);
+		}
 	}
 }
 /** An object without keys, or an array (of any nesting) holding nothing but such values (what a strip left of a parent). */
@@ -4561,6 +4877,15 @@ function routedController(ctx) {
 		return controllerOf(c);
 	}
 }
+/**
+* `collectQueryPaths`' aggregate flag for a parsed query: `true` when its
+* `$select` carries computed entries (aggregates, calendar buckets), else
+* `undefined` (aggregate mode iff `$groupBy`).
+*/
+function computedMode(parsed) {
+	const select = parsed.controls?.$select;
+	return Array.isArray(select) && select.some((item) => typeof item !== "string") || void 0;
+}
 /** The 400 of a filter / sort on a `@db.writeOnly` field. */
 function writeOnlyError(path, op) {
 	const verdict = writeOnlyVerdict(path, op);
@@ -4601,13 +4926,34 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	* would keep advertising (and gating) the pre-sync answer (since 0.1.132).
 	*/
 	get capabilities() {
+		const readable = this.readable;
+		const geo = readable.isGeoSearchable();
+		const units = readable.calendarBucketUnits();
+		const fns = readable.aggregateFns();
+		const expr = readable.supportsAggregateExpressions();
 		const current = this._capabilities;
-		if (current && current.signature === FieldCapabilityIndex.adapterSignature(this.readable)) return current;
-		const index = new FieldCapabilityIndex(this.readable, this._writeOnlySet, this._decorations?.visibleOn);
+		const seen = this._capabilityInputs;
+		if (current && seen && seen.geo === geo && seen.units === units && seen.unitsSize === units.size && seen.fns === fns && seen.fnsSize === fns.size && seen.expr === expr) return current;
+		const inputs = {
+			geo,
+			units,
+			unitsSize: units.size,
+			fns,
+			fnsSize: fns.size,
+			expr
+		};
+		if (current && current.signature === FieldCapabilityIndex.adapterSignature(readable)) {
+			this._capabilityInputs = inputs;
+			return current;
+		}
+		const index = new FieldCapabilityIndex(readable, this._writeOnlySet, this._decorations?.visibleOn);
 		this._capabilities = index;
+		this._capabilityInputs = inputs;
 		return index;
 	}
 	_capabilities;
+	/** The adapter answers {@link capabilities} last confirmed its index against (identity fast path). */
+	_capabilityInputs;
 	/** The client relational-predicate gate (since 0.1.147), built on first use — see {@link _relationGate}. */
 	_relGate;
 	/**
@@ -4640,6 +4986,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_derivedSource;
 	/** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
 	_targetWriteOnly = /* @__PURE__ */ new WeakMap();
+	/** The forced exclusion `$select` per sealed set (see {@link _sealSelect}). */
+	_exclusionBySealed = /* @__PURE__ */ new WeakMap();
+	/** The objects of {@link _exclusionBySealed}. */
+	_forcedExclusions = /* @__PURE__ */ new WeakSet();
+	/** {@link widenPreferredIdProjection} of each forced exclusion. */
+	_widenedExclusions = /* @__PURE__ */ new WeakMap();
 	/** Own leaf paths per readable (bound + `$with` targets), see {@link _leavesOf}. */
 	_targetLeaves = /* @__PURE__ */ new WeakMap();
 	_indexFieldPathsCache;
@@ -4725,7 +5077,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		this._idOpts = scoped ? { isFieldVisible: isVisible } : void 0;
 		this._planner = this._decorations && new DecorationPlanner(this._decorations, {
 			isVisible,
-			scoped,
+			metaVariants: this._metaVariants,
 			preferred: this._preferredIdSet,
 			capabilities: () => this.capabilities,
 			firstVisibleField: () => this._invertibleFields.find((path) => isVisible(path))
@@ -4871,8 +5223,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	checkCapabilities(parsed) {
 		const capabilities = this.capabilities;
 		const isVisible = this.fieldVisibility.isVisible;
-		const select = parsed.controls?.$select;
-		const refs = (0, _atscript_db.collectQueryPaths)(parsed, Array.isArray(select) && select.some((item) => typeof item !== "string") || void 0);
+		const shared = this._sharedRefs;
+		const refs = shared?.parsed === parsed ? shared.refs : (0, _atscript_db.collectQueryPaths)(parsed, computedMode(parsed));
 		if (refs.unsupportedOperator !== void 0) return badRequest(refs.unsupportedOperator, (0, _atscript_db.unsupportedOperatorMessage)(refs.unsupportedOperator));
 		const relState = { nodes: 0 };
 		for (const ref of refs.filter) {
@@ -4899,6 +5251,21 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (having) return badRequest(having.path, having.message);
 		return this.checkGates(parsed) ?? this._checkIndexGate(parsed.controls ?? {});
 	}
+	/** {@link checkCapabilities} reusing `refs` (the walk it makes) when the method is not overridden. */
+	_checkCapabilitiesWith(parsed, refs) {
+		if (this.checkCapabilities !== _AsDbReadableController.prototype.checkCapabilities) return this.checkCapabilities(parsed);
+		this._sharedRefs = {
+			parsed,
+			refs
+		};
+		try {
+			return this.checkCapabilities(parsed);
+		} finally {
+			this._sharedRefs = void 0;
+		}
+	}
+	/** The walk of the `parsed` in flight, handed to {@link checkCapabilities} (sync, cleared after). */
+	_sharedRefs;
 	/**
 	* The core's shared normalizer of `$select` computed entries
 	* (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
@@ -5237,15 +5604,22 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_applyIndexVisibility(meta) {
 		if (!this._indexGateActive) return meta;
 		const entries = this.indexFieldPaths();
+		const indexVisible = entries.map((e) => this._indexVisible(e));
+		const isSearchable = this.readable.isSearchable();
+		const fallbackVisible = isSearchable ? [] : this._searchFallbackFields.map((f) => this.fieldVisibility.isVisible(f));
+		return metaVariant(this._metaVariants, meta, `i:${bits(indexVisible)}:${isSearchable ? 1 : 0}:${bits(fallbackVisible)}`, () => this._narrowIndexVisibility(meta, entries, indexVisible, isSearchable, fallbackVisible));
+	}
+	/** {@link _applyIndexVisibility} for the given answers. */
+	_narrowIndexVisibility(meta, entries, indexVisible, isSearchable, fallbackVisible) {
 		const visibleDefault = (type) => {
-			const def = entries.find((e) => e.type === type && e.isDefault);
-			return def !== void 0 && this._indexVisible(def);
+			const at = entries.findIndex((e) => e.type === type && e.isDefault);
+			return at >= 0 && indexVisible[at];
 		};
 		const has = (type) => entries.some((e) => e.type === type);
-		const anyVisible = (type) => entries.some((e) => e.type === type && this._indexVisible(e));
-		const hidden = new Set(entries.filter((e) => e.type !== "geo" && !this._indexVisible(e)).map((e) => e.name));
-		const searchable = this.readable.isSearchable() ? visibleDefault("text") : this._searchFallbackFields.some((f) => this.fieldVisibility.isVisible(f));
-		const textUsable = searchable || this.readable.isSearchable() && anyVisible("text");
+		const anyVisible = (type) => entries.some((e, i) => e.type === type && indexVisible[i]);
+		const hidden = new Set(entries.filter((e, i) => e.type !== "geo" && !indexVisible[i]).map((e) => e.name));
+		const searchable = isSearchable ? visibleDefault("text") : fallbackVisible.some(Boolean);
+		const textUsable = searchable || isSearchable && anyVisible("text");
 		const vectorUsable = anyVisible("vector");
 		const unusable = /* @__PURE__ */ new Set();
 		if (has("text") && !anyVisible("text")) unusable.add("index");
@@ -5479,7 +5853,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		const transformed = await this.transformProjection(plan ? plan.select : controls.$select);
 		const sealed = this._sealControls(controls, transformed);
 		const finish = () => {
-			const select = this.widenPreferredIdProjection(sealed.$select);
+			const select = this._widenSealed(sealed.$select);
 			if (select instanceof _moostjs_event_http.HttpError) return select;
 			let kept;
 			const keptPaths = () => kept === void 0 ? kept = this._resolveProjectionForAugmenter(select) : kept;
@@ -5494,6 +5868,23 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			finish
 		};
 	}
+	/**
+	* {@link widenPreferredIdProjection} of a sealed `$select` — memoized for the
+	* forced exclusion of a read without `$select` (one object per sealed set,
+	* see {@link _sealSelect}): its widening depends on the controller alone.
+	*/
+	_widenSealed(select) {
+		if (select === void 0 || !this._forcedExclusions.has(select)) return this.widenPreferredIdProjection(select);
+		let widened = this._widenedExclusions.get(select);
+		if (widened === void 0) {
+			const out = this.widenPreferredIdProjection(select);
+			if (out instanceof _moostjs_event_http.HttpError) return out;
+			if (out !== void 0 && out !== select) freezeShared(out);
+			this._widenedExclusions.set(select, out);
+			widened = out;
+		}
+		return widened;
+	}
 	widenPreferredIdProjection(projection) {
 		const widened = this.widenQuantityRefProjection(projection);
 		if (widened instanceof _moostjs_event_http.HttpError) return widened;
@@ -5821,7 +6212,15 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 					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));
+				const pathsByShape = /* @__PURE__ */ new Map();
+				const pathsOf = (id) => {
+					const keys = Object.keys(id);
+					const shape = keys.join("");
+					let paths = pathsByShape.get(shape);
+					if (!paths) pathsByShape.set(shape, paths = splitPaths(new Set([...fields, ...keys])));
+					return paths;
+				};
+				return Promise.resolve(alignRowsToIds(rows, ids).map((row, i) => row ? projectRow$2(row, pathsOf(ids[i])) : void 0));
 			}
 		};
 	}
@@ -6004,7 +6403,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			sortGate: ids.length > 0 ? void 0 : order,
 			routeParams: sameRoute ? void 0 : {}
 		});
-		return rows.map((row) => projectRow$2(row, sealedSelect));
+		const paths = splitPaths(sealedSelect);
+		return rows.map((row) => projectRow$2(row, paths));
 	}
 	/**
 	* Runs `fn` as a READ of this controller (since 0.1.147): in a child of
@@ -6048,8 +6448,18 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_sealSelect(select, writeOnly, readable) {
 		if (writeOnly.size === 0) return select;
 		const exclusion = () => {
-			const out = {};
-			for (const f of writeOnly) out[f] = 0;
+			const shared = writeOnly === this._writeOnlySet || writeOnly === this._targetWriteOnly.get(readable);
+			let out = shared ? this._exclusionBySealed.get(writeOnly) : void 0;
+			if (out === void 0) {
+				const built = {};
+				for (const f of writeOnly) built[f] = 0;
+				out = built;
+				if (shared) {
+					freezeShared(out);
+					this._exclusionBySealed.set(writeOnly, out);
+					this._forcedExclusions.add(out);
+				}
+			}
 			return out;
 		};
 		if (select === void 0) return exclusion();
@@ -6321,10 +6731,11 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			const [overlaid, delegated] = await Promise.all([own, this._hasDelegations ? this._delegatedInfos() : []]);
 			const meta = this._planner ? this._planner.meta(overlaid) : overlaid;
 			const visible = this._applyIndexVisibility(meta);
-			return delegated.length > 0 ? {
+			if (delegated.length === 0) return visible;
+			return metaVariant(this._metaVariants, visible, `d:${delegated.map((info) => identityId(info)).join(",")}`, () => ({
 				...visible,
 				actions: [...visible.actions, ...delegated]
-			} : visible;
+			}));
 		})();
 	}
 	/**
@@ -6590,8 +7001,10 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		if (groupBy?.length && controls.$vector !== void 0) return new _moostjs_event_http.HttpError(400, "Cannot combine $vector and $groupBy in the same query");
 		const error = this.validateParsed(parsed, "query");
 		if (error) return error;
+		let gateRefs;
 		if (groupBy?.length && this._writeOnlySet.size > 0) {
-			const refs = (0, _atscript_db.collectQueryPaths)(parsed, true);
+			gateRefs = (0, _atscript_db.collectQueryPaths)(parsed, computedMode(parsed));
+			const refs = gateRefs.aggregateMode ? gateRefs : (0, _atscript_db.collectQueryPaths)(parsed, true);
 			const sealed = [
 				...refs.groupBy,
 				...refs.aggregate,
@@ -6601,7 +7014,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			].find((path) => this._writeOnlySet.has(path) && this.fieldVisibility.isVisible(path));
 			if (sealed) return new _moostjs_event_http.HttpError(400, `Field "${sealed}" is @db.writeOnly and cannot be aggregated`);
 		}
-		const gateError = this.checkCapabilities(parsed);
+		const gateError = gateRefs ? this._checkCapabilitiesWith(parsed, gateRefs) : this.checkCapabilities(parsed);
 		if (gateError) return gateError;
 		const clientFilter = await this._relationOverlay(parsed);
 		if (groupBy?.length) {
@@ -6793,14 +7206,15 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		};
 		const item = await this.returnOne(this._findRow(resolvedId, overlay, readControls));
 		if (item instanceof _moostjs_event_http.HttpError) return item;
-		const pending = this._finishRows([item], prep, {
+		const rows = [item];
+		const pending = this._finishRows(rows, prep, {
 			endpoint: "one",
 			projection: projected.select,
 			controls,
 			decorations: projected.read?.served ?? NO_DECORATIONS
 		}, projected.read);
 		if (pending) await pending;
-		return item;
+		return rows[0];
 	}
 	/**
 	* **GET /meta/actions/:id** — the row-level actions the caller may run on
@@ -7069,7 +7483,9 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		for (const row of rows) if (row) present.push(row);
 		const verdicts = envelopes.map((e, i) => {
 			const disabled = getCandidate(e)?.disabledFn;
-			return disabled && present.length > 0 ? judgeRows(e.info.name, disabled, present.map((row) => projectRow$2(row, fieldsOf[i]))) : void 0;
+			if (!disabled || present.length === 0) return void 0;
+			const paths = splitPaths(fieldsOf[i]);
+			return judgeRows(e.info.name, disabled, present.map((row) => projectRow$2(row, paths)));
 		});
 		let p = 0;
 		return rows.map((row, r) => {
@@ -7877,22 +8293,29 @@ let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueH
 	}
 	async query(controls) {
 		let rows = this.rows;
-		if (controls.filter && Object.keys(controls.filter).length > 0) {
-			const predicate = (0, _atscript_db_memory.buildMemoryPredicate)(controls.filter);
-			rows = rows.filter((row) => predicate(row));
-		}
 		const search = controls.controls.$search;
 		if (search) {
 			const needle = search.toLowerCase();
-			const fields = this.searchableFields.filter((field) => this.hasField(field));
-			rows = rows.filter((row) => {
-				for (const field of fields) {
+			const columns = this.searchableFields.filter((field) => this.hasField(field)).map((field) => [field, this._lowercased(field)]);
+			rows = rows.filter((row, i) => {
+				for (const [field, column] of columns) {
 					const v = row[field];
-					if (typeof v === "string" && v.toLowerCase().includes(needle)) return true;
+					if (typeof v !== "string") continue;
+					let lower = column.lower[i];
+					if (lower === void 0 || column.src[i] !== v) {
+						lower = v.toLowerCase();
+						column.src[i] = v;
+						column.lower[i] = lower;
+					}
+					if (lower.includes(needle)) return true;
 				}
 				return false;
 			});
 		}
+		if (controls.filter && Object.keys(controls.filter).length > 0) {
+			const predicate = (0, _atscript_db_memory.buildMemoryPredicate)(controls.filter);
+			rows = rows.filter((row) => predicate(row));
+		}
 		const sort = this.normalizeSort(controls.controls.$sort);
 		if (sort) rows = (0, _atscript_db_memory.sortRows)(rows, sort);
 		const total = rows.length;
@@ -7905,6 +8328,25 @@ let AsJsonValueHelpController = class AsJsonValueHelpController extends AsValueH
 			count: total
 		};
 	}
+	/**
+	* `field`'s lowercased values by position in {@link rows} (the `$search`
+	* haystack). An entry is used only while the row still holds the value it
+	* was lowercased from (`src`), so rows edited in place stay correct.
+	*/
+	_lowercased(field) {
+		let haystack = this._haystack;
+		if (haystack?.rows !== this.rows) haystack = this._haystack = {
+			rows: this.rows,
+			byField: /* @__PURE__ */ new Map()
+		};
+		let column = haystack.byField.get(field);
+		if (!column) haystack.byField.set(field, column = {
+			src: [],
+			lower: []
+		});
+		return column;
+	}
+	_haystack;
 	async getOne(id) {
 		return this._pkIndex?.get(String(id)) ?? null;
 	}
@@ -8786,6 +9228,7 @@ exports.resolveBoundReadable = resolveBoundReadable;
 exports.resolveDbSpace = require_db_space_registry.resolveDbSpace;
 exports.resolveProp = resolveProp;
 exports.resolveTerminalRef = resolveTerminalRef;
+exports.stableMeta = stableMeta;
 exports.unknownRelationError = unknownRelationError;
 exports.useDbActionId = useDbActionId;
 exports.useDbActionIds = useDbActionIds;