@atscript/moost-db 0.1.53 → 0.1.55

package/dist/index.d.cts

@@ -6,29 +6,66 @@ import { HttpError } from "@moostjs/event-http";
 import * as moost from "moost";
 import { Moost, TConsoleBase } from "moost";
 
-//#region src/as-db-readable.controller.d.ts
+//#region src/as-readable.controller.d.ts
 /**
- * Read-only database controller for Moost that works with any `AtscriptDbReadable`
- * (tables or views). Provides query, pages, getOne, and meta endpoints.
+ * Optional gate configuration for a single request. Each present entry enables
+ * the corresponding check; omitted entries skip that gate entirely.
+ */
+interface ReadableGates {
+  filter?: {
+    predicate: (field: string) => boolean;
+    annotation: string;
+  };
+  sort?: {
+    predicate: (field: string) => boolean;
+    annotation: string;
+  };
+  search?: {
+    allowed: boolean;
+    rejectionMessage: string;
+  };
+}
+/**
+ * Abstract base class for read-only HTTP controllers over an Atscript interface.
  *
- * For write operations (insert, replace, update, delete), use {@link AsDbController}.
- * For views, use {@link AsDbViewController}.
+ * Shared responsibilities (implemented here):
+ * - Stamps `@db.http.path` on the bound interface's metadata at registration
+ *   with the final public path (leading slash + Moost `globalPrefix`).
+ * - Lazily serializes the bound interface for the `/meta` endpoint
+ *   (see {@link getSerializeOptions}).
+ * - Provides DTO-backed validators for the Uniquery controls DTOs and the
+ *   helpers (`parseQueryString`, `returnOne`, `validateParsed`, etc.) that
+ *   subclasses share.
+ * - Registers the `/meta` route. Subclasses override {@link buildMetaResponse}
+ *   to shape the payload; DB-backed readables add relations/searchable flags,
+ *   value-help controllers add their capability hints.
+ *
+ * Subclass responsibilities:
+ * - Pass the bound interface + logical name + (optional) kind tag through super().
+ * - Implement {@link hasField} so insights validation can reject unknown keys.
+ * - Register the `/query`, `/pages`, `/one(/:id)` routes with the concrete
+ *   handlers that match the data source's contract (DB readables route into
+ *   aggregate/vector/search; value-help controllers just filter/sort/paginate).
  */
-declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
-  /** Reference to the underlying readable (table or view). */
-  protected readable: AtscriptDbReadable<T>;
+declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+  /** The Atscript interface this controller serves. */
+  protected readonly boundType: T;
+  /** Short human-readable name for logging (usually the table/source name). */
+  protected readonly controllerName: string;
   /** Application-scoped logger. */
   protected logger: TConsoleBase;
-  /** Cached serialized type definition (lazy, computed on first access). */
-  private _serializedType?;
   /** Moost application instance. */
   protected app: Moost;
+  /** Cached serialized type definition (lazy, computed on first access). */
+  private _serializedType?;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
-  constructor(readable: AtscriptDbReadable<T>, app: Moost);
+  constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
+  /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
+  protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
-  /** Lazily serializes the type (after all controllers have set their @db.http.path). */
+  /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
   protected getSerializedType(): _atscript_typescript_utils0.TSerializedAnnotatedType;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
@@ -36,14 +73,24 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected init(): void | Promise<void>;
   /**
    * Returns serialization options for the `/meta` endpoint's type field.
-   * Default: whitelist — keeps `meta.*`, `expect.*`, and `db.rel.*` annotations,
-   * strips all other `db.*` annotations (table, column, index, default, etc.).
-   * Override in subclass to customise what annotations are exposed to clients.
+   *
+   * `refDepth: 0.5` is intentionally static — independent of `@db.depth.limit`
+   * (which is a security guard on nested writes, not a serialization policy).
+   * The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
+   * which carries the target's `db.http.path` so clients can resolve value-help
+   * URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
+   * props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
+   * and always expand fully regardless of `refDepth` — the write-payload shape
+   * clients need is unaffected.
+   *
+   * Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
+   * other `db.*` (table, column, index, default, etc.). Override in subclass
+   * to customise.
    */
   protected getSerializeOptions(): TSerializeOptions;
   /**
    * Whether this controller is read-only (no write endpoints).
-   * Returns `true` for readable/view controllers, overridden to `false` in AsDbController.
+   * Returns `true` by default; {@link AsDbController} overrides to `false`.
    */
   protected _isReadOnly(): boolean;
   private _queryControlsValidator?;
@@ -55,6 +102,49 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
   protected validateInsights(insights: Map<string, unknown>): string | undefined;
   protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
+  /**
+   * Shared filter/sort/search gate check. Subclasses assemble a {@link ReadableGates}
+   * config per request (or once in the constructor when static) and call this to
+   * get a uniform HTTP 400 response for any offending field/control.
+   */
+  protected checkGates(filter: FilterExpr | undefined, controls: Record<string, unknown>, gates: ReadableGates): HttpError | undefined;
+  protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
+  protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
+  /**
+   * **GET /meta** — returns the bound interface's metadata envelope.
+   *
+   * Base implementation delegates to {@link buildMetaResponse}, which subclasses
+   * override to add source-specific fields (relations, searchable flags, etc.).
+   * The response is cached on the instance; async overrides must cache any
+   * extra enrichment themselves.
+   */
+  meta(): Promise<TMetaResponse>;
+  /**
+   * Builds the `/meta` payload. Override in subclasses to populate source-specific
+   * fields. Defaults return a minimal envelope with the serialized type and the
+   * read-only flag; value-help dicts populate their capability hints here.
+   */
+  protected buildMetaResponse(): Promise<TMetaResponse>;
+}
+//#endregion
+//#region src/as-db-readable.controller.d.ts
+/**
+ * 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}.
+ */
+declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
+  /** Reference to the underlying readable (table or view). */
+  protected readable: AtscriptDbReadable<T>;
+  private readonly _gates;
+  constructor(readable: AtscriptDbReadable<T>, app: Moost);
+  private _buildGates;
+  private _collectAnnotated;
+  protected hasField(path: string): boolean;
+  /** Validates $with relations against the readable. */
+  protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
   /**
    * Compute an embedding vector from a search term.
    * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
@@ -71,8 +161,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * May return a Promise for async lookups.
    */
   protected transformProjection(projection?: UniqueryControls["$select"]): UniqueryControls["$select"] | undefined | Promise<UniqueryControls["$select"] | undefined>;
-  protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
-  protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
    * Extracts a composite identifier object from query params.
    * Tries composite primary key first, then compound unique indexes.
@@ -104,12 +192,11 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /**
    * **GET /meta** — returns table/view metadata for UI.
    *
-   * The return type includes `Promise<...>` so subclasses can override with an
-   * async implementation (e.g. to enrich the payload from an external source).
-   * The base cache only covers the base payload — async overrides must cache
-   * their own enrichment if needed.
+   * Overrides the base's minimal envelope to add relations, searchable flags,
+   * vector-searchable flags, field-descriptor-derived filter/sort hints, and
+   * the configured primary keys.
    */
-  meta(): TMetaResponse | Promise<TMetaResponse>;
+  protected buildMetaResponse(): Promise<TMetaResponse>;
 }
 //#endregion
 //#region src/as-db.controller.d.ts
@@ -161,6 +248,132 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   removeComposite(query: Record<string, string>): Promise<unknown>;
 }
 //#endregion
+//#region src/as-value-help.controller.d.ts
+/**
+ * Parsed Uniquery controls with the `$search` field carved out for value-help
+ * use (the core DTO includes it but we narrow the type here so implementations
+ * can rely on the concrete shape).
+ */
+interface ValueHelpQuery<T> {
+  filter: FilterExpr;
+  controls: {
+    $skip?: number;
+    $limit?: number;
+    $search?: string;
+    $select?: (keyof T | string)[];
+    $sort?: unknown;
+    [key: string]: unknown;
+  };
+}
+/**
+ * Abstract base class for read-only HTTP controllers serving a **value-help**
+ * source — an interface bound to a simple `/query` / `/pages` / `/one(/:id)` /
+ * `/meta` surface, not a full DB table. Value-help controllers drive the
+ * client-side picker UI on fields annotated `@db.rel.FK`.
+ *
+ * Subclass responsibilities:
+ * - Pass the bound interface + rows/backing-source through super().
+ * - Implement the abstract {@link query} and {@link getOne} methods.
+ *
+ * The bound interface's `@ui.dict.*` annotations are **client-side hints**
+ * consumed by the picker UI; the server does not gate filter / sort / search
+ * requests against them. Subclasses that need a backend gate should compose
+ * one of their own (see {@link AsDbReadableController} for the
+ * `@db.column.filterable` / `@db.column.sortable` pattern).
+ */
+declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
+  /** Per-prop metadata map of the bound interface; eagerly built once. */
+  protected readonly fieldMeta: Map<string, Map<string, unknown>>;
+  /**
+   * Fields that participate in `$search` by default. Populated from
+   * `@ui.dict.searchable`:
+   * - If any prop carries `@ui.dict.searchable`, only those props are here.
+   * - Else if the interface carries `@ui.dict.searchable`, every `string`-typed prop is here.
+   * - Else every `string`-typed prop is here (hint is absent — default to all strings).
+   */
+  protected readonly searchableFields: readonly string[];
+  /** The `@meta.id` field name on the bound interface, if any. */
+  protected readonly primaryKey: string | undefined;
+  constructor(boundType: T, controllerName: string, app: Moost);
+  /** Executes a value-help query against the backing source. */
+  protected abstract query(controls: ValueHelpQuery<DataType>): Promise<{
+    data: DataType[];
+    count: number;
+  }>;
+  /** Returns the row whose primary key matches `id`, or `null` on miss. */
+  protected abstract getOne(id: string | number): Promise<DataType | null>;
+  protected hasField(path: string): boolean;
+  /**
+   * **GET /query** — returns an array of matched rows (up to `$limit`).
+   */
+  runQuery(url: string): Promise<DataType[] | HttpError>;
+  /**
+   * **GET /pages** — paginated row window plus total count.
+   */
+  runPages(url: string): Promise<{
+    data: DataType[];
+    page: number;
+    itemsPerPage: number;
+    pages: number;
+    count: number;
+  } | HttpError>;
+  /**
+   * **GET /one/:id** — retrieves a single row by primary key.
+   */
+  runGetOne(id: string): Promise<DataType | HttpError>;
+  /**
+   * **GET /one?<pk>=<val>** — retrieves a single row by PK query param (fallback).
+   */
+  runGetOneComposite(query: Record<string, string>): Promise<DataType | HttpError>;
+  /**
+   * Meta response surfaces `@ui.dict.*` annotations as **hints** for the
+   * client picker UI (which controls to render); the server does not enforce
+   * these flags at request time.
+   */
+  protected buildMetaResponse(): Promise<TMetaResponse>;
+}
+//#endregion
+//#region src/as-json-value-help.controller.d.ts
+/**
+ * Concrete value-help controller backed by a static in-memory array. Provides
+ * filter/sort/search/paginate over the provided rows, respecting the
+ * `@ui.dict.*` capability annotations on the bound interface.
+ *
+ * **Semantics:**
+ * - Filter is interpreted as a subset of MongoDB-style comparison operators
+ *   (`$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$regex`) and
+ *   logical combinators (`$and`, `$or`, `$not`, `$nor`). Unknown operators
+ *   fall through to strict equality.
+ * - Sort is stable, multi-key, lexicographic. Direction via `-` prefix on the
+ *   field name or `{ [field]: 'asc' | 'desc' }`.
+ * - Search is case-insensitive substring matching across every field listed in
+ *   {@link searchableFields}.
+ * - Type coercion: comparisons compare raw JS values (no implicit string-to-
+ *   number coercion); strings are compared case-insensitively only for
+ *   `$search`, not for filter operators.
+ *
+ * **Constructor:**
+ * ```ts
+ * new AsJsonValueHelpController(StatusDict, [
+ *   { id: 'active', label: 'Active' },
+ *   { id: 'archived', label: 'Archived' },
+ * ], app);
+ * ```
+ *
+ * Register under a Moost path with `@Controller('/api/dicts/status')` or the
+ * equivalent composition decorator.
+ */
+declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsValueHelpController<T, DataType> {
+  protected rows: DataType[];
+  private _pkIndex?;
+  constructor(boundType: T, rows: DataType[], app: Moost, controllerName?: string);
+  protected query(controls: ValueHelpQuery<DataType>): Promise<{
+    data: DataType[];
+    count: number;
+  }>;
+  protected getOne(id: string | number): Promise<DataType | null>;
+}
+//#endregion
 //#region src/decorators.d.ts
 /**
  * DI token under which the {@link AtscriptDbReadable} instance
@@ -223,4 +436,4 @@ declare const ViewController: (readable: AtscriptDbReadable, prefix?: string) =>
 declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
-export { AsDbController, AsDbReadableController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, validationErrorTransform };

package/dist/index.d.mts

@@ -6,29 +6,66 @@ import { Moost, TConsoleBase } from "moost";
 import * as _uniqu_url0 from "@uniqu/url";
 import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
 
-//#region src/as-db-readable.controller.d.ts
+//#region src/as-readable.controller.d.ts
 /**
- * Read-only database controller for Moost that works with any `AtscriptDbReadable`
- * (tables or views). Provides query, pages, getOne, and meta endpoints.
+ * Optional gate configuration for a single request. Each present entry enables
+ * the corresponding check; omitted entries skip that gate entirely.
+ */
+interface ReadableGates {
+  filter?: {
+    predicate: (field: string) => boolean;
+    annotation: string;
+  };
+  sort?: {
+    predicate: (field: string) => boolean;
+    annotation: string;
+  };
+  search?: {
+    allowed: boolean;
+    rejectionMessage: string;
+  };
+}
+/**
+ * Abstract base class for read-only HTTP controllers over an Atscript interface.
  *
- * For write operations (insert, replace, update, delete), use {@link AsDbController}.
- * For views, use {@link AsDbViewController}.
+ * Shared responsibilities (implemented here):
+ * - Stamps `@db.http.path` on the bound interface's metadata at registration
+ *   with the final public path (leading slash + Moost `globalPrefix`).
+ * - Lazily serializes the bound interface for the `/meta` endpoint
+ *   (see {@link getSerializeOptions}).
+ * - Provides DTO-backed validators for the Uniquery controls DTOs and the
+ *   helpers (`parseQueryString`, `returnOne`, `validateParsed`, etc.) that
+ *   subclasses share.
+ * - Registers the `/meta` route. Subclasses override {@link buildMetaResponse}
+ *   to shape the payload; DB-backed readables add relations/searchable flags,
+ *   value-help controllers add their capability hints.
+ *
+ * Subclass responsibilities:
+ * - Pass the bound interface + logical name + (optional) kind tag through super().
+ * - Implement {@link hasField} so insights validation can reject unknown keys.
+ * - Register the `/query`, `/pages`, `/one(/:id)` routes with the concrete
+ *   handlers that match the data source's contract (DB readables route into
+ *   aggregate/vector/search; value-help controllers just filter/sort/paginate).
  */
-declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
-  /** Reference to the underlying readable (table or view). */
-  protected readable: AtscriptDbReadable<T>;
+declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+  /** The Atscript interface this controller serves. */
+  protected readonly boundType: T;
+  /** Short human-readable name for logging (usually the table/source name). */
+  protected readonly controllerName: string;
   /** Application-scoped logger. */
   protected logger: TConsoleBase;
-  /** Cached serialized type definition (lazy, computed on first access). */
-  private _serializedType?;
   /** Moost application instance. */
   protected app: Moost;
+  /** Cached serialized type definition (lazy, computed on first access). */
+  private _serializedType?;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
-  constructor(readable: AtscriptDbReadable<T>, app: Moost);
+  constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
+  /** Subclass contract: return `true` if `path` addresses a valid field on the bound source. */
+  protected abstract hasField(path: string): boolean;
   /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
   private _resolveHttpPath;
-  /** Lazily serializes the type (after all controllers have set their @db.http.path). */
+  /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
   protected getSerializedType(): _atscript_typescript_utils0.TSerializedAnnotatedType;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
@@ -36,14 +73,24 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected init(): void | Promise<void>;
   /**
    * Returns serialization options for the `/meta` endpoint's type field.
-   * Default: whitelist — keeps `meta.*`, `expect.*`, and `db.rel.*` annotations,
-   * strips all other `db.*` annotations (table, column, index, default, etc.).
-   * Override in subclass to customise what annotations are exposed to clients.
+   *
+   * `refDepth: 0.5` is intentionally static — independent of `@db.depth.limit`
+   * (which is a security guard on nested writes, not a serialization policy).
+   * The shallow shape emits `{ field, type: { id, metadata } }` for every FK,
+   * which carries the target's `db.http.path` so clients can resolve value-help
+   * URLs and lazy-fetch target `/meta` when deeper structure is needed. Nav
+   * props (`@db.rel.from` / `@db.rel.to` / `@db.rel.via`) are not `.ref` nodes
+   * and always expand fully regardless of `refDepth` — the write-payload shape
+   * clients need is unaffected.
+   *
+   * Annotation whitelist: keeps `meta.*`, `expect.*`, and `db.rel.*`; strips
+   * other `db.*` (table, column, index, default, etc.). Override in subclass
+   * to customise.
    */
   protected getSerializeOptions(): TSerializeOptions;
   /**
    * Whether this controller is read-only (no write endpoints).
-   * Returns `true` for readable/view controllers, overridden to `false` in AsDbController.
+   * Returns `true` by default; {@link AsDbController} overrides to `false`.
    */
   protected _isReadOnly(): boolean;
   private _queryControlsValidator?;
@@ -55,6 +102,49 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
   protected validateInsights(insights: Map<string, unknown>): string | undefined;
   protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
+  /**
+   * Shared filter/sort/search gate check. Subclasses assemble a {@link ReadableGates}
+   * config per request (or once in the constructor when static) and call this to
+   * get a uniform HTTP 400 response for any offending field/control.
+   */
+  protected checkGates(filter: FilterExpr | undefined, controls: Record<string, unknown>, gates: ReadableGates): HttpError | undefined;
+  protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
+  protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
+  /**
+   * **GET /meta** — returns the bound interface's metadata envelope.
+   *
+   * Base implementation delegates to {@link buildMetaResponse}, which subclasses
+   * override to add source-specific fields (relations, searchable flags, etc.).
+   * The response is cached on the instance; async overrides must cache any
+   * extra enrichment themselves.
+   */
+  meta(): Promise<TMetaResponse>;
+  /**
+   * Builds the `/meta` payload. Override in subclasses to populate source-specific
+   * fields. Defaults return a minimal envelope with the serialized type and the
+   * read-only flag; value-help dicts populate their capability hints here.
+   */
+  protected buildMetaResponse(): Promise<TMetaResponse>;
+}
+//#endregion
+//#region src/as-db-readable.controller.d.ts
+/**
+ * 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}.
+ */
+declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
+  /** Reference to the underlying readable (table or view). */
+  protected readable: AtscriptDbReadable<T>;
+  private readonly _gates;
+  constructor(readable: AtscriptDbReadable<T>, app: Moost);
+  private _buildGates;
+  private _collectAnnotated;
+  protected hasField(path: string): boolean;
+  /** Validates $with relations against the readable. */
+  protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
   /**
    * Compute an embedding vector from a search term.
    * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
@@ -71,8 +161,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * May return a Promise for async lookups.
    */
   protected transformProjection(projection?: UniqueryControls["$select"]): UniqueryControls["$select"] | undefined | Promise<UniqueryControls["$select"] | undefined>;
-  protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
-  protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
   /**
    * Extracts a composite identifier object from query params.
    * Tries composite primary key first, then compound unique indexes.
@@ -104,12 +192,11 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /**
    * **GET /meta** — returns table/view metadata for UI.
    *
-   * The return type includes `Promise<...>` so subclasses can override with an
-   * async implementation (e.g. to enrich the payload from an external source).
-   * The base cache only covers the base payload — async overrides must cache
-   * their own enrichment if needed.
+   * Overrides the base's minimal envelope to add relations, searchable flags,
+   * vector-searchable flags, field-descriptor-derived filter/sort hints, and
+   * the configured primary keys.
    */
-  meta(): TMetaResponse | Promise<TMetaResponse>;
+  protected buildMetaResponse(): Promise<TMetaResponse>;
 }
 //#endregion
 //#region src/as-db.controller.d.ts
@@ -161,6 +248,132 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   removeComposite(query: Record<string, string>): Promise<unknown>;
 }
 //#endregion
+//#region src/as-value-help.controller.d.ts
+/**
+ * Parsed Uniquery controls with the `$search` field carved out for value-help
+ * use (the core DTO includes it but we narrow the type here so implementations
+ * can rely on the concrete shape).
+ */
+interface ValueHelpQuery<T> {
+  filter: FilterExpr;
+  controls: {
+    $skip?: number;
+    $limit?: number;
+    $search?: string;
+    $select?: (keyof T | string)[];
+    $sort?: unknown;
+    [key: string]: unknown;
+  };
+}
+/**
+ * Abstract base class for read-only HTTP controllers serving a **value-help**
+ * source — an interface bound to a simple `/query` / `/pages` / `/one(/:id)` /
+ * `/meta` surface, not a full DB table. Value-help controllers drive the
+ * client-side picker UI on fields annotated `@db.rel.FK`.
+ *
+ * Subclass responsibilities:
+ * - Pass the bound interface + rows/backing-source through super().
+ * - Implement the abstract {@link query} and {@link getOne} methods.
+ *
+ * The bound interface's `@ui.dict.*` annotations are **client-side hints**
+ * consumed by the picker UI; the server does not gate filter / sort / search
+ * requests against them. Subclasses that need a backend gate should compose
+ * one of their own (see {@link AsDbReadableController} for the
+ * `@db.column.filterable` / `@db.column.sortable` pattern).
+ */
+declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsReadableController<T, DataType> {
+  /** Per-prop metadata map of the bound interface; eagerly built once. */
+  protected readonly fieldMeta: Map<string, Map<string, unknown>>;
+  /**
+   * Fields that participate in `$search` by default. Populated from
+   * `@ui.dict.searchable`:
+   * - If any prop carries `@ui.dict.searchable`, only those props are here.
+   * - Else if the interface carries `@ui.dict.searchable`, every `string`-typed prop is here.
+   * - Else every `string`-typed prop is here (hint is absent — default to all strings).
+   */
+  protected readonly searchableFields: readonly string[];
+  /** The `@meta.id` field name on the bound interface, if any. */
+  protected readonly primaryKey: string | undefined;
+  constructor(boundType: T, controllerName: string, app: Moost);
+  /** Executes a value-help query against the backing source. */
+  protected abstract query(controls: ValueHelpQuery<DataType>): Promise<{
+    data: DataType[];
+    count: number;
+  }>;
+  /** Returns the row whose primary key matches `id`, or `null` on miss. */
+  protected abstract getOne(id: string | number): Promise<DataType | null>;
+  protected hasField(path: string): boolean;
+  /**
+   * **GET /query** — returns an array of matched rows (up to `$limit`).
+   */
+  runQuery(url: string): Promise<DataType[] | HttpError>;
+  /**
+   * **GET /pages** — paginated row window plus total count.
+   */
+  runPages(url: string): Promise<{
+    data: DataType[];
+    page: number;
+    itemsPerPage: number;
+    pages: number;
+    count: number;
+  } | HttpError>;
+  /**
+   * **GET /one/:id** — retrieves a single row by primary key.
+   */
+  runGetOne(id: string): Promise<DataType | HttpError>;
+  /**
+   * **GET /one?<pk>=<val>** — retrieves a single row by PK query param (fallback).
+   */
+  runGetOneComposite(query: Record<string, string>): Promise<DataType | HttpError>;
+  /**
+   * Meta response surfaces `@ui.dict.*` annotations as **hints** for the
+   * client picker UI (which controls to render); the server does not enforce
+   * these flags at request time.
+   */
+  protected buildMetaResponse(): Promise<TMetaResponse>;
+}
+//#endregion
+//#region src/as-json-value-help.controller.d.ts
+/**
+ * Concrete value-help controller backed by a static in-memory array. Provides
+ * filter/sort/search/paginate over the provided rows, respecting the
+ * `@ui.dict.*` capability annotations on the bound interface.
+ *
+ * **Semantics:**
+ * - Filter is interpreted as a subset of MongoDB-style comparison operators
+ *   (`$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$regex`) and
+ *   logical combinators (`$and`, `$or`, `$not`, `$nor`). Unknown operators
+ *   fall through to strict equality.
+ * - Sort is stable, multi-key, lexicographic. Direction via `-` prefix on the
+ *   field name or `{ [field]: 'asc' | 'desc' }`.
+ * - Search is case-insensitive substring matching across every field listed in
+ *   {@link searchableFields}.
+ * - Type coercion: comparisons compare raw JS values (no implicit string-to-
+ *   number coercion); strings are compared case-insensitively only for
+ *   `$search`, not for filter operators.
+ *
+ * **Constructor:**
+ * ```ts
+ * new AsJsonValueHelpController(StatusDict, [
+ *   { id: 'active', label: 'Active' },
+ *   { id: 'archived', label: 'Archived' },
+ * ], app);
+ * ```
+ *
+ * Register under a Moost path with `@Controller('/api/dicts/status')` or the
+ * equivalent composition decorator.
+ */
+declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsValueHelpController<T, DataType> {
+  protected rows: DataType[];
+  private _pkIndex?;
+  constructor(boundType: T, rows: DataType[], app: Moost, controllerName?: string);
+  protected query(controls: ValueHelpQuery<DataType>): Promise<{
+    data: DataType[];
+    count: number;
+  }>;
+  protected getOne(id: string | number): Promise<DataType | null>;
+}
+//#endregion
 //#region src/decorators.d.ts
 /**
  * DI token under which the {@link AtscriptDbReadable} instance
@@ -223,4 +436,4 @@ declare const ViewController: (readable: AtscriptDbReadable, prefix?: string) =>
 declare const validationErrorTransform: () => moost.TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
 //#endregion
-export { AsDbController, AsDbReadableController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };
+export { AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, validationErrorTransform };