tina4-nodejs 3.13.38 → 3.13.39

package/packages/orm/src/baseModel.ts

@@ -95,6 +95,16 @@ export class BaseModel {
   /** Relationship cache for lazy loading */
   private _relCache: Record<string, unknown> = {};
 
+  /**
+   * Cause of the most recent failed save(). null when the last save()
+   * succeeded. Mirrors db.getError() so a caller that checks
+   * `if (!(await model.save()))` can still recover the real cause via
+   * `model.getError()` / `model.lastError` — the failure never vanishes
+   * silently. Set by save() (validation message or driver error), cleared
+   * to null on a successful save.
+   */
+  lastError: string | null = null;
+
   constructor(data?: Record<string, unknown> | string) {
     // Accept a JSON object string (parity with Python/PHP/Ruby):
     //   new Widget('{"id":1,"name":"alpha"}')
@@ -110,6 +120,21 @@ export class BaseModel {
           `Map over the list to build many records.`,
       );
     }
+    const ModelClass0 = this.constructor as typeof BaseModel;
+    // Set defaults from field definitions BEFORE populating from data.
+    // Outlier A (mirrors Python issue #50.1): a callable default is resolved
+    // to its called value PER INSTANCE, so per-row defaults (e.g.
+    // `default: () => new Date()`) actually differ and a function never
+    // reaches the driver. Static defaults are assigned verbatim. Data passed
+    // to the constructor overrides any default below.
+    const fields0 = ModelClass0.fields ?? {};
+    for (const [name, def] of Object.entries(fields0)) {
+      if (def.default === undefined) continue;
+      this[name] = typeof def.default === "function"
+        ? (def.default as () => unknown)()
+        : def.default;
+    }
+
     if (data) {
       const ModelClass = this.constructor as typeof BaseModel;
       // If autoMap is on, auto-generate fieldMapping from camelCase fields
@@ -188,8 +213,12 @@ export class BaseModel {
         this.belongsTo.push({ model: def.references, foreignKey: key });
       }
 
-      // Register hasMany on the referenced model via the module-level registry
-      const hasManyKey = def.relatedName ?? (this.tableName ?? this.name.toLowerCase());
+      // Register hasMany on the referenced model via the module-level registry.
+      // Outlier F: the has-many key defaults to the DECLARING class name
+      // lowercased + "s" (Python master: `name.lower() + "s"`), e.g. a Post
+      // with author_id → Author.posts. The relatedName override wins. The old
+      // default was the table name, which drifted from the documented rule.
+      const hasManyKey = def.relatedName ?? (this.name.toLowerCase() + "s");
       const existing = _fkRegistry.get(def.references) ?? [];
       if (!existing.find((r) => r.foreignKey === key && r.declaringModel === this.name)) {
         existing.push({ foreignKey: key, declaringModel: this.name, hasManyKey });
@@ -207,7 +236,10 @@ export class BaseModel {
     for (const entry of entries) {
       this.hasMany = this.hasMany ?? [];
       if (!this.hasMany.find((r) => r.foreignKey === entry.foreignKey && r.model === entry.declaringModel)) {
-        this.hasMany.push({ model: entry.declaringModel, foreignKey: entry.foreignKey });
+        // Outlier F: carry the derived has-many key (declaring class lowercased
+        // + "s", or the relatedName override) onto the relationship so an
+        // include: ["posts"] resolves to it — not the related table name.
+        this.hasMany.push({ model: entry.declaringModel, foreignKey: entry.foreignKey, relatedName: entry.hasManyKey });
       }
     }
   }
@@ -300,38 +332,83 @@ export class BaseModel {
   /**
    * Create a new instance from data, save it, and return the saved instance.
    *
+   * Canonical #3: if the underlying save() fails (validation errors or a
+   * driver error), create() returns `false` — it does NOT hand back a
+   * possibly-unsaved instance, so a failed insert can never masquerade as a
+   * success. The failure cause is logged and available on the (discarded)
+   * instance's getError() via the same path save() uses.
+   *
    * Usage:
    *   const user = User.create({ name: "Alice", email: "alice@example.com" });
+   *   if (!(await User.create({ name: null }))) { ... }   // save() failed -> false
    */
   static async create<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     data: Record<string, unknown> = {},
-  ): Promise<T> {
+  ): Promise<T | false> {
     const instance = new this(data) as T;
-    await instance.save();
+    if ((await instance.save()) === false) {
+      return false;
+    }
     return instance;
   }
 
   /**
-   * Find records by filter dict. Always returns an array.
+   * Find record(s) by primary key, filter object, or all.
    *
-   * Usage:
-   *   User.find({ name: "Alice" })              → [User, ...]
-   *   User.find({ age: 18 }, 10)                → [User, ...] (limit 10)
-   *   User.find({}, 100, 0, "name ASC")         → [User, ...] (with orderBy)
-   *   User.find()                                → all records
+   * Outlier C — overloaded on the first argument (parity with
+   * Python/PHP/Ruby):
+   *   - number | string (scalar PK) → single instance (or null), like
+   *     findById(pk). `include` is accepted as the 2nd argument in this form.
+   *   - object (filter)             → array of instances (AND-ed conditions).
+   *   - omitted                     → array of all records.
    *
-   * Use findById(id) for single-record primary key lookup.
+   * Usage:
+   *   User.find(1)                       → User | null   (PK lookup)
+   *   User.find(1, ["posts"])            → User | null   (PK lookup + eager)
+   *   User.find({ name: "Alice" })       → [User, ...]
+   *   User.find({ age: 18 }, 10)         → [User, ...]  (limit 10)
+   *   User.find({}, 100, 0, "name ASC")  → [User, ...]  (with orderBy)
+   *   User.find()                        → all records
    */
+  // Scalar PK → single instance | null.
+  static async find<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    pk: number | string,
+    include?: string[],
+  ): Promise<T | null>;
+  // Filter object / all → array.
   static async find<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     filter?: Record<string, unknown>,
-    limit = 100,
+    limit?: number,
+    offset?: number,
+    orderBy?: string,
+    include?: string[],
+  ): Promise<T[]>;
+  static async find<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    filter?: Record<string, unknown> | number | string,
+    limit: number | string[] = 100,
     offset = 0,
     orderBy?: string,
     include?: string[],
-  ): Promise<T[]> {
+  ): Promise<T[] | T | null> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+
+    // Scalar PK lookup routes to findById. A number or a string (but NOT a
+    // boolean, and NOT an object) is a primary-key value — Active Record
+    // convention (Django Model.objects.get(pk), SQLAlchemy session.get(M, id),
+    // Ruby Model.find(1)). In the scalar form the 2nd arg is `include`.
+    if (typeof filter === "number" || typeof filter === "string") {
+      const inc = Array.isArray(limit) ? limit : undefined;
+      return (ModelClass.findById as (id: unknown, include?: string[]) => Promise<T | null>).call(
+        ModelClass, filter, inc,
+      );
+    }
+
+    // Array form — coerce `limit` back to a number for the list path.
+    const lim = typeof limit === "number" ? limit : 100;
     const db = ModelClass.getDb();
     const conditions: string[] = [];
     const params: unknown[] = [];
@@ -356,7 +433,7 @@ export class BaseModel {
       sql += ` ORDER BY ${orderBy}`;
     }
 
-    const rows = await adapterFetch(db, sql, params, limit, offset);
+    const rows = await adapterFetch(db, sql, params, lim, offset);
     const data = (rows as any)?.data ?? rows;
     const instances = (Array.isArray(data) ? data : []).map((row: Record<string, unknown>) => {
       const inst = new this(row) as T;
@@ -391,11 +468,16 @@ export class BaseModel {
 
     let sql: string;
     if (filter === undefined || filter === null) {
-      // No args — use PK already set
-      const pk = (ModelClass as any).primaryKey ?? (this as any).primaryKey ?? "id";
-      const pkValue = (this as any)[pk];
+      // No args — use the PK value already set. Outlier B: resolve the REAL
+      // primary key via getPkField()/getPkColumn() (a model has no
+      // `primaryKey` static — the old code referenced a non-existent field, so
+      // it always queried `WHERE undefined = ?` and never loaded). Use the JS
+      // property for the value and the DB column for the WHERE clause.
+      const pkProp = ModelClass.getPkField();
+      const pkCol = ModelClass.getPkColumn();
+      const pkValue = (this as any)[pkProp];
       if (pkValue === undefined || pkValue === null) return false;
-      sql = `SELECT * FROM ${table} WHERE ${pk} = ?`;
+      sql = `SELECT * FROM "${table}" WHERE "${pkCol}" = ?`;
       params = [pkValue];
     } else {
       sql = `SELECT * FROM ${table} WHERE ${filter}`;
@@ -492,11 +574,40 @@ export class BaseModel {
   }
 
   /**
-   * Save this instance (insert or update).
-   * Returns this on success (fluent), null on failure.
+   * Save this instance (insert or update). Returns this on success (fluent
+   * self), false on failure.
+   *
+   * Fails loud, never silent (the same principle db.execute() follows by
+   * raising). On ANY failure path save() returns `false` — keeping the
+   * contract callers rely on (`if (!(await model.save())) ...`) — but it also
+   * (a) logs the real cause via Log.error with model/table context and
+   * (b) records the cause on `this.lastError` so a caller can recover it after
+   * the fact via getError() / lastError. It never throws and never changes the
+   * `this | false` return shape.
+   *
+   * Two distinct failure paths, both loud:
+   *  - Validation (canonical #2): validate() runs FIRST. If it returns errors,
+   *    save() logs them, records them on lastError, and returns false WITHOUT
+   *    touching the database — an invalid model never reaches the driver.
+   *  - Database: a driver error (NOT NULL, duplicate PK, missing table, ...) is
+   *    rolled back, logged with the underlying cause, recorded on lastError,
+   *    and returns false — the cause is no longer swallowed silently.
    */
   async save(): Promise<this | false> {
     const ModelClass = this.constructor as typeof BaseModel;
+
+    // ── Canonical #2: validate() is enforced. An invalid model never reaches
+    // the driver — fail loud (log + lastError), return false. ──
+    const errors = this.validate();
+    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 db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
     const pkCol = ModelClass.getPkColumn();
@@ -585,14 +696,42 @@ export class BaseModel {
         }
       }
       await adapterCommit(db);
-    } catch (e) {
+    } catch (e: any) {
       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;
+      this.lastError = adapterErr || e?.message || String(e);
+      Log.error(
+        `${ModelClass.name}.save() failed for table ` +
+          `'${ModelClass.tableName}': ${this.lastError}`,
+      );
       return false;
     }
+    // Success — clear any previously-recorded error.
+    this.lastError = null;
     (this as any)._exists = true;
     return this;
   }
 
+  /**
+   * Return the cause of the most recent failed save(), or null.
+   *
+   * Mirrors db.getError(). After save() returns false — whether from
+   * validation or a driver error — the real cause is retrievable here (and on
+   * this.lastError) so a caller using the `if (!(await model.save()))`
+   * contract can still surface it. Cleared to null on a successful save.
+   */
+  getError(): string | null {
+    return this.lastError;
+  }
+
   /**
    * Delete this instance. Uses soft delete if configured.
    */
@@ -1249,9 +1388,15 @@ export class BaseModel {
         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)
         );
       };

package/packages/orm/src/index.ts

@@ -39,6 +39,10 @@ export {
   createMigration,
   status,
   Migration,
+  splitStatements,
+  normalizeQuotes,
+  sortMigrationFiles,
+  shouldSkipCreateTable,
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes } from "./autoCrud.js";

package/packages/orm/src/migration.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { Log } from "@tina4/core";
 import type { FieldDefinition, DatabaseAdapter } from "./types.js";
 import type { SQLiteAdapter } from "./adapters/sqlite.js";
 import type { DiscoveredModel } from "./model.js";
@@ -76,6 +77,55 @@ async function shouldSkipForFirebird(
   return null;
 }
 
+/**
+ * Match CREATE TABLE <name> — name may be quoted ("x"), bracketed ([x] MSSQL),
+ * or bare. Captures the table name.
+ */
+const CREATE_TABLE_RE =
+  /^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|\[([^\]]+)\]|(\w+))/i;
+
+/**
+ * Identify the database engine via the adapter's class name.
+ * (constructor.name is the engine discriminator used throughout this package.)
+ */
+function engineOf(db: DatabaseAdapter): "firebird" | "mssql" | "other" {
+  const name = db.constructor.name;
+  if (name === "FirebirdAdapter") return "firebird";
+  if (name === "MssqlAdapter") return "mssql";
+  return "other";
+}
+
+/**
+ * Make CREATE TABLE idempotent on engines lacking IF NOT EXISTS.
+ *
+ * Firebird and MSSQL do not support `CREATE TABLE IF NOT EXISTS`, so a raw
+ * CREATE in a re-run migration raises "object already exists". When the target
+ * table already exists on those engines, return a skip reason so the statement
+ * is skipped (mirrors the Firebird ALTER-TABLE-ADD idempotency guard).
+ * SQLite/MySQL/PostgreSQL support IF NOT EXISTS and are left to the engine.
+ * Only a genuine already-exists is skipped — every other error still raises.
+ */
+export async function shouldSkipCreateTable(
+  db: DatabaseAdapter,
+  stmt: string,
+): Promise<string | null> {
+  const engine = engineOf(db);
+  if (engine !== "firebird" && engine !== "mssql") return null;
+
+  const m = stmt.match(CREATE_TABLE_RE);
+  if (!m) return null;
+
+  const table = m[1] ?? m[2] ?? m[3];
+  try {
+    if (await adapterTableExists(db, table)) {
+      return `Table ${table} already exists, skipping CREATE TABLE`;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
 /**
  * Sync model definitions to the database (create tables, add columns).
  */
@@ -411,13 +461,44 @@ export interface MigrationStatus {
   pending: string[];
 }
 
+/**
+ * Smart/curly quotes — editors, word processors, docs and chat apps silently
+ * convert a straight " to “ ” and a straight ' to ‘ ’ (plus primes ′ ″). Those
+ * characters are NOT valid SQL string/identifier delimiters, so a pasted-in
+ * migration fails to run ("syntax error near …"). Map them back to straight
+ * ASCII quotes. (Real string CONTENTS are unaffected by intent — we only swap
+ * the lookalike code points for their ASCII equivalents.)
+ */
+const SMART_QUOTES: Record<string, string> = {
+  // Double-quote lookalikes → straight " (U+0022)
+  "“": '"', "”": '"', "„": '"', "‟": '"', "″": '"',
+  // Single-quote / apostrophe lookalikes → straight ' (U+0027)
+  "‘": "'", "’": "'", "‚": "'", "‛": "'", "′": "'",
+};
+const SMART_QUOTE_RE = new RegExp(`[${Object.keys(SMART_QUOTES).join("")}]`, "g");
+
+/**
+ * Replace smart/curly quotes with straight ASCII quotes so migration SQL
+ * authored or pasted from an editor/doc actually runs (those code points are
+ * not valid SQL delimiters). Already-straight quotes and ordinary string
+ * content are returned byte-for-byte unchanged.
+ */
+export function normalizeQuotes(sql: string): string {
+  return sql.replace(SMART_QUOTE_RE, (ch) => SMART_QUOTES[ch]);
+}
+
 /**
  * Split SQL text into individual statements on the given delimiter.
  *
  * Strips line comments (`-- ...`) and block comments, handles stored
  * procedure blocks delimited by `$$` or `//`.
  */
-function splitStatements(sql: string, delimiter = ";"): string[] {
+export function splitStatements(sql: string, delimiter = ";"): string[] {
+  // Normalize smart/curly quotes to straight ASCII first, so SQL pasted from
+  // an editor/doc (which converts " → “ ” and ' → ‘ ’) actually runs. Mirrors
+  // Python's _split_statements applying _normalize_quotes as its first line.
+  sql = normalizeQuotes(sql);
+
   // Extract blocks delimited by $$ or // first, replacing with placeholders
   const blocks: string[] = [];
   const saveBlock = (_match: string, _p1: string): string => {
@@ -426,7 +507,12 @@ function splitStatements(sql: string, delimiter = ";"): string[] {
   };
 
   let processed = sql.replace(/\$\$([\s\S]*?)\$\$/g, saveBlock);
-  processed = processed.replace(/\/\/([\s\S]*?)\/\//g, saveBlock);
+  // The `//` delimiters must NOT be preceded by a colon, so a URL scheme
+  // (`https://…`) or other `://` literal inside a migration is never captured
+  // as an opaque stored-proc block (it would otherwise swallow everything
+  // between two `//` occurrences and skip statement splitting/cleaning).
+  // Negative lookbehind `(?<!:)` mirrors Python's runner.
+  processed = processed.replace(/(?<!:)\/\/([\s\S]*?)(?<!:)\/\//g, saveBlock);
 
   // Remove block comments (/* ... */)
   const clean = processed.replace(/\/\*[\s\S]*?\*\//g, "");
@@ -458,25 +544,43 @@ function splitStatements(sql: string, delimiter = ";"): string[] {
  * - Sequential: 000001_name.sql, 000002_name.sql
  * - Timestamp: 20240315120000_name.sql (YYYYMMDDHHMMSS)
  *
- * Both patterns start with digits followed by underscore, so alphabetical
- * sort works correctly for both (zero-padded sequential and timestamp).
+ * Numeric-aware: a file with a leading numeric/timestamp prefix sorts first by
+ * that number (so `9_*` applies before `10_*` — a plain lexical sort misorders
+ * unpadded prefixes because "10" < "9"). Files with NO numeric prefix sort
+ * AFTER the numbered ones, then lexically. Mirrors Python's `_migration_sort_key`.
  */
-function sortMigrationFiles(files: string[]): string[] {
+export function sortMigrationFiles(files: string[]): string[] {
+  // Returns a tuple-like key: [group, numeric, name].
+  // group 0 = has numeric prefix (sorts first); group 1 = no prefix (sorts after).
+  const key = (name: string): [number, bigint, string] => {
+    const m = name.match(/^(\d+)/);
+    return m ? [0, BigInt(m[1]), name] : [1, 0n, name];
+  };
   return [...files].sort((a, b) => {
-    const aPrefix = a.match(/^(\d+)/);
-    const bPrefix = b.match(/^(\d+)/);
-    if (aPrefix && bPrefix) {
-      // Compare numeric prefixes — handles both 000001 and 20240315120000
-      const aNum = BigInt(aPrefix[1]);
-      const bNum = BigInt(bPrefix[1]);
-      if (aNum < bNum) return -1;
-      if (aNum > bNum) return 1;
-      return a.localeCompare(b);
-    }
-    return a.localeCompare(b);
+    const [ag, an, anm] = key(a);
+    const [bg, bn, bnm] = key(b);
+    if (ag !== bg) return ag - bg;
+    if (an < bn) return -1;
+    if (an > bn) return 1;
+    return anm.localeCompare(bnm);
   });
 }
 
+/**
+ * Warn (once) about migration filenames without a recognized NNNNNN_/timestamp
+ * prefix — their ordering relative to numbered migrations is undefined, a silent
+ * out-of-order-apply footgun. Mirrors Python's runner.
+ */
+function warnUnprefixedMigrations(files: string[]): void {
+  const unprefixed = files.filter((f) => !/^\d+[_-]/.test(f));
+  if (unprefixed.length > 0) {
+    Log.warning(
+      "Migration file(s) without a numeric/timestamp prefix may apply out of order: " +
+        unprefixed.join(", "),
+    );
+  }
+}
+
 /**
  * Run all pending SQL-file migrations.
  *
@@ -533,7 +637,19 @@ export async function migrate(
         batch INTEGER NOT NULL DEFAULT 1,
         applied_at TEXT NOT NULL
       )`);
+    } else if (engineOf(db) === "mssql") {
+      // MSSQL has no AUTOINCREMENT / IF NOT EXISTS — route the bootstrap
+      // through the adapter's engine-aware createTable (IDENTITY(1,1) etc.),
+      // exactly like ensureMigrationTable does. Emitting raw
+      // AUTOINCREMENT/IF NOT EXISTS here is invalid on SQL Server.
+      await adapterCreateTable(db, MIGRATION_TABLE, {
+        id: { type: "integer", primaryKey: true, autoIncrement: true },
+        name: { type: "string", required: true },
+        batch: { type: "integer", required: true },
+        applied_at: { type: "datetime", default: "now" },
+      });
     } else {
+      // SQLite / MySQL — both support IF NOT EXISTS + AUTOINCREMENT/AUTO_INCREMENT.
       await adapterExecute(db, `CREATE TABLE IF NOT EXISTS "${MIGRATION_TABLE}" (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT NOT NULL,
@@ -553,13 +669,17 @@ export async function migrate(
     }
   }
 
-  // Collect .sql files (exclude .down.sql), sorted by prefix
+  // Collect .sql files (exclude .down.sql), numeric-aware sorted (9_ before 10_).
   const files = sortMigrationFiles(
     readdirSync(dir).filter((f) => f.endsWith(".sql") && !f.endsWith(".down.sql")),
   );
 
   if (files.length === 0) return result;
 
+  // Warn about files without a recognized numeric/timestamp prefix — their
+  // ordering relative to numbered migrations is undefined.
+  warnUnprefixedMigrations(files);
+
   // Determine the batch number for this run
   let currentBatch = 1;
   try {
@@ -621,10 +741,12 @@ export async function migrate(
       await adapterStartTransaction(db);
 
       for (const stmt of statements) {
-        // Firebird lacks IF NOT EXISTS for ALTER TABLE ADD.
-        // Pre-check the system catalogue so duplicate columns are
-        // silently skipped instead of raising an error.
-        const skipReason = await shouldSkipForFirebird(db, stmt);
+        // Idempotency on engines lacking IF NOT EXISTS: Firebird ALTER-TABLE-ADD,
+        // and CREATE TABLE on Firebird/MSSQL. Pre-check the catalogue so a genuine
+        // already-exists is skipped instead of raising — every other error still
+        // raises (rolls the file back).
+        const skipReason =
+          (await shouldSkipForFirebird(db, stmt)) ?? (await shouldSkipCreateTable(db, stmt));
         if (skipReason) {
           console.log(`  Migration ${file}: ${skipReason}`);
           continue;
@@ -671,7 +793,12 @@ export async function migrate(
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`  Migration failed: ${file} — ${msg}`);
       result.failed.push(file);
-      // Continue to next file (matching Python behaviour)
+      // STOP at the first failure (parity with Python/PHP/Ruby). The file rolled
+      // back; later migrations must NOT be applied on top of a missing earlier
+      // one (a missing column / table would cascade silent corruption). Already-
+      // applied files stay applied — fix the bad file and re-run.
+      Log.error(`Migration stopped at first failure: ${file} — ${msg}`);
+      break;
     }
   }
 

package/packages/orm/src/queryBuilder.ts

@@ -428,8 +428,20 @@ export class QueryBuilder {
       return [{ [field]: { [mongoOp]: val } }, paramIndex + 1];
     }
 
-    // Fallback
-    return [{ $where: cond }, paramIndex];
+    // Canonical #5: no silent $where fallback. Previously an unparseable
+    // condition was wrapped as `{ $where: <raw condition string> }` — a raw-JS
+    // sink that is both injection-shaped (the WHERE string runs as JavaScript
+    // on the MongoDB server) and silently different semantics from the SQL the
+    // caller wrote. Fail loud instead: name the clause so the caller fixes it
+    // rather than shipping a surprise $where.
+    throw new Error(
+      `QueryBuilder.toMongo(): cannot translate WHERE clause to a MongoDB ` +
+        `filter: "${cond}". Supported forms: "<field> <op> ?" ` +
+        `(=, !=, <>, >, >=, <, <=), "<field> LIKE ?", ` +
+        `"<field> [NOT] IN (?)", "<field> IS [NOT] NULL". Rewrite the ` +
+        `condition in one of those forms (toMongo() will not silently emit a ` +
+        `raw $where JavaScript expression).`,
+    );
   }
 
   /**

package/packages/orm/src/types.ts

@@ -20,6 +20,13 @@ export interface FieldDefinition {
 export interface RelationshipDefinition {
   model: string;
   foreignKey: string;
+  /**
+   * The relationship accessor/include name on the OWNING model. For an
+   * FK-auto-wired has-many this is the declaring class name lowercased + "s"
+   * (Python master rule) or the `relatedName` override. Used by eager-load
+   * include resolution so an `include: ["posts"]` matches the wired relation.
+   */
+  relatedName?: string;
 }
 
 export interface ModelDefinition {

package/packages/orm/src/validation.ts

@@ -86,6 +86,20 @@ export function validate(
           errors.push({ field: name, message: "must be a valid date/time" });
         }
         break;
+
+      case "foreignKey": {
+        // Outlier D: previously there was no foreignKey case, so ANY value
+        // passed validation silently. A foreign key references another model's
+        // primary key — by default an auto-increment integer — so validate it
+        // as an integer (a numeric string like "12" is coerced and accepted).
+        // This catches the common bug of assigning a whole object / array /
+        // non-numeric string to an *_id column before it reaches the driver.
+        const fkNum = typeof value === "string" ? Number(value) : value;
+        if (typeof fkNum !== "number" || isNaN(fkNum) || !Number.isInteger(fkNum)) {
+          errors.push({ field: name, message: "must be a valid foreign key (integer)" });
+        }
+        break;
+      }
     }
   }