@atscript/db 0.1.146 → 0.1.148

package/dist/{buckets-DYFu0eZ8.d.cts → buckets-DJiYlMXc.d.cts}

@@ -1,8 +1,41 @@
 import { f as TFieldOps } from "./ops-AqhV7s9o.cjs";
-import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
-import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, RelationOp, ResolvedBucket, ResolvedRowOrderKey, ResolvedSelectExpr, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
+import { AtscriptExprNode, AtscriptExprNode as AtscriptExprNode$1, AtscriptOrderItem, AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 
 //#region src/query/uniqu-select.d.ts
+/** A row-level expression aggregate: `fn(<expr>)` over each row (physical field leaves). */
+interface TExprAggregate {
+  fn: "sum" | "avg" | "min" | "max";
+  alias: string;
+  expr: AtscriptExprNode;
+  /** The distinct physical columns the expression reads. */
+  names: readonly string[];
+}
+/** A group-level expression: leaves name aliases of other entries or grouped columns. */
+interface TSelectExpr {
+  alias: string;
+  expr: AtscriptExprNode;
+  /** The distinct names the expression reads (aliases of other entries, or grouped columns). */
+  names: readonly string[];
+}
+/** A `first` / `last` entry: the value of PHYSICAL `column` on the group's representative row. */
+interface TFirstLast {
+  fn: "first" | "last";
+  column: string;
+  alias: string;
+}
+/** One key of the representative-row order (PHYSICAL column). */
+interface TRowOrderKey {
+  column: string;
+  desc: boolean;
+}
+/** The arithmetic and representative-row parts of an aggregate `$select`, as the field mapper resolves them. */
+interface TUniquComputed {
+  exprAggregates?: readonly TExprAggregate[];
+  exprs?: readonly TSelectExpr[];
+  rowOrder?: readonly TRowOrderKey[];
+  sources?: ReadonlyMap<string, TDbFieldMeta>;
+}
 /**
  * Wraps a raw `$select` value and provides lazy-cached conversions
  * to the forms different adapters need.
@@ -13,8 +46,9 @@ import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef a
  * For exclusion → inclusion inversion, pass `allFields` (physical field names).
  *
  * An array `$select` holds plain field names and computed entries —
- * aggregates (`{ $fn, $field }`, {@link aggregates}) and calendar buckets
- * (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
+ * aggregates (`{ $fn, $field }`, {@link aggregates}), `first` / `last`
+ * ({@link firstLast}), arithmetic ({@link exprAggregates}, {@link exprs}) and
+ * calendar buckets (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
  * (`normalizeComputedSelect` rejects any other shape before translation).
  */
 declare class UniquSelect {
@@ -23,7 +57,6 @@ declare class UniquSelect {
   private _allFields?;
   private _array;
   private _projection;
-  private _aggregates;
   /**
    * The calendar buckets of an aggregate `$select`, normalized (canonical
    * zone, week start, alias) with the PHYSICAL source `field` and its
@@ -32,14 +65,56 @@ declare class UniquSelect {
    * columns). Since 0.1.132.
    */
   readonly buckets: readonly TResolvedBucket[] | undefined;
+  /**
+   * The plain aggregates (`{ $fn, $field }`) of an array-form `$select`;
+   * `undefined` when there are none or the `$select` is object form.
+   * `first` / `last` are listed separately ({@link firstLast}), so an adapter
+   * written before them never meets one here.
+   */
+  readonly aggregates: AggregateExpr[] | undefined;
+  /** The `first` / `last` entries of an array-form `$select` (since 0.1.148); `undefined` when none. */
+  readonly firstLast: readonly TFirstLast[] | undefined;
+  /**
+   * Row-level expression aggregates (`sum(price*qty)`) — leaves are physical
+   * columns; render `fn(<expr>)` per row. `undefined` when there are none.
+   * Only reaches adapters whose `supportsAggregateExpressions()` is true.
+   * Since 0.1.148.
+   */
+  readonly exprAggregates: readonly TExprAggregate[] | undefined;
+  /**
+   * Group-level expressions in dependency order: each leaf names an alias
+   * defined by an aggregate / `first` / `last` / expression entry or a
+   * grouped column; evaluate after grouping. `undefined` when there are none.
+   * Since 0.1.148.
+   */
+  readonly exprs: readonly TSelectExpr[] | undefined;
+  /**
+   * The order of the rows inside each group that `first` / `last` read, as
+   * physical columns, with the primary key appended as the final ascending
+   * tie-break. `undefined` without `first` / `last`. Since 0.1.148.
+   */
+  readonly rowOrder: readonly TRowOrderKey[] | undefined;
+  /**
+   * The descriptors of the PHYSICAL columns a `min` / `max` / `first` / `last`
+   * reads — for an engine that cannot aggregate a type directly (PostgreSQL
+   * has no `MIN(boolean)`). Since 0.1.148.
+   */
+  readonly sources: ReadonlyMap<string, TDbFieldMeta>;
+  /**
+   * The output alias of every computed entry but the calendar buckets, in the
+   * order adapters emit them: {@link aggregates}, {@link exprAggregates},
+   * {@link firstLast}, then {@link exprs} (which read the others). Since 0.1.148.
+   */
+  readonly computedAliases: readonly string[];
   /**
    * @param raw - the `$select` value (field paths already physical).
    * @param allFields - physical field names, for exclusion-form inversion.
    * @param buckets - the resolved calendar buckets of the raw `$select`'s
    *   `{ $bucket }` entries (the field mappers supply them — physical `field`,
    *   source `fd`).
+   * @param computed - the resolved arithmetic and `$rowOrder` parts (physical).
    */
-  constructor(raw: UniqueryControls["$select"], allFields?: string[], buckets?: readonly TResolvedBucket[]);
+  constructor(raw: UniqueryControls["$select"], allFields?: string[], buckets?: readonly TResolvedBucket[], computed?: TUniquComputed);
   /**
    * Resolved inclusion array of plain field names (strings only).
    * Computed entries (aggregates, calendar buckets) are filtered out.
@@ -53,11 +128,6 @@ declare class UniquSelect {
    * AggregateExpr objects in array form are ignored.
    */
   get asProjection(): Record<string, 0 | 1> | undefined;
-  /**
-   * Extracts AggregateExpr entries from array-form $select.
-   * Returns undefined if no aggregates present or if $select is object form.
-   */
-  get aggregates(): AggregateExpr[] | undefined;
   /** Whether the $select contains any AggregateExpr entries. */
   get hasAggregates(): boolean;
   /** The calendar bucket whose alias is `key`, if any — how adapters resolve a `$groupBy` / `$having` key. */
@@ -129,11 +199,28 @@ declare abstract class FieldMappingStrategy {
    * `buckets` are the query's calendar buckets as the core's normalizer
    * resolved them (`normalizeComputedSelect` — `AtscriptDbReadable.aggregate`
    * runs it before the guards); they reach adapters with `field` made
-   * physical and the source descriptor as `fd`.
+   * physical and the source descriptor as `fd`. `exprs` / `rowOrder` are the
+   * arithmetic entries and `$rowOrder` keys of the same normalizer
+   * (`resolveComputedSelect`): they reach adapters as `$select.exprAggregates`
+   * / `.exprs` / `.rowOrder` with physical names (the primary key appended to
+   * the order); `$rowOrder` itself is not forwarded (since 0.1.148).
+   */
+  translateAggregateQuery(query: AggregateQuery, meta: TableMetadata, buckets: readonly ResolvedBucket[], exprs?: readonly ResolvedSelectExpr[], rowOrder?: readonly ResolvedRowOrderKey[]): DbQuery;
+  /**
+   * `$having` with physical keys — except the computed output `aliases`,
+   * which stay as written (an alias equal to a renamed field's name,
+   * `first(raisedAt):raisedAt`, is the alias, exactly as in `$sort`).
    */
-  translateAggregateQuery(query: AggregateQuery, meta: TableMetadata, buckets: readonly ResolvedBucket[]): DbQuery;
-  /** Output aliases of the computed `$select` entries (aggregates and calendar buckets). */
+  private translateHaving;
+  /** Output aliases of the computed `$select` entries (aggregates, expressions and calendar buckets). */
   private computedAliasSet;
+  /**
+   * The arithmetic and `$rowOrder` parts of a grouped query with PHYSICAL
+   * names: a row-level operand is a column; a group-level operand stays an
+   * alias, or becomes the physical name of a `$groupBy` field. The primary
+   * key is appended to the order as the final ascending tie-break.
+   */
+  private physicalComputed;
   /**
    * `$select` with its field paths made physical: array-form names and
    * computed `$field`s (`'*'` kept), or the keys of the object
@@ -146,14 +233,30 @@ declare abstract class FieldMappingStrategy {
   /** `$sort` with physical keys; computed `aliases` (grouped queries) pass through. */
   protected physicalSort(sort: NonNullable<DbControls["$sort"]>, meta: TableMetadata, aliases?: ReadonlySet<string>): DbControls["$sort"];
   /**
-   * Recursively walks a filter expression, applying `@db.column` key renames
-   * (document paths — {@link TableMetadata.documentPath}) and adapter-specific
-   * value formatting via `formatFilterValue`.
+   * Translates a logical filter for the adapter: relational predicates are
+   * resolved first (`resolveRelationFilterTree`), then every key and value
+   * goes through {@link translateResolvedFilter}. `depth` is the predicate
+   * level of `filter` itself (0 for a query's own filter; the related tables
+   * translate predicate operands at deeper levels).
+   */
+  translateFilter(filter: FilterExpr, meta: TableMetadata, depth?: number): FilterExpr;
+  /**
+   * `out` — the translation of the caller's `filter` — with its pre-scan
+   * result (`has`) cached for the adapter's repeated `containsRelationFilter`
+   * checks; only when the core built it (never the caller's own object).
+   */
+  protected noteTranslated(filter: unknown, out: FilterExpr, has: boolean): FilterExpr;
+  /**
+   * Recursively walks a filter expression (predicates already resolved),
+   * applying `@db.column` key renames (document paths —
+   * {@link TableMetadata.documentPath}) and adapter-specific value formatting
+   * via `formatFilterValue`. A resolved predicate passes through under its
+   * navigation-field key.
    *
    * The relational mapper overrides this to use `leafByLogical` for deeper
    * key resolution (flattened nested paths).
    */
-  translateFilter(filter: FilterExpr, meta: TableMetadata): FilterExpr;
+  protected translateResolvedFilter(filter: FilterExpr, meta: TableMetadata): FilterExpr;
   abstract prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
   abstract translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   /** `$inc` / `$mul` field-op keys to physical names ({@link physicalPath}). */
@@ -289,6 +392,167 @@ declare class DbEncryption {
   private _getKey;
 }
 //#endregion
+//#region src/query/relation-filter.d.ts
+/**
+ * Relational filter predicates (`{ nav: { $some | $none: <filter on the
+ * related table> } }`) — resolution against the related tables.
+ *
+ * Semantics: `rel(r, nav)` is exactly the set of related rows `$with=nav`
+ * loads for row `r` (same foreign-key pairing, the relation's
+ * `@db.rel.filter` included). `$some: F` holds when one of them matches `F`,
+ * `$none: F` when none does; a NULL foreign-key component means "no related
+ * row". The core resolves each predicate into a {@link ResolvedRelationFilter}
+ * (physical names on every side, the inner filter translated by the related
+ * table's own field mapper) before the adapter sees the filter — adapters
+ * only render it.
+ *
+ * @since 0.1.147
+ */
+/**
+ * Maximum nesting of relational predicates in one filter, server-added ones
+ * included (a predicate inside a predicate's operand counts one level). The
+ * core backstop for every caller; higher than moost-db's per-client limit
+ * (`REL_FILTER_CLIENT_MAX_DEPTH`) so server overlays (row scopes,
+ * `transformRelationFilter`) have headroom above what a client may send.
+ */
+declare const REL_FILTER_MAX_DEPTH = 4;
+/** Maximum number of relational predicates in one filter (nested and server-added ones included). See {@link REL_FILTER_MAX_DEPTH}. */
+declare const REL_FILTER_MAX_NODES = 16;
+/** A table taking part in a resolved predicate. */
+interface TRelationFilterTable {
+  /** The adapter's `resolveTableName()` — schema-qualified when the table has a `@db.schema`. */
+  table: string;
+  /** The adapter's `resolveTableName(false)` — the bare table / collection name. */
+  name: string;
+  /** The adapter instance bound to this table. */
+  adapter: BaseDbAdapter;
+}
+/** The junction side of a resolved `via` predicate. */
+interface TRelationFilterJunction extends TRelationFilterTable {
+  /** Junction column → the SOURCE column it references (physical names). */
+  toSource: Array<{
+    junction: string;
+    source: string;
+  }>;
+  /** Junction column → the TARGET column it references (physical names). */
+  toTarget: Array<{
+    junction: string;
+    target: string;
+  }>;
+  /** The junction part of the relation's `@db.rel.filter` (junction physical names), if any. */
+  filter?: FilterExpr;
+}
+/**
+ * Cross-realm brand of {@link ResolvedRelationFilter}: `instanceof` fails when
+ * two copies of `@atscript/db` are loaded (ESM + CJS, or nested installs) and
+ * an adapter from one sees nodes built by the other.
+ */
+declare const RESOLVED_BRAND: unique symbol;
+/**
+ * A relational predicate as adapters receive it — the operand of
+ * `FilterVisitor.relation(field, op, operand)` once the core translated the
+ * filter. Every name is physical:
+ *
+ * - `to` / `from`: `pairs` correlate a SOURCE column with a TARGET column
+ *   (`target.<pair.target> = source.<pair.source>`, one pair per composite
+ *   key part);
+ * - `via`: `pairs` is empty — `junction.toSource` correlates the junction
+ *   with the source row, `junction.toTarget` with the target row.
+ *
+ * `filter` is the inner filter on the TARGET (already translated by the
+ * target's field mapper: renames, flattening, value formatters; nested
+ * predicates resolved the same way), conjoined with the target part of the
+ * relation's `@db.rel.filter`. `{}` matches every related row.
+ *
+ * @since 0.1.147
+ */
+declare class ResolvedRelationFilter {
+  /** @internal cross-realm brand (see {@link isResolvedRelationFilter}). */
+  readonly [RESOLVED_BRAND]: true;
+  readonly kind: "to" | "from" | "via";
+  /** Logical navigation field name on the source table. */
+  readonly nav: string;
+  readonly source: TRelationFilterTable;
+  readonly target: TRelationFilterTable;
+  readonly pairs: ReadonlyArray<{
+    source: string;
+    target: string;
+  }>;
+  readonly junction?: TRelationFilterJunction;
+  readonly filter: FilterExpr;
+  constructor(init: {
+    kind: "to" | "from" | "via";
+    nav: string;
+    source: TRelationFilterTable;
+    target: TRelationFilterTable;
+    pairs: Array<{
+      source: string;
+      target: string;
+    }>;
+    junction?: TRelationFilterJunction;
+    filter: FilterExpr;
+  });
+}
+/** `true` for a {@link ResolvedRelationFilter} (the resolved operand of a predicate). */
+declare function isResolvedRelationFilter(value: unknown): value is ResolvedRelationFilter;
+/** `true` when `value` (a filter entry's value) is an operator map with a `$some` / `$none` key. */
+declare function hasRelationOp(value: unknown): value is Record<string, unknown>;
+/**
+ * `true` when `filter` holds a relational predicate anywhere outside
+ * predicate operands (through `$and` / `$or` / `$not`) — the cheap pre-scan
+ * the field mappers and renderers use to keep predicate-free filters on
+ * their fast paths. Results for filters the core translated are cached.
+ */
+declare function containsRelationFilter(filter: unknown): boolean;
+/**
+ * Calls `visit` for every resolved predicate of a TRANSLATED filter,
+ * depth-first: the top-level ones, then (with `nested`) those inside each
+ * operand — target filters and junction filters alike. Adapters use it to
+ * prepare per-predicate data (memory snapshots, self-referencing checks).
+ */
+declare function forEachResolvedRelation(filter: unknown, visit: (node: ResolvedRelationFilter, op: RelationOp) => void, nested?: boolean): void;
+/** Shared state of one guarded filter: predicate depth / count and the read/write mode. */
+interface TRelGuardState {
+  /** Nesting level of the filter being guarded (0 = the query's own filter). */
+  depth: number;
+  /** Predicates seen so far in this query (shared by every level). */
+  counter: {
+    nodes: number;
+  };
+  /** Mutation filter (`supportsRelationFilters('write')`) vs read filter. */
+  write: boolean;
+  /** Dotted navigation chain of the filter being guarded (`""` at the root). */
+  path: string;
+}
+/** Installed on `TableMetadata.relationFilters` by the owning readable. */
+interface TRelationFilterHost {
+  /** Validates one predicate's operand against the related table (recursively). */
+  guard(nav: string, op: RelationOp, inner: FilterExpr, state: TRelGuardState): void;
+  /** Resolves one predicate into its adapter-facing form; `depth` is this predicate's level (≥ 1). */
+  resolve(nav: string, op: RelationOp, inner: FilterExpr, depth: number): ResolvedRelationFilter;
+}
+/** The present, non-empty `parts` ANDed (`{}` when none, a single one as is). */
+declare function andFilters(...parts: Array<FilterExpr | null | undefined>): FilterExpr;
+/** A relation's `@db.rel.filter`, split by the table each condition reads (LOGICAL names). */
+interface TRelationStaticFilter {
+  /** Conditions on the related (target) table. */
+  target?: FilterExpr;
+  /** Conditions on the junction table (`@db.rel.via` only). */
+  junction?: FilterExpr;
+}
+/**
+ * A relation's `@db.rel.filter` as logical filters per side — what `$with`
+ * loading and relational predicates both AND into the related rows (the
+ * filter is part of the relation's meaning). Top-level `and` conditions are
+ * split by side: an unqualified field and the related type's fields go to
+ * `target`, the `@db.rel.via` junction's to `junction`. A single condition
+ * that reads both sides (e.g. an `or` across them) or compares two fields is
+ * rejected with `INVALID_QUERY` — `name` is the navigation field (error path).
+ *
+ * @since 0.1.147
+ */
+declare function relationStaticFilter(relation: TDbRelation, name?: string): TRelationStaticFilter;
+//#endregion
 //#region src/table/db-readable.d.ts
 /**
  * Extracts nav prop names from a query's `$with` array.
@@ -358,6 +622,8 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * configured with an `encryption` options block.
    */
   setEncryption(encryption: DbEncryption | undefined): void;
+  /** @internal Set by the owning `DbSpace` when it closes. */
+  _spaceClosed: boolean;
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
   /**
@@ -369,6 +635,40 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   protected _ensureSearchable(): void;
   /** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
   protected _guardQuery(query: Uniquery | undefined): void;
+  /**
+   * Guards a relational predicate operand against THIS table — the filter
+   * guard and the path guard with the predicate's shared `state` (depth,
+   * count, read/write mode). Called by the source table's relation host.
+   *
+   * @internal Core wiring for relational predicates; not consumer API.
+   */
+  _guardRelationOperand(filter: FilterExpr, state: TRelGuardState): void;
+  /**
+   * Translates a relational predicate operand for THIS table's adapter (its
+   * own field mapper; nested predicates resolved at `depth + 1`).
+   *
+   * @internal Core wiring for relational predicates; not consumer API.
+   */
+  _resolveRelationOperand(filter: FilterExpr, depth: number): FilterExpr;
+  /**
+   * Translates a logical query (filter + controls) for THIS table's adapter
+   * after the read guards — exactly what `findMany` hands the adapter.
+   * For adapters that load `$with` relations natively and must address the
+   * related table's physical names.
+   *
+   * @internal Adapter-facing surface; not part of the consumer API.
+   * @since 0.1.147
+   */
+  _translateForAdapter(query: Uniquery): ReturnType<FieldMappingStrategy["translateQuery"]>;
+  /**
+   * Physical rows of THIS table → logical rows (field mapping, value
+   * formatters, decryption) — what every read does before `$with` loading.
+   * `controls` are the logical read controls the rows were read with.
+   *
+   * @internal Adapter-facing surface; not part of the consumer API.
+   * @since 0.1.147
+   */
+  _rowsFromAdapter(rows: Record<string, unknown>[], controls?: TReadControls): Promise<Record<string, unknown>[]>;
   private _encryptedPathsCache?;
   /** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
   protected get _encryptedPaths(): Array<{
@@ -401,6 +701,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   get indexes(): Map<string, TDbIndex>;
   /** Primary key field names from `@meta.id`. */
   get primaryKeys(): readonly string[];
+  /**
+   * Physical column lists that must be unique: the primary key (when declared)
+   * followed by every unique index and every adapter-contributed unique field. Used by conflict-ignoring inserts.
+   * @since 0.1.148
+   */
+  get uniqueKeySets(): string[][];
   /** Preferred row identifier field names. Defaults to primary keys. */
   get preferredId(): readonly string[];
   /** Legitimate row-identifier shapes (primary key + every unique index). */
@@ -495,6 +801,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   setVerbose(enabled: boolean): void;
   /** Precomputed logical dot-path → physical column name map. */
   get pathToPhysical(): ReadonlyMap<string, string>;
+  /**
+   * Physical column (or document path) of a logical field path —
+   * `@db.column` renames and flattening applied.
+   * @since 0.1.147
+   */
+  physicalPath(logical: string): string;
   /** Precomputed physical column name → logical dot-path map (inverse). */
   get physicalToPath(): ReadonlyMap<string, string>;
   /** Descriptor for the primary ID field(s). */
@@ -514,7 +826,10 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * its key was not selected.
    */
   private _translateRead;
-  /** Reconstructs + decrypts a read's rows, loads its `$with` relations and strips widened keys. */
+  /**
+   * Reconstructs + decrypts a read's rows, keeps the ones `pick` selects (all
+   * by default), loads their `$with` relations and strips widened keys.
+   */
   private _finishRead;
   /** `$select` plus the join keys of `withRelations` it leaves out — `undefined` when none is missing. */
   private _widenSelectForWith;
@@ -564,11 +879,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * table. Defense-in-depth for query-path validation: `flattenAnnotatedType`
    * still truncates real self-referential cycles, so paths like
    * `parent.parent.name` on a self-ref schema would miss `flatMap.has` but
-   * remain valid field references on the target.
+   * remain valid field references on the target — a path may cross the same
+   * relation any number of times (callers cap the depth).
    *
-   * Cycle-safe via a visited set keyed on `<tableName>:<navField>`.
+   * Terminates on cyclic schemas: every hop consumes one path segment.
    */
-  isValidFieldPath(path: string, _visited?: Set<string>): boolean;
+  isValidFieldPath(path: string): boolean;
   /**
    * Creates a new validator with custom options.
    */
@@ -585,6 +901,19 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * explicitly requested via `$with`.
    */
   findMany<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  /**
+   * `findMany` for the generic `$with` loader. With `partitionBy` (logical
+   * fields), `$skip` / `$limit` apply per group of rows sharing those fields'
+   * values (`BaseDbAdapter.findManyPerPartition`); `pick` chooses which of the
+   * read rows to keep before their own `$with` relations load.
+   *
+   * @internal Relation-loader surface; not part of the consumer API.
+   * @since 0.1.147
+   */
+  _findManyForRelation(query: Uniquery, opts: {
+    partitionBy?: readonly string[];
+    pick?: (rows: Record<string, unknown>[]) => Record<string, unknown>[];
+  }): Promise<Record<string, unknown>[]>;
   /**
    * Counts records matching the query.
    */
@@ -616,12 +945,20 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * then reverse-maps and applies fromStorage formatters on results.
    */
   aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * The computed aliases of one source field that is a boolean or a decimal —
+   * `min` / `max` / `first` / `last` — with that field's descriptor: the
+   * aggregate row's value is coerced like the column's own on read.
+   */
+  private _aliasFields;
   /** Whether the underlying adapter supports text search. */
   isSearchable(): boolean;
   /** Whether the adapter can filter on a given field (proxies adapter capability). */
   canFilterField(fd: TDbFieldMeta): boolean;
   /** Calendar-bucket units the adapter can group by (proxies adapter capability; empty = none). */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
+  /** Whether the adapter renders aggregate arithmetic (proxies adapter capability). @since 0.1.148 */
+  supportsAggregateExpressions(): boolean;
   /** Aggregate functions the adapter renders (proxies adapter capability). @since 0.1.136 */
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Whether the adapter can sort by a given field (proxies adapter capability). */
@@ -836,6 +1173,18 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
 }
 //#endregion
 //#region src/strategies/integrity.d.ts
+/**
+ * Result of {@link IntegrityStrategy.cascadeBeforeDelete}:
+ * - `undefined` — no cascade ran, or the filter holds no relational
+ *   predicate; delete with the caller's own filter;
+ * - an array — the rows the cascade ran for, pinned by primary key as
+ *   ADAPTER-READY (physical, already translated) filters, in batches. The
+ *   caller must delete exactly these rows instead of evaluating its filter
+ *   again: the cascade changed the data the filter may read (a relational
+ *   predicate on a child relation no longer matches once the children are
+ *   gone). An empty array means no row matched.
+ */
+type TCascadePin = FilterExpr[] | undefined;
 /**
  * Strategy for referential integrity enforcement.
  * Two implementations: {@link NativeIntegrity} (DB handles FK constraints)
@@ -843,7 +1192,7 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
  */
 declare abstract class IntegrityStrategy {
   abstract validateForeignKeys(items: Array<Record<string, unknown>>, meta: TableMetadata, fkLookupResolver: TFkLookupResolver | undefined, writeTableResolver: TWriteTableResolver | undefined, partial?: boolean, excludeTargetTable?: string): Promise<void>;
-  abstract cascadeBeforeDelete(filter: FilterExpr, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr) => FilterExpr, adapter: BaseDbAdapter): Promise<void>;
+  abstract cascadeBeforeDelete(filter: FilterExpr, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr) => FilterExpr, adapter: BaseDbAdapter): Promise<TCascadePin>;
   abstract needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
 }
 /**
@@ -852,7 +1201,7 @@ declare abstract class IntegrityStrategy {
  */
 declare class NativeIntegrity extends IntegrityStrategy {
   validateForeignKeys(): Promise<void>;
-  cascadeBeforeDelete(): Promise<void>;
+  cascadeBeforeDelete(): Promise<TCascadePin>;
   needsCascade(): boolean;
 }
 //#endregion
@@ -886,7 +1235,10 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Inserts a single record. Delegates to {@link insertMany} for unified
    * nested creation support.
    */
-  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
+  insertOne(payload: DbPatch<DataType>, opts: TInsertOptions<DataType> & {
+    onConflict: "ignore";
+  }): Promise<TDbInsertIgnoreResult>;
+  insertOne(payload: DbPatch<DataType>, opts?: TInsertOptions<DataType>): Promise<TDbInsertResult>;
   /**
    * Inserts multiple records with batch-optimized nested creation.
    *
@@ -903,7 +1255,11 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * 0.1.143) runs once after every phase with the inserted rows' primary-key
    * filters — see {@link TWriteOptions}.
    */
-  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts: TInsertOptions<DataType> & {
+    onConflict: "ignore";
+  }): Promise<TDbInsertManyIgnoreResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TInsertOptions<DataType>): Promise<TDbInsertManyResult>;
+  private _insertMany;
   /**
    * Replaces a single record identified by primary key(s).
    * Delegates to {@link bulkReplace} for unified nested relation support.
@@ -1057,6 +1413,24 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
   private _writtenPkFilters;
   /** Invokes a {@link TWriteOptions.check} with de-duplicated PK filters (inside the transaction). */
   private _runWriteCheck;
+  /**
+   * Ignore mode never writes a related parent — it would be orphaned when the
+   * row is skipped. A TO object that names only the target's key fields
+   * (`{ org: { id: 9 } }`) creates nothing: it is a reference to an existing
+   * parent, so it becomes the row's foreign key (the existence check follows
+   * with the other FK validation). Runs before validation (which would demand
+   * the parent's required fields); any other TO object is left for
+   * {@link _rejectNestedToInIgnoreMode}.
+   */
+  private _linkToByKeyInIgnoreMode;
+  /** Ignore mode: whatever TO object is left would create a related parent (see {@link _linkToByKeyInIgnoreMode}). */
+  private _rejectNestedToInIgnoreMode;
+  /**
+   * Conflict-ignoring main insert: marks rows repeating an earlier row's
+   * primary / unique key tuple (NULL components never collide), sends the rest
+   * to the adapter and assembles one slot per input row.
+   */
+  private _insertIgnoring;
   /**
    * The exact primary-key filter of each inserted row: the logical key from
    * the row (SDK defaults applied), else the stored key the adapter wrote into
@@ -1173,6 +1547,22 @@ interface TViewJoin {
    * @since 0.1.136
    */
   kind: "inner" | "left";
+  /**
+   * Set for a first-row join (the `@db.view.joins` 4th argument): of the
+   * target rows matching {@link condition} only the first by `order` joins.
+   * `order` refs are qualified with the target (`ref.type`), the target's
+   * primary key appended as the final ascending key unless already a key;
+   * `key` is that primary key's logical path — the anchor of the join's
+   * correlated subquery. NULL is the smallest value (first in `asc`).
+   * @since 0.1.147
+   */
+  first?: {
+    order: Array<{
+      ref: AtscriptQueryFieldRef;
+      desc: boolean;
+    }>;
+    key: string;
+  };
 }
 /** Resolved view query plan produced by AtscriptDbView. */
 interface TViewPlan {
@@ -1189,6 +1579,14 @@ interface TViewPlan {
  * via the provided resolver function.
  */
 declare function translateQueryTree(node: AtscriptQueryNode, resolveField: (ref: AtscriptQueryFieldRef) => string): FilterExpr;
+/**
+ * Evaluates a computed expression in process (the memory adapter, a test, a
+ * third-party adapter) with the semantics every adapter shares: IEEE double,
+ * a leaf is `Number()`-ed, NULL / undefined propagates as `null`, `/` by zero
+ * is `null`, `coalesce` returns its first non-null value.
+ * @since 0.1.148
+ */
+declare function evaluateExpr(expr: AtscriptExprNode, leaf: (field: string) => unknown): number | null;
 //#endregion
 //#region src/table/view-source.d.ts
 /**
@@ -1272,6 +1670,15 @@ interface TViewColumnMapping {
    * `@db.view.filter` (entry table + joins). @since 0.1.136
    */
   aggFilter?: AtscriptQueryNode;
+  /**
+   * A computed column (`@db.compute`): the arithmetic expression, its leaves
+   * naming the view's own fields by {@link viewPath}. Such a mapping reads no
+   * source column — `sourceTable` is the entry table and `sourceColumn` is
+   * `""` (unused). Renderers evaluate it in IEEE double with division by zero
+   * → NULL; `nullable` is set when the expression may be NULL.
+   * @since 0.1.147
+   */
+  expr?: AtscriptExprNode;
 }
 /**
  * Whether `type` declares a view (managed `@db.view.for` or external
@@ -1367,7 +1774,22 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    *   aggregate other than `count` over `'*'`.
    */
   getViewColumnMappings(): TViewColumnMapping[];
+  /**
+   * Why the bound adapter cannot render this managed view: one message per
+   * computed column / first-row join whose feature its `viewCapabilities()`
+   * does not list. Empty for an external view or when every feature is
+   * rendered. Schema sync refuses such a view; the adapter's `ensureTable()`
+   * throws for it (fail-closed for adapters that predate the features).
+   * @since 0.1.147
+   */
+  viewCapabilityProblems(): string[];
   private _buildColumnMappings;
+  /**
+   * The runtime twin of the compile-time `@db.compute` rules the renderers
+   * rely on: every leaf names a (non-ignored) view column, computed columns
+   * form no cycle; sets each computed mapping's `nullable`.
+   */
+  private _checkComputed;
   /** One view column over one physical source (a column or a JSON leaf). */
   private _leafMapping;
 }
@@ -1394,6 +1816,14 @@ interface TDbSpaceOptions {
   logger?: TGenericLogger;
   /** Field-level encryption configuration for `@db.encrypted` fields. */
   encryption?: TDbEncryptionOptions;
+  /**
+   * Runs once from {@link DbSpace.close}, after every adapter was disposed.
+   * Pass the resource the space does not own by itself, e.g.
+   * `() => driver.close()`. The `createAdapter` helpers of the adapter
+   * packages set it to close the driver they built.
+   * @since 0.1.148
+   */
+  onClose?: () => void | Promise<void>;
 }
 /**
  * A database space — a registry of tables and views sharing the same adapter type and driver.
@@ -1413,13 +1843,21 @@ interface TDbSpaceOptions {
  * const activeUsers = db.getView(ActiveUsersType)
  * ```
  */
-declare class DbSpace {
+declare class DbSpace implements AsyncDisposable {
   protected readonly adapterFactory: TAdapterFactory;
+  /** `await using` support — an alias for {@link close}, installed below where the runtime has the symbol. */
+  [Symbol.asyncDispose]: () => Promise<void>;
   private _readables;
   /** All tables created in this space — used for reverse FK lookup during cascade. */
   private _allTables;
+  /** Every table / view handle the space created — flagged closed on {@link close}. */
+  private _handles;
   /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
   private _adminAdapter?;
+  /** Every adapter this space created (tables, views, admin) — disposed on close. */
+  private _adapters;
+  private _onClose?;
+  private _closing?;
   protected readonly logger: TGenericLogger;
   /** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
   protected readonly _encryption?: DbEncryption;
@@ -1484,6 +1922,23 @@ declare class DbSpace {
    * Optional call: an adapter built against an older `@atscript/db` copy lacks it.
    */
   private _createAdapter;
+  /** `true` once {@link close} was called. @since 0.1.148 */
+  get closed(): boolean;
+  /** Throws `SPACE_CLOSED` once the space is closed. */
+  private _assertOpen;
+  /**
+   * Closes the space: marks it closed, disposes every adapter it created, then
+   * runs the `onClose` hook (the `createAdapter` helpers close their driver
+   * there). Idempotent — every call returns the first call's promise. Every
+   * step is attempted; failures are collected into an `AggregateError`.
+   *
+   * It does not cancel or drain in-flight queries: call it after the server
+   * stopped accepting requests. After close, `get*` and operations on existing
+   * table/view handles throw `DbError("SPACE_CLOSED")`.
+   * @since 0.1.148
+   */
+  close(): Promise<void>;
+  private _doClose;
   /**
    * Finds all child tables with FKs pointing to the given parent table name.
    * Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
@@ -1497,8 +1952,19 @@ declare class DbSpace {
 }
 //#endregion
 //#region src/base-adapter.d.ts
-/** Every calendar-bucket unit — what an adapter that renders them all returns from `calendarBucketUnits()`. */
+/**
+ * Every calendar-bucket unit — what an adapter that renders them all returns
+ * from `calendarBucketUnits()`. Includes `'hour'` since 0.1.147.
+ */
 declare const ALL_BUCKET_UNITS: ReadonlySet<BucketUnit>;
+/**
+ * A managed-view feature an adapter may render (`viewCapabilities()`):
+ * `compute` — computed columns (`@db.compute`); `firstJoin` — first-row joins.
+ * @since 0.1.147
+ */
+type TViewCapability = "compute" | "firstJoin";
+/** Every view capability — what the bundled adapters return from `viewCapabilities()`. @since 0.1.147 */
+declare const ALL_VIEW_CAPABILITIES: ReadonlySet<TViewCapability>;
 /**
  * Abstract base class for database adapters.
  *
@@ -1548,6 +2014,15 @@ declare abstract class BaseDbAdapter {
    * index sync, etc.
    */
   registerReadable(readable: AtscriptDbReadable<any, any, any, any, any, any, any>, logger?: TGenericLogger): void;
+  /**
+   * Makes `ensureTable()` of a managed view fail closed (since 0.1.147): it
+   * throws before the adapter renders a computed column / first-row join its
+   * {@link viewCapabilities} does not list — schema sync refuses such a view
+   * up front, a direct `ensureTable()` call must not render it as a plain
+   * (row-multiplying) join either. Wraps the subclass's own implementation, so
+   * third-party adapters get the guard without code changes.
+   */
+  private _guardViewCapabilities;
   /**
    * Called by {@link DbSpace} right after its factory builds this adapter —
    * the administrative one included — before {@link registerReadable}. No-op
@@ -1557,6 +2032,13 @@ declare abstract class BaseDbAdapter {
    * @since 0.1.137
    */
   registerSpace(_space: DbSpace): void;
+  /**
+   * Releases timers, caches or change streams the adapter holds. Called once
+   * by {@link DbSpace.close}; the driver itself is closed by the space's
+   * `onClose` hook, never here. No-op by default.
+   * @since 0.1.148
+   */
+  dispose?(): void | Promise<void>;
   /**
    * Enables or disables verbose (debug-level) logging for this adapter.
    * When disabled, no log strings are constructed — zero overhead.
@@ -1679,8 +2161,10 @@ declare abstract class BaseDbAdapter {
    * be adopted adapter by adapter. An adapter that returns a unit must group
    * by the bucket alias in `$groupBy` — see `controls.$select.buckets`
    * (`TResolvedBucket`: physical `field`, source `fd`) — and return the
-   * `YYYY-MM-DD` label of the bucket's first local day (null for a null or
-   * out-of-range source, uniqu's `bucketLabel` semantics). Since 0.1.132.
+   * `YYYY-MM-DD` label of the bucket's first local day, or for `'hour'` the
+   * local wall-clock hour `YYYY-MM-DDTHH:00` (null for a null or out-of-range
+   * source, uniqu's `bucketLabel` semantics). Since 0.1.132; `'hour'` since
+   * 0.1.147 — an adapter returning {@link ALL_BUCKET_UNITS} must render it.
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /**
@@ -1695,6 +2179,20 @@ declare abstract class BaseDbAdapter {
    * @since 0.1.136
    */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /**
+   * Whether this adapter renders arithmetic in an aggregate `$select`
+   * (`{ $expr }`, `{ $fn, $expr }`) — IEEE double, NULL propagating, `/` by
+   * zero NULL, the same semantics as `@db.compute`. Default `false`
+   * (fail-closed): the core rejects such a query with `AGG_EXPR_NOT_SUPPORTED`
+   * before dispatch. An adapter returning `true` also receives
+   * `controls.$select.exprAggregates` / `.exprs` (see `UniquSelect`), and
+   * `first` / `last` (`aggregateFns()`) with `.firstLast` and `.rowOrder`;
+   * the shared `evaluateExpr` evaluates an expression tree in process.
+   * moost-db advertises it as `/meta.aggregateExpressions`.
+   *
+   * @since 0.1.148
+   */
+  supportsAggregateExpressions(): boolean;
   /**
    * Revision of how this adapter renders a managed view (its SQL / pipeline)
    * from an unchanged view definition. Stored in each managed view's sync
@@ -1706,6 +2204,16 @@ declare abstract class BaseDbAdapter {
    * @since 0.1.137
    */
   viewRenderRevision(): string | undefined;
+  /**
+   * The managed-view features this adapter renders: `compute` — computed
+   * columns (`@db.compute`); `firstJoin` — first-row joins (the ordered 4th
+   * argument of `@db.view.joins`). Schema sync refuses a view using a feature
+   * not listed. The default is EMPTY (fail-closed): a third-party adapter
+   * opts in once it renders them.
+   *
+   * @since 0.1.147
+   */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   /**
    * Whether this adapter enforces foreign key constraints natively.
    * When `true`, the generic layer skips application-level cascade/setNull
@@ -1752,6 +2260,35 @@ declare abstract class BaseDbAdapter {
    * Default: `false` — the table layer uses application-level batch loading.
    */
   supportsNativeRelations(): boolean;
+  /**
+   * Whether this adapter renders relational filter predicates
+   * (`{ nav: { $some | $none: … } }`) in `mode` — `read` for find / count /
+   * search / aggregate filters, `write` for mutation filters
+   * (`updateMany`, `deleteMany`, …). Default `false`: the core rejects such
+   * filters with `REL_FILTER_NOT_SUPPORTED` before they reach the adapter.
+   *
+   * An adapter returning `true` receives each predicate already resolved by
+   * the core: the filter visitor's `relation(field, op, operand)` callback
+   * gets a `ResolvedRelationFilter` operand (`kind`, physical
+   * correlation `pairs`, `target` / `junction` tables with their adapters,
+   * and the inner `filter` already translated to the target's physical
+   * names, nested predicates resolved too). Keep `relation` on every
+   * `walkFilter` visitor that may meet such a filter.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
+  /**
+   * Whether `other` serves a table of the SAME store as this adapter, so one
+   * statement / pipeline can correlate both (a relational predicate renders
+   * the related table inside this table's query). Default: same adapter class
+   * and same {@link _transactionOwner} (the driver / pool / client the
+   * adapter was built with). Override when the owner is shared across
+   * separate databases (e.g. one Mongo client over several databases).
+   *
+   * @since 0.1.147
+   */
+  sharesStoreWith(other: BaseDbAdapter): boolean;
   /**
    * Loads relations onto result rows using adapter-native operations.
    * Only called when {@link supportsNativeRelations} returns `true`.
@@ -1987,6 +2524,22 @@ declare abstract class BaseDbAdapter {
     data: Array<Record<string, unknown>>;
     count: number;
   }>;
+  /**
+   * Reads like {@link findMany}, except that `$skip` / `$limit` apply to each
+   * partition — the rows sharing the values of the `partitionBy` columns
+   * (physical names) — instead of to the whole result. The generic `$with`
+   * loader reads the related rows of many parent rows at once this way, so a
+   * relation's `$skip` / `$limit` page each parent row's related rows.
+   * `$sort` orders the rows within a partition; how partitions interleave is
+   * unspecified.
+   *
+   * Default: one {@link findMany} without `$skip` / `$limit`, paged per
+   * partition in memory. The SQL adapters override it with a `ROW_NUMBER()`
+   * window, so only the kept rows are read.
+   *
+   * @since 0.1.147
+   */
+  findManyPerPartition(query: DbQuery, partitionBy: readonly string[]): Promise<Array<Record<string, unknown>>>;
   /**
    * Executes an aggregate query (GROUP BY + aggregate functions).
    * Default throws — override in adapters that support aggregation.
@@ -1994,6 +2547,21 @@ declare abstract class BaseDbAdapter {
   aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
   abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  /**
+   * Conflict-ignoring batch insert (`insertMany(rows, { onConflict: 'ignore' })`).
+   * Returns ONE SLOT PER INPUT ROW, in order: `{ insertedId }` for an inserted
+   * row, `null` for a row skipped because it collided with a STORED row on the
+   * primary key or a unique index. (The core already removed duplicates inside
+   * the batch.) Only uniqueness collisions are skipped — NOT NULL, FK, check
+   * and every other error must throw — and a skipped row must never abort the
+   * surrounding transaction. Fail-closed by default: throws
+   * `DbError("ON_CONFLICT_NOT_SUPPORTED")`; also override
+   * {@link supportsInsertIgnore}.
+   * @since 0.1.148
+   */
+  insertManyIgnore(_data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
+  /** Whether {@link insertManyIgnore} is implemented (drives `crud.insert: ["onConflict"]` in `/meta`). @since 0.1.148 */
+  supportsInsertIgnore(): boolean;
   abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
   abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   abstract deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -2350,6 +2918,14 @@ declare class TableMetadata {
   jsonValueParents: ReadonlySet<string>;
   /** Every field descriptor's `physicalName` — reserved names a bucket alias may not take. */
   physicalNames: ReadonlySet<string>;
+  /**
+   * Resolves / guards relational filter predicates (`{ nav: { $some: … } }`)
+   * against the related tables — installed by the owning readable when the
+   * table has navigation fields and a table resolver (a `DbSpace`). The field
+   * mappers and the path guard reach the related tables through it.
+   * @since 0.1.147
+   */
+  relationFilters?: TRelationFilterHost;
   private _built;
   private _identifications?;
   private _alwaysAddressable?;
@@ -2442,6 +3018,14 @@ declare class TableMetadata {
    * (flatMap, indexes, columnMap, etc.) is already populated.
    */
   private _buildFieldDescriptors;
+  /**
+   * Fills `physicalFields` / `physicalTargetFields` on every FK: the local
+   * side from this table's path maps, the target side from the referenced
+   * type's own `@db.column` renames (same storage rules as this table — a
+   * dotted target path is a flattened column on relational storage, a
+   * renamed top-level key on document storage).
+   */
+  private _resolveFkPhysicalFields;
   /**
    * Resolves `fkTargetField` for FK fields in field descriptors.
    */
@@ -2476,7 +3060,7 @@ declare class TableMetadata {
 //#endregion
 //#region src/types.d.ts
 /** Controls with resolved projection. Used in the adapter interface. */
-interface DbControls extends Omit<UniqueryControls, "$select"> {
+interface DbControls extends Omit<UniqueryControls, "$select" | "$rowOrder"> {
   $select?: UniquSelect;
 }
 /** Query object with resolved projection. Passed to adapter methods. */
@@ -2513,6 +3097,11 @@ interface TRelationInfo {
   name: string;
   direction: "to" | "from" | "via";
   isArray: boolean;
+  /**
+   * Present (true) when the relation is `@db.rel.filterable`: clients may
+   * filter by related rows (`nav=$some(…)` / `nav=$none(…)`). @since 0.1.147
+   */
+  filterable?: true;
 }
 /** Per-field capability flags in a meta response. */
 interface TFieldMeta {
@@ -2549,6 +3138,13 @@ interface TFieldMeta {
    * (`bucketUnits`). Since 0.1.132.
    */
   bucketable?: true;
+  /**
+   * Present (true) exactly when the field may be an operand of query-time
+   * arithmetic (`sum(price*qty)`, `expr(a/b)`) — a plain `number` (not a
+   * decimal or timestamp) that is visible and physically aggregatable — on an
+   * adapter with `aggregateExpressions`. Since 0.1.148.
+   */
+  numeric?: true;
   /**
    * Present (true) when the field is a `@db.column.derived` column: its value
    * is computed from a `@db.json` field of the same row and is never written
@@ -2556,6 +3152,27 @@ interface TFieldMeta {
    * render it read-only. Since 0.1.141.
    */
   derived?: true;
+  /**
+   * Present (true) when the field is a computed view column (`@db.compute`):
+   * its value is arithmetic over other fields of the view, evaluated by the
+   * database. Advisory — sorting / filtering follow `sortable` / `filterable`.
+   * Since 0.1.147.
+   */
+  computed?: true;
+  /**
+   * Present (true) exactly when `$groupBy` on this field passes the gate:
+   * physically filterable (adapter, not write-only, not encrypted) and, on a
+   * table declaring dimensions or measures, a dimension. Since 0.1.148.
+   */
+  groupable?: true;
+  /**
+   * Present (true) for a declared display-only decoration (`@DbDecorations`):
+   * a value the controller computes (`decorateRows`) and attaches to rows. Name
+   * it in `$select` to receive it; it is never filterable, sortable or
+   * groupable, and its column definition is in {@link TMetaResponse.decorations}
+   * (not in `type`). Since 0.1.148.
+   */
+  decoration?: true;
 }
 /** Built-in CRUD operation names; map 1:1 to public method names. */
 type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
@@ -2578,6 +3195,14 @@ interface TMetaResponse {
   relations: TRelationInfo[];
   fields: Record<string, TFieldMeta>;
   type: TSerializedAnnotatedType;
+  /**
+   * The declared display-only fields (`@DbDecorations`): an object type whose
+   * props are the decorations (with their `@meta.*`, `@expect.*` and `@ui.*`
+   * annotations), each also listed in {@link fields} with `decoration: true`.
+   * Absent when none is declared (or none is visible to the caller). Not part
+   * of {@link type}, so forms and write validation never see it. Since 0.1.148.
+   */
+  decorations?: TSerializedAnnotatedType;
   actions: TDbActionInfo[];
   crud: TCrudPermissions;
   /**
@@ -2602,6 +3227,15 @@ interface TMetaResponse {
    * @since 0.1.136
    */
   aggregateFns?: AggregateFn[];
+  /**
+   * Whether the adapter renders arithmetic in an aggregate `$select`
+   * (`{ $expr }`, URL `expr(a/b):alias`, `sum(price*qty):alias`) — see
+   * `BaseDbAdapter.supportsAggregateExpressions()`. Fields that may be
+   * operands are flagged `fields[P].numeric`.
+   *
+   * @since 0.1.148
+   */
+  aggregateExpressions?: boolean;
 }
 /** Where the action applies on the UI. */
 type TDbActionLevel = "table" | "row" | "rows";
@@ -2687,6 +3321,76 @@ interface TDbActionInfo {
    * @since 0.1.136
    */
   formUrl?: string;
+  /**
+   * Present on an action another controller owns and runs (a view
+   * delegating its source table's row actions): that controller's
+   * server-absolute base path. `value`, `formUrl` and the per-row
+   * `GET {owner}/meta/actions/:id` live there; `disabled` is not sent (the
+   * row's `$actions` verdict is authoritative).
+   *
+   * @since 0.1.147
+   */
+  owner?: string;
+  /**
+   * Delegated action only: the {@link owner}'s identification field → the
+   * path in THIS controller's rows that carries its value. Clients build the
+   * action's `ids` from a row through it. Absent when every pair is
+   * identical and is exactly this controller's `preferredId`.
+   *
+   * @since 0.1.147
+   */
+  idMap?: Record<string, string>;
+  /**
+   * `'rows'` level only: the action also accepts a query target — "every row
+   * matching this filter / search" instead of a list of identifiers — of at
+   * most `maxRows` rows. `url` (server-absolute) is where such a request is
+   * POSTed when it is not `value` (a delegated action: this controller
+   * resolves the query and runs the owner's action in batches).
+   *
+   * @since 0.1.147
+   */
+  queryTarget?: {
+    maxRows: number;
+    url?: string;
+  };
+}
+/**
+ * Outcome of an action run over a target (a query target, or the
+ * `@DbActionTarget` handler surface): how many rows the target matched, how
+ * many the handler processed, and the rows left out — `skipped` by the gate
+ * (disabled, out of scope, or `"stale"`: the row no longer matches the query
+ * it was selected by) and `failed` as reported by the handler.
+ *
+ * @since 0.1.147
+ */
+interface TDbActionTargetSummary {
+  matched: number;
+  processed: number;
+  skipped: {
+    id: Record<string, unknown>;
+    reason?: string;
+  }[];
+  failed: {
+    id: Record<string, unknown>;
+    reason: string;
+  }[];
+  /**
+   * The run stopped early: a batch failed after an earlier batch had run
+   * (those stay applied). Its ids, and every id not reached, are in
+   * `failed`. Absent when the run completed.
+   */
+  aborted?: {
+    status: number;
+    message: string;
+  };
+  /**
+   * A delegated run (a view's query target onto its source's action): the
+   * `message` each batch's source handler returned, in batch order. Absent
+   * when none returned one.
+   */
+  messages?: string[];
+  /** {@link messages}, the distinct ones joined by newlines — for a toast. */
+  message?: string;
 }
 /**
  * `GET /meta/actions/:id` (and `/meta/actions?…`) response: the row-level
@@ -2709,6 +3413,35 @@ interface TDbInsertManyResult {
   insertedCount: number;
   insertedIds: unknown[];
 }
+/**
+ * `insertOne` result in conflict-ignoring mode (`onConflict: 'ignore'`).
+ * @since 0.1.148
+ */
+interface TDbInsertIgnoreResult {
+  /** Id of the inserted row; absent when the row was skipped. */
+  insertedId?: unknown;
+  /** `true` when the row collided on the primary key or a unique index and was skipped. */
+  conflict: boolean;
+}
+/**
+ * `insertMany` result in conflict-ignoring mode (`onConflict: 'ignore'`):
+ * `insertedCount` / `insertedIds` cover the INSERTED rows only (dense, input
+ * order); `inserted` and `conflicts` map back to input indices.
+ * @since 0.1.148
+ */
+interface TDbInsertManyIgnoreResult extends TDbInsertManyResult {
+  /** Input index of each `insertedIds` entry. */
+  inserted: number[];
+  /** Input indices skipped because of a unique / primary-key conflict, ascending. */
+  conflicts: number[];
+}
+/**
+ * One slot per input row of `BaseDbAdapter.insertManyIgnore`: the inserted id,
+ * or `null` for a skipped (conflicting) row.
+ */
+type TDbInsertIgnoreSlot = {
+  insertedId: unknown;
+} | null;
 interface TDbUpdateResult {
   matchedCount: number;
   modifiedCount: number;
@@ -2870,6 +3603,20 @@ interface TDbFieldMeta {
    * rejected.
    */
   derived?: TDerivedColumn;
+  /**
+   * A computed view column (`@db.compute`, since 0.1.147): `operands` are the
+   * logical paths of the view fields its value is computed from — transitive
+   * (a computed operand is replaced by its own operands), never computed
+   * themselves. `via` lists the intermediate computed fields the value is
+   * computed through (transitively; empty when every leaf is a plain field).
+   * Read-only; a computed field must not be visible when one of its operands
+   * or `via` fields is hidden (the same rule as the `@db.writeOnly` seal —
+   * `priority = x * 100 + rank` would otherwise give back a hidden `rank`).
+   */
+  computed?: {
+    operands: readonly string[];
+    via: readonly string[];
+  };
 }
 interface TValueFormatterPair {
   /** Converts a JS value to storage representation (write + filter paths). */
@@ -2885,6 +3632,24 @@ interface TDbForeignKey {
   targetTable: string;
   /** Target field names on the referenced table. */
   targetFields: string[];
+  /**
+   * Physical column names of {@link fields} (after `@db.column` renames and
+   * flattening), in the same order. Use these for DDL, constraint sync, the
+   * FK diff and the schema snapshot; `fields` stays logical (query / relation
+   * pairing). Absent → same as `fields`.
+   */
+  physicalFields?: string[];
+  /**
+   * Physical column names of {@link targetFields} on the referenced table
+   * (its `@db.column` renames), in the same order. Absent → same as `targetFields`.
+   */
+  physicalTargetFields?: string[];
+  /**
+   * `@db.schema` of the referenced table, when it declares one — SQL DDL
+   * qualifies `REFERENCES` with it (a table in another schema). Not part of
+   * the schema snapshot.
+   */
+  targetSchema?: string;
   /** Lazy reference to the target annotated type (for on-demand table resolution). */
   targetTypeRef?: () => TAtscriptAnnotatedType;
   /** Alias grouping FK fields (if any). */
@@ -3074,7 +3839,7 @@ interface AtscriptDbTableLike {
   relations: ReadonlyMap<string, TDbRelation>;
   foreignKeys: ReadonlyMap<string, TDbForeignKey>;
   getMetadata(): TableMetadata;
-  isValidFieldPath(path: string, visited?: Set<string>): boolean;
+  isValidFieldPath(path: string): boolean;
 }
 /**
  * Nested FROM re-entry option (internal): pins every child's foreign key
@@ -3170,6 +3935,18 @@ interface TDbRelation {
   isArray: boolean;
   /** Junction type reference for 'via' (M:N) relations. */
   viaType?: () => TAtscriptAnnotatedType;
+  /**
+   * `@db.rel.filterable` — HTTP clients may filter the parent rows by this
+   * relation (`{ nav: { $some | $none: … } }`). Server-side code may always.
+   * @since 0.1.147
+   */
+  filterable?: boolean;
+  /**
+   * `@db.rel.filter` condition: part of the relation's meaning — applied when
+   * the relation is loaded (`$with`) and inside relational predicates.
+   * @since 0.1.147
+   */
+  filter?: AtscriptQueryNode;
 }
 /**
  * Write payload for insert / patch paths: every key optional, and optional
@@ -3295,6 +4072,21 @@ interface TWriteOptions<Row = Record<string, unknown>> extends TIdResolveOptions
    */
   check?: TDbWriteCheck;
 }
+/**
+ * Options of `insertOne` / `insertMany`.
+ * @since 0.1.148
+ */
+interface TInsertOptions<Row = Record<string, unknown>> extends TWriteOptions<Row> {
+  /**
+   * `'error'` (default): a unique / primary-key violation throws `CONFLICT`.
+   * `'ignore'`: rows that collide on the primary key or any unique index —
+   * with a stored row or an earlier row of the same batch — are skipped and
+   * reported by input index. Everything else (validation, NOT NULL, FK, check,
+   * guard) still throws and rolls the call back. A row that creates a related
+   * parent (`@db.rel.to` nested object) is rejected in this mode.
+   */
+  onConflict?: "error" | "ignore";
+}
 /**
  * Context handed to a write {@link TWriteOptions.check} (since 0.1.143) — and
  * through it to `AsDbController.checkWrite()`. Lets a permission layer verify
@@ -3433,7 +4225,14 @@ interface TBucketFieldSource {
 declare function normalizeComputedSelect(controls: {
   $select?: unknown;
   $groupBy?: unknown;
+  $rowOrder?: unknown;
 } | undefined, fields: TBucketFieldSource, aggregate?: boolean): ResolvedBucket[];
+/** The normalized computed `$select` entries of a grouped query — see {@link resolveComputedSelect}. */
+interface TComputedSelect {
+  buckets: ResolvedBucket[];
+  exprs: ResolvedSelectExpr[];
+  rowOrder?: ResolvedRowOrderKey[];
+}
 /**
  * @deprecated since 0.1.136 — renamed {@link normalizeComputedSelect} (it
  * normalizes every computed `$select` entry, aggregates included).
@@ -3464,4 +4263,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbUpdateResult as $, AtscriptRef as $t, TCrudPermissions as A, TViewJsonType as At, TDbFieldMeta as B, ALL_BUCKET_UNITS as Bt, NullableOptional as C, TRowResolveOptions as Ct, TCascadeTarget as D, TTableResolver as Dt, TCascadeResolver as E, TTableOptionDiff as Et, TDbAvailableActions as F, UniqueryControls$1 as Ft, TDbInsertManyResult as G, AtscriptDbView as Gt, TDbIndex as H, DbSpace as Ht, TDbCollation as I, WithRelation$1 as It, TDbReferentialAction as J, isViewType as Jt, TDbInsertResult as K, TViewColumnMapping as Kt, TDbDefaultFn as L, TableMetadata as Lt, TDbActionIntent as M, TWriteTableResolver as Mt, TDbActionLevel as N, TypedWithRelation as Nt, TColumnDiff as O, TTouchManyOptions as Ot, TDbActionProcessor as P, Uniquery$1 as Pt, TDbStorageType as Q, AtscriptQueryNode$1 as Qt, TDbDefaultValue as R, isGeoIndexableType as Rt, NavPropsOf$1 as S, TRelationInfo as St, PrimaryKeyOf$1 as T, TSyncColumnResult as Tt, TDbIndexField as U, TAdapterFactory as Ut, TDbForeignKey as V, BaseDbAdapter as Vt, TDbIndexType as W, TDbSpaceOptions as Wt, TDbRemoveGuard as X, AtscriptQueryComparison as Xt, TDbRelation as Y, aliasTargetOf as Yt, TDbRemoveGuardContext as Z, AtscriptQueryFieldRef$1 as Zt, DbQuery as _, UniquSelect as _n, TIdentification as _t, jsonValueAncestor as a, IntegrityStrategy as an, TDeleteOptions as at, FilterExpr$1 as b, TPrimaryKeyChange as bt, AggregateControls as c, DbResponse as cn, TEnsureTableOptions as ct, AggregateQuery$1 as d, TDbEncryptionOptions as dn, TExistingTableOption as dt, TViewJoin as en, TDbWriteAction as et, AggregateResult as f, DocumentFieldMapper as fn, TFieldMeta as ft, DbPatch as g, TGenericLogger as gn, TIdResolveOptions as gt, DbControls as h, NoopLogger as hn, TIdDescriptor as ht, isJsonValueField as i, AtscriptDbTable as in, TDbWriteGuardContext as it, TDbActionInfo as j, TWriteOptions as jt, TCrudOp as k, TValueFormatterPair as kt, AggregateExpr$1 as l, resolveDesignType as ln, TExistingColumn as lt, AtscriptDbWritable as m, TReadControls as mn, TFkLookupTarget as mt, TResolvedBucket as n, isFieldRef as nn, TDbWriteCheckContext as nt, normalizeComputedSelect as o, NativeIntegrity as on, TDerivedChangeReason as ot, AtscriptDbTableLike as p, FieldMappingStrategy as pn, TFkLookupResolver as pt, TDbObjectKind as q, isAtscriptDbView as qt, isBucketableField as r, translateQueryTree as rn, TDbWriteGuard as rt, resolveCalendarBuckets as s, AtscriptDbReadable as sn, TDerivedColumn as st, TBucketFieldSource as t, TViewPlan as tn, TDbWriteCheck as tt, AggregateFn$1 as u, DbEncryption as un, TExistingForeignKey as ut, DbRow as v, TMetaResponse as vt, OwnPropsOf$1 as w, TSearchIndexInfo as wt, FlatOf$1 as x, TReferencingForeignKey as xt, FieldOpsFor as y, TMetadataOverrides as yt, TDbDeleteResult as z, isGeoPointType as zt };
+export { TDbReferentialAction as $, AtscriptDbView as $t, TCrudOp as A, containsRelationFilter as An, TSearchIndexInfo as At, TDbDefaultValue as B, NoopLogger as Bn, Uniquery$1 as Bt, NavPropsOf$1 as C, REL_FILTER_MAX_NODES as Cn, TInsertOptions as Ct, TCascadeResolver as D, TRelationFilterTable as Dn, TReferencingForeignKey as Dt, PrimaryKeyOf$1 as E, TRelationFilterJunction as En, TPrimaryKeyChange as Et, TDbActionProcessor as F, DbEncryption as Fn, TValueFormatterPair as Ft, TDbIndexField as G, UniquSelect as Gn, isGeoPointType as Gt, TDbFieldMeta as H, TExprAggregate as Hn, WithRelation$1 as Ht, TDbActionTargetSummary as I, TDbEncryptionOptions as In, TViewJsonType as It, TDbInsertIgnoreSlot as J, BaseDbAdapter as Jt, TDbIndexType as K, ALL_BUCKET_UNITS as Kt, TDbAvailableActions as L, DocumentFieldMapper as Ln, TWriteOptions as Lt, TDbActionInfo as M, hasRelationOp as Mn, TTableOptionDiff as Mt, TDbActionIntent as N, isResolvedRelationFilter as Nn, TTableResolver as Nt, TCascadeTarget as O, TRelationStaticFilter as On, TRelationInfo as Ot, TDbActionLevel as P, relationStaticFilter as Pn, TTouchManyOptions as Pt, TDbObjectKind as Q, TDbSpaceOptions as Qt, TDbCollation as R, FieldMappingStrategy as Rn, TWriteTableResolver as Rt, FlatOf$1 as S, REL_FILTER_MAX_DEPTH as Sn, TIdentification as St, OwnPropsOf$1 as T, TRelGuardState as Tn, TMetadataOverrides as Tt, TDbForeignKey as U, TFirstLast as Un, TableMetadata as Ut, TDbDeleteResult as V, TGenericLogger as Vn, UniqueryControls$1 as Vt, TDbIndex as W, TRowOrderKey as Wn, isGeoIndexableType as Wt, TDbInsertManyResult as X, DbSpace as Xt, TDbInsertManyIgnoreResult as Y, TViewCapability as Yt, TDbInsertResult as Z, TAdapterFactory as Zt, DbPatch as _, NativeIntegrity as _n, TFieldMeta as _t, isJsonValueField as a, AtscriptOrderItem as an, TDbWriteAction as at, FieldOpsFor as b, DbResponse as bn, TIdDescriptor as bt, resolveCalendarBuckets as c, AtscriptQueryNode$1 as cn, TDbWriteGuard as ct, AggregateFn$1 as d, TViewPlan as dn, TDerivedChangeReason as dt, TViewColumnMapping as en, TDbRelation as et, AggregateQuery$1 as f, evaluateExpr as fn, TDerivedColumn as ft, DbControls as g, IntegrityStrategy as gn, TExistingTableOption as gt, AtscriptDbWritable as h, AtscriptDbTable as hn, TExistingForeignKey as ht, isBucketableField as i, AtscriptExprNode$1 as in, TDbUpdateResult as it, TCrudPermissions as j, forEachResolvedRelation as jn, TSyncColumnResult as jt, TColumnDiff as k, andFilters as kn, TRowResolveOptions as kt, AggregateControls as l, AtscriptRef as ln, TDbWriteGuardContext as lt, AtscriptDbTableLike as m, translateQueryTree as mn, TExistingColumn as mt, TComputedSelect as n, isViewType as nn, TDbRemoveGuardContext as nt, jsonValueAncestor as o, AtscriptQueryComparison as on, TDbWriteCheck as ot, AggregateResult as p, isFieldRef as pn, TEnsureTableOptions as pt, TDbInsertIgnoreResult as q, ALL_VIEW_CAPABILITIES as qt, TResolvedBucket as r, aliasTargetOf as rn, TDbStorageType as rt, normalizeComputedSelect as s, AtscriptQueryFieldRef$1 as sn, TDbWriteCheckContext as st, TBucketFieldSource as t, isAtscriptDbView as tn, TDbRemoveGuard as tt, AggregateExpr$1 as u, TViewJoin as un, TDeleteOptions as ut, DbQuery as v, TCascadePin as vn, TFkLookupResolver as vt, NullableOptional as w, ResolvedRelationFilter as wn, TMetaResponse as wt, FilterExpr$1 as x, resolveDesignType as xn, TIdResolveOptions as xt, DbRow as y, AtscriptDbReadable as yn, TFkLookupTarget as yt, TDbDefaultFn as z, TReadControls as zn, TypedWithRelation as zt };