tina4-nodejs 3.13.97 → 3.13.99

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

@@ -4,7 +4,18 @@ export declare class TestResponse {
     readonly body: string;
     readonly headers: Record<string, string>;
     readonly contentType: string;
-    constructor(statusCode: number, headers: Record<string, string>, body: string);
+    /** Every value sent per header name (lowercased), in emission order. */
+    private readonly headerList;
+    constructor(statusCode: number, headerList: Record<string, string[]>, body: string);
+    /**
+     * Every value sent for `name` (case-insensitive), in emission order.
+     *
+     * A header sent once returns a one-item array; a header never sent returns
+     * an empty array. This is the one place a duplicate response header (two
+     * `Set-Cookie`) is visible — `headers[name]` always collapses to the LAST
+     * value, same as before (TC-HEADER-COLLAPSE, TC-DEC-02).
+     */
+    getHeaderList(name: string): string[];
     /** Parse body as JSON. */
     json(): unknown;
     /** Return body as a string. */
@@ -17,8 +28,23 @@ export interface RequestOptions {
     headers?: Record<string, string>;
 }
 export declare class TestClient {
-    private router;
+    /** An explicitly-injected router (test isolation); undefined means "use the live server's router, or defaultRouter". */
+    private readonly explicitRouter;
+    private ctxPromise;
     constructor(router?: Router);
+    /**
+     * Resolve (and memoise) the DispatchContext this client dispatches
+     * through.
+     *
+     * An explicitly-injected router always gets its OWN standalone context
+     * (buildDispatchContext) — the test-isolation contract an injected router
+     * has always had: a dedicated Router never races with whatever else is
+     * registered on defaultRouter or a live server. With no injected router,
+     * the LIVE server's context wins when one is running in this process
+     * (getLiveDispatchContext — maximum fidelity, mirrors Ruby's
+     * `RackApp.current`), else a standalone context bound to defaultRouter.
+     */
+    private context;
     /** Send a GET request. */
     get(path: string, options?: RequestOptions): Promise<TestResponse>;
     /** Send a POST request. */
@@ -29,7 +55,7 @@ export declare class TestClient {
     patch(path: string, options?: RequestOptions): Promise<TestResponse>;
     /** Send a DELETE request. */
     delete(path: string, options?: RequestOptions): Promise<TestResponse>;
-    /** Build a mock request, match the route, execute the handler. */
+    /** Build a mock request/response pair and dispatch it through the REAL pipeline (runDispatch). */
     private _request;
     /** Gather the captured status/headers/body into a TestResponse and free the socket. */
     private _collect;

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

@@ -1,19 +1,23 @@
 /**
  * Tina4 Node.js — Inline testing framework.
  *
- * Attach test assertions to functions and run them all at once.
+ * Attach test expectations to functions and run them all at once.
  *
- *     import { tests, assertEqual, assertRaises, runAll } from "./testing.js";
+ *     import { tests, expectEqual, expectRaises, runAll } from "./testing.js";
  *
  *     const add = tests(
- *       assertEqual([5, 3], 8),
- *       assertRaises(Error, [null]),
+ *       expectEqual([5, 3], 8),
+ *       expectRaises(Error, [null]),
  *     )(function add(a: number, b: number | null = null): number {
  *       if (b === null) throw new Error("b required");
  *       return a + b;
  *     });
  *
  *     runAll();
+ *
+ * The builders are named expect* — DESCRIPTORS that record an expectation for the
+ * runner — deliberately distinct from the xUnit assert* on Tina4Test (test.ts),
+ * so importing the wrong surface can never silently change call semantics.
  */
 interface Assertion {
     type: "equal" | "raises" | "true" | "false";
@@ -31,14 +35,14 @@ interface TestResults {
         message?: string;
     }>;
 }
-/** Assert that calling the function with `args` returns `expected`. */
-export declare function assertEqual(args: unknown[], expected: unknown): Assertion;
-/** Assert that calling the function with `args` throws an instance of `errorClass`. */
-export declare function assertRaises(errorClass: new (...a: unknown[]) => Error, args: unknown[]): Assertion;
-/** Assert that calling the function with `args` returns a truthy value. */
-export declare function assertTrue(args: unknown[]): Assertion;
-/** Assert that calling the function with `args` returns a falsy value. */
-export declare function assertFalse(args: unknown[]): Assertion;
+/** Expect that calling the function with `args` returns `expected`. */
+export declare function expectEqual(args: unknown[], expected: unknown): Assertion;
+/** Expect that calling the function with `args` throws an instance of `errorClass`. */
+export declare function expectRaises(errorClass: new (...a: unknown[]) => Error, args: unknown[]): Assertion;
+/** Expect that calling the function with `args` returns a truthy value. */
+export declare function expectTrue(args: unknown[]): Assertion;
+/** Expect that calling the function with `args` returns a falsy value. */
+export declare function expectFalse(args: unknown[]): Assertion;
 /**
  * Attach inline test assertions to a function.
  *

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

@@ -18,20 +18,32 @@ export interface Tina4Request extends IncomingMessage {
     /**
      * Path params. Typed params arrive coerced: `{id:int}`/`{id:integer}` and
      * `{p:float}`/`{p:number}` are JS `number`s; every other type and untyped
-     * `{id}` stay `string` (parity with Python/PHP/Ruby).
+     * `{id}` stay `string` (parity with Python/PHP/Ruby). ROUTE-ONLY — never
+     * the query string or body (REQ-PARAM-POLLUTION, 3.13.99). Writable: the
+     * router assigns it AFTER createRequest() builds the wire-derived fields
+     * below, once a route has matched.
      */
     params: Record<string, string | number>;
-    query: Record<string, string>;
+    /**
+     * Core wire-derived fields below are `readonly` (REQ-IMMUTABILITY-DIVERGE,
+     * 3.13.99) — set once in createRequest() and never reassigned afterward,
+     * matching PHP's `readonly` properties and Ruby's writer-less attr_reader
+     * (the two languages already at this posture; this is TS-compile-time
+     * only, like PHP/Ruby's enforcement is at their own language boundary).
+     * `params`/`body`/`files`/`session`/`user` stay mutable: the router and
+     * middleware legitimately set them after construction.
+     */
+    readonly query: Record<string, string>;
     /**
      * Request path only — no query string. Matches `request.path` in
      * Python/PHP/Ruby. Example: `/users/42`.
      */
-    path: string;
+    readonly path: string;
     /**
      * Raw query string with no leading "?". Matches `request.query_string`
      * (Python/Ruby) and `request.queryString` (PHP). Example: `"page=2"`.
      */
-    queryString: string;
+    readonly queryString: string;
     /**
      * Full absolute URL — `scheme://host[:port]/path[?query]`.
      * Honours X-Forwarded-Proto / X-Forwarded-Host. Matches PHP/Ruby/Python parity.
@@ -39,19 +51,19 @@ export interface Tina4Request extends IncomingMessage {
      * Note: this overrides Node's native `IncomingMessage.url` (which contains
      * only path+query). Inside Tina4 handlers, `req.url` is always the full URL.
      */
-    url: string;
+    readonly url: string;
     body: unknown;
-    ip: string;
+    readonly ip: string;
     /**
      * Raw socket peer address - NEVER honours X-Forwarded-For (which any
      * caller can spoof), so it can be trusted for security decisions.
      * Empty for in-process / synthetic requests. Parity with Python's
      * request.remote_ip and PHP's Request::$remoteIp.
      */
-    remoteIp: string;
+    readonly remoteIp: string;
     files: Record<string, UploadedFile | UploadedFile[]>;
-    cookies: Record<string, string>;
-    contentType: string;
+    readonly cookies: Record<string, string>;
+    readonly contentType: string;
     /**
      * NULL when the session backend was unusable for this request (ADR-0021).
      * The request path logs the failure and degrades rather than 500-ing, so a

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

@@ -0,0 +1,11 @@
+/**
+ * Walk up from this file to the nearest package.json carrying a non-empty
+ * `version` field. Stops at the first hit (nearest wins), so a published
+ * `@tina4/core` install resolves its OWN package.json, and the monorepo dev
+ * tree resolves the workspace root's -- both the real, current version.
+ * Falls back to "0.0.0" only if none is found within the walk (a layout with
+ * no package.json anywhere in its ancestry at all).
+ */
+export declare function resolveFrameworkVersion(): string;
+/** Resolved once at module load -- every @tina4/core surface imports this. */
+export declare const TINA4_VERSION: string;

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

@@ -155,7 +155,7 @@ export declare class WsBackplaneManager {
 /** Minimal logger shape so the manager doesn't import the logger module. */
 export interface WsBackplaneLogger {
     info(message: string): void;
-    warn(message: string): void;
+    warning(message: string): void;
     error(message: string): void;
 }
 /** Build the cross-framework envelope. Exported for tests. */

package/types/frond/src/engine.d.ts

@@ -126,6 +126,16 @@ export declare class Frond {
     /** Render a debug dump of a value as HTML — parity with PHP/Ruby/Python.
      * Gated on TINA4_DEBUG=true. Returns empty string in production. */
     renderDump(value: unknown): string;
+    /**
+     * Load a template's source, CONFINED under the templates directory.
+     *
+     * Every path-taking tag ({% include %}, {% extends %}, {% import %},
+     * {% from ... import %}) funnels through this one loader, so this single guard
+     * confines them all (TAG-DEC-01): a name that is absolute, climbs out with a
+     * `..` up-level segment, or resolves through a symlink to a location OUTSIDE
+     * the templates root is REFUSED -- the outside file is never read. Template
+     * -side analogue of the static-asset confinement (feature 41 / ADR-0050).
+     */
     private load;
     /** Execute pre-tokenized template against context. */
     private executeCached;

package/types/orm/src/adapters/firebird.d.ts

@@ -89,9 +89,42 @@ export declare class FirebirdAdapter implements DatabaseAdapter {
     private db;
     private transaction;
     private _lastInsertId;
+    /** Resolved node-firebird config, kept so a dead connection can re-attach. */
+    private fbConfig;
+    private static readonly DEAD_CONN_MARKERS;
+    /** Is this a dead-socket error worth a transparent reconnect (not a logical SQL error)? */
+    static isDeadConnection(err: unknown): boolean;
     constructor(config: FirebirdConfig | string);
     /** Connect to Firebird. Must be called before using the adapter. */
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one
+     * that cannot sets this false so executeMany rejects BEFORE the first
+     * write rather than risking partial durability.
+     */
+    supportsAtomicBatch: boolean;
     connect(): Promise<void>;
+    private attachOnce;
+    /**
+     * Attach with a BOUNDED retry (FB-DEC-03). node-firebird's SRP login over
+     * WireCrypt is intermittently flaky (~12% measured historically), and a flake
+     * surfaces as an auth/handshake error indistinguishable from a real one, so a
+     * bounded retry-all is the robust, honest handling: a transient handshake
+     * failure recovers, while a genuine bad credential still fails after the bound
+     * -- never skipped, never papered over.
+     */
+    private attachWithRetry;
+    /**
+     * Run a node-firebird op; on a DEAD-connection error (outside an explicit
+     * transaction) re-attach once and retry (FB-DEC-01). Inside a transaction the
+     * error surfaces -- atomicity beats resilience, and the caller rolls back.
+     */
+    private withReconnect;
+    private reconnectFirebird;
     private parseUrl;
     private ensureConnected;
     /** Translate SQL for Firebird dialect. */
@@ -121,6 +154,28 @@ export declare class FirebirdAdapter implements DatabaseAdapter {
     private statementHandle;
     private queryPromise;
     private executePromise;
+    /**
+     * The real affected-row count. node-firebird gives NO DML count of its own
+     * (the callback result is undefined -- MEASURED), but Firebird 5 multi-row
+     * RETURNING surfaces one row per affected row, so `... RETURNING 1` + the row
+     * count IS the real count (FB-AFFECTED-FAB replaces the hardcoded 1). RETURNING
+     * a constant, not `*`, so a large update/delete does not materialise full rows.
+     */
+    private executeReturningCount;
+    /**
+     * Firebird has no generic last_insert_id -- read the GEN_<TABLE>_ID generator
+     * the row's BEFORE INSERT trigger drew from (FB-LASTID-GAP). Column-name-
+     * independent, so correct for a non-`id` PK too. null when the table has no
+     * such generator (GEN_ID then throws -> caught).
+     */
+    private readGeneratorId;
+    /**
+     * Read a node-firebird BLOB column into a Buffer. A BLOB arrives as a STREAMING
+     * FUNCTION (fn((err, name, emitter) => emitter.on('data'|'end'))), NOT a Buffer
+     * -- MEASURED -- so the old decodeBlobs no-op leaked the function to the caller
+     * and no bytes round-tripped (FB-BLOB-SRP-UNVERIFIED).
+     */
+    private readBlob;
     execute(sql: string, params?: unknown[]): unknown;
     executeMany(sql: string, paramsList: unknown[][]): {
         totalAffected: number;
@@ -133,8 +188,12 @@ export declare class FirebirdAdapter implements DatabaseAdapter {
     executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
     queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-    /** Ensure BLOB columns are readable — node-firebird may return callback-based
-     *  blob readers. Convert to Buffer. Regular buffers pass through unchanged. */
+    /**
+     * Read out any BLOB columns to Buffers. node-firebird returns a BLOB as a
+     * STREAMING FUNCTION, not a Buffer (MEASURED), so a column whose value is a
+     * function is read via readBlob(); everything else passes through unchanged
+     * (FB-BLOB-SRP-UNVERIFIED -- the old no-op leaked the function to the caller).
+     */
     private decodeBlobs;
     fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
     fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;

package/types/orm/src/adapters/mongodb.d.ts

@@ -24,6 +24,17 @@ export declare class MongodbAdapter implements DatabaseAdapter {
     private _dbName;
     constructor(config: MongoConfig | string);
     /** Connect to MongoDB. Must be called before using the adapter. */
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one
+     * that cannot sets this false so executeMany rejects BEFORE the first
+     * write rather than risking partial durability.
+     */
+    supportsAtomicBatch: boolean;
     connect(): Promise<void>;
     private ensureConnected;
     /** Execute a SQL-like statement translated to a MongoDB operation. */
@@ -43,6 +54,15 @@ export declare class MongodbAdapter implements DatabaseAdapter {
     fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
     fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
     fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    /**
+     * Atomic, monotonic, concurrency-safe next id — feature 16. A
+     * findOneAndUpdate($inc) on the tina4_sequences collection, keyed by _id (its
+     * built-in unique index makes concurrent first-use upserts race-safe: two
+     * callers can never create two counters for one table). Seeds from
+     * MAX(pkColumn) the FIRST time only ($setOnInsert). Throws on an impossible
+     * empty result rather than returning a fixed id that could collide with a row.
+     */
+    getNextId(table: string, pkColumn?: string): Promise<number>;
     insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
     insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
     update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult;

package/types/orm/src/adapters/mssql.d.ts

@@ -22,6 +22,17 @@ export declare class MssqlAdapter implements DatabaseAdapter {
     private _inTransaction;
     constructor(config: MssqlConfig | string);
     /** Connect to MSSQL. Must be called before using the adapter. */
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one
+     * that cannot sets this false so executeMany rejects BEFORE the first
+     * write rather than risking partial durability.
+     */
+    supportsAtomicBatch: boolean;
     connect(): Promise<void>;
     private parseUrl;
     private ensureConnected;

package/types/orm/src/adapters/mysql.d.ts

@@ -21,6 +21,17 @@ export declare class MysqlAdapter implements DatabaseAdapter {
     private _inTransaction;
     constructor(config: MysqlConfig | string);
     /** Connect to MySQL. Must be called before using the adapter. */
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one
+     * that cannot sets this false so executeMany rejects BEFORE the first
+     * write rather than risking partial durability.
+     */
+    supportsAtomicBatch: boolean;
     connect(): Promise<void>;
     private ensureConnected;
     private queryPromise;

package/types/orm/src/adapters/odbc.d.ts

@@ -2,6 +2,10 @@ import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } fro
 export interface OdbcConfig {
     /** Full ODBC connection string, e.g. "DSN=MyDSN" or "DRIVER={SQL Server};SERVER=host;DATABASE=db" */
     connectionString: string;
+    /** Optional username; appended as UID when not already in the connection string. */
+    username?: string;
+    /** Optional password; appended as PWD when not already in the connection string. */
+    password?: string;
 }
 export declare class OdbcAdapter implements DatabaseAdapter {
     private config;
@@ -16,6 +20,14 @@ export declare class OdbcAdapter implements DatabaseAdapter {
     constructor(config: OdbcConfig | string);
     /** Extract the raw ODBC connection string from config. */
     private getConnectionString;
+    /**
+     * The connection string with credentials applied. ODBC has no separate-
+     * credentials API (odbc.connect() reads only the string), so a username/
+     * password passed to Database.create() must be folded in as UID/PWD - the
+     * adapter used to drop them. Never used for diagnostics (describeTarget reads
+     * the raw string), so the password never reaches an error message.
+     */
+    private effectiveConnectionString;
     /**
      * The address for a diagnostic message. ODBC hides it inside an opaque
      * driver keyword string, so this reads the standard keywords and falls back to
@@ -24,6 +36,17 @@ export declare class OdbcAdapter implements DatabaseAdapter {
      */
     private describeTarget;
     /** Connect to the ODBC data source. Must be called before using the adapter. */
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one
+     * that cannot sets this false so executeMany rejects BEFORE the first
+     * write rather than risking partial durability.
+     */
+    supportsAtomicBatch: boolean;
     connect(): Promise<void>;
     private ensureConnected;
     execute(sql: string, params?: unknown[]): unknown;
@@ -56,18 +79,20 @@ export declare class OdbcAdapter implements DatabaseAdapter {
         totalAffected: number;
         lastId?: number | bigint;
     }>;
+    /** The real affected-row count from an odbc result, when the driver reports it. */
+    private affectedCount;
     /** Run a SELECT and return all matching rows. */
     queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /** Run a SELECT with optional LIMIT/OFFSET pagination. */
     fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
     /** Run a SELECT and return the first row or null. */
     fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
-    /** Insert a single row into a table. */
-    insertAsync(table: string, data: Record<string, unknown>): Promise<DatabaseResult>;
+    /** Insert a single row, or a list of rows as a batch. */
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
     /** Update rows in a table matching filter. */
-    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
     /** Delete rows from a table. */
-    deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): Promise<DatabaseResult>;
+    deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult>;
     /** Begin a transaction. */
     startTransactionAsync(): Promise<void>;
     /** Commit the current transaction. */
@@ -78,6 +103,12 @@ export declare class OdbcAdapter implements DatabaseAdapter {
     tablesAsync(): Promise<string[]>;
     /** Get column metadata for a table using ODBC catalog functions. */
     columnsAsync(table: string): Promise<ColumnInfo[]>;
+    /**
+     * The table's primary-key columns from the ODBC catalog (SQLPrimaryKeys),
+     * lower-cased for case-insensitive matching. Empty on any target that does not
+     * report them - the write-guard then requires an explicit filter.
+     */
+    private primaryKeyColumns;
     /** Check whether a table exists. */
     tableExistsAsync(name: string): Promise<boolean>;
     /** Create a table from a FieldDefinition map. Uses generic SQL — works with most ODBC sources. */

package/types/orm/src/adapters/postgres.d.ts

@@ -21,6 +21,17 @@ export declare class PostgresAdapter implements DatabaseAdapter {
     private _inTransaction;
     constructor(config: PostgresConfig | string);
     /** Connect to PostgreSQL. Must be called before using the adapter. */
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one
+     * that cannot sets this false so executeMany rejects BEFORE the first
+     * write rather than risking partial durability.
+     */
+    supportsAtomicBatch: boolean;
     connect(): Promise<void>;
     private ensureConnected;
     /** Convert ? placeholders to $1, $2, ... for pg. */

package/types/orm/src/adapters/sqlite.d.ts

@@ -2,6 +2,24 @@ import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } fro
 export declare class SQLiteAdapter implements DatabaseAdapter {
     private db;
     private _lastInsertId;
+    /** ADR-0044: readable/writable native boolean. */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: every built-in adapter can guarantee an atomic
+     * multi-row batch by default. A test-only deployment representing one that
+     * cannot (a standalone MongoDB without a replica set is the motivating real
+     * case) sets this false so executeMany rejects BEFORE the first write.
+     */
+    supportsAtomicBatch: boolean;
+    /** ADR-0044 required adapter capability. */
+    getDatabaseType(): string;
+    /**
+     * ADR-0044 canonical lifecycle name. A genuine no-op: `node:sqlite` opens
+     * the file synchronously in the constructor (see the timeout note below),
+     * so by the time a caller could reach connect() the adapter is already
+     * connected — repeated calls open no additional physical connection.
+     */
+    connect(): void;
     /**
      * TINA4_DATABASE_CONNECT_TIMEOUT DOES NOT APPLY HERE, deliberately.
      *
@@ -16,10 +34,7 @@ export declare class SQLiteAdapter implements DatabaseAdapter {
      */
     constructor(dbPath: string);
     execute(sql: string, params?: unknown[]): unknown;
-    executeMany(sql: string, paramsList: unknown[][]): {
-        totalAffected: number;
-        lastId?: number | bigint;
-    };
+    executeMany(sql: string, paramsList: unknown[][]): DatabaseResult;
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
     fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
     fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
@@ -33,6 +48,10 @@ export declare class SQLiteAdapter implements DatabaseAdapter {
     getTables(): string[];
     getColumns(table: string): ColumnInfo[];
     lastInsertId(): number | bigint | null;
+    private _closed;
+    /** ADR-0044 (DBA-L02): idempotent — node:sqlite's DatabaseSync.close()
+     * throws when called on an already-closed database, so a second close()
+     * must not reach it. */
     close(): void;
     /**
      * Atomically increment and return the next value of a tina4_sequences row.

package/types/orm/src/baseModel.d.ts

@@ -1,5 +1,4 @@
 import { QueryBuilder } from "./queryBuilder.js";
-import { QueryCache } from "./sqlTranslator.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 /**
  * Convert a snake_case name to camelCase.
@@ -29,23 +28,6 @@ export declare function toDbFieldValue(def: FieldDefinition | undefined, value:
  * null stays null; a non-decodable string keeps its raw form.
  */
 export declare function fromDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown;
-/**
- * BaseModel provides instance methods for ORM models.
- * Models extend this class and define static properties.
- *
- * Usage:
- *   class User extends BaseModel {
- *     static tableName = "users";
- *     static fields = { id: { type: "integer", primaryKey: true, autoIncrement: true }, ... };
- *     static softDelete = true;
- *     static tableFilter = "active = 1";
- *     static hasOne = [{ model: "Profile", foreignKey: "user_id" }];
- *     static hasMany = [{ model: "Post", foreignKey: "author_id" }];
- *     static _db = "secondary";
- *     static fieldMapping = { firstName: "first_name", lastName: "last_name" };
- *     static autoMap = true; // auto-generate fieldMapping from camelCase → snake_case
- *   }
- */
 export declare class BaseModel {
     static tableName: string;
     static fields: Record<string, FieldDefinition>;
@@ -55,7 +37,6 @@ export declare class BaseModel {
     static hasMany?: RelationshipDefinition[];
     static belongsTo?: RelationshipDefinition[];
     static _db?: string;
-    static _queryCache?: QueryCache;
     /**
      * When true, auto-generates fieldMapping entries from camelCase field names
      * to snake_case DB column names. Explicit fieldMapping entries always win.
@@ -315,7 +296,7 @@ export declare class BaseModel {
      * Validate this instance's values against the model's field definitions.
      * Returns an array of error strings (empty array means valid).
      */
-    validate(): string[];
+    validate(isUpdate?: boolean): string[];
     /**
      * Generate and execute CREATE TABLE DDL from the model's field definitions.
      * Uses the adapter's createTable method if available, otherwise builds SQL directly.
@@ -330,18 +311,36 @@ export declare class BaseModel {
      */
     static exists(pkValue: unknown): Promise<boolean>;
     /**
-     * Run a raw SQL query with results cached by TTL. Cache is per-model-class.
+     * Every table a cached query touches: this model's table plus every FROM/JOIN
+     * table in `sql`. A write to any of these busts the entry (CACHE-DEC-01).
+     */
+    static _cacheTags(sql: string): string[];
+    /**
+     * Run a raw SQL query with results cached by TTL.
+     *
+     * Invalidation (CACHE-DEC-01): the entry is tagged by every table the query
+     * touches (this model's table plus any FROM/JOIN tables) in ONE process-wide
+     * shared cache, so a write through the ORM (save/delete/forceDelete/restore)
+     * to ANY of those tables busts it -- including a cross-table JOIN cached on a
+     * different model. `ttl <= 0` means NO-CACHE: the query runs and the rows are
+     * returned but nothing is stored, so every read hits the database.
      *
      * @param sql     SQL query string.
      * @param params  Bind parameters.
-     * @param ttl     Cache TTL in seconds (default 60).
+     * @param ttl     Cache TTL in seconds (default 60; <= 0 = no-cache).
      * @param limit   Max records to return (default 100).
      * @param offset  Records to skip (default 0).
      * @param include Relationship names to eager-load on cache miss.
      */
     static cached<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], ttl?: number, limit?: number, offset?: number, include?: string[]): Promise<T[]>;
     /**
-     * Clear the per-model query cache.
+     * Invalidate every cached query that touches this model's table.
+     *
+     * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
+     * this table is busted too (it carries this table's tag), while a query that
+     * never touches this table is left intact. Called after every ORM write
+     * (save/delete/forceDelete/restore) so a read-after-write never serves a
+     * stale/deleted row (CACHE-DEC-01).
      */
     static clearCache(): void;
     /**
@@ -380,6 +379,11 @@ export declare class BaseModel {
     hasOne<T extends BaseModel, R extends BaseModel>(this: T, relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R), foreignKey: string): Promise<R | null>;
     /**
      * Load has-many related model instances.
+     *
+     * With no explicit `limit` this returns the WHOLE set (paged internally, like
+     * the lazy accessor), never a silent row cap -- so an imperatively-loaded
+     * has_many yields the SAME row count as the lazy path. An explicit `limit`
+     * still pages.
      */
     hasMany<T extends BaseModel, R extends BaseModel>(this: T, relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R), foreignKey: string, limit?: number, offset?: number): Promise<R[]>;
     /**
@@ -394,10 +398,26 @@ export declare class BaseModel {
     /**
      * Process foreignKey fields on every registered model so the cross-model
      * _fkRegistry (and each model's belongsTo/hasMany) is fully wired regardless
-     * of which model was used first. Idempotent — _processForeignKeys() and
-     * _applyFkRegistry() both guard against duplicates.
+     * of which model was used first, then attach the lazy relationship accessors.
+     * Idempotent — every step guards against duplicates.
      */
     private static _processAllForeignKeys;
+    /**
+     * REL-NODE-AUTOWIRE-DEAD: attach a lazy-loading accessor for each declared
+     * relationship (belongsTo/hasOne/hasMany) on this model's prototype, so
+     * `post.author` / `author.posts` resolve on attribute access. The accessor is
+     * async (Node lazy load) and caches into `_relCache` — the SAME cache eager
+     * loading fills, so `toDict` stays consistent once a relation has been loaded.
+     * Reuses the imperative belongsTo()/hasOne() path and the cross-model registry;
+     * a soft-deleted child is excluded and the has-many read is uncapped.
+     */
+    static _wireRelationshipAccessors(): void;
+    /**
+     * Lazy has-many read for a relationship accessor: excludes soft-deleted
+     * children and returns the WHOLE set (adapterQuery is uncapped, so the tail is
+     * never lost). Ordered by the child PK for a stable read.
+     */
+    private static _loadHasManyLazy;
     /**
      * Resolve a model class by name from the registry.
      */