@atscript/db 0.1.145 → 0.1.147

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

@@ -1,6 +1,6 @@
 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, 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
 /**
@@ -146,14 +146,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 +305,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.
@@ -369,6 +546,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<{
@@ -495,6 +706,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 +731,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 +784,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 +806,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.
    */
@@ -836,6 +1070,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 +1089,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 +1098,7 @@ declare abstract class IntegrityStrategy {
  */
 declare class NativeIntegrity extends IntegrityStrategy {
   validateForeignKeys(): Promise<void>;
-  cascadeBeforeDelete(): Promise<void>;
+  cascadeBeforeDelete(): Promise<TCascadePin>;
   needsCascade(): boolean;
 }
 //#endregion
@@ -1173,6 +1419,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 {
@@ -1272,6 +1534,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 +1638,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;
 }
@@ -1497,8 +1783,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 +1845,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
@@ -1679,8 +1985,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>;
   /**
@@ -1706,6 +2014,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 +2070,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 +2334,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.
@@ -2350,6 +2713,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 +2813,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.
    */
@@ -2513,6 +2892,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 {
@@ -2556,6 +2940,13 @@ 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;
 }
 /** Built-in CRUD operation names; map 1:1 to public method names. */
 type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
@@ -2687,6 +3078,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
@@ -2870,6 +3331,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 +3360,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 +3567,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 +3663,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
@@ -3464,4 +3969,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 { TDbStorageType as $, AtscriptExprNode$1 as $t, TCrudPermissions as A, TDbEncryptionOptions as An, TValueFormatterPair as At, TDbDeleteResult as B, isGeoPointType as Bt, NullableOptional as C, andFilters as Cn, TRelationInfo as Ct, TCascadeTarget as D, isResolvedRelationFilter as Dn, TTableOptionDiff as Dt, TCascadeResolver as E, hasRelationOp as En, TSyncColumnResult as Et, TDbActionTargetSummary as F, TGenericLogger as Fn, Uniquery$1 as Ft, TDbIndexType as G, DbSpace as Gt, TDbForeignKey as H, ALL_VIEW_CAPABILITIES as Ht, TDbAvailableActions as I, UniquSelect as In, UniqueryControls$1 as It, TDbObjectKind as J, AtscriptDbView as Jt, TDbInsertManyResult as K, TAdapterFactory as Kt, TDbCollation as L, WithRelation$1 as Lt, TDbActionIntent as M, FieldMappingStrategy as Mn, TWriteOptions as Mt, TDbActionLevel as N, TReadControls as Nn, TWriteTableResolver as Nt, TColumnDiff as O, relationStaticFilter as On, TTableResolver as Ot, TDbActionProcessor as P, NoopLogger as Pn, TypedWithRelation as Pt, TDbRemoveGuardContext as Q, aliasTargetOf as Qt, TDbDefaultFn as R, TableMetadata as Rt, NavPropsOf$1 as S, TRelationStaticFilter as Sn, TReferencingForeignKey as St, PrimaryKeyOf$1 as T, forEachResolvedRelation as Tn, TSearchIndexInfo as Tt, TDbIndex as U, BaseDbAdapter as Ut, TDbFieldMeta as V, ALL_BUCKET_UNITS as Vt, TDbIndexField as W, TViewCapability as Wt, TDbRelation as X, isAtscriptDbView as Xt, TDbReferentialAction as Y, TViewColumnMapping as Yt, TDbRemoveGuard as Z, isViewType as Zt, DbQuery as _, REL_FILTER_MAX_NODES as _n, TIdResolveOptions as _t, jsonValueAncestor as a, TViewJoin as an, TDbWriteGuardContext as at, FilterExpr$1 as b, TRelationFilterJunction as bn, TMetadataOverrides as bt, AggregateControls as c, translateQueryTree as cn, TDerivedColumn as ct, AggregateQuery$1 as d, NativeIntegrity as dn, TExistingForeignKey as dt, AtscriptOrderItem as en, TDbUpdateResult as et, AggregateResult as f, TCascadePin as fn, TExistingTableOption as ft, DbPatch as g, REL_FILTER_MAX_DEPTH as gn, TIdDescriptor as gt, DbControls as h, resolveDesignType as hn, TFkLookupTarget as ht, isJsonValueField as i, AtscriptRef as in, TDbWriteGuard as it, TDbActionInfo as j, DocumentFieldMapper as jn, TViewJsonType as jt, TCrudOp as k, DbEncryption as kn, TTouchManyOptions as kt, AggregateExpr$1 as l, AtscriptDbTable as ln, TEnsureTableOptions as lt, AtscriptDbWritable as m, DbResponse as mn, TFkLookupResolver as mt, TResolvedBucket as n, AtscriptQueryFieldRef$1 as nn, TDbWriteCheck as nt, normalizeComputedSelect as o, TViewPlan as on, TDeleteOptions as ot, AtscriptDbTableLike as p, AtscriptDbReadable as pn, TFieldMeta as pt, TDbInsertResult as q, TDbSpaceOptions as qt, isBucketableField as r, AtscriptQueryNode$1 as rn, TDbWriteCheckContext as rt, resolveCalendarBuckets as s, isFieldRef as sn, TDerivedChangeReason as st, TBucketFieldSource as t, AtscriptQueryComparison as tn, TDbWriteAction as tt, AggregateFn$1 as u, IntegrityStrategy as un, TExistingColumn as ut, DbRow as v, ResolvedRelationFilter as vn, TIdentification as vt, OwnPropsOf$1 as w, containsRelationFilter as wn, TRowResolveOptions as wt, FlatOf$1 as x, TRelationFilterTable as xn, TPrimaryKeyChange as xt, FieldOpsFor as y, TRelGuardState as yn, TMetaResponse as yt, TDbDefaultValue as z, isGeoIndexableType as zt };