tina4-nodejs 3.13.94 → 3.13.96

package/packages/orm/src/index.ts

@@ -7,11 +7,8 @@ export type {
   ColumnInfo,
   QueryOptions,
   RelationshipDefinition,
-  PaginatedResult,
 } from "./types.js";
 
-export { FetchResult } from "./types.js";
-
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
 export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
@@ -21,7 +18,9 @@ export {
   adapterTableExists, adapterTables, adapterColumns, adapterCreateTable,
   extractLastInsertId,
 } from "./database.js";
-export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
+export type { DatabaseConfig } from "./database.js";
+export { DatabaseUrl, redactCredentials } from "./databaseUrl.js";
+export type { DatabaseEngine } from "./databaseUrl.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";
 export {
@@ -54,6 +53,14 @@ export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export {
+  DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS,
+  CONNECT_TIMEOUT_TOLERANCE_MS,
+  connectTimeoutMillis,
+  driverConnectTimeoutMillis,
+  connectTarget,
+  withConnectTimeout,
+} from "./connectTimeout.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export type { CachedAdapterOptions } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";
@@ -62,8 +69,8 @@ export type { SeedSummary, SeedOptions } from "./seeder.js";
 
 // DocStore — pymongo-style document store with a zero-config SQLite (JSON1) fallback
 export {
-  ObjectId, InvalidId, SqliteDatabase, SqliteCollection, Cursor,
-  getCollection, isServerless, resetDefaultStore,
+  ObjectId, InvalidId, DocStoreDriverMissing, SqliteDatabase, SqliteCollection, Cursor,
+  getCollection, isServerless, resetDefaultStore, closeDocStore,
   encodeValue, decodeValue, compileFilter,
 } from "./docstore.js";
 export type {

package/packages/orm/src/migration.ts

@@ -217,7 +217,14 @@ export async function syncModels(models: DiscoveredModel[]): Promise<void> {
       console.log(`    Created table: ${tableName}`);
     } else {
       // Check for new columns. SQLite exposes the legacy getTableColumns/
-      // addColumn helpers; other engines use columns()/ALTER TABLE.
+      // addColumn helpers; other engines use getColumns()/ALTER TABLE.
+      //
+      // Collapsing this into getColumns() looks obviously right and is NOT:
+      // it broke the legacy NOT NULL migration_id path, which is the bug that
+      // wedged every migration for ~20 releases (python#93). getTableColumns
+      // reads PRAGMA directly; getColumns goes through schema splitting and
+      // does not return the same thing here. Removing it needs its own change
+      // with that path tested, not a drive-by in an interface tidy-up.
       const existingCols = (adapter as any).getTableColumns
         ? (adapter as SQLiteAdapter).getTableColumns(tableName)
         : await adapterColumns(adapter, tableName);
@@ -508,8 +515,16 @@ async function recordApplied(
  */
 async function trackingColumns(db: DatabaseAdapter): Promise<Set<string>> {
   try {
-    // The DatabaseAdapter contract exposes columns(), not getColumns().
-    const cols = await (db as any).columns?.(MIGRATION_TABLE);
+    // The DatabaseAdapter contract exposes getColumns() (feature 3: renamed from
+    // columns() to match the other three frameworks and the get- prefix used
+    // everywhere else).
+    //
+    // This reads through `as any`, so the compiler could not catch the rename
+    // here - it went silently to undefined, `cols` came back empty, migration_id
+    // was left out of the insert and every migration failed on the legacy
+    // NOT NULL column. Exactly the failure python#93 caused, from the opposite
+    // direction. Kept optional-chained for adapters that predate the contract.
+    const cols = await (db as any).getColumns?.(MIGRATION_TABLE);
     if (!Array.isArray(cols)) return new Set();
     return new Set(
       cols.map((c: any) => String(c?.name ?? c ?? "").toLowerCase()).filter(Boolean),
@@ -1161,9 +1176,24 @@ export async function status(
  */
 export async function createMigration(
   description: string,
-  options?: { migrationsDir?: string; kind?: "sql" | "class" },
+  options?: { migrationsDir?: string; kind?: "sql" | "code" | "class" },
 ): Promise<string | { upPath: string; downPath: string }> {
-  if (options?.kind === "class") {
+  // MEASURED 2026-08-06: the accepted kind differed in every framework -
+  // python "python", php "php", ruby "ruby" OR "python", node "class" - and
+  // NONE validated it, so create_migration(..., kind="python") produced a code
+  // migration in Python and Ruby and a SILENT .sql file in PHP and Node.
+  // "code" is now the canonical spelling in all four; each keeps its own
+  // language name as a legacy alias; anything else raises.
+  const kind = (options?.kind ?? "sql").trim().toLowerCase();
+  if (!["sql", "code", "class"].includes(kind)) {
+    throw new Error(
+      `Unknown migration kind "${kind}". Use "sql" (default) or "code" ` +
+        `(alias: "class"). An unrecognised kind used to produce a .sql file ` +
+        `silently, which is why this now throws.`,
+    );
+  }
+
+  if (kind === "code" || kind === "class") {
     return createClassMigration(description, options);
   }
   const dir = resolve(options?.migrationsDir ?? "migrations");
@@ -1322,15 +1352,18 @@ export class Migration {
    * Scaffold a new migration file.
    *
    * kind="sql"   — creates {timestamp}_{description}.sql + .down.sql (default)
-   * kind="class" — creates {timestamp}_{description}.ts with a TypeScript class template
+   * kind="code"  — creates {timestamp}_{description}.ts with a TypeScript class
+   *                 template. "class" is accepted as a legacy alias.
    *
    * Returns the path to the created up file (or class file).
    */
-  async create(description: string, kind: "sql" | "class" = "sql"): Promise<string | { upPath: string; downPath: string }> {
-    if (kind === "class") {
-      return createClassMigration(description, { migrationsDir: this.dir });
-    }
-    return createMigration(description, { migrationsDir: this.dir });
+  async create(
+    description: string,
+    kind: "sql" | "code" | "class" = "sql",
+  ): Promise<string | { upPath: string; downPath: string }> {
+    // Route through createMigration so the validation lives in ONE place - a
+    // second copy of the accepted set is a second place for it to drift.
+    return createMigration(description, { migrationsDir: this.dir, kind });
   }
 
   /** Return list of completed (applied) migration filenames. */

package/packages/orm/src/model.ts

@@ -38,6 +38,10 @@ export async function discoverModels(modelsDir: string): Promise<DiscoveredModel
 
       const definition: ModelDefinition = {
         tableName: ModelClass.tableName,
+        // The class name is the type name a generated OpenAPI client wants
+        // (`Item`, not `items`). Carry it so Swagger keys components.schemas by
+        // it. A model exported as `default` keeps its declared class name here.
+        className: typeof ModelClass.name === "string" && ModelClass.name ? ModelClass.name : undefined,
         fields: ModelClass.fields as Record<string, FieldDefinition>,
         fieldMapping: ModelClass.fieldMapping as Record<string, string> | undefined,
         softDelete: ModelClass.softDelete ?? false,

package/packages/orm/src/queryBuilder.ts

@@ -18,7 +18,8 @@
  */
 
 import type { DatabaseAdapter } from "./types.js";
-import { getAdapter, adapterFetch, adapterFetchOne } from "./database.js";
+import { getAdapter, adapterFetch, adapterFetchOne, probeTotal } from "./database.js";
+import { DatabaseResult } from "./databaseResult.js";
 
 export class QueryBuilder {
   private table: string;
@@ -198,21 +199,61 @@ export class QueryBuilder {
   }
 
   /**
-   * Execute the query and return all matching rows.
+   * Execute the query and return a DatabaseResult.
    *
-   * @returns Array of row objects.
+   * BREAKING (3.13.95, parity): this returned a bare array of rows. The other
+   * three frameworks all return the DatabaseResult that `db.fetch()` produces:
+   *   Python  get() -> DatabaseResult   (orm/query_builder/__init__.py)
+   *   PHP     get(): mixed -> $this->db->fetch(...)
+   *   Ruby    get -> @db.fetch(...)
+   * Node was the odd one out, so the same builder chain returned a different
+   * TYPE per language and portable code could not read `.records`, `.count`,
+   * `.limit` or `.offset` off it.
+   *
+   * MIGRATION: read `.records` for the rows.
+   *   before: const rows = await qb.get();          rows.length
+   *   after:  const result = await qb.get();        result.records.length
+   * DatabaseResult is iterable, so `for (const row of result)` and
+   * `[...result]` work unchanged, and `response()`/`res.json()` already
+   * auto-serialize it to a JSON array.
+   *
+   * No default LIMIT is applied when `.limit()` was never called (v3.13.39) --
+   * a silent cap here was a data-loss-on-read footgun. That is unchanged.
+   *
+   * @returns DatabaseResult carrying `.records`, `.count`, `.limit`, `.offset`.
    */
-  async get<T = Record<string, unknown>>(): Promise<T[]> {
+  async get(): Promise<DatabaseResult> {
     this.ensureDb();
     const sql = this.toSql();
     const allParams = [...this.params, ...this.havingParams];
 
-    return adapterFetch<T>(
+    const queryParams = allParams.length > 0 ? allParams : undefined;
+    const rows = await adapterFetch(
       this.db!,
       sql,
-      allParams.length > 0 ? allParams : undefined,
+      queryParams,
+      this.limitVal,
+      this.offsetVal,
+    );
+
+    // Constructed exactly as Database._fetchWithLimit does, so a QueryBuilder
+    // result and a db.fetch() result are the same object in the same state --
+    // INCLUDING `count`, which is the TRUE total for the filter via the shared
+    // COUNT probe (ADR-0043), not rows-returned. Python's get() -> db.fetch()
+    // and Ruby's get -> @db.fetch() already carried the true total; Node used to
+    // leave it at the row count here, so `QueryBuilder.get().toPaginate()`
+    // under-reported `total` while `db.fetch().toPaginate()` did not. The probe
+    // is best-effort (undefined on any error -> falls back to rows.length) and
+    // only runs when a limit was applied, so an unlimited get() is one query.
+    const total = await probeTotal(this.db!, sql, queryParams, this.limitVal);
+    return new DatabaseResult(
+      rows as Record<string, unknown>[],
+      undefined,
+      total,
       this.limitVal,
       this.offsetVal,
+      this.db!,
+      sql,
     );
   }
 

package/packages/orm/src/sqlTranslator.ts

@@ -19,6 +19,7 @@
 
 // ── SQL Translator ───────────────────────────────────────────
 
+import { DatabaseUrl } from "./databaseUrl.js";
 export class SQLTranslator {
   /**
    * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
@@ -172,6 +173,271 @@ export class SQLTranslator {
     if (idx === -1) return [null, name];
     return [name.slice(0, idx), name.slice(idx + 1)];
   }
+
+  /**
+   * Hard per-statement bind-parameter ceiling per engine. 0 = never collapse.
+   * Sourced from test/fixtures/batch_write_contract.json, byte-identical in all
+   * four frameworks.
+   */
+  static readonly MAX_BIND_PARAMS: Record<string, number> = {
+    sqlite: 999,
+    postgres: 65535,
+    mysql: 65535,
+    mssql: 2100,
+    firebird: 0,
+    odbc: 0,
+    mongodb: 0,
+  };
+
+  /**
+   * The four frameworks do not agree on what an engine calls itself — Python
+   * and PHP report "postgresql", Ruby and Node report "postgres". Without
+   * normalising, the cap lookup misses and the collapse silently does nothing
+   * on the engine with the largest win.
+   */
+  static readonly ENGINE_ALIASES: Record<string, string> = {
+    postgresql: "postgres",
+    pgsql: "postgres",
+    sqlite3: "sqlite",
+    sqlserver: "mssql",
+    sqlsrv: "mssql",
+    mariadb: "mysql",
+  };
+
+  // The `d` flag records group indices, so the head can be sliced at the exact
+  // start of the VALUES group rather than by hunting for a parenthesis (the
+  // column list has parentheses too).
+  private static readonly INSERT_VALUES =
+    /^\s*INSERT\s+INTO\s+.+?\s+VALUES\s*\(([^()]*)\)\s*$/dis;
+
+  /**
+   * Engines whose lastInsertId reports the FIRST generated id of a multi-row
+   * INSERT rather than the last. Verified live, not assumed: a 3-row insert
+   * into a fresh MySQL table reports 1 while MAX(id) is 3. SQLite, PostgreSQL
+   * and MSSQL already report the last, so collapsing does not change them.
+   */
+  static readonly FIRST_ID_ENGINES: readonly string[] = ["mysql"];
+
+  /**
+   * Normalise a collapsed batch's last id to the LAST row's id.
+   *
+   * A row-at-a-time batch reports the last row's id simply because the last
+   * statement inserted the last row. Collapsing rows into one statement changes
+   * that on any engine that reports the FIRST generated id, so this restores
+   * the contract instead of quietly redefining it. The ids in one statement are
+   * consecutive, so the last is `first + rows - 1`.
+   */
+  static batchLastId(reportedId: unknown, rowsInChunk: number, engine: string): unknown {
+    const lower = (engine ?? "").toLowerCase();
+    const name = SQLTranslator.ENGINE_ALIASES[lower] ?? lower;
+    if (!SQLTranslator.FIRST_ID_ENGINES.includes(name)) return reportedId;
+
+    const n = typeof reportedId === "bigint" ? Number(reportedId) : Number(reportedId);
+    if (reportedId === null || reportedId === undefined || Number.isNaN(n)) {
+      return reportedId;                    // UUID/ULID key — no successor
+    }
+    return n + Math.max(rowsInChunk, 1) - 1;
+  }
+
+  /**
+   * Collapse a row-at-a-time INSERT batch into chunked multi-row VALUES.
+   *
+   * A batch that loops one INSERT per row pays a full network round-trip per
+   * row, and the round-trip — not SQL building — is the entire cost of a batch
+   * write. Measured over 500 rows: PostgreSQL 9848ms row-at-a-time against
+   * 15.8ms as a single multi-row statement (625x), MySQL 216x, MSSQL 121x.
+   *
+   * PURE: no I/O and no engine contact, so the chunking rules are checkable
+   * without a database. The live-engine runners prove the rows land.
+   *
+   * @returns Statements to run INSTEAD of the loop, or an EMPTY array meaning
+   *          "not collapsible — keep looping", which is always correct.
+   */
+  static buildBatchInserts(
+    sql: string,
+    paramSets: unknown[][],
+    engine: string,
+  ): Array<[string, unknown[]]> {
+    const rows = paramSets ?? [];
+    if (rows.length < 2) return [];
+
+    const lower = (engine ?? "").toLowerCase();
+    const name = SQLTranslator.ENGINE_ALIASES[lower] ?? lower;
+    const cap = SQLTranslator.MAX_BIND_PARAMS[name] ?? 0;
+    // Firebird has no multi-row VALUES syntax (verified against a live 5.0.4:
+    // -104 Token unknown); ODBC's real ceiling depends on the driver behind it.
+    // Emitting SQL the engine cannot parse to save a round-trip is not a trade
+    // worth making.
+    if (cap <= 0) return [];
+
+    const upper = sql.toUpperCase();
+    // A collapsed statement returns N rows where the caller expects one, and
+    // conflict arbitration changes once rows share a statement.
+    if (
+      upper.includes("RETURNING") ||
+      upper.includes("ON CONFLICT") ||
+      upper.includes("ON DUPLICATE KEY")
+    ) {
+      return [];
+    }
+
+    const match = SQLTranslator.INSERT_VALUES.exec(sql);
+    if (match === null) return [];
+
+    // Every slot must be a bare placeholder. `now()` repeated per row inside one
+    // statement is not the same write as `now()` evaluated per statement.
+    const slots = match[1].split(",").map((s) => s.trim());
+    if (slots.length === 0 || slots.some((s) => s !== "?")) return [];
+
+    const columns = slots.length;
+    if (rows.some((params) => params.length !== columns)) return [];
+
+    const chunkRows = Math.max(1, Math.floor(cap / columns));
+    if (chunkRows < 2) return [];
+
+    const valuesStart = match.indices?.[1]?.[0];
+    if (valuesStart === undefined) return [];
+    const head = sql.slice(0, valuesStart - 1).trimEnd();
+    const oneRow = `(${new Array(columns).fill("?").join(", ")})`;
+
+    const statements: Array<[string, unknown[]]> = [];
+    for (let start = 0; start < rows.length; start += chunkRows) {
+      const chunk = rows.slice(start, start + chunkRows);
+      const flat: unknown[] = [];
+      for (const params of chunk) flat.push(...params);
+      statements.push([`${head} ${new Array(chunk.length).fill(oneRow).join(", ")}`, flat]);
+    }
+    return statements;
+  }
+
+  /**
+   * Blank out string literals, quoted identifiers and comments, so a keyword
+   * search sees only real SQL. Blanks are spaces of the SAME LENGTH (newlines
+   * preserved), so offsets and line structure still line up with the original.
+   *
+   * This exists because "does the caller's SQL already have a LIMIT?" used to be
+   * `sql.toUpperCase().split("--")[0].includes("LIMIT")`, and MEASURED on a real
+   * 150-row table with the 100-row cap in force, every one of these returned
+   * ALL 150 ROWS instead of 100:
+   *
+   *     SELECT * FROM t WHERE label != 'LIMIT' ORDER BY id     -- literal
+   *     SELECT * FROM t ORDER BY id -- LIMIT 5                 -- line comment
+   *     SELECT * FROM t ORDER BY id /* LIMIT 5 *\/              -- block comment
+   *
+   * A column named `rate_limit` does it too. That is a silently UNCAPPED read of
+   * a whole table, which is the exact production incident the row cap exists to
+   * prevent, reachable through an ordinary column name.
+   *
+   * @param sql Raw SQL, exactly as the caller wrote it.
+   * @returns The same string with literals and comments replaced by spaces.
+   */
+  static scrubSqlText(sql: string): string {
+    let out = "";
+    let i = 0;
+    const blank = (ch: string): string => (ch === "\n" ? "\n" : " ");
+
+    while (i < sql.length) {
+      const c = sql[i];
+      const next = sql[i + 1];
+
+      // '...' string literal, with '' as the embedded-quote escape
+      if (c === "'" || c === '"') {
+        const quote = c;
+        out += " ";
+        i++;
+        while (i < sql.length) {
+          if (sql[i] === quote) {
+            if (sql[i + 1] === quote) {
+              out += "  ";
+              i += 2;
+              continue;
+            }
+            out += " ";
+            i++;
+            break;
+          }
+          out += blank(sql[i]);
+          i++;
+        }
+        continue;
+      }
+
+      // -- line comment, to end of line
+      if (c === "-" && next === "-") {
+        while (i < sql.length && sql[i] !== "\n") {
+          out += " ";
+          i++;
+        }
+        continue;
+      }
+
+      // /* block comment */
+      if (c === "/" && next === "*") {
+        out += "  ";
+        i += 2;
+        while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/")) {
+          out += blank(sql[i]);
+          i++;
+        }
+        if (i < sql.length) {
+          out += "  ";
+          i += 2;
+        }
+        continue;
+      }
+
+      out += c;
+      i++;
+    }
+
+    return out;
+  }
+
+  /**
+   * True when the statement ENDS with its own LIMIT clause, so appending another
+   * would be wrong (and on SQLite, a syntax error).
+   *
+   * Anchored to the END on purpose. A bare "contains LIMIT" test also matches a
+   * LIMIT inside a subquery, where the OUTER statement still needs its cap. This
+   * is tina4-php's `SqlNormalizerTrait::hasTrailingLimit` regex, ported verbatim
+   * so all four frameworks answer identically: it accepts a numeric value, `?`,
+   * `$1` and `:name` placeholders, MySQL's `LIMIT a, b`, and a trailing OFFSET.
+   *
+   * @param sql Raw SQL; literals and comments are scrubbed before matching.
+   */
+  static hasTrailingLimit(sql: string): boolean {
+    const val = String.raw`(?:\d+|\?|\$\d+|:\w+|%s)`;
+    const re = new RegExp(
+      String.raw`\bLIMIT\s+${val}(?:\s*,\s*${val})?(?:\s+OFFSET\s+${val})?\s*;?\s*$`,
+      "i",
+    );
+    return re.test(SQLTranslator.scrubSqlText(sql));
+  }
+
+  /**
+   * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
+   *
+   * The clause goes on a NEW LINE. Appending it inline is the second half of the
+   * same bug: `SELECT * FROM t -- note` + ` LIMIT 100` puts the clause INSIDE the
+   * trailing comment, where SQLite silently ignores it and the whole table comes
+   * back. A newline cannot be commented out by a `--` that started on the line
+   * above. Trailing semicolons are stripped first for the same reason
+   * (`SELECT * FROM t;` + `LIMIT 100` is a syntax error).
+   *
+   * @param sql    The caller's statement.
+   * @param limit  Row cap to apply; a non-positive value means "no cap".
+   * @param offset Rows to skip; omitted or 0 emits no OFFSET.
+   */
+  static appendLimit(sql: string, limit?: number, offset?: number): string {
+    if (limit === undefined || limit === null || limit <= 0) return sql;
+    if (SQLTranslator.hasTrailingLimit(sql)) return sql;
+
+    const trimmed = sql.replace(/[\s;]+$/, "");
+    const suffix = offset !== undefined && offset > 0
+      ? `LIMIT ${limit} OFFSET ${offset}`
+      : `LIMIT ${limit}`;
+    return `${trimmed}\n${suffix}`;
+  }
 }
 
 // ── Query Cache ──────────────────────────────────────────────
@@ -196,14 +462,54 @@ export class QueryCache {
   }
 
   /**
-   * Generate a cache key from a SQL query and params.
+   * Stable identity of the DATABASE a cache entry came from.
+   *
+   * `engine://host:port/database` - and deliberately NOTHING else.
+   *
+   * WHY IT EXISTS: the key used to be `query:${sql}:${params}` with nothing
+   * naming the connection, so on any SHARED backend two databases cross-served
+   * each other's rows. Two apps pointed at one Redis, or one app with a primary
+   * and an analytics connection, silently read each other's data. Identical SQL
+   * text across tenants is the COMMON case, not an edge case, so the collision
+   * was the normal outcome.
+   *
+   * WHY NO CREDENTIALS: a password in the key means every rotation silently
+   * cold-starts the cache, and a shared backend's key namespace is visible to
+   * every tenant of that backend - a secret must never be folded into it. The
+   * username is out for the same reason plus a second: two connections
+   * differing only by role read the SAME rows and should share the entry.
+   *
+   * WHY NOTHING PER-PROCESS: no pid, no object id, no salt. Those would isolate
+   * the databases by ACCIDENT and destroy the point of a shared cache, because
+   * no instance would ever hit another instance's entry.
    */
-  static queryKey(sql: string, params?: unknown[]): string {
+  static cacheIdentity(url: string): string {
+    try {
+      const parsed = new DatabaseUrl(url);
+      return `${parsed.engine}://${parsed.host ?? ""}:${parsed.port ?? ""}/${parsed.database}`;
+    } catch {
+      // An unparseable URL still needs a STABLE identity, and falling back to a
+      // constant would silently restore the cross-serving bug. The raw URL is
+      // stable and distinct; it is only reached for a URL the connection layer
+      // is about to reject anyway.
+      return url;
+    }
+  }
+
+  /**
+   * Generate a cache key from DATABASE IDENTITY + SQL + params.
+   *
+   * The NUL separators keep the three parts from running together, so a table
+   * named after the tail of a database name cannot forge another database's
+   * key. The key is not hashed here: the only backend with a key-length limit
+   * is memcached, and its backend already SHA-256-hashes whatever it is given.
+   */
+  static queryKey(sql: string, params?: unknown[], identity = ""): string {
     const paramStr = params ? JSON.stringify(params) : "";
-    // Simple hash via string combination
-    return `query:${sql}:${paramStr}`;
+    return `query:${identity}\u0000${sql}\u0000${paramStr}`;
   }
 
+
   /**
    * Get a cached value. Returns undefined if expired or missing.
    */