tina4-nodejs 3.13.37 → 3.13.39

package/packages/orm/src/adapters/sqlite.ts

@@ -9,6 +9,45 @@ function isIdentifier(str: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(str);
 }
 
+/**
+ * The value shape `node:sqlite` binds as a statement parameter. Mirrors the
+ * module-internal `SQLInputValue` type (which is not exported from
+ * `node:sqlite`, so it cannot be imported). The DatabaseAdapter interface
+ * carries params as `unknown[]`; this narrows them to the bindable shape at the
+ * `.run()`/`.all()`/`.get()` call sites without an `any` cast.
+ */
+type SqlParam = null | number | bigint | string | NodeJS.ArrayBufferView;
+
+/** Narrow adapter-level `unknown[]` params to node:sqlite's bindable type. */
+function toSqlParams(params: readonly unknown[]): SqlParam[] {
+  return params as SqlParam[];
+}
+
+/**
+ * Whether the linked SQLite library is at least the given version.
+ *
+ * Used to gate `UPDATE ... RETURNING` (SQLite >= 3.35) in the atomic
+ * sequence path. Memoised — the version never changes at runtime.
+ */
+let _sqliteVersionInfo: [number, number, number] | null = null;
+function sqliteVersionAtLeast(major: number, minor: number, patch: number): boolean {
+  if (_sqliteVersionInfo === null) {
+    try {
+      const probe = new DatabaseSync(":memory:");
+      const row = probe.prepare("SELECT sqlite_version() AS v").get() as { v?: string };
+      probe.close();
+      const parts = String(row?.v ?? "0.0.0").split(".").map((n) => parseInt(n, 10) || 0);
+      _sqliteVersionInfo = [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+    } catch {
+      _sqliteVersionInfo = [0, 0, 0];
+    }
+  }
+  const [ma, mi, pa] = _sqliteVersionInfo;
+  if (ma !== major) return ma > major;
+  if (mi !== minor) return mi > minor;
+  return pa >= patch;
+}
+
 /**
  * Resolve a SQLite path argument against the project root (cwd).
  *
@@ -55,7 +94,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   execute(sql: string, params?: unknown[]): unknown {
     const stmt = this.db.prepare(sql);
-    const result = params ? stmt.run(...params) : stmt.run();
+    const result = params ? stmt.run(...toSqlParams(params)) : stmt.run();
     if (result && typeof result === "object" && "lastInsertRowid" in result) {
       this._lastInsertId = result.lastInsertRowid as number | bigint;
     }
@@ -70,8 +109,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     this.db.exec("BEGIN TRANSACTION");
     try {
       for (const params of paramsList) {
-        const result = stmt.run(...params);
-        totalAffected += result.changes;
+        const result = stmt.run(...toSqlParams(params));
+        totalAffected += Number(result.changes);
         if (result.lastInsertRowid) {
           lastId = result.lastInsertRowid;
           this._lastInsertId = result.lastInsertRowid;
@@ -88,7 +127,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
     const stmt = this.db.prepare(sql);
-    return (params ? stmt.all(...params) : stmt.all()) as T[];
+    return (params ? stmt.all(...toSqlParams(params)) : stmt.all()) as T[];
   }
 
   fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
@@ -108,7 +147,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
     const stmt = this.db.prepare(sql);
-    const row = params ? stmt.get(...params) : stmt.get();
+    const row = params ? stmt.get(...toSqlParams(params)) : stmt.get();
     return (row as T) ?? null;
   }
 
@@ -129,9 +168,9 @@ export class SQLiteAdapter implements DatabaseAdapter {
     const values = Object.values(data);
 
     try {
-      const result = this.db.prepare(sql).run(...values);
+      const result = this.db.prepare(sql).run(...toSqlParams(values));
       this._lastInsertId = result.lastInsertRowid;
-      return { success: true, rowsAffected: result.changes, lastInsertId: result.lastInsertRowid };
+      return { success: true, rowsAffected: Number(result.changes), lastInsertId: result.lastInsertRowid };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };
     }
@@ -144,8 +183,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     const values = [...Object.values(data), ...Object.values(filter)];
 
     try {
-      const result = this.db.prepare(sql).run(...values);
-      return { success: true, rowsAffected: result.changes };
+      const result = this.db.prepare(sql).run(...toSqlParams(values));
+      return { success: true, rowsAffected: Number(result.changes) };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };
     }
@@ -164,8 +203,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     if (typeof filter === "string") {
       const sql = filter ? `DELETE FROM "${table}" WHERE ${filter}` : `DELETE FROM "${table}"`;
       try {
-        const result = this.db.prepare(sql).run(...(params ?? []));
-        return { success: true, rowsAffected: result.changes };
+        const result = this.db.prepare(sql).run(...toSqlParams(params ?? []));
+        return { success: true, rowsAffected: Number(result.changes) };
       } catch (e) {
         return { success: false, rowsAffected: 0, error: (e as Error).message };
       }
@@ -176,8 +215,8 @@ export class SQLiteAdapter implements DatabaseAdapter {
     const values = Object.values(filter);
 
     try {
-      const result = this.db.prepare(sql).run(...values);
-      return { success: true, rowsAffected: result.changes };
+      const result = this.db.prepare(sql).run(...toSqlParams(values));
+      return { success: true, rowsAffected: Number(result.changes) };
     } catch (e) {
       return { success: false, rowsAffected: 0, error: (e as Error).message };
     }
@@ -233,6 +272,66 @@ export class SQLiteAdapter implements DatabaseAdapter {
   lastInsertId(): number | bigint | null { return this._lastInsertId; }
   close(): void { this.db.close(); }
 
+  /**
+   * Atomically increment and return the next value of a tina4_sequences row.
+   *
+   * DB-contract B (no duplicate primary keys under concurrency): the old
+   * read-increment-read path in Database.sequenceNext() yields at every `await`
+   * between the read and the write, so two concurrent async callers can read the
+   * same `current_value` and return the same id. This method runs the WHOLE
+   * operation — ensure-table, seed-if-absent, and the increment-and-return — as
+   * ONE synchronous burst on the single shared `node:sqlite` connection. Because
+   * `node:sqlite` is synchronous and JavaScript is single-threaded, no other
+   * async task can interleave between the statements (there is no `await`
+   * inside), so the increment is atomic and every caller gets a distinct id.
+   * This is the Node analog of the Python master holding SQLiteAdapter._write_lock
+   * across the whole op.
+   *
+   * On SQLite >= 3.35 a single `UPDATE ... SET current_value = current_value + 1
+   * ... RETURNING current_value` is itself atomic and returns the new value in
+   * one statement (read via prepare().all() — stmt.run() does not surface
+   * RETURNING rows). Older SQLite does `UPDATE ... + 1` then `SELECT`, still
+   * race-safe because both run in the same synchronous burst.
+   *
+   * @throws if the sequence row vanishes mid-increment (never silently returns 1).
+   */
+  sequenceNextSqlite(seqName: string, seedValue: number): number {
+    // Ensure the sequence table exists (idempotent).
+    this.db.exec(
+      "CREATE TABLE IF NOT EXISTS tina4_sequences (" +
+      "seq_name VARCHAR(200) NOT NULL PRIMARY KEY, " +
+      "current_value INTEGER NOT NULL DEFAULT 0)",
+    );
+    // Race-safe seed: INSERT OR IGNORE is a no-op if the row already exists, so
+    // there is never a read-then-insert gap.
+    this.db.prepare(
+      "INSERT OR IGNORE INTO tina4_sequences (seq_name, current_value) VALUES (?, ?)",
+    ).run(seqName, seedValue);
+
+    const supportsReturning = sqliteVersionAtLeast(3, 35, 0);
+    let row: { current_value?: number | bigint } | undefined;
+    if (supportsReturning) {
+      // One atomic increment-and-return.
+      row = this.db.prepare(
+        "UPDATE tina4_sequences SET current_value = current_value + 1 " +
+        "WHERE seq_name = ? RETURNING current_value",
+      ).get(seqName) as { current_value?: number | bigint } | undefined;
+    } else {
+      // Older SQLite (< 3.35, no RETURNING): increment then read. Still
+      // race-safe because both run in the same synchronous burst (no await).
+      this.db.prepare(
+        "UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ?",
+      ).run(seqName);
+      row = this.db.prepare(
+        "SELECT current_value FROM tina4_sequences WHERE seq_name = ?",
+      ).get(seqName) as { current_value?: number | bigint } | undefined;
+    }
+    if (!row || row.current_value == null) {
+      throw new Error(`getNextId: sequence row '${seqName}' vanished mid-increment`);
+    }
+    return Number(row.current_value);
+  }
+
   tableExists(name: string): boolean {
     // v3.13.14 (#48): a SQLite "schema" is an ATTACH alias ("extra.widget").
     // Query that database's own sqlite_master when the prefix is a plain

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.
    */
@@ -1086,7 +1225,10 @@ export class BaseModel {
 
     const related = new relatedClass(rows[0] as Record<string, unknown>) as R;
     const relKey = relatedClass.tableName.toLowerCase();
-    this[relKey] = related;
+    // Write through the BaseModel index signature: a generic `T` cannot be
+    // indexed for writing (TS2862), but `T extends BaseModel` guarantees `this`
+    // is a BaseModel, whose `[key: string]: unknown` signature is writable.
+    (this as BaseModel)[relKey] = related;
     return related;
   }
 
@@ -1118,7 +1260,8 @@ export class BaseModel {
     const rows = await adapterQuery(db, sql, [pkValue]);
     const related = rows.map((row) => new relatedClass(row as Record<string, unknown>) as R);
     const relKey = relatedClass.tableName.toLowerCase();
-    this[relKey] = related;
+    // See hasOne: write through BaseModel's writable index signature (TS2862).
+    (this as BaseModel)[relKey] = related;
     return related;
   }
 
@@ -1153,7 +1296,8 @@ export class BaseModel {
 
     const related = new relatedClass(rows[0] as Record<string, unknown>) as R;
     const relKey = relatedClass.tableName.toLowerCase();
-    this[relKey] = related;
+    // See hasOne: write through BaseModel's writable index signature (TS2862).
+    (this as BaseModel)[relKey] = related;
     return related;
   }
 
@@ -1244,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/cachedDatabase.ts

@@ -7,11 +7,14 @@
  *
  * One store, two layers (mirrors the Python master — tina4_python/database/connection.py):
  *
- *   • request-scoped (DEFAULT ON, off-switch TINA4_AUTO_CACHING=false) — dedupes
+ *   • request-scoped (DEFAULT OFF, opt-in TINA4_AUTO_CACHING=true) — dedupes
  *     identical SELECTs to protect the DB from rapid repeat reads. Cleared at the
  *     START of every HTTP request (via Database.resetRequestCaches()) AND on any
  *     write, with a short safety TTL (TINA4_AUTO_CACHING_TTL, default 5s) for
- *     non-request contexts (scripts/workers).
+ *     non-request contexts (scripts/workers). Default OFF because a request-scoped
+ *     cache defaulting ON is a footgun — a read-after-write in one request (e.g.
+ *     SELECT MAX(id) then INSERT) returns a cached pre-write value. Opt in for
+ *     read-heavy endpoints.
  *   • persistent (opt-in, TINA4_DB_CACHE=true) — cross-request TTL cache that is
  *     NOT cleared per request; entries expire by TINA4_DB_CACHE_TTL (default 30s).
  *
@@ -45,7 +48,7 @@ function isTruthy(val: string | undefined): boolean {
 export interface CachedAdapterOptions {
   /** Force-enable the persistent (cross-request) layer. Defaults to TINA4_DB_CACHE. */
   persistent?: boolean;
-  /** Force-enable the request-scoped layer. Defaults to TINA4_AUTO_CACHING (default true). */
+  /** Force-enable the request-scoped layer. Defaults to TINA4_AUTO_CACHING (default false / opt-in). */
   requestScoped?: boolean;
   /** Override the effective TTL (seconds). Defaults to the mode-appropriate env var. */
   ttl?: number;
@@ -65,7 +68,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   private cache: QueryCache;
   /** Persistent (cross-request) layer — TINA4_DB_CACHE. */
   private cachePersistent: boolean;
-  /** Request-scoped layer — TINA4_AUTO_CACHING (default ON). */
+  /** Request-scoped layer — TINA4_AUTO_CACHING (default OFF / opt-in). */
   private cacheRequestScoped: boolean;
   private enabled: boolean;
   private ttl: number;
@@ -94,8 +97,14 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   constructor(adapter: DatabaseAdapter, options: CachedAdapterOptions = {}) {
     this.adapter = adapter;
     this.cachePersistent = options.persistent ?? isTruthy(process.env.TINA4_DB_CACHE);
-    this.cacheRequestScoped = options.requestScoped
-      ?? (process.env.TINA4_AUTO_CACHING === undefined ? true : isTruthy(process.env.TINA4_AUTO_CACHING));
+    // Request-scoped cache defaults to OFF (opt-in). A request-scoped cache
+    // defaulting ON is a footgun: a `SELECT MAX(id)` (or generator read) right
+    // before an INSERT in the same request returns a cached pre-write value →
+    // duplicate primary keys; any read-after-write in one request shows stale
+    // state. So the DEFAULT is OFF; opt in for read-heavy endpoints with
+    // TINA4_AUTO_CACHING=true. Mirrors the Python master
+    // (tina4_python/database/connection.py: default literal "false").
+    this.cacheRequestScoped = options.requestScoped ?? isTruthy(process.env.TINA4_AUTO_CACHING);
     this.enabled = this.cachePersistent || this.cacheRequestScoped;
 
     if (options.ttl !== undefined) {