@atscript/db 0.1.39 → 0.1.40

package/dist/db-readable-BQQzfguJ.d.cts

@@ -0,0 +1,1249 @@
+import { u as TFieldOps } from "./ops-DXJ4Zw0P.cjs";
+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 { FlatOf, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+
+//#region src/query/uniqu-select.d.ts
+/**
+ * Wraps a raw `$select` value and provides lazy-cached conversions
+ * to the forms different adapters need.
+ *
+ * Only instantiated when `$select` is actually provided —
+ * `controls.$select` is `UniquSelect | undefined`.
+ *
+ * For exclusion → inclusion inversion, pass `allFields` (physical field names).
+ */
+declare class UniquSelect {
+  private static readonly UNRESOLVED;
+  private _raw;
+  private _allFields?;
+  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;
+  /**
+   * Resolved inclusion array of plain field names (strings only).
+   * AggregateExpr objects are filtered out.
+   * For exclusion form, inverts using `allFields` from constructor.
+   */
+  get asArray(): string[] | undefined;
+  /**
+   * Record projection preserving original semantics.
+   * Returns original object as-is if raw was object.
+   * Converts `string[]` to `{field: 1}` inclusion object.
+   * AggregateExpr objects in array form are ignored.
+   */
+  get asProjection(): Record<string, 0 | 1> | undefined;
+  /**
+   * Extracts AggregateExpr entries from array-form $select.
+   * Returns undefined if no aggregates present or if $select is object form.
+   */
+  get aggregates(): AggregateExpr[] | undefined;
+  /** Whether the $select contains any AggregateExpr entries. */
+  get hasAggregates(): boolean;
+}
+//#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";
+}
+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";
+interface TDbIndexField {
+  name: string;
+  sort: "asc" | "desc";
+  weight?: number;
+}
+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;
+}
+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;
+  /**
+   * 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)
+   */
+  storage: TDbStorageType;
+  /**
+   * 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.
+   */
+  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;
+  /** Whether this field participates in any index (@db.index.plain, @db.index.unique, @db.index.fulltext). */
+  isIndexed?: 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.
+   */
+  fkTargetField?: TDbFieldMeta;
+}
+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;
+  }>;
+}
+/** 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;
+  }>;
+}
+/**
+ * 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" | "relations" | "foreignKeys"> | 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[];
+  relations: ReadonlyMap<string, TDbRelation>;
+  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+}
+/** 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;
+}
+//#endregion
+//#region src/logger.d.ts
+interface TGenericLogger {
+  error(...messages: any[]): void;
+  warn(...messages: any[]): void;
+  log(...messages: any[]): void;
+  info(...messages: any[]): void;
+  debug(...messages: any[]): void;
+}
+declare const NoopLogger: TGenericLogger;
+//#endregion
+//#region src/table/table-metadata.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.
+ */
+declare class TableMetadata {
+  readonly nestedObjects: boolean;
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  fieldDescriptors: readonly TDbFieldMeta[];
+  primaryKeys: 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[];
+  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[];
+  requiresMappings: 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>;
+  private _built;
+  private _collateMap;
+  private _columnFromMap;
+  constructor(nestedObjects: boolean);
+  get isBuilt(): boolean;
+  /**
+   * 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
+   */
+  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
+  /**
+   * Applies adapter-provided metadata overrides atomically.
+   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
+   */
+  private _applyOverrides;
+  /**
+   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+   */
+  private _scanGenericAnnotations;
+  private _addIndexField;
+  /**
+   * Classifies each field as column, flattened, json, or parent-object.
+   * Builds the bidirectional pathToPhysical / physicalToPath maps.
+   */
+  private _classifyFields;
+  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
+  private _flattenedPrefix;
+  /**
+   * Indexes `fieldDescriptors` into two lookup maps for unified
+   * read/write field classification in the RelationalFieldMapper.
+   */
+  private _buildLeafIndexes;
+  /**
+   * Builds field descriptors, physical-name lookup, and value formatters.
+   * Called once during build() — everything it needs
+   * (flatMap, indexes, columnMap, etc.) is already populated.
+   */
+  private _buildFieldDescriptors;
+  /**
+   * Resolves `fkTargetField` for FK fields in field descriptors.
+   */
+  private _resolveFkTargetFields;
+  private _finalizeIndexes;
+}
+//#endregion
+//#region src/base-adapter.d.ts
+/**
+ * Abstract base class for database adapters.
+ *
+ * Adapter instances are 1:1 with readable instances (tables or views).
+ * When an {@link AtscriptDbReadable} is created with an adapter, it calls
+ * {@link registerReadable} to establish a bidirectional relationship:
+ *
+ * ```
+ * AtscriptDbReadable ──delegates ops──▶ BaseDbAdapter
+ *                    ◀──reads metadata── (via this._table)
+ * ```
+ *
+ * Adapter authors can access all computed metadata through `this._table`:
+ * - `this._table.tableName` — resolved table/collection/view name
+ * - `this._table.flatMap` — all fields as dot-notation paths
+ * - `this._table.indexes` — computed index definitions
+ * - `this._table.primaryKeys` — primary key field names
+ * - `this._table.columnMap` — logical → physical column mappings
+ * - `this._table.defaults` — default value configurations
+ * - `this._table.ignoredFields` — fields excluded from DB
+ * - `this._table.uniqueProps` — single-field unique index properties
+ * - `this._table.isView` — whether this is a view (vs a table)
+ */
+declare abstract class BaseDbAdapter {
+  protected _table: AtscriptDbReadable<any, any, any, any, any, any, any>;
+  private _metaIdPhysical;
+  /**
+   * Returns the physical column name of the single @meta.id field (if any).
+   * Used to return the user's logical ID instead of the DB-generated ID on insert.
+   */
+  protected _getMetaIdPhysical(): string | null;
+  /**
+   * Resolves the correct insertedId: prefers the user-supplied PK value
+   * from the data over the DB-generated fallback (e.g. rowid, _id).
+   */
+  protected _resolveInsertedId(data: Record<string, unknown>, dbGeneratedId: unknown): unknown;
+  /** Logger instance — set via {@link registerReadable} from the readable's logger. */
+  protected logger: TGenericLogger;
+  /** When true, adapter logs DB calls via `logger.debug`. Off by default. */
+  protected _verbose: boolean;
+  /**
+   * Called by {@link AtscriptDbReadable} constructor. Gives the adapter access
+   * to the readable's computed metadata for internal use in query rendering,
+   * index sync, etc.
+   */
+  registerReadable(readable: AtscriptDbReadable<any, any, any, any, any, any, any>, logger?: TGenericLogger): void;
+  /**
+   * Enables or disables verbose (debug-level) logging for this adapter.
+   * When disabled, no log strings are constructed — zero overhead.
+   */
+  setVerbose(enabled: boolean): void;
+  /**
+   * Logs a debug message if verbose mode is enabled.
+   * Adapters call this to log DB operations with zero overhead when disabled.
+   */
+  protected _log(...args: unknown[]): void;
+  /**
+   * Runs `fn` inside a database transaction. Nested calls (from related tables
+   * within the same async chain) reuse the existing transaction automatically.
+   *
+   * The generic layer handles nesting detection via `AsyncLocalStorage`.
+   * Adapters override `_beginTransaction`, `_commitTransaction`, and
+   * `_rollbackTransaction` to provide raw DB-specific transaction primitives.
+   */
+  withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Returns the opaque transaction state from the current async context.
+   * Adapters use this to retrieve DB-specific state (e.g., MongoDB `ClientSession`).
+   */
+  protected _getTransactionState(): unknown;
+  /**
+   * Runs `fn` inside the transaction ALS context with the given state.
+   * Adapters that override `withTransaction` (e.g., to use MongoDB's
+   * `session.withTransaction()` Convenient API) use this to set up the
+   * shared context so that nested adapters see the same session.
+   * If a context already exists (nesting), it's reused.
+   */
+  protected _runInTransactionContext<T>(state: unknown, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Starts a raw transaction. Returns opaque state stored in the async context.
+   * Override in adapters that support transactions.
+   */
+  protected _beginTransaction(): Promise<unknown>;
+  /** Commits the raw transaction. Override in adapters that support transactions. */
+  protected _commitTransaction(_state: unknown): Promise<void>;
+  /** Rolls back the raw transaction. Override in adapters that support transactions. */
+  protected _rollbackTransaction(_state: unknown): Promise<void>;
+  /**
+   * Returns additional validator plugins for this adapter.
+   * These are merged with the built-in Atscript validators.
+   *
+   * Example: MongoDB adapter returns ObjectId validation plugin.
+   */
+  getValidatorPlugins(): TValidatorPlugin[];
+  /**
+   * Transforms an ID value for the database.
+   * Override to convert string → ObjectId, parse numeric IDs, etc.
+   *
+   * @param id - The raw ID value.
+   * @param fieldType - The annotated type of the ID field.
+   * @returns The transformed ID value.
+   */
+  prepareId(id: unknown, _fieldType: TAtscriptAnnotatedType): unknown;
+  /**
+   * Whether this adapter supports native patch operations.
+   * When `true`, {@link AtscriptDbTable} delegates patch payloads to
+   * {@link nativePatch} instead of using the generic decomposition.
+   */
+  supportsNativePatch(): boolean;
+  /**
+   * Whether this adapter handles nested objects natively.
+   * When `true`, the generic layer skips flattening and
+   * passes nested objects as-is to the adapter.
+   * MongoDB returns `true`; relational adapters return `false` (default).
+   */
+  supportsNestedObjects(): boolean;
+  /**
+   * Whether the DB engine handles static `@db.default "value"` natively
+   * via column-level DEFAULT clauses in CREATE TABLE.
+   * When `true`, `_applyDefaults()` skips client-side value defaults,
+   * letting the DB apply its own DEFAULT. SQL adapters return `true`;
+   * document stores (MongoDB) return `false` and apply defaults client-side.
+   */
+  supportsNativeValueDefaults(): boolean;
+  /**
+   * Function default names handled natively by this adapter's DB engine.
+   * Fields with these defaults are omitted from INSERT when no value is provided,
+   * letting the DB apply its own DEFAULT expression (e.g. CURRENT_TIMESTAMP, UUID()).
+   *
+   * Override in adapters whose DB engine supports function defaults.
+   * The generic layer checks this in `_applyDefaults()` to decide whether
+   * to generate the value client-side or leave it for the DB.
+   */
+  nativeDefaultFns(): ReadonlySet<TDbDefaultFn>;
+  /**
+   * Whether this adapter enforces foreign key constraints natively.
+   * When `true`, the generic layer skips application-level cascade/setNull
+   * on delete — the DB engine handles it (e.g. SQLite `ON DELETE CASCADE`).
+   * When `false` (default), the generic layer implements cascade logic
+   * by finding child records and deleting/nullifying them before the parent.
+   */
+  supportsNativeForeignKeys(): boolean;
+  /**
+   * Whether this adapter handles `$with` relation loading natively.
+   * When `true`, the table layer delegates to {@link loadRelations}
+   * instead of using the generic batch-loading strategy.
+   *
+   * Adapters can use this to implement SQL JOINs, MongoDB `$lookup`,
+   * or other DB-native relation loading optimizations.
+   *
+   * Default: `false` — the table layer uses application-level batch loading.
+   */
+  supportsNativeRelations(): boolean;
+  /**
+   * Loads relations onto result rows using adapter-native operations.
+   * Only called when {@link supportsNativeRelations} returns `true`.
+   *
+   * The adapter receives the rows to enrich, the `$with` relation specs,
+   * and the table's relation/FK metadata for resolution.
+   *
+   * @param rows - The result rows to enrich (mutable — add relation properties in place).
+   * @param withRelations - The `$with` specs from the query.
+   * @param relations - This table's relation metadata (from `@db.rel.to`/`@db.rel.from`).
+   * @param foreignKeys - This table's FK metadata (from `@db.rel.FK`).
+   * @param tableResolver - Optional callback to resolve annotated types to table metadata (needed for FROM/VIA relations).
+   */
+  loadRelations(_rows: Array<Record<string, unknown>>, _withRelations: WithRelation[], _relations: ReadonlyMap<string, TDbRelation>, _foreignKeys: ReadonlyMap<string, TDbForeignKey>, _tableResolver?: TTableResolver): Promise<void>;
+  /**
+   * Applies a patch payload using native database operations.
+   * Only called when {@link supportsNativePatch} returns `true`.
+   *
+   * @param filter - Filter identifying the record to patch.
+   * @param patch - The patch payload with array operations.
+   * @returns Update result.
+   */
+  nativePatch(_filter: FilterExpr, _patch: unknown, _ops?: TFieldOps): Promise<TDbUpdateResult>;
+  /**
+   * Called before field flattening begins.
+   * Use to extract table-level adapter-specific annotations.
+   *
+   * Example: MongoDB adapter extracts `@db.mongo.search.dynamic`.
+   */
+  onBeforeFlatten?(type: TAtscriptAnnotatedType): void;
+  /**
+   * Called for each non-nav-descendant field during the build pipeline.
+   * Fields nested under navigation relations (`@db.rel.to/from/via`) are
+   * never delivered to this callback — adapters do not need to filter them.
+   *
+   * Use to extract field-level adapter-specific annotations.
+   * Example: MongoDB adapter extracts `@db.mongo.search.vector`, `@db.mongo.search.text`.
+   */
+  onFieldScanned?(field: string, type: TAtscriptAnnotatedType, metadata: TMetadataMap<AtscriptMetadata>): void;
+  /**
+   * Returns metadata overrides applied during the build pipeline.
+   * Called after field scanning/classification, before field descriptors are built.
+   *
+   * Use this to adjust primary keys, inject synthetic fields, or register
+   * unique constraints — instead of mutating metadata via back-references.
+   *
+   * @param meta - The table metadata (direct reference, not through readable getters).
+   */
+  getMetadataOverrides?(meta: TableMetadata): TMetadataOverrides | undefined;
+  /**
+   * Called after all fields are scanned.
+   * Use to finalize adapter-specific computed state.
+   * Access table metadata via `this._table`.
+   */
+  onAfterFlatten?(): void;
+  /**
+   * Returns an adapter-specific table name.
+   * For example, MongoDB reads from `@db.mongo.collection`.
+   * Return `undefined` to fall back to `@db.table` or the interface name.
+   */
+  getAdapterTableName?(type: TAtscriptAnnotatedType): string | undefined;
+  /**
+   * Returns the metadata tag used to mark top-level arrays during flattening.
+   * Default: `'db.__topLevelArray'`
+   *
+   * Override to use adapter-specific tags (e.g., `'db.mongo.__topLevelArray'`).
+   */
+  getTopLevelArrayTag?(): string;
+  /**
+   * Resolves the full table name, optionally including the schema prefix.
+   * Override for databases that don't support schemas (e.g., SQLite).
+   *
+   * @param includeSchema - Whether to prepend `schema.` prefix (default: true).
+   */
+  resolveTableName(includeSchema?: boolean): string;
+  /**
+   * Template method for index synchronization.
+   * Implements the diff algorithm (list → compare → create/drop).
+   * Adapters provide the three DB-specific primitives.
+   *
+   * @example
+   * ```typescript
+   * async syncIndexes() {
+   *   await this.syncIndexesWithDiff({
+   *     listExisting: async () => this.driver.all('PRAGMA index_list(...)'),
+   *     createIndex: async (index) => this.driver.exec('CREATE INDEX ...'),
+   *     dropIndex: async (name) => this.driver.exec('DROP INDEX ...'),
+   *     shouldSkipType: (type) => type === 'fulltext',
+   *   })
+   * }
+   * ```
+   */
+  protected syncIndexesWithDiff(opts: {
+    listExisting(): Promise<Array<{
+      name: string;
+    }>>;
+    createIndex(index: TDbIndex): Promise<void>;
+    dropIndex(name: string): Promise<void>;
+    prefix?: string;
+    shouldSkipType?(type: TDbIndex["type"]): boolean;
+  }): Promise<void>;
+  /**
+   * Returns available search indexes for this adapter.
+   * UI uses this to show index picker. Override in adapters that support search.
+   */
+  getSearchIndexes(): TSearchIndexInfo[];
+  /**
+   * Whether this adapter supports text search.
+   * Default: `true` when {@link getSearchIndexes} returns any entries.
+   */
+  isSearchable(): boolean;
+  /**
+   * Whether this adapter supports vector similarity search.
+   * Override in adapters that support vector search.
+   */
+  isVectorSearchable(): boolean;
+  /**
+   * Full-text search. Override in adapters that support search.
+   *
+   * @param text - Search text.
+   * @param query - Filter, sort, limit, etc.
+   * @param indexName - Optional search index to target.
+   */
+  search(_text: string, _query: DbQuery, _indexName?: string): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Full-text search with count (for paginated search results).
+   *
+   * @param text - Search text.
+   * @param query - Filter, sort, limit, etc.
+   * @param indexName - Optional search index to target.
+   */
+  searchWithCount(_text: string, _query: DbQuery, _indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  /**
+   * Vector similarity search. Override in adapters that support vector search.
+   *
+   * @param vector - Pre-computed embedding vector.
+   * @param query - Filter, sort, limit, etc.
+   * @param indexName - Optional vector index to target (for multi-vector documents).
+   */
+  vectorSearch(_vector: number[], _query: DbQuery, _indexName?: string): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Vector similarity search with count (for paginated results).
+   *
+   * @param vector - Pre-computed embedding vector.
+   * @param query - Filter, sort, limit, etc.
+   * @param indexName - Optional vector index to target (for multi-vector documents).
+   */
+  vectorSearchWithCount(_vector: number[], _query: DbQuery, _indexName?: string): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  /**
+   * Fetches records and total count in one call.
+   * Default: two parallel calls. Adapters may override for single-query optimization.
+   */
+  findManyWithCount(query: DbQuery): Promise<{
+    data: Array<Record<string, unknown>>;
+    count: number;
+  }>;
+  /**
+   * Executes an aggregate query (GROUP BY + aggregate functions).
+   * Default throws — override in adapters that support aggregation.
+   */
+  aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
+  abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  abstract deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
+  abstract findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
+  abstract findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  abstract count(query: DbQuery): Promise<number>;
+  abstract updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
+  abstract replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+  abstract deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  /**
+   * Synchronizes indexes between the Atscript definitions and the database.
+   * Uses `this._table.indexes` for the full index definitions.
+   */
+  abstract syncIndexes(): Promise<void>;
+  /**
+   * Ensures the table exists in the database, creating it if needed.
+   * Uses `this._table.tableName`, `this._table.schema`, etc.
+   */
+  abstract ensureTable(): Promise<void>;
+  /**
+   * Synchronizes foreign key constraints between Atscript definitions and the database.
+   * Uses `this._table.foreignKeys` for the full FK definitions.
+   * Optional — only relational adapters need to implement this.
+   */
+  /**
+   * Post-sync hook called after all table operations (columns, indexes, FKs)
+   * are complete. Adapters can use this for finalization work such as
+   * resetting auto-increment sequences to match existing data.
+   * Optional — most adapters don't need this.
+   */
+  afterSyncTable?(): Promise<void>;
+  syncForeignKeys?(): Promise<void>;
+  /**
+   * Drops FK constraints identified by their canonical local column key.
+   * Called by the sync executor before column operations to remove stale FKs
+   * that would otherwise block ALTER COLUMN.
+   *
+   * @param fkFieldKeys - Canonical FK keys (sorted local field names, comma-joined).
+   */
+  dropForeignKeys?(fkFieldKeys: string[]): Promise<void>;
+  /**
+   * Returns the desired table options from Atscript annotations.
+   * Called after onBeforeFlatten/onAfterFlatten, so adapter-specific state
+   * (e.g., engine, charset, capped options) is populated.
+   *
+   * Values are stringified for consistent comparison.
+   * Returns undefined if the adapter has no table-level options.
+   */
+  getDesiredTableOptions?(): TExistingTableOption[];
+  /**
+   * Returns the current table options from the live database.
+   * Primary source for option diffing (DB-first strategy).
+   *
+   * Returns undefined if the adapter cannot introspect table options.
+   * In that case, schema sync falls back to stored snapshot.
+   */
+  getExistingTableOptions?(): Promise<TExistingTableOption[]>;
+  /**
+   * Applies non-destructive table option changes (e.g., MySQL ALTER TABLE ENGINE=X).
+   * Called for each non-destructive change in the diff.
+   * Destructive changes go through dropTable+ensureTable or recreateTable.
+   */
+  applyTableOptions?(changes: TTableOptionDiff["changed"]): Promise<void>;
+  /**
+   * Returns the set of option keys where a value change requires table recreation.
+   * Default: empty (all changes are non-destructive).
+   */
+  destructiveOptionKeys?(): ReadonlySet<string>;
+  /**
+   * Checks whether the table/collection already exists in the database.
+   * Used by schema sync to determine create vs in-sync status for
+   * adapters that don't implement column introspection (e.g. MongoDB).
+   */
+  tableExists?(): Promise<boolean>;
+  /**
+   * Returns existing columns from the database via introspection.
+   * Used by schema sync for column diffing.
+   * Optional — schema-less adapters (MongoDB) skip this.
+   */
+  getExistingColumns?(): Promise<TExistingColumn[]>;
+  /**
+   * When true, the adapter can handle column type changes in-place
+   * (e.g. MySQL's ALTER TABLE MODIFY COLUMN) without requiring table recreation.
+   * The generic sync layer will delegate type changes to {@link syncColumns}
+   * instead of requiring `@db.sync.method "recreate"` or `"drop"`.
+   */
+  supportsColumnModify?: boolean;
+  /**
+   * Applies column diff (ALTER TABLE ADD COLUMN, etc.).
+   * The generic layer computes the diff; adapters execute DB-specific DDL.
+   * Optional — only relational adapters implement this.
+   */
+  syncColumns?(diff: TColumnDiff): Promise<TSyncColumnResult>;
+  /**
+   * Recreates the table losslessly: create temp → copy data → drop old → rename.
+   * Used by `@db.sync.method "recreate"` when structural changes can't be ALTER'd.
+   * Optional — only relational adapters implement this.
+   */
+  recreateTable?(): Promise<void>;
+  /**
+   * Drops the table entirely.
+   * Used by `@db.sync.method "drop"` for tables with ephemeral data.
+   * Optional — only relational adapters implement this.
+   */
+  dropTable?(): Promise<void>;
+  /**
+   * Drops one or more columns from the table.
+   * Used by schema sync to remove stale columns no longer in the schema.
+   * Optional — only relational adapters implement this.
+   */
+  dropColumns?(columns: string[]): Promise<void>;
+  /**
+   * Drops a table by name (without needing a registered readable).
+   * Used by schema sync to remove tables no longer in the schema.
+   * Optional — only relational adapters implement this.
+   */
+  dropTableByName?(tableName: string): Promise<void>;
+  /**
+   * Drops a view by name (without needing a registered readable).
+   * Used by schema sync to remove views no longer in the schema.
+   * Optional — only relational adapters implement this.
+   */
+  dropViewByName?(viewName: string): Promise<void>;
+  /**
+   * Renames a table/collection from `oldName` to the adapter's current table name.
+   * Used by schema sync when `@db.table.renamed` is present.
+   * Optional — only relational adapters implement this.
+   */
+  renameTable?(oldName: string): Promise<void>;
+  /**
+   * Introspects columns for an arbitrary table name (not the adapter's own table).
+   * Used by schema sync `plan()` to inspect a table under its old name before rename.
+   * Optional — only relational adapters implement this.
+   */
+  getExistingColumnsForTable?(tableName: string): Promise<TExistingColumn[]>;
+  /**
+   * Maps a field's metadata to the adapter's native column type string.
+   * Receives the full field descriptor (design type, annotations, PK status, etc.)
+   * so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
+   * Used by schema sync to detect column type changes.
+   * Optional — adapters that don't implement this skip type change detection.
+   */
+  typeMapper?(field: TDbFieldMeta): string;
+  /**
+   * Returns a value formatter for a field, or undefined if no formatting is needed.
+   * Called once per field during build. The returned formatter(s) are cached and
+   * applied during write preparation, filter translation, and read reconstruction.
+   *
+   * Can return:
+   * - A bare function: used as `toStorage` only (write + filter paths)
+   * - A `TValueFormatterPair`: `toStorage` for writes/filters, `fromStorage` for reads
+   * - `undefined`: no formatting needed
+   *
+   * This avoids per-value method dispatch — only fields that need formatting
+   * get a formatter function, and the generic layer skips fields without one.
+   *
+   * Example: MySQL returns a pair for TIMESTAMP-mapped fields (epoch ms ↔ datetime string).
+   */
+  formatValue?(field: TDbFieldMeta): TValueFormatterPair | ((value: unknown) => unknown) | undefined;
+}
+//#endregion
+//#region src/strategies/field-mapping.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).
+ */
+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 adapter-specific value
+   * formatting via `formatFilterValue`. Shared by both document and relational
+   * mappers (relational adds key-renaming via `translateFilterWithRename`).
+   */
+  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>;
+  /**
+   * Coerces field values from storage representation to JS types
+   * (booleans from 0/1, decimals from number to string).
+   */
+  protected coerceFieldValues(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  /**
+   * Applies adapter-specific fromStorage formatting to a row read from the database.
+   * Converts storage representations back to JS values (e.g. Date → epoch ms).
+   */
+  protected applyFromStorageFormatters(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  /**
+   * Sets a value at a dot-notation path, creating intermediate objects as needed.
+   */
+  protected setNestedValue(obj: Record<string, unknown>, dotPath: string, value: unknown): void;
+  /**
+   * If all children of a flattened parent are null, collapse the parent to null.
+   */
+  protected reconstructNullParent(obj: Record<string, unknown>, parentPath: string, meta: TableMetadata): void;
+  /**
+   * Applies adapter-specific value formatting to a single filter value.
+   * Handles direct values, operator objects ({$gt: v}), and $in/$nin arrays.
+   */
+  protected formatFilterValue(physicalName: string, value: unknown, meta: TableMetadata): unknown;
+  /**
+   * Applies adapter-specific value formatting to prepared (physical-named) data.
+   */
+  protected formatWriteValues(data: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  /**
+   * Prepares primary key values and strips ignored fields.
+   * Shared pre-processing for both document and relational write paths.
+   */
+  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/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 : 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 = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = 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;
+  constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
+  /** Ensures metadata is built. Called before any metadata access. */
+  protected _ensureBuilt(): 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[];
+  /** Original `@meta.id` field names as declared in the schema (before adapter manipulation). */
+  get originalMetaIdFields(): readonly string[];
+  /** 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>;
+  /** 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;
+  /**
+   * Enables or disables verbose (debug-level) DB call logging for this table/view.
+   * When disabled (default), no log strings are constructed — zero overhead.
+   */
+  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;
+  /**
+   * Pre-computed field metadata for adapter use.
+   */
+  get fieldDescriptors(): readonly TDbFieldMeta[];
+  /**
+   * Creates a new validator with custom options.
+   */
+  createValidator(opts?: Partial<TValidatorOptions>): Validator<T, DataType>;
+  /**
+   * Finds a single record matching the query.
+   * The return type automatically excludes nav props unless they are
+   * explicitly requested via `$with`.
+   */
+  findOne<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
+  /**
+   * Finds all records matching the query.
+   * The return type automatically excludes nav props unless they are
+   * explicitly requested via `$with`.
+   */
+  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;
+  }>;
+  /**
+   * 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.
+   */
+  aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
+  /** Whether the underlying adapter supports text search. */
+  isSearchable(): boolean;
+  /** Returns available search indexes from the adapter. */
+  getSearchIndexes(): TSearchIndexInfo[];
+  /**
+   * Full-text search with query translation and result reconstruction.
+   */
+  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;
+  }>;
+  /** 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;
+  }>;
+  /** Resolves overloaded vector search arguments into canonical form. */
+  private _resolveVectorSearchArgs;
+  /**
+   * 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>;
+  /**
+   * Resolves an id value into a filter expression.
+   */
+  protected _resolveIdFilter(id: unknown): FilterExpr | null;
+  /**
+   * Attempts to build a single-field filter `{ field: preparedId }`.
+   */
+  private _tryFieldFilter;
+  /**
+   * Public entry point for relation loading. Used by adapters for nested $with delegation.
+   */
+  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;
+}
+//#endregion
+export { Uniquery$1 as $, TDbForeignKey as A, TExistingColumn as B, TCascadeTarget as C, TDbDefaultValue as D, TDbDefaultFn as E, TDbInsertResult as F, TMetadataOverrides as G, TFkLookupResolver as H, TDbReferentialAction as I, TTableOptionDiff as J, TSearchIndexInfo as K, TDbRelation as L, TDbIndexField as M, TDbIndexType as N, TDbDeleteResult as O, TDbInsertManyResult as P, TypedWithRelation as Q, TDbStorageType as R, TCascadeResolver as S, TDbCollation as T, TFkLookupTarget as U, TExistingTableOption as V, TIdDescriptor as W, TValueFormatterPair as X, TTableResolver as Y, TWriteTableResolver as Z, DbQuery as _, FieldMappingStrategy as a, NavPropsOf$1 as b, NoopLogger as c, AggregateExpr$1 as d, UniqueryControls$1 as et, AggregateFn as f, DbControls as g, AtscriptDbWritable as h, DocumentFieldMapper as i, TDbIndex as j, TDbFieldMeta as k, TGenericLogger as l, AggregateResult as m, DbResponse as n, UniquSelect as nt, BaseDbAdapter as o, AggregateQuery$1 as p, TSyncColumnResult as q, resolveDesignType as r, TableMetadata as s, AtscriptDbReadable as t, WithRelation$1 as tt, AggregateControls as u, FieldOpsFor as v, TColumnDiff as w, OwnPropsOf$1 as x, FilterExpr$1 as y, TDbUpdateResult as z };