tina4-nodejs 3.13.137 → 3.13.138

package/packages/orm/src/autoCrud.ts

@@ -1,9 +1,17 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import type { RouteDefinition, Tina4Request, Tina4Response } from "../../core/src/index.js";
 import type { DiscoveredModel } from "./model.js";
 import type { FieldDefinition } from "./types.js";
-import { getAdapter, adapterQuery, adapterExecute } from "./database.js";
+import { getAdapter, getNamedAdapter, adapterQuery, adapterExecute, adapterFetch, quoteIdentifier } from "./database.js";
 import { DatabaseResult } from "./databaseResult.js";
-import { buildQuery, parseQueryString } from "./query.js";
+import { buildQuery, parseQueryString, resolveField, resolveFieldColumn, UnknownFieldError, InvalidQueryParameterError } from "./query.js";
 import { validate } from "./validation.js";
 
 /**
@@ -23,6 +31,7 @@ import { validate } from "./validation.js";
  */
 function allowListedBody(
   fields: Record<string, FieldDefinition>,
+  columnOf: (field: string) => string,
   pkField: string,
   body: Record<string, unknown> | null | undefined,
   isCreate: boolean,
@@ -31,10 +40,14 @@ function allowListedBody(
   const stripPk = isCreate ? pkDef?.autoIncrement === true : true;
   const allowed: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(body ?? {})) {
-    if (!(key in fields)) continue;
-    if (key === "is_deleted") continue;
-    if (stripPk && key === pkField) continue;
-    allowed[key] = value;
+    // ADR-0069 (G1): the SAME resolver the list route uses - a declared field
+    // by its property or its column; anything else (including an inherited
+    // Object property such as "constructor") is dropped.
+    const field = resolveField(fields, columnOf, key);
+    if (field === null) continue;
+    if (field === "is_deleted") continue;
+    if (stripPk && field === pkField) continue;
+    allowed[field] = value;
   }
   return allowed;
 }
@@ -154,7 +167,11 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
   const writeSecurity = options.public === true ? { secure: false as const } : {};
 
   for (const { definition } of models) {
-    const { tableName, fields, softDelete, tableFilter, fieldMapping } = definition;
+    const { tableName, fields, softDelete, tableFilter, fieldMapping, dbName } = definition;
+
+    // The connection the model is bound to (`static _db = "name"`), never the
+    // global default behind its back - the same resolution BaseModel.getDb() uses.
+    const modelAdapter = () => (dbName ? getNamedAdapter(dbName) : getAdapter());
     const basePath = `/api/${tableName}`;
     const mapping = fieldMapping ?? {};
 
@@ -168,7 +185,9 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
     // Build extra WHERE conditions for soft delete and table filter
     const extraConditions: string[] = [];
     if (softDelete) {
-      extraConditions.push(`"is_deleted" = 0`);
+      // Bare, like BaseModel's soft-delete filter: resolves on every engine
+      // (Firebird folds it to IS_DELETED, the name its DDL created).
+      extraConditions.push(`is_deleted = 0`);
     }
     if (tableFilter) {
       extraConditions.push(tableFilter);
@@ -183,23 +202,42 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const adapter = getAdapter();
+        const adapter = modelAdapter();
+        const q = (name: string): string => quoteIdentifier(adapter, name);
 
-        // Parse query params for filtering / sorting / pagination
-        const qp = parseQueryString(req.query ?? {});
+        // Parse query params for filtering / sorting / pagination.
         // limit/offset/page are the CLAMPED/CAPPED values buildQuery actually used
         // for the SQL (PAGE-DEC-01: page >= 1, per-page <= DEFAULT_ROW_CAP) — read
         // them back here instead of recomputing from the raw qp, so the envelope
         // can never drift from the query that ran.
-        const { sql, countSql, params, limit, offset } = buildQuery(tableName, qp, extraConditions);
+        //
+        // Filter keys and sort fields resolve against the model's DECLARED fields
+        // (ADR-0069); an unknown one is a 400 before any SQL runs.
+        // A wrong-shaped value (a list/map where one value belongs) is a 400 too.
+        let built: ReturnType<typeof buildQuery>;
+        try {
+          const qp = parseQueryString(req.query ?? {});
+          built = buildQuery(tableName, qp, extraConditions, q, (key) => resolveFieldColumn(fields, getDbCol, key));
+        } catch (err) {
+          if (err instanceof UnknownFieldError) {
+            res.error("UNKNOWN_FIELD", err.message, 400);
+            return;
+          }
+          if (err instanceof InvalidQueryParameterError) {
+            res.error("INVALID_QUERY_PARAMETER", err.message, 400);
+            return;
+          }
+          throw err;
+        }
+        const { pageSql, countSql, filterParams, limit, offset } = built;
 
-        // params includes limit and offset at the end; countSql doesn't need them
-        const countParams = params.slice(0, -2);
-        const rows = await adapterQuery(adapter, sql, params);
+        // adapterFetch pages in the engine's own syntax (LIMIT/OFFSET, OFFSET
+        // FETCH on MSSQL, ROWS on Firebird) - the same path BaseModel reads use.
+        const rows = await adapterFetch(adapter, pageSql, filterParams, limit, offset);
 
         // total is the TRUE total for the filter (a COUNT probe), NEVER the number
         // of rows this page returned (ADR-0043).
-        const countRow = await adapterQuery(adapter, countSql, countParams);
+        const countRow = await adapterQuery(adapter, countSql, filterParams);
         const total = Number(countRow[0]?.total ?? 0);
 
         // The REST list envelope IS the canonical paginate envelope: exactly the
@@ -220,11 +258,12 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const adapter = getAdapter();
+        const adapter = modelAdapter();
+        const q = (name: string): string => quoteIdentifier(adapter, name);
 
-        const conditions = [`"${pkColumn}" = ?`, ...extraConditions];
+        const conditions = [`${q(pkColumn)} = ?`, ...extraConditions];
         const rows = await adapterQuery(adapter,
-          `SELECT * FROM "${tableName}" WHERE ${conditions.join(" AND ")}`,
+          `SELECT * FROM ${q(tableName)} WHERE ${conditions.join(" AND ")}`,
           [req.params.id],
         );
 
@@ -247,12 +286,13 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const adapter = getAdapter();
+        const adapter = modelAdapter();
+        const q = (name: string): string => quoteIdentifier(adapter, name);
         const rawBody = req.body as Record<string, unknown>;
 
         // CRUD-MASS-ASSIGNMENT: allow-list before anything downstream (both
         // validation and persistence) ever sees the body.
-        const body = allowListedBody(fields, pkField, rawBody, true);
+        const body = allowListedBody(fields, getDbCol, pkField, rawBody, true);
 
         // Validate against field definitions
         const errors = validate(body, fields);
@@ -276,8 +316,8 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         // tolerates RETURNING but we still prefer its lastId below.
         const isSqlite = adapter.constructor.name === "SQLiteAdapter";
         const insertSql =
-          `INSERT INTO "${tableName}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders})` +
-          (isSqlite ? "" : ` RETURNING "${pkColumn}"`);
+          `INSERT INTO ${q(tableName)} (${columns.map((c) => q(c)).join(", ")}) VALUES (${placeholders})` +
+          (isSqlite ? "" : ` RETURNING ${q(pkColumn)}`);
 
         const insertResult = await adapterExecute(adapter, insertSql, values);
 
@@ -295,7 +335,7 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
 
         // Fetch the created record to include auto-generated fields (e.g. id)
         const created = await adapterQuery(adapter,
-          `SELECT * FROM "${tableName}" WHERE "${pkColumn}" = ?`,
+          `SELECT * FROM ${q(tableName)} WHERE ${q(pkColumn)} = ?`,
           [lastId],
         );
 
@@ -313,14 +353,15 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const adapter = getAdapter();
+        const adapter = modelAdapter();
+        const q = (name: string): string => quoteIdentifier(adapter, name);
         const rawBody = req.body as Record<string, unknown>;
 
         // CRUD-MASS-ASSIGNMENT: allow-list -- the row is addressed by the URL
         // {id} alone, so a body PK is stripped (never lets the write rename
         // the row's own identity column or, on a mis-wired WHERE, redirect
         // to a different row); is_deleted is guarded the same as create.
-        const body = allowListedBody(fields, pkField, rawBody, false);
+        const body = allowListedBody(fields, getDbCol, pkField, rawBody, false);
 
         // Feature 19 (VALID-NODE-PUT-NOVALIDATE): the update path validates the
         // request body too — previously only POST did, so a PUT could write
@@ -334,9 +375,9 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
           return;
         }
 
-        const conditions = [`"${pkColumn}" = ?`, ...extraConditions];
+        const conditions = [`${q(pkColumn)} = ?`, ...extraConditions];
         const existing = await adapterQuery(adapter,
-          `SELECT * FROM "${tableName}" WHERE ${conditions.join(" AND ")}`,
+          `SELECT * FROM ${q(tableName)} WHERE ${conditions.join(" AND ")}`,
           [req.params.id],
         );
         if (existing.length === 0) {
@@ -359,17 +400,17 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         }
 
         const setClauses = Object.keys(dbBody)
-          .map((col) => `"${col}" = ?`)
+          .map((col) => `${q(col)} = ?`)
           .join(", ");
         const values = [...Object.values(dbBody), req.params.id];
 
         await adapterExecute(adapter,
-          `UPDATE "${tableName}" SET ${setClauses} WHERE "${pkColumn}" = ?`,
+          `UPDATE ${q(tableName)} SET ${setClauses} WHERE ${q(pkColumn)} = ?`,
           values,
         );
 
         const updated = await adapterQuery(adapter,
-          `SELECT * FROM "${tableName}" WHERE "${pkColumn}" = ?`,
+          `SELECT * FROM ${q(tableName)} WHERE ${q(pkColumn)} = ?`,
           [req.params.id],
         );
 
@@ -387,11 +428,12 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         tags: [tableName],
       },
       handler: async (req: Tina4Request, res: Tina4Response) => {
-        const adapter = getAdapter();
+        const adapter = modelAdapter();
+        const q = (name: string): string => quoteIdentifier(adapter, name);
 
-        const conditions = [`"${pkColumn}" = ?`, ...extraConditions];
+        const conditions = [`${q(pkColumn)} = ?`, ...extraConditions];
         const existing = await adapterQuery(adapter,
-          `SELECT * FROM "${tableName}" WHERE ${conditions.join(" AND ")}`,
+          `SELECT * FROM ${q(tableName)} WHERE ${conditions.join(" AND ")}`,
           [req.params.id],
         );
         if (existing.length === 0) {
@@ -401,13 +443,13 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
 
         if (softDelete) {
           await adapterExecute(adapter,
-            `UPDATE "${tableName}" SET is_deleted = 1 WHERE "${pkColumn}" = ?`,
+            `UPDATE ${q(tableName)} SET is_deleted = 1 WHERE ${q(pkColumn)} = ?`,
             [req.params.id],
           );
           res.json({ message: "Deleted (soft)", data: existing[0] });
         } else {
           await adapterExecute(adapter,
-            `DELETE FROM "${tableName}" WHERE "${pkColumn}" = ?`,
+            `DELETE FROM ${q(tableName)} WHERE ${q(pkColumn)} = ?`,
             [req.params.id],
           );
           res.json({ message: "Deleted", data: existing[0] });

package/packages/orm/src/baseModel.ts

@@ -1,13 +1,22 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import {
   getAdapter, getNamedAdapter, setAdapter, parseDatabaseUrl,
   adapterQuery, adapterFetch, adapterExecute, adapterFetchOne,
   adapterStartTransaction, adapterCommit, adapterRollback,
   adapterTableExists, adapterCreateTable, extractLastInsertId,
-  probeTotal, DEFAULT_ROW_CAP,
+  probeTotal, DEFAULT_ROW_CAP, quoteIdentifier,
 } from "./database.js";
 import { ModelCollection } from "./modelCollection.js";
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
+import { resolveFieldColumn } from "./query.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
 import { QueryCache, SQLTranslator } from "./sqlTranslator.js";
 import { Log } from "../../core/src/index.js";
@@ -379,6 +388,14 @@ export class BaseModel {
    * SQLite URLs are initialised synchronously. Other engines require initDatabase()
    * to be called before first use.
    */
+  /**
+   * Quote a table/column name in the dialect of the adapter this model runs on
+   * (MySQL backticks, Firebird upper-cased, `"name"` elsewhere).
+   */
+  protected static quoteName(name: string): string {
+    return quoteIdentifier(this.getDb(), name);
+  }
+
   protected static getDb(): DatabaseAdapter {
     if (this._db) {
       return getNamedAdapter(this._db);
@@ -497,7 +514,7 @@ export class BaseModel {
   static async findById<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): Promise<T | null> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const pkCol = ModelClass.getPkColumn();
-    let sql = `SELECT * FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`;
+    let sql = `SELECT * FROM ${ModelClass.quoteName(ModelClass.tableName)} WHERE ${ModelClass.quoteName(pkCol)} = ?`;
 
     if (ModelClass.softDelete) {
       sql += ` AND is_deleted = 0`;
@@ -598,8 +615,12 @@ export class BaseModel {
 
     if (filter) {
       for (const [key, value] of Object.entries(filter)) {
-        const col = ModelClass.getDbColumn(key) ?? key;
-        conditions.push(`"${col}" = ?`);
+        // ADR-0069: a filter key must be a declared field (or its column).
+        const col = resolveFieldColumn(ModelClass.fields, (field) => ModelClass.getDbColumn(field), key);
+        if (col === null) {
+          throw new Error(`Unknown filter field '${key}' for model ${ModelClass.name}`);
+        }
+        conditions.push(`${ModelClass.quoteName(col)} = ?`);
         params.push(value);
       }
     }
@@ -608,7 +629,7 @@ export class BaseModel {
       conditions.push("is_deleted = 0");
     }
 
-    let sql = `SELECT * FROM "${ModelClass.tableName}"`;
+    let sql = `SELECT * FROM ${ModelClass.quoteName(ModelClass.tableName)}`;
     if (conditions.length > 0) {
       sql += ` WHERE ${conditions.join(" AND ")}`;
     }
@@ -648,7 +669,7 @@ export class BaseModel {
       const pkCol = ModelClass.getPkColumn();
       const pkValue = (this as any)[pkProp];
       if (pkValue === undefined || pkValue === null) return false;
-      sql = `SELECT * FROM "${table}" WHERE "${pkCol}" = ?`;
+      sql = `SELECT * FROM ${ModelClass.quoteName(table)} WHERE ${ModelClass.quoteName(pkCol)} = ?`;
       params = [pkValue];
     } else {
       sql = `SELECT * FROM ${table} WHERE ${filter}`;
@@ -712,7 +733,7 @@ export class BaseModel {
     const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
     // No LIMIT/OFFSET embedded: _collect's adapterFetch applies them to the page
     // and the COUNT probe wraps the un-limited SQL so the total is the whole set.
-    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`;
+    const sql = `SELECT * FROM ${ModelClass.quoteName(ModelClass.tableName)}${whereClause}${orderClause}`;
 
     // No bind parameters: the only conditions left are the framework's own
     // softDelete / tableFilter literals. A caller-supplied filter belongs on
@@ -754,7 +775,7 @@ export class BaseModel {
     const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
     // No LIMIT/OFFSET embedded — _collect applies them to the page and probes
     // the total (ADR-0064). orderBy affects the page only; COUNT is order-free.
-    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")}${orderClause}`;
+    const sql = `SELECT * FROM ${ModelClass.quoteName(ModelClass.tableName)} WHERE ${parts.join(" AND ")}${orderClause}`;
 
     return ModelClass._collect<T>(sql, params, limit, offset, include);
   }
@@ -840,13 +861,13 @@ export class BaseModel {
     try {
       if (ModelClass.softDelete) {
         await adapterExecute(db,
-          `UPDATE "${ModelClass.tableName}" SET is_deleted = 1 WHERE ${this.pkWhere().sql}`,
+          `UPDATE ${ModelClass.quoteName(ModelClass.tableName)} SET is_deleted = 1 WHERE ${this.pkWhere().sql}`,
           this.pkWhere().params,
         );
         this.is_deleted = 1;
       } else {
         await adapterExecute(db,
-          `DELETE FROM "${ModelClass.tableName}" WHERE ${this.pkWhere().sql}`,
+          `DELETE FROM ${ModelClass.quoteName(ModelClass.tableName)} WHERE ${this.pkWhere().sql}`,
           this.pkWhere().params,
         );
       }
@@ -1136,7 +1157,7 @@ export class BaseModel {
     await adapterStartTransaction(db);
     try {
       await adapterExecute(db,
-        `DELETE FROM "${ModelClass.tableName}" WHERE ${this.pkWhere().sql}`,
+        `DELETE FROM ${ModelClass.quoteName(ModelClass.tableName)} WHERE ${this.pkWhere().sql}`,
         this.pkWhere().params,
       );
       await adapterCommit(db);
@@ -1169,7 +1190,7 @@ export class BaseModel {
     await adapterStartTransaction(db);
     try {
       await adapterExecute(db,
-        `UPDATE "${ModelClass.tableName}" SET is_deleted = 0 WHERE ${this.pkWhere().sql}`,
+        `UPDATE ${ModelClass.quoteName(ModelClass.tableName)} SET is_deleted = 0 WHERE ${this.pkWhere().sql}`,
         this.pkWhere().params,
       );
       await adapterCommit(db);
@@ -1203,7 +1224,7 @@ export class BaseModel {
       parts.push(conditions);
     }
 
-    let sql = `SELECT * FROM "${ModelClass.tableName}"`;
+    let sql = `SELECT * FROM ${ModelClass.quoteName(ModelClass.tableName)}`;
     if (parts.length > 0) {
       sql += ` WHERE ${parts.join(" AND ")}`;
     }
@@ -1230,7 +1251,7 @@ export class BaseModel {
       parts.push(conditions);
     }
     const whereClause = parts.length > 0 ? ` WHERE ${parts.join(" AND ")}` : "";
-    const sql = `SELECT COUNT(*) as cnt FROM "${this.tableName}"${whereClause}`;
+    const sql = `SELECT COUNT(*) as cnt FROM ${this.quoteName(this.tableName)}${whereClause}`;
     const rows = await adapterQuery(db, sql, params);
     if (rows.length === 0) return 0;
     // PostgreSQL returns COUNT(*) as a bigint, which the `pg` driver hands
@@ -1277,7 +1298,7 @@ export class BaseModel {
     }
 
     const db = relatedClass.getDb();
-    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${foreignKey}" = ?`;
+    let sql = `SELECT * FROM ${quoteIdentifier(db, relatedClass.tableName)} WHERE ${quoteIdentifier(db, foreignKey)} = ?`;
     if (relatedClass.softDelete) {
       sql += ` AND is_deleted = 0`;
     }
@@ -1325,12 +1346,12 @@ export class BaseModel {
 
     const db = relatedClass.getDb();
     const orderCol = relatedClass.getPkColumn();
-    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${foreignKey}" = ?`;
+    let sql = `SELECT * FROM ${quoteIdentifier(db, relatedClass.tableName)} WHERE ${quoteIdentifier(db, foreignKey)} = ?`;
     if (relatedClass.softDelete) {
       sql += ` AND is_deleted = 0`;
     }
     // Order by the child PK for a stable read (parity with the lazy accessor).
-    sql += ` ORDER BY "${orderCol}"`;
+    sql += ` ORDER BY ${quoteIdentifier(db, orderCol)}`;
     // IMPREL-PY-CAP parity: with no explicit limit, return the WHOLE set (like
     // the lazy accessor, which is uncapped) instead of a silent 100-row cap. An
     // explicit limit still pages (explicit, never silent).
@@ -1369,7 +1390,7 @@ export class BaseModel {
 
     const db = relatedClass.getDb();
     const relatedPkCol = relatedClass.getPkColumn();
-    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${relatedPkCol}" = ?`;
+    let sql = `SELECT * FROM ${quoteIdentifier(db, relatedClass.tableName)} WHERE ${quoteIdentifier(db, relatedPkCol)} = ?`;
     if (relatedClass.softDelete) {
       sql += ` AND is_deleted = 0`;
     }
@@ -1504,9 +1525,9 @@ export class BaseModel {
     if (pkValue === undefined || pkValue === null) return [];
     const db = relatedClass.getDb();
     const orderCol = relatedClass.getPkColumn();
-    let sql = `SELECT * FROM "${relatedClass.tableName}" WHERE "${foreignKey}" = ?`;
+    let sql = `SELECT * FROM ${quoteIdentifier(db, relatedClass.tableName)} WHERE ${quoteIdentifier(db, foreignKey)} = ?`;
     if (relatedClass.softDelete) sql += ` AND is_deleted = 0`;
-    sql += ` ORDER BY "${orderCol}"`;
+    sql += ` ORDER BY ${quoteIdentifier(db, orderCol)}`;
     const rows = await adapterQuery(db, sql, [pkValue]);
     return rows.map((row) => new (relatedClass as unknown as new (d: Record<string, unknown>) => BaseModel)(row as Record<string, unknown>));
   }
@@ -1606,11 +1627,11 @@ function validateBeforeSave(instance: BaseModel, model: typeof BaseModel, isUpda
 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 setClause = fields.map(([name]) => `${quoteIdentifier(db, 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);
+  await adapterExecute(db, `UPDATE ${quoteIdentifier(db, model.tableName)} SET ${setClause} WHERE ${where.sql}`, values);
 }
 
 function buildInsertStatement(
@@ -1623,17 +1644,28 @@ function buildInsertStatement(
   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}"` : "";
+  // The generated key comes back three ways: PostgreSQL and Firebird take a
+  // trailing RETURNING, MSSQL an OUTPUT INSERTED clause before VALUES, and
+  // SQLite / MySQL report it through lastInsertId(). MySQL and MSSQL reject a
+  // RETURNING outright, so an auto-increment save() used to fail on both. The
+  // engine comes from getDatabaseType(): the ORM holds the CachedDatabaseAdapter
+  // wrapper, whose constructor.name never names the engine.
+  const engine = db.getDatabaseType?.() ?? "";
+  const wantsKey = Boolean(pkField?.autoIncrement);
+  const returning = wantsKey && (engine === "postgres" || engine === "firebird")
+    ? ` RETURNING ${quoteIdentifier(db, pkCol)}` : "";
+  const output = wantsKey && engine === "mssql" ? ` OUTPUT INSERTED.${quoteIdentifier(db, pkCol)}` : "";
+  const table = quoteIdentifier(db, model.tableName);
   if (fields.length === 0) {
-    const emptyInsert = db.constructor.name === "MysqlAdapter"
-      ? `INSERT INTO "${model.tableName}" () VALUES ()`
-      : `INSERT INTO "${model.tableName}" DEFAULT VALUES`;
+    const emptyInsert = engine === "mysql"
+      ? `INSERT INTO ${table} () VALUES ()`
+      : `INSERT INTO ${table}${output} DEFAULT VALUES`;
     return { sql: emptyInsert + returning, values: [] };
   }
-  const columns = fields.map(([name]) => `"${model.getDbColumn(name)}"`).join(", ");
+  const columns = fields.map(([name]) => quoteIdentifier(db, 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 };
+  return { sql: `INSERT INTO ${table} (${columns})${output} VALUES (${placeholders})${returning}`, values };
 }
 
 function applyInsertedId(
@@ -1804,7 +1836,7 @@ async function eagerQueryRelated(
   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})`;
+    let sql = `SELECT * FROM ${quoteIdentifier(db, relatedClass.tableName)} WHERE ${quoteIdentifier(db, 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>));

package/packages/orm/src/cachedDatabase.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 Cached Database — Transparent query cache decorator for DatabaseAdapter.
  *
@@ -32,7 +40,8 @@
  *   db.cacheStats();                   // { enabled, mode, hits, misses, size, ttl }
  */
 
-import { QueryCache } from "./sqlTranslator.js";
+import { QueryCache, SQLTranslator } from "./sqlTranslator.js";
+import { quoteIdentifierAnsi } from "./adapters/sqlDialect.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
 import type { CacheBackend } from "../../core/src/index.js";
 
@@ -309,6 +318,25 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     if (b) { try { await b.set(key, { row }, this.ttl); } catch { /* best effort */ } }
   }
 
+  /**
+   * A write that arrives through a READ method (fetch/fetchOne/query of an
+   * `INSERT ... RETURNING`) is still a write: its result must never be cached
+   * (a repeat would answer from the cache and never insert) and it flushes the
+   * cache like every other write (tina4-python#133 contract).
+   */
+  private isWriteRead(sql: string): boolean {
+    return this.enabled && SQLTranslator.isWriteStatement(sql);
+  }
+
+  /** Run a write that came through a read method, then flush (never store). */
+  private runWrite<R>(run: () => R): R {
+    try { return run(); } finally { this.invalidate(); }
+  }
+
+  private async runWriteAsync<R>(run: () => Promise<R>): Promise<R> {
+    try { return await run(); } finally { await this.invalidateAsync(); }
+  }
+
   // ── DatabaseAdapter interface — writes flush, reads cache ──
 
   /** ADR-0044 required capability — delegates to the wrapped adapter. */
@@ -316,11 +344,28 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.connect?.();
   }
 
+  /**
+   * The derived-table alias the COUNT probe needs, forwarded from the wrapped
+   * adapter. SQL Server and MySQL REQUIRE `FROM (<sql>) AS _count_query`; the
+   * probe reads this property off whatever adapter it is handed, and
+   * Database.create() hands it THIS wrapper. Without the forward the probe ran
+   * unaliased, the engine rejected it, the error was swallowed, and
+   * `result.count` silently became the page length on those two engines.
+   */
+  get countSubqueryAlias(): string | undefined {
+    return (this.adapter as { countSubqueryAlias?: string } | null)?.countSubqueryAlias;
+  }
+
   /** ADR-0044 required capability — delegates to the wrapped adapter. */
   getDatabaseType(): string {
     return this.adapter.getDatabaseType();
   }
 
+  /** Identifier quoting is the wrapped engine's, never the wrapper's. */
+  quoteIdentifier(name: string): string {
+    return this.adapter.quoteIdentifier ? this.adapter.quoteIdentifier(name) : quoteIdentifierAnsi(name);
+  }
+
   /**
    * ADR-0044 required capability — a native boolean, readable and writable.
    * A getter/setter pair (not a plain field) so it genuinely delegates to the
@@ -347,6 +392,21 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.execute(sql, params);
   }
 
+  /**
+   * Forward an adapter's row-returning execute (SQLite, Firebird), for
+   * Database.execute(). Resolves `undefined` when the wrapped adapter has none
+   * - WITHOUT running anything - so the caller falls back to execute().
+   */
+  async executeRowsAsync(sql: string, params?: unknown[]): Promise<unknown[] | undefined> {
+    const inner = this.adapter as unknown as {
+      executeRowsAsync?: (s: string, p?: unknown[]) => Promise<unknown[]>;
+      executeRows?: (s: string, p?: unknown[]) => unknown[];
+    };
+    if (!inner.executeRowsAsync && !inner.executeRows) return undefined;
+    if (this.enabled) await this.invalidateAsync();
+    return inner.executeRowsAsync ? inner.executeRowsAsync(sql, params) : inner.executeRows!(sql, params);
+  }
+
   executeMany(sql: string, paramsList: unknown[][]): import("./types.js").DatabaseResult | { totalAffected: number; lastId?: number | bigint } {
     if (this.enabled) this.invalidate();
     return this.adapter.executeMany(sql, paramsList);
@@ -357,6 +417,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     // so caching here is what makes ORM reads dedupe — matching the Python master
     // where every ORM read flows through the cached db.fetch(). Same store, same
     // counters, flushed on writes.
+    if (this.isWriteRead(sql)) return this.runWrite(() => this.adapter.query<T>(sql, params));
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined, this.identity);
       const cached = this.cache.get<T[]>(key);
@@ -377,6 +438,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     // store, run straight against the underlying adapter (mirrors the Python
     // master's `no_cache`). Counters are left untouched so a bypass read isn't
     // misreported as a hit or a miss.
+    if (this.isWriteRead(sql)) return this.runWrite(() => this.adapter.fetch<T>(sql, params, limit, skip));
     if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined, this.identity);
       const cached = this.cache.get<T[]>(key);
@@ -393,6 +455,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   }
 
   fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): T | null {
+    if (this.isWriteRead(sql)) return this.runWrite(() => this.adapter.fetchOne<T>(sql, params));
     if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined, this.identity);
       const cached = this.cache.get<T | null>(key);
@@ -488,6 +551,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       : this.adapter.fetch<T>(sql, params, limit, skip);
     // `noCache` bypasses both cache layers for this one call — no lookup, no
     // store, run directly (mirrors the Python master's `no_cache`).
+    if (this.isWriteRead(sql)) return this.runWriteAsync(run);
     if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined, this.identity);
       // Persistent distributed backend is AUTHORITATIVE (mirrors Python, where a
@@ -520,6 +584,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       ? await (this.adapter as any).fetchOneAsync(sql, params)
       : this.adapter.fetchOne<T>(sql, params);
     // `noCache` bypasses both cache layers for this one call (see fetchAsync).
+    if (this.isWriteRead(sql)) return this.runWriteAsync(run);
     if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined, this.identity);
       if (this.usesPersistentBackend()) {
@@ -547,6 +612,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     const run = async (): Promise<T[]> => (this.adapter as any).queryAsync
       ? await (this.adapter as any).queryAsync(sql, params)
       : this.adapter.query<T>(sql, params);
+    if (this.isWriteRead(sql)) return this.runWriteAsync(run);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined, this.identity);
       if (this.usesPersistentBackend()) {

package/packages/orm/src/connectTimeout.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * TINA4_DATABASE_CONNECT_TIMEOUT - bound a database connect attempt.
  *