tina4-nodejs 3.13.98 → 3.13.100

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

@@ -14,6 +14,15 @@ export interface LiveResponse {
 }
 /** WebSocket broadcaster hook wired by @tina4/core so pushLive can broadcast. */
 export type LiveBroadcaster = (wsPath: string | null, name: string, envelope: string) => void;
+/**
+ * Cache for parsed filter chains: expr string -> [variable, filters].
+ * Exported (like TEMPLATE_CACHE_MAX) so the ADR-0004 bound has something for
+ * a test to inspect directly — module-level state has no instance to read
+ * off, unlike `compiled`/`compiledStrings`/`fragmentCache`.
+ */
+export declare const filterChainCache: Map<string, [string, [string, unknown[]][]]>;
+/** Cache for parsed dotted/bracket paths: expr string -> [parts, fromBracket]. Exported for the same reason as filterChainCache. */
+export declare const pathParseCache: Map<string, [string[], boolean[]]>;
 /**
  * Hard cap on the template caches — `compiled` and `compiledStrings`
  * (ADR-0004, parity with PHP/Python/Ruby TEMPLATE_CACHE_MAX).
@@ -26,6 +35,18 @@ export type LiveBroadcaster = (wsPath: string | null, name: string, envelope: st
  * dynamically adds an entry per distinct string.
  */
 export declare const TEMPLATE_CACHE_MAX = 256;
+/**
+ * Hard cap on every per-expression memo cache — `filterChainCache` and
+ * `pathParseCache` (ADR-0004, parity with PHP's MEMO_CACHE_MAX and the
+ * Python master's `@lru_cache(maxsize=1024)` on the equivalent module-level
+ * parsers). Deliberately higher than TEMPLATE_CACHE_MAX: one entry here is a
+ * small parsed-path array, orders of magnitude smaller than a token list.
+ *
+ * Also reused for `fragmentCache` (the `{% cache %}` tag's runtime store):
+ * TEMPLATE_CACHE_MAX, not this one — a rendered fragment is a whole HTML
+ * string, the same order of magnitude as a compiled template.
+ */
+export declare const MEMO_CACHE_MAX = 1024;
 /**
  * Set the session ID used by formToken() / form_token() for CSRF session binding.
  */
@@ -95,20 +116,16 @@ export declare class Frond {
     sandbox(filters?: string[], tags?: string[], vars?: string[]): Frond;
     unsandbox(): Frond;
     /**
-     * Register a custom filter. The filter is persisted at class level
-     * so new instances created by hot-reload inherit it automatically;
-     * the live instance's local filter map also receives the addition
-     * immediately. Mirrors Python's _ClassOrInstanceMethod dual-call.
+     * Register a custom filter on this instance only. Use the static method
+     * for process-global registration. tina4: ADR-0052.
      */
     addFilter(name: string, fn: FilterFn): void;
     /**
-     * Register a global variable available in all templates. Persisted
-     * at class level — see ``addFilter`` for the dual-call semantics.
+     * Register a global variable on this instance only.
      */
     addGlobal(name: string, value: unknown): void;
     /**
-     * Register a custom test. Persisted at class level — see
-     * ``addFilter`` for the dual-call semantics.
+     * Register a custom test on this instance only.
      */
     addTest(name: string, fn: TestFn): void;
     /**
@@ -126,6 +143,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;
@@ -133,6 +160,31 @@ export declare class Frond {
     private executeWithSource;
     private execute;
     private extractBlocks;
+    /**
+     * Depth-aware block substitution against `source` (typically the
+     * fully-resolved root template).
+     *
+     * A single regex `.replace()` pass (the flat `pattern` this replaces in
+     * renderWithBlocks) pairs an OUTER block's open tag with the FIRST
+     * `{% endblock %}` found -- which, when the outer block wraps a NESTED
+     * `{% block %}`, is the nested block's own close tag, not the outer's.
+     * That silently truncates the outer block's captured content and drops
+     * everything after the inner endblock (the root-nested-block
+     * content-loss bug). This scans with an open/close depth counter
+     * instead (mirroring extractBlocks), so an outer block always captures
+     * its FULL body, nested child blocks included.
+     *
+     * The content chosen for each block -- the child override in `blocks`
+     * if present, else the block's own default body -- is then recursively
+     * substituted against the SAME `blocks` map before being tokenized and
+     * rendered, so a block nested inside another block resolves correctly
+     * regardless of which template in the inheritance chain declared the
+     * nesting (the root, an intermediate, however many levels deep).
+     *
+     * `{{ parent() }}` / `{{ super() }}` inside a block still render that
+     * block's OWN default content at this level (lazy, on first call).
+     */
+    private substituteBlocks;
     private renderWithBlocks;
     private renderTokens;
     /**

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.