@atscript/moost-db 0.1.126 → 0.1.128

package/dist/index.d.mts

@@ -3,26 +3,8 @@ 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, 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, TIdentification, TMetaResponse, Uniquery, UniqueryControls } from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, 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, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 //#region src/as-readable.controller.d.ts
-/**
- * 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.
  *
@@ -67,6 +49,14 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   private _resolveHttpPath;
   /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
   protected getSerializedType(): TSerializedAnnotatedType;
+  /**
+   * Serializes a type for the meta surfaces (`/meta`, `/meta/form/:name`)
+   * with {@link getSerializeOptions}, then re-points every reference chain to
+   * its terminal field and inherits the `db.rel.FK` value-help marker through
+   * the chain (since 0.1.128; see `meta/terminal-ref.ts`). Direct references
+   * serialize exactly as before.
+   */
+  protected serializeForMeta(type: TAtscriptAnnotatedType): TSerializedAnnotatedType;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
    */
@@ -98,12 +88,28 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   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.
+   * Per-request gate hook, invoked by the DB readable controller right after
+   * its capability gate (`checkCapabilities`) with the parsed query. The
+   * default accepts everything. Return an `HttpError` to reject.
+   *
+   * @deprecated since 0.1.128 — the filter / sort gate is the
+   * `FieldCapabilityIndex` behind `checkCapabilities` (override that, or read
+   * `this.capabilities` on `AsDbReadableController`); this hook only remains
+   * so subclasses that overrode it keep being called.
    */
-  protected checkGates(filter: FilterExpr | undefined, controls: Record<string, unknown>, gates: ReadableGates): HttpError | undefined;
+  protected checkGates(_parsed: {
+    filter?: FilterExpr;
+    controls?: object;
+  }): HttpError | undefined;
   protected parseQueryString(url: string): import("@uniqu/url").UrlQuery;
+  /**
+   * The ONE place a query string meets the `@uniqu/url` grammar. A lexer /
+   * parser error (e.g. an unquoted `-` in a value: `?name=json-w1`) is the
+   * client's fault, so since 0.1.128 it is a 400 with the validation envelope
+   * `{ message, statusCode: 400, errors: [{ path: "", message }] }` instead of
+   * an unhandled 500. Quote such values: `?name='json-w1'`.
+   */
+  protected parseUrlOr400(queryString: string): ReturnType<typeof parseUrl>;
   /**
    * Parse a URL keeping only `$*` control keywords; report whether any
    * non-control parts were present. Used by `/one` routes where the
@@ -163,6 +169,90 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected applyMetaOverlay(meta: TMetaResponse): TMetaResponse | Promise<TMetaResponse>;
 }
 //#endregion
+//#region src/meta/field-capabilities.d.ts
+/**
+ * Per-path HTTP capability of a DB readable — the single source that both the
+ * `/meta.fields` projection and the request gate are computed from, so the
+ * two can never disagree (since 0.1.128).
+ *
+ * Physical capability (adapter `canFilterField` / `canSortField`, storage,
+ * `@db.encrypted`) is combined with HTTP policy (`@db.writeOnly`,
+ * `@db.table.filterable / sortable 'manual'` + `@db.column.*`). Policy applies
+ * to filters and `$sort` only; `$groupBy`, `$having` keys and aggregate
+ * `$field`s use the physical capability alone.
+ */
+interface TFieldCapability {
+  /** A filter on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
+  filterable: boolean;
+  /** A `$sort` on this path passes the gate (adapter ∧ ¬writeOnly ∧ ¬encrypted ∧ policy). */
+  sortable: boolean;
+  /** The path may appear in `$select`. `@db.writeOnly` fields are selectable — the seal strips them after the gate. */
+  selectable: boolean;
+  /** Advisory: index-backed (explicit `@db.index*`, primary key, unique). Never affects acceptance. */
+  indexed: boolean;
+  /** Present when `filterable` is `false` — the reason clause appended to the HTTP 400 message. */
+  filterReason?: string;
+  /** Present when `sortable` is `false` — the reason clause appended to the HTTP 400 message. */
+  sortReason?: string;
+}
+/** One rejected path: `path` is the offending logical path, `message` the full sentence. */
+interface TCapabilityVerdict {
+  path: string;
+  message: string;
+}
+/** The readable members the index reads. */
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField">;
+/**
+ * Capability index of one readable, built once per controller.
+ *
+ * - {@link entries} feeds `/meta.fields` (listed leaves in descriptor order);
+ * - {@link check} is the request gate: same inputs, same answer.
+ *
+ * Paths outside the index are classified by the core's `classifyQueryPath`
+ * (the same rules the core backstop applies) — navigation path, nested-object
+ * parent, JSON descendant (relational adapters), encrypted descendant,
+ * unknown — so the 400 names the storage reason and the alternative.
+ */
+declare class FieldCapabilityIndex implements TQueryPathSource {
+  readonly filterableManual: boolean;
+  readonly sortableManual: boolean;
+  /** Navigation relations (`@db.rel.to/from/via`), incl. nested ones. */
+  readonly navFields: ReadonlySet<string>;
+  /** `@db.writeOnly` paths. */
+  readonly writeOnly: ReadonlySet<string>;
+  /** Descriptors stored as one JSON column (relational adapters). */
+  readonly jsonParents: ReadonlySet<string>;
+  /** Descriptors carrying `@db.encrypted` (the ciphertext column on relational adapters). */
+  readonly encryptedFields: ReadonlySet<string>;
+  private readonly _entries;
+  /** Nested-object parents (never listed, always selectable) → their listed leaves. */
+  private readonly _objectParents;
+  /** Listed leaves — the {@link TQueryPathSource} view for `classifyQueryPath`. */
+  get leaves(): ReadonlyMap<string, unknown>;
+  /** Nested-object parents — the {@link TQueryPathSource} view for `classifyQueryPath`. */
+  get objectParents(): ReadonlyMap<string, unknown>;
+  constructor(source: TCapabilityReadable, writeOnly: ReadonlySet<string>);
+  private _buildEntry;
+  /** Listed leaves in descriptor order — the `/meta.fields` projection source. */
+  entries(): IterableIterator<[path: string, cap: TFieldCapability, fd: TDbFieldMeta]>;
+  /** Physical filter capability (adapter ∧ ¬writeOnly ∧ ¬encrypted) — ignores the manual-mode policy. */
+  isPhysicallyFilterable(path: string): boolean;
+  /**
+   * Gate check for one path in one position. Returns `undefined` when the
+   * path is accepted. Order: navigation paths first (a nav path "exists" on
+   * the target table but is never a column here), then a listed leaf's
+   * capability (no existence lookup needed — every listed leaf is a real
+   * field), then `exists` (the readable's `isValidFieldPath`) and, for paths
+   * that exist but are not leaves, the storage classification.
+   *
+   * Existence deliberately runs BEFORE the JSON / encrypted classification:
+   * an untyped descendant of a JSON column (`address.nope`) is reported as
+   * `Unknown field`, not as "inside JSON-stored column" — clients pin that
+   * wording, so do not "align" it with the core backstop's text.
+   */
+  check(path: string, op: TQueryPathOp$1, exists: (path: string) => boolean): TCapabilityVerdict | undefined;
+}
+//#endregion
 //#region src/as-db-readable.controller.d.ts
 /**
  * Read-only database controller for Moost that works with any `AtscriptDbReadable`
@@ -182,30 +272,58 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * (or any non-table readable).
    */
   protected get table(): AtscriptDbTable<T>;
-  private readonly _gates;
+  /**
+   * Per-path capability index (since 0.1.128): the ONE input both `/meta.fields`
+   * and the request gate ({@link checkCapabilities}) are computed from, so
+   * metadata and runtime can never diverge.
+   */
+  protected readonly capabilities: FieldCapabilityIndex;
+  /** Bound once: the field-existence check the gate hands to `capabilities.check`. */
+  private readonly _exists;
   private readonly _preferredIdSet;
   private readonly _overlayIsNoOp;
   /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
   private readonly _quantityRefByPath;
-  /** Paths the adapter vetoes for filtering (e.g. JSON storage on SQL). Symmetric with `/meta` `filterable: false`. */
-  private readonly _adapterNonFilterable;
   /** `@db.column.searchable` paths — the `$search` fallback when the adapter has no native search. */
   private readonly _searchFallbackFields;
   /** `@db.writeOnly` paths — settable in writes, sealed out of every read surface. */
   private readonly _writeOnlySet;
+  /**
+   * Logical paths an exclusion `$select` inverts into: every listed leaf and
+   * (on nested-object adapters) object parents — never navigation descendants,
+   * which the core path guard rejects.
+   */
+  private readonly _invertibleFields;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
-  private _collectAdapterNonFilterable;
+  private _collectInvertibleFields;
   private _collectQuantityRefs;
-  private _buildGates;
   private _collectAnnotated;
   protected hasField(path: string): boolean;
   /**
-   * Adds an adapter-capability veto on top of the base gate. Distinct from the
-   * `@db.column.filterable` rejection because the message must reference the
-   * adapter, not an annotation the user could add to bypass it. Sort uses
-   * adapter capability differently and is enforced at the SQL builder layer.
+   * Structural capability gate (since 0.1.128): walks the PARSED query —
+   * filter tree, `$sort`, `$select`, `$groupBy`, `$having`, aggregate
+   * `$field`s — and checks every root path against {@link capabilities}, the
+   * same index `/meta.fields` is projected from. Runs on the wire request,
+   * before `transformFilter` / `transformProjection` and before the write-only
+   * seal (a `@db.writeOnly` field is selectable; the seal strips it silently).
+   *
+   * Rejections use the structured envelope `{ message, statusCode: 400,
+   * errors: [{ path, message }] }` — `path` is the offending logical path.
+   * After the per-path checks the core `$having` rule runs (`checkHavingKeys`:
+   * aliases or `$groupBy` fields only), so a readable mock and a real table
+   * answer alike.
+   */
+  protected checkCapabilities(parsed: {
+    filter?: FilterExpr;
+    controls?: object;
+  }): HttpError | undefined;
+  /**
+   * Root-path existence moved into {@link checkCapabilities}; the insights map
+   * only serves `$with` sub-controls here — the URL parser flattens
+   * `$with=assignee($select=name)` into the insight `assignee.name`, which is
+   * resolved against the target table through `isValidFieldPath`.
    */
-  protected checkGates(filter: FilterExpr | undefined, controls: Record<string, unknown>, gates: ReadableGates): HttpError | undefined;
+  protected validateInsights(insights: Map<string, unknown>): string | undefined;
   /** Validates $with relations against the readable. */
   protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
   /**
@@ -251,7 +369,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /** Returns a widened `$select` only when at least one `requiredFields` entry is missing; `null` means "no widening needed". */
   private _widenSelectForActions;
   private _prepareAugmentation;
-  /** `@db.column.searchable` paths, minus anything the adapter can't filter (JSON storage, encrypted). */
+  /**
+   * `@db.column.searchable` paths, minus anything the adapter can't filter
+   * (JSON storage, encrypted), `@db.writeOnly` fields and navigation
+   * descendants — physical capability only (manual-mode policy does not
+   * apply to `$search`).
+   */
   private _collectSearchFallbackFields;
   /**
    * Removes `@db.writeOnly` fields from any `$select` shape — and forces an
@@ -350,20 +473,109 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
  * ‎@TableController(usersTable)
  * export class UsersController extends AsDbController<typeof UserModel> {}
  * ```
+ *
+ * ### Write pipeline (since 0.1.128)
+ *
+ * ```
+ * shape gate (400) → onWrite / onRemove (outside any transaction)
+ *   → table op — the table's own transaction: validate → guardWrite / guardRemove
+ *                (only when overridden) → re-validate → write
+ *   → 404 / 409 disambiguation
+ * ```
+ *
+ * The guard is the table's `guard` write option (`TWriteOptions.guard` /
+ * `TDeleteOptions.guard`); overriding `guardWrite` / `guardRemove` is the
+ * switch that passes it. Built-in failures are THROWN as `HttpError`
+ * (wire-identical to returning them; a throw also rolls back a user-level
+ * `withTransaction` wrapper).
  */
 declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsDbReadableController<T, DataType> {
   constructor(app: Moost, table?: AtscriptDbTable<T>);
   protected buildCrud(): TCrudPermissions$1;
   /**
-   * Intercepts write operations. Return `undefined` to abort.
-   * May be async (e.g. to enrich payloads from session / permissions).
+   * Intercepts write operations with the UNTRUSTED body (after the shape gate:
+   * an object, or an array of objects). Runs outside any transaction. Return
+   * the data in the shape received — an object, or an array of objects for
+   * the `*Many` actions; anything else (including `undefined`) aborts with
+   * 500 "Not saved". Return an `Error` instance to respond with that error
+   * (since 0.1.128 — previously passed on as data); throw to respond with
+   * the thrown error's status. May be async (e.g. to enrich payloads from
+   * session / permissions).
    */
-  protected onWrite(action: "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany", data: unknown): unknown;
+  protected onWrite(action: TDbWriteAction$1, data: unknown): unknown;
   /**
-   * Intercepts delete operations. Return `undefined` to abort.
-   * May be async (e.g. to resolve composite ids from external state).
+   * Intercepts delete operations. Return `undefined` to abort (500 "Not
+   * deleted"); return an `Error` instance to respond with that error.
+   * Runs outside any transaction. May be async (e.g. to resolve composite
+   * ids from external state).
    */
   protected onRemove(id: unknown): unknown;
+  /**
+   * Validated-stage write guard (since 0.1.128). Overriding it is the switch:
+   * the override is passed to the table as its `guard` write option and runs
+   * once inside the table's own transaction, after defaults + validation and
+   * before encryption / nested-relation phases. `ctx.rows` are the validated
+   * rows (defaults applied on insert/replace; `$cas` removed on update) and
+   * may be enriched in place — the table validates them again afterwards.
+   * Reject by throwing (an `HttpError` is recommended): the transaction rolls
+   * back and the error propagates unchanged. Unmodified controllers pass no
+   * guard and pay nothing.
+   *
+   * Do not swallow `DbError`s (on PostgreSQL the transaction is aborted after
+   * a failed statement), and do not await external I/O on SQLite (the guard
+   * holds the connection). On MongoDB replica sets the transaction callback —
+   * and therefore this guard — may run more than once on transient errors.
+   */
+  protected guardWrite(_ctx: TDbWriteGuardContext$1<DataType>): void | Promise<void>;
+  /**
+   * Validated-stage remove guard (since 0.1.128). Same switch semantics as
+   * {@link guardWrite}: the override becomes `deleteOne`'s `guard` option and
+   * runs inside the table's transaction once `onRemove`'s id resolved to a
+   * filter. A missing row still reaches the guard — `ctx.current()` resolves
+   * to `null` and the 404 comes after the guard; only an id that cannot be
+   * resolved to a filter at all (malformed for the key type) is a 404 before
+   * the guard.
+   */
+  protected guardRemove(_ctx: TDbRemoveGuardContext$1<DataType>): void | Promise<void>;
+  /**
+   * Runs `fn` inside the bound table's adapter transaction (nested calls
+   * join it). For custom actions and routes that need one transaction across
+   * several table operations.
+   */
+  protected withTransaction<R>(fn: () => Promise<R>): Promise<R>;
+  /**
+   * The table write call's trailing options: `[{ guard }]` only when
+   * `guardWrite` is overridden, else nothing (the table is called exactly as
+   * an unmodified controller always called it).
+   */
+  private _writeArgs;
+  /** `deleteOne`'s trailing options: `[{ guard }]` only when `guardRemove` is overridden. */
+  private _removeArgs;
+  /** Resolves a hook result: `undefined` aborts with `abortMessage`, an `Error` is thrown, anything else passes. */
+  private _checkHook;
+  /** Runs `onWrite` and re-applies the shape gate to its output (a non-object is a 500 "Not saved"). */
+  private _writeBody;
+  /**
+   * Normalises the OCC shape of one write item in place through the shared
+   * `reconcileCas` (since 0.1.128): a top-level `version` field in a write
+   * body is a `$cas` directive, not a SET — it is lifted to
+   * `$cas: { [versionColumn]: version }`; a raw SDK-shaped `$cas` is accepted
+   * as sent; both present with different values → 400 at `$cas`; a malformed
+   * `$cas` reports `separateCas`'s own message. Returns `true` iff the item is
+   * CAS-bearing — callers use this to gate the 404/409 disambiguation
+   * `findOne` on `matchedCount === 0`. On a non-versioned table nothing is
+   * lifted and a raw `$cas` reaches the table, which rejects it.
+   */
+  private _resolveCas;
+  /**
+   * Bulk auto-lift: each item carries its own `version` → `$cas`.
+   * NOTE: per-item conflict disambiguation in the response body is deferred
+   * (§6.4) — the aggregate `{ matchedCount, modifiedCount }` surfaces partial
+   * application; callers can detect mismatches via `modifiedCount < N`.
+   */
+  private _resolveBulkCas;
+  /** Deletes by id (guard forwarded when overridden) and maps "nothing deleted" to 404. */
+  private _deleteOrThrow;
   /**
    * **POST /** — inserts one or many records.
    */
@@ -372,22 +584,25 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * **PUT /** — fully replaces one or many records matched by primary key.
    *
    * When the table opts into OCC (`@db.column.version`), a top-level `version`
-   * field in the body is auto-lifted to `$cas` (§6.2 of VERSION_PROPOSAL.md).
-   * On `matchedCount === 0` for a CAS-protected write, this disambiguates
-   * 404 (row gone) vs 409 (version mismatch) via a single `findOne`.
+   * field in the body is auto-lifted to `$cas` (§6.2 of VERSION_PROPOSAL.md);
+   * a raw `$cas` is accepted as sent. On `matchedCount === 0` for a
+   * CAS-bearing write, this disambiguates 404 (row gone) vs 409 (version
+   * mismatch) via a single `findOne` after the table call.
    */
   replace(payload: unknown): Promise<unknown>;
   /**
    * **PATCH /** — partially updates one or many records matched by primary key.
    *
-   * Same OCC semantics as {@link replace} (§6.2 / §6.3).
+   * Same OCC semantics as {@link replace} (§6.2 / §6.3). A PK-only body
+   * carrying `version` (or `$cas`) is a real write — the "versioned touch":
+   * the CAS statement executes and bumps the version on a hit.
    */
   update(payload: unknown): Promise<unknown>;
   /**
    * Disambiguates a `matchedCount === 0` result on a CAS-protected write:
    * returns 404 when the row is genuinely missing, 409 with
    * `{ error: "version_mismatch", currentVersion: N }` when it's present
-   * but the supplied version is stale (§6.3).
+   * but the supplied version is stale (§6.3). Callers throw the result.
    */
   protected _disambiguateMismatch(data: unknown, versionColumn: string): Promise<HttpError>;
   /**
@@ -986,6 +1201,26 @@ interface TAssertExposedOptions {
  */
 declare function assertExposed(app: Moost, models: readonly TAtscriptAnnotatedType[], options?: TAssertExposedOptions): TAtscriptAnnotatedType[];
 //#endregion
+//#region src/http-errors.d.ts
+/** One entry of the structured error envelope's `errors` array. */
+interface THttpErrorEntry {
+  path: string;
+  message: string;
+}
+/**
+ * The structured error envelope every `moost-db` rejection uses (since
+ * 0.1.128 all of them do): `{ message, statusCode, errors: [{ path, message }] }`
+ * — the same shape the validation interceptor renders for `ValidatorError` /
+ * `DbError`, so clients parse one format.
+ */
+declare function errorEnvelope(statusCode: number, message: string, errors: THttpErrorEntry[]): HttpError;
+/**
+ * A 400 with a single `errors` entry: `path` names the offending logical
+ * path / body position, `message` the reason, `top` the envelope's top-level
+ * message (defaults to `message`).
+ */
+declare function badRequest(path: string, message: string, top?: string): HttpError;
+//#endregion
 //#region src/validation-interceptor.d.ts
 declare const validationErrorTransform: () => import("moost").TInterceptorDef;
 declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
@@ -1283,4 +1518,50 @@ declare const QUERY_CONTROLS: readonly string[];
 declare const PAGES_CONTROLS: readonly string[];
 declare const ONE_CONTROLS: readonly string[];
 //#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, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, ReadableController, ReadableGates, TABLE_DEF, TAssertExposedOptions, 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, TReadableBinding, type TReadableBindingMeta, TableController, UseValidationErrorTransform, ValueHelpQuery, ViewController, assertExposed, clearDbSpaces, dbActionBodySlot, dbActionInputSlot, discoverActions, findReadableBinding, getAtscriptDbMate, getControllerFormType, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, validationErrorTransform };
+//#region src/meta/terminal-ref.d.ts
+/**
+ * Terminal-reference resolution for `/meta` and `/meta/form/:name`
+ * (since 0.1.128).
+ *
+ * A prop declared through a reference chain — a view field `code: Issue.code`
+ * where `Issue.code: Dict.code` carries `@db.rel.FK` — serializes with
+ * `refDepth: 0.5` as a shallow ref to its DIRECT hop (`Issue.code`), and the
+ * `@db.rel.FK` marker does not travel through references. Value-help pickers
+ * therefore target the wrong table. This post-pass re-points every serialized
+ * `ref` to the chain's terminal field (the column's value domain) and
+ * inherits the FK marker when any hop of the chain is an FK. The runtime type
+ * is never mutated; direct references serialize byte-identically.
+ */
+/** Result of walking a reference chain to its end. */
+interface TTerminalRef {
+  type: TAtscriptAnnotatedType;
+  field: string;
+  /** `true` when the prop itself or any hop of its chain carries `@db.rel.FK`. */
+  fk: boolean;
+}
+/**
+ * Resolves a (possibly dotted) prop path against an object type by walking
+ * `type.props` one segment at a time. Bails with `undefined` as soon as a hop
+ * is not an object type or the segment is missing.
+ */
+declare function resolveProp(type: TAtscriptAnnotatedType, field: string): TAtscriptAnnotatedType | undefined;
+/**
+ * Follows `def.ref` hop by hop until a prop without a `ref` (a primary key or
+ * a plain column) is reached. Cycle-safe (visited on `<typeId>.<field>`) and
+ * bounded by chain length.
+ */
+declare function resolveTerminalRef(def: TAtscriptAnnotatedType): TTerminalRef | undefined;
+/**
+ * Post-pass over a serialized type in lock-step with its runtime type: every
+ * object prop (recursing into nested objects and array elements — never into
+ * `ref` bodies or navigation subtrees) whose runtime prop has a `ref` gets its
+ * serialized `ref` re-pointed to the terminal field (shallow `{ id, metadata }`
+ * target, serialized with the same annotation whitelist) and, when the chain
+ * passes an FK, `metadata["db.rel.FK"] = true` (never the hop's alias).
+ *
+ * Only shallow refs (`refDepth` with a `.5` step) are rewritten; a full-body
+ * ref target is left alone. Mutates and returns `serialized`.
+ */
+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 };