@objectstack/driver-sql 9.11.0 → 10.2.0

package/dist/index.js

@@ -30,8 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BUILTIN_COLUMNS: () => BUILTIN_COLUMNS,
   SqlDriver: () => SqlDriver,
-  default: () => index_default
+  default: () => index_default,
+  diffManagedTable: () => diffManagedTable,
+  driftKey: () => driftKey,
+  fieldHasColumn: () => fieldHasColumn
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -39,6 +43,108 @@ module.exports = __toCommonJS(index_exports);
 var import_data = require("@objectstack/spec/data");
 var import_system = require("@objectstack/spec/system");
 var import_shared = require("@objectstack/spec/shared");
+
+// src/schema-drift.ts
+var BUILTIN_COLUMNS = /* @__PURE__ */ new Set(["id", "created_at", "updated_at"]);
+function fieldHasColumn(field) {
+  if (field?.multiple) return true;
+  return (field?.type ?? "string") !== "formula";
+}
+function enforcesVarcharLength(dialect) {
+  return dialect === "postgres" || dialect === "mysql";
+}
+function diffManagedTable(args) {
+  const { table, fields, columns, dialect } = args;
+  const out = [];
+  const columnsByName = new Map(columns.map((c) => [c.name, c]));
+  const expectedColumns = /* @__PURE__ */ new Set();
+  for (const [fieldName, field] of Object.entries(fields ?? {})) {
+    if (BUILTIN_COLUMNS.has(fieldName)) continue;
+    if (!fieldHasColumn(field)) continue;
+    expectedColumns.add(fieldName);
+    const col = columnsByName.get(fieldName);
+    if (!col) continue;
+    const expectNullable = field.required !== true;
+    if (expectNullable && !col.nullable) {
+      out.push({
+        kind: "nullability_mismatch",
+        remoteName: table,
+        table,
+        column: fieldName,
+        expected: "NULL",
+        actual: "NOT NULL",
+        severity: "warning",
+        category: "safe",
+        op: { type: "relax_not_null", table, column: fieldName },
+        message: `${table}.${fieldName}: metadata is optional but the column is NOT NULL \u2014 writes that omit it fail. Run "os migrate" to relax it.`
+      });
+    } else if (!expectNullable && col.nullable) {
+      out.push({
+        kind: "nullability_mismatch",
+        remoteName: table,
+        table,
+        column: fieldName,
+        expected: "NOT NULL",
+        actual: "NULL",
+        severity: "error",
+        category: "destructive",
+        op: { type: "tighten_not_null", table, column: fieldName },
+        message: `${table}.${fieldName}: metadata is required but the column is nullable \u2014 existing nulls must be backfilled. Run "os migrate apply --allow-destructive".`
+      });
+    }
+    if (enforcesVarcharLength(dialect) && typeof field.maxLength === "number" && typeof col.maxLength === "number" && field.maxLength !== col.maxLength) {
+      if (field.maxLength > col.maxLength) {
+        out.push({
+          kind: "type_mismatch",
+          remoteName: table,
+          table,
+          column: fieldName,
+          expected: `varchar(${field.maxLength})`,
+          actual: `varchar(${col.maxLength})`,
+          severity: "warning",
+          category: "safe",
+          op: { type: "widen_varchar", table, column: fieldName, to: field.maxLength, from: col.maxLength },
+          message: `${table}.${fieldName}: metadata allows ${field.maxLength} chars but the column caps at ${col.maxLength} \u2014 widen via "os migrate".`
+        });
+      } else {
+        out.push({
+          kind: "type_mismatch",
+          remoteName: table,
+          table,
+          column: fieldName,
+          expected: `varchar(${field.maxLength})`,
+          actual: `varchar(${col.maxLength})`,
+          severity: "error",
+          category: "destructive",
+          op: { type: "narrow_varchar", table, column: fieldName, to: field.maxLength, from: col.maxLength },
+          message: `${table}.${fieldName}: metadata caps at ${field.maxLength} chars but the column allows ${col.maxLength} \u2014 narrowing may truncate. "os migrate apply --allow-destructive".`
+        });
+      }
+    }
+  }
+  for (const col of columns) {
+    if (BUILTIN_COLUMNS.has(col.name)) continue;
+    if (expectedColumns.has(col.name)) continue;
+    out.push({
+      kind: "unmapped_column",
+      remoteName: table,
+      table,
+      column: col.name,
+      expected: "(absent)",
+      actual: col.type,
+      severity: "warning",
+      category: "destructive",
+      op: { type: "drop_column", table, column: col.name },
+      message: `${table}.${col.name}: column exists in the database but not in metadata (orphaned) \u2014 "os migrate apply --allow-destructive" to drop it.`
+    });
+  }
+  return out;
+}
+function driftKey(d) {
+  return `${d.table}.${d.column ?? ""}:${d.kind}`;
+}
+
+// src/sql-driver.ts
 var import_knex = __toESM(require("knex"));
 var import_nanoid = require("nanoid");
 var import_node_crypto = require("crypto");
@@ -86,6 +192,20 @@ var SqlDriver = class {
     this.numericFields = {};
     this.dateFields = {};
     this.datetimeFields = {};
+    /**
+     * 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.
+     */
+    this.physicalTableByObject = {};
+    this.physicalSchemaByObject = {};
+    this.objectByPhysicalTable = {};
+    /** External columnMap (ADR-0015): logical field -> physical remote column (for WHERE/ORDER BY/writes). */
+    this.fieldColumnByObject = {};
+    /** External columnMap inverse: physical remote column -> logical field (for read output remap). */
+    this.columnFieldByObject = {};
     this.tablesWithTimestamps = /* @__PURE__ */ new Set();
     /**
      * Autonumber field configs per table, captured during initObjects.
@@ -138,8 +258,19 @@ var SqlDriver = class {
     this.logger = {
       warn: (msg, meta) => console.warn(msg, meta ?? "")
     };
-    const { schemaMode, ...knexConfig } = config;
+    /**
+     * 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.
+     */
+    this.managedObjectFields = /* @__PURE__ */ new Map();
+    /** Declared indexes per managed table (tableName → indexes[]), captured in `initObjects`. Used to recreate indexes after a SQLite table rebuild. */
+    this.managedObjectIndexes = /* @__PURE__ */ new Map();
+    /** De-dup set for boot-time drift warnings (keyed by {@link driftKey}). */
+    this.driftWarned = /* @__PURE__ */ new Set();
+    const { schemaMode, autoMigrate, ...knexConfig } = config;
     this.schemaMode = schemaMode ?? "managed";
+    this.autoMigrate = autoMigrate ?? "off";
     this.config = knexConfig;
     this.knex = (0, import_knex.default)(knexConfig);
   }
@@ -310,6 +441,13 @@ var SqlDriver = class {
   // ===================================
   async connect() {
     await this.ensureDatabaseExists();
+    if (this.isSqlite) {
+      try {
+        await this.knex.raw("PRAGMA auto_vacuum = INCREMENTAL");
+      } catch (e) {
+        this.logger.warn("Failed to set PRAGMA auto_vacuum=INCREMENTAL", e);
+      }
+    }
   }
   async checkHealth() {
     try {
@@ -335,7 +473,7 @@ var SqlDriver = class {
       if (query.orderBy && Array.isArray(query.orderBy)) {
         for (const item of query.orderBy) {
           if (item.field) {
-            b.orderBy(this.mapSortField(item.field), item.order || "asc");
+            b.orderBy(this.remoteColumn(object, item.field, this.mapSortField(item.field)), item.order || "asc");
           }
         }
       }
@@ -412,7 +550,7 @@ var SqlDriver = class {
     this.injectTenantOnInsert(object, toInsert, options);
     await this.fillAutoNumberFields(object, toInsert, options);
     const builder = this.getBuilder(object, options);
-    const formatted = this.formatInput(object, toInsert);
+    const formatted = this.applyWriteColumnMap(object, this.formatInput(object, toInsert));
     const result = await builder.insert(formatted).returning("*");
     return this.formatOutput(object, result[0]);
   }
@@ -609,8 +747,8 @@ var SqlDriver = class {
    * tenant scopes it for isolation.
    */
   async fillAutoNumberFields(object, row, options) {
-    const tableName = import_system.StorageNameMapping.resolveTableName({ name: object });
-    const cfgs = this.autoNumberFields[tableName] || this.autoNumberFields[object];
+    const tableName = this.physicalTableByObject[object] ?? import_system.StorageNameMapping.resolveTableName({ name: object });
+    const cfgs = this.autoNumberFields[object] || this.autoNumberFields[tableName];
     if (!cfgs || cfgs.length === 0) return;
     const parentTrx = options?.transaction;
     const timezone = options?.timezone;
@@ -644,7 +782,7 @@ var SqlDriver = class {
     this.auditMissingTenant(object, "update", options);
     const builder = this.getBuilder(object, options).where("id", id);
     this.applyTenantScope(builder, object, options);
-    const formatted = this.formatInput(object, data);
+    const formatted = this.applyWriteColumnMap(object, this.formatInput(object, data));
     if (this.tablesWithTimestamps.has(object)) {
       if (this.isSqlite) {
         const now = /* @__PURE__ */ new Date();
@@ -670,7 +808,7 @@ var SqlDriver = class {
     this.auditMissingTenant(object, "upsert", options);
     this.injectTenantOnInsert(object, toUpsert, options);
     await this.fillAutoNumberFields(object, toUpsert, options);
-    const formatted = this.formatInput(object, toUpsert);
+    const formatted = this.applyWriteColumnMap(object, this.formatInput(object, toUpsert));
     const mergeKeys = conflictKeys && conflictKeys.length > 0 ? conflictKeys : ["id"];
     const builder = this.getBuilder(object, options);
     await builder.insert(formatted).onConflict(mergeKeys).merge();
@@ -953,12 +1091,99 @@ var SqlDriver = class {
   /**
    * 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) {
+    const key = schema.name;
+    const remoteName = schema.external?.remoteName || schema.name;
+    const remoteSchema = schema.external?.remoteSchema;
+    this.physicalTableByObject[key] = remoteName;
+    this.objectByPhysicalTable[remoteName] = key;
+    if (remoteSchema) {
+      if (this.isSqlite) {
+        this.logger.warn(
+          `[sql-driver] external object "${key}" declares remoteSchema="${remoteSchema}" but SQLite has no schema namespace; ignoring (treating "${remoteName}" as a bare table).`
+        );
+      } else {
+        this.physicalSchemaByObject[key] = remoteSchema;
+      }
+    }
+    const columnMap = schema.external?.columnMap;
+    if (columnMap && typeof columnMap === "object" && Object.keys(columnMap).length > 0) {
+      const fieldToCol = {};
+      const colToField = {};
+      for (const [remoteCol, localField] of Object.entries(columnMap)) {
+        if (typeof localField === "string" && localField) {
+          fieldToCol[localField] = remoteCol;
+          colToField[remoteCol] = localField;
+        }
+      }
+      this.fieldColumnByObject[key] = fieldToCol;
+      this.columnFieldByObject[key] = colToField;
+    }
+    const jsonCols = [];
+    const booleanCols = [];
+    const numericCols = [];
+    const dateCols = [];
+    const datetimeCols = [];
+    const autoNumberCols = [];
+    const tenancyDecl = schema?.tenancy;
+    let tenantField = null;
+    if (tenancyDecl && tenancyDecl.enabled !== false && tenancyDecl.tenantField) {
+      const declared = String(tenancyDecl.tenantField);
+      if (schema.fields && Object.prototype.hasOwnProperty.call(schema.fields, declared)) {
+        tenantField = declared;
+      }
+    }
+    if (!tenantField) {
+      const hasOrgField = !!(schema.fields && Object.prototype.hasOwnProperty.call(schema.fields, "organization_id"));
+      tenantField = hasOrgField ? "organization_id" : null;
+    }
+    if (schema.fields) {
+      for (const [name, field] of Object.entries(schema.fields)) {
+        const type = field.type || "string";
+        if (this.isJsonField(type, field)) jsonCols.push(name);
+        if (type === "boolean" || type === "toggle") booleanCols.push(name);
+        if (NUMERIC_SCALAR_TYPES.has(type) && !field.multiple) numericCols.push(name);
+        if (type === "date") dateCols.push(name);
+        if (type === "datetime") datetimeCols.push(name);
+        if (type === "auto_number" || type === "autonumber") {
+          const rawFmt = typeof field.autonumberFormat === "string" && field.autonumberFormat ? field.autonumberFormat : typeof field.format === "string" && field.format ? field.format : "";
+          const fmt = rawFmt || "{0000}";
+          autoNumberCols.push({ name, format: fmt, tokens: (0, import_data.parseAutonumberFormat)(fmt), tenantField });
+        }
+      }
+    }
+    this.jsonFields[key] = jsonCols;
+    this.booleanFields[key] = booleanCols;
+    this.numericFields[key] = numericCols;
+    this.autoNumberFields[key] = autoNumberCols;
+    this.tenantFieldByTable[key] = tenantField;
+    if (dateCols.length) this.dateFields[key] = new Set(dateCols);
+    if (datetimeCols.length) this.datetimeFields[key] = new Set(datetimeCols);
+  }
   async initObjects(objects) {
     var _a, _b;
     this.assertSchemaMutable("initObjects");
     await this.ensureDatabaseExists();
     for (const obj of objects) {
       const tableName = import_system.StorageNameMapping.resolveTableName(obj);
+      this.managedObjectFields.set(tableName, obj.fields ?? {});
+      if (Array.isArray(obj.indexes)) {
+        this.managedObjectIndexes.set(tableName, obj.indexes);
+      }
       const jsonCols = [];
       const booleanCols = [];
       const numericCols = [];
@@ -1051,8 +1276,267 @@ var SqlDriver = class {
         const physicalColumns = new Set(Object.keys(colInfo));
         await this.syncDeclaredIndexes(tableName, declaredIndexes, physicalColumns);
       }
+      if (exists) {
+        await this.reconcileAndWarnDrift(tableName, obj.fields ?? {});
+      }
     }
   }
+  // ── Managed-schema drift & reconcile (#2186) ───────────────────────────────
+  /** Canonical dialect name for the drift differ. */
+  get dialectName() {
+    if (this.isSqlite) return "sqlite";
+    if (this.isPostgres) return "postgres";
+    if (this.isMysql) return "mysql";
+    return "unknown";
+  }
+  /** True only when running under `NODE_ENV=production` — auto-DDL is force-disabled there. */
+  isProductionEnv() {
+    try {
+      return (process.env.NODE_ENV ?? "").toLowerCase() === "production";
+    } catch {
+      return false;
+    }
+  }
+  /** Diff one table's metadata fields against its physical columns. */
+  async detectTableDrift(tableName, fields) {
+    const cols = await this.introspectColumns(tableName);
+    const physical = cols.map((c) => ({
+      name: c.name,
+      type: c.type,
+      nullable: c.nullable,
+      maxLength: c.maxLength
+    }));
+    return diffManagedTable({ table: tableName, fields, columns: physical, dialect: this.dialectName });
+  }
+  /**
+   * 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}).
+   */
+  async detectManagedDrift(objects) {
+    const tables = /* @__PURE__ */ new Map();
+    if (objects) {
+      for (const o of objects) tables.set(import_system.StorageNameMapping.resolveTableName(o), o.fields ?? {});
+    } else {
+      for (const [t, f] of this.managedObjectFields) tables.set(t, f);
+    }
+    const out = [];
+    for (const [tableName, fields] of tables) {
+      if (!await this.knex.schema.hasTable(tableName)) continue;
+      out.push(...await this.detectTableDrift(tableName, fields));
+    }
+    out.sort((a, b) => a.table === b.table ? (a.column ?? "").localeCompare(b.column ?? "") : a.table.localeCompare(b.table));
+    return out;
+  }
+  /**
+   * 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.
+   */
+  async reconcileAndWarnDrift(tableName, fields) {
+    let drift;
+    try {
+      drift = await this.detectTableDrift(tableName, fields);
+    } catch (e) {
+      this.logger.warn(`[schema-drift] could not introspect '${tableName}' for drift detection`, e?.message ?? e);
+      return;
+    }
+    if (drift.length === 0) return;
+    const autoOn = this.autoMigrate === "safe" && this.schemaMode === "managed";
+    if (autoOn && this.isProductionEnv()) {
+      this.logger.warn(
+        `[schema-drift] autoMigrate='safe' is ignored under NODE_ENV=production \u2014 schema is never auto-altered in production. Run 'os migrate' deliberately.`
+      );
+    } else if (autoOn) {
+      const safe = drift.filter((d) => d.category === "safe");
+      if (safe.length > 0) {
+        try {
+          const { applied } = await this.applyMigrationEntries(safe, { allowDestructive: false });
+          for (const d of applied) {
+            (this.logger.info ?? this.logger.warn)(`[schema-drift] auto-reconciled ${d.op.type} on ${d.table}.${d.column}`);
+          }
+          drift = await this.detectTableDrift(tableName, fields);
+        } catch (e) {
+          this.logger.warn(`[schema-drift] dev auto-reconcile failed for '${tableName}' \u2014 falling back to warning`, e?.message ?? e);
+        }
+      }
+    }
+    for (const d of drift) {
+      const k = driftKey(d);
+      if (this.driftWarned.has(k)) continue;
+      this.driftWarned.add(k);
+      this.logger.warn(`[schema-drift] ${d.message}`);
+    }
+  }
+  /**
+   * 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).
+   */
+  async applyMigrationEntries(entries, opts = {}) {
+    this.assertSchemaMutable("reconcileManagedSchema");
+    const allowDestructive = opts.allowDestructive === true;
+    const applied = [];
+    const skipped = [];
+    const candidates = entries.filter((d) => {
+      if (d.category === "destructive" && !allowDestructive) {
+        skipped.push(d);
+        return false;
+      }
+      return true;
+    });
+    if (candidates.length === 0) return { applied, skipped };
+    const byTable = /* @__PURE__ */ new Map();
+    for (const d of candidates) {
+      (byTable.get(d.table) ?? byTable.set(d.table, []).get(d.table)).push(d);
+    }
+    for (const [table, ents] of byTable) {
+      try {
+        if (this.isSqlite) {
+          await this.rebuildSqliteTablePatched(table, ents);
+          applied.push(...ents);
+        } else {
+          for (const d of ents) {
+            const ok = await this.applyDriftOpInPlace(d.op);
+            (ok ? applied : skipped).push(d);
+          }
+        }
+      } catch (e) {
+        this.logger.warn(`[schema-drift] failed to reconcile '${table}'`, e?.message ?? e);
+        for (const d of ents) if (!applied.includes(d)) skipped.push(d);
+      }
+    }
+    return { applied, skipped };
+  }
+  /** Apply a single drift op in place (Postgres / MySQL). Returns false if unsupported. */
+  async applyDriftOpInPlace(op) {
+    const { table, column } = op;
+    if (this.isPostgres) {
+      switch (op.type) {
+        case "relax_not_null":
+          await this.knex.raw("ALTER TABLE ?? ALTER COLUMN ?? DROP NOT NULL", [table, column]);
+          return true;
+        case "tighten_not_null":
+          await this.knex.raw("ALTER TABLE ?? ALTER COLUMN ?? SET NOT NULL", [table, column]);
+          return true;
+        case "widen_varchar":
+        case "narrow_varchar":
+          await this.knex.raw(`ALTER TABLE ?? ALTER COLUMN ?? TYPE varchar(${op.to})`, [table, column]);
+          return true;
+        case "drop_column":
+          await this.knex.raw("ALTER TABLE ?? DROP COLUMN ??", [table, column]);
+          return true;
+      }
+    }
+    if (this.isMysql) {
+      const info = await this.knex(table).columnInfo();
+      const ci = info?.[column];
+      const colType = ci?.type ? /char/i.test(ci.type) && ci.maxLength ? `${ci.type}(${ci.maxLength})` : ci.type : void 0;
+      switch (op.type) {
+        case "relax_not_null":
+          if (!colType) return false;
+          await this.knex.raw(`ALTER TABLE ?? MODIFY ?? ${colType} NULL`, [table, column]);
+          return true;
+        case "tighten_not_null":
+          if (!colType) return false;
+          await this.knex.raw(`ALTER TABLE ?? MODIFY ?? ${colType} NOT NULL`, [table, column]);
+          return true;
+        case "widen_varchar":
+        case "narrow_varchar":
+          await this.knex.raw(`ALTER TABLE ?? MODIFY ?? varchar(${op.to})`, [table, column]);
+          return true;
+        case "drop_column":
+          await this.knex.raw("ALTER TABLE ?? DROP COLUMN ??", [table, column]);
+          return true;
+      }
+    }
+    this.logger.warn(`[schema-drift] ${op.type} on ${table}.${column} is unsupported on dialect '${this.dialectName}' \u2014 skipped`);
+    return false;
+  }
+  /**
+   * 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).
+   */
+  async rebuildSqliteTablePatched(table, ents) {
+    const relax = /* @__PURE__ */ new Set();
+    const tighten = /* @__PURE__ */ new Set();
+    const drop = /* @__PURE__ */ new Set();
+    for (const e of ents) {
+      if (e.op.type === "relax_not_null") relax.add(e.op.column);
+      else if (e.op.type === "tighten_not_null") tighten.add(e.op.column);
+      else if (e.op.type === "drop_column") drop.add(e.op.column);
+    }
+    const physical = await this.introspectColumns(table);
+    const kept = physical.filter((c) => !drop.has(c.name));
+    const keptNames = kept.map((c) => c.name);
+    const fields = this.managedObjectFields.get(table) ?? {};
+    const tmp = `__os_mig_${table}`;
+    await this.knex.raw("PRAGMA foreign_keys = OFF");
+    try {
+      await this.knex.transaction(async (trx) => {
+        await trx.schema.dropTableIfExists(tmp);
+        await trx.schema.createTable(tmp, (t) => {
+          for (const c of kept) {
+            const col = this.buildRebuiltColumn(t, c);
+            if (!col) continue;
+            const nullable = relax.has(c.name) ? true : tighten.has(c.name) ? false : c.nullable;
+            if (!nullable && c.name !== "id") col.notNullable();
+            if (c.name === "created_at" || c.name === "updated_at") col.defaultTo(this.knex.fn.now());
+          }
+        });
+        const colList = keptNames.map((n) => `"${n}"`).join(", ");
+        await trx.raw(`INSERT INTO "${tmp}" (${colList}) SELECT ${colList} FROM "${table}"`);
+        await trx.schema.dropTable(table);
+        await trx.schema.renameTable(tmp, table);
+      });
+    } finally {
+      await this.knex.raw("PRAGMA foreign_keys = ON");
+    }
+    try {
+      const keptSet = new Set(keptNames);
+      for (const [name, field] of Object.entries(fields)) {
+        if (field?.unique && keptSet.has(name)) {
+          const idx = `uniq_${table}_${name}`;
+          await this.knex.raw("CREATE UNIQUE INDEX IF NOT EXISTS ?? ON ?? (??)", [idx, table, name]);
+        }
+      }
+      const declared = this.managedObjectIndexes.get(table);
+      if (Array.isArray(declared) && declared.length > 0) {
+        await this.syncDeclaredIndexes(table, declared, keptSet);
+      }
+    } catch (e) {
+      this.logger.warn(`[schema-drift] could not fully recreate indexes for '${table}' after rebuild`, e?.message ?? e);
+    }
+  }
+  /** Map an introspected SQLite column to a knex builder for the rebuilt table. */
+  buildRebuiltColumn(t, c) {
+    if (c.name === "id") return t.string("id").primary();
+    const ty = (c.type || "text").toLowerCase();
+    if (ty.includes("int")) return t.integer(c.name);
+    if (/(real|floa|doub|num|dec)/.test(ty)) return t.float(c.name);
+    if (ty.includes("bool")) return t.boolean(c.name);
+    if (ty.includes("datetime") || ty.includes("timestamp")) return t.timestamp(c.name);
+    if (ty === "date") return t.date(c.name);
+    if (ty === "time") return t.time(c.name);
+    if (ty.includes("json")) return t.json(c.name);
+    if (ty.includes("blob") || ty.includes("binary")) return t.binary(c.name);
+    if (ty.includes("text")) return t.text(c.name);
+    return t.string(c.name);
+  }
   /**
    * Build a deterministic index name for a declared index so repeated
    * `initObjects` runs converge on the same identifier (and can detect an
@@ -1194,7 +1678,12 @@ var SqlDriver = class {
     return this.knex;
   }
   getBuilder(object, options) {
-    let builder = this.knex(object);
+    const physical = this.physicalTableByObject[object] ?? object;
+    let builder = this.knex(physical);
+    const remoteSchema = this.physicalSchemaByObject[object];
+    if (remoteSchema) {
+      builder = builder.withSchema(remoteSchema);
+    }
     if (options?.transaction) {
       builder = builder.transacting(options.transaction);
     }
@@ -1293,6 +1782,20 @@ var SqlDriver = class {
     if (typeof t === "string") return t;
     return 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.
+   */
+  coercionKey(builder) {
+    const physical = this.tableNameForBuilder(builder);
+    if (physical == null) return null;
+    return this.objectByPhysicalTable[physical] ?? physical;
+  }
   /**
    * 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
@@ -1386,7 +1889,7 @@ var SqlDriver = class {
   }
   applyFilters(builder, filters) {
     if (!filters) return;
-    const table = this.tableNameForBuilder(builder);
+    const table = this.coercionKey(builder);
     if (!Array.isArray(filters) && typeof filters === "object") {
       const hasMongoOperators = Object.keys(filters).some(
         (k) => k.startsWith("$") || typeof filters[k] === "object" && filters[k] !== null && Object.keys(filters[k]).some((op) => op.startsWith("$"))
@@ -1397,7 +1900,7 @@ var SqlDriver = class {
       }
       for (const [key, value] of Object.entries(filters)) {
         if (["limit", "offset", "fields", "orderBy"].includes(key)) continue;
-        builder.where(key, this.coerceFilterValue(table, key, value));
+        builder.where(this.remoteColumn(table, key, key), this.coerceFilterValue(table, key, value));
       }
       return;
     }
@@ -1413,8 +1916,9 @@ var SqlDriver = class {
         const [fieldRaw, op, value] = item;
         const isCriterion = typeof fieldRaw === "string" && typeof op === "string";
         if (isCriterion) {
-          const field = this.mapSortField(fieldRaw);
-          const coerced = this.coerceFilterValue(table, field, value);
+          const localField = this.mapSortField(fieldRaw);
+          const field = this.remoteColumn(table, fieldRaw, localField);
+          const coerced = this.coerceFilterValue(table, localField, value);
           const apply = (b) => {
             const method = nextJoin === "or" ? "orWhere" : "where";
             const methodIn = nextJoin === "or" ? "orWhereIn" : "whereIn";
@@ -1466,7 +1970,7 @@ var SqlDriver = class {
   }
   applyFilterCondition(builder, condition, logicalOp = "and", tableHint) {
     if (!condition || typeof condition !== "object") return;
-    const table = tableHint ?? this.tableNameForBuilder(builder);
+    const table = tableHint ?? this.coercionKey(builder);
     for (const [key, value] of Object.entries(condition)) {
       if (key === "$and" && Array.isArray(value)) {
         builder.where((qb) => {
@@ -1486,10 +1990,11 @@ var SqlDriver = class {
           }
         });
       } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-        const field = this.mapSortField(key);
+        const localField = this.mapSortField(key);
+        const field = this.remoteColumn(table, key, localField);
         for (const [op, opValue] of Object.entries(value)) {
           const method = logicalOp === "or" ? "orWhere" : "where";
-          const coerced = this.coerceFilterValue(table, field, opValue);
+          const coerced = this.coerceFilterValue(table, localField, opValue);
           switch (op) {
             case "$eq":
               builder[method](field, coerced);
@@ -1527,9 +2032,10 @@ var SqlDriver = class {
           }
         }
       } else {
-        const field = this.mapSortField(key);
+        const localField = this.mapSortField(key);
+        const field = this.remoteColumn(table, key, localField);
         const method = logicalOp === "or" ? "orWhere" : "where";
-        builder[method](field, this.coerceFilterValue(table, field, value));
+        builder[method](field, this.coerceFilterValue(table, localField, value));
       }
     }
   }
@@ -1539,6 +2045,28 @@ var SqlDriver = class {
     if (field === "updatedAt") return "updated_at";
     return field;
   }
+  /**
+   * 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.
+   */
+  remoteColumn(object, field, fallback) {
+    const m = object ? this.fieldColumnByObject[object] : void 0;
+    return m && m[field] || fallback;
+  }
+  /**
+   * 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).
+   */
+  applyWriteColumnMap(object, data) {
+    const m = this.fieldColumnByObject[object];
+    if (!m || !data || typeof data !== "object") return data;
+    const out = {};
+    for (const [k, v] of Object.entries(data)) out[m[k] ?? k] = v;
+    return out;
+  }
   mapAggregateFunc(func) {
     switch (func) {
       case "count":
@@ -1795,6 +2323,15 @@ var SqlDriver = class {
   }
   formatOutput(object, data) {
     if (!data) return data;
+    const colToField = this.columnFieldByObject[object];
+    if (colToField && typeof data === "object") {
+      for (const [remoteCol, localField] of Object.entries(colToField)) {
+        if (remoteCol !== localField && Object.prototype.hasOwnProperty.call(data, remoteCol)) {
+          data[localField] = data[remoteCol];
+          delete data[remoteCol];
+        }
+      }
+    }
     if (this.isSqlite) {
       const jsonFields = this.jsonFields[object];
       if (jsonFields && jsonFields.length > 0) {
@@ -2067,6 +2604,10 @@ var index_default = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  SqlDriver
+  BUILTIN_COLUMNS,
+  SqlDriver,
+  diffManagedTable,
+  driftKey,
+  fieldHasColumn
 });
 //# sourceMappingURL=index.js.map