@atscript/moost-db 0.1.147 → 0.1.148

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { i as resolveDbSpace, n as clearDbSpaces, r as provideDbSpace, t as DEFAULT_DB_SPACE } from "./db-space-registry-CWpYwZ4R.cjs";
+import { a as resolveDbSpace, i as provideDbSpace, n as clearDbSpaces, r as closeDbSpaces, t as DEFAULT_DB_SPACE } from "./db-space-registry-fXB8LnGe.cjs";
 import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializeOptions, TSerializedAnnotatedType, TValidatorOptions, Validator } from "@atscript/typescript/utils";
 import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$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";
@@ -61,6 +61,14 @@ interface TDbRequestContext {
   readonly hasRelationFilters?: boolean;
   /** `"action"` / `"delegatedAction"` endpoints only: the `@DbAction` name being run. */
   readonly action?: string;
+  /**
+   * `"insert"` endpoint only: the `?$onConflict=` mode the request carries
+   * (`"ignore"`); absent for a plain insert. A controller can refuse it by
+   * throwing from `prepareRequest`.
+   *
+   * @since 0.1.148
+   */
+  readonly onConflict?: "ignore";
 }
 /** Control DTO a {@link AsReadableController.validateControls} call checks against. @since 0.1.143 (`"geo"`) */
 type TDbControlsType = "query" | "pages" | "getOne" | "geo";
@@ -210,8 +218,8 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected prepareRequest?(ctx: TDbRequestContext): void | Promise<void>;
   /**
    * The ONE request entry of every built-in route: with a `url` (read
-   * endpoints) it parses the query string — `/one` keeps only the `$`
-   * controls ({@link parseControlsOnlyFromUrl}), every other endpoint the
+   * endpoints, and `POST /`) it parses the query string — `/one` and `POST /`
+   * keep only the `$` controls ({@link parseControlsOnlyFromUrl}), every other endpoint the
    * whole query ({@link parseQueryString}) — and coerces boolean controls the
    * URL grammar leaves as strings (`$actions=true`); then it awaits
    * {@link prepareRequest} (when implemented) with the parsed controls.
@@ -589,6 +597,45 @@ type EntryRequiredFields<E, TRow> = E extends {
 } ? R extends readonly FlatKey<TRow>[] ? R : [] : [];
 type ValidatedDict<TRow, D extends DbActionsDictBase> = { [K in keyof D]: TDbActionsEntry<TRow, EntryRequiredFields<D[K], TRow>> };
 type ValidatedUnpinnedDict<TRow, D extends DbActionsDictBase> = { [K in keyof D]: TDbActionsEntryUnpinned<TRow, EntryRequiredFields<D[K], TRow>> };
+/**
+ * An id as an id-addressed endpoint received it: a path scalar (always a
+ * string from the URL) or an identification object (`?field=value` forms,
+ * action bodies).
+ *
+ * @since 0.1.148
+ */
+type TDbRowIdInput = string | number | boolean | Record<string, unknown>;
+/**
+ * Which endpoint asks `resolveRowIds`:
+ *
+ * - `"action"` — an action route: the body's validated ids;
+ * - `"available"` — `GET /meta/actions/:id` | `?…` (and a view asking its source);
+ * - `"one"` — `GET /one/:id` | `?…`;
+ * - `"remove"` — `DELETE /:id` | `?…`.
+ *
+ * @since 0.1.148
+ */
+type TDbRowIdPurpose = "action" | "available" | "one" | "remove";
+/**
+ * Context of `AsDbReadableController.resolveRowIds`.
+ *
+ * @since 0.1.148
+ */
+interface TDbRowIdsContext {
+  readonly purpose: TDbRowIdPurpose;
+  /** `"action"` only: the action's name. */
+  readonly action?: string;
+  /** `"action"` only: the action's level. */
+  readonly level?: "row" | "rows";
+  /**
+   * The row overlay the endpoint will apply to the resolved id
+   * (`rowOverlay()`; for actions the gate's overlay), `undefined` when none.
+   * Server data — never sent to the client. Resolve INSIDE it when an alias
+   * could name several rows, so a row the caller can't reach never shadows
+   * one they can.
+   */
+  readonly overlay?: FilterExpr;
+}
 //#endregion
 //#region src/actions/discover.d.ts
 /**
@@ -622,6 +669,24 @@ declare const ALLOWED_ACTIONS: unique symbol;
 /** `true` when the controller class declares `@DbActionsFrom` (inherited included). */
 declare function hasActionDelegations(ctor: Function): boolean;
 //#endregion
+//#region src/actions/rows-by-id.d.ts
+/** One id the client sent, with the {@link identityKey} of the id it resolved to. */
+interface TRequestedId {
+  id: Record<string, unknown>;
+  key: string;
+}
+/**
+ * The result of a `resolveRowIds` call over an action's ids: the resolved
+ * ids with duplicate identities collapsed to the first (what handlers and
+ * the row load see) and — only when an id changed or collapsed — EVERY
+ * request id in request order (`requests`), the single model all refusals,
+ * reasons, summaries and counts are judged and reported in.
+ */
+interface TAppliedIds {
+  ids: Record<string, unknown>[];
+  requests?: readonly TRequestedId[];
+}
+//#endregion
 //#region src/actions/scope-context.d.ts
 /**
  * Which surface asks {@link TDbActionScopeContext} — see
@@ -636,17 +701,30 @@ declare function hasActionDelegations(ctor: Function): boolean;
 type TDbActionScopePurpose = "execute" | "rows" | "available";
 /**
  * The candidate rows `AsDbReadableController.actionRowScope` is asked about
- * (since 0.1.147). Every candidate is already inside the controller's row
- * overlay; the hook's result restricts them further.
+ * (since 0.1.147). Every candidate is inside the controller's row overlay;
+ * the hook's result restricts them further.
+ *
+ * Exception (since 0.1.148): at `purpose: "execute"` with NO row overlay, the
+ * hook is asked BEFORE the rows are loaded when the request's ids are in
+ * `preferredId` shape — `ids` are then the request's (resolved) ids, deduped,
+ * and may name rows that do not exist (`loadRows` omits them). A restriction
+ * it returns joins the single row load (`id ∧ scope`); an answer of
+ * `undefined` / `null` / `{}` makes the gate load nothing.
  *
  * @since 0.1.147
  */
 interface TDbActionScopeContext {
-  /** Which surface asks — the action gate, `$actions` on a read, or `GET /meta/actions`. */
+  /**
+   * Which surface asks: `"execute"` — the action gate (≤ `maxIds` ids; one
+   * batch of a query target); `"rows"` — `$actions` on a read (also a view's
+   * delegated verdicts), the read's rows; `"available"` — `GET /meta/actions/:id`,
+   * the one row.
+   */
   readonly purpose: TDbActionScopePurpose;
   /**
    * The candidates' identities (`preferredId`-shaped), deduped and never
-   * empty. ONE array object per evaluation, shared by every action of it —
+   * empty — at `"execute"` without a row overlay, the request's ids (they may
+   * not exist; see above). ONE array object per evaluation, shared by every action of it —
    * memoize on it (`WeakMap`) when several actions derive the same filter.
    */
   readonly ids: readonly Record<string, unknown>[];
@@ -672,6 +750,10 @@ declare const ACTION_OVERLAY: unique symbol;
 declare const ACTION_SCOPE: unique symbol;
 /** `true` when the controller overrides `actionRowScope` (since 0.1.147). */
 declare const ACTION_SCOPED: unique symbol;
+/** The controller's internal `resolveRowIds` call for an action's ids (since 0.1.148). */
+declare const ROW_RESOLVE_IDS: unique symbol;
+/** `true` when the controller overrides `resolveRowIds` (since 0.1.148). */
+declare const ROW_RESOLVES: unique symbol;
 //#endregion
 //#region src/meta/field-capabilities.d.ts
 /**
@@ -713,16 +795,37 @@ interface TFieldCapability {
    * `bucketSourceVerdict`). Since 0.1.132.
    */
   bucketable: boolean;
+  /**
+   * `$groupBy` on this path passes the gate: physically filterable (adapter ∧
+   * ¬writeOnly ∧ ¬encrypted) and, on a table declaring dimensions / measures,
+   * a dimension. Since 0.1.148.
+   */
+  groupable: boolean;
+  /** Present when `groupable` is `false` — the reason clause appended to the HTTP 400 message. */
+  groupReason?: string;
   /** Present when `bucketable` is `false` — the reason clause appended to the HTTP 400 message. */
   bucketReason?: string;
+  /**
+   * The path may be an operand of query-time arithmetic: a numeric field
+   * ({@link numericOperandProblem}) that aggregates (`$groupBy` / aggregate
+   * capability, ¬writeOnly, visible). Only on an adapter with
+   * `supportsAggregateExpressions()`. Since 0.1.148.
+   */
+  numeric: boolean;
 }
 /** One rejected path: `path` is the offending logical path, `message` the full sentence. */
 interface TCapabilityVerdict {
   path: string;
   message: string;
 }
+/**
+ * The positions {@link FieldCapabilityIndex.check} judges: the core's path
+ * positions plus the `$select` of an aggregate query (`groupedSelect`), where
+ * a plain field must be a `$groupBy` key — a display-only decoration never is.
+ */
+type TGateOp = TQueryPathOp$1 | "groupedSelect";
 /** The readable members the index reads. */
-type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "dimensions" | "measures">;
+type TCapabilityReadable = Pick<AtscriptDbReadable, "type" | "fieldDescriptors" | "flatMap" | "navFields" | "relations" | "ignoredFields" | "canFilterField" | "canSortField" | "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "supportsAggregateExpressions" | "dimensions" | "measures">;
 /**
  * Capability index of one readable.
  *
@@ -756,6 +859,8 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   readonly bucketUnits: readonly BucketUnit[];
   /** Aggregate functions the adapter renders, in canonical `ALL_AGGREGATE_FNS` order (`/meta.aggregateFns`). */
   readonly aggregateFns: readonly AggregateFn[];
+  /** Whether the adapter renders aggregate arithmetic (`/meta.aggregateExpressions`). */
+  readonly aggregateExpressions: boolean;
   /** The adapter-level capabilities this index was built against — see {@link adapterSignature}. */
   readonly signature: string;
   /**
@@ -764,8 +869,19 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * {@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" | "aggregateFns">): string;
+  static adapterSignature(source: Pick<TCapabilityReadable, "isGeoSearchable" | "calendarBucketUnits" | "aggregateFns" | "supportsAggregateExpressions">): string;
+  /**
+   * The navigation paths of a readable: its `navFields`, else its relation
+   * names (partial readables list only the latter).
+   */
+  static navPathsOf(source: Pick<TCapabilityReadable, "navFields" | "relations">): Set<string>;
   private readonly _entries;
+  /**
+   * Declared display-only decorations (`@DbDecorations`, since 0.1.148) —
+   * virtual entries: key → the readable paths it `requires`. Selectable only;
+   * visible while every required path is.
+   */
+  private readonly _decorations;
   /** Nested-object parents (never listed, always selectable) → their listed leaves. */
   private readonly _objectParents;
   /** What `bucketSourceVerdict` reads of the table (JSON-value parents, dimensions, measures). */
@@ -774,10 +890,16 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
   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>);
+  constructor(source: TCapabilityReadable, writeOnly: ReadonlySet<string>, decorations?: ReadonlyMap<string, readonly string[]>);
   private _buildEntry;
   /** Listed leaves in descriptor order — the `/meta.fields` projection source. */
   entries(): IterableIterator<[path: string, cap: TFieldCapability, fd: TDbFieldMeta]>;
+  /** The declared decoration keys, in declaration order. */
+  get decorationKeys(): IterableIterator<string>;
+  /** The capability of the declared decoration `key` (selectable only), `undefined` when `key` is none. */
+  decorationCap(key: string): Readonly<TFieldCapability> | undefined;
+  /** The decoration `key` is visible: every path it `requires` passes `exists` (the hidden-field hook). */
+  decorationVisible(key: string, exists: (path: string) => boolean): boolean;
   /** Physical filter capability (adapter ∧ ¬writeOnly ∧ ¬encrypted) — ignores the manual-mode policy. */
   isPhysicallyFilterable(path: string): boolean;
   /**
@@ -800,6 +922,11 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * JSON-stored column" — clients pin that wording, so do not "align" it
    * with the core backstop's text.
    *
+   * A declared decoration (`@DbDecorations`) is a virtual entry: `select` while
+   * every path it requires passes `exists`, any other position a display-only
+   * refusal (`groupedSelect` is a `$select` of an aggregate query), and hidden
+   * sources answer `Unknown field` like a nonexistent path.
+   *
    * `predicate` is a filter entry's class (`collectQueryPaths` records it per
    * occurrence); it only matters for `op === "filter"` on a listed leaf.
    *
@@ -809,7 +936,7 @@ declare class FieldCapabilityIndex implements TQueryPathSource {
    * name the prefixed one. A filter on a navigation path names the predicate
    * alternative (`ticket=$some(status=…)`).
    */
-  check(local: string, op: TQueryPathOp$1, exists: (path: string) => boolean, predicate?: TFilterPredicate, prefix?: string): TCapabilityVerdict | undefined;
+  check(local: string, gateOp: TGateOp, exists: (path: string) => boolean, predicate?: TFilterPredicate, prefix?: string): TCapabilityVerdict | undefined;
 }
 //#endregion
 //#region src/as-db-readable.controller.d.ts
@@ -832,6 +959,15 @@ interface TDbDecorateContext {
   projection: UniqueryControls["$select"] | undefined;
   /** The request's parsed controls (`$select`, `$with`, `$actions`, …). Read-only by convention. */
   controls: Record<string, unknown>;
+  /**
+   * The declared decoration keys ([`@DbDecorations`](./decorations/db-decorations.decorator.ts))
+   * this response must carry — the ones the client asked for (all of them
+   * without a `$select`) whose sources are visible and kept by
+   * `transformProjection`. Compute only these; a declared key not listed is
+   * removed from the rows after the hook. Empty when none is declared.
+   * Undeclared (`$`-prefixed) keys are not affected. Since 0.1.148.
+   */
+  decorations: ReadonlySet<string>;
 }
 /**
  * One text / vector / geo index of the bound readable with the LOGICAL field
@@ -940,6 +1076,8 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _derivedSource;
   /** `@db.writeOnly` paths of `$with` target readables, collected once per target. */
   private readonly _targetWriteOnly;
+  /** Own leaf paths per readable (bound + `$with` targets), see {@link _leavesOf}. */
+  private readonly _targetLeaves;
   private _indexFieldPathsCache?;
   /** {@link _nativeSearch} per request, keyed by the request's parsed controls. */
   private readonly _nativeSearchByRequest;
@@ -963,8 +1101,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private readonly _gateFieldsMemo;
   /** `true` when a subclass overrides {@link allowedActions}. */
   private readonly _hasAllowedActions;
+  /** The class's validated `@DbDecorations` (since 0.1.148), `undefined` when none is declared. */
+  private readonly _decorations;
+  /** The decoration plumbing of {@link _decorations} — see `DecorationPlanner`. */
+  private readonly _planner;
   /** `true` when a subclass overrides {@link actionRowScope} (the gate, `$actions` and `/meta/actions` apply it). */
   private readonly _hasActionRowScope;
+  /** @internal `true` when a subclass overrides {@link resolveRowIds} (every id-addressed endpoint calls it; since 0.1.148). */
+  readonly [ROW_RESOLVES]: boolean;
   /** `true` when the class declares `@DbActionsFrom` (since 0.1.147). */
   private readonly _hasDelegations;
   /** `transformProjection` is overridden (a delegation's id paths are checked against it). */
@@ -982,6 +1126,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    */
   private readonly _invertibleFields;
   constructor(app: Moost, readable?: AtscriptDbReadable<T>);
+  /**
+   * The class's `@DbDecorations`, validated against the bound readable once
+   * per class and readable (a `[moost-db]` error when invalid); warns once
+   * when `decorateRows` is not implemented.
+   */
+  private _resolveDecorations;
   /**
    * The identifications this request may address rows through (since
    * 0.1.134): the readable's own, minus unique indexes over fields
@@ -1231,34 +1381,24 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * The rows the row-level action `actionName` may run on (since 0.1.145),
    * as an extra row filter; `undefined` or `{}` = no restriction (the
    * default). Enforced by the action gate — the action's ids / rows are
-   * loaded under {@link rowOverlay}, then checked against this filter, so an
-   * id outside it gets the same 404 "Row not found for action identifier"
+   * loaded under {@link rowOverlay}, then checked against this filter (or —
+   * without an overlay — the filter joins the load), so an id outside it gets
+   * the same 404 "Row not found for action identifier"
    * as a missing one — and reflected in `$actions` and
    * `GET /meta/actions`, which list the action only on rows inside it.
    *
-   * Since 0.1.147 the hook receives the candidate rows (`ctx`), so a scope
-   * can depend on them — e.g. derive `{ ticketKey: { $in: … } }` from a
-   * related table read for exactly these rows:
-   *
-   * | `ctx.purpose` | asked by | `ctx.ids` |
-   * | --- | --- | --- |
-   * | `"execute"` | the action gate | the loaded ids / rows (≤ `maxIds`; one batch of a query target) |
-   * | `"rows"` | `$actions` on a read (and a view's delegated verdicts) | the read's rows |
-   * | `"available"` | `GET /meta/actions/:id` | the one row |
-   *
-   * - Called only with at least one candidate, at most once per action per
-   *   evaluation; `ctx.ids` is the same array object for every action of
-   *   one evaluation (memoize on it with a `WeakMap`).
-   * - Candidates are already inside the row overlay — ids that do not exist
-   *   or fall outside it never reach the hook.
-   * - The result only restricts (`ids ∧ rowOverlay ∧ scope`); a throw fails
-   *   the request — never a silent "allow".
-   * - The filter runs straight against the bound readable: it may use
-   *   fields {@link hasField} hides, and nothing of it (nor of
-   *   `ctx.loadRows`) reaches the response. Equal filters — the same object,
-   *   or structurally equal ones — share one id-only query.
-   * - Runs after {@link prepareRequest} and, on the action route, after the
-   *   request body is read (it needs the ids).
+   * The hook receives the candidate rows (`ctx`), so a scope can depend on
+   * them — what `ctx.purpose`, `ctx.ids` and `ctx.loadRows` hold, and when the
+   * hook is asked before any load, is documented on {@link TDbActionScopeContext}.
+   * Called only with at least one candidate, at most once per action per
+   * evaluation. An answer restricting nothing (`undefined`, `null`, `{}`)
+   * makes the gate load no row at all; a restriction is folded into the one
+   * row load. The result only restricts (`ids ∧ rowOverlay ∧ scope`); a throw
+   * fails the request — never a silent "allow". The filter runs straight
+   * against the bound readable: it may use fields {@link hasField} hides, and
+   * nothing of it reaches the response. Runs after {@link prepareRequest} and,
+   * on the action route, after the request body is read and
+   * {@link resolveRowIds}.
    *
    * Not overriding it costs nothing; a one-parameter override keeps working.
    * moost-db always passes `ctx` — it is optional in the signature only so
@@ -1320,6 +1460,18 @@ 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>;
+  /**
+   * The shared projection step of `/query`, `/pages`, `/geo` and `/one`:
+   * splits the declared decoration keys out of the wire `$select`
+   * ({@link DecorationPlanner.plan}), runs {@link transformProjection} on the
+   * rest (decoration keys never reach it — a permission layer needs no
+   * change; their `requires` paths are added so the hook's inputs are read),
+   * then seals every projection level. `finish` completes it once the
+   * endpoint is past its own checks: the preferred-id widening (an
+   * `HttpError` for a mixed `$select`) and the decoration step — what every
+   * read endpoint then passes to {@link _runReadWithActions}.
+   */
+  private _projectRead;
   private widenPreferredIdProjection;
   private _widenArrayProjection;
   private _widenMapProjection;
@@ -1394,6 +1546,12 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * loaded candidates ({@link ACTION_SCOPE}).
    */
   [ACTION_OVERLAY](): Promise<FilterExpr | undefined>;
+  /**
+   * @internal {@link resolveRowIds} for an action's validated ids (since
+   * 0.1.148): the output validated, duplicate identities collapsed, and the
+   * ids as the client sent them kept for the error bodies and summaries.
+   */
+  [ROW_RESOLVE_IDS](ids: readonly Record<string, unknown>[], ctx: TDbRowIdsContext): Promise<TAppliedIds>;
   /** @internal {@link actionRowScope} for the gate's loaded candidates (since 0.1.147). */
   [ACTION_SCOPE](action: string, ctx: TDbActionScopeContext): Promise<FilterExpr | undefined>;
   /** @internal `true` when {@link actionRowScope} is overridden (since 0.1.147). */
@@ -1427,11 +1585,13 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   /**
    * `select` without the `sealed` paths (see {@link _sealControls}); an
    * exclusion of them is forced when there is no projection, or when every
-   * requested path was sealed.
+   * requested path was sealed. An inclusion naming a PARENT of a sealed path
+   * (`secret` over a write-only `secret.hash`) is replaced by the parent's
+   * unsealed leaves, so a sealed descendant never rides along with it.
    */
   private _sealSelect;
-  /** First `@db.writeOnly` field referenced by `$groupBy` / aggregate `$select`, or undefined. */
-  private _findWriteOnlyInAggregate;
+  /** Own leaf field paths (no navigation, no ignored field) of `readable`, once per readable. */
+  private _leavesOf;
   /**
    * Merges the `$search` fallback into the filter: a case-insensitive literal
    * substring match OR'd across the `@db.column.searchable` fields, `$and`-combined
@@ -1473,11 +1633,17 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * (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` or `$disabledReasons`. Columns the
-   * hook needs but the client did not select must be added in
-   * {@link transformProjection} — they are then part of the response.
+   * Two kinds of keys. **Undeclared** keys: name them with a `$` prefix, like
+   * `$actions` and `$distance`, so they can never collide with a field; they
+   * are always kept and a client cannot select them. **Declared** keys
+   * ({@link DbDecorations}, since 0.1.148): list them with `@DbDecorations`,
+   * and a client may name them in `$select`; compute only `ctx.decorations`,
+   * read your inputs from the columns `requires` names, and any declared key
+   * not in `ctx.decorations` — and every column added only for the hook — is
+   * removed from the rows afterwards. Do not overwrite `$actions` or
+   * `$disabledReasons`. Without `@DbDecorations`, 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) {
@@ -1564,13 +1730,86 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * strategy to its read-method family (count vs no-count).
    */
   private _runReadWithActions;
+  /**
+   * Maps the ids an id-addressed endpoint received to the rows' current ids
+   * (since 0.1.148) — the seam for stale or alias ids, e.g. a natural key that
+   * was renamed. Called once per request, after {@link prepareRequest} and
+   * after the request's own validation, before anything reads the row, by:
+   *
+   * | `ctx.purpose` | endpoint | `ids` |
+   * | --- | --- | --- |
+   * | `"one"` | `GET /one/:id`, `GET /one?…` | one id: the path string, or the `?`-form identification object |
+   * | `"available"` | `GET /meta/actions/:id`, `?…` (and a view asking its source) | one id, as above |
+   * | `"remove"` | `DELETE /:id`, `DELETE /?…` (`AsDbController`) | one id, as above |
+   * | `"action"` | an action route | the body's validated ids (one for a `'row'` action) |
+   *
+   * Contract:
+   *
+   * - Return one id per input id, index-aligned (anything else is a 500). An
+   *   id that already names a row must come back UNCHANGED — the current
+   *   holder of a key wins over an alias; so must an id you cannot resolve
+   *   (never throw for an unknown alias: a custom error is an oracle — the
+   *   endpoint then answers its normal miss).
+   * - The output is validated (a server bug is a 500, never a client 400): a
+   *   scalar is resolved like a path scalar (primary key first, then the
+   *   visible unique keys, inside the row overlay); an object must be one of
+   *   the visible identifications ({@link idSource}); an `"action"` id must
+   *   be such an object.
+   * - The resolved id is never trusted for access: the endpoint still reads
+   *   or deletes it under {@link rowOverlay} and the visible identifications.
+   *   `ctx.overlay` is that overlay — resolve INSIDE it when an alias could
+   *   name several rows, so a row the caller can't reach never shadows one
+   *   they can. Don't log or return the canonical id in errors.
+   * - Handlers (`@DbActionID()`, `useDbActionId()`), {@link rowOverlay} reads,
+   *   {@link actionRowScope} and `onRemove` / `guardRemove` receive the
+   *   resolved ids; error bodies and `summary()` echo the ids the client sent.
+   * - Write bodies (`POST` / `PUT` / `PATCH`) are not resolved — use
+   *   `onWrite`. Not called by value-help controllers, `$actions` on a read
+   *   or a query target. Not overriding it costs nothing.
+   *
+   * It is NOT overridden by {@link resolveRowFilter}, which does not take part
+   * in `/one` for real tables and views.
+   *
+   * ```ts
+   * protected async resolveRowIds(ids: readonly TDbRowIdInput[], ctx: TDbRowIdsContext) {
+   *   return Promise.all(ids.map(async (id) => {
+   *     const key = typeof id === "object" ? id.code : id
+   *     if (typeof key !== "string") return id
+   *     // the current holder of the key wins; consult the alias table on a miss
+   *     // resolve INSIDE the overlay: a row the caller cannot reach never wins
+   *     const inScope = (code: string) =>
+   *       this.readable.count({ filter: ctx.overlay ? { $and: [{ code }, ctx.overlay] } : { code } })
+   *     if (await inScope(key)) return id
+   *     const alias = await aliases.findOne({ filter: { oldCode: key } })
+   *     if (!alias || !(await inScope(alias.newCode))) return id
+   *     return typeof id === "object" ? { code: alias.newCode } : alias.newCode
+   *   }))
+   * }
+   * ```
+   *
+   * @since 0.1.148
+   */
+  protected resolveRowIds(ids: readonly TDbRowIdInput[], _ctx: TDbRowIdsContext): readonly TDbRowIdInput[] | Promise<readonly TDbRowIdInput[]>;
+  /** {@link resolveRowIds} with its output validated (a server bug is a 500). */
+  private _runResolveRowIds;
+  /**
+   * @internal The one id of an id-addressed endpoint through
+   * {@link resolveRowIds} (identity, at no cost, when it is not overridden)
+   * and the row overlay it was resolved inside — computed once, for the
+   * endpoint's read or delete under that overlay.
+   */
+  protected _resolveWithOverlay(id: TDbRowIdInput, purpose: Exclude<TDbRowIdPurpose, "action">): Promise<{
+    id: TDbRowIdInput;
+    overlay: FilterExpr | undefined;
+  }>;
   /**
    * The filter addressing exactly the ONE row `id` means — the readable's
    * PK-first `resolveRowFilter` (since 0.1.143) under this request's
    * identifications (`_idOpts`). `scope` (the row overlay) restricts which
    * rows count while the id is pinned, so a row outside it never shadows one
    * inside it. Readables without it (partial mocks) fall back to
-   * `resolveIdFilter`.
+   * `resolveIdFilter`. Not an alias seam: `/one` reads through `findOneByRow`
+   * on every real table or view — map stale ids in {@link resolveRowIds}.
    */
   protected resolveRowFilter(id: unknown, scope?: FilterExpr): Promise<FilterExpr | null>;
   /**
@@ -1668,6 +1907,26 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * `/one?…` rules.
    */
   availableActions(query: Record<string, string>): Promise<TDbAvailableActions$1 | HttpError>;
+  /** Every field of every identification (primary key and unique indexes) the view addresses a row by. */
+  private _identificationFields;
+  /**
+   * A delegation's source id: each source id field from the row's mapped path
+   * of the RESOLVED `id`. A path of ANY of the view's identifications
+   * (`consumed` — not just the one the request matched: `?id=1&code=T-OLD` names
+   * `code` too) is NEVER taken from the raw `?` query: that value may be an
+   * alias `resolveRowIds` rewrote, and the source would see (and answer for)
+   * it. Paths outside the identification fall back to `fallback`'s (the raw
+   * query's) value; `undefined` when a path has none.
+   */
+  private _sourceIdOf;
+  /**
+   * {@link _availableActions} for a request id (`names`: only those actions):
+   * through {@link resolveRowIds} (`"available"`) first, the row overlay
+   * computed once for both — and the resolved id returned as an object (a
+   * scalar is the single-field `preferredId` value) for the delegated part to
+   * derive its source id from.
+   */
+  private _availableResolved;
   /**
    * **POST /delegated-actions/:name** — a query target for a `@DbActionsFrom`
    * action whose source action declares `queryTarget` (since 0.1.147); the
@@ -1787,7 +2046,9 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    */
   protected onWrite(action: TDbWriteAction$1, data: unknown): unknown;
   /**
-   * Intercepts delete operations. Return `undefined` to abort (500 "Not
+   * Intercepts delete operations. Receives the id {@link resolveRowIds}
+   * resolved (the one the request carried when it is not overridden; since
+   * 0.1.148). 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).
@@ -1895,8 +2156,16 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   private _deleteOrThrow;
   /**
    * **POST /** — inserts one or many records.
+   *
+   * `?$onConflict=ignore` (since 0.1.148) skips rows colliding on the primary
+   * key or a unique index instead of answering 409. The response then is
+   * `{ insertedId?, conflict }` for an object body and
+   * `{ insertedCount, insertedIds, inserted, conflicts }` for an array body.
+   * Any other `$` control on POST answers 400.
    */
-  insert(payload: unknown): Promise<unknown>;
+  insert(payload: unknown, url?: string): Promise<unknown>;
+  /** The only POST control: `$onConflict` (`error` | `ignore`). Anything else `$…` → 400. */
+  private _readOnConflict;
   /**
    * **PUT /** — fully replaces one or many records matched by primary key.
    *
@@ -2161,6 +2430,59 @@ declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtsc
   private normalizeSort;
 }
 //#endregion
+//#region src/decorations/db-decorations.decorator.d.ts
+/** Options of {@link DbDecorations}. @since 0.1.148 */
+interface TDbDecorationsOpts<D = Record<string, unknown>> {
+  /**
+   * Per decoration key, the bound readable's field paths `decorateRows` reads
+   * to compute it. Those paths are selected (and kept visible) automatically
+   * and stripped from the response unless the client selected them. A
+   * decoration that reveals a field's data MUST list it: the decoration is
+   * then served — and listed in `/meta` — only while that field is visible.
+   */
+  requires?: { [K in keyof D & string]?: readonly string[] };
+}
+/** Class metadata written by {@link DbDecorations}. */
+interface TDbDecorationsMeta {
+  /** The declared interface (a plain object type, no `@db.table` / `@db.view`). */
+  type: TAtscriptAnnotatedType;
+  /** Decoration key → the readable's field paths it reads. */
+  requires: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Declares display-only (decoration) fields of a table or view controller —
+ * values `decorateRows` computes and attaches to rows (since 0.1.148).
+ *
+ * `type` is a plain atscript interface (no `@db.table` / `@db.view`) whose
+ * top-level props are the decorations: their `@meta.label`, `@expect.*` and
+ * `@ui.*` annotations travel in `/meta.decorations`, each key is listed in
+ * `/meta.fields` with `decoration: true`, and a client may name it in
+ * `$select`. A decoration is never filterable, sortable or groupable, and it
+ * is not part of `/meta.type` (forms and write validation never see it).
+ *
+ * ```ts
+ * @TableController(TicketTable)
+ * @DbDecorations(TicketDecorations, { requires: { ownerName: ["ownerId"] } })
+ * export class TicketsController extends AsDbController<typeof TicketTable> {
+ *   protected async decorateRows(rows: Record<string, unknown>[], ctx: TDbDecorateContext) {
+ *     if (ctx.decorations.has("ownerName")) {
+ *       // read rows[i].ownerId, set rows[i].ownerName
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Validated once per class at first use (a `[moost-db]` error): the type is an
+ * object interface; keys are top-level identifiers that collide with no field
+ * or relation of the readable; every `requires` path is an own, readable
+ * (not `@db.writeOnly`) field or a parent object of own fields (on SQL a nested
+ * object is flattened to leaf columns; the hook still gets the whole object). Inherited under `@Inherit()`. Not supported on
+ * value-help controllers.
+ *
+ * @since 0.1.148
+ */
+declare function DbDecorations<D extends TAtscriptAnnotatedType>(type: D, opts?: TDbDecorationsOpts<TAtscriptDataType<D>>): ClassDecorator;
+//#endregion
 //#region src/actions/keys.d.ts
 type TDbActionRowMarker = true;
 /** Stamped by `@InputForm(FormType)` — the compiled `.as` class + the wire name (`FormType.name`). */
@@ -2201,6 +2523,7 @@ declare module "moost" {
     atscript_db_action_rows?: TDbActionRowMarker;
     atscript_db_endpoint?: TDbRequestEndpoint;
     atscript_db_actions_from?: TDbActionsFromMeta[];
+    atscript_db_decorations?: TDbDecorationsMeta;
   }
   interface TMoostParamsMetadata {
     atscript_db_action_param?: TDbActionParamKind;
@@ -2262,6 +2585,8 @@ interface AtscriptDbMeta {
   atscript_db_endpoint?: TDbRequestEndpoint;
   /** Class-level — written by `@DbActionsFrom(...)` (since 0.1.147). Decorators accumulate. */
   atscript_db_actions_from?: TDbActionsFromMeta[];
+  /** Class-level — written by `@DbDecorations(...)` (since 0.1.148). */
+  atscript_db_decorations?: TDbDecorationsMeta;
 }
 /**
  * Param-level metadata written by `@atscript/moost-db`'s param
@@ -3094,4 +3419,4 @@ declare const REL_FILTER_CLIENT_MAX_DEPTH = 3;
  */
 declare const REL_FILTER_CLIENT_MAX_NODES = 8;
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionTargetError, type ActionTargetErrorBody, AsDbController, AsDbReadableController, AsJsonValueHelpController, AsReadableController, AsValueHelpController, type AtscriptDbMate, type AtscriptDbMeta, type AtscriptDbParamsMeta, DB_CRUD_HANDLERS, DEFAULT_DB_SPACE, DbAction, DbActionDefault, type DbActionEnvelope, DbActionID, DbActionIDs, type DbActionOpts, DbActionRow, DbActionRows, DbActionTarget, DbActions, DbActionsFrom, DbDecorations, DbRowActions, DbRowsActions, DbTableActions, FieldCapabilityIndex, type IdValidationSource, InputForm, ONE_CONTROLS, PAGES_CONTROLS, QUERY_CONTROLS, READABLE_DEF, REL_FILTER_CLIENT_MAX_DEPTH, REL_FILTER_CLIENT_MAX_NODES, ReadableController, TABLE_DEF, type TActionTargetErrorCode, TAssertExposedOptions, type TCapabilityReadable, type TCapabilityVerdict, TControllerBindingOptions, type TCrudOp, type TCrudPermissions, type TDbActionDisabledVerdict, type TDbActionEnvelope, type TDbActionInfo, type TDbActionInputFormMeta, type TDbActionIntent, type TDbActionLevel, type TDbActionMeta, type TDbActionParamKind, type TDbActionProcessor, type TDbActionQueryTarget, type TDbActionScopeContext, type TDbActionScopePurpose, type TDbActionTarget, type TDbActionTargetSummary, type TDbActionsEntry, type TDbActionsEntryUnpinned, type TDbActionsFromMeta, type TDbActionsFromOpts, type TDbAvailableActions, type TDbClassActionMeta, TDbControlsType, TDbDecorateContext, TDbDecorateEndpoint, type TDbDecorationsOpts, TDbFieldVisibility, TDbIndexFieldPaths, TDbParsedRequest, type TDbQueryTargetOpts, type TDbRemoveGuardContext, TDbRequestContext, TDbRequestEndpoint, type TDbRowIdInput, type TDbRowIdPurpose, type TDbRowIdsContext, type TDbWriteAction, type TDbWriteCheckContext, type TDbWriteGuardContext, type TFieldCapability, type TGateOp, type THttpErrorEntry, type TQueryPathOp, type TQueryPathRefs, TReadableBinding, type TReadableBindingMeta, type TTerminalRef, TableController, UseValidationErrorTransform, VALUE_HELP_CRUD_HANDLERS, ValueHelpQuery, ValueHelpSelect, ViewController, applyTerminalRefs, assertExposed, badRequest, clearDbSpaces, closeDbSpaces, collectQueryPaths, dbActionBodySlot, dbActionInputSlot, discoverActions, discoverRowLevelActions, errorEnvelope, findReadableBinding, getAtscriptDbMate, getControllerFormType, getDbEndpoint, hasActionDelegations, perRow, provideDbSpace, resolveBoundReadable, resolveDbSpace, resolveProp, resolveTerminalRef, unknownRelationError, useDbActionId, useDbActionIds, useDbActionInput, useDbActionRow, useDbActionRows, useDbActionTarget, validationErrorTransform };