tina4-nodejs 3.13.94 → 3.13.95

package/packages/orm/src/index.ts

@@ -21,7 +21,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 +56,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 +72,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),

package/packages/orm/src/queryBuilder.ts

@@ -19,6 +19,7 @@
 
 import type { DatabaseAdapter } from "./types.js";
 import { getAdapter, adapterFetch, adapterFetchOne } from "./database.js";
+import { DatabaseResult } from "./databaseResult.js";
 
 export class QueryBuilder {
   private table: string;
@@ -198,22 +199,55 @@ 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 rows = await adapterFetch(
       this.db!,
       sql,
       allParams.length > 0 ? allParams : undefined,
       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 leaving `count` to default to the row count and handing the
+    // adapter + sql through.
+    return new DatabaseResult(
+      rows as Record<string, unknown>[],
+      undefined,
+      undefined,
+      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.
    */

package/packages/orm/src/types.ts

@@ -77,8 +77,8 @@ export interface DatabaseAdapter {
   /** Insert one or more rows into a table, returns result with lastId. */
   insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
 
-  /** Update rows in a table matching filter, returns affected row count. */
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+  /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
 
   /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
   delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
@@ -93,10 +93,10 @@ export interface DatabaseAdapter {
   rollback(): void;
 
   /** List all tables in the database. */
-  tables(): string[];
+  getTables(): string[];
 
   /** List columns with types for a table. */
-  columns(table: string): ColumnInfo[];
+  getColumns(table: string): ColumnInfo[];
 
   /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
   lastInsertId(): number | bigint | string | null;
@@ -115,6 +115,17 @@ export interface DatabaseAdapter {
 
   /** Add a column to an existing table (legacy, used by migration). */
   addColumn?(table: string, colName: string, def: FieldDefinition): void;
+
+  /**
+   * Stable identity of the DATABASE this adapter is connected to, as
+   * `engine://host:port/database` with NO credentials - set by whoever built
+   * the adapter from a URL or config.
+   *
+   * The query cache folds this into every key. Without it two databases sharing
+   * one cache backend cross-serve each other's rows, because identical SQL text
+   * across tenants is the common case.
+   */
+  cacheIdentity?: string;
 }
 
 export interface PaginatedResult<T = Record<string, unknown>> {

package/types/core/src/ai.d.ts

@@ -61,4 +61,4 @@ export declare function writeOrMerge(contextPath: string, contextFile: string, f
  * Generate the Tina4 context document for a specific AI tool.
  */
 export declare function generateContext(toolName?: string): string;
-export { AiTool as AiToolType };
+export type { AiTool as AiToolType };

package/types/core/src/auth.d.ts

@@ -16,6 +16,18 @@ import type { Middleware } from "./types.js";
  * @returns The newly-generated secret, or null when nothing was generated.
  */
 export declare function ensureDevSecret(cwd?: string): string | null;
+/**
+ * Can this runtime actually sign and verify `algorithm` right now?
+ *
+ * The cross-framework capability check — same question, same answer shape, in
+ * all four frameworks. HMAC answers `true` everywhere. RS256 answers `true`
+ * only where the runtime ships asymmetric crypto natively (node:crypto here,
+ * core ext-openssl in PHP, the stdlib openssl gem in Ruby) and `false` in
+ * tina4-python. An algorithm Tina4 does not know at all answers `false`.
+ */
+export declare function algorithmAvailable(algorithm: string): boolean;
+/** Every algorithm this runtime can sign and verify right now, in advertised order. */
+export declare function availableAlgorithms(): string[];
 /**
  * Seconds of clock skew tolerated on the "nbf" (not-before) claim.
  *
@@ -27,8 +39,12 @@ export declare const JWT_LEEWAY_SECONDS = 60;
 /**
  * Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else HS256.
  *
- * Throws (naming the supported set and the env var) when asked for an algorithm
- * we cannot sign — a silent downgrade to HS256 is the whole bug in python#106.
+ * Throws when asked for an algorithm Tina4 does not know (naming the known set,
+ * what is available here, and the env var), and throws again — with the runtime's
+ * own reason and a remedy — when it knows the algorithm but this build cannot
+ * provide it. A silent downgrade to HS256 is the whole bug in python#106, and a
+ * silent downgrade from RS256 would be worse: it would quietly turn asymmetric
+ * verification into a shared secret.
  *
  * @param algorithm - Explicit algorithm; wins over the environment when given.
  */
@@ -37,8 +53,11 @@ export declare function resolveAlgorithm(algorithm?: string): string;
  * Create a signed JWT token.
  *
  * Secret is always read from `process.env.TINA4_SECRET`.
- * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256");
- * HS256 / HS384 / HS512 / RS256 are supported and anything else throws.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ * HS256 / HS384 / HS512 is the cross-framework standard; RS256 is an opt-in
+ * extra that Node provides from builtin node:crypto (pass the PEM private key
+ * as the secret). An unknown algorithm, or one this runtime cannot provide,
+ * throws — see `resolveAlgorithm`.
  *
  * The header's `alg` is always the algorithm that actually signed the token.
  *
@@ -117,7 +136,8 @@ export declare function refreshToken(token: string, expiresIn?: number): string
  *
  * @param headers   - Object with header keys (e.g. `{ authorization: "Bearer ..." }`)
  * @param secret    - HMAC secret or PEM public key
- * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @param algorithm - Omit it to honour TINA4_JWT_ALGORITHM (then HS256). HS256 /
+ *   HS384 / HS512 everywhere; RS256 where the runtime provides it (it does here).
  * @returns Decoded payload, or null if missing/invalid
  */
 export declare function authenticateRequest(headers: Record<string, string | string[] | undefined>, secret?: string, algorithm?: string): Record<string, unknown> | null;
@@ -144,6 +164,9 @@ export declare function validateApiKey(provided: string, expected?: string): boo
 export declare class Auth {
     static getToken: typeof getToken;
     static validToken: typeof validToken;
+    static resolveAlgorithm: typeof resolveAlgorithm;
+    static algorithmAvailable: typeof algorithmAvailable;
+    static availableAlgorithms: typeof availableAlgorithms;
     static getPayload: typeof getPayload;
     static hashPassword: typeof hashPassword;
     static checkPassword: typeof checkPassword;

package/types/core/src/background.d.ts

@@ -25,9 +25,9 @@ export declare function background(callback: () => unknown | Promise<unknown>, i
     stop: () => void;
 };
 /**
- * Clear every registered background task. Called automatically on SIGTERM/SIGINT;
- * also called from the server's `close()` so a manual server shutdown stops
- * the timer wheel along with HTTP listeners.
+ * Clear every registered background task. Called by the server's graceful
+ * shutdown (its first step on SIGTERM/SIGINT) and by its `close()`, so both a
+ * signal and a manual shutdown stop the timer wheel along with the listeners.
  */
 export declare function stopAllBackgroundTasks(): void;
 /** Number of currently-registered background tasks (test helper). */

package/types/core/src/cache.d.ts

@@ -70,6 +70,20 @@ interface CacheBackend {
     set(key: string, value: unknown, ttl: number): Promise<void>;
     delete(key: string): Promise<boolean>;
     clear(): Promise<void>;
+    /**
+     * Evict expired entries and return HOW MANY were actually evicted.
+     *
+     * REQUIRED, not optional. It used to be neither declared nor implemented, so
+     * the module-level sweep() found no backend method and returned a permanent
+     * 0: the one API whose job is reclaiming expired space did nothing and
+     * reported success. Declaring it here makes "every provider can sweep" a
+     * compile-time fact instead of a runtime hope.
+     *
+     * 0 is the HONEST answer on redis/valkey/memcached/mongodb - they expire
+     * entries server-side, so there is nothing left for us to evict. It is the
+     * WRONG answer for memory, file and database, which own their own expiry.
+     */
+    sweep(): Promise<number>;
     stats(): Promise<{
         hits: number;
         misses: number;
@@ -107,18 +121,7 @@ export declare function createBackend(config?: {
     cacheDir?: string;
     maxEntries?: number;
 }): Promise<CacheBackend>;
-/**
- * Response cache middleware for GET requests.
- * Caches the full response body, content-type, and status code through the
- * unified async backend. Cache key is method + url (including query string).
- *
- * The middleware is ASYNC: the before-path awaits `backend.get` (serve hit) and
- * the after-path awaits `backend.set` (store on the captured `res.raw.end`).
- * The framework's middleware chain (`runRouteMiddlewares` / `MiddlewareChain`)
- * already awaits middleware, so async is transparent. Honors ttl/statusCodes/
- * maxEntries. With the default `memory` backend behaviour is unchanged; a
- * redis/etc. backend distributes cross-instance.
- */
+export declare function _getResponseBackend(config?: ResponseCacheConfig): Promise<CacheBackend>;
 export declare function responseCache(config?: ResponseCacheConfig): Middleware;
 /**
  * Clear all cached responses (the responseCache middleware backend).