@atscript/db 0.1.39 → 0.1.41

package/dist/sync.d.ts

@@ -1,1878 +0,0 @@
-import { TAtscriptAnnotatedType, TAtscriptTypeObject, TAtscriptDataType, FlatOf, PrimaryKeyOf, OwnPropsOf, NavPropsOf, TValidatorOptions, Validator, TValidatorPlugin, TMetadataMap, AtscriptQueryNode, AtscriptQueryFieldRef } from '@atscript/typescript/utils';
-import { UniqueryControls, AggregateExpr, WithRelation, FilterExpr, UniqueryInsights, Uniquery, AggregateQuery } from '@uniqu/core';
-
-/**
- * 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;
-}
-
-/** 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;
-}
-
-interface TGenericLogger {
-    error(...messages: any[]): void;
-    warn(...messages: any[]): void;
-    log(...messages: any[]): void;
-    info(...messages: any[]): void;
-    debug(...messages: any[]): void;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-/**
- * 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>;
-/**
- * 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;
-}
-
-/**
- * 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): 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>): 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>): 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;
-}
-
-/**
- * Strategy for referential integrity enforcement.
- * Two implementations: {@link NativeIntegrity} (DB handles FK constraints)
- * and `ApplicationIntegrity` (generic layer validates + cascades).
- */
-declare abstract class IntegrityStrategy {
-    abstract validateForeignKeys(items: Array<Record<string, unknown>>, meta: TableMetadata, fkLookupResolver: TFkLookupResolver | undefined, writeTableResolver: TWriteTableResolver | undefined, partial?: boolean, excludeTargetTable?: string): Promise<void>;
-    abstract cascadeBeforeDelete(filter: FilterExpr, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr) => FilterExpr, adapter: BaseDbAdapter): Promise<void>;
-    abstract needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
-}
-
-/**
- * Generic database table abstraction driven by Atscript `@db.*` annotations.
- *
- * Extends {@link AtscriptDbReadable} (read operations, field metadata, query
- * translation, relation loading) with write operations, validators, and
- * schema management.
- *
- * ```typescript
- * const adapter = new MongoAdapter(db)
- * const users = new AtscriptDbTable(UsersType, adapter)
- * await users.insertOne({ name: 'John', email: 'john@example.com' })
- * ```
- *
- * @typeParam T - The Atscript annotated type for this table.
- * @typeParam DataType - The inferred data shape from the annotated type.
- */
-declare class AtscriptDbTable<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
-    protected _cascadeResolver?: TCascadeResolver;
-    protected _fkLookupResolver?: TFkLookupResolver;
-    protected readonly _integrity: IntegrityStrategy;
-    protected readonly validators: Map<string, Validator<T, DataType>>;
-    constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver, _writeTableResolver?: TWriteTableResolver);
-    /**
-     * Sets the cascade resolver for application-level cascade deletes.
-     * Called by DbSpace after table creation.
-     */
-    setCascadeResolver(resolver: TCascadeResolver): void;
-    /**
-     * Sets the FK lookup resolver for application-level FK validation.
-     * Called by DbSpace after table creation.
-     */
-    setFkLookupResolver(resolver: TFkLookupResolver): void;
-    /**
-     * Returns a cached validator for the given purpose.
-     * Built with adapter plugins from {@link BaseDbAdapter.getValidatorPlugins}.
-     *
-     * Standard purposes: `'insert'`, `'update'`, `'patch'`.
-     * Adapters may define additional purposes.
-     */
-    getValidator(purpose: string): Validator<T, DataType>;
-    /**
-     * Inserts a single record. Delegates to {@link insertMany} for unified
-     * nested creation support.
-     */
-    insertOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-        maxDepth?: number;
-    }): Promise<TDbInsertResult>;
-    /**
-     * Inserts multiple records with batch-optimized nested creation.
-     *
-     * Supports **nested creation**: if payloads include data for navigation
-     * fields (`@db.rel.to` / `@db.rel.from`), related records are created
-     * automatically in batches. TO dependencies are batch-created first
-     * (their PKs become our FKs), FROM dependents are batch-created after
-     * (they receive our PKs as their FKs). Fully recursive — nested records
-     * with their own nav data trigger further batch inserts at each level.
-     * Recursive up to `maxDepth` (default 3).
-     */
-    insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-        maxDepth?: number;
-    }): Promise<TDbInsertManyResult>;
-    /**
-     * Replaces a single record identified by primary key(s).
-     * Delegates to {@link bulkReplace} for unified nested relation support.
-     */
-    replaceOne(payload: DataType & Record<string, unknown>, opts?: {
-        maxDepth?: number;
-    }): Promise<TDbUpdateResult>;
-    /**
-     * Replaces multiple records with deep nested relation support.
-     *
-     * Supports all relation types (TO, FROM, VIA). TO dependencies are
-     * replaced first (their PKs become our FKs), FROM dependents are replaced
-     * after (they receive our PKs as their FKs), VIA relations clear and
-     * re-create junction rows. Fully recursive up to `maxDepth` (default 3).
-     */
-    bulkReplace(payloads: Array<DataType & Record<string, unknown>>, opts?: {
-        maxDepth?: number;
-    }): Promise<TDbUpdateResult>;
-    /**
-     * Partially updates a single record identified by primary key(s).
-     * Delegates to {@link bulkUpdate} for unified nested relation support.
-     */
-    updateOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-        maxDepth?: number;
-    }): Promise<TDbUpdateResult>;
-    /**
-     * Partially updates multiple records with deep nested relation support.
-     *
-     * Only TO relations (1:1, N:1) are supported for patching. FROM/VIA
-     * relations will error — use {@link bulkReplace} for those.
-     * Recursive up to `maxDepth` (default 3).
-     */
-    bulkUpdate(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-        maxDepth?: number;
-    }): Promise<TDbUpdateResult>;
-    /**
-     * Deletes a single record by any type-compatible identifier — primary key
-     * or single-field unique index. Uses the same resolution logic as `findById`.
-     *
-     * When the adapter does not support native foreign keys (e.g. MongoDB),
-     * cascade and setNull actions are applied before the delete.
-     */
-    deleteOne(id: IdType): Promise<TDbDeleteResult>;
-    updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
-    replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-    deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
-    /**
-     * Synchronizes indexes between Atscript definitions and the database.
-     */
-    syncIndexes(): Promise<void>;
-    /**
-     * Ensures the table/collection exists in the database.
-     */
-    ensureTable(): Promise<void>;
-    /**
-     * Applies default values for fields that are missing from the payload.
-     * Defaults handled natively by the DB engine are skipped — the field stays
-     * absent so the DB's own DEFAULT clause applies.
-     */
-    protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
-    /**
-     * Extracts primary key field(s) from a payload to build a filter.
-     */
-    protected _extractPrimaryKeyFilter(payload: Record<string, unknown>): FilterExpr;
-    /**
-     * Pre-validate items (type validation + FK constraints) without inserting them.
-     * Used by parent tables to validate FROM children before the main insert,
-     * ensuring errors are caught before the parent is committed.
-     *
-     * @param opts.excludeFkTargetTable - Skip FK validation to this table (the parent).
-     */
-    preValidateItems(items: Array<Record<string, unknown>>, opts?: {
-        excludeFkTargetTable?: string;
-    }): Promise<void>;
-    /**
-     * Builds a validator for a given purpose with adapter plugins.
-     *
-     * Uses annotation-based `replace` callback to make `@meta.id` and
-     * `@db.default` fields optional — works at all nesting levels
-     * (including inside nav field target types).
-     */
-    protected _buildValidator(purpose: string): Validator<T, DataType>;
-}
-
-/** A single join in a view query plan. */
-interface TViewJoin {
-    targetType: () => TAtscriptAnnotatedType;
-    targetTable: string;
-    condition: AtscriptQueryNode;
-}
-/** Resolved view query plan produced by AtscriptDbView. */
-interface TViewPlan {
-    entryType: () => TAtscriptAnnotatedType;
-    entryTable: string;
-    joins: TViewJoin[];
-    filter?: AtscriptQueryNode;
-    having?: AtscriptQueryNode;
-    materialized: boolean;
-}
-
-interface TViewColumnMapping {
-    viewColumn: string;
-    sourceTable: string;
-    sourceColumn: string;
-    /** Aggregate function name ('sum'|'avg'|'count'|'min'|'max') if this is an aggregate column. */
-    aggFn?: string;
-    /** Source field for the aggregate function ('*' for COUNT(*)). */
-    aggField?: string;
-}
-/**
- * Database view abstraction driven by Atscript `@db.view.*` annotations.
- *
- * Extends {@link AtscriptDbReadable} with view plan resolution — entry table,
- * joins, filter, and materialization flag. Read operations are inherited;
- * write operations are not available on views.
- *
- * ```typescript
- * const adapter = new SqliteAdapter(db)
- * const activeUsers = new AtscriptDbView(ActiveUsersType, adapter)
- * const users = await activeUsers.findMany({ filter: {}, controls: {} })
- * ```
- */
-declare class AtscriptDbView<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
-    private _viewPlan?;
-    get isView(): boolean;
-    /**
-     * Whether this is an external view — declared with `@db.view` only,
-     * without `@db.view.for`. External views reference pre-existing DB views
-     * and are not managed (created/dropped) by schema sync.
-     */
-    get isExternal(): boolean;
-    /**
-     * Lazily resolves the view plan from `@db.view.*` metadata.
-     *
-     * - `db.view.for` → entry type ref (required)
-     * - `db.view.joins` → array of `{ target, condition }` (optional, multiple)
-     * - `db.view.filter` → query tree (optional)
-     * - `db.view.materialized` → boolean (optional)
-     */
-    get viewPlan(): TViewPlan;
-    /**
-     * Resolves a query field ref to a quoted `table.column` SQL fragment.
-     *
-     * @param ref - The field reference from the query tree.
-     * @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
-     *             Defaults to double-quote wrapping for backwards compatibility.
-     */
-    resolveFieldRef(ref: AtscriptQueryFieldRef, qi?: (name: string) => string): string;
-    /**
-     * Maps each view field to its source table and column via ref chain.
-     * Fields without refs (inline definitions) map to the entry table with the same name.
-     */
-    getViewColumnMappings(): TViewColumnMapping[];
-}
-
-/**
- * Adapter factory function. Called once per table/view to create a fresh adapter instance.
- * Each readable gets its own adapter (1:1 relationship required by BaseDbAdapter).
- */
-type TAdapterFactory = () => BaseDbAdapter;
-/**
- * A database space — a registry of tables and views sharing the same adapter type and driver.
- *
- * `DbSpace` solves the cross-table discovery problem: when table A has a relation
- * to table B, it needs to find and query table B. The space acts as the registry
- * that makes this possible via the table resolver callback.
- *
- * Each table/view gets its own adapter instance (created by the factory), but all
- * share the same space and can discover each other for `$with` relation loading.
- *
- * ```typescript
- * // SQLite
- * const driver = new BetterSqlite3Driver(':memory:')
- * const db = new DbSpace(() => new SqliteAdapter(driver))
- * const users = db.getTable(UsersType)
- * const activeUsers = db.getView(ActiveUsersType)
- * ```
- */
-declare class DbSpace {
-    protected readonly adapterFactory: TAdapterFactory;
-    protected readonly logger: TGenericLogger;
-    private _readables;
-    /** All tables created in this space — used for reverse FK lookup during cascade. */
-    private _allTables;
-    /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
-    private _adminAdapter?;
-    constructor(adapterFactory: TAdapterFactory, logger?: TGenericLogger);
-    /**
-     * Auto-detects whether the type is a table or view and returns the
-     * appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
-     */
-    get<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbReadable<T>;
-    /**
-     * Returns the table for the given annotated type.
-     * Creates the table + adapter on first access, caches for subsequent calls.
-     */
-    getTable<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbTable<T>;
-    /**
-     * Returns the view for the given annotated type.
-     * Creates the view + adapter on first access, caches for subsequent calls.
-     */
-    getView<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbView<T>;
-    /**
-     * Returns the adapter for the given annotated type.
-     * Creates the table/view + adapter on first access if needed.
-     */
-    getAdapter(type: TAtscriptAnnotatedType): BaseDbAdapter;
-    /**
-     * Drops a table by name. Used by schema sync to remove tables no longer in the schema.
-     */
-    dropTableByName(tableName: string): Promise<void>;
-    /**
-     * Drops a view by name. Used by schema sync to remove views no longer in the schema.
-     */
-    dropViewByName(viewName: string): Promise<void>;
-    private _getAdminAdapter;
-    /**
-     * Finds all child tables with FKs pointing to the given parent table name.
-     * Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
-     */
-    private _getCascadeTargets;
-    /**
-     * Resolves a table name to a queryable target for FK validation.
-     * Searches all registered tables for one with the matching table name.
-     */
-    private _getFkLookupTarget;
-}
-
-interface TSyncColors {
-    green(s: string): string;
-    red(s: string): string;
-    cyan(s: string): string;
-    yellow(s: string): string;
-    bold(s: string): string;
-    dim(s: string): string;
-    underline(s: string): string;
-}
-type TSyncEntryStatus = 'create' | 'alter' | 'drop' | 'in-sync' | 'error';
-interface TSyncEntryInit {
-    name: string;
-    /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
-    viewType?: 'V' | 'M' | 'E';
-    status: TSyncEntryStatus;
-    syncMethod?: 'drop' | 'recreate';
-    columnsToAdd?: TDbFieldMeta[];
-    columnsToRename?: Array<{
-        from: string;
-        to: string;
-    }>;
-    typeChanges?: Array<{
-        column: string;
-        fromType: string;
-        toType: string;
-    }>;
-    nullableChanges?: Array<{
-        column: string;
-        toNullable: boolean;
-    }>;
-    defaultChanges?: Array<{
-        column: string;
-        oldDefault?: string;
-        newDefault?: string;
-    }>;
-    columnsToDrop?: string[];
-    optionChanges?: TTableOptionDiff['changed'];
-    fkAdded?: Array<{
-        fields: string[];
-        targetTable: string;
-    }>;
-    fkRemoved?: Array<{
-        fields: string[];
-        targetTable: string;
-    }>;
-    fkChanged?: Array<{
-        fields: string[];
-        targetTable: string;
-        details: string;
-    }>;
-    columnsAdded?: string[];
-    columnsRenamed?: string[];
-    columnsDropped?: string[];
-    recreated?: boolean;
-    errors?: string[];
-    renamedFrom?: string;
-}
-declare class SyncEntry {
-    readonly name: string;
-    /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
-    readonly viewType?: 'V' | 'M' | 'E';
-    readonly status: TSyncEntryStatus;
-    readonly syncMethod?: 'drop' | 'recreate';
-    readonly columnsToAdd: TDbFieldMeta[];
-    readonly columnsToRename: Array<{
-        from: string;
-        to: string;
-    }>;
-    readonly typeChanges: Array<{
-        column: string;
-        fromType: string;
-        toType: string;
-    }>;
-    readonly nullableChanges: Array<{
-        column: string;
-        toNullable: boolean;
-    }>;
-    readonly defaultChanges: Array<{
-        column: string;
-        oldDefault?: string;
-        newDefault?: string;
-    }>;
-    readonly columnsToDrop: string[];
-    readonly optionChanges: TTableOptionDiff['changed'];
-    readonly fkAdded: Array<{
-        fields: string[];
-        targetTable: string;
-    }>;
-    readonly fkRemoved: Array<{
-        fields: string[];
-        targetTable: string;
-    }>;
-    readonly fkChanged: Array<{
-        fields: string[];
-        targetTable: string;
-        details: string;
-    }>;
-    readonly columnsAdded: string[];
-    readonly columnsRenamed: string[];
-    readonly columnsDropped: string[];
-    readonly recreated: boolean;
-    readonly errors: string[];
-    readonly renamedFrom?: string;
-    constructor(init: TSyncEntryInit);
-    /** Whether this entry involves destructive operations */
-    get destructive(): boolean;
-    /** Whether this entry represents any change (not in-sync) */
-    get hasChanges(): boolean;
-    /** Whether this entry has errors */
-    get hasErrors(): boolean;
-    /** Render this entry for display */
-    print(mode: 'plan' | 'result', colors?: TSyncColors): string[];
-    private labelAndPrefix;
-    private printError;
-    private printPlan;
-    private printResult;
-    private printInSync;
-}
-
-interface TFieldSnapshot {
-    physicalName: string;
-    designType: string;
-    optional: boolean;
-    isPrimaryKey: boolean;
-    storage: TDbStorageType;
-    defaultValue?: TDbDefaultValue;
-    /** Adapter-specific mapped type (e.g., "VARCHAR(255)", "INTEGER"). */
-    mappedType?: string;
-}
-interface TIndexSnapshot {
-    key: string;
-    type: string;
-    fields: Array<{
-        name: string;
-        sort: string;
-    }>;
-}
-interface TForeignKeySnapshot {
-    fields: string[];
-    targetTable: string;
-    targetFields: string[];
-    onDelete?: string;
-    onUpdate?: string;
-}
-interface TTableSnapshot {
-    tableName: string;
-    fields: TFieldSnapshot[];
-    indexes: TIndexSnapshot[];
-    foreignKeys: TForeignKeySnapshot[];
-    /** Adapter-specific table-level options (e.g., MySQL engine/charset, MongoDB capped). */
-    tableOptions?: TExistingTableOption[];
-}
-interface TViewSnapshot {
-    tableName: string;
-    viewType: 'V' | 'M' | 'E';
-    entryTable?: string;
-    joinTables?: string[];
-    filterHash?: string;
-    materialized?: boolean;
-    fields: TFieldSnapshot[];
-}
-/**
- * Extracts a canonical, serializable snapshot from a readable's metadata.
- * Sorted deterministically so the hash is stable across runs.
- *
- * @param readable - The table/view readable.
- * @param typeMapper - Optional adapter-specific type mapper. When provided,
- *   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
- *   for precise type change detection.
- */
-declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?: (field: TDbFieldMeta) => string, tableOptions?: TExistingTableOption[]): TTableSnapshot;
-/**
- * Extracts a canonical, serializable snapshot from a view's metadata.
- * Captures view plan (entry table, joins, filter, materialization) for
- * detecting view definition changes.
- */
-declare function computeViewSnapshot(view: AtscriptDbView): TViewSnapshot;
-/**
- * Computes a deterministic hash string from multiple table snapshots.
- * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
- */
-declare function computeSchemaHash(snapshots: Array<TTableSnapshot | TViewSnapshot>): string;
-/**
- * Computes a hash for a single table/view snapshot.
- * Used for per-table change detection via stored snapshots.
- */
-declare function computeTableHash(snapshot: TTableSnapshot | TViewSnapshot): string;
-/**
- * Converts stored snapshot fields to `TExistingColumn[]` format
- * for use with `computeColumnDiff`. Used by adapters that lack
- * native column introspection (e.g., MongoDB).
- *
- * The `type` field uses `mappedType` when available (adapter-specific),
- * falling back to `designType`.
- */
-declare function snapshotToExistingColumns(snapshot: TTableSnapshot): TExistingColumn[];
-/**
- * Extracts table options from a stored snapshot for diff comparison.
- * Used as fallback when an adapter lacks native table option introspection.
- */
-declare function snapshotToExistingTableOptions(snapshot: TTableSnapshot): TExistingTableOption[];
-
-/**
- * Reads a stored table snapshot from the control table.
- * Use this for introspection/test utilities without coupling to control table internals.
- */
-declare function readStoredSnapshot(space: DbSpace, tableName: string): Promise<TTableSnapshot | null>;
-declare function readStoredSnapshot(space: DbSpace, tableName: string, asView: true): Promise<TViewSnapshot | null>;
-
-interface TSyncPlan {
-    status: 'up-to-date' | 'changes-needed';
-    schemaHash: string;
-    entries: SyncEntry[];
-}
-interface TSyncOptions {
-    /** Pod/instance identifier for distributed locking. Default: random UUID. */
-    podId?: string;
-    /** Lock TTL in milliseconds. Default: 30000 (30s). */
-    lockTtlMs?: number;
-    /** How long to wait for another pod's lock before giving up. Default: 60000 (60s). */
-    waitTimeoutMs?: number;
-    /** Poll interval when waiting for lock. Default: 500ms. */
-    pollIntervalMs?: number;
-    /** Force sync even if hash matches. Default: false. */
-    force?: boolean;
-    /** Safe mode — skip destructive operations (column drops, table drops). Default: false. */
-    safe?: boolean;
-}
-interface TSyncResult {
-    status: 'up-to-date' | 'synced' | 'synced-by-peer';
-    schemaHash: string;
-    entries: SyncEntry[];
-}
-declare class SchemaSync {
-    private readonly space;
-    private readonly store;
-    private readonly logger;
-    constructor(space: DbSpace, logger?: TGenericLogger);
-    /**
-     * Resolves types into categorized readables and computes the schema hash.
-     * Passes each adapter's typeMapper for precise type tracking in snapshots.
-     */
-    private resolveAndHash;
-    /**
-     * Checks an external view: verifies it exists in the DB and columns match.
-     * Returns a SyncEntry with status 'in-sync' or 'error'.
-     */
-    private checkExternalView;
-    /**
-     * Detects tables/views present in the previous sync but absent from the current schema.
-     * Returns SyncEntry instances with status 'drop'.
-     */
-    private detectRemoved;
-    /**
-     * Starts a periodic heartbeat that extends the lock's TTL while sync runs.
-     * Returns a handle with `stop()` to cancel and `getAbortReason()` to check
-     * whether the lock was stolen or unexpectedly removed.
-     */
-    private startHeartbeat;
-    /** Throws if the heartbeat detected a stolen/missing lock. */
-    private assertLockHeld;
-    /**
-     * Runs schema synchronization with distributed locking.
-     */
-    run(types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
-    /**
-     * Computes a dry-run plan showing what `run()` would do, without executing any DDL.
-     */
-    plan(types: TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, 'force' | 'safe'>): Promise<TSyncPlan>;
-    /** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
-    private resolveTypeMapper;
-    private planTable;
-    /**
-     * Populates plan init from a column diff (shared by Path A and Path B).
-     */
-    private populatePlanFromDiff;
-    /**
-     * Computes table option diff using DB-first introspection with snapshot fallback.
-     * Returns null if the adapter has no table options.
-     */
-    private diffTableOptions;
-    private planView;
-    private buildExecutorDeps;
-}
-
-/**
- * Computes the difference between desired schema fields and existing database columns.
- *
- * @param desired - Field descriptors from the Atscript type (after flattening).
- * @param existing - Columns currently in the database (from introspection).
- * @param typeMapper - Optional function to map field metadata to DB-native type strings.
- *                     Receives the full field meta (design type, annotations, PK status, etc.)
- *                     so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
- *                     Required for type change detection.
- */
-declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: TExistingColumn[], typeMapper?: (field: TDbFieldMeta) => string): TColumnDiff;
-
-/**
- * Computes the difference between desired and existing table options.
- *
- * Options present in desired but absent from existing are ignored (initial state).
- * Options present in existing but absent from desired are ignored (sticky options).
- * Only value changes on matching keys are tracked.
- *
- * @param desired - Options from Atscript annotations (via adapter.getDesiredTableOptions()).
- * @param existing - Options from DB introspection or snapshot fallback.
- * @param destructiveKeys - Option keys where a value change requires table recreation.
- */
-declare function computeTableOptionDiff(desired: readonly TExistingTableOption[], existing: readonly TExistingTableOption[], destructiveKeys?: ReadonlySet<string>): TTableOptionDiff;
-
-interface TForeignKeyDiff {
-    /** FKs present in desired but not in stored snapshot (new). */
-    added: TDbForeignKey[];
-    /** FKs present in stored snapshot but not in desired (removed). */
-    removed: TForeignKeySnapshot[];
-    /** FKs where fields match but target, onDelete, or onUpdate differ. */
-    changed: Array<{
-        desired: TDbForeignKey;
-        existing: TForeignKeySnapshot;
-    }>;
-}
-/** Canonical key for an FK: sorted local field names, comma-joined. */
-declare function fkKey(fields: readonly string[]): string;
-/**
- * Compares desired FK constraints against stored snapshot to detect
- * additions, removals, and property changes (target table, target fields,
- * onDelete, onUpdate).
- */
-declare function computeForeignKeyDiff(desired: ReadonlyMap<string, TDbForeignKey>, existingSnapshot: readonly TForeignKeySnapshot[]): TForeignKeyDiff;
-/** Whether the FK diff contains any changes. */
-declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
-
-/**
- * Synchronizes database schema with distributed locking.
- * Safe to call from multiple concurrent processes/pods.
- *
- * ```typescript
- * import { syncSchema } from '@atscript/db/sync'
- *
- * const db = new DbSpace(() => new SqliteAdapter(driver))
- * await syncSchema(db, [UsersType, PostsType, CommentsType])
- * ```
- *
- * The function:
- * 1. Creates an `__atscript_control` table for lock coordination
- * 2. Computes a schema hash — skips entirely if nothing changed
- * 3. Acquires a distributed lock so only one process syncs
- * 4. Creates tables, adds new columns, syncs indexes
- * 5. Stores the new hash and releases the lock
- *
- * @param space - The DbSpace containing the adapter factory.
- * @param types - Atscript annotated types to synchronize.
- * @param opts - Lock TTL, wait timeout, force mode, etc.
- */
-declare function syncSchema(space: DbSpace, types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
-
-export { SchemaSync, SyncEntry, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };
-export type { TFieldSnapshot, TForeignKeyDiff, TForeignKeySnapshot, TSyncColors, TSyncEntryStatus, TSyncOptions, TSyncPlan, TSyncResult, TTableSnapshot, TViewSnapshot };