@objectstack/driver-sql 9.11.0 → 10.2.0

package/dist/index.d.mts

@@ -1,7 +1,115 @@
 import { AutonumberToken, SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
+import { SchemaDiffEntry } from '@objectstack/spec/shared';
 import knex, { Knex } from 'knex';
 
+/**
+ * Managed-datasource schema drift (issue #2186).
+ *
+ * The driver's `initObjects` sync is *additive-only*: it creates missing
+ * tables and adds missing columns, but never alters or drops existing ones.
+ * So a non-additive metadata change (relax `required`, change a type/length,
+ * drop or rename a field) silently diverges from an existing database — the
+ * served metadata says one thing and the physical column enforces another.
+ *
+ * This module is the single source of truth for *detecting* that divergence
+ * (metadata is authoritative on a `managed` datasource) and for *categorising*
+ * each divergence by how dangerous it is to reconcile:
+ *
+ *   - `safe`         — loosening that cannot lose data and cannot fail:
+ *                      relax NOT NULL → NULL, widen a varchar. Applied
+ *                      automatically by dev auto-reconcile (P2).
+ *   - `needs_confirm`— a change a human should eyeball but that does not
+ *                      destroy data (e.g. a non-narrowing type change).
+ *   - `destructive`  — drops or tightenings that can lose data or fail:
+ *                      drop an orphaned column, narrow a varchar, add a
+ *                      NOT NULL constraint over possibly-null data. Only
+ *                      applied by `os migrate apply --allow-destructive`.
+ *
+ * The detector reuses {@link SchemaDiffEntry} (the same shape the external /
+ * federated validator emits, ADR-0015 §5.2) so CLI / Studio / audit can render
+ * managed and external drift uniformly.
+ */
+
+type SqlDialectName = 'sqlite' | 'postgres' | 'mysql' | 'unknown';
+type DriftCategory = 'safe' | 'needs_confirm' | 'destructive';
+/** A reconcilable schema operation, machine-readable for the reconciler. */
+type DriftOp = {
+    type: 'relax_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'tighten_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'widen_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'narrow_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'drop_column';
+    table: string;
+    column: string;
+};
+/**
+ * A managed-schema drift finding: a {@link SchemaDiffEntry} enriched with the
+ * owning table, a reconcile {@link DriftOp}, and a {@link DriftCategory}.
+ */
+interface ManagedDriftEntry extends SchemaDiffEntry {
+    table: string;
+    category: DriftCategory;
+    op: DriftOp;
+    /** Human one-liner with an actionable hint. */
+    message: string;
+}
+/** Columns the driver creates unconditionally — never metadata fields. */
+declare const BUILTIN_COLUMNS: Set<string>;
+/** Minimal shape of an introspected physical column (see SqlDriver.introspectColumns). */
+interface PhysicalColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    maxLength?: number;
+}
+/** Minimal shape of a metadata field definition. */
+interface FieldDef {
+    type?: string;
+    required?: boolean;
+    multiple?: boolean;
+    maxLength?: number;
+}
+/**
+ * Does this metadata field materialise a physical column? Mirrors
+ * `SqlDriver.createColumn` exactly: `formula` is virtual (computed, no column);
+ * everything else — including `multiple` (a JSON column) — gets one.
+ */
+declare function fieldHasColumn(field: FieldDef): boolean;
+/**
+ * Diff one table's metadata fields against its physical columns and return the
+ * set of *drift* findings. Metadata is authoritative.
+ *
+ * Note: a metadata field with no physical column is NOT reported — the
+ * additive sync (`ALTER TABLE ADD COLUMN`) already covers added fields, so by
+ * the time this runs every expected column exists. We only surface the
+ * non-additive divergences the additive sync can never fix.
+ */
+declare function diffManagedTable(args: {
+    table: string;
+    fields: Record<string, FieldDef>;
+    columns: PhysicalColumn[];
+    dialect: SqlDialectName;
+}): ManagedDriftEntry[];
+/** Stable de-dup / sort key for a drift entry. */
+declare function driftKey(d: ManagedDriftEntry): string;
+
 /**
  * SQL Driver for ObjectStack
  *
@@ -44,6 +152,14 @@ interface IntrospectedSchema {
  */
 type SqlDriverConfig = Knex.Config & {
     schemaMode?: SchemaMode;
+    /**
+     * Dev-only schema auto-reconcile (issue #2186). When `'safe'`, `initObjects`
+     * automatically applies *non-destructive* alters (relax NOT NULL, widen
+     * varchar) so an existing database self-heals after a metadata change
+     * loosens a constraint. `'off'` (default) only warns. Never applies
+     * destructive DDL, and is force-disabled when `NODE_ENV==='production'`.
+     */
+    autoMigrate?: 'off' | 'safe';
 };
 /**
  * SQL Driver for ObjectStack.
@@ -101,6 +217,20 @@ declare class SqlDriver implements IDataDriver {
     protected numericFields: Record<string, string[]>;
     protected dateFields: Record<string, Set<string>>;
     protected datetimeFields: Record<string, Set<string>>;
+    /**
+     * Federation read path (ADR-0015). For external objects whose physical
+     * remote table differs from the object name, these map between the two so
+     * {@link getBuilder} targets the remote table while the coercion maps above
+     * stay keyed by OBJECT name (matching formatInput/formatOutput). Empty for
+     * managed objects, so the managed query path is unchanged.
+     */
+    protected physicalTableByObject: Record<string, string>;
+    protected physicalSchemaByObject: Record<string, string>;
+    protected objectByPhysicalTable: Record<string, string>;
+    /** External columnMap (ADR-0015): logical field -> physical remote column (for WHERE/ORDER BY/writes). */
+    protected fieldColumnByObject: Record<string, Record<string, string>>;
+    /** External columnMap inverse: physical remote column -> logical field (for read output remap). */
+    protected columnFieldByObject: Record<string, Record<string, string>>;
     protected tablesWithTimestamps: Set<string>;
     /**
      * Autonumber field configs per table, captured during initObjects.
@@ -157,6 +287,7 @@ declare class SqlDriver implements IDataDriver {
      */
     protected logger: {
         warn: (msg: string, meta?: any) => void;
+        info?: (msg: string, meta?: any) => void;
     };
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
     protected get isSqlite(): boolean;
@@ -198,6 +329,20 @@ declare class SqlDriver implements IDataDriver {
      * `'managed'` so existing callers are unaffected.
      */
     protected readonly schemaMode: SchemaMode;
+    /**
+     * Dev-only auto-reconcile policy (issue #2186). See {@link SqlDriverConfig.autoMigrate}.
+     */
+    protected readonly autoMigrate: 'off' | 'safe';
+    /**
+     * Metadata field defs for every table this driver manages, captured during
+     * `initObjects` (tableName → fields). The source of truth that
+     * {@link detectManagedDrift} diffs the physical schema against.
+     */
+    protected managedObjectFields: Map<string, Record<string, any>>;
+    /** Declared indexes per managed table (tableName → indexes[]), captured in `initObjects`. Used to recreate indexes after a SQLite table rebuild. */
+    protected managedObjectIndexes: Map<string, any[]>;
+    /** De-dup set for boot-time drift warnings (keyed by {@link driftKey}). */
+    protected driftWarned: Set<string>;
     constructor(config: SqlDriverConfig);
     /**
      * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
@@ -334,10 +479,89 @@ declare class SqlDriver implements IDataDriver {
     /**
      * Batch-initialise tables from an array of object definitions.
      */
+    /**
+     * DDL-free metadata registration for a federated (external) object — the
+     * read-path counterpart to {@link initObjects} (ADR-0015 federation).
+     *
+     * `initObjects` is gated by `assertSchemaMutable` and therefore throws for
+     * any non-`managed` driver, which left external objects with NO read-coercion
+     * metadata and the query path resolving to a table named after the object
+     * instead of its remote table. This populates the same coercion maps (keyed
+     * by OBJECT name, matching formatInput/formatOutput/coerceFilterValue) and
+     * records the physical remote table (`external.remoteName`, optionally
+     * `external.remoteSchema`) so {@link getBuilder} targets it — WITHOUT running
+     * any DDL (createTable/alterTable/columnInfo). Keep the field-classification
+     * below in sync with initObjects() if the field-type -> storage mapping changes.
+     */
+    registerExternalObject(schema: {
+        name: string;
+        fields?: Record<string, any>;
+        tenancy?: any;
+        external?: {
+            remoteName?: string;
+            remoteSchema?: string;
+            columnMap?: Record<string, string>;
+        };
+    }): void;
     initObjects(objects: Array<{
         name: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
+    /** Canonical dialect name for the drift differ. */
+    protected get dialectName(): SqlDialectName;
+    /** True only when running under `NODE_ENV=production` — auto-DDL is force-disabled there. */
+    protected isProductionEnv(): boolean;
+    /** Diff one table's metadata fields against its physical columns. */
+    protected detectTableDrift(tableName: string, fields: Record<string, any>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Detect every managed-schema divergence between metadata and the physical
+     * database. Metadata is the source of truth. Returns one entry per drift,
+     * sorted by table then column. Used by `os migrate` (P3) and tests.
+     *
+     * @param objects optional explicit object list; defaults to whatever
+     *   `initObjects` last synced (captured in {@link managedObjectFields}).
+     */
+    detectManagedDrift(objects?: Array<{
+        name: string;
+        fields?: Record<string, any>;
+    }>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Boot-time per-table drift handling (P1 + P2): detect divergence, in dev
+     * auto-reconcile the *safe* (loosening) subset when `autoMigrate==='safe'`,
+     * then WARN once per remaining divergence with an actionable hint.
+     */
+    protected reconcileAndWarnDrift(tableName: string, fields: Record<string, any>): Promise<void>;
+    /**
+     * Apply a set of drift entries to the physical schema. Destructive entries
+     * are skipped unless `allowDestructive` is set. Postgres/MySQL alter columns
+     * in place; SQLite (which cannot alter constraints in place) rebuilds each
+     * affected table (copy → swap) applying only the requested edits.
+     *
+     * @returns the entries actually applied and those skipped (e.g. destructive
+     *   without `allowDestructive`, or unsupported on the dialect).
+     */
+    applyMigrationEntries(entries: ManagedDriftEntry[], opts?: {
+        allowDestructive?: boolean;
+    }): Promise<{
+        applied: ManagedDriftEntry[];
+        skipped: ManagedDriftEntry[];
+    }>;
+    /** Apply a single drift op in place (Postgres / MySQL). Returns false if unsupported. */
+    protected applyDriftOpInPlace(op: DriftOp): Promise<boolean>;
+    /**
+     * Rebuild a SQLite table applying a set of column edits (relax/tighten NOT
+     * NULL, drop column), preserving all other columns and their data. Follows
+     * the official SQLite procedure: create patched table → copy → drop → rename.
+     * varchar widen/narrow are no-ops on SQLite (dynamic typing) and ignored.
+     *
+     * Unique field-level constraints and declared indexes are recreated from
+     * metadata afterwards (the source of truth). DB-level foreign keys declared
+     * by `lookup` fields are not re-added (ObjectStack enforces relationships at
+     * the application layer, not via SQLite FK constraints).
+     */
+    protected rebuildSqliteTablePatched(table: string, ents: ManagedDriftEntry[]): Promise<void>;
+    /** Map an introspected SQLite column to a knex builder for the rebuilt table. */
+    protected buildRebuiltColumn(t: Knex.CreateTableBuilder, c: IntrospectedColumn): any;
     /**
      * Build a deterministic index name for a declared index so repeated
      * `initObjects` runs converge on the same identifier (and can detect an
@@ -439,6 +663,16 @@ declare class SqlDriver implements IDataDriver {
      * `initObjects`). Returns null when the builder is not table-scoped yet.
      */
     protected tableNameForBuilder(builder: any): string | null;
+    /**
+     * Coercion-map key for a builder. Coercion maps (date/datetime) are keyed by
+     * OBJECT name, but after the federation change {@link getBuilder} targets the
+     * physical remote table, so a builder reports the remote name. Map it back to
+     * the object name for external objects; identity for managed ones (no reverse
+     * entry). Note datetime coercion is a SQLite-only concern (see
+     * coerceFilterValue), and SQLite external tables are bare-named, so this is
+     * exact where it matters.
+     */
+    protected coercionKey(builder: any): string | null;
     /**
      * Collapse a `Field.date` value to a timezone-naive `YYYY-MM-DD`
      * calendar-day string (ADR-0053 Phase 1). A `Date` collapses to its UTC
@@ -498,6 +732,19 @@ declare class SqlDriver implements IDataDriver {
     private applyContainsLike;
     protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or', tableHint?: string | null): void;
     protected mapSortField(field: string): string;
+    /**
+     * Physical column for a logical field on an external object that declares an
+     * `external.columnMap` (ADR-0015). Returns `fallback` (the caller's existing
+     * per-site resolution) when the object has no columnMap, so managed objects
+     * and external objects without a columnMap are byte-for-byte unchanged.
+     */
+    protected remoteColumn(object: string | null | undefined, field: string, fallback: string): string;
+    /**
+     * Remap a write payload's logical field keys to physical remote columns for an
+     * external object with a columnMap. No-op otherwise. Applied AFTER formatInput
+     * (whose value coercion is keyed by logical field name).
+     */
+    protected applyWriteColumnMap(object: string, data: any): any;
     protected mapAggregateFunc(func: string): string;
     protected buildWindowFunction(spec: any): string;
     protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any): void;
@@ -518,4 +765,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, SqlDriver, type SqlDriverConfig, _default as default };
+export { BUILTIN_COLUMNS, type DriftCategory, type FieldDef as DriftFieldDef, type DriftOp, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, type ManagedDriftEntry, type PhysicalColumn, type SqlDialectName, SqlDriver, type SqlDriverConfig, _default as default, diffManagedTable, driftKey, fieldHasColumn };

package/dist/index.d.ts

@@ -1,7 +1,115 @@
 import { AutonumberToken, SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
+import { SchemaDiffEntry } from '@objectstack/spec/shared';
 import knex, { Knex } from 'knex';
 
+/**
+ * Managed-datasource schema drift (issue #2186).
+ *
+ * The driver's `initObjects` sync is *additive-only*: it creates missing
+ * tables and adds missing columns, but never alters or drops existing ones.
+ * So a non-additive metadata change (relax `required`, change a type/length,
+ * drop or rename a field) silently diverges from an existing database — the
+ * served metadata says one thing and the physical column enforces another.
+ *
+ * This module is the single source of truth for *detecting* that divergence
+ * (metadata is authoritative on a `managed` datasource) and for *categorising*
+ * each divergence by how dangerous it is to reconcile:
+ *
+ *   - `safe`         — loosening that cannot lose data and cannot fail:
+ *                      relax NOT NULL → NULL, widen a varchar. Applied
+ *                      automatically by dev auto-reconcile (P2).
+ *   - `needs_confirm`— a change a human should eyeball but that does not
+ *                      destroy data (e.g. a non-narrowing type change).
+ *   - `destructive`  — drops or tightenings that can lose data or fail:
+ *                      drop an orphaned column, narrow a varchar, add a
+ *                      NOT NULL constraint over possibly-null data. Only
+ *                      applied by `os migrate apply --allow-destructive`.
+ *
+ * The detector reuses {@link SchemaDiffEntry} (the same shape the external /
+ * federated validator emits, ADR-0015 §5.2) so CLI / Studio / audit can render
+ * managed and external drift uniformly.
+ */
+
+type SqlDialectName = 'sqlite' | 'postgres' | 'mysql' | 'unknown';
+type DriftCategory = 'safe' | 'needs_confirm' | 'destructive';
+/** A reconcilable schema operation, machine-readable for the reconciler. */
+type DriftOp = {
+    type: 'relax_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'tighten_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'widen_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'narrow_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'drop_column';
+    table: string;
+    column: string;
+};
+/**
+ * A managed-schema drift finding: a {@link SchemaDiffEntry} enriched with the
+ * owning table, a reconcile {@link DriftOp}, and a {@link DriftCategory}.
+ */
+interface ManagedDriftEntry extends SchemaDiffEntry {
+    table: string;
+    category: DriftCategory;
+    op: DriftOp;
+    /** Human one-liner with an actionable hint. */
+    message: string;
+}
+/** Columns the driver creates unconditionally — never metadata fields. */
+declare const BUILTIN_COLUMNS: Set<string>;
+/** Minimal shape of an introspected physical column (see SqlDriver.introspectColumns). */
+interface PhysicalColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    maxLength?: number;
+}
+/** Minimal shape of a metadata field definition. */
+interface FieldDef {
+    type?: string;
+    required?: boolean;
+    multiple?: boolean;
+    maxLength?: number;
+}
+/**
+ * Does this metadata field materialise a physical column? Mirrors
+ * `SqlDriver.createColumn` exactly: `formula` is virtual (computed, no column);
+ * everything else — including `multiple` (a JSON column) — gets one.
+ */
+declare function fieldHasColumn(field: FieldDef): boolean;
+/**
+ * Diff one table's metadata fields against its physical columns and return the
+ * set of *drift* findings. Metadata is authoritative.
+ *
+ * Note: a metadata field with no physical column is NOT reported — the
+ * additive sync (`ALTER TABLE ADD COLUMN`) already covers added fields, so by
+ * the time this runs every expected column exists. We only surface the
+ * non-additive divergences the additive sync can never fix.
+ */
+declare function diffManagedTable(args: {
+    table: string;
+    fields: Record<string, FieldDef>;
+    columns: PhysicalColumn[];
+    dialect: SqlDialectName;
+}): ManagedDriftEntry[];
+/** Stable de-dup / sort key for a drift entry. */
+declare function driftKey(d: ManagedDriftEntry): string;
+
 /**
  * SQL Driver for ObjectStack
  *
@@ -44,6 +152,14 @@ interface IntrospectedSchema {
  */
 type SqlDriverConfig = Knex.Config & {
     schemaMode?: SchemaMode;
+    /**
+     * Dev-only schema auto-reconcile (issue #2186). When `'safe'`, `initObjects`
+     * automatically applies *non-destructive* alters (relax NOT NULL, widen
+     * varchar) so an existing database self-heals after a metadata change
+     * loosens a constraint. `'off'` (default) only warns. Never applies
+     * destructive DDL, and is force-disabled when `NODE_ENV==='production'`.
+     */
+    autoMigrate?: 'off' | 'safe';
 };
 /**
  * SQL Driver for ObjectStack.
@@ -101,6 +217,20 @@ declare class SqlDriver implements IDataDriver {
     protected numericFields: Record<string, string[]>;
     protected dateFields: Record<string, Set<string>>;
     protected datetimeFields: Record<string, Set<string>>;
+    /**
+     * Federation read path (ADR-0015). For external objects whose physical
+     * remote table differs from the object name, these map between the two so
+     * {@link getBuilder} targets the remote table while the coercion maps above
+     * stay keyed by OBJECT name (matching formatInput/formatOutput). Empty for
+     * managed objects, so the managed query path is unchanged.
+     */
+    protected physicalTableByObject: Record<string, string>;
+    protected physicalSchemaByObject: Record<string, string>;
+    protected objectByPhysicalTable: Record<string, string>;
+    /** External columnMap (ADR-0015): logical field -> physical remote column (for WHERE/ORDER BY/writes). */
+    protected fieldColumnByObject: Record<string, Record<string, string>>;
+    /** External columnMap inverse: physical remote column -> logical field (for read output remap). */
+    protected columnFieldByObject: Record<string, Record<string, string>>;
     protected tablesWithTimestamps: Set<string>;
     /**
      * Autonumber field configs per table, captured during initObjects.
@@ -157,6 +287,7 @@ declare class SqlDriver implements IDataDriver {
      */
     protected logger: {
         warn: (msg: string, meta?: any) => void;
+        info?: (msg: string, meta?: any) => void;
     };
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
     protected get isSqlite(): boolean;
@@ -198,6 +329,20 @@ declare class SqlDriver implements IDataDriver {
      * `'managed'` so existing callers are unaffected.
      */
     protected readonly schemaMode: SchemaMode;
+    /**
+     * Dev-only auto-reconcile policy (issue #2186). See {@link SqlDriverConfig.autoMigrate}.
+     */
+    protected readonly autoMigrate: 'off' | 'safe';
+    /**
+     * Metadata field defs for every table this driver manages, captured during
+     * `initObjects` (tableName → fields). The source of truth that
+     * {@link detectManagedDrift} diffs the physical schema against.
+     */
+    protected managedObjectFields: Map<string, Record<string, any>>;
+    /** Declared indexes per managed table (tableName → indexes[]), captured in `initObjects`. Used to recreate indexes after a SQLite table rebuild. */
+    protected managedObjectIndexes: Map<string, any[]>;
+    /** De-dup set for boot-time drift warnings (keyed by {@link driftKey}). */
+    protected driftWarned: Set<string>;
     constructor(config: SqlDriverConfig);
     /**
      * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
@@ -334,10 +479,89 @@ declare class SqlDriver implements IDataDriver {
     /**
      * Batch-initialise tables from an array of object definitions.
      */
+    /**
+     * DDL-free metadata registration for a federated (external) object — the
+     * read-path counterpart to {@link initObjects} (ADR-0015 federation).
+     *
+     * `initObjects` is gated by `assertSchemaMutable` and therefore throws for
+     * any non-`managed` driver, which left external objects with NO read-coercion
+     * metadata and the query path resolving to a table named after the object
+     * instead of its remote table. This populates the same coercion maps (keyed
+     * by OBJECT name, matching formatInput/formatOutput/coerceFilterValue) and
+     * records the physical remote table (`external.remoteName`, optionally
+     * `external.remoteSchema`) so {@link getBuilder} targets it — WITHOUT running
+     * any DDL (createTable/alterTable/columnInfo). Keep the field-classification
+     * below in sync with initObjects() if the field-type -> storage mapping changes.
+     */
+    registerExternalObject(schema: {
+        name: string;
+        fields?: Record<string, any>;
+        tenancy?: any;
+        external?: {
+            remoteName?: string;
+            remoteSchema?: string;
+            columnMap?: Record<string, string>;
+        };
+    }): void;
     initObjects(objects: Array<{
         name: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
+    /** Canonical dialect name for the drift differ. */
+    protected get dialectName(): SqlDialectName;
+    /** True only when running under `NODE_ENV=production` — auto-DDL is force-disabled there. */
+    protected isProductionEnv(): boolean;
+    /** Diff one table's metadata fields against its physical columns. */
+    protected detectTableDrift(tableName: string, fields: Record<string, any>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Detect every managed-schema divergence between metadata and the physical
+     * database. Metadata is the source of truth. Returns one entry per drift,
+     * sorted by table then column. Used by `os migrate` (P3) and tests.
+     *
+     * @param objects optional explicit object list; defaults to whatever
+     *   `initObjects` last synced (captured in {@link managedObjectFields}).
+     */
+    detectManagedDrift(objects?: Array<{
+        name: string;
+        fields?: Record<string, any>;
+    }>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Boot-time per-table drift handling (P1 + P2): detect divergence, in dev
+     * auto-reconcile the *safe* (loosening) subset when `autoMigrate==='safe'`,
+     * then WARN once per remaining divergence with an actionable hint.
+     */
+    protected reconcileAndWarnDrift(tableName: string, fields: Record<string, any>): Promise<void>;
+    /**
+     * Apply a set of drift entries to the physical schema. Destructive entries
+     * are skipped unless `allowDestructive` is set. Postgres/MySQL alter columns
+     * in place; SQLite (which cannot alter constraints in place) rebuilds each
+     * affected table (copy → swap) applying only the requested edits.
+     *
+     * @returns the entries actually applied and those skipped (e.g. destructive
+     *   without `allowDestructive`, or unsupported on the dialect).
+     */
+    applyMigrationEntries(entries: ManagedDriftEntry[], opts?: {
+        allowDestructive?: boolean;
+    }): Promise<{
+        applied: ManagedDriftEntry[];
+        skipped: ManagedDriftEntry[];
+    }>;
+    /** Apply a single drift op in place (Postgres / MySQL). Returns false if unsupported. */
+    protected applyDriftOpInPlace(op: DriftOp): Promise<boolean>;
+    /**
+     * Rebuild a SQLite table applying a set of column edits (relax/tighten NOT
+     * NULL, drop column), preserving all other columns and their data. Follows
+     * the official SQLite procedure: create patched table → copy → drop → rename.
+     * varchar widen/narrow are no-ops on SQLite (dynamic typing) and ignored.
+     *
+     * Unique field-level constraints and declared indexes are recreated from
+     * metadata afterwards (the source of truth). DB-level foreign keys declared
+     * by `lookup` fields are not re-added (ObjectStack enforces relationships at
+     * the application layer, not via SQLite FK constraints).
+     */
+    protected rebuildSqliteTablePatched(table: string, ents: ManagedDriftEntry[]): Promise<void>;
+    /** Map an introspected SQLite column to a knex builder for the rebuilt table. */
+    protected buildRebuiltColumn(t: Knex.CreateTableBuilder, c: IntrospectedColumn): any;
     /**
      * Build a deterministic index name for a declared index so repeated
      * `initObjects` runs converge on the same identifier (and can detect an
@@ -439,6 +663,16 @@ declare class SqlDriver implements IDataDriver {
      * `initObjects`). Returns null when the builder is not table-scoped yet.
      */
     protected tableNameForBuilder(builder: any): string | null;
+    /**
+     * Coercion-map key for a builder. Coercion maps (date/datetime) are keyed by
+     * OBJECT name, but after the federation change {@link getBuilder} targets the
+     * physical remote table, so a builder reports the remote name. Map it back to
+     * the object name for external objects; identity for managed ones (no reverse
+     * entry). Note datetime coercion is a SQLite-only concern (see
+     * coerceFilterValue), and SQLite external tables are bare-named, so this is
+     * exact where it matters.
+     */
+    protected coercionKey(builder: any): string | null;
     /**
      * Collapse a `Field.date` value to a timezone-naive `YYYY-MM-DD`
      * calendar-day string (ADR-0053 Phase 1). A `Date` collapses to its UTC
@@ -498,6 +732,19 @@ declare class SqlDriver implements IDataDriver {
     private applyContainsLike;
     protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or', tableHint?: string | null): void;
     protected mapSortField(field: string): string;
+    /**
+     * Physical column for a logical field on an external object that declares an
+     * `external.columnMap` (ADR-0015). Returns `fallback` (the caller's existing
+     * per-site resolution) when the object has no columnMap, so managed objects
+     * and external objects without a columnMap are byte-for-byte unchanged.
+     */
+    protected remoteColumn(object: string | null | undefined, field: string, fallback: string): string;
+    /**
+     * Remap a write payload's logical field keys to physical remote columns for an
+     * external object with a columnMap. No-op otherwise. Applied AFTER formatInput
+     * (whose value coercion is keyed by logical field name).
+     */
+    protected applyWriteColumnMap(object: string, data: any): any;
     protected mapAggregateFunc(func: string): string;
     protected buildWindowFunction(spec: any): string;
     protected createColumn(table: Knex.CreateTableBuilder, name: string, field: any): void;
@@ -518,4 +765,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, SqlDriver, type SqlDriverConfig, _default as default };
+export { BUILTIN_COLUMNS, type DriftCategory, type FieldDef as DriftFieldDef, type DriftOp, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, type ManagedDriftEntry, type PhysicalColumn, type SqlDialectName, SqlDriver, type SqlDriverConfig, _default as default, diffManagedTable, driftKey, fieldHasColumn };