@atscript/moost-db 0.1.134 → 0.1.136

package/dist/index.cjs

@@ -251,7 +251,8 @@ const rowLevelActionsCache = /* @__PURE__ */ new WeakMap();
 /**
 * Per-controller registry of form names → compiled `.as` classes, populated
 * during {@link discoverActions} when a method param carries
-* `atscript_db_action_input_form`. Backs `GET /meta/form/:name`.
+* `atscript_db_action_input_form` or a class-level entry passes a type as
+* `inputForm`. Backs `GET /meta/form/:name`.
 *
 * Same name + same type ref across multiple actions is fine (forms can be
 * reused). Same name + *different* type refs is an ambiguity — discovery
@@ -395,7 +396,7 @@ function collectClassActions(ctor, logger, out, seen) {
 			logger.warn(`${WARN_PREFIX} duplicate action name "${name}" within controller — dropping the second declaration`);
 			continue;
 		}
-		const built = buildClassEntry(name, entry, logger);
+		const built = buildClassEntry(ctor, name, entry, logger);
 		if (built) {
 			seen.add(name);
 			out.push({
@@ -405,7 +406,7 @@ function collectClassActions(ctor, logger, out, seen) {
 		}
 	}
 }
-function buildClassEntry(name, entry, logger) {
+function buildClassEntry(ctor, name, entry, logger) {
 	const level = entry.level;
 	if (!level) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a level — dropping. Use @DbTableActions/@DbRowActions/@DbRowsActions or set "level" explicitly.`);
@@ -443,6 +444,8 @@ function buildClassEntry(name, entry, logger) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" has unknown processor "${String(processor)}" — dropping`);
 		return null;
 	}
+	const form = resolveClassInputForm(name, entry, processor, logger);
+	if (form === null) return null;
 	const info = {
 		name,
 		label: entry.label,
@@ -450,9 +453,45 @@ function buildClassEntry(name, entry, logger) {
 		processor,
 		value
 	};
+	if (form) {
+		if (form.type && !registerFormType(ctor, {
+			type: form.type,
+			name: form.name
+		}, name, logger)) return null;
+		info.inputForm = form.name;
+		if (form.url !== void 0) info.formUrl = form.url;
+	}
 	emitInfo(info, entry);
 	return info;
 }
+/**
+* Resolves a class-level entry's `inputForm`. Returns `undefined` when the
+* entry declares none, `null` when it must be dropped (already warned — the
+* runtime check for JS callers and `processor: "navigate"`), else the form to
+* emit: `type` when this controller serves it (`/meta/form/:name`), `url`
+* when it lives elsewhere.
+*/
+function resolveClassInputForm(name, entry, processor, logger) {
+	const inputForm = entry.inputForm;
+	if (inputForm === void 0) return void 0;
+	const drop = (reason) => {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" — ${reason} — dropping`);
+		return null;
+	};
+	if (processor === "navigate") return drop("processor \"navigate\" cannot take an `inputForm`");
+	const { name: formName, url } = inputForm ?? {};
+	if (typeof formName === "string" && formName !== "") {
+		if ((0, _atscript_typescript_utils.isAnnotatedType)(inputForm)) return {
+			name: formName,
+			type: inputForm
+		};
+		if (typeof url === "string" && url !== "") return {
+			name: formName,
+			url
+		};
+	}
+	return drop("`inputForm` must be a compiled .as interface or `{ name, url }` (non-empty strings)");
+}
 function applyDefaultPerLevel(envelopes, logger) {
 	const winners = /* @__PURE__ */ new Map();
 	for (const { info } of envelopes) {
@@ -977,6 +1016,11 @@ function computeStripFields(candidates, resolvedProjection) {
 	}
 	return strip;
 }
+/**
+* Sets `$actions` on every row and strips the columns fetched only for an
+* action's `requiredFields` — IN PLACE; returns the same array, typed as
+* augmented.
+*/
 function augmentRowsWithActions(args) {
 	const { envelopes, rows, resolvedProjection } = args;
 	const candidates = collectCandidates(envelopes);
@@ -1224,16 +1268,18 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	physicalNames;
 	/** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
 	bucketUnits;
+	/** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
+	aggregateFns;
 	/** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
 	signature;
 	/**
 	* The adapter-level capabilities that can change after construction (geo
-	* support, calendar-bucket units): an index whose {@link signature}
-	* differs from this is stale. Any new adapter-level input the index reads
-	* must be added here.
+	* support, calendar-bucket units, aggregate functions): an index whose
+	* {@link signature} differs from this is stale. Any new adapter-level input
+	* the index reads must be added here.
 	*/
 	static adapterSignature(source) {
-		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}`;
+		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}|${[...source.aggregateFns()].join(",")}`;
 	}
 	_entries = /* @__PURE__ */ new Map();
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
@@ -1256,6 +1302,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		this.signature = FieldCapabilityIndex.adapterSignature(source);
 		const units = source.calendarBucketUnits();
 		this.bucketUnits = _uniqu_core.BUCKET_UNITS.filter((unit) => units.has(unit));
+		const fns = source.aggregateFns();
+		this.aggregateFns = [..._atscript_db.ALL_AGGREGATE_FNS].filter((fn) => fns.has(fn));
 		const physicalNames = /* @__PURE__ */ new Set();
 		const jsonValueParents = /* @__PURE__ */ new Set();
 		for (const fd of source.fieldDescriptors) {
@@ -1552,6 +1600,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_idSources = /* @__PURE__ */ new Map();
 	_preferredIdSet;
 	_overlayIsNoOp;
+	/** `true` when a subclass implements {@link decorateRows} (the override switches the hook on). */
+	_decorates;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	_quantityRefByPath;
 	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -1575,6 +1625,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		this._quantityRefByPath = this._collectQuantityRefs();
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
+		this._decorates = typeof this.decorateRows === "function";
 		this._idOpts = this.hasField === _AsDbReadableController.prototype.hasField ? void 0 : { isFieldVisible: this._exists };
 	}
 	/**
@@ -1681,7 +1732,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	}
 	/**
 	* The core's shared normalizer of `$select` computed entries
-	* (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+	* (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
 	* (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
 	* week start / alias, "grouped queries only", "must also appear in
 	* $groupBy", alias collisions with this table's fields. Runs once per
@@ -1693,7 +1744,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	checkComputedSelect(controls) {
 		const capabilities = this.capabilities;
 		try {
-			(0, _atscript_db.resolveCalendarBuckets)(controls, {
+			(0, _atscript_db.normalizeComputedSelect)(controls, {
 				flatMap: this.readable.flatMap,
 				physicalNames: capabilities.physicalNames,
 				navFields: capabilities.navFields
@@ -2050,13 +2101,27 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return { kind: "plain" };
 	}
 	/**
-	* Shared `query` / `pages` pipeline: prepare actions augmentation + read
+	* Finishes a read's top-level rows in place: `$actions` augmentation (when
+	* the request asked for it — `prep`), then {@link decorateRows} when a
+	* subclass implements it. Returns the hook's result — `undefined`, with no
+	* promise or microtask, when there is no hook or it is synchronous.
+	*/
+	_finishRows(rows, prep, ctx) {
+		if (prep) augmentRowsWithActions({
+			envelopes: prep.envelopes,
+			rows,
+			resolvedProjection: prep.resolvedProjection
+		});
+		return this._decorates ? this.decorateRows(rows, ctx) : void 0;
+	}
+	/**
+	* Shared `query` / `pages` / `geo` pipeline: prepare actions augmentation + read
 	* strategy in parallel, pre-widen $select for `requiredFields`, run
 	* `exec`, and augment `result.data` with `$actions` when the request set
-	* `$actions=true`. Caller dispatches the strategy to its read-method
-	* family (count vs no-count).
+	* `$actions=true`, then run {@link decorateRows}. Caller dispatches the
+	* strategy to its read-method family (count vs no-count).
 	*/
-	async _runReadWithActions(queryObj, controls, select, exec) {
+	async _runReadWithActions(endpoint, queryObj, controls, select, exec) {
 		const [prep, strategy] = await Promise.all([this._prepareAugmentation(controls, select), this._resolveReadStrategy(controls)]);
 		const result = await exec(prep?.widenedSelect ? {
 			...queryObj,
@@ -2065,12 +2130,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$select: prep.widenedSelect
 			}
 		} : queryObj, strategy);
-		if (!prep) return result;
-		result.data = augmentRowsWithActions({
-			envelopes: prep.envelopes,
-			rows: result.data,
-			resolvedProjection: prep.resolvedProjection
+		const pending = this._finishRows(result.data, prep, {
+			endpoint,
+			projection: select,
+			controls
 		});
+		if (pending) await pending;
 		return result;
 	}
 	/**
@@ -2142,7 +2207,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$threshold: threshold
 			}
 		};
-		return (await this._runReadWithActions(queryObj, controls, select, async (q, strategy) => {
+		return (await this._runReadWithActions("query", queryObj, controls, select, async (q, strategy) => {
 			switch (strategy.kind) {
 				case "vector": return { data: await (strategy.vectorField ? this.readable.vectorSearch(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearch(strategy.vector, q)) };
 				case "search": return { data: await this.readable.search(strategy.term, q, strategy.index) };
@@ -2180,7 +2245,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$threshold: threshold
 			}
 		};
-		const result = await this._runReadWithActions(query, controls, select, async (q, strategy) => {
+		const result = await this._runReadWithActions("pages", query, controls, select, async (q, strategy) => {
 			switch (strategy.kind) {
 				case "vector": return strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q);
 				case "search": return this.readable.searchWithCount(strategy.term, q, strategy.index);
@@ -2245,7 +2310,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			}
 		};
 		if (paginated) {
-			const result = await this._runReadWithActions(queryObj, controls, select, async (q) => indexName ? this.readable.geoSearchWithCount(indexName, point, q) : this.readable.geoSearchWithCount(point, q));
+			const result = await this._runReadWithActions("geo", queryObj, controls, select, async (q) => indexName ? this.readable.geoSearchWithCount(indexName, point, q) : this.readable.geoSearchWithCount(point, q));
 			return {
 				data: result.data,
 				page,
@@ -2254,7 +2319,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				count: result.count
 			};
 		}
-		return (await this._runReadWithActions(queryObj, controls, select, async (q) => ({ data: await (indexName ? this.readable.geoSearch(indexName, point, q) : this.readable.geoSearch(point, q)) }))).data;
+		return (await this._runReadWithActions("geo", queryObj, controls, select, async (q) => ({ data: await (indexName ? this.readable.geoSearch(indexName, point, q) : this.readable.geoSearch(point, q)) }))).data;
 	}
 	/** Parses the `$center` control: `"lng,lat"` string (or tuple) → `[number, number]`. */
 	_parseGeoCenter(raw) {
@@ -2329,13 +2394,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		const item = await this.returnOne(Promise.resolve(row));
 		if (item instanceof _moostjs_event_http.HttpError) return item;
-		if (!prep) return item;
-		const [augmented] = augmentRowsWithActions({
-			envelopes: prep.envelopes,
-			rows: [item],
-			resolvedProjection: prep.resolvedProjection
+		const pending = this._finishRows([item], prep, {
+			endpoint: "one",
+			projection: select,
+			controls: parsedControls
 		});
-		return augmented;
+		if (pending) await pending;
+		return item;
 	}
 	/**
 	* **GET /meta** — returns table/view metadata for UI.
@@ -2383,7 +2448,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			actions: this.buildActions(),
 			crud: this.buildCrud(),
 			versionColumn: this.readable.versionColumn,
-			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] }
+			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] },
+			aggregateFns: [...capabilities.aggregateFns]
 		};
 	}
 	buildCrud() {

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { i as resolveDbSpace, n as clearDbSpaces, r as provideDbSpace, t as DEFAULT_DB_SPACE } from "./db-space-registry-CWpYwZ4R.cjs";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, TValidatorOptions, Validator } from "@atscript/typescript/utils";
-import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
@@ -241,7 +241,7 @@ interface TCapabilityVerdict {
   message: string;
 }
 /** The readable members the index reads. */
-type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "dimensions" | "measures">;
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "dimensions" | "measures">;
 /**
  * Capability index of one readable.
  *
@@ -273,15 +273,17 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   readonly physicalNames: ReadonlySet<string>;
   /** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
   readonly bucketUnits: readonly BucketUnit[];
+  /** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
+  readonly aggregateFns: readonly AggregateFn[];
   /** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
   readonly signature: string;
   /**
    * The adapter-level capabilities that can change after construction (geo
-   * support, calendar-bucket units): an index whose {@link signature}
-   * differs from this is stale. Any new adapter-level input the index reads
-   * must be added here.
+   * support, calendar-bucket units, aggregate functions): an index whose
+   * {@link signature} differs from this is stale. Any new adapter-level input
+   * the index reads must be added here.
    */
-  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits">): string;
+  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns">): string;
   private readonly _entries;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
@@ -324,12 +326,34 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
+/** Read endpoint a {@link AsDbReadableController.decorateRows} call serves. */
+type TDbDecorateEndpoint = "query" | "pages" | "geo" | "one";
+/**
+ * Context passed to {@link AsDbReadableController.decorateRows}.
+ *
+ * @since 0.1.136
+ */
+interface TDbDecorateContext {
+  /** Endpoint that produced the rows. `/one` and `/one/:id` both report `"one"`. */
+  endpoint: TDbDecorateEndpoint;
+  /**
+   * The effective `$select` the endpoint read with — after
+   * `transformProjection`, the `@db.writeOnly` seal and preferred-id
+   * widening (`undefined` = no projection). Columns added only to feed an
+   * action's `requiredFields` are stripped again before the hook runs.
+   */
+  projection: UniqueryControls["$select"] | undefined;
+  /** The request's parsed controls (`$select`, `$with`, `$actions`, …). Read-only by convention. */
+  controls: Record<string, unknown>;
+}
 /**
  * Read-only database controller for Moost that works with any `AtscriptDbReadable`
  * (tables or views). Provides query, pages, getOne, and meta endpoints.
  *
  * For write operations (insert, replace, update, delete), use {@link AsDbController}.
- * For views, use {@link AsDbViewController}.
+ * Views bind to this same class — `@ViewController(view)` (an alias of
+ * `@ReadableController`) or a constructor-passed view; there is no separate
+ * view controller.
  */
 declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
   /** Reference to the underlying readable (table or view). */
@@ -370,6 +394,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _idSources;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
+  /** `true` when a subclass implements {@link decorateRows} (the override switches the hook on). */
+  private readonly _decorates;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   private readonly _quantityRefByPath;
   /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -435,7 +461,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   }): HttpError | undefined;
   /**
    * The core's shared normalizer of `$select` computed entries
-   * (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+   * (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
    * (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
    * week start / alias, "grouped queries only", "must also appear in
    * $groupBy", alias collisions with this table's fields. Runs once per
@@ -551,11 +577,45 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _aggregateControls;
   private _resolveReadStrategy;
   /**
-   * Shared `query` / `pages` pipeline: prepare actions augmentation + read
+   * Post-read row decoration hook. Not implemented by
+   * default — defining it in a subclass switches it on. Runs once per
+   * response on `/query`, `/pages`, `/geo` and `/one` (`/one/:id` and the
+   * composite form), after `$actions` augmentation, with the final top-level
+   * rows. Mutate the rows in place; the return value is ignored. May be async.
+   *
+   * Not called for `$count`, `$groupBy` aggregates, nested `$with` rows
+   * (reach them through the parent row), a `/one` 404, or value-help
+   * controllers.
+   *
+   * Convention (not enforced): name decoration keys with a `$` prefix, like
+   * `$actions` and `$distance`, so they can never collide with a field name.
+   * Do not overwrite `$actions`. Columns the
+   * hook needs but the client did not select must be added in
+   * {@link transformProjection} — they are then part of the response.
+   *
+   * ```ts
+   * protected async decorateRows(rows: Record<string, unknown>[], ctx: TDbDecorateContext) {
+   *   const unread = await countUnread(rows.map((r) => r.id))
+   *   for (const row of rows) row.$unread = unread.get(row.id) ?? 0
+   * }
+   * ```
+   *
+   * @since 0.1.136
+   */
+  protected decorateRows?(rows: Record<string, unknown>[], ctx: TDbDecorateContext): void | Promise<void>;
+  /**
+   * Finishes a read's top-level rows in place: `$actions` augmentation (when
+   * the request asked for it — `prep`), then {@link decorateRows} when a
+   * subclass implements it. Returns the hook's result — `undefined`, with no
+   * promise or microtask, when there is no hook or it is synchronous.
+   */
+  private _finishRows;
+  /**
+   * Shared `query` / `pages` / `geo` pipeline: prepare actions augmentation + read
    * strategy in parallel, pre-widen $select for `requiredFields`, run
    * `exec`, and augment `result.data` with `$actions` when the request set
-   * `$actions=true`. Caller dispatches the strategy to its read-method
-   * family (count vs no-count).
+   * `$actions=true`, then run {@link decorateRows}. Caller dispatches the
+   * strategy to its read-method family (count vs no-count).
    */
   private _runReadWithActions;
   /**
@@ -1006,7 +1066,7 @@ interface LooseGate {
   onDisabledRows?: TOnDisabledRows;
 }
 type GateOpts<TRow, R extends readonly FlatKey<TRow>[]> = unknown extends TRow ? LooseGate : NoGate | WithGate<TRow, R>;
-interface BaseActionOpts extends Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled">> {
+interface BaseActionOpts extends Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled" | "formUrl">> {
   /**
    * Bound table reference. REQUIRED on non-`AsDbReadableController` classes
    * when `disabled` is set OR a `@DbActionRow*` parameter is declared.
@@ -1035,6 +1095,25 @@ interface DbActionsEntryCommonBase {
   promptText?: string | [string, string];
   /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
   shortcut?: string;
+  /**
+   * Input form the UI collects before invoking the action:
+   *
+   * - a compiled `.as` interface — registered on THIS controller and served
+   *   by its own `GET /meta/form/:name`; the wire carries `inputForm: Type.name`.
+   * - `{ name, url }` — a form served elsewhere: `name` goes on the wire as
+   *   `inputForm`, `url` (server-absolute path of the serialized schema, e.g.
+   *   `"/api/shipping/meta/form/ShipForm"`) as {@link TDbActionInfo.formUrl}.
+   *
+   * Not allowed with `processor: 'navigate'`. Class-level entries only
+   * describe the action — validating `input` is the target handler's job
+   * (e.g. its own `@InputForm(Type)` param).
+   *
+   * @since 0.1.136
+   */
+  inputForm?: TAtscriptAnnotatedType | {
+    name: string;
+    url: string;
+  };
 }
 type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbActionsEntryCommonBase & GateOpts<TRow, R>;
 /**
@@ -1048,6 +1127,7 @@ type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbAction
 type TDbActionsEntry<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = (DbActionsEntryWithGate<TRow, R> & {
   processor: "navigate";
   value: string;
+  inputForm?: never;
 }) | (DbActionsEntryWithGate<TRow, R> & {
   processor: "custom";
   value?: never;
@@ -1721,4 +1801,4 @@ declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef |
  */
 declare function applyTerminalRefs(serialized: TSerializedAnnotatedType, runtime: TAtscriptAnnotatedType, options: TSerializeOptions): TSerializedAnnotatedType;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbDecorateContext, TDbDecorateEndpoint, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.d.mts

@@ -3,7 +3,7 @@ import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializ
 import { HttpError } from "@moostjs/event-http";
 import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
+import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 //#region src/as-readable.controller.d.ts
 /**
  * Abstract base class for read-only HTTP controllers over an Atscript interface.
@@ -241,7 +241,7 @@ interface TCapabilityVerdict {
   message: string;
 }
 /** The readable members the index reads. */
-type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "dimensions" | "measures">;
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "dimensions" | "measures">;
 /**
  * Capability index of one readable.
  *
@@ -273,15 +273,17 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   readonly physicalNames: ReadonlySet<string>;
   /** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
   readonly bucketUnits: readonly BucketUnit[];
+  /** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
+  readonly aggregateFns: readonly AggregateFn[];
   /** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
   readonly signature: string;
   /**
    * The adapter-level capabilities that can change after construction (geo
-   * support, calendar-bucket units): an index whose {@link signature}
-   * differs from this is stale. Any new adapter-level input the index reads
-   * must be added here.
+   * support, calendar-bucket units, aggregate functions): an index whose
+   * {@link signature} differs from this is stale. Any new adapter-level input
+   * the index reads must be added here.
    */
-  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits">): string;
+  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns">): string;
   private readonly _entries;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
@@ -324,12 +326,34 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
+/** Read endpoint a {@link AsDbReadableController.decorateRows} call serves. */
+type TDbDecorateEndpoint = "query" | "pages" | "geo" | "one";
+/**
+ * Context passed to {@link AsDbReadableController.decorateRows}.
+ *
+ * @since 0.1.136
+ */
+interface TDbDecorateContext {
+  /** Endpoint that produced the rows. `/one` and `/one/:id` both report `"one"`. */
+  endpoint: TDbDecorateEndpoint;
+  /**
+   * The effective `$select` the endpoint read with — after
+   * `transformProjection`, the `@db.writeOnly` seal and preferred-id
+   * widening (`undefined` = no projection). Columns added only to feed an
+   * action's `requiredFields` are stripped again before the hook runs.
+   */
+  projection: UniqueryControls["$select"] | undefined;
+  /** The request's parsed controls (`$select`, `$with`, `$actions`, …). Read-only by convention. */
+  controls: Record<string, unknown>;
+}
 /**
  * Read-only database controller for Moost that works with any `AtscriptDbReadable`
  * (tables or views). Provides query, pages, getOne, and meta endpoints.
  *
  * For write operations (insert, replace, update, delete), use {@link AsDbController}.
- * For views, use {@link AsDbViewController}.
+ * Views bind to this same class — `@ViewController(view)` (an alias of
+ * `@ReadableController`) or a constructor-passed view; there is no separate
+ * view controller.
  */
 declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
   /** Reference to the underlying readable (table or view). */
@@ -370,6 +394,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _idSources;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
+  /** `true` when a subclass implements {@link decorateRows} (the override switches the hook on). */
+  private readonly _decorates;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   private readonly _quantityRefByPath;
   /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -435,7 +461,7 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   }): HttpError | undefined;
   /**
    * The core's shared normalizer of `$select` computed entries
-   * (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+   * (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
    * (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
    * week start / alias, "grouped queries only", "must also appear in
    * $groupBy", alias collisions with this table's fields. Runs once per
@@ -551,11 +577,45 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _aggregateControls;
   private _resolveReadStrategy;
   /**
-   * Shared `query` / `pages` pipeline: prepare actions augmentation + read
+   * Post-read row decoration hook. Not implemented by
+   * default — defining it in a subclass switches it on. Runs once per
+   * response on `/query`, `/pages`, `/geo` and `/one` (`/one/:id` and the
+   * composite form), after `$actions` augmentation, with the final top-level
+   * rows. Mutate the rows in place; the return value is ignored. May be async.
+   *
+   * Not called for `$count`, `$groupBy` aggregates, nested `$with` rows
+   * (reach them through the parent row), a `/one` 404, or value-help
+   * controllers.
+   *
+   * Convention (not enforced): name decoration keys with a `$` prefix, like
+   * `$actions` and `$distance`, so they can never collide with a field name.
+   * Do not overwrite `$actions`. Columns the
+   * hook needs but the client did not select must be added in
+   * {@link transformProjection} — they are then part of the response.
+   *
+   * ```ts
+   * protected async decorateRows(rows: Record<string, unknown>[], ctx: TDbDecorateContext) {
+   *   const unread = await countUnread(rows.map((r) => r.id))
+   *   for (const row of rows) row.$unread = unread.get(row.id) ?? 0
+   * }
+   * ```
+   *
+   * @since 0.1.136
+   */
+  protected decorateRows?(rows: Record<string, unknown>[], ctx: TDbDecorateContext): void | Promise<void>;
+  /**
+   * Finishes a read's top-level rows in place: `$actions` augmentation (when
+   * the request asked for it — `prep`), then {@link decorateRows} when a
+   * subclass implements it. Returns the hook's result — `undefined`, with no
+   * promise or microtask, when there is no hook or it is synchronous.
+   */
+  private _finishRows;
+  /**
+   * Shared `query` / `pages` / `geo` pipeline: prepare actions augmentation + read
    * strategy in parallel, pre-widen $select for `requiredFields`, run
    * `exec`, and augment `result.data` with `$actions` when the request set
-   * `$actions=true`. Caller dispatches the strategy to its read-method
-   * family (count vs no-count).
+   * `$actions=true`, then run {@link decorateRows}. Caller dispatches the
+   * strategy to its read-method family (count vs no-count).
    */
   private _runReadWithActions;
   /**
@@ -1006,7 +1066,7 @@ interface LooseGate {
   onDisabledRows?: TOnDisabledRows;
 }
 type GateOpts<TRow, R extends readonly FlatKey<TRow>[]> = unknown extends TRow ? LooseGate : NoGate | WithGate<TRow, R>;
-interface BaseActionOpts extends Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled">> {
+interface BaseActionOpts extends Partial<Omit<TDbActionInfo$1, "name" | "level" | "processor" | "value" | "disabled" | "formUrl">> {
   /**
    * Bound table reference. REQUIRED on non-`AsDbReadableController` classes
    * when `disabled` is set OR a `@DbActionRow*` parameter is declared.
@@ -1035,6 +1095,25 @@ interface DbActionsEntryCommonBase {
   promptText?: string | [string, string];
   /** Mirrors {@link TDbActionInfo.shortcut} — single-character UI hint. */
   shortcut?: string;
+  /**
+   * Input form the UI collects before invoking the action:
+   *
+   * - a compiled `.as` interface — registered on THIS controller and served
+   *   by its own `GET /meta/form/:name`; the wire carries `inputForm: Type.name`.
+   * - `{ name, url }` — a form served elsewhere: `name` goes on the wire as
+   *   `inputForm`, `url` (server-absolute path of the serialized schema, e.g.
+   *   `"/api/shipping/meta/form/ShipForm"`) as {@link TDbActionInfo.formUrl}.
+   *
+   * Not allowed with `processor: 'navigate'`. Class-level entries only
+   * describe the action — validating `input` is the target handler's job
+   * (e.g. its own `@InputForm(Type)` param).
+   *
+   * @since 0.1.136
+   */
+  inputForm?: TAtscriptAnnotatedType | {
+    name: string;
+    url: string;
+  };
 }
 type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbActionsEntryCommonBase & GateOpts<TRow, R>;
 /**
@@ -1048,6 +1127,7 @@ type DbActionsEntryWithGate<TRow, R extends readonly FlatKey<TRow>[]> = DbAction
 type TDbActionsEntry<TRow = unknown, R extends readonly FlatKey<TRow>[] = []> = (DbActionsEntryWithGate<TRow, R> & {
   processor: "navigate";
   value: string;
+  inputForm?: never;
 }) | (DbActionsEntryWithGate<TRow, R> & {
   processor: "custom";
   value?: never;
@@ -1721,4 +1801,4 @@ declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef |
  */
 declare function applyTerminalRefs(serialized: TSerializedAnnotatedType, runtime: TAtscriptAnnotatedType, options: TSerializeOptions): TSerializedAnnotatedType;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActions, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, TABLE_DEF, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbClassActionMeta, TDbDecorateContext, TDbDecorateEndpoint, type TDbRemoveGuardContext, type TDbWriteAction, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { ValidatorError, defineAnnotatedType, isAnnotatedType, serializeAnnotate
 import { Body, Delete, Get, HttpError, Patch, Post, Put, Query, Url } from "@moostjs/event-http";
 import { ApplyDecorators, Controller, Inherit, Inject, Intercept, Moost, Optional, Param, Provide, Resolve, TInterceptorPriority, defineBeforeInterceptor, defineInterceptor, getMoostMate, useControllerContext } from "moost";
 import { parseUrl } from "@uniqu/url";
-import { ADAPTER_FILTER_REASON, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, reconcileCas, resolveCalendarBuckets, unsupportedOperatorMessage } from "@atscript/db";
+import { ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, DbError, ENCRYPTED_REASON, acceptedOperatorsHint, bucketSourceVerdict, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, collectQueryPaths as collectQueryPaths$1, findAncestorInSet, isJsonValueField, isPlainObject, narrowerFilterOps, normalizeComputedSelect, reconcileCas, unsupportedOperatorMessage } from "@atscript/db";
 import { BUCKET_UNITS } from "@uniqu/core";
 import { buildMemoryPredicate, projectRow, sortRows } from "@atscript/db-memory";
 import { cached, current, defineWook, key } from "@wooksjs/event-core";
@@ -250,7 +250,8 @@ const rowLevelActionsCache = /* @__PURE__ */ new WeakMap();
 /**
 * Per-controller registry of form names → compiled `.as` classes, populated
 * during {@link discoverActions} when a method param carries
-* `atscript_db_action_input_form`. Backs `GET /meta/form/:name`.
+* `atscript_db_action_input_form` or a class-level entry passes a type as
+* `inputForm`. Backs `GET /meta/form/:name`.
 *
 * Same name + same type ref across multiple actions is fine (forms can be
 * reused). Same name + *different* type refs is an ambiguity — discovery
@@ -394,7 +395,7 @@ function collectClassActions(ctor, logger, out, seen) {
 			logger.warn(`${WARN_PREFIX} duplicate action name "${name}" within controller — dropping the second declaration`);
 			continue;
 		}
-		const built = buildClassEntry(name, entry, logger);
+		const built = buildClassEntry(ctor, name, entry, logger);
 		if (built) {
 			seen.add(name);
 			out.push({
@@ -404,7 +405,7 @@ function collectClassActions(ctor, logger, out, seen) {
 		}
 	}
 }
-function buildClassEntry(name, entry, logger) {
+function buildClassEntry(ctor, name, entry, logger) {
 	const level = entry.level;
 	if (!level) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" requires a level — dropping. Use @DbTableActions/@DbRowActions/@DbRowsActions or set "level" explicitly.`);
@@ -442,6 +443,8 @@ function buildClassEntry(name, entry, logger) {
 		logger.warn(`${WARN_PREFIX} class-level action "${name}" has unknown processor "${String(processor)}" — dropping`);
 		return null;
 	}
+	const form = resolveClassInputForm(name, entry, processor, logger);
+	if (form === null) return null;
 	const info = {
 		name,
 		label: entry.label,
@@ -449,9 +452,45 @@ function buildClassEntry(name, entry, logger) {
 		processor,
 		value
 	};
+	if (form) {
+		if (form.type && !registerFormType(ctor, {
+			type: form.type,
+			name: form.name
+		}, name, logger)) return null;
+		info.inputForm = form.name;
+		if (form.url !== void 0) info.formUrl = form.url;
+	}
 	emitInfo(info, entry);
 	return info;
 }
+/**
+* Resolves a class-level entry's `inputForm`. Returns `undefined` when the
+* entry declares none, `null` when it must be dropped (already warned — the
+* runtime check for JS callers and `processor: "navigate"`), else the form to
+* emit: `type` when this controller serves it (`/meta/form/:name`), `url`
+* when it lives elsewhere.
+*/
+function resolveClassInputForm(name, entry, processor, logger) {
+	const inputForm = entry.inputForm;
+	if (inputForm === void 0) return void 0;
+	const drop = (reason) => {
+		logger.warn(`${WARN_PREFIX} class-level action "${name}" — ${reason} — dropping`);
+		return null;
+	};
+	if (processor === "navigate") return drop("processor \"navigate\" cannot take an `inputForm`");
+	const { name: formName, url } = inputForm ?? {};
+	if (typeof formName === "string" && formName !== "") {
+		if (isAnnotatedType(inputForm)) return {
+			name: formName,
+			type: inputForm
+		};
+		if (typeof url === "string" && url !== "") return {
+			name: formName,
+			url
+		};
+	}
+	return drop("`inputForm` must be a compiled .as interface or `{ name, url }` (non-empty strings)");
+}
 function applyDefaultPerLevel(envelopes, logger) {
 	const winners = /* @__PURE__ */ new Map();
 	for (const { info } of envelopes) {
@@ -976,6 +1015,11 @@ function computeStripFields(candidates, resolvedProjection) {
 	}
 	return strip;
 }
+/**
+* Sets `$actions` on every row and strips the columns fetched only for an
+* action's `requiredFields` — IN PLACE; returns the same array, typed as
+* augmented.
+*/
 function augmentRowsWithActions(args) {
 	const { envelopes, rows, resolvedProjection } = args;
 	const candidates = collectCandidates(envelopes);
@@ -1223,16 +1267,18 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 	physicalNames;
 	/** Calendar-bucket units the adapter groups by, in `BUCKET_UNITS` order (`/meta.bucketUnits`). */
 	bucketUnits;
+	/** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
+	aggregateFns;
 	/** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
 	signature;
 	/**
 	* The adapter-level capabilities that can change after construction (geo
-	* support, calendar-bucket units): an index whose {@link signature}
-	* differs from this is stale. Any new adapter-level input the index reads
-	* must be added here.
+	* support, calendar-bucket units, aggregate functions): an index whose
+	* {@link signature} differs from this is stale. Any new adapter-level input
+	* the index reads must be added here.
 	*/
 	static adapterSignature(source) {
-		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}`;
+		return `${source.isGeoSearchable()}|${[...source.calendarBucketUnits()].join(",")}|${[...source.aggregateFns()].join(",")}`;
 	}
 	_entries = /* @__PURE__ */ new Map();
 	/** Nested-object parents (never listed, always selectable) → their listed leaves. */
@@ -1255,6 +1301,8 @@ var FieldCapabilityIndex = class FieldCapabilityIndex {
 		this.signature = FieldCapabilityIndex.adapterSignature(source);
 		const units = source.calendarBucketUnits();
 		this.bucketUnits = BUCKET_UNITS.filter((unit) => units.has(unit));
+		const fns = source.aggregateFns();
+		this.aggregateFns = [...ALL_AGGREGATE_FNS].filter((fn) => fns.has(fn));
 		const physicalNames = /* @__PURE__ */ new Set();
 		const jsonValueParents = /* @__PURE__ */ new Set();
 		for (const fd of source.fieldDescriptors) {
@@ -1551,6 +1599,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	_idSources = /* @__PURE__ */ new Map();
 	_preferredIdSet;
 	_overlayIsNoOp;
+	/** `true` when a subclass implements {@link decorateRows} (the override switches the hook on). */
+	_decorates;
 	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
 	_quantityRefByPath;
 	/** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
@@ -1574,6 +1624,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		this._quantityRefByPath = this._collectQuantityRefs();
 		const defaultOverlay = AsReadableController.prototype.applyMetaOverlay;
 		this._overlayIsNoOp = this.applyMetaOverlay === defaultOverlay;
+		this._decorates = typeof this.decorateRows === "function";
 		this._idOpts = this.hasField === _AsDbReadableController.prototype.hasField ? void 0 : { isFieldVisible: this._exists };
 	}
 	/**
@@ -1680,7 +1731,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	}
 	/**
 	* The core's shared normalizer of `$select` computed entries
-	* (`resolveCalendarBuckets`) as a 400 with the core's wording and `path`
+	* (`normalizeComputedSelect`) as a 400 with the core's wording and `path`
 	* (`$select` / `$groupBy`): entry shapes, calendar-bucket unit / zone /
 	* week start / alias, "grouped queries only", "must also appear in
 	* $groupBy", alias collisions with this table's fields. Runs once per
@@ -1692,7 +1743,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 	checkComputedSelect(controls) {
 		const capabilities = this.capabilities;
 		try {
-			resolveCalendarBuckets(controls, {
+			normalizeComputedSelect(controls, {
 				flatMap: this.readable.flatMap,
 				physicalNames: capabilities.physicalNames,
 				navFields: capabilities.navFields
@@ -2049,13 +2100,27 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		return { kind: "plain" };
 	}
 	/**
-	* Shared `query` / `pages` pipeline: prepare actions augmentation + read
+	* Finishes a read's top-level rows in place: `$actions` augmentation (when
+	* the request asked for it — `prep`), then {@link decorateRows} when a
+	* subclass implements it. Returns the hook's result — `undefined`, with no
+	* promise or microtask, when there is no hook or it is synchronous.
+	*/
+	_finishRows(rows, prep, ctx) {
+		if (prep) augmentRowsWithActions({
+			envelopes: prep.envelopes,
+			rows,
+			resolvedProjection: prep.resolvedProjection
+		});
+		return this._decorates ? this.decorateRows(rows, ctx) : void 0;
+	}
+	/**
+	* Shared `query` / `pages` / `geo` pipeline: prepare actions augmentation + read
 	* strategy in parallel, pre-widen $select for `requiredFields`, run
 	* `exec`, and augment `result.data` with `$actions` when the request set
-	* `$actions=true`. Caller dispatches the strategy to its read-method
-	* family (count vs no-count).
+	* `$actions=true`, then run {@link decorateRows}. Caller dispatches the
+	* strategy to its read-method family (count vs no-count).
 	*/
-	async _runReadWithActions(queryObj, controls, select, exec) {
+	async _runReadWithActions(endpoint, queryObj, controls, select, exec) {
 		const [prep, strategy] = await Promise.all([this._prepareAugmentation(controls, select), this._resolveReadStrategy(controls)]);
 		const result = await exec(prep?.widenedSelect ? {
 			...queryObj,
@@ -2064,12 +2129,12 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$select: prep.widenedSelect
 			}
 		} : queryObj, strategy);
-		if (!prep) return result;
-		result.data = augmentRowsWithActions({
-			envelopes: prep.envelopes,
-			rows: result.data,
-			resolvedProjection: prep.resolvedProjection
+		const pending = this._finishRows(result.data, prep, {
+			endpoint,
+			projection: select,
+			controls
 		});
+		if (pending) await pending;
 		return result;
 	}
 	/**
@@ -2141,7 +2206,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$threshold: threshold
 			}
 		};
-		return (await this._runReadWithActions(queryObj, controls, select, async (q, strategy) => {
+		return (await this._runReadWithActions("query", queryObj, controls, select, async (q, strategy) => {
 			switch (strategy.kind) {
 				case "vector": return { data: await (strategy.vectorField ? this.readable.vectorSearch(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearch(strategy.vector, q)) };
 				case "search": return { data: await this.readable.search(strategy.term, q, strategy.index) };
@@ -2179,7 +2244,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				$threshold: threshold
 			}
 		};
-		const result = await this._runReadWithActions(query, controls, select, async (q, strategy) => {
+		const result = await this._runReadWithActions("pages", query, controls, select, async (q, strategy) => {
 			switch (strategy.kind) {
 				case "vector": return strategy.vectorField ? this.readable.vectorSearchWithCount(strategy.vectorField, strategy.vector, q) : this.readable.vectorSearchWithCount(strategy.vector, q);
 				case "search": return this.readable.searchWithCount(strategy.term, q, strategy.index);
@@ -2244,7 +2309,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			}
 		};
 		if (paginated) {
-			const result = await this._runReadWithActions(queryObj, controls, select, async (q) => indexName ? this.readable.geoSearchWithCount(indexName, point, q) : this.readable.geoSearchWithCount(point, q));
+			const result = await this._runReadWithActions("geo", queryObj, controls, select, async (q) => indexName ? this.readable.geoSearchWithCount(indexName, point, q) : this.readable.geoSearchWithCount(point, q));
 			return {
 				data: result.data,
 				page,
@@ -2253,7 +2318,7 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 				count: result.count
 			};
 		}
-		return (await this._runReadWithActions(queryObj, controls, select, async (q) => ({ data: await (indexName ? this.readable.geoSearch(indexName, point, q) : this.readable.geoSearch(point, q)) }))).data;
+		return (await this._runReadWithActions("geo", queryObj, controls, select, async (q) => ({ data: await (indexName ? this.readable.geoSearch(indexName, point, q) : this.readable.geoSearch(point, q)) }))).data;
 	}
 	/** Parses the `$center` control: `"lng,lat"` string (or tuple) → `[number, number]`. */
 	_parseGeoCenter(raw) {
@@ -2328,13 +2393,13 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 		}
 		const item = await this.returnOne(Promise.resolve(row));
 		if (item instanceof HttpError) return item;
-		if (!prep) return item;
-		const [augmented] = augmentRowsWithActions({
-			envelopes: prep.envelopes,
-			rows: [item],
-			resolvedProjection: prep.resolvedProjection
+		const pending = this._finishRows([item], prep, {
+			endpoint: "one",
+			projection: select,
+			controls: parsedControls
 		});
-		return augmented;
+		if (pending) await pending;
+		return item;
 	}
 	/**
 	* **GET /meta** — returns table/view metadata for UI.
@@ -2382,7 +2447,8 @@ let AsDbReadableController = _AsDbReadableController = class AsDbReadableControl
 			actions: this.buildActions(),
 			crud: this.buildCrud(),
 			versionColumn: this.readable.versionColumn,
-			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] }
+			...capabilities.bucketUnits.length > 0 && { bucketUnits: [...capabilities.bucketUnits] },
+			aggregateFns: [...capabilities.aggregateFns]
 		};
 	}
 	buildCrud() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/moost-db",
-  "version": "0.1.134",
+  "version": "0.1.136",
   "description": "Generic database controller for Moost with Atscript.",
   "keywords": [
     "annotations",
@@ -43,14 +43,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/url": "^0.1.10",
-    "@atscript/db-memory": "^0.1.134"
+    "@uniqu/url": "^0.1.11",
+    "@atscript/db-memory": "^0.1.136"
   },
   "devDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
     "@moostjs/event-http": "^0.6.37",
-    "@uniqu/core": "^0.1.10",
+    "@uniqu/core": "^0.1.11",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/event-http": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
@@ -60,11 +60,11 @@
   "peerDependencies": {
     "@atscript/typescript": "^0.1.92",
     "@moostjs/event-http": "^0.6.37",
-    "@uniqu/core": "^0.1.10",
+    "@uniqu/core": "^0.1.11",
     "@wooksjs/event-core": "^0.7.23",
     "@wooksjs/http-body": "^0.7.23",
     "moost": "^0.6.37",
-    "@atscript/db": "^0.1.134"
+    "@atscript/db": "^0.1.136"
   },
   "scripts": {
     "postinstall": "asc -f dts",