@atscript/db 0.1.130 → 0.1.132

package/dist/{db-readable-Bn1bV_eC.d.mts → buckets-D2XPrwSC.d.mts}

@@ -1,6 +1,6 @@
 import { f as TFieldOps } from "./ops-AqhV7s9o.mjs";
 import { 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, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
+import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, 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";
 
 //#region src/query/uniqu-select.d.ts
 /**
@@ -11,6 +11,11 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
  * `controls.$select` is `UniquSelect | undefined`.
  *
  * 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
+ * (`resolveCalendarBuckets` rejects any other shape before translation).
  */
 declare class UniquSelect {
   private static readonly UNRESOLVED;
@@ -19,12 +24,25 @@ declare class UniquSelect {
   private _array;
   private _projection;
   private _aggregates;
-  constructor(raw: UniqueryControls["$select"], allFields?: string[]);
-  /** Type guard: checks if a value is an AggregateExpr ({$fn, $field}). */
-  private static _isAggregateExpr;
+  /**
+   * The calendar buckets of an aggregate `$select`, normalized (canonical
+   * zone, week start, alias) with the PHYSICAL source `field` and its
+   * descriptor `fd`. `undefined` when there are none. A `$groupBy` key equal
+   * to a bucket's `alias` groups by that bucket (aliases never collide with
+   * columns). Since 0.1.132.
+   */
+  readonly buckets: readonly TResolvedBucket[] | undefined;
+  /**
+   * @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`).
+   */
+  constructor(raw: UniqueryControls["$select"], allFields?: string[], buckets?: readonly TResolvedBucket[]);
   /**
    * Resolved inclusion array of plain field names (strings only).
-   * AggregateExpr objects are filtered out.
+   * Computed entries (aggregates, calendar buckets) are filtered out.
    * For exclusion form, inverts using `allFields` from constructor.
    */
   get asArray(): string[] | undefined;
@@ -42,6 +60,8 @@ declare class UniquSelect {
   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. */
+  bucketByAlias(key: string): TResolvedBucket | undefined;
 }
 //#endregion
 //#region src/logger.d.ts
@@ -54,822 +74,539 @@ interface TGenericLogger {
 }
 declare const NoopLogger: TGenericLogger;
 //#endregion
-//#region src/table/table-metadata.d.ts
-/**
- * Finds the nearest ancestor of `path` that belongs to `set`.
- * Used by both the build pipeline (in `_classifyFields`) and
- * runtime reconstruction on the Readable.
- */
-declare function findAncestorInSet(path: string, set: ReadonlySet<string>): string | undefined;
-/** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
-declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
-/**
- * Returns true if the annotated type is acceptable for `@db.index.geo`:
- * the `db.geoPoint` primitive or a structurally identical `number[]`
- * (excluding `db.vector`, which is semantically an embedding).
- */
-declare function isGeoIndexableType(fieldType: TAtscriptAnnotatedType): boolean;
+//#region src/strategies/field-mapping.d.ts
 /**
- * Computed metadata for a database table or view.
- *
- * Contains all field metadata, physical mapping indexes, relation definitions,
- * and constraint information derived from Atscript annotations. Built lazily
- * on first access via {@link build}, then immutable.
- *
- * This class owns the build pipeline that was previously part of
- * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
- * access to this class.
+ * Strategy for mapping data between logical field shapes and physical storage.
+ * Two implementations: {@link DocumentFieldMapper} (nested objects, NoSQL)
+ * and `RelationalFieldMapper` (flattened columns, SQL).
  */
-declare class TableMetadata {
-  readonly nestedObjects: boolean;
-  flatMap: Map<string, TAtscriptAnnotatedType>;
-  fieldDescriptors: readonly TDbFieldMeta[];
-  primaryKeys: string[];
-  preferredId: string[];
-  originalMetaIdFields: string[];
-  indexes: Map<string, TDbIndex>;
-  foreignKeys: Map<string, TDbForeignKey>;
-  relations: Map<string, TDbRelation>;
-  navFields: Set<string>;
-  ignoredFields: Set<string>;
-  uniqueProps: Set<string>;
-  defaults: Map<string, TDbDefaultValue>;
-  columnMap: Map<string, string>;
-  dimensions: string[];
-  measures: string[];
-  /** Logical field name annotated with `@db.column.version`, if any. */
-  versionField?: string;
-  /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
-  quantityRefByField: Map<string, string>;
-  /** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
-  encryptedFields: Set<string>;
-  pathToPhysical: Map<string, string>;
-  physicalToPath: Map<string, string>;
-  flattenedParents: Set<string>;
-  jsonFields: Set<string>;
-  selectExpansion: Map<string, string[]>;
-  booleanFields: Set<string>;
-  decimalFields: Set<string>;
-  allPhysicalFields: string[];
-  /** Precomputed parent path → child physical column names for fast null-setting. */
-  childrenByParent: Map<string, string[]>;
-  /** Precomputed parent path → optional child logical paths (replace-strategy null-fill in the patch decomposer). */
-  optionalLeavesByLogicalParent: Map<string, string[]>;
-  requiresMappings: boolean;
-  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
-  onlyColumnRenames: boolean;
-  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  /** Leaf field descriptors indexed by physical column name (read path). */
-  leafByPhysical: Map<string, TDbFieldMeta>;
-  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
-  leafByLogical: Map<string, TDbFieldMeta>;
+declare abstract class FieldMappingStrategy {
+  abstract reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  abstract translateQuery(query: Uniquery, meta: TableMetadata): DbQuery;
   /**
-   * Non-ignored field descriptors keyed by logical path, excluding navigation
-   * relations and their descendants. Unlike `leafByLogical` (relational
-   * adapters only) this is built for every adapter, so the core path guard
-   * (`guardPaths`) can answer "does this path have physical storage here?"
-   * on nested-object adapters too.
+   * The physical path of a logical field path — a `__`-joined column
+   * (relational) or a document path with `@db.column` renames applied.
    */
-  descriptorByPath: Map<string, TDbFieldMeta>;
+  protected abstract physicalPath(logical: string, meta: TableMetadata): string;
   /**
-   * Logical paths stored as a single JSON column (`storage === 'json'`,
-   * non-ignored descriptors). Retained after build — unlike the build-time
-   * `jsonFields` set — so the path guard can classify JSON descendants on
-   * relational adapters. Empty on nested-object adapters (they keep native
-   * dotted paths as descriptors).
+   * Whether {@link physicalPath} can differ from the logical path for this
+   * table; `false` lets the path translations hand their input back as-is.
    */
-  jsonParents: ReadonlySet<string>;
-  private _built;
-  private _identifications?;
-  private _collateMap;
-  private _columnFromMap;
-  constructor(nestedObjects: boolean);
-  get isBuilt(): boolean;
+  protected renamesPaths(_meta: TableMetadata): boolean;
   /**
-   * Runs the full metadata compilation pipeline. Called once by
-   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
+   * Translates a grouped query to physical names: the filter and `$having`
+   * through {@link translateFilter}, and every field path in `$groupBy`,
+   * `$select` (plain and computed `$field`s) and `$sort` through
+   * {@link physicalPath}. Computed aliases pass through (a bucket alias never
+   * equals a field name).
    *
-   * Pipeline steps:
-   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
-   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
-   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
-   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
-   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
-   * 6. Build field descriptors (TDbFieldMeta[])
-   * 7. Build leaf field indexes (skipped for nested-objects adapters)
-   * 8. Finalize indexes (resolve field names to physical)
-   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
-   * 10. Build allPhysicalFields list
+   * `buckets` are the query's calendar buckets as the core's normalizer
+   * resolved them (`resolveCalendarBuckets` — `AtscriptDbReadable.aggregate`
+   * runs it before the guards); they reach adapters with `field` made
+   * physical and the source descriptor as `fd`.
    */
-  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
+  translateAggregateQuery(query: AggregateQuery, meta: TableMetadata, buckets: readonly ResolvedBucket[]): DbQuery;
+  /** Output aliases of the computed `$select` entries (aggregates and calendar buckets). */
+  private computedAliasSet;
   /**
-   * Applies adapter-provided metadata overrides atomically.
-   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
+   * `$select` with its field paths made physical: array-form names and
+   * computed `$field`s (`'*'` kept), or the keys of the object
+   * (inclusion / exclusion) form.
    */
-  private _applyOverrides;
+  protected physicalSelect(select: NonNullable<UniqueryControls["$select"]>, meta: TableMetadata): NonNullable<UniqueryControls["$select"]>;
+  /** `$sort` with physical keys; computed `aliases` (grouped queries) pass through. */
+  protected physicalSort(sort: NonNullable<DbControls["$sort"]>, meta: TableMetadata, aliases?: ReadonlySet<string>): DbControls["$sort"];
   /**
-   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+   * Recursively walks a filter expression, applying `@db.column` key renames
+   * (document paths — {@link TableMetadata.documentPath}) and adapter-specific
+   * value formatting via `formatFilterValue`.
+   *
+   * The relational mapper overrides this to use `leafByLogical` for deeper
+   * key resolution (flattened nested paths).
    */
-  private _scanGenericAnnotations;
+  translateFilter(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>;
   /**
-   * Build-time diagnostics for `@db.encrypted` (§6 of the field-encryption
-   * spec). Mirrors the compile-time AnnotationSpec validation so models built
-   * from pre-compiled types still fail fast.
+   * Reverse-maps `@db.column` renames on a row read from storage.
+   * Renames physical keys back to logical names in-place.
    */
-  private _validateEncryptedField;
-  /** Build-time diagnostics for `@db.index.geo` (§3 of the geo-index spec). */
-  private _validateGeoIndexField;
-  private _addIndexField;
+  protected reverseColumnRenames(row: Record<string, unknown>, meta: TableMetadata): void;
   /**
-   * Classifies each field as column, flattened, json, or parent-object.
-   * Builds the bidirectional pathToPhysical / physicalToPath maps.
+   * Coerces field values from storage representation to JS types
+   * (booleans from 0/1, decimals from number to string).
    */
-  private _classifyFields;
-  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
-  private _flattenedPrefix;
-  /** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
+  protected coerceFieldValues(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   /**
-   * Indexes non-ignored descriptors by logical path and retains the JSON-parent
-   * set. Navigation relations and their descendants are skipped even when the
-   * adapter keeps them as descriptors (nested-object adapters do) — they are
-   * loaded with `$with`, never addressed as columns of this table.
+   * Applies adapter-specific fromStorage formatting to a row read from the database.
+   * Converts storage representations back to JS values (e.g. Date → epoch ms).
    */
-  private _buildGuardIndexes;
+  protected applyFromStorageFormatters(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   /**
-   * Indexes `fieldDescriptors` into two lookup maps for unified
-   * read/write field classification in the RelationalFieldMapper.
+   * Sets a value at a dot-notation path, creating intermediate objects as needed.
    */
-  private _buildLeafIndexes;
+  protected setNestedValue(obj: Record<string, unknown>, dotPath: string, value: unknown): void;
   /**
-   * Builds field descriptors, physical-name lookup, and value formatters.
-   * Called once during build() — everything it needs
-   * (flatMap, indexes, columnMap, etc.) is already populated.
+   * If all children of a flattened parent are null, collapse the parent to null.
    */
-  private _buildFieldDescriptors;
+  protected reconstructNullParent(obj: Record<string, unknown>, parentPath: string, meta: TableMetadata): void;
   /**
-   * Resolves `fkTargetField` for FK fields in field descriptors.
+   * Applies adapter-specific value formatting to a single filter value.
+   * Handles direct values, operator objects ({$gt: v}), and $in/$nin arrays.
    */
-  private _resolveFkTargetFields;
-  private _finalizeIndexes;
+  protected formatFilterValue(physicalName: string, value: unknown, meta: TableMetadata): unknown;
   /**
-   * Captures legitimate row-identifier shapes from the metadata: primary key
-   * (when present) followed by every unique index. Must run BEFORE
-   * `_finalizeIndexes` rewrites `index.fields[i].name` from logical to
-   * physical, so the field lists stay logical.
-   *
-   * Sources:
-   * - `this.primaryKeys` — composite-aware PK (one identification covering
-   *   the PK columns).
-   * - `this.indexes` — user-declared `@db.index.unique` (single or compound).
-   * - `this.uniqueProps` — single-field uniques contributed by adapter
-   *   overrides (`addUniqueFields`); these aren't reflected in
-   *   `this.indexes` but still legitimate addressing identifications.
-   *   Deduped against any single-field unique index already captured.
+   * Applies adapter-specific value formatting to prepared (physical-named) data.
    */
-  private _buildIdentifications;
-  /** Legitimate row-identifier shapes — primary key first, then each unique index. */
-  getIdentifications(): readonly TIdentification[];
-  private _resolvePreferredId;
-}
-//#endregion
-//#region src/types.d.ts
-/** Controls with resolved projection. Used in the adapter interface. */
-interface DbControls extends Omit<UniqueryControls, "$select"> {
-  $select?: UniquSelect;
-}
-/** Query object with resolved projection. Passed to adapter methods. */
-interface DbQuery {
-  filter: FilterExpr;
-  controls: DbControls;
-  /** Pre-computed query insights (field → operators). Adapters may use this to apply query-time behaviour (e.g. collation). */
-  insights?: UniqueryInsights;
-}
-/** Describes an available search index exposed by a database adapter. */
-interface TSearchIndexInfo {
-  /** Index name. Empty string or 'DEFAULT' for the default index. */
-  name: string;
-  /** Human-readable label for UI display. */
-  description?: string;
-  /** Index type: text search or vector similarity search. */
-  type?: "text" | "vector";
-}
-/** Relation summary in a meta response. */
-interface TRelationInfo {
-  name: string;
-  direction: "to" | "from" | "via";
-  isArray: boolean;
-}
-/** Per-field capability flags in a meta response. */
-interface TFieldMeta {
-  sortable: boolean;
-  filterable: boolean;
-  /** Present (true) when the field is `@db.encrypted` — stored as ciphertext at rest. */
-  encrypted?: boolean;
-  /** Present (true) when the field carries a `@db.index.geo` geospatial index. */
-  geo?: boolean;
+  protected formatWriteValues(data: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   /**
-   * Present (true) when the field is write-only over HTTP (`@db.writeOnly` or
-   * stamped by a permission overlay): settable in write payloads, never
-   * present in read responses. UIs render it as a set-only input.
+   * Prepares primary key values and strips ignored fields.
+   * Shared pre-processing for both document and relational write paths.
    */
-  writeOnly?: boolean;
+  protected prepareCommon(data: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): void;
+}
+/**
+ * Field mapper for document-oriented adapters (e.g. MongoDB).
+ * Nested objects are preserved as-is. Only applies column renames and
+ * value coercion.
+ */
+declare class DocumentFieldMapper extends FieldMappingStrategy {
+  reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
   /**
-   * Present (true) when the field is index-backed (explicit `@db.index*`,
-   * primary key or unique field). Advisory only — a hint for UIs that want to
-   * steer users toward cheap sort keys; it never affects whether a `$sort`
-   * is accepted (`sortable` does). Since 0.1.128.
+   * Every field-path position goes through `@db.column` renames
+   * ({@link TableMetadata.documentPath}): filter keys, `$select` fields
+   * (array, inclusion and exclusion forms) and `$sort` keys.
    */
-  indexed?: boolean;
+  translateQuery(query: Uniquery, meta: TableMetadata): DbQuery;
+  /** A document path with `@db.column` renames ({@link TableMetadata.documentPath}). */
+  protected physicalPath(logical: string, meta: TableMetadata): string;
+  protected renamesPaths(meta: TableMetadata): boolean;
+  prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
+  translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
 }
-/** Built-in CRUD operation names; map 1:1 to public method names. */
-type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
+//#endregion
+//#region src/encryption.d.ts
 /**
- * CRUD permissions advertised in `/meta`. Key absent → operation is denied or
- * not exposed. Key present → operation is allowed; the `string[]` value is the
- * accepted UniQuery control whitelist for read ops (`[]` for write ops, which
- * take no controls — presence still signals "allowed").
+ * Configuration for field-level encryption at rest (`@db.encrypted`).
+ * Passed to `DbSpace` via the options bag.
  */
-type TCrudPermissions = Partial<Record<TCrudOp, string[]>>;
-/** Response payload for `GET /meta`. */
-interface TMetaResponse {
-  searchable: boolean;
-  vectorSearchable: boolean;
-  /** Whether the adapter supports `geoSearch()` AND the table declares a geo index. */
-  geoSearchable?: boolean;
-  searchIndexes: TSearchIndexInfo[];
-  primaryKeys: string[];
-  preferredId: string[];
-  relations: TRelationInfo[];
-  fields: Record<string, TFieldMeta>;
-  type: TSerializedAnnotatedType;
-  actions: TDbActionInfo[];
-  crud: TCrudPermissions;
+interface TDbEncryptionOptions {
+  /** Key used for all new writes. */
+  defaultKeyId: string;
   /**
-   * Physical column name annotated with `@db.column.version`, when the table
-   * opts into optimistic concurrency control (OCC). Absent for tables without
-   * the annotation, i.e. last-write-wins (default) behavior.
+   * Key registry: keyId → 32-byte key (Buffer, or base64/hex/utf8 string).
+   * Decryption looks keys up by the keyId recorded in each value's envelope,
+   * so old keys stay in the registry for as long as data encrypted with them exists.
    */
-  versionColumn?: string;
+  keys?: Record<string, string | Buffer>;
+  /**
+   * Alternative/supplement to `keys`: async resolver (KMS, Vault, env indirection).
+   * Called once per keyId, result cached for the process lifetime.
+   */
+  resolveKey?: (keyId: string) => Promise<string | Buffer> | string | Buffer;
+  /**
+   * What to do when a stored value is NOT a valid envelope (pre-existing
+   * plaintext rows, e.g. when @db.encrypted is added to a live column).
+   *  - 'error' (default): fail the read with DbError("ENC_NOT_ENCRYPTED")
+   *  - 'passthrough': return the raw value as-is (migration window mode);
+   *    the value gets encrypted on its next write.
+   */
+  onUnencrypted?: "error" | "passthrough";
+}
+/** Decryption context — carried into error messages (never the key itself). */
+interface TDecryptContext {
+  table?: string;
+  field?: string;
 }
-/** Where the action applies on the UI. */
-type TDbActionLevel = "table" | "row" | "rows";
 /**
- * Semantic intent the UI maps to its own visual language (color, prominence).
+ * AES-256-GCM envelope encryption service for `@db.encrypted` fields.
  *
- * Suggested visual prominence (most → least): `negative` > `warning` > `primary`
- * > `positive` > `secondary`. Use `negative` for destructive ops (delete, purge),
- * `warning` for risky-but-non-destructive ops (retry payment, force recompute,
- * reset state), `primary` for the headline action, `positive` for benign
- * confirmations (approve, publish), `secondary` for everything else.
+ * Owned by `DbSpace` and shared across all tables in the space. Values are
+ * `JSON.stringify`'d before encryption (type-exact round-trips) and stored as
+ * a single ASCII envelope string: `aes1$<keyId>$<iv>$<tag>$<ciphertext>`.
+ *
+ * Key material is validated eagerly at construction (`ENC_KEY_INVALID`);
+ * `resolveKey` lookups are cached per keyId for the process lifetime.
  */
-type TDbActionIntent = "positive" | "negative" | "warning" | "primary" | "secondary";
-/** How the UI client should handle the action when invoked. */
-type TDbActionProcessor = "backend" | "navigate" | "custom";
+declare class DbEncryption {
+  readonly defaultKeyId: string;
+  readonly onUnencrypted: "error" | "passthrough";
+  private readonly _keys;
+  private readonly _resolveKey?;
+  private readonly _resolved;
+  constructor(options: TDbEncryptionOptions);
+  /** True when `value` looks like an encryption envelope produced by this service. */
+  isEnvelope(value: unknown): value is string;
+  /** Encrypts a JSON-serializable value into an envelope string using the default key. */
+  encrypt(value: unknown): Promise<string>;
+  /** Decrypts an envelope string back into its plaintext value. */
+  decrypt(envelope: string, ctx?: TDecryptContext): Promise<unknown>;
+  private _decryptFailed;
+  private _getKey;
+}
+//#endregion
+//#region src/table/db-readable.d.ts
 /**
- * Single action descriptor in the `/meta` envelope. Flat shape — `processor`
- * is a string discriminator; `value` is its sibling and is always populated.
+ * Extracts nav prop names from a query's `$with` array.
+ * Returns `never` when `$with` is absent → all nav props stripped from response.
+ */
+type ExtractWith<Q> = Q extends {
+  controls: {
+    $with: Array<{
+      name: infer N extends string;
+    }>;
+  };
+} ? N : never;
+/**
+ * Computes the response type for a query:
+ * - Strips all nav props from the base DataType
+ * - Adds back only the nav props requested via `$with`
  *
- * - `processor: 'backend'` — UI POSTs to `value` (full HTTP path).
- * - `processor: 'navigate'` — UI routes to `value` (URL template; `$1` is the row PK).
- * - `processor: 'custom'`  — UI dispatches `value` as an event name (defaults to action `name`).
+ * When no `$with` is provided, result is `Omit<DataType, keyof NavType>`.
+ * When `$with: [{ name: 'author' }]`, result includes `author` from DataType.
+ * When the query type is not a literal (e.g. a variable typed as `Uniquery`),
+ * falls back to `DataType` (all nav props optional, as declared).
  */
-interface TDbActionInfo {
-  name: string;
-  label: string;
-  level: TDbActionLevel;
-  processor: TDbActionProcessor;
-  value: string;
-  icon?: string;
-  intent?: TDbActionIntent;
-  description?: string;
-  order?: number;
-  default?: boolean;
+type DbResponse<Data, Nav, Q> = [keyof Nav] extends [never] ? Data : string extends keyof Nav ? Data : Omit<Data, keyof Nav & string> & Pick<Data, ExtractWith<Q> & keyof Data & string>;
+/**
+ * Resolves the design type from an annotated type.
+ * Encapsulates the `kind === ''` check and fallback logic that
+ * otherwise trips up every adapter author.
+ *
+ * For union types (e.g., from flattened `{...} | {...}` objects):
+ * - If all members resolve to the same type → returns that type (strong type)
+ * - If members disagree → returns `'union'` (out of scope for type management)
+ */
+declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
+/**
+ * Shared read-only database abstraction driven by Atscript annotations.
+ *
+ * Contains all field metadata computation, read operations, query translation,
+ * relation loading, and result reconstruction. Extended by both
+ * {@link AtscriptDbTable} (adds write operations) and {@link AtscriptDbView}
+ * (adds view plan/DDL).
+ */
+declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, _FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> {
+  protected readonly _type: T;
+  protected readonly adapter: A;
+  protected readonly logger: TGenericLogger;
+  protected readonly _tableResolver?: TTableResolver | undefined;
+  /** Resolved table/collection/view name. */
+  readonly tableName: string;
+  /** Database schema/namespace from `@db.schema` (if set). */
+  readonly schema: string | undefined;
+  /** Sync method from `@db.sync.method` ('drop' | 'recreate' | undefined). */
+  protected readonly _syncMethod: "drop" | "recreate" | undefined;
+  /** Previous table/view name from `@db.table.renamed` or `@db.view.renamed`. */
+  readonly renamedFrom: string | undefined;
+  /** Computed metadata for this table/view. Built lazily on first access. */
+  protected readonly _meta: TableMetadata;
+  /** Strategy for mapping between logical field shapes and physical storage. */
+  protected readonly _fieldMapper: FieldMappingStrategy;
+  protected _writeTableResolver?: TWriteTableResolver;
+  /** Encryption service for `@db.encrypted` fields — set by `DbSpace` from its options. */
+  protected _encryption?: DbEncryption;
+  private _metaIdPhysical;
+  constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
   /**
-   * Confirmation prompt copy. String form is shown verbatim. Tuple form is
-   * `[singular, plural]`: the UI picks `[0]` when the action will execute
-   * against a single PK (always for `'row'`-level; for `'rows'`-level when the
-   * current selection has exactly one PK) and `[1]` otherwise.
-   *
-   * Placeholder substitution is UI-resolved, not server-parsed. Conventional
-   * placeholders: `$1` for the single PK (singular form) and `$N` for the
-   * count (plural form), e.g. `['Delete order $1?', 'Delete $N orders?']`.
+   * Sets the encryption service used for `@db.encrypted` fields.
+   * Called by `DbSpace` after table/view creation when the space was
+   * configured with an `encryption` options block.
    */
-  promptText?: string | [string, string];
+  setEncryption(encryption: DbEncryption | undefined): void;
+  /** Ensures metadata is built. Called before any metadata access. */
+  protected _ensureBuilt(): void;
   /**
-   * Single-character keyboard shortcut hint. The server stores this verbatim
-   * — choice of modifier prefix (Alt+, Ctrl+, bare key) and activation scope
-   * (e.g. only when an actions dropdown is open) are UI/UX concerns. Conflict
-   * resolution between actions sharing the same key is also up to the UI;
-   * the server does no dedup.
+   * Built table metadata. Triggers a lazy build on first access — safe to call
+   * from peer tables that need this one's relations / nav fields before any
+   * operation has run against it directly.
    */
-  shortcut?: string;
+  getMetadata(): TableMetadata;
+  protected _ensureSearchable(): void;
+  /** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
+  protected _guardQuery(query: Uniquery | undefined): void;
+  private _encryptedPathsCache?;
+  /** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
+  protected get _encryptedPaths(): Array<{
+    path: string;
+    segments: string[];
+    leaf: string;
+  }>;
   /**
-   * Stringified gate predicate (`fn.toString()`). Present only for `'row'`
-   * and `'rows'` level actions whose decorator declared a `disabled` function.
-   * The function is the batch shape `(rows: TRow[]) => boolean[]` (sync). The
-   * UI evaluates against a level-specific scope to grey-out / hide the
-   * button. The server has already enforced this predicate before the
-   * action's handler ran — the server is authoritative; this field is purely
-   * a UI hint.
+   * Walks all but the last of `segments` down from `root`, returning the
+   * object holding the leaf — or `undefined` when the path is unreachable
+   * (a missing, non-object, or array step). With `cloneParents`, every
+   * traversed object is shallow-cloned and re-linked so caller-shared
+   * nested objects are never mutated.
    */
-  disabled?: string;
+  protected _walkToLeafParent(root: Record<string, unknown>, segments: string[], cloneParents: boolean): Record<string, unknown> | undefined;
   /**
-   * Name of the `.as` interface the action's `@InputForm()` parameter expects
-   * (the compiled class's `.name`). Present only when the handler declares an
-   * `@InputForm(FormType)` parameter. Clients fetch the serialized schema via
-   * `GET /meta/form/:name` on the same controller and render a form to
-   * collect the `input` field of the action's request envelope.
+   * Decrypts `@db.encrypted` fields on reconstructed rows (in place).
+   * Non-envelope stored values follow the configured `onUnencrypted` policy.
    */
-  inputForm?: string;
-}
-interface TDbInsertResult {
-  insertedId: unknown;
-}
-interface TDbInsertManyResult {
-  insertedCount: number;
-  insertedIds: unknown[];
-}
-interface TDbUpdateResult {
-  matchedCount: number;
-  modifiedCount: number;
-}
-interface TDbDeleteResult {
-  deletedCount: number;
-}
-type TDbIndexType = "plain" | "unique" | "fulltext" | "geo";
-interface TDbIndexField {
-  name: string;
-  sort: "asc" | "desc";
-  weight?: number;
+  protected _decryptRows(rows: Array<Record<string, unknown>>): Promise<void>;
+  /** Whether this readable is a view (overridden in AtscriptDbView). */
+  get isView(): boolean;
+  /** Returns the underlying adapter with its concrete type preserved. */
+  getAdapter(): A;
+  /** The raw annotated type. */
+  get type(): TAtscriptAnnotatedType<TAtscriptTypeObject>;
+  /** Lazily-built flat map of all fields (dot-notation paths → annotated types). */
+  get flatMap(): Map<string, TAtscriptAnnotatedType>;
+  /** All computed indexes from `@db.index.*` annotations. */
+  get indexes(): Map<string, TDbIndex>;
+  /** Primary key field names from `@meta.id`. */
+  get primaryKeys(): readonly string[];
+  /** Preferred row identifier field names. Defaults to primary keys. */
+  get preferredId(): readonly string[];
+  /** Legitimate row-identifier shapes (primary key + every unique index). */
+  get identifications(): readonly TIdentification[];
   /**
-   * Whether the indexed field is optional (declared `field?:` in the model).
-   * Resolved during index finalization. Adapters use this to make a unique
-   * index "present-only" so multiple value-less rows are tolerated — matching
-   * SQL's `NULLS DISTINCT` default. SQL adapters get this for free and ignore
-   * the flag; MongoDB needs it to emit a partial unique index.
-   */
-  optional?: boolean;
+   * Physical column name of the single `@meta.id` field, or `null` when the
+   * schema has zero or multiple `@meta.id` fields. Used by adapters to return
+   * the user's logical ID instead of the DB-generated one on insert.
+   *
+   * @internal Adapter-facing surface; not part of the consumer API.
+   */
+  get metaIdPhysical(): string | null;
   /**
-   * Resolved design type of the field ('string', 'number', 'boolean', …).
-   * Carried alongside {@link optional} so adapters can derive a type-correct
-   * present-only filter (e.g. Mongo's `partialFilterExpression`) without
-   * re-resolving the field type. Undefined when the field cannot be resolved.
+   * Physical column name of the field annotated with `@db.column.version`, or
+   * `undefined` when the table has no version column. Used by adapters and the
+   * REST integration to drive optimistic concurrency control (OCC).
    */
-  designType?: string;
-}
-interface TDbIndex {
-  /** Unique key used for identity/diffing (e.g., "atscript__plain__email") */
-  key: string;
-  /** Human-readable index name. */
-  name: string;
-  /** Index type. */
-  type: TDbIndexType;
-  /** Ordered list of fields in the index. */
-  fields: TDbIndexField[];
-}
-type TDbDefaultFn = "increment" | "uuid" | "now";
-type TDbCollation = "binary" | "nocase" | "unicode";
-type TDbDefaultValue = {
-  kind: "value";
-  value: string;
-} | {
-  kind: "fn";
-  fn: TDbDefaultFn;
-  start?: number;
-};
-interface TIdDescriptor {
-  /** Field names that form the primary key. */
-  fields: string[];
-  /** Whether this is a composite key (multiple fields). */
-  isComposite: boolean;
-}
-/** A legitimate row-identifier shape: primary key or a unique index. */
-interface TIdentification {
-  /** Logical (path) field names that form this identifier. */
-  fields: readonly string[];
-  /** `'primaryKey'` for the PK; the unique-index name otherwise. */
-  source: string;
-}
-type TDbStorageType = "column" | "flattened" | "json";
-interface TDbFieldMeta {
-  /** The dot-notation path to this field (logical name). */
-  path: string;
-  /** The annotated type for this field. */
-  type: TAtscriptAnnotatedType;
-  /** Physical column/field name (from @db.column, __-separated for flattened, or same as path). */
-  physicalName: string;
-  /** Resolved design type: 'string', 'number', 'boolean', 'object', 'json', etc. */
-  designType: string;
-  /** Whether the field is optional. */
-  optional: boolean;
-  /** Whether this field is part of the primary key (@meta.id). */
-  isPrimaryKey: boolean;
-  /** Whether this field is excluded from the DB (@db.ignore). */
-  ignored: boolean;
-  /** Default value from @db.default.* */
-  defaultValue?: TDbDefaultValue;
+  get versionColumn(): string | undefined;
+  /** Dimension fields from `@db.column.dimension`. */
+  get dimensions(): readonly string[];
+  /** Measure fields from `@db.column.measure`. */
+  get measures(): readonly string[];
+  /** Sync method for structural changes: 'drop' (lossy), 'recreate' (lossless), or undefined (manual). */
+  get syncMethod(): "drop" | "recreate" | undefined;
+  /** Logical → physical column name mapping from `@db.column`. */
+  get columnMap(): ReadonlyMap<string, string>;
+  /** Default values from `@db.default.*`. */
+  get defaults(): ReadonlyMap<string, TDbDefaultValue>;
+  /** Fields excluded from DB via `@db.ignore`. */
+  get ignoredFields(): ReadonlySet<string>;
+  /** Navigational fields (`@db.rel.to` / `@db.rel.from`) — not stored as columns. */
+  get navFields(): ReadonlySet<string>;
+  /** Physical field names used to invert exclude-mode `$select` into a SELECT list. */
+  get allPhysicalFields(): readonly string[];
+  /** Single-field unique index properties. */
+  get uniqueProps(): ReadonlySet<string>;
+  /** Foreign key constraints from `@db.rel.FK` annotations. */
+  get foreignKeys(): ReadonlyMap<string, TDbForeignKey>;
+  /** Navigational relation metadata from `@db.rel.to` / `@db.rel.from`. */
+  get relations(): ReadonlyMap<string, TDbRelation>;
+  /** The underlying database adapter instance. */
+  get dbAdapter(): A;
   /**
-   * How this field is stored in the database.
-   * - 'column': a standard scalar column (default for primitives)
-   * - 'flattened': a leaf scalar from a flattened nested object
-   * - 'json': stored as a single JSON column (arrays, @db.json fields)
+   * Enables or disables verbose (debug-level) DB call logging for this table/view.
+   * When disabled (default), no log strings are constructed — zero overhead.
    */
-  storage: TDbStorageType;
+  setVerbose(enabled: boolean): void;
+  /** Precomputed logical dot-path → physical column name map. */
+  get pathToPhysical(): ReadonlyMap<string, string>;
+  /** Precomputed physical column name → logical dot-path map (inverse). */
+  get physicalToPath(): ReadonlyMap<string, string>;
+  /** Descriptor for the primary ID field(s). */
+  getIdDescriptor(): TIdDescriptor;
   /**
-   * For flattened fields: the dot-notation path (same as `path`).
-   * E.g., for physicalName 'contact__email', this is 'contact.email'.
-   * Undefined for non-flattened fields.
+   * Pre-computed field metadata for adapter use.
    */
-  flattenedFrom?: string;
-  /** Old physical column name from @db.column.renamed (for rename migration). */
-  renamedFrom?: string;
-  /** Collation from @db.column.collate (e.g. 'nocase', 'binary', 'unicode'). */
-  collate?: TDbCollation;
+  get fieldDescriptors(): readonly TDbFieldMeta[];
   /**
-   * Whether this field is index-backed: it participates in an explicit index
-   * (@db.index.plain, @db.index.unique, @db.index.fulltext) OR is a primary key
-   * or unique field (which are always index-backed — Mongo `_id`, SQL PK/unique
-   * constraints — even without an explicit `@db.index*`).
+   * Resolves whether `path` references a real field — directly via `flatMap`
+   * or transitively through a nav relation by recursing into the target
+   * 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.
+   *
+   * Cycle-safe via a visited set keyed on `<tableName>:<navField>`.
    */
-  isIndexed?: boolean;
-  /** Literal currency code from `@db.amount.currency 'EUR'`. */
-  currencyCode?: string;
-  /** Sibling field path from `@db.amount.currency.ref 'fieldName'`. */
-  currencyRefField?: string;
-  /** Literal unit-of-measure from `@db.unit 'kg'`. */
-  unitCode?: string;
-  /** Sibling field path from `@db.unit.ref 'fieldName'`. */
-  unitRefField?: string;
+  isValidFieldPath(path: string, _visited?: Set<string>): boolean;
   /**
-   * For FK fields: the resolved field metadata of the referenced (target) PK column.
-   * Adapters use this in `typeMapper` to produce matching DB types for FK columns
-   * (e.g., `typeMapper(field.fkTargetField)` to inherit the target PK's DB type).
-   * Undefined for non-FK fields or when the target cannot be resolved.
+   * Creates a new validator with custom options.
    */
-  fkTargetField?: TDbFieldMeta;
+  createValidator(opts?: Partial<TValidatorOptions>): Validator<T, DataType>;
   /**
-   * `@db.encrypted` — the value is AES-256-GCM encrypted by the core layer
-   * before reaching the adapter. Adapters must map the column to an unbounded
-   * text type and veto filtering/sorting (`canFilterField`/`canSortField`).
-   * The descriptor's `designType` is forced to `'string'` (ciphertext envelope);
-   * the declared type stays available via `type` for validation.
+   * Finds a single record matching the query.
+   * The return type automatically excludes nav props unless they are
+   * explicitly requested via `$with`.
    */
-  encrypted?: boolean;
+  findOne<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
   /**
-   * The field's declared type is the `db.geoPoint` primitive (`[lng, lat]` tuple).
-   * Adapters map this to their native geo storage (e.g. MongoDB GeoJSON Point).
+   * Finds all records matching the query.
+   * The return type automatically excludes nav props unless they are
+   * explicitly requested via `$with`.
    */
-  isGeoPoint?: boolean;
-}
-interface TValueFormatterPair {
-  /** Converts a JS value to storage representation (write + filter paths). */
-  toStorage: (value: unknown) => unknown;
-  /** Converts a storage value back to JS representation (read path). */
-  fromStorage: (value: unknown) => unknown;
-}
-type TDbReferentialAction = "cascade" | "restrict" | "noAction" | "setNull" | "setDefault";
-interface TDbForeignKey {
-  /** FK field names on this table (local columns). */
-  fields: string[];
-  /** Target table name (from the chain ref's type @db.table annotation). */
-  targetTable: string;
-  /** Target field names on the referenced table. */
-  targetFields: string[];
-  /** Lazy reference to the target annotated type (for on-demand table resolution). */
-  targetTypeRef?: () => TAtscriptAnnotatedType;
-  /** Alias grouping FK fields (if any). */
-  alias?: string;
-  /** Referential action on delete. */
-  onDelete?: TDbReferentialAction;
-  /** Referential action on update. */
-  onUpdate?: TDbReferentialAction;
-}
-/** Describes an existing column in the database (from introspection). */
-interface TExistingColumn {
-  name: string;
-  type: string;
-  notnull: boolean;
-  pk: boolean;
-  /** Serialized default value (e.g., "'active'", "NULL"). */
-  dflt_value?: string;
-}
-/** Result of comparing desired schema against existing database columns. */
-interface TColumnDiff {
-  added: TDbFieldMeta[];
-  removed: TExistingColumn[];
-  renamed: Array<{
-    field: TDbFieldMeta;
-    oldName: string;
-  }>;
-  typeChanged: Array<{
-    field: TDbFieldMeta;
-    existingType: string;
-  }>;
-  nullableChanged: Array<{
-    field: TDbFieldMeta;
-    wasNullable: boolean;
-  }>;
-  defaultChanged: Array<{
-    field: TDbFieldMeta;
-    oldDefault?: string;
-    newDefault?: string;
-  }>;
-  conflicts: Array<{
-    field: TDbFieldMeta;
-    oldName: string;
-    conflictsWith: string;
+  findMany<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  /**
+   * Counts records matching the query.
+   */
+  count(query?: Uniquery<OwnProps, NavType>): Promise<number>;
+  /**
+   * Finds records and total count in a single logical call.
+   */
+  findManyWithCount<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<{
+    data: Array<DbResponse<DataType, NavType, Q>>;
+    count: number;
   }>;
   /**
-   * The primary-key FIELD SET differs between the live table and the model
-   * (set semantics — a composite-key reorder is not a change, consistent with
-   * the schema hash). Column names are physical; a renamed PK column is
-   * compared under its new name. Only reported when the table exists.
-   * @since 0.1.128
+   * Executes an aggregate query with GROUP BY and aggregate functions.
+   *
+   * Validates:
+   * - `$select` computed entries and calendar buckets (the shared normalizer,
+   *   `resolveCalendarBuckets`: shapes, unit, zone, alias, grouping)
+   * - Plain fields in $select are a subset of $groupBy
+   * - When dimensions/measures are defined (strict mode): $groupBy fields
+   *   must be dimensions (a calendar bucket's source field included),
+   *   aggregate $field values must be measures (or '*')
+   * - the path guard (a bucket source must be a timestamp field) and the
+   *   adapter's calendar-bucket units (`BUCKET_NOT_SUPPORTED`)
+   *
+   * Translates field names, delegates to adapter.aggregate(),
+   * then reverse-maps and applies fromStorage formatters on results.
    */
-  primaryKeyChanged?: TPrimaryKeyChange;
-}
-/** Old and new primary-key column sets of a table whose key definition moved. */
-interface TPrimaryKeyChange {
-  /** Physical PK columns currently in the database (after rename mapping). */
-  from: string[];
-  /** Physical PK columns the model declares. */
-  to: string[];
-}
-/**
- * A live foreign-key constraint as introspected from the database
- * (outbound: declared on the table that owns it).
- */
-interface TExistingForeignKey {
-  /** Local (referencing) columns, in constraint order. */
-  fields: string[];
-  /** Referenced table name. */
-  targetTable: string;
-  /** Referenced columns, in constraint order. */
-  targetFields: string[];
-}
-/**
- * A live foreign key that REFERENCES a given table (inbound edge), as returned
- * by `BaseDbAdapter.getReferencingForeignKeys(tableName)`.
- */
-interface TReferencingForeignKey {
-  /** The referencing (child) table. */
-  table: string;
-  /** Referencing columns on `table`, in constraint order. */
-  fields: string[];
-  /** Referenced columns on the queried table, in constraint order. */
-  targetFields: string[];
-}
-/** Kind of a physical database object, as returned by `BaseDbAdapter.getObjectKind`. */
-type TDbObjectKind = "table" | "view" | "materialized";
-/** Options accepted by `BaseDbAdapter.ensureTable`. */
-interface TEnsureTableOptions {
+  aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
+  /** 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 can sort by a given field (proxies adapter capability). */
+  canSortField(fd: TDbFieldMeta): boolean;
+  /** Returns available search indexes from the adapter. */
+  getSearchIndexes(): TSearchIndexInfo[];
   /**
-   * Table names whose inline FOREIGN KEY constraints must be omitted from
-   * CREATE TABLE — the constraints are added afterwards by `syncForeignKeys()`.
-   * Schema sync passes the members of a foreign-key cycle so they can be
-   * created in any order.
+   * Full-text search with query translation and result reconstruction.
    */
-  deferForeignKeysTo?: ReadonlySet<string>;
-}
-/** Result of applying column diff to the database. */
-interface TSyncColumnResult {
-  added: string[];
-  renamed: string[];
-}
-/** A single table-level option in unified key-value format. */
-interface TExistingTableOption {
-  key: string;
-  value: string;
-}
-/** Result of comparing desired table options against existing ones. */
-interface TTableOptionDiff {
-  changed: Array<{
-    key: string;
-    oldValue: string;
-    newValue: string; /** Whether applying this change requires dropping and recreating the table. */
-    destructive: boolean;
+  search<Q extends Uniquery<OwnProps, NavType>>(text: string, query: Q, indexName?: string): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  /**
+   * Full-text search with count for paginated search results.
+   */
+  searchWithCount<Q extends Uniquery<OwnProps, NavType>>(text: string, query: Q, indexName?: string): Promise<{
+    data: Array<DbResponse<DataType, NavType, Q>>;
+    count: number;
   }>;
-}
-/**
- * Adapter-provided metadata adjustments applied atomically during the
- * build pipeline, before field descriptors are built.
- *
- * Replaces the old pattern where adapters mutated metadata via
- * back-references (`this._table.addPrimaryKey()`, etc.).
- */
-interface TMetadataOverrides {
-  /** Fields to add as primary keys. */
-  addPrimaryKeys?: string[];
-  /** Fields to remove from primary keys. */
-  removePrimaryKeys?: string[];
-  /** Fields to register as having a unique constraint. */
-  addUniqueFields?: string[];
-  /** Synthetic fields to inject into flatMap (e.g. MongoDB's `_id`). */
-  injectFields?: Array<{
-    path: string;
-    type: TAtscriptAnnotatedType;
+  /** Whether the underlying adapter supports vector similarity search. */
+  isVectorSearchable(): boolean;
+  /**
+   * Vector similarity search with query translation and result reconstruction.
+   *
+   * Overloads:
+   * - `vectorSearch(vector, query?)` — uses default vector index
+   * - `vectorSearch(indexName, vector, query?)` — targets a specific vector index
+   */
+  vectorSearch<Q extends Uniquery<OwnProps, NavType>>(vectorOrIndex: number[] | string, maybeVectorOrQuery?: number[] | Q, maybeQuery?: Q): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  /**
+   * Vector similarity search with count for paginated results.
+   *
+   * Overloads:
+   * - `vectorSearchWithCount(vector, query?)` — uses default vector index
+   * - `vectorSearchWithCount(indexName, vector, query?)` — targets a specific vector index
+   */
+  vectorSearchWithCount<Q extends Uniquery<OwnProps, NavType>>(vectorOrIndex: number[] | string, maybeVectorOrQuery?: number[] | Q, maybeQuery?: Q): Promise<{
+    data: Array<DbResponse<DataType, NavType, Q>>;
+    count: number;
   }>;
-}
-/**
- * Callback that resolves an annotated type to a queryable table instance.
- * Required for `$with` relation loading — each table needs to query related tables.
- *
- * Typically provided by the driver/registry (e.g. `DbSpace.getTable`).
- */
-type TTableResolver = (type: TAtscriptAnnotatedType) => Pick<AtscriptDbTableLike, "findMany" | "loadRelations" | "primaryKeys" | "preferredId" | "relations" | "foreignKeys" | "isValidFieldPath"> | undefined;
-/** Minimal table interface used by the table resolver. Avoids circular dependency with AtscriptDbTable. */
-interface AtscriptDbTableLike {
-  findMany(query: unknown): Promise<Array<Record<string, unknown>>>;
-  loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[]): Promise<void>;
-  primaryKeys: readonly string[];
-  preferredId: readonly string[];
-  relations: ReadonlyMap<string, TDbRelation>;
-  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
-  getMetadata(): TableMetadata;
-  isValidFieldPath(path: string, visited?: Set<string>): boolean;
-}
-/** Minimal writable table interface for nested creation/update. */
-interface AtscriptDbWritable {
-  insertOne(payload: Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertResult>;
-  insertMany(payloads: Array<Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-    _depth?: number;
-  }): Promise<TDbInsertManyResult>;
-  replaceOne(payload: Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
-  bulkReplace(payloads: Array<Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-    _depth?: number;
-  }): Promise<TDbUpdateResult>;
-  updateOne(payload: Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
-  bulkUpdate(payloads: Array<Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-    _depth?: number;
-  }): Promise<TDbUpdateResult>;
-  findOne(query: unknown): Promise<Record<string, unknown> | null>;
-  count(query: {
-    filter: Record<string, unknown>;
-  }): Promise<number>;
-  deleteMany(filter: unknown): Promise<TDbDeleteResult>;
-  /** Pre-validate items (type + FK constraints) without inserting them. */
-  preValidateItems(items: Array<Record<string, unknown>>, opts?: {
-    excludeFkTargetTable?: string;
-  }): Promise<void>;
-}
-/**
- * Callback that resolves an annotated type to a writable table instance.
- * Used for nested creation — inserting related records inline.
- */
-type TWriteTableResolver = (type: TAtscriptAnnotatedType) => (AtscriptDbTableLike & AtscriptDbWritable) | undefined;
-/**
- * A child table that may need cascade/setNull processing when a parent is deleted.
- * Returned by the cascade resolver.
- */
-interface TCascadeTarget {
-  /** FK on the child table that references the parent being deleted. */
-  fk: TDbForeignKey;
-  /** Name of the child table that holds this FK. */
-  childTable: string;
-  /** Delete matching child records (goes through AtscriptDbTable for recursive cascade). */
-  deleteMany(filter: Record<string, unknown>): Promise<TDbDeleteResult>;
-  /** Update matching child records (for setNull — sets FK fields to null). */
-  updateMany(filter: Record<string, unknown>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-  /** Count matching child records (for restrict — check existence before delete). */
-  count(filter: Record<string, unknown>): Promise<number>;
-}
-/**
- * Callback that finds all child tables with FKs pointing to a given parent table.
- * Used by AtscriptDbTable to implement application-level cascade deletes.
- */
-type TCascadeResolver = (tableName: string) => TCascadeTarget[];
-/**
- * Minimal interface for querying a target table during FK validation.
- * Only `count` is needed — we check if the referenced record exists.
- */
-interface TFkLookupTarget {
-  count(filter: Record<string, unknown>): Promise<number>;
-}
-/**
- * Callback that resolves a table name to a queryable target for FK validation.
- * Returns undefined if the target table is not registered in the space.
- */
-type TFkLookupResolver = (tableName: string) => TFkLookupTarget | undefined;
-interface TDbRelation {
-  /** Direction: 'to' (FK is local), 'from' (FK is remote), or 'via' (M:N junction). */
-  direction: "to" | "from" | "via";
-  /** The alias used for pairing (if any). */
-  alias?: string;
-  /** Target type's annotated type reference. */
-  targetType: () => TAtscriptAnnotatedType;
-  /** Whether this is an array relation (one-to-many). */
-  isArray: boolean;
-  /** Junction type reference for 'via' (M:N) relations. */
-  viaType?: () => TAtscriptAnnotatedType;
-}
-/**
- * Write payload for insert / patch paths: every key optional, and optional
- * columns additionally accept `null` (an explicit NULL — `undefined` means
- * "absent" and is dropped before the row reaches defaults or validation).
- */
-type DbPatch<D> = { [K in keyof D]?: undefined extends D[K] ? D[K] | null : D[K] } & Record<string, unknown>;
-/**
- * Write payload for full-row replace paths: required keys stay required,
- * optional columns additionally accept `null` (explicit NULL).
- */
-type DbRow<D> = { [K in keyof D]: undefined extends D[K] ? D[K] | null : D[K] } & Record<string, unknown>;
-/** Built-in write actions a moost-db `AsDbController` endpoint performs. */
-type TDbWriteAction = "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany";
-/**
- * Context handed to a write {@link TWriteOptions.guard} (since 0.1.128) — and
- * through it to `AsDbController.guardWrite()`. The table invokes the guard
- * exactly once, inside its own transaction, after `undefined`-pruning,
- * defaults and validation and before encryption / nested-relation phases.
- */
-interface TDbWriteGuardContext<Row = Record<string, unknown>> {
-  /** The table method the guard runs for (`insertOne` → `insert`, `insertMany` → `insertMany`, …). */
-  readonly action: TDbWriteAction;
+  /** Resolves overloaded vector search arguments into canonical form. */
+  private _resolveVectorSearchArgs;
+  /** Whether the underlying adapter supports geospatial search. */
+  isGeoSearchable(): boolean;
+  /**
+   * Distance-ranked geospatial search (mirrors {@link vectorSearch}).
+   * Results are sorted by distance ascending; each row carries a computed
+   * `$distance` field (meters from the query point). `$maxDistance` /
+   * `$minDistance` (meters) ride in `query.controls`; user `$sort` is rejected.
+   *
+   * Overloads:
+   * - `geoSearch(point, query?)` — uses the table's only geo index
+   * - `geoSearch(indexName, point, query?)` — targets a specific geo index
+   */
+  geoSearch<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<Array<DbResponse<DataType, NavType, Q> & {
+    $distance: number;
+  }>>;
+  /**
+   * Distance-ranked geospatial search with count for paginated results.
+   *
+   * Overloads:
+   * - `geoSearchWithCount(point, query?)` — uses the table's only geo index
+   * - `geoSearchWithCount(indexName, point, query?)` — targets a specific geo index
+   */
+  geoSearchWithCount<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<{
+    data: Array<DbResponse<DataType, NavType, Q> & {
+      $distance: number;
+    }>;
+    count: number;
+  }>;
+  /** Resolves overloaded geo search arguments into canonical form. */
+  private _resolveGeoSearchArgs;
+  /** Shared geoSearch validation + query translation. */
+  private _prepareGeoSearch;
   /**
-   * insert/replace: validated rows with SDK-side defaults applied (plaintext,
-   * nav data still attached); update: validated patches with the identifying
-   * PK/unique fields present and `$cas` removed. Mutate in place to enrich —
-   * the table re-validates the rows after the guard.
+   * Finds a single record by any type-compatible identifier — primary key
+   * or single-field unique index.
+   * The return type excludes nav props unless `$with` is provided in controls.
+   *
+   * ```typescript
+   * // Without relations — nav props stripped from result
+   * const user = await table.findById('123')
+   *
+   * // With relations — only requested nav props appear
+   * const user = await table.findById('123', { controls: { $with: [{ name: 'posts' }] } })
+   * ```
    */
-  readonly rows: Row[];
-  /** Parallel to `rows`: expected version lifted from `$cas`, or `undefined`. */
-  readonly expectedVersions: ReadonlyArray<number | undefined>;
+  findById<Q extends {
+    controls?: UniqueryControls<OwnProps, NavType>;
+  } = Record<string, never>>(id: IdType, query?: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
   /**
-   * Lazy, memoised pre-image of `rows[i]` by its identifying filter, read
-   * inside the transaction. `null` when the row is missing OR when it carries
-   * no identifying key yet (e.g. auto-increment inserts) — never throws.
+   * Resolve an id value (scalar or object) into a {@link FilterExpr} using the
+   * same identification resolution as {@link findById}. Public so callers can
+   * AND-combine the id-filter with a row-level read overlay before issuing
+   * `findOne` (avoiding the existence leak that `findById` would cause).
    */
-  current(i: number): Promise<Row | null>;
-}
-/**
- * Context handed to a delete {@link TDeleteOptions.guard} (since 0.1.128) —
- * and through it to `AsDbController.guardRemove()`. Runs inside the table's
- * transaction; an id that resolves to no filter never reaches the guard
- * (`deleteOne` answers `{ deletedCount: 0 }`).
- */
-interface TDbRemoveGuardContext<Row = Record<string, unknown>> {
-  /** The id `deleteOne` was called with. */
-  readonly id: unknown;
-  /** `table.resolveIdFilter(id)` — never null here. */
-  readonly filter: FilterExpr;
-  /** Lazy, memoised pre-image of the row about to be deleted (`null` when missing). */
-  current(): Promise<Row | null>;
-}
-/** A validated-stage write guard — see {@link TWriteOptions.guard}. */
-type TDbWriteGuard<Row = Record<string, unknown>> = (ctx: TDbWriteGuardContext<Row>) => void | Promise<void>;
-/** A validated-stage delete guard — see {@link TDeleteOptions.guard}. */
-type TDbRemoveGuard<Row = Record<string, unknown>> = (ctx: TDbRemoveGuardContext<Row>) => void | Promise<void>;
-/** Options of `AtscriptDbTable.touchMany` (since 0.1.129). */
-interface TTouchManyOptions {
+  resolveIdFilter(id: unknown): FilterExpr | null;
   /**
-   * `'all'` (default): every key must match its stored version — a stale or
-   * missing row throws `DbError("CAS_MISMATCH")` and no version moves.
-   * `'any'`: bump whatever matches and report the honest counts.
+   * Resolve an id value into a filter expression.
+   *
+   * When `preferredId` differs from the PK, scalar ids resolve only against
+   * the preferred field (deterministic addressing). Otherwise scalars try PK
+   * + every single-field unique index; objects try PK + compound unique
+   * indexes.
    */
-  require?: "all" | "any";
-}
-/** Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`. */
-interface TWriteOptions<Row = Record<string, unknown>> {
-  /** Nested-relation write recursion limit (default 3). */
-  maxDepth?: number;
+  protected _resolveIdFilter(id: unknown): FilterExpr | null;
+  /** Build a single-key filter from `idObj` over `fields`, or null if any field is missing/incompatible. */
+  private _tryCompoundFilter;
   /**
-   * Validated-stage guard (since 0.1.128): invoked exactly once inside the
-   * table's transaction, after defaults + validation and before encryption
-   * and nested-relation phases, with the rows the table is about to write.
-   * Rows may be enriched in place — they are validated again afterwards. A
-   * throw rolls the transaction back and propagates unchanged. Never runs
-   * for the nested re-entries a deep write performs on related tables.
+   * Attempts to build a single-field filter `{ field: preparedId }`.
    */
-  guard?: TDbWriteGuard<Row>;
-}
-/** Options of `deleteOne`. */
-interface TDeleteOptions<Row = Record<string, unknown>> {
+  private _tryFieldFilter;
   /**
-   * Validated-stage guard (since 0.1.128): invoked inside the table's
-   * transaction after the id resolved to a filter and before cascade /
-   * delete. A throw rolls the transaction back and propagates unchanged.
+   * Public entry point for relation loading. Used by adapters for nested $with delegation.
    */
-  guard?: TDbRemoveGuard<Row>;
+  loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[]): Promise<void>;
+  /**
+   * Finds the FK entry that connects a `@db.rel.to` relation to its target.
+   * Thin wrapper — delegates to relation-loader for shared use with db-table.ts write path.
+   */
+  protected _findFKForRelation(relation: TDbRelation): {
+    localFields: string[];
+    targetFields: string[];
+  } | undefined;
+  /**
+   * Finds a FK on a remote table that points back to this table.
+   * Thin wrapper — delegates to relation-loader for shared use with db-table.ts write path.
+   */
+  protected _findRemoteFK(targetTable: {
+    foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
-/**
- * Adds `null` to every optional property of `O`. Optional columns store SQL
- * NULL / Mongo null, and the runtime validator accepts `null` for optional
- * props — so filter shapes (`{ note: null }`, `{ note: { $ne: null } }`) and
- * row shapes must admit it at the type level too. Homomorphic: keys and
- * required properties are unchanged; applying it twice is a no-op.
- */
-type NullableOptional<O> = { [K in keyof O]: undefined extends O[K] ? O[K] | null : O[K] };
 //#endregion
 //#region src/base-adapter.d.ts
+/** Every calendar-bucket unit — what an adapter that renders them all returns from `calendarBucketUnits()`. */
+declare const ALL_BUCKET_UNITS: ReadonlySet<BucketUnit>;
 /**
  * Abstract base class for database adapters.
  *
@@ -1022,6 +759,21 @@ declare abstract class BaseDbAdapter {
    * to generate the value client-side or leave it for the DB.
    */
   nativeDefaultFns(): ReadonlySet<TDbDefaultFn>;
+  /**
+   * Calendar-bucket units (`{ $bucket, $field }` in an aggregate `$select`)
+   * this adapter can group by, over IANA time zones. Empty (the default) =
+   * calendar buckets unsupported: the core rejects them with
+   * `BUCKET_NOT_SUPPORTED` before dispatch, and moost-db's `/meta` advertises
+   * no bucketable field.
+   *
+   * A set rather than a boolean (like {@link nativeDefaultFns}) so a unit can
+   * 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.
+   */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   /**
    * Whether this adapter enforces foreign key constraints natively.
    * When `true`, the generic layer skips application-level cascade/setNull
@@ -1042,6 +794,9 @@ declare abstract class BaseDbAdapter {
    * Used by `AsDbReadableController.buildMetaResponse()` to gate the
    * `filterable` flag exposed to UIs — the adapter's answer is a hard gate
    * even when the field carries `@db.column.filterable`.
+   *
+   * Vetoes value comparison only — a sole-`$exists` entry needs just a stored
+   * column (`canFilterLeaf`).
    */
   canFilterField(fd: TDbFieldMeta): boolean;
   /**
@@ -1195,8 +950,15 @@ declare abstract class BaseDbAdapter {
    */
   getSearchIndexes(): TSearchIndexInfo[];
   /**
-   * Whether this adapter supports text search.
-   * Default: `true` when {@link getSearchIndexes} returns any entries.
+   * Whether this adapter can run TEXT search — `search()`, `searchWithCount()`
+   * and the grouped `$search` path all gate on it. Vector capability is a
+   * separate predicate, {@link isVectorSearchable}.
+   *
+   * Default: `true` when {@link getSearchIndexes} lists at least one non-vector
+   * index. Vector entries are published there for the index picker, but a
+   * vector index answers {@link vectorSearch} and nothing else, so counting one
+   * here would claim a capability the adapter does not have. An entry without
+   * `type` counts as text — adapters predating the field only listed text.
    */
   isSearchable(): boolean;
   /**
@@ -1532,487 +1294,931 @@ declare abstract class BaseDbAdapter {
   formatValue?(field: TDbFieldMeta): TValueFormatterPair | ((value: unknown) => unknown) | undefined;
 }
 //#endregion
-//#region src/strategies/field-mapping.d.ts
+//#region src/table/table-metadata.d.ts
 /**
- * Strategy for mapping data between logical field shapes and physical storage.
- * Two implementations: {@link DocumentFieldMapper} (nested objects, NoSQL)
- * and `RelationalFieldMapper` (flattened columns, SQL).
+ * Finds the nearest ancestor of `path` that belongs to `set`.
+ * Used by both the build pipeline (in `_classifyFields`) and
+ * runtime reconstruction on the Readable.
  */
-declare abstract class FieldMappingStrategy {
-  abstract reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
-  abstract translateQuery(query: Uniquery, meta: TableMetadata): DbQuery;
-  abstract translateAggregateQuery(query: AggregateQuery, meta: TableMetadata): DbQuery;
-  /**
-   * Recursively walks a filter expression, applying `@db.column` key renames
-   * via `columnMap` and adapter-specific value formatting via `formatFilterValue`.
-   *
-   * The relational mapper overrides this to use `leafByLogical` for deeper
-   * key resolution (flattened nested paths).
-   */
-  translateFilter(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>;
-  /**
-   * Reverse-maps `@db.column` renames on a row read from storage.
-   * Renames physical keys back to logical names in-place.
-   */
-  protected reverseColumnRenames(row: Record<string, unknown>, meta: TableMetadata): void;
+declare function findAncestorInSet(path: string, set: ReadonlySet<string>): string | undefined;
+/** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
+declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
+/**
+ * Returns true if the annotated type is acceptable for `@db.index.geo`:
+ * the `db.geoPoint` primitive or a structurally identical `number[]`
+ * (excluding `db.vector`, which is semantically an embedding).
+ */
+declare function isGeoIndexableType(fieldType: TAtscriptAnnotatedType): boolean;
+/**
+ * Computed metadata for a database table or view.
+ *
+ * Contains all field metadata, physical mapping indexes, relation definitions,
+ * and constraint information derived from Atscript annotations. Built lazily
+ * on first access via {@link build}, then immutable.
+ *
+ * This class owns the build pipeline that was previously part of
+ * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
+ * access to this class.
+ */
+declare class TableMetadata {
+  readonly nestedObjects: boolean;
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  fieldDescriptors: readonly TDbFieldMeta[];
+  primaryKeys: string[];
+  preferredId: string[];
+  originalMetaIdFields: string[];
+  indexes: Map<string, TDbIndex>;
+  foreignKeys: Map<string, TDbForeignKey>;
+  relations: Map<string, TDbRelation>;
+  navFields: Set<string>;
+  ignoredFields: Set<string>;
+  uniqueProps: Set<string>;
+  defaults: Map<string, TDbDefaultValue>;
+  columnMap: Map<string, string>;
+  dimensions: string[];
+  measures: string[];
+  /** Logical field name annotated with `@db.column.version`, if any. */
+  versionField?: string;
+  /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
+  quantityRefByField: Map<string, string>;
+  /** Logical paths annotated with `@db.encrypted` — stored as one opaque ciphertext column. */
+  encryptedFields: Set<string>;
+  pathToPhysical: Map<string, string>;
+  physicalToPath: Map<string, string>;
+  flattenedParents: Set<string>;
+  jsonFields: Set<string>;
+  selectExpansion: Map<string, string[]>;
+  booleanFields: Set<string>;
+  decimalFields: Set<string>;
+  allPhysicalFields: string[];
+  /** Precomputed parent path → child physical column names for fast null-setting. */
+  childrenByParent: Map<string, string[]>;
+  /** Precomputed parent path → optional child logical paths (replace-strategy null-fill in the patch decomposer). */
+  optionalLeavesByLogicalParent: Map<string, string[]>;
+  requiresMappings: boolean;
+  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
+  onlyColumnRenames: boolean;
+  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  /** Leaf field descriptors indexed by physical column name (read path). */
+  leafByPhysical: Map<string, TDbFieldMeta>;
+  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
+  leafByLogical: Map<string, TDbFieldMeta>;
   /**
-   * Coerces field values from storage representation to JS types
-   * (booleans from 0/1, decimals from number to string).
+   * Non-ignored field descriptors keyed by logical path, excluding navigation
+   * relations and their descendants. Unlike `leafByLogical` (relational
+   * adapters only) this is built for every adapter, so the core path guard
+   * (`guardPaths`) can answer "does this path have physical storage here?"
+   * on nested-object adapters too.
    */
-  protected coerceFieldValues(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  descriptorByPath: Map<string, TDbFieldMeta>;
   /**
-   * Applies adapter-specific fromStorage formatting to a row read from the database.
-   * Converts storage representations back to JS values (e.g. Date → epoch ms).
+   * Logical paths stored as a single JSON column (`storage === 'json'`,
+   * non-ignored descriptors). Retained after build — unlike the build-time
+   * `jsonFields` set — so the path guard can classify JSON descendants on
+   * relational adapters. Empty on nested-object adapters (they keep native
+   * dotted paths as descriptors).
    */
-  protected applyFromStorageFormatters(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  jsonParents: ReadonlySet<string>;
   /**
-   * Sets a value at a dot-notation path, creating intermediate objects as needed.
+   * Logical paths holding a JSON value (`isJsonValueField`: JSON-stored, `json`
+   * or `array` design type; non-ignored, nav-free descriptors) — a timestamp
+   * beneath one is never a calendar-bucket source (`jsonValueAncestor`).
    */
-  protected setNestedValue(obj: Record<string, unknown>, dotPath: string, value: unknown): void;
+  jsonValueParents: ReadonlySet<string>;
+  /** Every field descriptor's `physicalName` — reserved names a bucket alias may not take. */
+  physicalNames: ReadonlySet<string>;
+  private _built;
+  private _identifications?;
+  private _collateMap;
+  private _columnFromMap;
+  constructor(nestedObjects: boolean);
+  get isBuilt(): boolean;
   /**
-   * If all children of a flattened parent are null, collapse the parent to null.
+   * Logical field path → its physical path in document storage (nested
+   * objects kept inline). `@db.column` renames apply to the annotated key,
+   * and a document renames the TOP-LEVEL key only — nested keys are stored
+   * as-is — so a dotted path under a renamed top-level object renames its
+   * first segment: `profile.bio` under `@db.column 'prof'` → `prof.bio`.
    */
-  protected reconstructNullParent(obj: Record<string, unknown>, parentPath: string, meta: TableMetadata): void;
+  documentPath(path: string): string;
   /**
-   * Applies adapter-specific value formatting to a single filter value.
-   * Handles direct values, operator objects ({$gt: v}), and $in/$nin arrays.
+   * Runs the full metadata compilation pipeline. Called once by
+   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
+   *
+   * Pipeline steps:
+   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
+   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
+   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
+   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
+   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
+   * 6. Build field descriptors (TDbFieldMeta[])
+   * 7. Build leaf field indexes (skipped for nested-objects adapters)
+   * 8. Finalize indexes (resolve field names to physical)
+   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
+   * 10. Build allPhysicalFields list
    */
-  protected formatFilterValue(physicalName: string, value: unknown, meta: TableMetadata): unknown;
+  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
   /**
-   * Applies adapter-specific value formatting to prepared (physical-named) data.
+   * Applies adapter-provided metadata overrides atomically.
+   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
    */
-  protected formatWriteValues(data: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  private _applyOverrides;
   /**
-   * Prepares primary key values and strips ignored fields.
-   * Shared pre-processing for both document and relational write paths.
+   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
    */
-  protected prepareCommon(data: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): void;
-}
-/**
- * Field mapper for document-oriented adapters (e.g. MongoDB).
- * Nested objects are preserved as-is. Only applies column renames and
- * value coercion.
- */
-declare class DocumentFieldMapper extends FieldMappingStrategy {
-  reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
-  translateQuery(query: Uniquery, meta: TableMetadata): DbQuery;
-  translateAggregateQuery(query: AggregateQuery, meta: TableMetadata): DbQuery;
-  prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
-  translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
-}
-//#endregion
-//#region src/encryption.d.ts
-/**
- * Configuration for field-level encryption at rest (`@db.encrypted`).
- * Passed to `DbSpace` via the options bag.
- */
-interface TDbEncryptionOptions {
-  /** Key used for all new writes. */
-  defaultKeyId: string;
+  private _scanGenericAnnotations;
   /**
-   * Key registry: keyId → 32-byte key (Buffer, or base64/hex/utf8 string).
-   * Decryption looks keys up by the keyId recorded in each value's envelope,
-   * so old keys stay in the registry for as long as data encrypted with them exists.
+   * Build-time diagnostics for `@db.encrypted` (§6 of the field-encryption
+   * spec). Mirrors the compile-time AnnotationSpec validation so models built
+   * from pre-compiled types still fail fast.
    */
-  keys?: Record<string, string | Buffer>;
+  private _validateEncryptedField;
+  /** Build-time diagnostics for `@db.index.geo` (§3 of the geo-index spec). */
+  private _validateGeoIndexField;
+  private _addIndexField;
   /**
-   * Alternative/supplement to `keys`: async resolver (KMS, Vault, env indirection).
-   * Called once per keyId, result cached for the process lifetime.
+   * Classifies each field as column, flattened, json, or parent-object.
+   * Builds the bidirectional pathToPhysical / physicalToPath maps.
    */
-  resolveKey?: (keyId: string) => Promise<string | Buffer> | string | Buffer;
+  private _classifyFields;
+  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
+  private _flattenedPrefix;
+  /** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
   /**
-   * What to do when a stored value is NOT a valid envelope (pre-existing
-   * plaintext rows, e.g. when @db.encrypted is added to a live column).
-   *  - 'error' (default): fail the read with DbError("ENC_NOT_ENCRYPTED")
-   *  - 'passthrough': return the raw value as-is (migration window mode);
-   *    the value gets encrypted on its next write.
+   * Indexes non-ignored descriptors by logical path and retains the JSON-parent
+   * sets (plus every descriptor's physical name). Navigation relations and their descendants are skipped even when the
+   * adapter keeps them as descriptors (nested-object adapters do) — they are
+   * loaded with `$with`, never addressed as columns of this table.
    */
-  onUnencrypted?: "error" | "passthrough";
-}
-/** Decryption context — carried into error messages (never the key itself). */
-interface TDecryptContext {
-  table?: string;
-  field?: string;
-}
-/**
- * AES-256-GCM envelope encryption service for `@db.encrypted` fields.
- *
- * Owned by `DbSpace` and shared across all tables in the space. Values are
- * `JSON.stringify`'d before encryption (type-exact round-trips) and stored as
- * a single ASCII envelope string: `aes1$<keyId>$<iv>$<tag>$<ciphertext>`.
- *
- * Key material is validated eagerly at construction (`ENC_KEY_INVALID`);
- * `resolveKey` lookups are cached per keyId for the process lifetime.
- */
-declare class DbEncryption {
-  readonly defaultKeyId: string;
-  readonly onUnencrypted: "error" | "passthrough";
-  private readonly _keys;
-  private readonly _resolveKey?;
-  private readonly _resolved;
-  constructor(options: TDbEncryptionOptions);
-  /** True when `value` looks like an encryption envelope produced by this service. */
-  isEnvelope(value: unknown): value is string;
-  /** Encrypts a JSON-serializable value into an envelope string using the default key. */
-  encrypt(value: unknown): Promise<string>;
-  /** Decrypts an envelope string back into its plaintext value. */
-  decrypt(envelope: string, ctx?: TDecryptContext): Promise<unknown>;
-  private _decryptFailed;
-  private _getKey;
-}
-//#endregion
-//#region src/table/db-readable.d.ts
-/**
- * Extracts nav prop names from a query's `$with` array.
- * Returns `never` when `$with` is absent → all nav props stripped from response.
- */
-type ExtractWith<Q> = Q extends {
-  controls: {
-    $with: Array<{
-      name: infer N extends string;
-    }>;
-  };
-} ? N : never;
-/**
- * Computes the response type for a query:
- * - Strips all nav props from the base DataType
- * - Adds back only the nav props requested via `$with`
- *
- * When no `$with` is provided, result is `Omit<DataType, keyof NavType>`.
- * When `$with: [{ name: 'author' }]`, result includes `author` from DataType.
- * When the query type is not a literal (e.g. a variable typed as `Uniquery`),
- * falls back to `DataType` (all nav props optional, as declared).
- */
-type DbResponse<Data, Nav, Q> = [keyof Nav] extends [never] ? Data : string extends keyof Nav ? Data : Omit<Data, keyof Nav & string> & Pick<Data, ExtractWith<Q> & keyof Data & string>;
-/**
- * Resolves the design type from an annotated type.
- * Encapsulates the `kind === ''` check and fallback logic that
- * otherwise trips up every adapter author.
- *
- * For union types (e.g., from flattened `{...} | {...}` objects):
- * - If all members resolve to the same type → returns that type (strong type)
- * - If members disagree → returns `'union'` (out of scope for type management)
- */
-declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
-/**
- * Shared read-only database abstraction driven by Atscript annotations.
- *
- * Contains all field metadata computation, read operations, query translation,
- * relation loading, and result reconstruction. Extended by both
- * {@link AtscriptDbTable} (adds write operations) and {@link AtscriptDbView}
- * (adds view plan/DDL).
- */
-declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, _FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> {
-  protected readonly _type: T;
-  protected readonly adapter: A;
-  protected readonly logger: TGenericLogger;
-  protected readonly _tableResolver?: TTableResolver | undefined;
-  /** Resolved table/collection/view name. */
-  readonly tableName: string;
-  /** Database schema/namespace from `@db.schema` (if set). */
-  readonly schema: string | undefined;
-  /** Sync method from `@db.sync.method` ('drop' | 'recreate' | undefined). */
-  protected readonly _syncMethod: "drop" | "recreate" | undefined;
-  /** Previous table/view name from `@db.table.renamed` or `@db.view.renamed`. */
-  readonly renamedFrom: string | undefined;
-  /** Computed metadata for this table/view. Built lazily on first access. */
-  protected readonly _meta: TableMetadata;
-  /** Strategy for mapping between logical field shapes and physical storage. */
-  protected readonly _fieldMapper: FieldMappingStrategy;
-  protected _writeTableResolver?: TWriteTableResolver;
-  /** Encryption service for `@db.encrypted` fields — set by `DbSpace` from its options. */
-  protected _encryption?: DbEncryption;
-  private _metaIdPhysical;
-  constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
+  private _buildGuardIndexes;
   /**
-   * Sets the encryption service used for `@db.encrypted` fields.
-   * Called by `DbSpace` after table/view creation when the space was
-   * configured with an `encryption` options block.
+   * Indexes `fieldDescriptors` into two lookup maps for unified
+   * read/write field classification in the RelationalFieldMapper.
    */
-  setEncryption(encryption: DbEncryption | undefined): void;
-  /** Ensures metadata is built. Called before any metadata access. */
-  protected _ensureBuilt(): void;
+  private _buildLeafIndexes;
   /**
-   * Built table metadata. Triggers a lazy build on first access — safe to call
-   * from peer tables that need this one's relations / nav fields before any
-   * operation has run against it directly.
+   * Builds field descriptors, physical-name lookup, and value formatters.
+   * Called once during build() — everything it needs
+   * (flatMap, indexes, columnMap, etc.) is already populated.
    */
-  getMetadata(): TableMetadata;
-  protected _ensureSearchable(): void;
-  /** Engine-agnostic query-time guards (encrypted-field refs, $geoWithin shape). */
-  protected _guardQuery(query: Uniquery | undefined): void;
-  private _encryptedPathsCache?;
-  /** Pre-split `encryptedFields` paths — computed once, reused on every read/write. */
-  protected get _encryptedPaths(): Array<{
-    path: string;
-    segments: string[];
-    leaf: string;
-  }>;
+  private _buildFieldDescriptors;
   /**
-   * Walks all but the last of `segments` down from `root`, returning the
-   * object holding the leaf — or `undefined` when the path is unreachable
-   * (a missing, non-object, or array step). With `cloneParents`, every
-   * traversed object is shallow-cloned and re-linked so caller-shared
-   * nested objects are never mutated.
+   * Resolves `fkTargetField` for FK fields in field descriptors.
    */
-  protected _walkToLeafParent(root: Record<string, unknown>, segments: string[], cloneParents: boolean): Record<string, unknown> | undefined;
+  private _resolveFkTargetFields;
+  private _finalizeIndexes;
   /**
-   * Decrypts `@db.encrypted` fields on reconstructed rows (in place).
-   * Non-envelope stored values follow the configured `onUnencrypted` policy.
+   * Captures legitimate row-identifier shapes from the metadata: primary key
+   * (when present) followed by every unique index. Must run BEFORE
+   * `_finalizeIndexes` rewrites `index.fields[i].name` from logical to
+   * physical, so the field lists stay logical.
+   *
+   * Sources:
+   * - `this.primaryKeys` — composite-aware PK (one identification covering
+   *   the PK columns).
+   * - `this.indexes` — user-declared `@db.index.unique` (single or compound).
+   * - `this.uniqueProps` — single-field uniques contributed by adapter
+   *   overrides (`addUniqueFields`); these aren't reflected in
+   *   `this.indexes` but still legitimate addressing identifications.
+   *   Deduped against any single-field unique index already captured.
    */
-  protected _decryptRows(rows: Array<Record<string, unknown>>): Promise<void>;
-  /** Whether this readable is a view (overridden in AtscriptDbView). */
-  get isView(): boolean;
-  /** Returns the underlying adapter with its concrete type preserved. */
-  getAdapter(): A;
-  /** The raw annotated type. */
-  get type(): TAtscriptAnnotatedType<TAtscriptTypeObject>;
-  /** Lazily-built flat map of all fields (dot-notation paths → annotated types). */
-  get flatMap(): Map<string, TAtscriptAnnotatedType>;
-  /** All computed indexes from `@db.index.*` annotations. */
-  get indexes(): Map<string, TDbIndex>;
-  /** Primary key field names from `@meta.id`. */
-  get primaryKeys(): readonly string[];
-  /** Preferred row identifier field names. Defaults to primary keys. */
-  get preferredId(): readonly string[];
-  /** Legitimate row-identifier shapes (primary key + every unique index). */
-  get identifications(): readonly TIdentification[];
+  private _buildIdentifications;
+  /** Legitimate row-identifier shapes — primary key first, then each unique index. */
+  getIdentifications(): readonly TIdentification[];
+  private _resolvePreferredId;
+}
+//#endregion
+//#region src/types.d.ts
+/** Controls with resolved projection. Used in the adapter interface. */
+interface DbControls extends Omit<UniqueryControls, "$select"> {
+  $select?: UniquSelect;
+}
+/** Query object with resolved projection. Passed to adapter methods. */
+interface DbQuery {
+  filter: FilterExpr;
+  controls: DbControls;
+  /** Pre-computed query insights (field → operators). Adapters may use this to apply query-time behaviour (e.g. collation). */
+  insights?: UniqueryInsights;
+}
+/** Describes an available search index exposed by a database adapter. */
+interface TSearchIndexInfo {
+  /** Index name. Empty string or 'DEFAULT' for the default index. */
+  name: string;
+  /** Human-readable label for UI display. */
+  description?: string;
+  /** Index type: text search or vector similarity search. */
+  type?: "text" | "vector";
+}
+/** Relation summary in a meta response. */
+interface TRelationInfo {
+  name: string;
+  direction: "to" | "from" | "via";
+  isArray: boolean;
+}
+/** Per-field capability flags in a meta response. */
+interface TFieldMeta {
+  sortable: boolean;
+  filterable: boolean;
   /**
-   * Physical column name of the single `@meta.id` field, or `null` when the
-   * schema has zero or multiple `@meta.id` fields. Used by adapters to return
-   * the user's logical ID instead of the DB-generated one on insert.
-   *
-   * @internal Adapter-facing surface; not part of the consumer API.
+   * Present only when `filterable` is `false` but narrower predicates still
+   * pass the gate: their operators — `$exists` on a relational adapter's JSON
+   * / array column, `$geoWithin` on a geoPoint of a geo-searchable adapter.
+   * Since 0.1.132.
    */
-  get metaIdPhysical(): string | null;
+  filterOps?: string[];
+  /** Present (true) when the field is `@db.encrypted` — stored as ciphertext at rest. */
+  encrypted?: boolean;
+  /** Present (true) when the field carries a `@db.index.geo` geospatial index. */
+  geo?: boolean;
   /**
-   * Physical column name of the field annotated with `@db.column.version`, or
-   * `undefined` when the table has no version column. Used by adapters and the
-   * REST integration to drive optimistic concurrency control (OCC).
+   * Present (true) when the field is write-only over HTTP (`@db.writeOnly` or
+   * stamped by a permission overlay): settable in write payloads, never
+   * present in read responses. UIs render it as a set-only input.
    */
-  get versionColumn(): string | undefined;
-  /** Dimension fields from `@db.column.dimension`. */
-  get dimensions(): readonly string[];
-  /** Measure fields from `@db.column.measure`. */
-  get measures(): readonly string[];
-  /** Sync method for structural changes: 'drop' (lossy), 'recreate' (lossless), or undefined (manual). */
-  get syncMethod(): "drop" | "recreate" | undefined;
-  /** Logical → physical column name mapping from `@db.column`. */
-  get columnMap(): ReadonlyMap<string, string>;
-  /** Default values from `@db.default.*`. */
-  get defaults(): ReadonlyMap<string, TDbDefaultValue>;
-  /** Fields excluded from DB via `@db.ignore`. */
-  get ignoredFields(): ReadonlySet<string>;
-  /** Navigational fields (`@db.rel.to` / `@db.rel.from`) — not stored as columns. */
-  get navFields(): ReadonlySet<string>;
-  /** Physical field names used to invert exclude-mode `$select` into a SELECT list. */
-  get allPhysicalFields(): readonly string[];
-  /** Single-field unique index properties. */
-  get uniqueProps(): ReadonlySet<string>;
-  /** Foreign key constraints from `@db.rel.FK` annotations. */
-  get foreignKeys(): ReadonlyMap<string, TDbForeignKey>;
-  /** Navigational relation metadata from `@db.rel.to` / `@db.rel.from`. */
-  get relations(): ReadonlyMap<string, TDbRelation>;
-  /** The underlying database adapter instance. */
-  get dbAdapter(): A;
+  writeOnly?: boolean;
   /**
-   * Enables or disables verbose (debug-level) DB call logging for this table/view.
-   * When disabled (default), no log strings are constructed — zero overhead.
+   * Present (true) when the field is index-backed (explicit `@db.index*`,
+   * primary key or unique field). Advisory only — a hint for UIs that want to
+   * steer users toward cheap sort keys; it never affects whether a `$sort`
+   * is accepted (`sortable` does). Since 0.1.128.
    */
-  setVerbose(enabled: boolean): void;
-  /** Precomputed logical dot-path → physical column name map. */
-  get pathToPhysical(): ReadonlyMap<string, string>;
-  /** Precomputed physical column name → logical dot-path map (inverse). */
-  get physicalToPath(): ReadonlyMap<string, string>;
-  /** Descriptor for the primary ID field(s). */
-  getIdDescriptor(): TIdDescriptor;
+  indexed?: boolean;
   /**
-   * Pre-computed field metadata for adapter use.
+   * Present (true) exactly when a calendar bucket over this field passes the
+   * gate: a physically filterable `number.timestamp` field (a dimension, when
+   * the table declares dimensions) on an adapter with calendar buckets
+   * (`bucketUnits`). Since 0.1.132.
    */
-  get fieldDescriptors(): readonly TDbFieldMeta[];
+  bucketable?: true;
+}
+/** Built-in CRUD operation names; map 1:1 to public method names. */
+type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
+/**
+ * CRUD permissions advertised in `/meta`. Key absent → operation is denied or
+ * not exposed. Key present → operation is allowed; the `string[]` value is the
+ * accepted UniQuery control whitelist for read ops (`[]` for write ops, which
+ * take no controls — presence still signals "allowed").
+ */
+type TCrudPermissions = Partial<Record<TCrudOp, string[]>>;
+/** Response payload for `GET /meta`. */
+interface TMetaResponse {
+  searchable: boolean;
+  vectorSearchable: boolean;
+  /** Whether the adapter supports `geoSearch()` AND the table declares a geo index. */
+  geoSearchable?: boolean;
+  searchIndexes: TSearchIndexInfo[];
+  primaryKeys: string[];
+  preferredId: string[];
+  relations: TRelationInfo[];
+  fields: Record<string, TFieldMeta>;
+  type: TSerializedAnnotatedType;
+  actions: TDbActionInfo[];
+  crud: TCrudPermissions;
   /**
-   * Resolves whether `path` references a real field — directly via `flatMap`
-   * or transitively through a nav relation by recursing into the target
-   * 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.
+   * Physical column name annotated with `@db.column.version`, when the table
+   * opts into optimistic concurrency control (OCC). Absent for tables without
+   * the annotation, i.e. last-write-wins (default) behavior.
+   */
+  versionColumn?: string;
+  /**
+   * Calendar-bucket units the adapter can group by (`{ $bucket }` in an
+   * aggregate `$select`, URL `bucket(field,unit,…)`); omitted when it has
+   * none. Since 0.1.132.
+   */
+  bucketUnits?: BucketUnit[];
+}
+/** Where the action applies on the UI. */
+type TDbActionLevel = "table" | "row" | "rows";
+/**
+ * Semantic intent the UI maps to its own visual language (color, prominence).
+ *
+ * Suggested visual prominence (most → least): `negative` > `warning` > `primary`
+ * > `positive` > `secondary`. Use `negative` for destructive ops (delete, purge),
+ * `warning` for risky-but-non-destructive ops (retry payment, force recompute,
+ * reset state), `primary` for the headline action, `positive` for benign
+ * confirmations (approve, publish), `secondary` for everything else.
+ */
+type TDbActionIntent = "positive" | "negative" | "warning" | "primary" | "secondary";
+/** How the UI client should handle the action when invoked. */
+type TDbActionProcessor = "backend" | "navigate" | "custom";
+/**
+ * Single action descriptor in the `/meta` envelope. Flat shape — `processor`
+ * is a string discriminator; `value` is its sibling and is always populated.
+ *
+ * - `processor: 'backend'` — UI POSTs to `value` (full HTTP path).
+ * - `processor: 'navigate'` — UI routes to `value` (URL template; `$1` is the row PK).
+ * - `processor: 'custom'`  — UI dispatches `value` as an event name (defaults to action `name`).
+ */
+interface TDbActionInfo {
+  name: string;
+  label: string;
+  level: TDbActionLevel;
+  processor: TDbActionProcessor;
+  value: string;
+  icon?: string;
+  intent?: TDbActionIntent;
+  description?: string;
+  order?: number;
+  default?: boolean;
+  /**
+   * Confirmation prompt copy. String form is shown verbatim. Tuple form is
+   * `[singular, plural]`: the UI picks `[0]` when the action will execute
+   * against a single PK (always for `'row'`-level; for `'rows'`-level when the
+   * current selection has exactly one PK) and `[1]` otherwise.
    *
-   * Cycle-safe via a visited set keyed on `<tableName>:<navField>`.
+   * Placeholder substitution is UI-resolved, not server-parsed. Conventional
+   * placeholders: `$1` for the single PK (singular form) and `$N` for the
+   * count (plural form), e.g. `['Delete order $1?', 'Delete $N orders?']`.
    */
-  isValidFieldPath(path: string, _visited?: Set<string>): boolean;
+  promptText?: string | [string, string];
   /**
-   * Creates a new validator with custom options.
+   * Single-character keyboard shortcut hint. The server stores this verbatim
+   * — choice of modifier prefix (Alt+, Ctrl+, bare key) and activation scope
+   * (e.g. only when an actions dropdown is open) are UI/UX concerns. Conflict
+   * resolution between actions sharing the same key is also up to the UI;
+   * the server does no dedup.
    */
-  createValidator(opts?: Partial<TValidatorOptions>): Validator<T, DataType>;
+  shortcut?: string;
   /**
-   * Finds a single record matching the query.
-   * The return type automatically excludes nav props unless they are
-   * explicitly requested via `$with`.
+   * Stringified gate predicate (`fn.toString()`). Present only for `'row'`
+   * and `'rows'` level actions whose decorator declared a `disabled` function.
+   * The function is the batch shape `(rows: TRow[]) => boolean[]` (sync). The
+   * UI evaluates against a level-specific scope to grey-out / hide the
+   * button. The server has already enforced this predicate before the
+   * action's handler ran — the server is authoritative; this field is purely
+   * a UI hint.
    */
-  findOne<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
+  disabled?: string;
   /**
-   * Finds all records matching the query.
-   * The return type automatically excludes nav props unless they are
-   * explicitly requested via `$with`.
+   * Name of the `.as` interface the action's `@InputForm()` parameter expects
+   * (the compiled class's `.name`). Present only when the handler declares an
+   * `@InputForm(FormType)` parameter. Clients fetch the serialized schema via
+   * `GET /meta/form/:name` on the same controller and render a form to
+   * collect the `input` field of the action's request envelope.
    */
-  findMany<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  inputForm?: string;
+}
+interface TDbInsertResult {
+  insertedId: unknown;
+}
+interface TDbInsertManyResult {
+  insertedCount: number;
+  insertedIds: unknown[];
+}
+interface TDbUpdateResult {
+  matchedCount: number;
+  modifiedCount: number;
+}
+interface TDbDeleteResult {
+  deletedCount: number;
+}
+type TDbIndexType = "plain" | "unique" | "fulltext" | "geo";
+interface TDbIndexField {
+  name: string;
+  sort: "asc" | "desc";
+  weight?: number;
   /**
-   * Counts records matching the query.
+   * Whether the indexed field is optional (declared `field?:` in the model).
+   * Resolved during index finalization. Adapters use this to make a unique
+   * index "present-only" so multiple value-less rows are tolerated — matching
+   * SQL's `NULLS DISTINCT` default. SQL adapters get this for free and ignore
+   * the flag; MongoDB needs it to emit a partial unique index.
    */
-  count(query?: Uniquery<OwnProps, NavType>): Promise<number>;
+  optional?: boolean;
+  /**
+   * Resolved design type of the field ('string', 'number', 'boolean', …).
+   * Carried alongside {@link optional} so adapters can derive a type-correct
+   * present-only filter (e.g. Mongo's `partialFilterExpression`) without
+   * re-resolving the field type. Undefined when the field cannot be resolved.
+   */
+  designType?: string;
+}
+interface TDbIndex {
+  /** Unique key used for identity/diffing (e.g., "atscript__plain__email") */
+  key: string;
+  /** Human-readable index name. */
+  name: string;
+  /** Index type. */
+  type: TDbIndexType;
+  /** Ordered list of fields in the index. */
+  fields: TDbIndexField[];
+}
+type TDbDefaultFn = "increment" | "uuid" | "now";
+type TDbCollation = "binary" | "nocase" | "unicode";
+type TDbDefaultValue = {
+  kind: "value";
+  value: string;
+} | {
+  kind: "fn";
+  fn: TDbDefaultFn;
+  start?: number;
+};
+interface TIdDescriptor {
+  /** Field names that form the primary key. */
+  fields: string[];
+  /** Whether this is a composite key (multiple fields). */
+  isComposite: boolean;
+}
+/** A legitimate row-identifier shape: primary key or a unique index. */
+interface TIdentification {
+  /** Logical (path) field names that form this identifier. */
+  fields: readonly string[];
+  /** `'primaryKey'` for the PK; the unique-index name otherwise. */
+  source: string;
+}
+type TDbStorageType = "column" | "flattened" | "json";
+interface TDbFieldMeta {
+  /** The dot-notation path to this field (logical name). */
+  path: string;
+  /** The annotated type for this field. */
+  type: TAtscriptAnnotatedType;
+  /** Physical column/field name (from @db.column, __-separated for flattened, or same as path). */
+  physicalName: string;
+  /** Resolved design type: 'string', 'number', 'boolean', 'object', 'json', etc. */
+  designType: string;
+  /** Whether the field is optional. */
+  optional: boolean;
+  /** Whether this field is part of the primary key (@meta.id). */
+  isPrimaryKey: boolean;
+  /** Whether this field is excluded from the DB (@db.ignore). */
+  ignored: boolean;
+  /** Default value from @db.default.* */
+  defaultValue?: TDbDefaultValue;
   /**
-   * Finds records and total count in a single logical call.
+   * How this field is stored in the database.
+   * - 'column': a standard scalar column (default for primitives)
+   * - 'flattened': a leaf scalar from a flattened nested object
+   * - 'json': stored as a single JSON column (arrays, @db.json fields)
    */
-  findManyWithCount<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<{
-    data: Array<DbResponse<DataType, NavType, Q>>;
-    count: number;
-  }>;
+  storage: TDbStorageType;
   /**
-   * Executes an aggregate query with GROUP BY and aggregate functions.
-   *
-   * Validates:
-   * - Plain fields in $select are a subset of $groupBy
-   * - When dimensions/measures are defined (strict mode): $groupBy fields
-   *   must be dimensions, aggregate $field values must be measures (or '*')
-   *
-   * Translates field names, delegates to adapter.aggregate(),
-   * then reverse-maps and applies fromStorage formatters on results.
+   * For flattened fields: the dot-notation path (same as `path`).
+   * E.g., for physicalName 'contact__email', this is 'contact.email'.
+   * Undefined for non-flattened fields.
    */
-  aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
-  /** 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;
-  /** Whether the adapter can sort by a given field (proxies adapter capability). */
-  canSortField(fd: TDbFieldMeta): boolean;
-  /** Returns available search indexes from the adapter. */
-  getSearchIndexes(): TSearchIndexInfo[];
+  flattenedFrom?: string;
+  /** Old physical column name from @db.column.renamed (for rename migration). */
+  renamedFrom?: string;
+  /** Collation from @db.column.collate (e.g. 'nocase', 'binary', 'unicode'). */
+  collate?: TDbCollation;
   /**
-   * Full-text search with query translation and result reconstruction.
+   * Whether this field is index-backed: it participates in an explicit index
+   * (@db.index.plain, @db.index.unique, @db.index.fulltext) OR is a primary key
+   * or unique field (which are always index-backed — Mongo `_id`, SQL PK/unique
+   * constraints — even without an explicit `@db.index*`).
    */
-  search<Q extends Uniquery<OwnProps, NavType>>(text: string, query: Q, indexName?: string): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  isIndexed?: boolean;
+  /** Literal currency code from `@db.amount.currency 'EUR'`. */
+  currencyCode?: string;
+  /** Sibling field path from `@db.amount.currency.ref 'fieldName'`. */
+  currencyRefField?: string;
+  /** Literal unit-of-measure from `@db.unit 'kg'`. */
+  unitCode?: string;
+  /** Sibling field path from `@db.unit.ref 'fieldName'`. */
+  unitRefField?: string;
   /**
-   * Full-text search with count for paginated search results.
+   * For FK fields: the resolved field metadata of the referenced (target) PK column.
+   * Adapters use this in `typeMapper` to produce matching DB types for FK columns
+   * (e.g., `typeMapper(field.fkTargetField)` to inherit the target PK's DB type).
+   * Undefined for non-FK fields or when the target cannot be resolved.
    */
-  searchWithCount<Q extends Uniquery<OwnProps, NavType>>(text: string, query: Q, indexName?: string): Promise<{
-    data: Array<DbResponse<DataType, NavType, Q>>;
-    count: number;
-  }>;
-  /** Whether the underlying adapter supports vector similarity search. */
-  isVectorSearchable(): boolean;
+  fkTargetField?: TDbFieldMeta;
   /**
-   * Vector similarity search with query translation and result reconstruction.
-   *
-   * Overloads:
-   * - `vectorSearch(vector, query?)` — uses default vector index
-   * - `vectorSearch(indexName, vector, query?)` — targets a specific vector index
+   * `@db.encrypted` — the value is AES-256-GCM encrypted by the core layer
+   * before reaching the adapter. Adapters must map the column to an unbounded
+   * text type and veto filtering/sorting (`canFilterField`/`canSortField`).
+   * The descriptor's `designType` is forced to `'string'` (ciphertext envelope);
+   * the declared type stays available via `type` for validation.
    */
-  vectorSearch<Q extends Uniquery<OwnProps, NavType>>(vectorOrIndex: number[] | string, maybeVectorOrQuery?: number[] | Q, maybeQuery?: Q): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  encrypted?: boolean;
   /**
-   * Vector similarity search with count for paginated results.
-   *
-   * Overloads:
-   * - `vectorSearchWithCount(vector, query?)` — uses default vector index
-   * - `vectorSearchWithCount(indexName, vector, query?)` — targets a specific vector index
+   * The field's declared type is the `db.geoPoint` primitive (`[lng, lat]` tuple).
+   * Adapters map this to their native geo storage (e.g. MongoDB GeoJSON Point).
    */
-  vectorSearchWithCount<Q extends Uniquery<OwnProps, NavType>>(vectorOrIndex: number[] | string, maybeVectorOrQuery?: number[] | Q, maybeQuery?: Q): Promise<{
-    data: Array<DbResponse<DataType, NavType, Q>>;
-    count: number;
+  isGeoPoint?: boolean;
+}
+interface TValueFormatterPair {
+  /** Converts a JS value to storage representation (write + filter paths). */
+  toStorage: (value: unknown) => unknown;
+  /** Converts a storage value back to JS representation (read path). */
+  fromStorage: (value: unknown) => unknown;
+}
+type TDbReferentialAction = "cascade" | "restrict" | "noAction" | "setNull" | "setDefault";
+interface TDbForeignKey {
+  /** FK field names on this table (local columns). */
+  fields: string[];
+  /** Target table name (from the chain ref's type @db.table annotation). */
+  targetTable: string;
+  /** Target field names on the referenced table. */
+  targetFields: string[];
+  /** Lazy reference to the target annotated type (for on-demand table resolution). */
+  targetTypeRef?: () => TAtscriptAnnotatedType;
+  /** Alias grouping FK fields (if any). */
+  alias?: string;
+  /** Referential action on delete. */
+  onDelete?: TDbReferentialAction;
+  /** Referential action on update. */
+  onUpdate?: TDbReferentialAction;
+}
+/** Describes an existing column in the database (from introspection). */
+interface TExistingColumn {
+  name: string;
+  type: string;
+  notnull: boolean;
+  pk: boolean;
+  /** Serialized default value (e.g., "'active'", "NULL"). */
+  dflt_value?: string;
+}
+/** Result of comparing desired schema against existing database columns. */
+interface TColumnDiff {
+  added: TDbFieldMeta[];
+  removed: TExistingColumn[];
+  renamed: Array<{
+    field: TDbFieldMeta;
+    oldName: string;
+  }>;
+  typeChanged: Array<{
+    field: TDbFieldMeta;
+    existingType: string;
+  }>;
+  nullableChanged: Array<{
+    field: TDbFieldMeta;
+    wasNullable: boolean;
+  }>;
+  defaultChanged: Array<{
+    field: TDbFieldMeta;
+    oldDefault?: string;
+    newDefault?: string;
+  }>;
+  conflicts: Array<{
+    field: TDbFieldMeta;
+    oldName: string;
+    conflictsWith: string;
   }>;
-  /** Resolves overloaded vector search arguments into canonical form. */
-  private _resolveVectorSearchArgs;
-  /** Whether the underlying adapter supports geospatial search. */
-  isGeoSearchable(): boolean;
   /**
-   * Distance-ranked geospatial search (mirrors {@link vectorSearch}).
-   * Results are sorted by distance ascending; each row carries a computed
-   * `$distance` field (meters from the query point). `$maxDistance` /
-   * `$minDistance` (meters) ride in `query.controls`; user `$sort` is rejected.
-   *
-   * Overloads:
-   * - `geoSearch(point, query?)` — uses the table's only geo index
-   * - `geoSearch(indexName, point, query?)` — targets a specific geo index
+   * The primary-key FIELD SET differs between the live table and the model
+   * (set semantics — a composite-key reorder is not a change, consistent with
+   * the schema hash). Column names are physical; a renamed PK column is
+   * compared under its new name. Only reported when the table exists.
+   * @since 0.1.128
    */
-  geoSearch<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<Array<DbResponse<DataType, NavType, Q> & {
-    $distance: number;
-  }>>;
+  primaryKeyChanged?: TPrimaryKeyChange;
+}
+/** Old and new primary-key column sets of a table whose key definition moved. */
+interface TPrimaryKeyChange {
+  /** Physical PK columns currently in the database (after rename mapping). */
+  from: string[];
+  /** Physical PK columns the model declares. */
+  to: string[];
+}
+/**
+ * A live foreign-key constraint as introspected from the database
+ * (outbound: declared on the table that owns it).
+ */
+interface TExistingForeignKey {
+  /** Local (referencing) columns, in constraint order. */
+  fields: string[];
+  /** Referenced table name. */
+  targetTable: string;
+  /** Referenced columns, in constraint order. */
+  targetFields: string[];
+}
+/**
+ * A live foreign key that REFERENCES a given table (inbound edge), as returned
+ * by `BaseDbAdapter.getReferencingForeignKeys(tableName)`.
+ */
+interface TReferencingForeignKey {
+  /** The referencing (child) table. */
+  table: string;
+  /** Referencing columns on `table`, in constraint order. */
+  fields: string[];
+  /** Referenced columns on the queried table, in constraint order. */
+  targetFields: string[];
+}
+/** Kind of a physical database object, as returned by `BaseDbAdapter.getObjectKind`. */
+type TDbObjectKind = "table" | "view" | "materialized";
+/** Options accepted by `BaseDbAdapter.ensureTable`. */
+interface TEnsureTableOptions {
   /**
-   * Distance-ranked geospatial search with count for paginated results.
-   *
-   * Overloads:
-   * - `geoSearchWithCount(point, query?)` — uses the table's only geo index
-   * - `geoSearchWithCount(indexName, point, query?)` — targets a specific geo index
+   * Table names whose inline FOREIGN KEY constraints must be omitted from
+   * CREATE TABLE — the constraints are added afterwards by `syncForeignKeys()`.
+   * Schema sync passes the members of a foreign-key cycle so they can be
+   * created in any order.
    */
-  geoSearchWithCount<Q extends Uniquery<OwnProps, NavType>>(pointOrIndex: [number, number] | string, maybePointOrQuery?: [number, number] | Q, maybeQuery?: Q): Promise<{
-    data: Array<DbResponse<DataType, NavType, Q> & {
-      $distance: number;
-    }>;
-    count: number;
+  deferForeignKeysTo?: ReadonlySet<string>;
+}
+/** Result of applying column diff to the database. */
+interface TSyncColumnResult {
+  added: string[];
+  renamed: string[];
+}
+/** A single table-level option in unified key-value format. */
+interface TExistingTableOption {
+  key: string;
+  value: string;
+}
+/** Result of comparing desired table options against existing ones. */
+interface TTableOptionDiff {
+  changed: Array<{
+    key: string;
+    oldValue: string;
+    newValue: string; /** Whether applying this change requires dropping and recreating the table. */
+    destructive: boolean;
+  }>;
+}
+/**
+ * Adapter-provided metadata adjustments applied atomically during the
+ * build pipeline, before field descriptors are built.
+ *
+ * Replaces the old pattern where adapters mutated metadata via
+ * back-references (`this._table.addPrimaryKey()`, etc.).
+ */
+interface TMetadataOverrides {
+  /** Fields to add as primary keys. */
+  addPrimaryKeys?: string[];
+  /** Fields to remove from primary keys. */
+  removePrimaryKeys?: string[];
+  /** Fields to register as having a unique constraint. */
+  addUniqueFields?: string[];
+  /** Synthetic fields to inject into flatMap (e.g. MongoDB's `_id`). */
+  injectFields?: Array<{
+    path: string;
+    type: TAtscriptAnnotatedType;
   }>;
-  /** Resolves overloaded geo search arguments into canonical form. */
-  private _resolveGeoSearchArgs;
-  /** Shared geoSearch validation + query translation. */
-  private _prepareGeoSearch;
-  /**
-   * Finds a single record by any type-compatible identifier — primary key
-   * or single-field unique index.
-   * The return type excludes nav props unless `$with` is provided in controls.
-   *
-   * ```typescript
-   * // Without relations — nav props stripped from result
-   * const user = await table.findById('123')
-   *
-   * // With relations — only requested nav props appear
-   * const user = await table.findById('123', { controls: { $with: [{ name: 'posts' }] } })
-   * ```
-   */
-  findById<Q extends {
-    controls?: UniqueryControls<OwnProps, NavType>;
-  } = Record<string, never>>(id: IdType, query?: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
-  /**
-   * Resolve an id value (scalar or object) into a {@link FilterExpr} using the
-   * same identification resolution as {@link findById}. Public so callers can
-   * AND-combine the id-filter with a row-level read overlay before issuing
-   * `findOne` (avoiding the existence leak that `findById` would cause).
-   */
-  resolveIdFilter(id: unknown): FilterExpr | null;
+}
+/**
+ * Callback that resolves an annotated type to a queryable table instance.
+ * Required for `$with` relation loading — each table needs to query related tables.
+ *
+ * Typically provided by the driver/registry (e.g. `DbSpace.getTable`).
+ */
+type TTableResolver = (type: TAtscriptAnnotatedType) => Pick<AtscriptDbTableLike, "findMany" | "loadRelations" | "primaryKeys" | "preferredId" | "relations" | "foreignKeys" | "isValidFieldPath"> | undefined;
+/** Minimal table interface used by the table resolver. Avoids circular dependency with AtscriptDbTable. */
+interface AtscriptDbTableLike {
+  findMany(query: unknown): Promise<Array<Record<string, unknown>>>;
+  loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[]): Promise<void>;
+  primaryKeys: readonly string[];
+  preferredId: readonly string[];
+  relations: ReadonlyMap<string, TDbRelation>;
+  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  getMetadata(): TableMetadata;
+  isValidFieldPath(path: string, visited?: Set<string>): boolean;
+}
+/** Minimal writable table interface for nested creation/update. */
+interface AtscriptDbWritable {
+  insertOne(payload: Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbInsertResult>;
+  insertMany(payloads: Array<Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+    _depth?: number;
+  }): Promise<TDbInsertManyResult>;
+  replaceOne(payload: Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbUpdateResult>;
+  bulkReplace(payloads: Array<Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+    _depth?: number;
+  }): Promise<TDbUpdateResult>;
+  updateOne(payload: Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbUpdateResult>;
+  bulkUpdate(payloads: Array<Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+    _depth?: number;
+  }): Promise<TDbUpdateResult>;
+  findOne(query: unknown): Promise<Record<string, unknown> | null>;
+  count(query: {
+    filter: Record<string, unknown>;
+  }): Promise<number>;
+  deleteMany(filter: unknown): Promise<TDbDeleteResult>;
+  /** Pre-validate items (type + FK constraints) without inserting them. */
+  preValidateItems(items: Array<Record<string, unknown>>, opts?: {
+    excludeFkTargetTable?: string;
+  }): Promise<void>;
+}
+/**
+ * Callback that resolves an annotated type to a writable table instance.
+ * Used for nested creation — inserting related records inline.
+ */
+type TWriteTableResolver = (type: TAtscriptAnnotatedType) => (AtscriptDbTableLike & AtscriptDbWritable) | undefined;
+/**
+ * A child table that may need cascade/setNull processing when a parent is deleted.
+ * Returned by the cascade resolver.
+ */
+interface TCascadeTarget {
+  /** FK on the child table that references the parent being deleted. */
+  fk: TDbForeignKey;
+  /** Name of the child table that holds this FK. */
+  childTable: string;
+  /** Delete matching child records (goes through AtscriptDbTable for recursive cascade). */
+  deleteMany(filter: Record<string, unknown>): Promise<TDbDeleteResult>;
+  /** Update matching child records (for setNull — sets FK fields to null). */
+  updateMany(filter: Record<string, unknown>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  /** Count matching child records (for restrict — check existence before delete). */
+  count(filter: Record<string, unknown>): Promise<number>;
+}
+/**
+ * Callback that finds all child tables with FKs pointing to a given parent table.
+ * Used by AtscriptDbTable to implement application-level cascade deletes.
+ */
+type TCascadeResolver = (tableName: string) => TCascadeTarget[];
+/**
+ * Minimal interface for querying a target table during FK validation.
+ * Only `count` is needed — we check if the referenced record exists.
+ */
+interface TFkLookupTarget {
+  count(filter: Record<string, unknown>): Promise<number>;
+}
+/**
+ * Callback that resolves a table name to a queryable target for FK validation.
+ * Returns undefined if the target table is not registered in the space.
+ */
+type TFkLookupResolver = (tableName: string) => TFkLookupTarget | undefined;
+interface TDbRelation {
+  /** Direction: 'to' (FK is local), 'from' (FK is remote), or 'via' (M:N junction). */
+  direction: "to" | "from" | "via";
+  /** The alias used for pairing (if any). */
+  alias?: string;
+  /** Target type's annotated type reference. */
+  targetType: () => TAtscriptAnnotatedType;
+  /** Whether this is an array relation (one-to-many). */
+  isArray: boolean;
+  /** Junction type reference for 'via' (M:N) relations. */
+  viaType?: () => TAtscriptAnnotatedType;
+}
+/**
+ * Write payload for insert / patch paths: every key optional, and optional
+ * columns additionally accept `null` (an explicit NULL — `undefined` means
+ * "absent" and is dropped before the row reaches defaults or validation).
+ */
+type DbPatch<D> = { [K in keyof D]?: undefined extends D[K] ? D[K] | null : D[K] } & Record<string, unknown>;
+/**
+ * Write payload for full-row replace paths: required keys stay required,
+ * optional columns additionally accept `null` (explicit NULL).
+ */
+type DbRow<D> = { [K in keyof D]: undefined extends D[K] ? D[K] | null : D[K] } & Record<string, unknown>;
+/** Built-in write actions a moost-db `AsDbController` endpoint performs. */
+type TDbWriteAction = "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany";
+/**
+ * Context handed to a write {@link TWriteOptions.guard} (since 0.1.128) — and
+ * through it to `AsDbController.guardWrite()`. The table invokes the guard
+ * exactly once, inside its own transaction, after `undefined`-pruning,
+ * defaults and validation and before encryption / nested-relation phases.
+ */
+interface TDbWriteGuardContext<Row = Record<string, unknown>> {
+  /** The table method the guard runs for (`insertOne` → `insert`, `insertMany` → `insertMany`, …). */
+  readonly action: TDbWriteAction;
   /**
-   * Resolve an id value into a filter expression.
-   *
-   * When `preferredId` differs from the PK, scalar ids resolve only against
-   * the preferred field (deterministic addressing). Otherwise scalars try PK
-   * + every single-field unique index; objects try PK + compound unique
-   * indexes.
+   * insert/replace: validated rows with SDK-side defaults applied (plaintext,
+   * nav data still attached); update: validated patches with the identifying
+   * PK/unique fields present and `$cas` removed. Mutate in place to enrich —
+   * the table re-validates the rows after the guard.
    */
-  protected _resolveIdFilter(id: unknown): FilterExpr | null;
-  /** Build a single-key filter from `idObj` over `fields`, or null if any field is missing/incompatible. */
-  private _tryCompoundFilter;
+  readonly rows: Row[];
+  /** Parallel to `rows`: expected version lifted from `$cas`, or `undefined`. */
+  readonly expectedVersions: ReadonlyArray<number | undefined>;
   /**
-   * Attempts to build a single-field filter `{ field: preparedId }`.
+   * Lazy, memoised pre-image of `rows[i]` by its identifying filter, read
+   * inside the transaction. `null` when the row is missing OR when it carries
+   * no identifying key yet (e.g. auto-increment inserts) — never throws.
    */
-  private _tryFieldFilter;
+  current(i: number): Promise<Row | null>;
+}
+/**
+ * Context handed to a delete {@link TDeleteOptions.guard} (since 0.1.128) —
+ * and through it to `AsDbController.guardRemove()`. Runs inside the table's
+ * transaction; an id that resolves to no filter never reaches the guard
+ * (`deleteOne` answers `{ deletedCount: 0 }`).
+ */
+interface TDbRemoveGuardContext<Row = Record<string, unknown>> {
+  /** The id `deleteOne` was called with. */
+  readonly id: unknown;
+  /** `table.resolveIdFilter(id)` — never null here. */
+  readonly filter: FilterExpr;
+  /** Lazy, memoised pre-image of the row about to be deleted (`null` when missing). */
+  current(): Promise<Row | null>;
+}
+/** A validated-stage write guard — see {@link TWriteOptions.guard}. */
+type TDbWriteGuard<Row = Record<string, unknown>> = (ctx: TDbWriteGuardContext<Row>) => void | Promise<void>;
+/** A validated-stage delete guard — see {@link TDeleteOptions.guard}. */
+type TDbRemoveGuard<Row = Record<string, unknown>> = (ctx: TDbRemoveGuardContext<Row>) => void | Promise<void>;
+/** Options of `AtscriptDbTable.touchMany` (since 0.1.129). */
+interface TTouchManyOptions {
   /**
-   * Public entry point for relation loading. Used by adapters for nested $with delegation.
+   * `'all'` (default): every key must match its stored version — a stale or
+   * missing row throws `DbError("CAS_MISMATCH")` and no version moves.
+   * `'any'`: bump whatever matches and report the honest counts.
    */
-  loadRelations(rows: Array<Record<string, unknown>>, withRelations: WithRelation[]): Promise<void>;
+  require?: "all" | "any";
+}
+/** Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`. */
+interface TWriteOptions<Row = Record<string, unknown>> {
+  /** Nested-relation write recursion limit (default 3). */
+  maxDepth?: number;
   /**
-   * Finds the FK entry that connects a `@db.rel.to` relation to its target.
-   * Thin wrapper — delegates to relation-loader for shared use with db-table.ts write path.
+   * Validated-stage guard (since 0.1.128): invoked exactly once inside the
+   * table's transaction, after defaults + validation and before encryption
+   * and nested-relation phases, with the rows the table is about to write.
+   * Rows may be enriched in place — they are validated again afterwards. A
+   * throw rolls the transaction back and propagates unchanged. Never runs
+   * for the nested re-entries a deep write performs on related tables.
    */
-  protected _findFKForRelation(relation: TDbRelation): {
-    localFields: string[];
-    targetFields: string[];
-  } | undefined;
+  guard?: TDbWriteGuard<Row>;
+}
+/** Options of `deleteOne`. */
+interface TDeleteOptions<Row = Record<string, unknown>> {
   /**
-   * Finds a FK on a remote table that points back to this table.
-   * Thin wrapper — delegates to relation-loader for shared use with db-table.ts write path.
+   * Validated-stage guard (since 0.1.128): invoked inside the table's
+   * transaction after the id resolved to a filter and before cascade /
+   * delete. A throw rolls the transaction back and propagates unchanged.
    */
-  protected _findRemoteFK(targetTable: {
-    foreignKeys: ReadonlyMap<string, TDbForeignKey>;
-  }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+  guard?: TDbRemoveGuard<Row>;
+}
+/**
+ * Adds `null` to every optional property of `O`. Optional columns store SQL
+ * NULL / Mongo null, and the runtime validator accepts `null` for optional
+ * props — so filter shapes (`{ note: null }`, `{ note: { $ne: null } }`) and
+ * row shapes must admit it at the type level too. Homomorphic: keys and
+ * required properties are unchanged; applying it twice is a no-op.
+ */
+type NullableOptional<O> = { [K in keyof O]: undefined extends O[K] ? O[K] | null : O[K] };
+//#endregion
+//#region src/query/buckets.d.ts
+/**
+ * A calendar bucket as adapters receive it (`controls.$select.buckets`): the
+ * normalized uniqu bucket (canonical zone, week start, alias) whose `field` is
+ * the PHYSICAL column / document path, plus the source field's descriptor —
+ * dialects read the storage kind from `fd` (since 0.1.132).
+ */
+type TResolvedBucket = ResolvedBucket & {
+  /** Physical column (relational) or document path (nested-object adapters). */field: string; /** Descriptor of the source field (a `number.timestamp` leaf). */
+  fd: TDbFieldMeta;
+};
+/**
+ * The names a bucket alias must not shadow: `TableMetadata` provides them, and
+ * moost-db's HTTP gate assembles the same set from its readable and capability
+ * index, so both layers resolve against the same names.
+ */
+interface TBucketFieldSource {
+  /** Every logical path of the table type (nested parents and navigation fields included). */
+  flatMap: ReadonlyMap<string, unknown>;
+  /** Every field descriptor's `physicalName` — reserved too. */
+  physicalNames: ReadonlySet<string>;
+  navFields: ReadonlySet<string>;
 }
+/**
+ * The one normalizer of `$select` computed entries (since 0.1.132) — uniqu's
+ * `resolveBuckets` (entry shapes, unit, time zone canonicalization, week
+ * start, alias syntax and uniqueness, "grouped queries only", "must also
+ * appear in $groupBy", string `$groupBy` entries) with the table's names as
+ * the collision set: a bucket alias may not equal a logical path, a physical
+ * column or a navigation field, so a label is never reverse-mapped as a
+ * column.
+ *
+ * Which layer validates what:
+ * - **Shapes** (this normalizer) run FIRST at every entry point — the core's
+ *   read path (`guardQuery`), its aggregate path (`AtscriptDbReadable.aggregate`,
+ *   which hands the result on to `guardAggregate` and the field mapper), and
+ *   moost-db's HTTP gate — so both layers answer with the same wording.
+ *   Everything downstream (`collectQueryPaths`, the field mappers,
+ *   `UniquSelect`, adapters) assumes normalized input and does not re-check.
+ * - **Schema** (timestamp-typed source, JSON ancestor, encryption, physical
+ *   filterability) is the path guard's (`guardPath` op `bucket`), mirrored by
+ *   moost-db's capability index; dimensions are the aggregate rules'.
+ * - **Adapter capability** (`calendarBucketUnits()`) is `guardAggregate`'s
+ *   (`BUCKET_NOT_SUPPORTED`); SQL builders only re-assert the inlined
+ *   literals (defense in depth).
+ *
+ * `aggregate` defaults to "`$groupBy` is non-empty".
+ *
+ * @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy`).
+ */
+declare function resolveCalendarBuckets(controls: {
+  $select?: unknown;
+  $groupBy?: unknown;
+} | undefined, fields: TBucketFieldSource, aggregate?: boolean): ResolvedBucket[];
+/**
+ * Whether a field can be the source of a calendar bucket: a `number` /
+ * `integer` leaf carrying the `timestamp` tag (`number.timestamp`,
+ * `.created`, `.updated`) that is not `@db.encrypted`. The type is the
+ * declaration — no annotation opts a field in. Physical filterability is the
+ * caller's (the core path guard and moost-db's capability index both add it).
+ */
+declare function isBucketableField(fd: TDbFieldMeta): boolean;
+/**
+ * Whether a field holds a JSON value — a `@db.json` object / JSON-stored
+ * column or an array. The members of `TableMetadata.jsonValueParents` (and
+ * moost-db's equivalent set) — see {@link jsonValueAncestor}.
+ */
+declare function isJsonValueField(fd: TDbFieldMeta): boolean;
+/**
+ * The outermost ancestor of `path` in `jsonValueParents` (the paths of the
+ * {@link isJsonValueField} descriptors), or `undefined`. A timestamp inside a
+ * JSON value is never a bucket source — relational adapters cannot address
+ * it and nested-object adapters (which can) must not diverge from them.
+ */
+declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbWriteAction as $, TCrudPermissions as A, findAncestorInSet as At, TDbForeignKey as B, NullableOptional as C, TWriteOptions as Ct, TCascadeTarget as D, UniqueryControls$1 as Dt, TCascadeResolver as E, Uniquery$1 as Et, TDbCollation as F, UniquSelect as Ft, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, isGeoPointType as Mt, TDbActionLevel as N, NoopLogger as Nt, TColumnDiff as O, WithRelation$1 as Ot, TDbActionProcessor as P, TGenericLogger as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TValueFormatterPair as St, PrimaryKeyOf$1 as T, TypedWithRelation as Tt, TDbIndexType as U, TDbIndex as V, TDbInsertManyResult as W, TDbRemoveGuardContext as X, TDbRemoveGuard as Y, TDbStorageType as Z, DbQuery as _, TSearchIndexInfo as _t, TDbEncryptionOptions as a, TExistingForeignKey as at, FilterExpr$1 as b, TTableResolver as bt, BaseDbAdapter as c, TFkLookupResolver as ct, AggregateFn as d, TIdentification as dt, TDbWriteGuard as et, AggregateQuery$1 as f, TMetaResponse as ft, DbPatch as g, TRelationInfo as gt, DbControls as h, TReferencingForeignKey as ht, DbEncryption as i, TExistingColumn as it, TDbActionInfo as j, isGeoIndexableType as jt, TCrudOp as k, TableMetadata as kt, AggregateControls as l, TFkLookupTarget as lt, AtscriptDbWritable as m, TPrimaryKeyChange as mt, DbResponse as n, TDeleteOptions as nt, DocumentFieldMapper as o, TExistingTableOption as ot, AggregateResult as p, TMetadataOverrides as pt, TDbReferentialAction as q, resolveDesignType as r, TEnsureTableOptions as rt, FieldMappingStrategy as s, TFieldMeta as st, AtscriptDbReadable as t, TDbWriteGuardContext as tt, AggregateExpr$1 as u, TIdDescriptor as ut, DbRow as v, TSyncColumnResult as vt, OwnPropsOf$1 as w, TWriteTableResolver as wt, FlatOf$1 as x, TTouchManyOptions as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };
+export { TDbWriteGuardContext as $, TDbActionIntent as A, isGeoPointType as At, TDbIndexField as B, NoopLogger as Bt, PrimaryKeyOf$1 as C, TypedWithRelation as Ct, TCrudOp as D, TableMetadata as Dt, TColumnDiff as E, WithRelation$1 as Et, TDbDefaultValue as F, resolveDesignType as Ft, TDbReferentialAction as G, TDbInsertManyResult as H, UniquSelect as Ht, TDbDeleteResult as I, DbEncryption as It, TDbRemoveGuardContext as J, TDbRelation as K, TDbFieldMeta as L, TDbEncryptionOptions as Lt, TDbActionProcessor as M, BaseDbAdapter as Mt, TDbCollation as N, AtscriptDbReadable as Nt, TCrudPermissions as O, findAncestorInSet as Ot, TDbDefaultFn as P, DbResponse as Pt, TDbWriteGuard as Q, TDbForeignKey as R, DocumentFieldMapper as Rt, OwnPropsOf$1 as S, TWriteTableResolver as St, TCascadeTarget as T, UniqueryControls$1 as Tt, TDbInsertResult as U, TDbIndexType as V, TGenericLogger as Vt, TDbObjectKind as W, TDbUpdateResult as X, TDbStorageType as Y, TDbWriteAction as Z, FieldOpsFor as _, TTableOptionDiff as _t, jsonValueAncestor as a, TFieldMeta as at, NavPropsOf$1 as b, TValueFormatterPair as bt, AggregateExpr$1 as c, TIdDescriptor as ct, AggregateResult as d, TMetadataOverrides as dt, TDeleteOptions as et, AtscriptDbWritable as f, TPrimaryKeyChange as ft, DbRow as g, TSyncColumnResult as gt, DbQuery as h, TSearchIndexInfo as ht, isJsonValueField as i, TExistingTableOption as it, TDbActionLevel as j, ALL_BUCKET_UNITS as jt, TDbActionInfo as k, isGeoIndexableType as kt, AggregateFn as l, TIdentification as lt, DbPatch as m, TRelationInfo as mt, TResolvedBucket as n, TExistingColumn as nt, resolveCalendarBuckets as o, TFkLookupResolver as ot, DbControls as p, TReferencingForeignKey as pt, TDbRemoveGuard as q, isBucketableField as r, TExistingForeignKey as rt, AggregateControls as s, TFkLookupTarget as st, TBucketFieldSource as t, TEnsureTableOptions as tt, AggregateQuery$1 as u, TMetaResponse as ut, FilterExpr$1 as v, TTableResolver as vt, TCascadeResolver as w, Uniquery$1 as wt, NullableOptional as x, TWriteOptions as xt, FlatOf$1 as y, TTouchManyOptions as yt, TDbIndex as z, FieldMappingStrategy as zt };