tina4-nodejs 3.13.94 → 3.13.96

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.94)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.95)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.94 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.95 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -34,7 +34,6 @@ tina4-nodejs/
         messenger.ts     # Messaging system
         queue.ts         # Queue system
         rateLimiter.ts   # Rate limiting middleware
-        scss.ts          # SCSS compilation
         service.ts       # Service layer helpers
         session.ts       # Session management
         testing.ts       # Inline testing framework (attach tests to functions)
@@ -55,9 +54,9 @@ tina4-nodejs/
     swagger/    # OpenAPI spec generator, Swagger UI
     frond/      # Zero-dependency Twig-compatible template engine
   test/
-    run-all.ts       # Test runner — executes all 43 test files
+    run-all.ts       # Test runner — executes every test file (262 in the last lab run)
     integration.ts   # Full integration test
-    *.test.ts        # 42 individual test files covering all subsystems
+    *.test.ts        # 267 individual test files covering all subsystems
   plan/
     FEATURES.md      # Feature tracking and roadmap
 ```
@@ -72,13 +71,13 @@ This is an **npm workspaces monorepo**. All packages are in `packages/*`.
 - **Database:** SQLite via `node:sqlite` (default), with adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird
 - **Templates:** Frond — built-in zero-dependency Twig-compatible engine (`@tina4/frond`)
 - **Dev tooling:** `tsx` for runtime TS execution, `esbuild` for builds
-- **Testing:** 43 test files via `tsx test/run-all.ts`
+- **Testing:** 267 `*.test.ts` files via `tsx test/run-all.ts`
 
 ## Key Commands
 
 ```bash
 npm install          # Install all workspace dependencies
-npm test             # Run all 43 test files via test/run-all.ts
+npm test             # Run every test file via test/run-all.ts
 npm run build        # Build all packages to dist/
 npm run clean        # Remove all dist/ directories
 ```
@@ -128,11 +127,11 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `queue.ts` — Queue system with pluggable backends
 - `graphql.ts` — GraphQL engine. **Hardening:** selection-set nesting is bounded by `TINA4_GRAPHQL_MAX_DEPTH` (default `50`; `<= 0` disables; exposed as the public `gql.maxDepth` field + `graphqlMaxDepth()` helper). Depth increments on every recursive entry — sub-selections, fragment spreads, AND inline fragments — so an over-deep query or a circular fragment fails with `Query exceeds maximum depth of N` instead of overflowing the stack (top-level starts at depth 1). A resolver exception is logged via `Log.error` and the detail is surfaced to the client **only** under `TINA4_DEBUG` (`isDebugMode()`); otherwise it returns a generic `Internal server error` (path preserved) so internal state never leaks.
 - `i18n.ts` — Internationalization / localization
-- `logger.ts` — Structured logging. Five first-class severity levels: `debug`(0) < `info`(1) < `warning`(2) < `error`(3) < `critical`(4). `critical` is the HIGHEST level, NOT a relabelled `error`, and renders magenta. `Log.critical()` ALWAYS emits like every other level — subject only to `TINA4_LOG_LEVEL` (which it always clears) and teed to the log file whenever a file is being written. There is NO enable toggle: the old `TINA4_LOG_CRITICAL` opt-in was retired in v3.13.39 (the env var is no longer read), so a critical log is never a silent no-op. `Log.isEnabled("critical")` is ordinary threshold logic (`4 >= configured min`). **Dev/prod-aware default file output (v3.13.39, Python master 4c6d881):** stdout is ALWAYS on. When `TINA4_LOG_OUTPUT` is unset (default), the log FILE (`logs/tina4.log`) is written ONLY in development (`TINA4_DEBUG` truthy); in production / containers (`TINA4_DEBUG` falsy) the logger is stdout-only — no file to bloat the writable layer / disk (12-factor: logs on stdout for the platform to capture). Explicit `TINA4_LOG_OUTPUT=file`/`both`, OR an explicit `TINA4_LOG_FILE` path, always forces a file (explicit wins). `readEnv()` resolves all of this into a single `fileEnabled` flag that gates the file writer. Full parity with Python master.
+- `logger.ts` — Structured logging. Five first-class severity levels: `debug`(0) < `info`(1) < `warning`(2) < `error`(3) < `critical`(4). `critical` is the HIGHEST level, NOT a relabelled `error`, and renders magenta. `Log.critical()` ALWAYS emits like every other level — subject only to `TINA4_LOG_LEVEL` (which it always clears) and teed to the log file whenever a file is being written. There is NO enable toggle: the old `TINA4_LOG_CRITICAL` opt-in was retired in v3.13.39 (the env var is no longer read), so a critical log is never a silent no-op. `Log.isEnabled("critical")` is ordinary threshold logic (`4 >= configured min`). **Dev/prod-aware default file output (v3.13.39, Python master 4c6d881):** stdout is ALWAYS on. When `TINA4_LOG_OUTPUT` is unset (default), the log FILE (`logs/tina4.log`) is written ONLY in development (`TINA4_DEBUG` truthy); in production / containers (`TINA4_DEBUG` falsy) the logger is stdout-only — no file to bloat the writable layer / disk (12-factor: logs on stdout for the platform to capture). Explicit `TINA4_LOG_OUTPUT=file`/`both`, OR an explicit `TINA4_LOG_FILE` path, always forces a file (explicit wins). `readEnv()` resolves all of this into a single `fileEnabled` flag that gates the file writer. Full parity with Python master. **Format is TEXT by default (settled logger contract, 2026-08-01):** `TINA4_LOG_FORMAT=json` is the ONLY thing that selects JSON, and it applies to BOTH sinks (stdout and file). The implicit "production means JSON" switch (an unset `TINA4_DEBUG`) is DELETED — it made the same `.env` produce four different formats across the four frameworks. `TINA4_DEBUG` now decides COLOUR only: ANSI on a dev terminal, clean bytes on a production pipe. An object/array passed as the MESSAGE is still JSON-encoded INLINE inside the text line (never `[object Object]`). **`TINA4_LOG_STRICT`:** truthy makes a log-write failure THROW instead of being swallowed (default off — logging must never crash an app that did not ask for it). **Every `TINA4_LOG_*` var is read LAZILY on each call**, so a script, worker, CLI tool or test that logs without booting a server still gets the operator's configuration; `Log.configure()` remains an explicit override.
 - `rateLimiter.ts` — Rate limiting middleware
 - `dotenv.ts` — `.env` file loading
 - `health.ts` — Health check endpoint
-- `scss.ts` — SCSS compilation
+- SCSS compilation is owned by the `tina4` Rust CLI (grass), not the framework
 - `messenger.ts` — Messaging system
 - `service.ts` — Service layer helpers
 - `wsdl.ts` — WSDL / SOAP support. **Hardening:** a SOAP message containing a `<!DOCTYPE>` is rejected with a `Client` fault ("DOCTYPE declarations are not allowed in SOAP messages") BEFORE the body is parsed and the operation never runs — SOAP 1.1 forbids DTDs and this closes the XML entity-expansion (billion-laughs) / external-entity (XXE) surface (defence in depth — the hand-rolled parser is already immune). `convertValue` for an `int`/`float`/`integer`/`double`/`number` param throws on a non-numeric value (matching Python's `int()`/`float()` raise) so it becomes a `Server` fault instead of a silent `NaN`. An operation that throws is logged via `Log.error`; the real cause reaches the client **only** under `TINA4_DEBUG` (`isDebugMode()`), else a generic `Internal server error`.
@@ -157,7 +156,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `seeder.ts` — Database seeding (`seedTable` raw SQL, `seedOrm` model-based, `seedModels` FK-ordered batch). All return a `SeedSummary { seeded, failed, errors }`; per-row failures are logged + counted + skipped (`strict` re-raises). Options: `{ overrides, clear, seed, strict }`.
 - `sqlTranslator.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
 - **Instance methods:** `save(): this|false` (fluent, false on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
-- **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(where?, params?, include?)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit?, offset?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit?, offset?)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
+- **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(limit=100, offset=0, include?, orderBy?)`, `select(sql, params?, limit=100, offset=0)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit=100, offset=0, include?, orderBy?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit=100, offset=0)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
 - **Foreign key auto-wire:** Declare a field with `type: "foreignKey"` and `references: "ModelName"` to auto-wire both `belongsTo` on the declaring model and `hasMany` on the referenced model. Optional `relatedName` overrides the has-many key. Models must be registered via `BaseModel.registerModel(name, class)` for name-based resolution. Example: `user_id: { type: "foreignKey", references: "User" }` → `post.belongsTo(User, "user_id")` and `user.hasMany(Post, "user_id")` both resolve without extra wiring.
 - QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 - `getNextId(table: string, pkColumn?: string, generatorName?: string): Promise<number>` — Race-safe ID generation using atomic sequence table (`tina4_sequences`). SQLite/MySQL/MSSQL use `tina4_sequences` with atomic UPDATE+SELECT. PostgreSQL auto-creates sequences if missing. Firebird uses existing generators (unchanged).
@@ -225,7 +224,27 @@ session.getSessionId(): string | null
 session.gc(): void
 ```
 
-Backends: file, redis, redis-npm, valkey, mongodb, database.
+Backends: file, redis, valkey, mongodb, database, memcached.
+
+**Breaking (3.13.95): the mongodb backend's default database is now `tina4`.** With
+`TINA4_SESSION_MONGO_DB` unset it was `tina4_sessions` in Node and `tina4` in
+tina4-python, tina4-php and tina4-ruby, so the same `.env` put Node's sessions in a
+different database from the other three — identical configuration, different
+observable outcome. What an operator sees on upgrade: current sessions are not
+found, so users log in once more. Set `TINA4_SESSION_MONGO_DB=tina4_sessions` to
+keep the old database. There is deliberately no fallback read: a session store is
+ephemeral (everything in it carries a TTL, default 3600s), so the impact self-heals
+within one session lifetime and a fallback would double a read path forever.
+
+**`redis-npm` was removed on 2026-07-31.** It was a Node-only backend name that drove
+Redis through the optional `redis` npm package. Python and Ruby also prefer that
+driver when installed, but they choose it inside their single `redis` handler; only
+Node exposed it as a selectable backend, and only Node's copy still ran
+`execFileSync` per command instead of the persistent worker connection every other
+handler moved to. Use `redis` — same backend, same `TINA4_SESSION_REDIS_*`
+settings, faster transport. Setting `TINA4_SESSION_BACKEND=redis-npm` now **throws**
+rather than falling through to the `file` default, because a silent demotion to disk
+would log every user out on deploy and look like an outage.
 
 **Backend-failure policy (all 4 frameworks): log-loud + degrade.** A backend (Redis/Valkey/Mongo/DB) that becomes unreachable mid-request is logged via `Log.error` and degraded rather than crashing the app or losing data silently. The external handlers now **throw** a transport error on an unreachable server (previously they swallowed it to an empty string — silent data loss); the `Session` boundary catches it: a read failure yields an empty session (the request still serves), and `save()` returns `false` (best-effort, dirty flag retained for a later retry). A genuine key/doc miss still returns empty **without** logging — empty is not a failure. Set `TINA4_SESSION_STRICT=true` to re-throw instead. Call `regenerate()` right after a successful login or privilege change to defeat session fixation.
 
@@ -240,20 +259,23 @@ db.cacheStats(): { enabled, size, ttl }   // synchronous
 
 ### DocStore — pymongo-style document store (zero-config SQLite fallback)
 
-`getCollection(name)` (from `@tina4/orm`) returns a Mongo-style collection. When a Mongo URI is configured it is a real Mongo collection (resolved lazily, returns a Promise); otherwise it is a `SqliteCollection` backed by a local SQLite file (`node:sqlite`, JSON1) and is synchronous. The call sites are identical either way — only the backend differs — so you develop against a zero-dependency local store and switch to MongoDB in production by setting one env var. Because `node:sqlite` is synchronous, `getCollection` is sync in the serverless path and returns a Promise only on the real-Mongo path.
+`getCollection(name)` (from `@tina4/orm`) returns a Mongo-style collection. When a Mongo URI is configured it is a real Mongo collection; otherwise it is a `SqliteCollection` backed by a local SQLite file (`node:sqlite`, JSON1). The call sites are identical either way — only the backend differs — so you develop against a zero-dependency local store and switch to MongoDB in production by setting one env var.
+
+**The API is ASYNC on both providers (ADR-0025).** `getCollection` and every collection method return a Promise; `find()` is sync and returns a cursor whose `toArray()` is async, exactly matching the MongoDB driver. `node:sqlite` is synchronous underneath, but the SHAPE never changes with the provider — before 3.13.95 the fallback was fully sync, so identical source changed TYPE when `TINA4_MONGO_URI` was set, and because a Promise is always truthy, `if (doc)` succeeded for a document that did not exist.
 
 ```typescript
 import { getCollection, isServerless, ObjectId } from "@tina4/orm";
 
-const orders = getCollection("orders") as any; // SqliteCollection in serverless mode
-const res = orders.insertOne({ customer_id: 1, total: 9.99, status: "new" });
-orders.findOne({ _id: res.insertedId });
-orders.updateOne({ _id: res.insertedId }, { $set: { status: "shipped" } });
-for (const doc of orders.find({ total: { $gt: 5 } }).sort("total", -1).limit(10)) {
+const orders = (await getCollection("orders")) as any;
+const res = await orders.insertOne({ customer_id: 1, total: 9.99, status: "new" });
+await orders.findOne({ _id: res.insertedId });
+await orders.updateOne({ _id: res.insertedId }, { $set: { status: "shipped" } });
+// for await — a real FindCursor has Symbol.asyncIterator only, never Symbol.iterator
+for await (const doc of orders.find({ total: { $gt: 5 } }).sort("total", -1).limit(10)) {
   // ...
 }
-orders.countDocuments({ status: "shipped" });
-isServerless();   // true when running on the SQLite fallback
+await orders.countDocuments({ status: "shipped" });
+isServerless();   // true when running on the SQLite fallback (sync — reads config only)
 ```
 
 Filter operators: equality, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$exists`, `$regex`, implicit AND, `$or`, `$and`, and dotted nested keys (`addr.city`). Updates: `$set`, `$unset`, `$inc`, replace, upsert. Cursors: `sort`, `limit`, `skip`, projection. Values round-trip (Date to/from ISO-8601, `ObjectId` to/from 24-hex) and stay queryable via `json_extract`. Non-goals: aggregation pipelines, `$elemMatch`, geo queries.
@@ -262,6 +284,8 @@ Selection and configuration:
 - `TINA4_MONGO_URI` — app-wide Mongo URI. Falls back to `TINA4_SESSION_MONGO_URI`, then the legacy `TINA4_SESSION_MONGO_URL`. When one is set, `getCollection` returns a real Mongo collection.
 - `TINA4_DOC_STORE_PATH` — SQLite file for the fallback store (default `data/tina4_docstore.db`).
 
+**One client per (uri, database), and a way to close it.** `getCollection` caches the connected Mongo client rather than building a new one per call — before 3.13.95 it constructed a `new MongoClient` on EVERY call and never closed it, so 20 calls left 40 server connections open and the count grew without bound (invisible locally, because the SQLite fallback opens no connections at all). `await closeDocStore()` closes every Mongo client and the SQLite store; a pooled client keeps the event loop alive, so a script or test that touched the real provider needs it to exit.
+
 ### Request extras
 
 ```typescript
@@ -627,6 +651,9 @@ import { initDatabase, bindDatabase, createAdapterFromUrl, Database, DatabaseRes
 const db = await initDatabase({ url: "sqlite:///app.db" });
 // Connection pooling: pass `pool: 4` for round-robin connections.
 
+// db.fetch() caps at 100 rows when no limit is passed (one number across all
+// four frameworks). db.fetchAll() deliberately does NOT inherit the cap -- its
+// name is the request for every row -- so it routes around fetch()'s default.
 // EVERY db method that touches the database is ASYNC on the Database wrapper --
 // it returns a Promise, so `await` it. (The node:sqlite ADAPTER underneath is
 // synchronous, but the wrapper is async so the query cache and the pg/mysql/
@@ -634,7 +661,7 @@ const db = await initDatabase({ url: "sqlite:///app.db" });
 // and close() are synchronous.
 
 // Reads — async, await them
-await db.fetch(sql, params?, limit?, offset?): Promise<DatabaseResult>   // .records, .count, .limit, .offset
+await db.fetch(sql, params?, limit?, offset?): Promise<DatabaseResult>   // limit defaults to DEFAULT_ROW_CAP (100)   // .records, .count, .limit, .offset
 await db.fetchOne<T>(sql, params?): Promise<T | null>
 
 // Writes — execute() RAISES on a SQL error (bad SQL, constraint violation,
@@ -773,8 +800,8 @@ User.find(id, include?);
 User.findById(id, include?);
 User.findOrFail(id);                       // throws if missing
 User.create(data);                         // construct + save
-User.all(where?, params?, include?);
-User.select(sql, params?);
+User.all(limit?, offset?, include?, orderBy?);   // limit defaults to 100; NO filter -- use where()
+User.select(sql, params?, limit?, offset?);       // limit defaults to 100
 User.selectOne(sql, params?, include?);
 User.where(conditions, params?, limit?, offset?, include?, orderBy?);
 User.count(conditions?, params?);
@@ -812,7 +839,7 @@ const orders = QueryBuilder.fromTable("orders o")
   .where("o.status = ?", ["pending"])
   .orderBy("o.created_at DESC")
   .limit(20)
-  .get();                       // → row[]
+  .get();                       // → DatabaseResult (.records, .count, .limit, .offset)
 
 // LEFT JOIN
 QueryBuilder.fromTable("products p")
@@ -965,6 +992,10 @@ queue.purge("completed");
 queue.retryFailed();
 queue.deadLetters();
 queue.produce("notifications", payload, 0, 0);
+// Release the backend connection. Idempotent; discard the queue afterwards.
+// Node caveat: neither reachable backend holds a connection between calls today
+// (ADR-0022 child-process design), so this releases nothing YET - it is the contract.
+queue.close();
 
 // Job methods
 job?.complete();
@@ -984,6 +1015,37 @@ for await (const job of queue.consume("emails")) {
 // pollInterval=0 for single-pass drain (tests).
 ```
 
+## Graceful shutdown (`packages/core/src/server.ts`)
+
+`startServer()` owns signal handling. It is the ONLY place that registers
+`process.on("SIGTERM"/"SIGINT")` — `background.ts` and the CLI's `serve.ts`
+deliberately register none.
+
+On SIGTERM or SIGINT it: stops background tasks, sends RFC 6455 close code
+**1001 ("going away")** to every live WebSocket, closes the listeners so new
+connections get a clean refusal, waits for in-flight requests to finish (up to
+`TINA4_SHUTDOWN_TIMEOUT`), closes the database, and exits **0**.
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `TINA4_SHUTDOWN_TIMEOUT` | `30` | Seconds to wait for in-flight requests before force-closing them. Matches Kubernetes' default `terminationGracePeriodSeconds` and Gunicorn's `graceful_timeout`, and is the same env var and default as tina4-python / tina4-php / tina4-ruby. A non-numeric or negative value warns and falls back to 30. |
+| `TINA4_DEFAULT_WEBSERVER` | unset | **Accepted and ignored in Node.** `TRUE` pins the built-in server. Node has only one server (`node:http`), so there is nothing to switch and this is a genuine no-op. It exists here so the env surface is identical across all four frameworks: in tina4-python it forces the built-in asyncio server instead of uvicorn/hypercorn/granian, and in tina4-ruby it forces WEBrick instead of Puma. Setting it must never be an error. |
+
+**SIGHUP is deliberately NOT trapped** — the default disposition terminates the
+process. The Rust CLI owns file watching and production logs go to stdout, so
+neither Puma's log-reopen nor gunicorn's config-reload use for SIGHUP applies.
+`test/gracefulShutdown.test.ts` pins this so it is not restored by accident.
+
+**Never register a signal handler that does not exit.** Adding any listener for
+SIGTERM REPLACES Node's default disposition, so a handler that only cleans up
+does not "add" to the default, it CANCELS it — the process then ignores SIGTERM
+and runs until SIGKILL. `background.ts` shipped exactly that bug: a server with
+one registered `background()` task hung forever on SIGTERM, burning the whole
+Kubernetes grace period on every rolling deploy.
+
+Set `terminationGracePeriodSeconds` ABOVE `TINA4_SHUTDOWN_TIMEOUT` in your pod
+spec so the drain finishes before SIGKILL.
+
 ## Module: Background Tasks (`packages/core/src/background.ts`)
 
 Periodic callbacks that run alongside the HTTP server. Use this instead of bare `setInterval` so timers integrate with the server lifecycle and clear on graceful shutdown.
@@ -1001,11 +1063,11 @@ background(async () => {
 }, 30);
 
 task.stop();              // stop just this one
-stopAllBackgroundTasks(); // stop everything (also runs on SIGTERM/SIGINT)
+stopAllBackgroundTasks(); // stop everything (the server's shutdown calls this on SIGTERM/SIGINT)
 backgroundTaskCount();    // test helper
 ```
 
-**Never use bare `setInterval` for periodic work in a Tina4 app.** `background()` catches errors, integrates with shutdown signals, calls `timer.unref()` so it doesn't block process exit, and matches Python's `background()` API exactly.
+**Never use bare `setInterval` for periodic work in a Tina4 app.** `background()` catches errors, is cleared by the server's graceful shutdown (which owns the signal handlers), calls `timer.unref()` so it doesn't block process exit, and matches Python's `background()` API exactly.
 
 ## Module: DI Container (`packages/core/src/container.ts`)
 
@@ -1161,8 +1223,15 @@ Set `TINA4_DATABASE_URL` in your `.env` file using `driver://host:port/database`
 
 ```bash
 # SQLite (default if nothing configured)
-TINA4_DATABASE_URL=sqlite:///path/to/db.sqlite
+# Slash count decides relative vs absolute (the SQLAlchemy convention,
+# identical in all four frameworks). THREE slashes is RELATIVE to the working
+# directory; an absolute path needs FOUR.
+TINA4_DATABASE_URL=sqlite:///app.db                 # relative: ./app.db
+TINA4_DATABASE_URL=sqlite:////var/data/app.db       # absolute: /var/data/app.db
+TINA4_DATABASE_URL=sqlite:/var/data/app.db          # absolute (one slash) too
 TINA4_DATABASE_URL=sqlite://./data/tina4.db
+# FOOTGUN: "sqlite://" + an absolute path yields THREE slashes, so the file is
+# created UNDER the working directory and a stray ./var/data/ tree appears.
 
 # PostgreSQL
 TINA4_DATABASE_URL=postgres://localhost:5432/mydb
@@ -1194,6 +1263,64 @@ TINA4_DATABASE_PASSWORD=mypass
 
 Credential priority: `config.user` > `config.username` > `TINA4_DATABASE_USERNAME` env var.
 
+### Connect timeout
+
+`TINA4_DATABASE_CONNECT_TIMEOUT` bounds every database connect attempt. Same name,
+unit, default and semantics in all four frameworks.
+
+| | |
+|---|---|
+| unit | **seconds** |
+| default | `10` |
+| `<= 0` | disables the bound (unbounded — each driver keeps exactly its old behaviour) |
+| garbage | warns and uses `10` |
+| on expiry | throws, naming the host, the port, the elapsed seconds, and this variable |
+
+Without it a driver that never calls back hangs the app on connect with no log, no
+error and no signal — measured on the Firebird adapter at 16 minutes, 0.0% CPU. It
+is applied in two layers: the driver's own knob where it has one (so one variable
+really governs, rather than tedious's 15s or Mongo's 30s quietly winning), and an
+outer bound around the whole attempt (so it exists at all for `node-firebird`,
+which has no knob, and so a knob that covers only part of the handshake cannot
+leave a gap).
+
+**The driver's timer is meant to WIN, and Tina4 translates what it raises.** The
+knob is set to the bound EXACTLY (rounded up to whole milliseconds, floored at 1 —
+three of the four knobs read `0` as *wait forever*), Tina4's own clock starts
+before the driver arms its timer, and a driver failure that took at least that long
+is re-thrown in the framework's words with the driver's error preserved as `cause`:
+
+```
+Database connect to 127.0.0.1:34467 timed out after 2.0s
+(TINA4_DATABASE_CONNECT_TIMEOUT=2 seconds; set it to 0 to wait indefinitely).
+Driver reported: timeout expired
+```
+
+That is real output, captured against a server that accepts and never replies.
+Each driver contributes its own words — pg `timeout expired`, mysql2 `connect
+ETIMEDOUT`, tedious `Failed to connect to 127.0.0.1:34467 in 2000ms`, Mongo
+`Server selection timed out after 2000 ms` — and the last two quote the budget
+they were GIVEN, which is how you can see that `2` means 2000ms and not 3000ms.
+Firebird and ODBC have no knob, so the outer bound fires instead and there is no
+`Driver reported:` clause to add.
+
+`N` means `N`. Whether a failure was the bound expiring is decided by **elapsed
+time**, never by matching the driver's error text — the four clients word it four
+different ways and a marker table would drift and miss. A 50ms tolerance absorbs
+libuv's timer granularity without inflating `N`. The outer bound remains as the
+backstop for the phases a knob does not cover and the adapters that have none;
+being armed after the driver's, it only fires when the driver's did not.
+
+| Adapter | Can connect block? | Bounded now | How |
+|---------|--------------------|-------------|-----|
+| Firebird | yes — **the measured 16-minute hang** | ✅ | outer bound only (`node-firebird` has no timeout option) |
+| PostgreSQL | yes — pg's `connectionTimeoutMillis` defaults to `0`, no timeout | ✅ | `connectionTimeoutMillis` + outer bound |
+| MySQL | bounded at mysql2's own 10s default | ✅ | `connectTimeout` + outer bound |
+| MSSQL | bounded at tedious's own 15s default | ✅ | `connectTimeout` + outer bound |
+| MongoDB | bounded at the driver's own 30s default | ✅ | `serverSelectionTimeoutMS` + `connectTimeoutMS` + outer bound |
+| ODBC | yes — a raw driver string carries no timeout | ⚠️ caller only | outer bound; the blocked native thread cannot be cancelled from JS |
+| SQLite | no network; opens in a **synchronous** constructor | ❌ N/A | a sync call cannot be interrupted by a timer on the same thread, and there is no host/port to name |
+
 ### Programmatic configuration
 ```typescript
 import { initDatabase } from "@tina4/orm";
@@ -1219,9 +1346,10 @@ Run tests with:
 npm test
 ```
 
-This executes `test/run-all.ts` which runs all 43 test files:
+This executes `test/run-all.ts`, which ran **262 files** in the last lab verification:
 - `test/integration.ts` — Full integration test (creates a temp project, starts a real server, runs assertions)
-- `test/*.test.ts` — 42 individual test files covering all subsystems (ORM, routing, middleware, database drivers, sessions, queues, WebSocket, GraphQL, i18n, etc.)
+- `test/*.test.ts` — 267 files on disk covering all subsystems (ORM, routing, middleware, database drivers, sessions, queues, WebSocket, GraphQL, i18n, etc.). 259 are spawned by the runner under `tsx`, plus `integration.ts`; the 2 i18n suites are vitest and the runner drives them itself (so no invoker can miss them); the 6 `metrics*` files need the Rust CLI's native engine and are opted in with `TINA4_SKIP_METRICS=0`.
+- `test/_*.ts` are helpers, not suites, so the runner never collects them: `_serviceGate.ts` (the require-services gate), `_testSummary.ts`, and `_driverlessTree.ts` (builds a tree where a bare specifier genuinely cannot resolve).
 
 **Always run tests after making changes.** All tests must pass.
 
@@ -1257,7 +1385,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **98 built-in features**, zero third-party dependencies
-- **6,230 tests** passing, 0 failed, across 198 files (build + typecheck green) - measured 2026-07-29 on Ubuntu 24.04.4 LTS x86_64, Node 24.18.0, live services, TINA4_REQUIRE_SERVICES=1; Firebird excluded by design
+- **7,537 tests** passing, 0 failed, **0 skipped** across 262 files (typecheck exit 0) - measured 2026-08-06 on the lab host (Ubuntu 24.04.4 LTS x86_64, Node v24.18.0) against live services with TINA4_REQUIRE_SERVICES=1. **Firebird is NOT excluded** - `test/firebird*.test.ts` runs against a REAL Firebird 5. The last six skips are closed, each by giving it the environment its condition needs rather than by relaxing what it asserts: the four missing-driver cases run in a child process that genuinely cannot resolve the driver (the source is copied out of the repo to a tree with no `node_modules` above it and run with plain `node` - `test/_driverlessTree.ts`, no resolver shim); the strict-mode write failure drops the effective uid so a 0400 file really denies root; and the RabbitMQ default-config round-trip clears the per-framework isolation overrides for that one case so "default" means the default. Every one was proven able to FAIL by mutating the code it guards.
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode
@@ -1267,7 +1395,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars. **Reservation/visibility timeout** (file + MongoDB): a popped job is reserved for `TINA4_QUEUE_VISIBILITY_TIMEOUT` seconds (default 300; `visibilityTimeout` Queue option; `<= 0` disables) — if the consumer dies before `complete()`/`fail()`, the next `pop()` reclaims it (incrementing `attempts`, dead-lettering past `maxRetries`), so a crashed/evicted consumer never strands a job. RabbitMQ/Kafka delegate redelivery to the broker.
 - **Cache**: memory/Redis/file backends
-- **Messenger**: .env driven SMTP/IMAP
+- **Messenger**: .env driven SMTP/IMAP. **Cross-framework contract:** `inbox(folder = "INBOX", limit = 20, offset = 0)` takes the folder FIRST (same order in all four frameworks — Node was the outlier at `(limit, offset, folder)` before 3.13.95); `uid` is a **string** everywhere; `read(uid, folder?)` returns `ImapFullMessage | null` and a non-existent UID reads as **`null`** — falsy, so `if (!message)` is the portable missing-message check, matching Python's `{}`, PHP's `null` and Ruby's `nil`. A missing UID is NOT an error and never throws. IMAP reads DO fail loud on a connection/auth/protocol failure: `inbox`/`read`/`unread`/`search`/`folders` all raise `MessengerConnectionError` rather than swallowing it into an empty result. Real SMTP + IMAP round-trips are covered against a live GreenMail in `test/messengerGreenMail.test.ts` (ports 3025/3143; `TINA4_TEST_SMTP_*` / `TINA4_TEST_IMAP_*` to relocate)
 - **ORM relationships**: `hasMany`, `hasOne`, `belongsTo` with eager loading (`include`)
 - **Frond pre-compilation**: 2.8x template render improvement
 - **QueryBuilder** with NoSQL/MongoDB support (`toMongo()`)

package/README.md

@@ -59,7 +59,7 @@ export default class User {
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
 | **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
-| **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
+| **Auth & Security** (5) | JWT (HS256/HS384/HS512 standard, RS256 opt-in, all from builtin `node:crypto`), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
 | **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.94",
+  "version": "3.13.96",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [
@@ -94,10 +94,12 @@
     "redis": "^4.7.0"
   },
   "devDependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
     "@types/node": "^22.10.0",
     "@types/pg": "^8.20.0",
     "esbuild": "^0.24.0",
     "mongodb": "^6.0.0",
+    "node-firebird": "^2.14.3",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.9"