tina4-nodejs 3.13.24 → 3.13.26

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.24)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.26)
 
 > 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.24 — 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.26 — 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.
 
@@ -575,7 +575,10 @@ db.delete(table, filter?, params?): DatabaseWriteResult
 db.getLastId(): string | number | null
 db.getError(): string | null
 
-// Transactions — autoCommit defaults to OFF; set TINA4_AUTOCOMMIT=true to enable
+// Transactions — autoCommit defaults to ON: a standalone write commits on its
+// own connection (durable + visible across the pool); inside startTransaction()
+// the per-statement commit is suppressed so the transaction stays atomic. Set
+// TINA4_AUTOCOMMIT=false for strict manual-commit mode.
 db.startTransaction(): void
 db.commit(): void
 db.rollback(): void
@@ -591,13 +594,15 @@ db.getNextId(table, pkColumn?, generatorName?): number
 
 // DB query cache — request-scoped auto cache is ON by default (TINA4_AUTO_CACHING=true,
 // TTL TINA4_AUTO_CACHING_TTL=5s): dedupes identical db.fetch()/ORM reads within a request,
-// flushed on any write. Persistent cross-request cache opt-in via TINA4_DB_CACHE=true
-// (TTL TINA4_DB_CACHE_TTL=30s), configured via TINA4_DB_CACHE_BACKEND + TINA4_DB_CACHE_URL.
-// NODE CHARACTERISTIC: because db.fetch() is synchronous, Node's persistent DB query cache
-// runs IN-PROCESS (per-instance), not distributed. For cross-instance caching in Node, use
-// the async KV API (await cacheGet/cacheSet). The other three frameworks route this through
-// the backend (distributed). cacheStats()/cacheClear() are real (the DB query cache is wired).
-db.cacheStats(): { enabled, size, ttl, mode }   // mode: "request" | "persistent" | "off"
+// flushed on any write (always in-process, fastest). Persistent cross-request cache opt-in
+// via TINA4_DB_CACHE=true (TTL TINA4_DB_CACHE_TTL=30s), configured via TINA4_DB_CACHE_BACKEND
+// + TINA4_DB_CACHE_URL. The persistent layer routes through the SAME unified async backend
+// set (memory default = in-process; redis/valkey/memcached/mongodb/database distribute), so
+// multiple instances share one cache with global write-invalidation — full parity with
+// Python/PHP/Ruby. (Node's read path — db.fetch → fetchAsync — is async, so the backend's
+// async get/set work directly; the KV/middleware API is async, await it.) cacheStats() reports
+// mode + backend; cacheClear() is real.
+db.cacheStats(): { enabled, size, ttl, mode, backend }   // mode: "request" | "persistent" | "off"
 db.cacheClear(): void
 
 // Connection pool access (null when pooling disabled)
@@ -906,7 +911,7 @@ await cacheClear();
 await cacheStats();   // { hits, misses, size, backend } — reflects the real KV backend
 ```
 
-**Node characteristic (by design, not a bug):** the async KV API supports all 7 backends with native async clients. Because Node's middleware runner and `db.fetch()` are synchronous, the **`responseCache` middleware and the persistent DB query cache run in-process (per-instance) in Node** — distributed/cross-instance caching in Node is done via the async KV API (`await cacheGet`/`await cacheSet`). The other three frameworks route those auto-paths through the configured backend (distributed). A full async middleware/DB pipeline is a future-major item.
+**Async everywhere (full parity):** the KV API, the `responseCache` middleware, and the persistent DB query cache all route through the same unified async backend set with native async clients (no child processes). The `responseCache` middleware and persistent DB cache distribute cross-instance when a network backend (redis/valkey/memcached/mongodb/database) is selected — exactly like Python/PHP/Ruby. The default `memory` backend keeps both in-process (fastest), so default behaviour is unchanged. Because the KV/middleware API is async, **`await` it** (`await cacheGet`/`await cacheSet`/`await clearCache`; the middleware runner and `db.fetch` are async). Request-scoped DB caching (`TINA4_AUTO_CACHING`) always stays in-process.
 
 **Graceful fallback**: if a configured backend's driver is missing or the service/credentials are unreachable or wrong, the cache logs a warning and falls back to the **file** backend — a real persistent cache, never a silent no-op.
 
@@ -1112,13 +1117,13 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **45 built-in features**, zero third-party dependencies
-- **3,787 tests** passing across all modules
+- **3,748 tests** passing across all modules
 - **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
 - **`npx tina4nodejs generate`**: model, route, migration, middleware scaffolding
-- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes; persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) configured via `TINA4_DB_CACHE_BACKEND` + `TINA4_DB_CACHE_URL`. `db.cacheStats()` reports `mode` (request/persistent/off). **Node characteristic**: `db.fetch()` is synchronous, so the persistent DB query cache runs in-process (per-instance) in Node — cross-instance caching uses the async KV API (`await cacheGet`/`cacheSet`)
-- **Cache**: unified backend set — `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database` — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable. KV API is async (`await cacheGet`/`cacheSet`) with native async clients; the `responseCache` middleware runs in-process (per-instance) since Node's middleware runner is synchronous
+- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes (always in-process); persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified async backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL`, so instances share one cache with global write-invalidation (full parity with Python/PHP/Ruby). `db.cacheStats()` reports `mode` (request/persistent/off) + `backend`
+- **Cache**: unified backend set — `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database` — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable. The KV API, the `responseCache` middleware, and the persistent DB query cache all route through this async backend set (native async clients, no child processes) — a network backend distributes them cross-instance, full parity with Python/PHP/Ruby; `memory` (default) keeps them in-process. `await` the async API (`cacheGet`/`cacheSet`/`clearCache`)
 - **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: memory/Redis/file backends

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.24",
+  "version": "3.13.26",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/cache.ts

@@ -1199,17 +1199,55 @@ export async function createBackend(config?: {
 
 // ── Response cache store (for middleware) ──────────────────────────
 
-const store = new Map<string, CacheEntry>();
+/**
+ * The responseCache middleware's backend. Built lazily (and memoised) from the
+ * SAME unified `createBackend()` factory as the KV API, so cached GET responses
+ * distribute across instances via redis/valkey/memcached/mongodb/database
+ * (parity with Python's ResponseCache, which routes through `_create_backend`).
+ *
+ * The default backend is `memory` (in-process), so the DEFAULT behaviour is
+ * unchanged — only an explicit redis/etc. backend distributes. Each middleware
+ * instance resolves the shared module-level backend; a fresh middleware
+ * instance therefore serves hits stored by an earlier one (cross-instance via a
+ * network backend, same-process via memory).
+ *
+ * Response entries are stored as a plain JSON-serialisable object so every
+ * backend (redis SETEX, mongo doc, etc.) can round-trip them.
+ */
+let _responseBackend: CacheBackend | null = null;
+let _responseBackendPromise: Promise<CacheBackend> | null = null;
+
+function _getResponseBackend(config?: ResponseCacheConfig): Promise<CacheBackend> {
+  if (_responseBackend) return Promise.resolve(_responseBackend);
+  if (!_responseBackendPromise) {
+    _responseBackendPromise = createBackend({
+      backend: config?.backend,
+      cacheUrl: config?.cacheUrl,
+      cacheDir: config?.cacheDir,
+      maxEntries: config?.maxEntries,
+    }).then((b) => {
+      _responseBackend = b;
+      return b;
+    });
+  }
+  return _responseBackendPromise;
+}
 
 /**
  * Response cache middleware for GET requests.
- * Caches the full response body, content-type, and status code.
- * Cache key is method + url (including query string).
+ * 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 function responseCache(config?: ResponseCacheConfig): Middleware {
   const ttl = config?.ttl
     ?? (process.env.TINA4_CACHE_TTL ? parseInt(process.env.TINA4_CACHE_TTL, 10) : 60);
-  const maxEntries = config?.maxEntries ?? 1000;
   const allowedCodes = new Set(config?.statusCodes ?? [200]);
 
   if (ttl <= 0) {
@@ -1217,34 +1255,26 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
     return (_req, _res, next) => next();
   }
 
-  // Periodic cleanup
-  const cleanupTimer = setInterval(() => {
-    const now = Date.now();
-    for (const [key, entry] of store) {
-      if (now > entry.expiresAt) store.delete(key);
-    }
-  }, 30_000);
-  if (cleanupTimer.unref) cleanupTimer.unref();
-
-  return (req, res, next) => {
+  return async (req, res, next) => {
     // Only cache GET requests
     if (req.method !== "GET") {
       next();
       return;
     }
 
-    const cacheKey = `GET:${req.url}`;
-    const cached = store.get(cacheKey);
+    const backend = await _getResponseBackend(config);
+    const cacheKey = `response:GET:${req.url}`;
+    const cached = (await backend.get(cacheKey)) as CacheEntry | undefined;
 
-    if (cached && Date.now() < cached.expiresAt) {
-      // Cache HIT
+    if (cached && typeof cached === "object" && typeof cached.body === "string") {
+      // Cache HIT — serve from the (possibly distributed) backend.
       res.header("X-Cache", "HIT");
       res.header("Content-Type", cached.contentType);
       res(cached.body, cached.statusCode, cached.contentType);
       return;
     }
 
-    // Cache MISS — intercept the response to capture it
+    // Cache MISS — intercept the response to capture and store it.
     const originalEnd = res.raw.end.bind(res.raw);
     let captured = false;
 
@@ -1254,18 +1284,16 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
         const body = typeof chunk === "string" ? chunk : chunk?.toString() ?? "";
         const contentType = String(res.raw.getHeader("Content-Type") ?? "application/octet-stream");
 
-        // Evict oldest if at capacity
-        if (store.size >= maxEntries) {
-          const firstKey = store.keys().next().value;
-          if (firstKey) store.delete(firstKey);
-        }
-
-        store.set(cacheKey, {
+        // backend.set is async; the captured end() must stay synchronous (Node
+        // flushes the body here), so fire-and-forget the store. The backend's
+        // TTL + maxEntries handle expiry/eviction. Errors are swallowed so a
+        // cache write can never break the response.
+        void backend.set(cacheKey, {
           body,
           contentType,
           statusCode: res.raw.statusCode,
           expiresAt: Date.now() + ttl * 1000,
-        });
+        } as CacheEntry, ttl).catch(() => { /* best effort */ });
       }
 
       res.header("X-Cache", "MISS");
@@ -1276,9 +1304,20 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
   };
 }
 
-/** Clear all cached responses (middleware store) */
-export function clearCache(): void {
-  store.clear();
+/**
+ * Clear all cached responses (the responseCache middleware backend).
+ * ASYNC on Node — callers `await clearCache()` — because the backend may be a
+ * network backend (redis/etc.). Resets the backend's namespace; mirrors the
+ * Python ResponseCache.clear_cache() which clears its backend.
+ */
+export async function clearCache(): Promise<void> {
+  if (!_responseBackend && !_responseBackendPromise) {
+    // Nothing built yet — build the default so a clear before first use still
+    // resolves to a real (empty) backend rather than silently no-op'ing.
+    await _getResponseBackend();
+  }
+  const backend = await _getResponseBackend();
+  await backend.clear();
 }
 
 /**
@@ -1358,10 +1397,13 @@ export async function cacheBackendStats(): Promise<{ hits: number; misses: numbe
 
 /** Reset the default backend (for testing). Closes any pooled connection. */
 export function _resetBackend(): void {
-  const b = _defaultBackend as any;
-  if (b && typeof b.client?.close === "function") { try { b.client.close(); } catch { /* noop */ } }
-  if (b && typeof b.client?.close !== "function" && typeof b.db?.close === "function") { /* leave shared ORM db */ }
+  for (const b of [_defaultBackend, _responseBackend] as any[]) {
+    if (b && typeof b.client?.close === "function") { try { b.client.close(); } catch { /* noop */ } }
+    if (b && typeof b.client?.close !== "function" && typeof b.db?.close === "function") { /* leave shared ORM db */ }
+  }
   _defaultBackend = null;
   _defaultBackendPromise = null;
+  _responseBackend = null;
+  _responseBackendPromise = null;
   _defaultTtl = null;
 }

package/packages/core/src/middleware.ts

@@ -95,18 +95,23 @@ export class MiddlewareRunner {
    * boolean indicating whether the route handler should still run.
    *
    * Short-circuits when a before method sets a status >= 400.
+   *
+   * ASYNC — each hook is awaited so middleware can perform async work (e.g.
+   * the distributed responseCache before-hook awaiting `backend.get`). Awaiting
+   * a synchronous hook that returns an array is harmless (the array resolves
+   * immediately), so existing sync hooks keep working unchanged.
    */
-  static runBefore(
+  static async runBefore(
     classes: any[],
     req: Tina4Request,
     res: Tina4Response,
-  ): [Tina4Request, Tina4Response, boolean] {
+  ): Promise<[Tina4Request, Tina4Response, boolean]> {
     for (const cls of classes) {
       const methods = Object.getOwnPropertyNames(cls).filter(
         (name) => typeof cls[name] === "function" && name.startsWith("before"),
       );
       for (const method of methods) {
-        const result = cls[method](req, res);
+        const result = await cls[method](req, res);
         if (Array.isArray(result)) {
           [req, res] = result as [Tina4Request, Tina4Response];
         }
@@ -122,18 +127,22 @@ export class MiddlewareRunner {
   /**
    * Execute every afterX static method found on the supplied classes,
    * in order. Returns the (possibly mutated) request and response pair.
+   *
+   * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
+   * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
+   * after-hooks keep working unchanged.
    */
-  static runAfter(
+  static async runAfter(
     classes: any[],
     req: Tina4Request,
     res: Tina4Response,
-  ): [Tina4Request, Tina4Response] {
+  ): Promise<[Tina4Request, Tina4Response]> {
     for (const cls of classes) {
       const methods = Object.getOwnPropertyNames(cls).filter(
         (name) => typeof cls[name] === "function" && name.startsWith("after"),
       );
       for (const method of methods) {
-        const result = cls[method](req, res);
+        const result = await cls[method](req, res);
         if (Array.isArray(result)) {
           [req, res] = result as [Tina4Request, Tina4Response];
         }

package/packages/core/src/server.ts

@@ -1142,7 +1142,7 @@ ${reset}
           ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
         ];
         if (globalMiddleware.length > 0) {
-          const [, , proceed] = MiddlewareRunner.runBefore(globalMiddleware, req, res);
+          const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
           if (!proceed || res.raw.writableEnded) return;
         }
 
@@ -1240,7 +1240,7 @@ ${reset}
         // Header mutations here are no-ops once the response is flushed (Node
         // sends headers with the body) — set response headers in beforeX.
         if (globalMiddleware.length > 0) {
-          MiddlewareRunner.runAfter(globalMiddleware, req, res);
+          await MiddlewareRunner.runAfter(globalMiddleware, req, res);
         }
 
         if (!res.raw.writableEnded) {

package/packages/orm/src/cachedDatabase.ts

@@ -31,17 +31,12 @@
 
 import { QueryCache } from "./sqlTranslation.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
+import type { CacheBackend } from "@tina4/core";
 
 function isTruthy(val: string | undefined): boolean {
   return ["true", "1", "yes", "on"].includes((val ?? "").trim().toLowerCase());
 }
 
-/** Network backends that cannot serve a SYNCHRONOUS db.fetch() path. */
-const NETWORK_DB_CACHE_BACKENDS = new Set(["redis", "valkey", "memcached", "memcache", "mongodb", "mongo"]);
-
-/** One-time guard so the distributed-DB-cache warning logs once per process. */
-let _warnedNetworkDbCache = false;
-
 /**
  * Options for wrapping an adapter with a query cache. When several pooled
  * connections must share one cache store (so a write on any connection
@@ -77,6 +72,25 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   private hits: number = 0;
   private misses: number = 0;
 
+  /**
+   * Persistent-mode distributed backend (TINA4_DB_CACHE=true). Built lazily from
+   * the SAME unified `createBackend()` factory the response/KV cache uses, so
+   * multiple Database instances share one cache with global write-invalidation
+   * (parity with Python's connection.py, which routes the persistent DB cache
+   * through `_create_backend`). The read path (`fetchAsync`/`fetchOneAsync`/
+   * `queryAsync`) is async, so the backend's async get/set work directly — no
+   * sync-path restriction. Request-scoped mode keeps the in-process QueryCache
+   * above (ephemeral, fastest, never serialized).
+   *
+   * `null` until the first async read builds it; a `memory` backend (the
+   * default) means the persistent layer behaves in-process exactly as before, so
+   * default behaviour is unchanged and only an explicit redis/etc. backend
+   * distributes.
+   */
+  private backend: CacheBackend | null = null;
+  private backendPromise: Promise<CacheBackend | null> | null = null;
+  private backendName: string;
+
   constructor(adapter: DatabaseAdapter, options: CachedAdapterOptions = {}) {
     this.adapter = adapter;
     this.cachePersistent = options.persistent ?? isTruthy(process.env.TINA4_DB_CACHE);
@@ -94,32 +108,52 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
 
     this.cache = options.sharedCache ?? new QueryCache({ defaultTtl: this.ttl, maxSize: 10000 });
 
-    // Persistent mode runs on the SYNCHRONOUS db.fetch() path, which cannot
-    // await an async cache backend. So the persistent DB-query cache is always
-    // the in-process QueryCache above (synchronous, no serialization-over-the-
-    // wire). If the operator selects a NETWORK backend via TINA4_DB_CACHE_BACKEND
-    // (redis/valkey/memcached/mongodb), warn once and fall back to in-process
-    // memory — distributed DB-query caching isn't available on Node's sync
-    // fetch path; use the response cache (cacheGet/cacheSet) for distributed
-    // caching. (File/database/memory selections also resolve to the in-process
-    // store here — the unified network backends live behind the async KV API.)
-    if (this.cachePersistent) {
-      const backendName = (process.env.TINA4_DB_CACHE_BACKEND ?? "memory").toLowerCase().trim();
-      if (NETWORK_DB_CACHE_BACKENDS.has(backendName) && !_warnedNetworkDbCache) {
-        _warnedNetworkDbCache = true;
-        // eslint-disable-next-line no-console
-        console.warn(
-          `[tina4] TINA4_DB_CACHE_BACKEND='${backendName}' selects a distributed cache, ` +
-          `but Node's db.fetch() is synchronous so distributed DB-query caching is not ` +
-          `available on that path — falling back to the in-process memory store. ` +
-          `For distributed caching use the response cache (cacheGet/cacheSet).`,
-        );
-      }
-    }
+    // Persistent mode now routes through the unified async backend (the read
+    // path — fetchAsync/fetchOneAsync/queryAsync — is async, so the backend's
+    // async get/set work directly). TINA4_DB_CACHE_BACKEND + TINA4_DB_CACHE_URL
+    // select the backend (default `memory` = in-process, unchanged behaviour).
+    // The backend is built lazily on first async read so an unreachable network
+    // backend degrades to `file` (via createBackend's own fallback) without
+    // blocking construction.
+    this.backendName = (process.env.TINA4_DB_CACHE_BACKEND ?? "memory").toLowerCase().trim();
 
     CachedDatabaseAdapter.instances.add(this);
   }
 
+  /**
+   * Whether the persistent layer should use a distributed/serialised backend.
+   * For the default `memory` backend we keep the in-process QueryCache (fast,
+   * no serialisation) so behaviour is identical to before; only an explicit
+   * non-memory backend (redis/valkey/memcached/mongodb/database/file) routes
+   * through the unified async backend for cross-instance sharing.
+   */
+  private usesPersistentBackend(): boolean {
+    return this.cachePersistent && this.backendName !== "memory";
+  }
+
+  /** Lazily build (and memoise) the persistent backend via createBackend(). */
+  private async getBackend(): Promise<CacheBackend | null> {
+    if (this.backend) return this.backend;
+    if (!this.backendPromise) {
+      this.backendPromise = (async () => {
+        try {
+          // Dynamic import keeps @tina4/orm free of an import-time cycle with
+          // @tina4/core (whose `database` backend dynamically imports @tina4/orm).
+          const core: any = await import("@tina4/core");
+          const b: CacheBackend = await core.createBackend({
+            backend: this.backendName,
+            cacheUrl: process.env.TINA4_DB_CACHE_URL,
+          });
+          this.backend = b;
+          return b;
+        } catch {
+          return null; // fall back to the in-process QueryCache
+        }
+      })();
+    }
+    return this.backendPromise;
+  }
+
   // ── Cache mode helpers ────────────────────────────────────
 
   /** Current cache mode: "persistent" | "request" | "off". */
@@ -171,9 +205,14 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       mode: this.cacheMode(),
       hits: this.hits,
       misses: this.misses,
+      // `size` is the in-process figure. When a distributed persistent backend
+      // is active the authoritative size lives in redis/etc.; the hit/miss
+      // counters here are still real (tracked locally per the read path).
       size: this.cache.size(),
       ttl: this.ttl,
-      backend: "memory",
+      // Report the actually-configured persistent backend so the operator sees
+      // where cross-instance entries land (parity with Python's cache_stats).
+      backend: this.usesPersistentBackend() ? this.backendName : "memory",
     };
   }
 
@@ -182,11 +221,68 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
+    // Best-effort flush of the distributed backend too (fire-and-forget — this
+    // method is synchronous to keep db.cacheClear() ergonomic).
+    if (this.usesPersistentBackend()) {
+      void this.getBackend().then((b) => b?.clear()).catch(() => { /* best effort */ });
+    }
   }
 
   /** Clear the entire query cache (called on writes). */
   private invalidate(): void {
     this.cache.clear();
+    // Persistent distributed backend: clear it too so a write on ANY instance
+    // invalidates entries cached by ALL instances (global write-invalidation,
+    // parity with Python's _cache_invalidate → backend.clear()). Fire-and-forget
+    // on the sync write path (execute/insert/...); the async write methods below
+    // await invalidateAsync() instead for deterministic ordering.
+    if (this.usesPersistentBackend()) {
+      void this.getBackend().then((b) => b?.clear()).catch(() => { /* best effort */ });
+    }
+  }
+
+  /** Async write-invalidation — awaits the distributed backend clear. */
+  private async invalidateAsync(): Promise<void> {
+    this.cache.clear();
+    if (this.usesPersistentBackend()) {
+      const b = await this.getBackend();
+      if (b) { try { await b.clear(); } catch { /* best effort */ } }
+    }
+  }
+
+  // ── Persistent-backend get/set helpers (serialised rows) ──
+  //
+  // The persistent backend stores the adapter's row payload (T[] for fetch/
+  // query, {row:T|null} for fetchOne) as plain JSON — every backend (redis
+  // SETEX, mongo doc, db row) round-trips it. fetchOne is wrapped in an object
+  // so a genuine `null` row is distinguishable from a cache miss (the backend
+  // returns undefined on miss).
+
+  private async backendGetRows<T>(key: string): Promise<T[] | undefined> {
+    const b = await this.getBackend();
+    if (!b) return undefined;
+    const raw = await b.get(key);
+    return Array.isArray(raw) ? (raw as T[]) : undefined;
+  }
+
+  private async backendSetRows<T>(key: string, rows: T[]): Promise<void> {
+    const b = await this.getBackend();
+    if (b) { try { await b.set(key, rows, this.ttl); } catch { /* best effort */ } }
+  }
+
+  private async backendGetOne<T>(key: string): Promise<{ row: T | null } | undefined> {
+    const b = await this.getBackend();
+    if (!b) return undefined;
+    const raw = await b.get(key);
+    if (raw && typeof raw === "object" && "row" in (raw as object)) {
+      return raw as { row: T | null };
+    }
+    return undefined;
+  }
+
+  private async backendSetOne<T>(key: string, row: T | null): Promise<void> {
+    const b = await this.getBackend();
+    if (b) { try { await b.set(key, { row }, this.ttl); } catch { /* best effort */ } }
   }
 
   // ── DatabaseAdapter interface — writes flush, reads cache ──
@@ -327,6 +423,18 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       : this.adapter.fetch<T>(sql, params, limit, skip);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
+      // Persistent distributed backend is AUTHORITATIVE (mirrors Python, where a
+      // configured _cache_backend bypasses the in-process dict). This keeps
+      // cross-instance write-invalidation deterministic: a write clears the
+      // shared backend, so every instance misses on its next read.
+      if (this.usesPersistentBackend()) {
+        const shared = await this.backendGetRows<T>(key);
+        if (shared !== undefined) { this.hits++; return shared; }
+        const result = await run();
+        await this.backendSetRows(key, result);
+        this.misses++;
+        return result;
+      }
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
         this.hits++;
@@ -346,6 +454,14 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       : this.adapter.fetchOne<T>(sql, params);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
+      if (this.usesPersistentBackend()) {
+        const shared = await this.backendGetOne<T>(key);
+        if (shared !== undefined) { this.hits++; return shared.row; }
+        const result = await run();
+        await this.backendSetOne(key, result);
+        this.misses++;
+        return result;
+      }
       const cached = this.cache.get<T | null>(key);
       if (cached !== undefined) {
         this.hits++;
@@ -365,6 +481,14 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       : this.adapter.query<T>(sql, params);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined);
+      if (this.usesPersistentBackend()) {
+        const shared = await this.backendGetRows<T>(key);
+        if (shared !== undefined) { this.hits++; return shared; }
+        const result = await run();
+        await this.backendSetRows(key, result);
+        this.misses++;
+        return result;
+      }
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
         this.hits++;
@@ -379,28 +503,28 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   }
 
   async executeAsync(sql: string, params?: unknown[]): Promise<unknown> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).executeAsync
       ? await (this.adapter as any).executeAsync(sql, params)
       : this.adapter.execute(sql, params);
   }
 
   async insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).insertAsync
       ? await (this.adapter as any).insertAsync(table, data)
       : this.adapter.insert(table, data);
   }
 
   async updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): Promise<DatabaseResult> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).updateAsync
       ? await (this.adapter as any).updateAsync(table, data, filter, params)
       : this.adapter.update(table, data, filter);
   }
 
   async deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).deleteAsync
       ? await (this.adapter as any).deleteAsync(table, filter, params)
       : this.adapter.delete(table, filter as Record<string, unknown>);

package/packages/orm/src/database.ts

@@ -458,8 +458,17 @@ export class Database {
   /** Factory for creating new adapters (used by pool) */
   private adapterFactory: (() => Promise<DatabaseAdapter>) | null = null;
 
-  /** Whether to automatically commit after each write operation */
-  private autoCommit: boolean = process.env.TINA4_AUTOCOMMIT === "true";
+  /**
+   * Whether a standalone write auto-commits. ON by default — a write made
+   * outside an explicit transaction commits on its own connection before
+   * returning (so it's durable and visible across pooled connections). Inside
+   * startTransaction()/commit()/rollback() the per-statement commit is
+   * suppressed, so explicit transactions stay atomic. Set TINA4_AUTOCOMMIT=false
+   * for strict manual-commit mode.
+   */
+  private autoCommit: boolean = ["true", "1", "yes"].includes(
+    (process.env.TINA4_AUTOCOMMIT ?? "true").toLowerCase(),
+  );
   private lastError: string | null = null;
 
   /** Database engine type (sqlite, postgres, mysql, mssql, firebird) */
@@ -675,7 +684,7 @@ export class Database {
     try {
       const adapter = this.getNextAdapter();
       const result = await adapterExecute(adapter, sql, params);
-      if (this.autoCommit) {
+      if (this.autoCommit && !this.inExplicitTransaction()) {
         try { await adapterCommit(adapter); } catch { /* no active transaction */ }
       }
       this.lastError = null;
@@ -697,7 +706,7 @@ export class Database {
     const result = (adapter as any).insertAsync
       ? await (adapter as any).insertAsync(table, data)
       : adapter.insert(table, data);
-    if (this.autoCommit) {
+    if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
     return result;
@@ -709,7 +718,7 @@ export class Database {
     const result = (adapter as any).updateAsync
       ? await (adapter as any).updateAsync(table, data, filter ?? {}, params)
       : adapter.update(table, data, filter ?? {}, params);
-    if (this.autoCommit) {
+    if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
     return result;
@@ -721,7 +730,7 @@ export class Database {
     const result = (adapter as any).deleteAsync
       ? await (adapter as any).deleteAsync(table, filter ?? {}, params)
       : adapter.delete(table, filter ?? {}, params);
-    if (this.autoCommit) {
+    if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
     return result;
@@ -741,6 +750,16 @@ export class Database {
     }
   }
 
+  /**
+   * True while an explicit transaction is active on the current async context.
+   * startTransaction() pins an adapter into txStore; commit()/rollback() clear
+   * it. Standalone writes only auto-commit when this is false, so per-statement
+   * commits never break the atomicity of an explicit transaction.
+   */
+  private inExplicitTransaction(): boolean {
+    return !!this.txStore.getStore()?.adapter;
+  }
+
   /**
    * Start a transaction. Pins the adapter to the current async context for
    * the whole transaction so executes and the final commit/rollback all run