@aooth/arbac-moost 0.1.77 → 0.1.78

package/dist/atscript/index.d.mts

@@ -32,6 +32,61 @@ interface ArbacUserTable<T extends object> {
     };
   }): Promise<T | null>;
 }
+/** Options of {@link AtscriptArbacUserProvider}. @since 0.1.78 */
+interface AtscriptArbacUserProviderOptions {
+  /**
+   * Extra user fields to select in the provider's single per-event user
+   * fetch, next to the id, `@arbac.role` and `@arbac.attribute` fields — read
+   * them in an `extractAttrs` / `extractRoles` override instead of fetching
+   * the user a second time (e.g. a `username` that scope functions need but
+   * that cannot carry `@arbac.attribute`).
+   */
+  extraSelect?: readonly string[];
+  /**
+   * OPT-IN cross-request cache of the fetched user record (roles + attrs),
+   * see {@link ArbacUserRecordCache}. Off by default: without it every
+   * request reads the user once.
+   */
+  cache?: ArbacUserRecordCache;
+}
+/** Options of {@link ArbacUserRecordCache}. @since 0.1.78 */
+interface ArbacUserRecordCacheOptions {
+  /** How long a fetched record is reused, in ms (keep it short — seconds). */
+  ttlMs: number;
+  /** Most cached users; the oldest entry is dropped past it. Default 1000. */
+  max?: number;
+  /** Clock (ms) — for tests. Default `Date.now`. */
+  now?: () => number;
+}
+/**
+ * OPT-IN, process-local cache of the user records an
+ * {@link AtscriptArbacUserProvider} fetches for ARBAC (`userId` → roles +
+ * attributes), shared across requests for `ttlMs`. Pass it as the provider's
+ * `cache` option; off by default.
+ *
+ * Staleness: a role or attribute change reaches ARBAC within `ttlMs` — or
+ * immediately on THIS process when you call {@link invalidate} (wire it to
+ * your user writes, e.g. `userService.onUserWrite((id) => cache.invalidate(id))`).
+ * Other processes keep their entry until it expires, so the cross-node lag is
+ * at most `ttlMs`. Only the stored record is cached: credential attenuation
+ * (read from the token per request) and every policy evaluation still run
+ * per request. A missing user is never cached.
+ *
+ * @since 0.1.78
+ */
+declare class ArbacUserRecordCache {
+  private readonly ttlMs;
+  private readonly max;
+  private readonly now;
+  private readonly entries;
+  constructor(opts: ArbacUserRecordCacheOptions);
+  /** Drop the cached record of `userId` (all users when omitted). */
+  invalidate(userId?: string): void;
+  /** @internal The live record cached for `owner` (a provider), if any. */
+  get(owner: object, userId: string): Promise<unknown> | undefined;
+  /** @internal Cache `record` (dropped again if it rejects or resolves to `null`). */
+  set(owner: object, userId: string, record: Promise<unknown>): void;
+}
 /**
  * `@Injectable()` (SINGLETON) — moost@0.6.x's `Injectable` metadata is NOT
  * inherited from the base `ArbacUserProvider` by infact, so the decorator
@@ -44,7 +99,9 @@ interface ArbacUserTable<T extends object> {
  * table, and register the subclass via `setReplaceRegistry`.
  *
  * `extractRoles` and `extractAttrs` are protected seams — override to
- * reshape roles/attrs without re-implementing the fetch path.
+ * reshape roles/attrs without re-implementing the fetch path; pass
+ * `extraSelect` (third constructor argument) to have the fetch include the
+ * extra fields they read.
  */
 declare abstract class AtscriptArbacUserProvider<T extends object = object> extends ArbacUserProvider {
   protected readonly userType: TAtscriptAnnotatedType;
@@ -52,7 +109,8 @@ declare abstract class AtscriptArbacUserProvider<T extends object = object> exte
   private readonly spec;
   private readonly projection;
   private readonly withClause;
-  constructor(userType: TAtscriptAnnotatedType, table: ArbacUserTable<T>);
+  private readonly recordCache;
+  constructor(userType: TAtscriptAnnotatedType, table: ArbacUserTable<T>, options?: AtscriptArbacUserProviderOptions);
   abstract getUserId(): string | Promise<string>;
   getRoles(id: string): Promise<string[]>;
   getAttrs(id: string): Promise<object>;
@@ -233,4 +291,4 @@ declare class AoothArbacUserCredentials extends AoothUserCredentials {
 }
 // prettier-ignore-end
 //#endregion
-export { AoothArbacUserCredentials, type AoothCredentialMetadataSpec, type AoothUserHandleSpec, type ArbacAttenuationSpec, type ArbacUserTable, AtscriptArbacUserProvider, extractAttenuation, getAoothCredentialMetadataSpec, getAoothUserHandleSpec, getArbacAttenuationSpec, validateAttenuationTargets };
+export { AoothArbacUserCredentials, type AoothCredentialMetadataSpec, type AoothUserHandleSpec, type ArbacAttenuationSpec, ArbacUserRecordCache, type ArbacUserRecordCacheOptions, type ArbacUserTable, AtscriptArbacUserProvider, type AtscriptArbacUserProviderOptions, extractAttenuation, getAoothCredentialMetadataSpec, getAoothUserHandleSpec, getArbacAttenuationSpec, validateAttenuationTargets };

package/dist/atscript/index.mjs

@@ -141,20 +141,88 @@ const useFetchCache = defineWook((ctx) => {
 	}
 	return cache;
 });
+/**
+* OPT-IN, process-local cache of the user records an
+* {@link AtscriptArbacUserProvider} fetches for ARBAC (`userId` → roles +
+* attributes), shared across requests for `ttlMs`. Pass it as the provider's
+* `cache` option; off by default.
+*
+* Staleness: a role or attribute change reaches ARBAC within `ttlMs` — or
+* immediately on THIS process when you call {@link invalidate} (wire it to
+* your user writes, e.g. `userService.onUserWrite((id) => cache.invalidate(id))`).
+* Other processes keep their entry until it expires, so the cross-node lag is
+* at most `ttlMs`. Only the stored record is cached: credential attenuation
+* (read from the token per request) and every policy evaluation still run
+* per request. A missing user is never cached.
+*
+* @since 0.1.78
+*/
+var ArbacUserRecordCache = class {
+	ttlMs;
+	max;
+	now;
+	entries = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		if (!(opts.ttlMs > 0)) throw new Error("ArbacUserRecordCache: ttlMs must be > 0");
+		this.ttlMs = opts.ttlMs;
+		this.max = opts.max ?? 1e3;
+		this.now = opts.now ?? Date.now;
+	}
+	/** Drop the cached record of `userId` (all users when omitted). */
+	invalidate(userId) {
+		if (userId === void 0) this.entries.clear();
+		else this.entries.delete(userId);
+	}
+	/** @internal The live record cached for `owner` (a provider), if any. */
+	get(owner, userId) {
+		const entry = this.entries.get(userId);
+		if (!entry) return void 0;
+		if (entry.owner !== owner || entry.expiresAt <= this.now()) {
+			this.entries.delete(userId);
+			return;
+		}
+		return entry.record;
+	}
+	/** @internal Cache `record` (dropped again if it rejects or resolves to `null`). */
+	set(owner, userId, record) {
+		this.entries.delete(userId);
+		if (this.entries.size >= this.max) {
+			const oldest = this.entries.keys().next();
+			if (!oldest.done) this.entries.delete(oldest.value);
+		}
+		const entry = {
+			owner,
+			expiresAt: this.now() + this.ttlMs,
+			record
+		};
+		this.entries.set(userId, entry);
+		const drop = () => {
+			if (this.entries.get(userId) === entry) this.entries.delete(userId);
+		};
+		record.then((r) => r === null && drop(), drop);
+	}
+};
 let AtscriptArbacUserProvider = class AtscriptArbacUserProvider extends ArbacUserProvider {
 	userType;
 	table;
 	spec;
 	projection;
 	withClause;
-	constructor(userType, table) {
+	recordCache;
+	constructor(userType, table, options) {
 		super();
 		this.userType = userType;
 		this.table = table;
 		this.spec = getArbacExtractSpec(userType);
 		if (!this.spec.userIdField) throw new Error("AtscriptArbacUserProvider: userType has no @arbac.userId, @db.table.preferredId.uniqueIndex field, or @meta.id — annotate one to identify users");
-		this.projection = getArbacProjection(userType);
+		const projection = getArbacProjection(userType);
+		const extra = options?.extraSelect?.filter((f) => !Object.hasOwn(projection, f)) ?? [];
+		this.projection = extra.length > 0 ? {
+			...projection,
+			...Object.fromEntries(extra.map((f) => [f, 1]))
+		} : projection;
 		this.withClause = this.spec.roleField?.shape === "rel.from" ? [{ name: this.spec.roleField.name }] : void 0;
+		this.recordCache = options?.cache;
 	}
 	async getRoles(id) {
 		const record = await this.fetchRecord(id);
@@ -217,6 +285,11 @@ let AtscriptArbacUserProvider = class AtscriptArbacUserProvider extends ArbacUse
 		}
 		const cached = perProvider.get(userId);
 		if (cached !== void 0) return cached;
+		const shared = this.recordCache?.get(this, userId);
+		if (shared !== void 0) {
+			perProvider.set(userId, shared);
+			return shared;
+		}
 		const userIdField = this.spec.userIdField;
 		const controls = { $select: this.projection };
 		if (this.withClause) controls.$with = this.withClause;
@@ -226,10 +299,15 @@ let AtscriptArbacUserProvider = class AtscriptArbacUserProvider extends ArbacUse
 		});
 		promise.catch(() => perProvider?.delete(userId));
 		perProvider.set(userId, promise);
+		this.recordCache?.set(this, userId, promise);
 		return promise;
 	}
 };
-AtscriptArbacUserProvider = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [Object, Object])], AtscriptArbacUserProvider);
+AtscriptArbacUserProvider = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [
+	Object,
+	Object,
+	Object
+])], AtscriptArbacUserProvider);
 //#endregion
 //#region src/atscript/attenuation-extract.ts
 const specCache$2 = /* @__PURE__ */ new WeakMap();
@@ -439,4 +517,4 @@ var AoothArbacUserCredentials = class {
 };
 defineAnnotatedType("object", AoothArbacUserCredentials).prop("id", defineAnnotatedType().designType("string").tags("string").annotate("meta.id", true).annotate("db.default.uuid", true).$type).prop("username", defineAnnotatedType().designType("string").tags("string").annotate("db.index.unique", "username_idx", true).$type).prop("version", defineAnnotatedType().designType("number").tags("int", "number").annotate("db.column.version", true).annotate("expect.int", true).$type).prop("password", defineAnnotatedType("object").prop("hash", defineAnnotatedType().designType("string").tags("string").$type).prop("history", defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).$type).prop("lastChanged", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("isInitial", defineAnnotatedType().designType("boolean").tags("boolean").$type).annotate("db.patch.strategy", "merge").$type).prop("account", defineAnnotatedType("object").prop("active", defineAnnotatedType().designType("boolean").tags("boolean").$type).prop("locked", defineAnnotatedType().designType("boolean").tags("boolean").$type).prop("lockReason", defineAnnotatedType().designType("string").tags("string").$type).prop("lockEnds", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("failedLoginAttempts", defineAnnotatedType().designType("number").tags("number").$type).prop("lastLogin", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("pendingInvitation", defineAnnotatedType().designType("boolean").tags("boolean").optional().$type).prop("verifiedEmail", defineAnnotatedType().designType("string").tags("string").optional().$type).annotate("db.patch.strategy", "merge").$type).prop("mfa", defineAnnotatedType("object").prop("methods", defineAnnotatedType("array").of(defineAnnotatedType("object").prop("name", defineAnnotatedType().designType("string").tags("string").$type).prop("confirmed", defineAnnotatedType().designType("boolean").tags("boolean").$type).prop("value", defineAnnotatedType().designType("string").tags("string").$type).prop("lastUsedWindow", defineAnnotatedType().designType("number").tags("int", "number").annotate("expect.int", true).optional().$type).$type).$type).prop("defaultMethod", defineAnnotatedType().designType("string").tags("string").$type).prop("autoSend", defineAnnotatedType().designType("boolean").tags("boolean").$type).annotate("db.patch.strategy", "merge").$type).prop("trustedDevices", defineAnnotatedType("array").of(defineAnnotatedType("object").prop("token", defineAnnotatedType().designType("string").tags("string").$type).prop("ip", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("issuedAt", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("expiresAt", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("name", defineAnnotatedType().designType("string").tags("string").optional().$type).$type).annotate("db.patch.strategy", "merge").optional().$type).prop("seenDevices", defineAnnotatedType("array").of(defineAnnotatedType("object").prop("token", defineAnnotatedType().designType("string").tags("string").$type).prop("ip", defineAnnotatedType().designType("string").tags("string").optional().$type).prop("issuedAt", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("expiresAt", defineAnnotatedType().designType("number").tags("timestamp", "number").annotate("expect.int", true).$type).prop("name", defineAnnotatedType().designType("string").tags("string").optional().$type).$type).annotate("db.patch.strategy", "merge").optional().$type).prop("roles", defineAnnotatedType("array").of(defineAnnotatedType().designType("string").tags("string").$type).annotate("arbac.role", true).$type);
 //#endregion
-export { AoothArbacUserCredentials, AtscriptArbacUserProvider, extractAttenuation, getAoothCredentialMetadataSpec, getAoothUserHandleSpec, getArbacAttenuationSpec, validateAttenuationTargets };
+export { AoothArbacUserCredentials, ArbacUserRecordCache, AtscriptArbacUserProvider, extractAttenuation, getAoothCredentialMetadataSpec, getAoothUserHandleSpec, getArbacAttenuationSpec, validateAttenuationTargets };

package/dist/index.d.mts

@@ -884,6 +884,23 @@ declare class MoostArbac<TUserAttrs extends object, TScope extends object> exten
   }): Promise<TArbacEvalResult$1<TScope>>;
   private readonly warnedFields;
   private readonly warnUnknownField;
+  private metaMemoMax;
+  /**
+   * Configure the `/meta` projection memo of the ARBAC DB / value-help
+   * controllers. The overlay still evaluates every grant per request; only
+   * the pure pruning of the cached envelope by those decisions is reused —
+   * keyed by the decisions themselves (never by user, scopes' JSON or row
+   * filters), up to `max` projections per envelope (default 64, LRU).
+   * Memoized projections are frozen and pre-serialized with a weak ETag.
+   * `false` turns it off (every `/meta` is pruned afresh).
+   *
+   * @since 0.1.78
+   */
+  setMetaMemo(options: false | {
+    max?: number;
+  }): this;
+  /** Most memoized `/meta` projections per envelope (`0` = memo off). @since 0.1.78 */
+  getMetaMemoMax(): number;
   /** The registered custom scope field rules. @since 0.1.72 */
   getScopeFields(): TScopeFieldRules<TScope>;
 }

package/dist/index.mjs

@@ -7,6 +7,7 @@ import { Inherit, Injectable, TInterceptorPriority, defineBeforeInterceptor, get
 import { computeInsights, containsRelationFilter, findAncestorInSet, getPath, hasRelationOp, isPlainObject, isRelationOp, translateQueryTree } from "@atscript/db";
 import { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsValueHelpController, DB_CRUD_HANDLERS, VALUE_HELP_CRUD_HANDLERS, badRequest, discoverRowLevelActions, getControllerFormType, getDbEndpoint, hasActionDelegations, resolveTerminalRef } from "@atscript/moost-db";
 import { groupByFields, walkFilter } from "@uniqu/core";
+import { prerenderJson } from "@wooksjs/event-http";
 //#region src/db/helpers.ts
 /** `map.get(key)`, created with `create()` and stored on a miss. */
 function getOrCreate(map, key, create) {
@@ -248,7 +249,7 @@ function buildScopeVisibility(scopes, table, opts = {}) {
 		return source === void 0 || alwaysVisible.has(source) || base(source);
 	};
 	const declared = /* @__PURE__ */ new Map();
-	return {
+	return tagBuilt({
 		allowed,
 		alwaysVisible,
 		withGrants,
@@ -261,7 +262,16 @@ function buildScopeVisibility(scopes, table, opts = {}) {
 			if (resolved || !withGrants.has(name)) return resolved ?? void 0;
 			return getOrCreate(declared, name, () => buildScopeVisibility(eff.withScopes(name), table?.relatedTable?.(name)));
 		}
-	};
+	});
+}
+const BUILT = Symbol("arbac.builtVisibility");
+function tagBuilt(vis) {
+	vis[BUILT] = vis;
+	return vis;
+}
+/** `vis` came from {@link buildScopeVisibility} as is (not hand-built, not a copy). */
+function isBuiltVisibility(vis) {
+	return vis[BUILT] === vis;
 }
 const scopeVisibilityCache = /* @__PURE__ */ new WeakMap();
 const NO_TABLE = {
@@ -725,6 +735,8 @@ function fieldChildrenOf(table) {
 }
 //#endregion
 //#region src/moost-arbac.ts
+/** Default number of memoized `/meta` projections per envelope. */
+const DEFAULT_META_MEMO_MAX = 64;
 let MoostArbac = class MoostArbac extends Arbac$1 {
 	scopeFieldRules = {};
 	/**
@@ -790,6 +802,26 @@ let MoostArbac = class MoostArbac extends Arbac$1 {
 		this.warnedFields.add(field);
 		console.warn(`[arbac] Scope field "${field}" has no rule registered with registerScopeFields: it reaches only your own code, and an attenuated request carrying it fails with 500.`);
 	};
+	metaMemoMax = DEFAULT_META_MEMO_MAX;
+	/**
+	* Configure the `/meta` projection memo of the ARBAC DB / value-help
+	* controllers. The overlay still evaluates every grant per request; only
+	* the pure pruning of the cached envelope by those decisions is reused —
+	* keyed by the decisions themselves (never by user, scopes' JSON or row
+	* filters), up to `max` projections per envelope (default 64, LRU).
+	* Memoized projections are frozen and pre-serialized with a weak ETag.
+	* `false` turns it off (every `/meta` is pruned afresh).
+	*
+	* @since 0.1.78
+	*/
+	setMetaMemo(options) {
+		this.metaMemoMax = options === false ? 0 : Math.max(0, options.max ?? DEFAULT_META_MEMO_MAX);
+		return this;
+	}
+	/** Most memoized `/meta` projections per envelope (`0` = memo off). @since 0.1.78 */
+	getMetaMemoMax() {
+		return this.metaMemoMax;
+	}
 	/** The registered custom scope field rules. @since 0.1.72 */
 	getScopeFields() {
 		return this.scopeFieldRules;
@@ -843,6 +875,7 @@ async function loadPrincipal(user) {
 		attrs: (id) => attrs ??= Promise.resolve(user.getAttrs(id))
 	};
 }
+const arbacDeps = cachedBy((_controller, ctx) => Promise.all([useControllerContext(ctx).instantiate(ArbacUserProviderToken), useControllerContext(ctx).instantiate(MoostArbac)]));
 const principalKey = key("arbac.principal");
 function isHttpEvent(ctx) {
 	return ctx.has(eventTypeKey) && ctx.get(eventTypeKey) === "http";
@@ -858,7 +891,7 @@ function evaluateArbac(ctx, target, memoPrincipal = false) {
 	const cc = useControllerContext(ctx);
 	const table = target.table ?? cc.getController()?.readable;
 	const pending = (async () => {
-		const [user, arbac] = await Promise.all([cc.instantiate(ArbacUserProviderToken), cc.instantiate(MoostArbac)]);
+		const [user, arbac] = await arbacDeps(cc.getController(), ctx);
 		let principal;
 		if (!memoPrincipal || !isHttpEvent(ctx)) principal = loadPrincipal(user);
 		else if (ctx.has(principalKey)) principal = ctx.get(principalKey);
@@ -919,7 +952,12 @@ function conjoinForTable(a, b, table, fields) {
 		fields
 	})[0]);
 }
-const scopeFieldsSlot = cached(async (ctx) => (await useControllerContext(ctx).instantiate(MoostArbac)).getScopeFields());
+const scopeFieldsSlot = cached(async (ctx) => (await arbacDeps(useControllerContext(ctx).getController(), ctx))[1].getScopeFields());
+/** The current controller's `MoostArbac` — resolved once per (event, controller). */
+async function currentMoostArbac() {
+	const ctx = current();
+	return (await arbacDeps(useControllerContext(ctx).getController(), ctx))[1];
+}
 /** The current app's custom scope field rules — resolved once per event. */
 function currentScopeFields() {
 	return current().get(scopeFieldsSlot);
@@ -1090,6 +1128,189 @@ const ArbacResource = (name) => getArbacMate().decorate("arbacResourceId", name)
 */
 const ArbacAction = (name) => getArbacMate().decorate("arbacActionId", name);
 //#endregion
+//#region src/db/meta-memo.ts
+/** Deepest relation nesting the decision record follows; deeper → not memoized. */
+const MAX_RECORD_DEPTH = 16;
+var Unkeyable = class extends Error {};
+const UNKEYABLE = new Unkeyable("unkeyable /meta decision");
+function refuse() {
+	throw UNKEYABLE;
+}
+const ids = /* @__PURE__ */ new WeakMap();
+let nextId = 1;
+function idOf(obj) {
+	if (!obj) return 0;
+	let id = ids.get(obj);
+	if (id === void 0) ids.set(obj, id = nextId++);
+	return id;
+}
+/**
+* Validate a scope list without copying it: no symbol-keyed scope (the
+* `INHERITED_CONJUNCTION` marker of a one-sided `with` sub-scope) and no
+* function-valued scope piece, `with` sub-scopes recursively. Each scope
+* object is visited once per record (`seen`). The record itself keys on the
+* visibility DERIVED from the scopes (row data never reaches `/meta`).
+*/
+function checkScopes(scopes, seen, depth = 0) {
+	if (!scopes) return;
+	if (depth > MAX_RECORD_DEPTH) refuse();
+	for (const scope of scopes) {
+		if (seen.has(scope)) continue;
+		if (scope === null || typeof scope !== "object") refuse();
+		seen.add(scope);
+		if (Object.getOwnPropertySymbols(scope).length > 0) refuse();
+		const record = scope;
+		for (const key of Object.keys(record)) {
+			const value = record[key];
+			if (typeof value === "function" || typeof value === "symbol") refuse();
+			if (key === "with" && value !== void 0 && value !== null) {
+				if (typeof value !== "object" || Object.getOwnPropertySymbols(value).length > 0) refuse();
+				checkScopes(Object.values(value), seen, depth + 1);
+			}
+		}
+	}
+}
+/** A projection (`path` → `0 | 1`) as sorted `[path, flag, …]`; anything else refuses. */
+function projectionKey(projection) {
+	if (Object.getOwnPropertySymbols(projection).length > 0) refuse();
+	const keys = Object.keys(projection).toSorted();
+	const out = [];
+	for (const key of keys) {
+		const flag = projection[key];
+		if (flag !== 0 && flag !== 1) refuse();
+		out.push(key, flag);
+	}
+	return out;
+}
+/** Sorted strings of a set / list; a non-string refuses. */
+function sortedNames(names) {
+	const out = [];
+	for (const name of names) {
+		if (typeof name !== "string") refuse();
+		out.push(name);
+	}
+	return out.toSorted();
+}
+const NO_TREE = /* @__PURE__ */ new Map();
+/**
+* One visibility level: its table, normalized projection, parent-authority
+* relations, and every relation the pruning can resolve at this level — the
+* `/meta` relation names (`tree`, what the overlay resolved) and the declared
+* `with` names — as the child level or `null`. Only levels built by
+* `buildScopeVisibility` (whose `isAllowed` / `relation` are pure functions
+* of exactly these) are accepted.
+*/
+function encodeLevel(vis, tree, ctx, seen, depth) {
+	if (depth > MAX_RECORD_DEPTH || !isBuiltVisibility(vis)) refuse();
+	if (vis.alwaysVisible !== ctx.identifiers(vis.table)) refuse();
+	checkScopes(vis.scopes, seen);
+	const withGrants = sortedNames(vis.withGrants);
+	const names = tree.size === 0 ? withGrants : sortedNames(/* @__PURE__ */ new Set([...tree.keys(), ...withGrants]));
+	const relations = [];
+	for (const name of names) {
+		const sub = vis.relation?.(name);
+		relations.push(name, sub ? encodeLevel(sub, tree.get(name) ?? NO_TREE, ctx, seen, depth + 1) : 0);
+	}
+	return [
+		idOf(vis.table),
+		projectionKey(vis.allowed),
+		withGrants,
+		relations
+	];
+}
+/** Bit string of `flags`. */
+function bits(flags) {
+	let out = "";
+	for (const flag of flags) out += flag ? "1" : "0";
+	return out;
+}
+/**
+* The memo key of a `/meta` projection: its decision record, serialized —
+* or `undefined` when an input cannot be keyed exactly (then the request is
+* not memoized).
+*/
+function metaDecisionKey(input, ctx) {
+	try {
+		const seen = /* @__PURE__ */ new Set();
+		checkScopes(input.writeScopes, seen);
+		checkScopes(input.readScopes, seen);
+		const p = input.projection;
+		if (!p) return JSON.stringify([bits(input.actions), bits(input.crud)]);
+		const refTargets = [];
+		const types = [...p.refTargets.keys()].toSorted((a, b) => idOf(a) - idOf(b));
+		for (const type of types) {
+			const vis = p.refTargets.get(type);
+			refTargets.push(idOf(type), ctx.isServed(type), vis ? encodeLevel(vis, NO_TREE, ctx, seen, 1) : 0);
+		}
+		const { writable, nestedWrites, groupBy } = p;
+		if (groupBy !== void 0 && typeof groupBy !== "boolean" && !Array.isArray(groupBy)) refuse();
+		return JSON.stringify([
+			bits(input.actions),
+			bits(input.crud),
+			encodeLevel(p.vis, p.tree, ctx, seen, 0),
+			writable === void 0 ? 0 : writable === "all" ? 1 : sortedNames(writable),
+			nestedWrites ? sortedNames(nestedWrites) : 0,
+			Array.isArray(groupBy) ? sortedNames(groupBy) : groupBy ?? 0,
+			refTargets,
+			p.vis.table?.type ? ctx.isServed(p.vis.table.type) : 0
+		]);
+	} catch (error) {
+		if (error instanceof Unkeyable) return void 0;
+		throw error;
+	}
+}
+const variants = /* @__PURE__ */ new WeakMap();
+const seenEnvelopes = /* @__PURE__ */ new WeakSet();
+/**
+* The projection of `envelope` for `key`, computed once per (envelope, key)
+* and reused while it stays among the `max` most recently used. No `key`
+* (unkeyable decisions) or `max` ≤ 0 → computed per call, uncached.
+*/
+function memoMetaProjection(envelope, key, max, compute) {
+	if (key === void 0 || max <= 0) return compute();
+	if (!seenEnvelopes.has(envelope)) {
+		seenEnvelopes.add(envelope);
+		return compute();
+	}
+	let byKey = variants.get(envelope);
+	const hit = byKey?.get(key);
+	if (hit) {
+		byKey.delete(key);
+		byKey.set(key, hit);
+		return hit;
+	}
+	const out = shareMeta(compute());
+	if (!byKey) variants.set(envelope, byKey = /* @__PURE__ */ new Map());
+	while (byKey.size >= max) byKey.delete(byKey.keys().next().value);
+	byKey.set(key, out);
+	return out;
+}
+/**
+* Make a memoized `/meta` object shareable across requests: frozen (deeply in
+* development / test, so an in-place mutation throws instead of serving old
+* bytes) and registered for prerendering with a weak ETag.
+*/
+function shareMeta(obj) {
+	if (shouldDeepFreeze()) deepFreeze(obj);
+	else Object.freeze(obj);
+	return prerenderJson(obj, { etag: true });
+}
+let deepFreezeOn;
+function shouldDeepFreeze() {
+	if (deepFreezeOn === void 0) {
+		const env = typeof process === "undefined" ? void 0 : process.env.NODE_ENV;
+		deepFreezeOn = env === "test" || env === "development";
+	}
+	return deepFreezeOn;
+}
+const deepFrozen = /* @__PURE__ */ new WeakSet();
+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/db/meta-projection.ts
 /**
 * Exact-or-ancestor membership in the write whitelist: `credit.credentials.user`
@@ -1648,30 +1869,45 @@ async function applyArbacMetaOverlay(meta, source, _indexes) {
 	const instance = useControllerContext().getController();
 	const { methods } = controllerMethodIndex(instance);
 	const crudKeys = Object.keys(meta.crud);
-	const [allowedActions, crudScopes] = await Promise.all([grantedActions(instance, meta.actions.map((entry) => entry.name)), Promise.all(crudKeys.map((op) => evaluateHandlers(crudHandlerIds(instance, op, methods))))]);
+	const [allowedActions, crudScopes, arbac] = await Promise.all([
+		grantedActions(instance, meta.actions.map((entry) => entry.name)),
+		Promise.all(crudKeys.map((op) => evaluateHandlers(crudHandlerIds(instance, op, methods)))),
+		currentMoostArbac()
+	]);
+	const memoMax = arbac.getMetaMemoMax();
 	const allowed = new Set(allowedActions);
-	const actions = meta.actions.filter((entry) => allowed.has(entry.name));
-	const crud = {};
+	const actionBits = meta.actions.map((entry) => allowed.has(entry.name));
+	const crudBits = crudScopes.map((scopes) => scopes !== void 0);
 	const readScopes = [];
 	const writeScopes = [];
 	for (let i = 0; i < crudKeys.length; i++) {
 		const scopes = crudScopes[i];
 		if (!scopes) continue;
-		crud[crudKeys[i]] = meta.crud[crudKeys[i]];
 		(WRITE_CRUD_OPS.has(crudKeys[i]) ? writeScopes : readScopes).push(...scopes);
 	}
-	const overlaid = {
-		...meta,
-		actions,
-		crud
+	const overlay = () => {
+		const crud = {};
+		for (let i = 0; i < crudKeys.length; i++) if (crudBits[i]) crud[crudKeys[i]] = meta.crud[crudKeys[i]];
+		return {
+			...meta,
+			actions: meta.actions.filter((_, i) => actionBits[i]),
+			crud
+		};
 	};
-	if (readScopes.length === 0) return overlaid;
+	if (readScopes.length === 0) return memoMetaProjection(meta, memoMax > 0 ? metaDecisionKey({
+		actions: actionBits,
+		crud: crudBits,
+		readScopes,
+		writeScopes
+	}, RECORD_CTX) : void 0, memoMax, overlay);
 	const groupBy = effectiveScope(readScopes).controls.$groupBy;
 	const writable = collectWritableFields(writeScopes, false);
 	const nestedWrites = effectiveScope(writeScopes).nestedWrites;
 	if (isIdentifierSet(source)) {
 		const vis = buildScopeVisibility(readScopes, void 0, source);
-		return gateGroupable(Object.keys(vis.allowed).length > 0 || vis.withGrants.size > 0 ? pruneMetaByVisibility(overlaid, {
+		const visible = Object.keys(vis.allowed).length > 0 || vis.withGrants.size > 0;
+		const overlaid = overlay();
+		return gateGroupable(visible ? pruneMetaByVisibility(overlaid, {
 			...vis,
 			writable,
 			nestedWrites
@@ -1679,12 +1915,30 @@ async function applyArbacMetaOverlay(meta, source, _indexes) {
 	}
 	const vis = buildScopeVisibility(readScopes, source, { relations: await resolveRelationTree(readScopes, source, metaRelationNames(meta), { listSiblings: false }) });
 	const refTargets = await resolveRefTargets(vis, meta);
-	return gateGroupable(pruneMetaByVisibility(overlaid, {
+	return memoMetaProjection(meta, memoMax > 0 ? metaDecisionKey({
+		actions: actionBits,
+		crud: crudBits,
+		readScopes,
+		writeScopes,
+		projection: {
+			vis,
+			tree: metaRelationNames(meta),
+			writable,
+			nestedWrites,
+			groupBy,
+			refTargets
+		}
+	}, RECORD_CTX) : void 0, memoMax, () => gateGroupable(pruneMetaByVisibility(overlay(), {
 		...vis,
 		writable,
 		nestedWrites
-	}, refTargets), groupBy);
+	}, refTargets), groupBy));
 }
+/** What the `/meta` memo's decision record reads from the pruning rules. */
+const RECORD_CTX = {
+	isServed: isDbServed,
+	identifiers: identifierSet
+};
 /**
 * The `/meta/form/:name` overlay: a form is a plain annotated type (no table),
 * so only its cross-table pointers are projected. Every prop's `ref` and
@@ -2595,8 +2849,9 @@ function insertRowsVerdict(rows, check) {
 		if (error instanceof UnsupportedCheckError) return void 0;
 		throw error;
 	}
+	const fieldList = [...fields];
 	let verdict = true;
-	for (const row of rows) if ([...fields].some((f) => getPath(row, f) === void 0)) verdict = void 0;
+	for (const row of rows) if (fieldList.some((f) => getPath(row, f) === void 0)) verdict = void 0;
 	else if (!predicate(row)) return false;
 	return verdict;
 }
@@ -3190,11 +3445,21 @@ function requestsField(requested, field) {
 async function applyValueHelpMetaOverlay(host, meta) {
 	const overlaid = await applyArbacMetaOverlay(meta, host.source);
 	if (!overlaid.searchable || overlaid.fields === meta.fields) return overlaid;
-	return host.searchableFields.some((f) => f in overlaid.fields) ? overlaid : {
+	if (host.searchableFields.some((f) => f in overlaid.fields)) return overlaid;
+	if (!Object.isFrozen(overlaid)) return {
 		...overlaid,
 		searchable: false
 	};
+	let perHost = unsearchable.get(overlaid);
+	if (!perHost) unsearchable.set(overlaid, perHost = /* @__PURE__ */ new WeakMap());
+	let out = perHost.get(host);
+	if (!out) perHost.set(host, out = shareMeta({
+		...overlaid,
+		searchable: false
+	}));
+	return out;
 }
+const unsearchable = /* @__PURE__ */ new WeakMap();
 let AsArbacValueHelpController = class AsArbacValueHelpController extends AsValueHelpController {
 	_arbacHost;
 	/** Makes this controller the binding / `ref` policy source for its bound type's ARBAC resource. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aooth/arbac-moost",
-  "version": "0.1.77",
+  "version": "0.1.78",
   "description": "Moost RBAC integration for aoothjs (migrated from @moostjs/arbac)",
   "keywords": [
     "abac",
@@ -60,31 +60,31 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/core": "^0.1.13",
-    "@aooth/arbac": "0.1.77",
-    "@aooth/arbac-core": "0.1.77",
-    "@aooth/user": "0.1.77"
+    "@uniqu/core": "^0.1.14",
+    "@aooth/arbac": "0.1.78",
+    "@aooth/user": "0.1.78",
+    "@aooth/arbac-core": "0.1.78"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.101",
-    "@atscript/db": "^0.1.150",
-    "@atscript/db-sql-tools": "^0.1.150",
-    "@atscript/db-sqlite": "^0.1.150",
-    "@atscript/moost-db": "^0.1.150",
-    "@atscript/typescript": "^0.1.101",
-    "@moostjs/event-http": "^0.6.47",
+    "@atscript/core": "^0.1.102",
+    "@atscript/db": "^0.1.152",
+    "@atscript/db-sql-tools": "^0.1.152",
+    "@atscript/db-sqlite": "^0.1.152",
+    "@atscript/moost-db": "^0.1.152",
+    "@atscript/typescript": "^0.1.102",
+    "@moostjs/event-http": "^0.6.48",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.6.2",
-    "unplugin-atscript": "^0.1.101"
+    "unplugin-atscript": "^0.1.102"
   },
   "peerDependencies": {
-    "@atscript/db": "^0.1.150",
-    "@atscript/moost-db": "^0.1.150",
-    "@atscript/typescript": "^0.1.101",
-    "@moostjs/event-http": "^0.6.47",
-    "@wooksjs/event-core": "^0.7.26",
-    "@wooksjs/event-http": "^0.7.26",
-    "moost": "^0.6.47"
+    "@atscript/db": "^0.1.152",
+    "@atscript/moost-db": "^0.1.152",
+    "@atscript/typescript": "^0.1.102",
+    "@moostjs/event-http": "^0.6.48",
+    "@wooksjs/event-core": "^0.7.27",
+    "@wooksjs/event-http": "^0.7.27",
+    "moost": "^0.6.48"
   },
   "peerDependenciesMeta": {
     "@atscript/db": {