@objectstack/driver-sql 9.10.0 → 10.0.0

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/sql-driver.ts
+var import_data = require("@objectstack/spec/data");
 var import_system = require("@objectstack/spec/system");
 var import_shared = require("@objectstack/spec/shared");
 var import_knex = __toESM(require("knex"));
@@ -85,6 +86,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.
@@ -103,6 +118,14 @@ var SqlDriver = class {
     this.autoNumberFields = {};
     /** Whether the sequences table has been ensured this process. */
     this.sequencesTableReady = false;
+    /**
+     * Whether `_objectstack_sequences` is the current `key_hash`-keyed shape.
+     * Set on a fresh create or a successful in-place migration. If a legacy table
+     * could NOT be migrated, this stays false: fixed-prefix sequences (empty
+     * scope) keep working via the legacy `(object, tenant_id, field)` key, while a
+     * per-scope write raises an actionable error rather than corrupting counters.
+     */
+    this.sequencesHasKeyHash = false;
     /** In-flight ensure promise; deduplicates concurrent first calls. */
     this.sequencesTableEnsurePromise = null;
     /**
@@ -301,6 +324,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 {
@@ -326,7 +356,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");
           }
         }
       }
@@ -403,13 +433,22 @@ 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]);
   }
   /**
    * Ensure the sequence-counter table exists. Idempotent and cheap after
    * the first call (cached via `sequencesTableReady`).
+   *
+   * The row key is `key_hash` — a SHA-256 of `(object, tenant_id, field, scope)`
+   * where `scope` is the rendered autonumber prefix (date/field tokens before
+   * the `{0000}` slot), so a new day/group/parent starts a fresh counter. A
+   * single 64-char hashed primary key (rather than the four raw columns, which
+   * blow past MySQL's 3072-byte index limit under utf8mb4 and bound how long a
+   * `{field}` scope may be) keys every dialect uniformly and lets `scope` be a
+   * generous non-indexed column. Fixed-prefix formats use the empty scope and
+   * keep their single global counter (backward compatible).
    */
   async ensureSequencesTable() {
     if (this.sequencesTableReady) return;
@@ -421,18 +460,15 @@ var SqlDriver = class {
       const exists = await this.knex.schema.hasTable(SEQUENCES_TABLE);
       if (!exists) {
         try {
-          await this.knex.schema.createTable(SEQUENCES_TABLE, (t) => {
-            t.string("object").notNullable();
-            t.string("tenant_id").notNullable();
-            t.string("field").notNullable();
-            t.bigInteger("last_value").notNullable().defaultTo(0);
-            t.timestamp("updated_at").defaultTo(this.knex.fn.now());
-            t.primary(["object", "tenant_id", "field"]);
-          });
+          await this.createSequencesTable(SEQUENCES_TABLE);
+          this.sequencesHasKeyHash = true;
         } catch (err) {
           const stillMissing = !await this.knex.schema.hasTable(SEQUENCES_TABLE);
           if (stillMissing) throw err;
+          await this.ensureSequencesKeyHashShape();
         }
+      } else {
+        await this.ensureSequencesKeyHashShape();
       }
       this.sequencesTableReady = true;
     })();
@@ -442,6 +478,71 @@ var SqlDriver = class {
       this.sequencesTableEnsurePromise = null;
     }
   }
+  /** SHA-256 of the composite counter key — the table's single-column PK. */
+  sequenceKeyHash(object, tenantId, field, scope) {
+    return (0, import_node_crypto.createHash)("sha256").update(`${object}${tenantId}${field}${scope}`).digest("hex");
+  }
+  /** Create the current `key_hash`-keyed sequences table shape. */
+  async createSequencesTable(table) {
+    await this.knex.schema.createTable(table, (t) => {
+      t.string("key_hash", 64).notNullable().primary();
+      t.string("object").notNullable();
+      t.string("tenant_id").notNullable();
+      t.string("field").notNullable();
+      t.string("scope", 1024).notNullable().defaultTo("");
+      t.bigInteger("last_value").notNullable().defaultTo(0);
+      t.timestamp("updated_at").defaultTo(this.knex.fn.now());
+    });
+  }
+  /**
+   * Migrate a pre-existing `_objectstack_sequences` table to the current
+   * `key_hash`-keyed shape. Handles both the original 3-column table (no
+   * `scope`) and an interim 4-column `(object, tenant_id, field, scope)` table:
+   * every legacy row is read, its `key_hash` computed in app code (no portable
+   * SQL hash exists), and re-inserted into a freshly built table that then
+   * replaces the original. Idempotent — a no-op once `key_hash` is present.
+   *
+   * If the rebuild fails, `sequencesHasKeyHash` stays false: fixed-prefix
+   * sequences keep working via the legacy key and per-scope writes error
+   * actionably (see getNextSequenceValue), rather than corrupting data.
+   */
+  async ensureSequencesKeyHashShape() {
+    if (await this.knex.schema.hasColumn(SEQUENCES_TABLE, "key_hash")) {
+      this.sequencesHasKeyHash = true;
+      return;
+    }
+    const hasScope = await this.knex.schema.hasColumn(SEQUENCES_TABLE, "scope");
+    const TMP = `${SEQUENCES_TABLE}__rebuild`;
+    try {
+      const rows = await this.knex(SEQUENCES_TABLE).select("*");
+      await this.knex.schema.dropTableIfExists(TMP);
+      await this.createSequencesTable(TMP);
+      const migrated = rows.map((r) => {
+        const scope = hasScope && r.scope != null ? String(r.scope) : "";
+        return {
+          key_hash: this.sequenceKeyHash(String(r.object), String(r.tenant_id), String(r.field), scope),
+          object: r.object,
+          tenant_id: r.tenant_id,
+          field: r.field,
+          scope,
+          last_value: r.last_value ?? 0,
+          updated_at: r.updated_at ?? this.knex.fn.now()
+        };
+      });
+      if (migrated.length > 0) await this.knex(TMP).insert(migrated);
+      await this.knex.schema.dropTable(SEQUENCES_TABLE);
+      await this.knex.schema.renameTable(TMP, SEQUENCES_TABLE);
+      this.sequencesHasKeyHash = true;
+    } catch (err) {
+      this.sequencesHasKeyHash = false;
+      await this.knex.schema.dropTableIfExists(TMP).catch(() => {
+      });
+      this.logger.warn(
+        `[autonumber] Failed to migrate ${SEQUENCES_TABLE} to the key_hash shape. Fixed-prefix autonumbers keep working; date/{field}/per-parent formats will error until the table is migrated.`,
+        { error: String(err) }
+      );
+    }
+  }
   /**
    * Bootstrap helper: scan the data table for the highest numeric suffix
    * matching `prefix` (optionally scoped to a tenant). Used the first time
@@ -479,10 +580,16 @@ var SqlDriver = class {
    * Gaps are tolerated by design — a rolled-back insert "burns" a number,
    * matching standard sequence semantics.
    */
-  async getNextSequenceValue(object, tableName, field, prefix, tenantField, tenantId, parentTrx) {
+  async getNextSequenceValue(object, tableName, field, prefix, tenantField, tenantId, parentTrx, scope = "") {
     await this.ensureSequencesTable();
     const resolvedTenantId = tenantField && tenantId ? String(tenantId) : GLOBAL_TENANT;
-    const key = { object: tableName, tenant_id: resolvedTenantId, field };
+    if (scope !== "" && !this.sequencesHasKeyHash) {
+      throw new Error(
+        `Cannot generate a per-scope autonumber for "${object}.${field}": the ${SEQUENCES_TABLE} table is still the legacy shape. Migrate it to the key_hash shape before using date/{field}/per-parent formats.`
+      );
+    }
+    const key = this.sequencesHasKeyHash ? { key_hash: this.sequenceKeyHash(tableName, resolvedTenantId, field, scope) } : { object: tableName, tenant_id: resolvedTenantId, field };
+    const insertRow = this.sequencesHasKeyHash ? { ...key, object: tableName, tenant_id: resolvedTenantId, field, scope } : { ...key };
     const runner = parentTrx ?? this.knex;
     return runner.transaction(async (trx) => {
       let existing;
@@ -502,7 +609,7 @@ var SqlDriver = class {
         );
         const initial = seedMax + 1;
         try {
-          await trx(SEQUENCES_TABLE).insert({ ...key, last_value: initial });
+          await trx(SEQUENCES_TABLE).insert({ ...insertRow, last_value: initial });
           return initial;
         } catch (err) {
           existing = await trx(SEQUENCES_TABLE).where(key).forUpdate().first();
@@ -515,38 +622,50 @@ var SqlDriver = class {
     });
   }
   /**
-   * For each `auto_number` field on the object that the caller did not
-   * provide a value for, reserve the next sequence value scoped to the
-   * record's tenant (or globally if the object has no tenant field) and
-   * render `prefix + zero-padded(value)`.
+   * For each `auto_number` field the caller left empty, render the format and
+   * reserve the next counter value. The counter is scoped to the rendered
+   * prefix (date tokens like `{YYYYMMDD}` in the request's business timezone,
+   * plus `{field}` interpolation from the row), so it resets per period/group;
+   * the full rendered prefix bootstraps the counter from existing data, and the
+   * 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;
+    const now = /* @__PURE__ */ new Date();
     for (const cfg of cfgs) {
       if (row[cfg.name] !== void 0 && row[cfg.name] !== null && row[cfg.name] !== "") continue;
+      const missing = (0, import_data.missingFieldValues)(cfg.tokens, row);
+      if (missing.length > 0) {
+        throw new Error(
+          `Cannot generate autonumber "${object}.${cfg.name}" (format "${cfg.format}"): referenced field(s) [${missing.join(", ")}] are empty on the record. Fields interpolated into an autonumber format must be set before the record is created.`
+        );
+      }
       const rowTenant = cfg.tenantField ? row[cfg.tenantField] : void 0;
       const optTenant = options?.tenantId;
       const tenantId = rowTenant != null && rowTenant !== "" ? String(rowTenant) : optTenant != null && optTenant !== "" ? String(optTenant) : null;
+      const probe = (0, import_data.renderAutonumber)({ tokens: cfg.tokens, seq: 0, record: row, now, timezone });
       const next = await this.getNextSequenceValue(
         object,
         tableName,
         cfg.name,
-        cfg.prefix,
+        probe.prefix,
         cfg.tenantField,
         tenantId,
-        parentTrx
+        parentTrx,
+        probe.scope
       );
-      row[cfg.name] = `${cfg.prefix}${String(next).padStart(cfg.padWidth, "0")}`;
+      row[cfg.name] = (0, import_data.renderAutonumber)({ tokens: cfg.tokens, seq: next, record: row, now, timezone }).value;
     }
   }
   async update(object, id, data, options) {
     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();
@@ -572,7 +691,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();
@@ -855,6 +974,89 @@ 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");
@@ -898,10 +1100,8 @@ var SqlDriver = class {
           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}";
-            const m = fmt.match(/\{(0+)\}/);
-            const padWidth = m ? m[1].length : 4;
-            const prefix = m ? fmt.slice(0, m.index ?? 0) : fmt;
-            autoNumberCols.push({ name, format: fmt, prefix, padWidth, tenantField });
+            const tokens = (0, import_data.parseAutonumberFormat)(fmt);
+            autoNumberCols.push({ name, format: fmt, tokens, tenantField });
           }
         }
       }
@@ -1098,7 +1298,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);
     }
@@ -1197,6 +1402,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
@@ -1290,7 +1509,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("$"))
@@ -1301,7 +1520,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;
     }
@@ -1317,8 +1536,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";
@@ -1370,7 +1590,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) => {
@@ -1390,10 +1610,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);
@@ -1431,9 +1652,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));
       }
     }
   }
@@ -1443,6 +1665,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":
@@ -1699,6 +1943,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) {