tina4-nodejs 3.13.133 → 3.13.134

package/packages/orm/src/baseModel.ts

@@ -783,204 +783,26 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
 
     const db = ModelClass.getDb();
-    const pk = ModelClass.getPkField();
-    const pkCol = ModelClass.getPkColumn();
+    const pk = primaryKeyFields(ModelClass)[0];
+    const pkCol = ModelClass.getDbColumn(pk);
     const pkValue = this[pk];
     const pkField = (ModelClass.fields as Record<string, FieldDefinition>)[pk];
     this._relCache = {}; // Clear relationship cache on save
 
-    // v3.13.11 (issue #50.2): for non-auto-increment PKs (user-supplied
-    // string IDs like "GC-100"), decide INSERT vs UPDATE on row
-    // existence, not on whether the PK is set. Pre-v3.13.11 a
-    // natural-key save() always chose UPDATE → matched zero rows →
-    // silently returned success without inserting anything.
-    //
-    // Auto-increment behaviour is unchanged: pkValue is null/undefined
-    // → INSERT, pkValue is set → UPDATE.
-    let isUpdate = false;
-    if (pkValue !== undefined && pkValue !== null) {
-      if (pkField?.autoIncrement) {
-        isUpdate = true;
-      } else {
-        try {
-          // This asked exists(pkValue), which tests only the FIRST key column.
-          // On a composite key that is true for any row sharing that column, so
-          // inserting a genuinely NEW row was decided to be an UPDATE and
-          // silently OVERWROTE a different row: saving (acme, a2) rewrote
-          // (acme, a1). The check has to name the whole key, like the write
-          // that follows it.
-          const probe = this.pkWhere();
-          if (ModelClass.getPkFields().length > 1 && probe.sql) {
-            const found = await db.fetch(
-              `SELECT 1 AS present FROM ${ModelClass.tableName} WHERE ${probe.sql}`,
-              probe.params,
-              1,
-            );
-            isUpdate = (found as unknown as { length: number }).length > 0;
-          } else {
-            isUpdate = await ModelClass.exists(pkValue);
-          }
-        } catch {
-          // If we can't tell (e.g. table doesn't exist yet), fall back
-          // to INSERT so the user sees the real driver error rather
-          // than a silent no-op.
-          isUpdate = false;
-        }
-      }
-    }
-
-    // ── Canonical #2: validate() is enforced. An invalid model never reaches
-    // the driver — fail loud (log + lastError), return false. Feature 19: on an
-    // UPDATE the partial-update mode (isUpdate) is passed so an unset field is
-    // not spuriously "required" (the persisted row already carries it), while a
-    // field that IS present stays held to its type/length/pattern/range rules.
-    const errors = this.validate(isUpdate);
-    if (errors.length > 0) {
-      this.lastError = errors.join("; ");
-      Log.error(
-        `${ModelClass.name}.save() refused: validation failed for table ` +
-          `'${ModelClass.tableName}' — ${this.lastError}`,
-      );
-      return false;
-    }
+    const isUpdate = await resolveSaveMode(this, ModelClass, db, pk, pkValue, pkField);
+    if (!validateBeforeSave(this, ModelClass, isUpdate)) return false;
 
     await adapterStartTransaction(db);
     try {
       if (isUpdate) {
-        // Update — keyed on the WHOLE primary key (see pkWhere).
-        const updateFields = Object.entries(ModelClass.fields).filter(
-          ([name, def]) => !def.primaryKey && this[name] !== undefined,
-        );
-        if (updateFields.length === 0) { await adapterCommit(db); return this; }
-
-        const setClause = updateFields.map(([k]) => `"${ModelClass.getDbColumn(k)}" = ?`).join(", ");
-        // The key params come from pkWhere() below; appending pkValue here too
-        // would bind the first key column twice and shift every placeholder.
-        const values = [...updateFields.map(([k, def]) => toDbFieldValue(def, this[k]))];
-
-        // Keyed on the WHOLE primary key: one column of a composite key matches
-        // every row sharing that value.
-        const uw = this.pkWhere();
-        values.push(...uw.params);
-        await adapterExecute(db, `UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE ${uw.sql}`, values);
+        await executeModelUpdate(this, ModelClass, db);
       } else {
-        // Insert
-        //
-        // #165: an INSERT must OMIT a column the caller never assigned so a
-        // `NOT NULL DEFAULT <x>` column gets its DB default instead of an
-        // explicit NULL that violates the constraint. In TS an unset column is
-        // `undefined` (the constructor only seeds a field that declares a
-        // non-null ORM default — everything else stays `undefined`), so the
-        // `this[name] !== undefined` filter already drops unset columns; a
-        // value the caller set to `null` IS included and written as an explicit
-        // NULL (parity with Python's _assigned_fields split — JS distinguishes
-        // undefined-unset from null-explicit natively). A resolved non-null ORM
-        // default is still written (no regression).
-        const insertFields = Object.entries(ModelClass.fields).filter(
-          ([name, def]) => !(def.primaryKey && def.autoIncrement) && this[name] !== undefined,
-        );
-
-        // For auto-increment PKs on engines that need it (PostgreSQL),
-        // RETURNING the PK column lets us read the engine-assigned id back.
-        // SQLite ignores the RETURNING clause harmlessly (it supports it
-        // since 3.35) and we still prefer its lastInsertRowid; for other
-        // engines extractLastInsertId() reads rows[0].id.
-        const wantReturning = pkField?.autoIncrement && db.constructor.name !== "SQLiteAdapter";
-        const returningClause = wantReturning ? ` RETURNING "${pkCol}"` : "";
-
-        let insertSql: string;
-        let values: unknown[];
-        if (insertFields.length === 0) {
-          // #165: every insertable column was left unset — let the DB apply ALL
-          // its column defaults rather than emitting an empty column list
-          // (`() VALUES ()` is invalid on SQLite/PostgreSQL/Firebird/MSSQL, which
-          // spell the all-defaults insert `DEFAULT VALUES`; only MySQL uses the
-          // empty-parens form). Mirrors the Python master's engine split.
-          insertSql =
-            (db.constructor.name === "MysqlAdapter"
-              ? `INSERT INTO "${ModelClass.tableName}" () VALUES ()`
-              : `INSERT INTO "${ModelClass.tableName}" DEFAULT VALUES`) + returningClause;
-          values = [];
-        } else {
-          const columns = insertFields.map(([k]) => `"${ModelClass.getDbColumn(k)}"`).join(", ");
-          const placeholders = insertFields.map(() => "?").join(", ");
-          values = insertFields.map(([k, def]) => toDbFieldValue(def, this[k]));
-          insertSql =
-            `INSERT INTO "${ModelClass.tableName}" (${columns}) VALUES (${placeholders})` +
-            returningClause;
-        }
-
-        const result = await adapterExecute(db, insertSql, values);
-
-        // v3.13.11 (issue #50.2): only adopt the engine-assigned ID
-        // for auto-increment PKs. A natural-key PK was already set by
-        // the caller; don't overwrite it with the driver's last_id.
-        if (pkField?.autoIncrement) {
-          // RETURNING result: pg puts it in rows[0][pkCol]; normalise here.
-          // string is allowed for a non-integer PK surfaced by lastInsertId()
-          // (e.g. a PostgreSQL UUID PK) — #256.
-          let newId: number | bigint | string | null = extractLastInsertId(result);
-          if (newId === null && result && typeof result === "object") {
-            const rows = (result as any).rows;
-            if (Array.isArray(rows) && rows[0]) {
-              newId = rows[0][pkCol] ?? rows[0].id ?? null;
-            }
-          }
-          if (newId === null) {
-            // Fall back to the adapter's tracked last id (MySQL/MSSQL).
-            newId = db.lastInsertId();
-          }
-          if (newId !== null && newId !== undefined) {
-            this[pk] = newId;
-          }
-        }
+        await executeModelInsert(this, ModelClass, db, pk, pkCol, pkField);
       }
       await adapterCommit(db);
-    } catch (e: any) {
+    } catch (e: unknown) {
       await adapterRollback(db);
-      // ── Canonical #1: fail loud, never silent. Keep the false return
-      // contract, but capture the REAL cause (prefer the adapter's
-      // getError()/getLastError() when present, falling back to the exception
-      // text) on this.lastError so it survives, and log it with model/table
-      // context. ──
-      const adapterErr =
-        typeof (db as any).getError === "function" ? (db as any).getError() :
-        typeof (db as any).getLastError === "function" ? (db as any).getLastError() :
-        null;
-      let cause = adapterErr || e?.message || String(e);
-      // ── DX hint (v3.13.60 parity with the Python master): turn a bare driver
-      // error into an actionable fix for the two commonest ORM write footguns.
-      // Matched case-insensitively (SQLite via node:sqlite: "no such table" /
-      // "no such column: is_deleted" / "has no column named is_deleted";
-      // Postgres/MySQL: "does not exist" / "doesn't exist" / "unknown column").
-      // Any OTHER error keeps its raw cause untouched so an unrelated failure
-      // (NOT NULL, duplicate PK) is never masked. ──
-      const low = cause.toLowerCase();
-      if (
-        ModelClass.softDelete && low.includes("is_deleted") &&
-        (low.includes("no such column") || low.includes("has no column") ||
-          low.includes("does not exist") || low.includes("doesn't exist") ||
-          low.includes("unknown column"))
-      ) {
-        cause +=
-          " — softDelete=true needs an is_deleted column; declare it " +
-          "(is_deleted: { type: 'integer', default: 0 }), boot the server so " +
-          "syncModels() adds it, or run a migration";
-      } else if (
-        low.includes("no such table") ||
-        ((low.includes("does not exist") || low.includes("doesn't exist")) &&
-          !low.includes("column"))
-      ) {
-        cause +=
-          ` — table '${ModelClass.tableName}' does not exist; call ` +
-          `${ModelClass.name}.createTable() or run a migration`;
-      }
-      this.lastError = cause;
-      Log.error(
-        `${ModelClass.name}.save() failed for table ` +
-          `'${ModelClass.tableName}': ${this.lastError}`,
-      );
-      return false;
+      return saveDatabaseFailure(this, ModelClass, db, e);
     }
     // Success — clear any previously-recorded error.
     this.lastError = null;
@@ -1045,88 +867,9 @@ export class BaseModel {
    */
   toDict(include?: string[], case_: "camel" | "snake" = "camel"): Record<string, unknown> {
     const ModelClass = this.constructor as typeof BaseModel;
-    const result: Record<string, unknown> = {};
-    for (const key of Object.keys(ModelClass.fields)) {
-      if (this[key] !== undefined) {
-        const outKey = case_ === "snake" ? (ModelClass.fieldMapping[key] ?? key) : key;
-        result[outKey] = this[key] instanceof Point ? (this[key] as Point).geojson : this[key];
-      }
-    }
-    // Include soft delete field
-    if (ModelClass.softDelete && this.is_deleted !== undefined) {
-      result.is_deleted = this.is_deleted;
-    }
-
-    if (include) {
-      // Group includes: top-level and nested
-      const topLevel: Record<string, string[]> = {};
-      for (const inc of include) {
-        const parts = inc.split(".", 2);
-        const relName = parts[0];
-        if (!topLevel[relName]) {
-          topLevel[relName] = [];
-        }
-        if (parts.length > 1) {
-          topLevel[relName].push(parts[1]);
-        }
-      }
-
-      for (const [relName, nested] of Object.entries(topLevel)) {
-        // toDict stays synchronous (used in routes, templates, serialization).
-        // Relationships must be eager-loaded first (await Model._eagerLoad / the
-        // include arg on find/all/where) which fills _relCache. A relation that
-        // isn't cached is simply skipped here — async lazy-load on a sync
-        // serializer is not possible after the Option A async refactor.
-        const data = this._relCache[relName];
-        if (data === undefined) {
-          // LOAD-NODE-SERIALIZE-OMIT (feature 26, 3.13.99): the omission used
-          // to be completely silent — a developer who forgot `include` on the
-          // finder that produced this instance got a serialized object
-          // missing the relation with no signal at all. Warn (never throw —
-          // serialization must keep working) naming the model, the relation,
-          // and the fix, so the gap is visible instead of a quiet data loss.
-          Log.warning(
-            `${ModelClass.name}.toDict(): relation "${relName}" was requested via ` +
-              `include but was never eager-loaded (a synchronous serializer cannot ` +
-              `lazy-load it), so it is OMITTED from the result. Pass ` +
-              `include: ["${relName}"] to the finder (find/all/where/select/load) ` +
-              `that produced this instance.`,
-          );
-          continue;
-        }
-        if (data === null || data === undefined) {
-          result[relName] = null;
-        } else if (Array.isArray(data)) {
-          result[relName] = (data as BaseModel[]).map((r) =>
-            r.toDict(nested.length > 0 ? nested : undefined, case_),
-          );
-        } else if (typeof (data as BaseModel).toDict === "function") {
-          result[relName] = (data as BaseModel).toDict(
-            nested.length > 0 ? nested : undefined, case_,
-          );
-        }
-      }
-    } else {
-      // Legacy: include any relationship data already loaded on instance
-      if (ModelClass.hasOne) {
-        for (const rel of ModelClass.hasOne) {
-          const relKey = rel.model.toLowerCase();
-          if (this[relKey] !== undefined) {
-            result[relKey] = this[relKey];
-          }
-        }
-      }
-      if (ModelClass.hasMany) {
-        for (const rel of ModelClass.hasMany) {
-          const base = rel.model.toLowerCase();
-          const relKey = _pluralRelKeys() ? base + "s" : base;
-          if (this[relKey] !== undefined) {
-            result[relKey] = this[relKey];
-          }
-        }
-      }
-    }
-
+    const result = serializeModelFields(this, ModelClass, case_);
+    if (include) serializeIncludedRelations(this, ModelClass, result, include, case_);
+    else serializeLoadedRelations(this, ModelClass, result);
     return result;
   }
 
@@ -1209,99 +952,16 @@ export class BaseModel {
     if (pointFields.length > 0) SQLTranslator.requireSpatial(engine, "PointField");
     if (await adapterTableExists(db, this.tableName)) return this.createSpatialIndexes(db, pointFields);
 
-    // Prefer the adapter's createTable — every adapter implements it and the
-    // async variants (PostgreSQL/MySQL/MSSQL/Firebird) emit engine-aware DDL
-    // (datetime → TIMESTAMP, boolean → native BOOLEAN, auto-increment → SERIAL
-    // etc. on PG). Remap field keys to DB column names if fieldMapping exists.
-    if (typeof db.createTable === "function" || typeof (db as any).createTableAsync === "function") {
-      const mappedFields: Record<string, FieldDefinition> = {};
-      for (const [fieldName, def] of Object.entries(this.fields)) {
-        const dbCol = this.getDbColumn(fieldName);
-        // A callable default (e.g. `default: () => new Date()`) is resolved per-row
-        // in the constructor; it must NOT reach the adapter DDL builder, where it
-        // stringifies to an invalid `DEFAULT () => ...` and silently fails table
-        // creation. Drop the default key so no adapter emits it (parity with Python #61).
-        if (typeof def.default === "function") {
-          const { default: _callableDefault, ...rest } = def;
-          mappedFields[dbCol] = rest;
-        } else {
-          mappedFields[dbCol] = def;
-        }
-      }
-      // SOFTDEL-DEC-02: a softDelete model needs an is_deleted flag column, but
-      // createTable() built the schema from DECLARED fields only — so a
-      // softDelete = true model that never declared is_deleted produced a table
-      // with NO such column, and every soft-delete read/write then errored on
-      // the missing column. syncModels() adds it on boot; createTable() must too.
-      // Inject it (INTEGER 0/1, default 0) unless the model already declares it.
-      if (this.softDelete && !("is_deleted" in mappedFields)) {
-        mappedFields["is_deleted"] = { type: "integer", default: 0 };
-      }
+    if (hasAdapterCreateTable(db)) {
+      const mappedFields = mappedCreateTableFields(this);
+      addSoftDeleteField(this, mappedFields);
       await adapterCreateTable(db, this.tableName, mappedFields);
       return this.createSpatialIndexes(db, pointFields);
     }
 
     // Fallback: build SQL manually (SQLite-only dialect — used only when an
     // adapter lacks createTable, which none currently do).
-    const typeMap: Record<string, string> = {
-      integer: "INTEGER",
-      string: "TEXT",
-      text: "TEXT",
-      number: "REAL",
-      numeric: "REAL",
-      boolean: "INTEGER",
-      datetime: "TEXT",
-    };
-
-    const colDefs: string[] = [];
-    for (const [fieldName, def] of Object.entries(this.fields)) {
-      const dbCol = this.getDbColumn(fieldName);
-      const sqlType = typeMap[def.type] || "TEXT";
-      const parts = [`"${dbCol}" ${sqlType}`];
-      // A COMPOSITE key is declared ONCE, at table level (below). An inline
-      // PRIMARY KEY per column is invalid DDL - SQLite, PostgreSQL and MySQL
-      // all reject two of them in one table.
-      if (def.primaryKey && this.getPkFields().length === 1) parts.push("PRIMARY KEY");
-      if (def.autoIncrement) parts.push("AUTOINCREMENT");
-      if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      // A callable default (e.g. `default: () => new Date()`) is resolved per-row
-      // in the constructor above; it must NOT be emitted into the CREATE TABLE
-      // DDL, where String(fn) stringifies to `DEFAULT () => ...` — invalid SQL
-      // that silently fails table creation (parity with Python #61).
-      if (def.default !== undefined && typeof def.default !== "function") {
-        const dv = typeof def.default === "string" ? `'${def.default}'` : String(def.default);
-        parts.push(`DEFAULT ${dv}`);
-      }
-      colDefs.push(parts.join(" "));
-    }
-
-    // SOFTDEL-DEC-02 (fallback path): inject the is_deleted flag column for a
-    // softDelete model that did not declare it, mirroring the adapter path above.
-    if (this.softDelete) {
-      const dbCols = Object.keys(this.fields).map((f) => this.getDbColumn(f));
-      if (!dbCols.includes("is_deleted")) {
-        colDefs.push(`"is_deleted" INTEGER DEFAULT 0`);
-      }
-    }
-
-    // A COMPOSITE key is declared ONCE, at table level; the per-column inline
-    // form above is suppressed for it, because two inline primary keys is
-    // invalid DDL on every engine.
-    const pkFields = this.getPkFields();
-    if (pkFields.length > 1) {
-      const pkCols = pkFields.map((f) => this.getDbColumn(f));
-      colDefs.push(`PRIMARY KEY (${pkCols.join(", ")})`);
-    }
-
-    const sql = `CREATE TABLE IF NOT EXISTS "${this.tableName}" (${colDefs.join(", ")})`;
-    await adapterStartTransaction(db);
-    try {
-      await adapterExecute(db, sql);
-      await adapterCommit(db);
-    } catch (e) {
-      await adapterRollback(db);
-      throw e;
-    }
+    await createFallbackTable(db, this);
     return true;
   }
 
@@ -1875,167 +1535,9 @@ export class BaseModel {
     // Post._processForeignKeys() never ran. _applyFkRegistry() then merges the
     // registered hasMany entries onto each model.
     BaseModel._processAllForeignKeys();
-
-    // Group includes: top-level and nested
-    const topLevel: Record<string, string[]> = {};
-    for (const inc of include) {
-      const parts = inc.split(".", 2);
-      const relName = parts[0];
-      if (!topLevel[relName]) {
-        topLevel[relName] = [];
-      }
-      if (parts.length > 1) {
-        topLevel[relName].push(parts[1]);
-      }
-    }
-
+    const topLevel = groupIncludedRelations(include);
     for (const [relName, nested] of Object.entries(topLevel)) {
-      // Find the relationship definition.
-      //
-      // Include names are resolved case-insensitively against each candidate
-      // relation. Accepted forms (for a relation to model "Post" on table "posts"):
-      //   - the model name           → "Post" / "post"
-      //   - the auto/related key     → "post" (singular) or "posts" (when
-      //                                 TINA4_ORM_PLURAL_TABLE_NAMES is enabled)
-      //   - the table name           → "posts"
-      // All matching is lower-cased so "Post", "post" and "posts" all resolve.
-      const want = relName.toLowerCase();
-      let relDef: RelationshipDefinition | undefined;
-      let relType: "hasOne" | "hasMany" | "belongsTo" | null = null;
-
-      const matchesModel = (r: RelationshipDefinition): boolean => {
-        const base = r.model.toLowerCase();
-        const related = BaseModel._modelRegistry[r.model];
-        const table = related?.tableName?.toLowerCase();
-        // Outlier F: an FK-auto-wired has-many carries its derived key
-        // (declaring class lowercased + "s", or relatedName) — match it so
-        // include: ["posts"] resolves to the wired relation regardless of the
-        // related table name.
-        const rel = r.relatedName?.toLowerCase();
-        return (
-          base === want ||
-          base + "s" === want ||
-          (rel !== undefined && rel === want) ||
-          (table !== undefined && table === want)
-        );
-      };
-
-      if (ModelClass.hasOne) {
-        relDef = ModelClass.hasOne.find(matchesModel);
-        if (relDef) relType = "hasOne";
-      }
-      if (!relDef && ModelClass.hasMany) {
-        relDef = ModelClass.hasMany.find(matchesModel);
-        if (relDef) relType = "hasMany";
-      }
-      if (!relDef && ModelClass.belongsTo) {
-        relDef = ModelClass.belongsTo.find(matchesModel);
-        if (relDef) relType = "belongsTo";
-      }
-
-      if (!relDef || !relType) {
-        // Don't silently skip — a typo'd or unknown include name is almost
-        // always a developer mistake. Surface it so it's visible.
-        Log.warning(
-          `eager-load: include "${relName}" did not match any relationship on ` +
-            `${ModelClass.name} (table "${ModelClass.tableName}"). ` +
-            `Accepted forms are the related model name, its singular/plural ` +
-            `key, or the related table name (case-insensitive).`,
-        );
-        continue;
-      }
-
-      const relatedClass = BaseModel._modelRegistry[relDef.model];
-      if (!relatedClass) continue;
-
-      const db = relatedClass.getDb();
-      const fk = relDef.foreignKey;
-
-      if (relType === "hasOne" || relType === "hasMany") {
-        const pk = ModelClass.getPkField();
-        const pkValues = instances
-          .map((inst) => inst[pk])
-          .filter((v) => v !== undefined && v !== null);
-        if (pkValues.length === 0) continue;
-
-        // REL-EAGER-UNBOUNDED: chunk the parent PKs so the IN list stays bounded
-        // (each chunk is one query). adapterQuery is uncapped, so no row cap.
-        const related: BaseModel[] = [];
-        for (const pkChunk of _chunk(pkValues, EAGER_IN_CHUNK)) {
-          const placeholders = pkChunk.map(() => "?").join(",");
-          let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${fk}" IN (${placeholders})`;
-          if (relatedClass.softDelete) {
-            sql += ` AND is_deleted = 0`;
-          }
-          const rows = await adapterQuery(db, sql, pkChunk);
-          for (const row of rows) related.push(new relatedClass(row as Record<string, unknown>));
-        }
-
-        // Eager load nested
-        if (nested.length > 0 && related.length > 0) {
-          await relatedClass._eagerLoad(related, nested);
-        }
-
-        // Group by FK — fk is a DB column name, resolve to JS property name on the related model
-        const relatedReverseMap = relatedClass.getReverseMapping();
-        const fkProp = relatedReverseMap[fk] ?? fk;
-        const grouped: Record<string, BaseModel[]> = {};
-        for (const record of related) {
-          const fkVal = _joinKey(record[fkProp]);
-          if (!grouped[fkVal]) grouped[fkVal] = [];
-          grouped[fkVal].push(record);
-        }
-
-        for (const inst of instances) {
-          const pkVal = _joinKey(inst[pk]);
-          const records = grouped[pkVal] || [];
-          if (relType === "hasOne") {
-            inst._relCache[relName] = records[0] ?? null;
-          } else {
-            inst._relCache[relName] = records;
-          }
-        }
-      } else if (relType === "belongsTo") {
-        // fk is a DB column name on the current model — resolve to JS property name
-        const ownerReverseMap = ModelClass.getReverseMapping();
-        const fkProp = ownerReverseMap[fk] ?? fk;
-        const fkValues = [...new Set(
-          instances
-            .map((inst) => inst[fkProp])
-            .filter((v) => v !== undefined && v !== null),
-        )];
-        if (fkValues.length === 0) continue;
-
-        const relatedPk = relatedClass.getPkField();
-        const relatedPkCol = relatedClass.getPkColumn();
-        // REL-EAGER-UNBOUNDED: chunk the FK values so the IN list stays bounded.
-        const related: BaseModel[] = [];
-        for (const fkChunk of _chunk(fkValues, EAGER_IN_CHUNK)) {
-          const placeholders = fkChunk.map(() => "?").join(",");
-          let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPkCol}" IN (${placeholders})`;
-          if (relatedClass.softDelete) {
-            sql += ` AND is_deleted = 0`;
-          }
-          const rows = await adapterQuery(db, sql, fkChunk);
-          for (const row of rows) related.push(new relatedClass(row as Record<string, unknown>));
-        }
-
-        if (nested.length > 0 && related.length > 0) {
-          await relatedClass._eagerLoad(related, nested);
-        }
-
-        const lookup: Record<string, BaseModel> = {};
-        for (const record of related) {
-          lookup[_joinKey(record[relatedPk])] = record;
-        }
-
-        for (const inst of instances) {
-          const fkVal = inst[fkProp];
-          inst._relCache[relName] = fkVal !== undefined && fkVal !== null
-            ? lookup[_joinKey(fkVal)] ?? null
-            : null;
-        }
-      }
+      await eagerLoadRelation(instances, ModelClass, relName, nested);
     }
   }
 
@@ -2062,3 +1564,415 @@ export class BaseModel {
     this._relCache = {};
   }
 }
+
+function savePrimaryKeyWhere(instance: BaseModel, model: typeof BaseModel): { sql: string; params: unknown[] } {
+  const params: unknown[] = [];
+  const clauses = primaryKeyFields(model).map((field) => {
+    params.push(instance[field]);
+    return `${model.getDbColumn(field)} = ?`;
+  });
+  return { sql: clauses.join(" AND "), params };
+}
+
+async function resolveSaveMode(
+  instance: BaseModel,
+  model: typeof BaseModel,
+  db: DatabaseAdapter,
+  pk: string,
+  pkValue: unknown,
+  pkField: FieldDefinition | undefined,
+): Promise<boolean> {
+  if (pkValue === undefined || pkValue === null || pkField?.autoIncrement) return pkValue !== undefined && pkValue !== null;
+  try {
+    const where = savePrimaryKeyWhere(instance, model);
+    if (primaryKeyFields(model).length > 1) {
+      const found = await db.fetch(`SELECT 1 AS present FROM ${model.tableName} WHERE ${where.sql}`, where.params, 1);
+      return (found as unknown as { length: number }).length > 0;
+    }
+    return await model.exists(pkValue);
+  } catch {
+    return false;
+  }
+}
+
+function validateBeforeSave(instance: BaseModel, model: typeof BaseModel, isUpdate: boolean): boolean {
+  const errors = instance.validate(isUpdate);
+  if (errors.length === 0) return true;
+  instance.lastError = errors.join("; ");
+  Log.error(`${model.name}.save() refused: validation failed for table '${model.tableName}' — ${instance.lastError}`);
+  return false;
+}
+
+async function executeModelUpdate(instance: BaseModel, model: typeof BaseModel, db: DatabaseAdapter): Promise<void> {
+  const fields = Object.entries(model.fields).filter(([name, def]) => !def.primaryKey && instance[name] !== undefined);
+  if (fields.length === 0) return;
+  const setClause = fields.map(([name]) => `"${model.getDbColumn(name)}" = ?`).join(", ");
+  const values = fields.map(([name, def]) => toDbFieldValue(def, instance[name]));
+  const where = savePrimaryKeyWhere(instance, model);
+  values.push(...where.params);
+  await adapterExecute(db, `UPDATE "${model.tableName}" SET ${setClause} WHERE ${where.sql}`, values);
+}
+
+function buildInsertStatement(
+  instance: BaseModel,
+  model: typeof BaseModel,
+  db: DatabaseAdapter,
+  pkField: FieldDefinition | undefined,
+  pkCol: string,
+): { sql: string; values: unknown[] } {
+  const fields = Object.entries(model.fields).filter(
+    ([name, def]) => !(def.primaryKey && def.autoIncrement) && instance[name] !== undefined,
+  );
+  const returning = pkField?.autoIncrement && db.constructor.name !== "SQLiteAdapter" ? ` RETURNING "${pkCol}"` : "";
+  if (fields.length === 0) {
+    const emptyInsert = db.constructor.name === "MysqlAdapter"
+      ? `INSERT INTO "${model.tableName}" () VALUES ()`
+      : `INSERT INTO "${model.tableName}" DEFAULT VALUES`;
+    return { sql: emptyInsert + returning, values: [] };
+  }
+  const columns = fields.map(([name]) => `"${model.getDbColumn(name)}"`).join(", ");
+  const placeholders = fields.map(() => "?").join(", ");
+  const values = fields.map(([name, def]) => toDbFieldValue(def, instance[name]));
+  return { sql: `INSERT INTO "${model.tableName}" (${columns}) VALUES (${placeholders})${returning}`, values };
+}
+
+function applyInsertedId(
+  instance: BaseModel,
+  db: DatabaseAdapter,
+  result: unknown,
+  pk: string,
+  pkCol: string,
+): void {
+  let newId: number | bigint | string | null = extractLastInsertId(result);
+  if (newId === null && result && typeof result === "object") {
+    const rows = (result as { rows?: Array<Record<string, unknown>> }).rows;
+    if (Array.isArray(rows) && rows[0]) newId = (rows[0][pkCol] ?? rows[0].id ?? null) as typeof newId;
+  }
+  if (newId === null) newId = db.lastInsertId();
+  if (newId !== null && newId !== undefined) instance[pk] = newId;
+}
+
+async function executeModelInsert(
+  instance: BaseModel,
+  model: typeof BaseModel,
+  db: DatabaseAdapter,
+  pk: string,
+  pkCol: string,
+  pkField: FieldDefinition | undefined,
+): Promise<void> {
+  const statement = buildInsertStatement(instance, model, db, pkField, pkCol);
+  const result = await adapterExecute(db, statement.sql, statement.values);
+  if (pkField?.autoIncrement) applyInsertedId(instance, db, result, pk, pkCol);
+}
+
+function saveDatabaseFailure(instance: BaseModel, model: typeof BaseModel, db: DatabaseAdapter, error: unknown): false {
+  const adapter = db as any;
+  const adapterError = typeof adapter.getError === "function" ? adapter.getError() :
+    typeof adapter.getLastError === "function" ? adapter.getLastError() : null;
+  let cause = String(adapterError || (error instanceof Error ? error.message : error));
+  const low = cause.toLowerCase();
+  if (model.softDelete && low.includes("is_deleted") &&
+      ["no such column", "has no column", "does not exist", "doesn't exist", "unknown column"].some((part) => low.includes(part))) {
+    cause += " — softDelete=true needs an is_deleted column; declare it (is_deleted: { type: 'integer', default: 0 }), boot the server so syncModels() adds it, or run a migration";
+  } else if (low.includes("no such table") ||
+      ((low.includes("does not exist") || low.includes("doesn't exist")) && !low.includes("column"))) {
+    cause += ` — table '${model.tableName}' does not exist; call ${model.name}.createTable() or run a migration`;
+  }
+  instance.lastError = cause;
+  Log.error(`${model.name}.save() failed for table '${model.tableName}': ${instance.lastError}`);
+  return false;
+}
+
+function serializeModelFields(instance: BaseModel, model: typeof BaseModel, case_: "camel" | "snake"): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(model.fields)) {
+    if (instance[key] === undefined) continue;
+    const outKey = case_ === "snake" ? (model.fieldMapping[key] ?? key) : key;
+    result[outKey] = instance[key] instanceof Point ? (instance[key] as Point).geojson : instance[key];
+  }
+  if (model.softDelete && instance.is_deleted !== undefined) result.is_deleted = instance.is_deleted;
+  return result;
+}
+
+function groupIncludedRelations(include: string[]): Record<string, string[]> {
+  const grouped: Record<string, string[]> = {};
+  for (const item of include) {
+    const parts = item.split(".", 2);
+    grouped[parts[0]] ??= [];
+    if (parts.length > 1) grouped[parts[0]].push(parts[1]);
+  }
+  return grouped;
+}
+
+function serializeIncludedRelation(
+  instance: BaseModel,
+  model: typeof BaseModel,
+  result: Record<string, unknown>,
+  relName: string,
+  nested: string[],
+  case_: "camel" | "snake",
+): void {
+  const cache = (instance as unknown as { _relCache: Record<string, unknown> })._relCache;
+  const data = cache[relName];
+  if (data === undefined) {
+    Log.warning(
+      `${model.name}.toDict(): relation "${relName}" was requested via include but was never eager-loaded ` +
+      `(a synchronous serializer cannot lazy-load it), so it is OMITTED from the result. Pass ` +
+      `include: ["${relName}"] to the finder (find/all/where/select/load) that produced this instance.`,
+    );
+    return;
+  }
+  if (data === null) {
+    result[relName] = null;
+    return;
+  }
+  const nestedInclude = nested.length > 0 ? nested : undefined;
+  if (Array.isArray(data)) {
+    result[relName] = (data as BaseModel[]).map((item) => item.toDict(nestedInclude, case_));
+    return;
+  }
+  if (typeof (data as BaseModel).toDict === "function") {
+    result[relName] = (data as BaseModel).toDict(nestedInclude, case_);
+  }
+}
+
+function serializeIncludedRelations(
+  instance: BaseModel,
+  model: typeof BaseModel,
+  result: Record<string, unknown>,
+  include: string[],
+  case_: "camel" | "snake",
+): void {
+  const grouped = groupIncludedRelations(include);
+  for (const [relName, nested] of Object.entries(grouped)) {
+    serializeIncludedRelation(instance, model, result, relName, nested, case_);
+  }
+}
+
+function serializeLoadedRelations(instance: BaseModel, model: typeof BaseModel, result: Record<string, unknown>): void {
+  for (const relation of model.hasOne ?? []) {
+    const key = relation.model.toLowerCase();
+    if (instance[key] !== undefined) result[key] = instance[key];
+  }
+  for (const relation of model.hasMany ?? []) {
+    const base = relation.model.toLowerCase();
+    const key = _pluralRelKeys() ? base + "s" : base;
+    if (instance[key] !== undefined) result[key] = instance[key];
+  }
+}
+
+type EagerRelation = {
+  definition: RelationshipDefinition;
+  type: "hasOne" | "hasMany" | "belongsTo";
+};
+
+function findEagerRelation(model: typeof BaseModel, name: string): EagerRelation | undefined {
+  const want = name.toLowerCase();
+  const matches = (relation: RelationshipDefinition): boolean => {
+    const base = relation.model.toLowerCase();
+    const related = BaseModel._modelRegistry[relation.model];
+    const table = related?.tableName?.toLowerCase();
+    const relatedName = relation.relatedName?.toLowerCase();
+    return base === want || base + "s" === want || relatedName === want || table === want;
+  };
+  const candidates: Array<[RelationshipDefinition[] | undefined, EagerRelation["type"]]> = [
+    [model.hasOne, "hasOne"],
+    [model.hasMany, "hasMany"],
+    [model.belongsTo, "belongsTo"],
+  ];
+  for (const [relations, type] of candidates) {
+    const definition = relations?.find(matches);
+    if (definition) return { definition, type };
+  }
+  return undefined;
+}
+
+function relationshipCache(instance: BaseModel): Record<string, unknown> {
+  return (instance as unknown as { _relCache: Record<string, unknown> })._relCache;
+}
+
+function reverseMappedColumn(model: typeof BaseModel, column: string): string {
+  return model.getReverseMapping()[column] ?? column;
+}
+
+async function eagerQueryRelated(
+  relatedClass: typeof BaseModel,
+  column: string,
+  values: unknown[],
+): Promise<BaseModel[]> {
+  const db = (relatedClass as unknown as { getDb(): DatabaseAdapter }).getDb();
+  const related: BaseModel[] = [];
+  for (const chunk of _chunk(values, EAGER_IN_CHUNK)) {
+    const placeholders = chunk.map(() => "?").join(",");
+    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${column}" IN (${placeholders})`;
+    if (relatedClass.softDelete) sql += " AND is_deleted = 0";
+    const rows = await adapterQuery(db, sql, chunk);
+    for (const row of rows) related.push(new relatedClass(row as Record<string, unknown>));
+  }
+  return related;
+}
+
+async function eagerLoadHasRelation(
+  instances: BaseModel[],
+  model: typeof BaseModel,
+  relatedClass: typeof BaseModel,
+  relationName: string,
+  nested: string[],
+  relation: RelationshipDefinition,
+  type: "hasOne" | "hasMany",
+): Promise<void> {
+  const pk = primaryKeyFields(model)[0];
+  const values = instances.map((instance) => instance[pk]).filter((value) => value !== undefined && value !== null);
+  if (values.length === 0) return;
+  const related = await eagerQueryRelated(relatedClass, relation.foreignKey, values);
+  if (nested.length > 0 && related.length > 0) await relatedClass._eagerLoad(related, nested);
+  const fkProp = reverseMappedColumn(relatedClass, relation.foreignKey);
+  const grouped: Record<string, BaseModel[]> = {};
+  for (const record of related) {
+    const key = _joinKey(record[fkProp]);
+    (grouped[key] ??= []).push(record);
+  }
+  for (const instance of instances) {
+    const records = grouped[_joinKey(instance[pk])] ?? [];
+    relationshipCache(instance)[relationName] = type === "hasOne" ? records[0] ?? null : records;
+  }
+}
+
+async function eagerLoadBelongsToRelation(
+  instances: BaseModel[],
+  model: typeof BaseModel,
+  relatedClass: typeof BaseModel,
+  relationName: string,
+  nested: string[],
+  relation: RelationshipDefinition,
+): Promise<void> {
+  const fkProp = reverseMappedColumn(model, relation.foreignKey);
+  const values = [...new Set(instances.map((instance) => instance[fkProp]).filter((value) => value !== undefined && value !== null))];
+  if (values.length === 0) return;
+  const relatedPk = primaryKeyFields(relatedClass)[0];
+  const relatedPkColumn = relatedClass.getDbColumn(relatedPk);
+  const related = await eagerQueryRelated(relatedClass, relatedPkColumn, values);
+  if (nested.length > 0 && related.length > 0) await relatedClass._eagerLoad(related, nested);
+  const lookup: Record<string, BaseModel> = {};
+  for (const record of related) lookup[_joinKey(record[relatedPk])] = record;
+  for (const instance of instances) {
+    const value = instance[fkProp];
+    relationshipCache(instance)[relationName] = value !== undefined && value !== null
+      ? lookup[_joinKey(value)] ?? null
+      : null;
+  }
+}
+
+async function eagerLoadRelation(
+  instances: BaseModel[],
+  model: typeof BaseModel,
+  relationName: string,
+  nested: string[],
+): Promise<void> {
+  const found = findEagerRelation(model, relationName);
+  if (!found) {
+    Log.warning(
+      `eager-load: include "${relationName}" did not match any relationship on ${model.name} ` +
+      `(table "${model.tableName}"). Accepted forms are the related model name, its ` +
+      `singular/plural key, or the related table name (case-insensitive).`,
+    );
+    return;
+  }
+  const relatedClass = BaseModel._modelRegistry[found.definition.model];
+  if (!relatedClass) return;
+  if (found.type === "belongsTo") {
+    await eagerLoadBelongsToRelation(instances, model, relatedClass, relationName, nested, found.definition);
+    return;
+  }
+  await eagerLoadHasRelation(instances, model, relatedClass, relationName, nested, found.definition, found.type);
+}
+
+/** Whether the adapter can emit engine-specific CREATE TABLE DDL. */
+function hasAdapterCreateTable(db: DatabaseAdapter): boolean {
+  return typeof db.createTable === "function" || typeof (db as any).createTableAsync === "function";
+}
+
+/**
+ * Map model fields to adapter column names while removing callable defaults.
+ * Callable defaults are resolved per row by the model constructor and must not
+ * be stringified into adapter DDL.
+ */
+function mappedCreateTableFields(model: typeof BaseModel): Record<string, FieldDefinition> {
+  const mapped: Record<string, FieldDefinition> = {};
+  for (const [fieldName, def] of Object.entries(model.fields)) {
+    const dbCol = model.getDbColumn(fieldName);
+    if (typeof def.default === "function") {
+      const { default: _callableDefault, ...rest } = def;
+      mapped[dbCol] = rest;
+    } else {
+      mapped[dbCol] = def;
+    }
+  }
+  return mapped;
+}
+
+/** Add the implicit soft-delete column when a model has not declared it. */
+function addSoftDeleteField(model: typeof BaseModel, fields: Record<string, FieldDefinition>): void {
+  if (model.softDelete && !("is_deleted" in fields)) {
+    fields.is_deleted = { type: "integer", default: 0 };
+  }
+}
+
+function primaryKeyFields(model: typeof BaseModel): string[] {
+  const keys = Object.entries(model.fields)
+    .filter(([, def]) => def.primaryKey)
+    .map(([name]) => name);
+  return keys.length > 0 ? keys : ["id"];
+}
+
+const FALLBACK_COLUMN_TYPES: Record<string, string> = {
+  integer: "INTEGER",
+  string: "TEXT",
+  text: "TEXT",
+  number: "REAL",
+  numeric: "REAL",
+  boolean: "INTEGER",
+  datetime: "TEXT",
+};
+
+function fallbackColumnDefinition(model: typeof BaseModel, fieldName: string, def: FieldDefinition): string {
+  const dbCol = model.getDbColumn(fieldName);
+  const parts = [`"${dbCol}" ${FALLBACK_COLUMN_TYPES[def.type] || "TEXT"}`];
+  if (def.primaryKey && primaryKeyFields(model).length === 1) parts.push("PRIMARY KEY");
+  if (def.autoIncrement) parts.push("AUTOINCREMENT");
+  if (def.required && !def.primaryKey) parts.push("NOT NULL");
+  if (def.default !== undefined && typeof def.default !== "function") {
+    const value = typeof def.default === "string" ? `'${def.default}'` : String(def.default);
+    parts.push(`DEFAULT ${value}`);
+  }
+  return parts.join(" ");
+}
+
+function fallbackPrimaryKeyDefinition(model: typeof BaseModel): string | undefined {
+  const pkFields = primaryKeyFields(model);
+  if (pkFields.length <= 1) return undefined;
+  const pkCols = pkFields.map((fieldName) => model.getDbColumn(fieldName));
+  return `PRIMARY KEY (${pkCols.join(", ")})`;
+}
+
+function fallbackColumnDefinitions(model: typeof BaseModel): string[] {
+  const definitions = Object.entries(model.fields).map(([fieldName, def]) => fallbackColumnDefinition(model, fieldName, def));
+  const dbCols = Object.keys(model.fields).map((fieldName) => model.getDbColumn(fieldName));
+  if (model.softDelete && !dbCols.includes("is_deleted")) definitions.push('"is_deleted" INTEGER DEFAULT 0');
+  const primaryKey = fallbackPrimaryKeyDefinition(model);
+  if (primaryKey) definitions.push(primaryKey);
+  return definitions;
+}
+
+async function createFallbackTable(db: DatabaseAdapter, model: typeof BaseModel): Promise<void> {
+  const definitions = fallbackColumnDefinitions(model);
+  const sql = `CREATE TABLE IF NOT EXISTS "${model.tableName}" (${definitions.join(", ")})`;
+  await adapterStartTransaction(db);
+  try {
+    await adapterExecute(db, sql);
+    await adapterCommit(db);
+  } catch (e) {
+    await adapterRollback(db);
+    throw e;
+  }
+}