tina4-nodejs 3.13.136 → 3.13.138

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

@@ -1,36 +1,3 @@
-/**
- * Zero-dependency MQTT 3.1.1 client — the protocol every broker and every IoT
- * device already speaks.
- *
- * Built on Node's `node:net` and `node:tls` stdlib modules only: no npm package,
- * so an app that talks to Mosquitto / EMQX / HiveMQ / AWS IoT adds nothing to its
- * dependency tree. Shaped like the Queue on purpose — publish / subscribe /
- * consume:
- *
- *     import { Mqtt } from "@tina4stack/tina4-node";
- *
- *     const mqtt = new Mqtt({ url: "mqtt://broker:1883" });   // TINA4_MQTT_URL
- *     await mqtt.connect();
- *     await mqtt.publish("fleet/meter-42/telemetry", '{"kwh":12.5}', 1);
- *
- *     for await (const message of mqtt.consume("fleet/+/telemetry", 1)) {
- *       if (message.isDuplicate()) continue;                  // QoS 1 is at-least-once
- *       store(message.topic, message.payload);
- *     }
- *
- * Environment: TINA4_MQTT_URL (default mqtt://127.0.0.1:1883),
- * TINA4_MQTT_CLIENT_ID, TINA4_MQTT_KEEPALIVE (seconds, default 60),
- * TINA4_MQTT_CA_FILE, TINA4_MQTT_TLS_VERIFY.
- *
- * Node has no synchronous blocking socket read, so connect()/publish()/
- * subscribe()/receive() are async and consume() is an async generator — the same
- * idiom as the Queue. No background task runs by default; opt in to the
- * cooperative keepalive with startKeepalive(), which registers a background()
- * task exactly like the queue consumers do.
- *
- * Single reader: like every MQTT client the socket has ONE network reader. Call
- * receive()/consume() from one place.
- */
 import { MqttMessage } from "./mqttMessage.js";
 /** Any MQTT protocol / connection failure. */
 export declare class MqttError extends Error {

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

@@ -0,0 +1,25 @@
+/**
+ * Optional peer packages: the database drivers and service clients an
+ * APPLICATION installs, never the framework (ADR-0067).
+ *
+ * tina4-nodejs installs as exactly one package. `pg`, `mongodb`, `redis` and
+ * the `@aws-sdk` S3 client are optional peerDependencies, which npm does not
+ * install, so for most apps "missing" is the normal state. Every feature that
+ * reaches for one must therefore fail at the point of use with the exact
+ * command that fixes it - never a bare MODULE_NOT_FOUND, never a silent no-op.
+ */
+/** The actionable "install it" error, one wording for every optional peer. */
+export declare function optionalPackageMissing(feature: string, packageNames: string[]): Error;
+/**
+ * Resolve an optional peer from the FRAMEWORK's location and return its module
+ * URL, or throw the actionable error. Synchronous, so a constructor can refuse
+ * immediately (parity with the Python master, which raises ImportError in the
+ * constructor) instead of leaving a rejected promise for later.
+ *
+ * Resolving from here rather than from process.cwd() is what finds the peer an
+ * app installed, wherever the server was started from.
+ *
+ * @param installTogether packages the feature needs as a set (S3 needs the
+ *   client AND the presigner), all named in the one install command.
+ */
+export declare function resolveOptionalPackage(packageName: string, feature: string, installTogether?: string[]): string;

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

@@ -1,13 +1,3 @@
-/**
- * Project plan management — persistent, human-readable task state.
- *
- * Ported from tina4_python/dev_admin/plan.py (master reference).
- * A plan is a markdown file under plan/ at the project root with sections
- * for title, goal, steps (checkboxes), and notes. Exactly one plan is
- * "current" at a time, recorded in plan/.current.
- *
- * Byte-for-byte compatible with Python's plan/*.md storage.
- */
 export interface PlanStep {
     text: string;
     done: boolean;

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

@@ -1,13 +1,3 @@
-/**
- * Project index — lightweight, persistent "where is what" map.
- *
- * Ported from tina4_python/dev_admin/project_index.py (master reference).
- *
- * Storage: .tina4/project_index.json at the project root.
- * Freshness: lazy-refreshes on read via mtime compare — no watchers.
- * Extractors: per-language symbol extraction (TS/JS, Twig/HTML, SQL, Markdown,
- * Python) using regex. No LLM involvement — pure static analysis.
- */
 export interface FileRoute {
     method: string;
     path: string;

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

@@ -42,6 +42,8 @@ export declare class MongoBackend implements QueueBackend {
     private collection;
     private visibilityTimeout;
     private maxRetries;
+    /** Module URL of the app-installed `mongodb` driver, resolved once. */
+    private driverUrl;
     constructor(config?: MongoConfig);
     /**
      * Resolved connection config — exposed for testing/introspection.

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

@@ -11,6 +11,18 @@ import type { Tina4Request, UploadedFile } from "./types.js";
  */
 export declare function makeCaseInsensitiveHeaders(raw: IncomingHttpHeaders): IncomingHttpHeaders;
 export declare function createRequest(req: IncomingMessage): Tina4Request;
+export declare const DEFAULT_MAX_UPLOAD_SIZE = 10485760;
+/**
+ * Read a numeric limit from the environment. A value that is not a usable
+ * number falls back to the default with a warning naming the variable (the
+ * same rule as PHP's Server::resolveLimit) - a typo must never be what
+ * disables a DoS guard.
+ */
+export declare function resolveLimit(name: string, fallback: number, zeroAllowed?: boolean): number;
+/** TINA4_MAX_UPLOAD_SIZE, read when it is needed so a value from .env counts. */
+export declare function maxUploadSize(): number;
+/** The one 413 wording (ADR-0068 section 4). */
+export declare function bodyTooLargeMessage(bytes: number | bigint | string, limit: number): string;
 export declare class PayloadTooLargeError extends Error {
     statusCode: number;
     constructor(actual: number, limit: number);

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

@@ -1,5 +1,18 @@
 import type { ServerResponse } from "node:http";
 import type { Tina4Response } from "./types.js";
+/**
+ * The caller's name as a JSON string literal with non-ASCII escaped, byte-
+ * identical to Python's json.dumps (ADR-0068), so a name that is itself broken
+ * cannot break the error message or the log line carrying it.
+ */
+export declare function quoteHeaderName(name: string): string;
+/**
+ * Refuse a response header whose name is not an HTTP token or whose value
+ * carries CR, LF or NUL, with the exact ADR-0068 wording. node:http refuses
+ * these too, but names a broken header raw (a CR/LF in the name reaches the
+ * log line) - this is the ADR's form, checked first.
+ */
+export declare function assertSafeHeader(name: string, value: unknown): void;
 /**
  * Set the default templates directory for render().
  * Called by server.ts during startup.

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

@@ -88,6 +88,25 @@ export declare function _checkLegacyEnvVars(): void;
  * of killing an innocent process.
  */
 export declare function killPort(port: number): void;
+/**
+ * Variables that mark a CI run, in ADR-0070's order (ci_env_vars). A run is CI
+ * when any of them holds a value that, trimmed and lower-cased, is non-empty
+ * and not in CI_NOT_SET_VALUES.
+ */
+export declare const CI_ENVIRONMENT_VARIABLES: string[];
+/** Values that say "not under CI" (ADR-0070 ci_not_set_values), compared trimmed and lower-cased. */
+export declare const CI_NOT_SET_VALUES: string[];
+/**
+ * Whether the server may open a browser (ADR-0070): only for a developer at a
+ * desk. Every rule is a veto; nothing forces a browser open past one.
+ *
+ *   1. development only - the caller's resolved debug mode, and never with
+ *      TINA4_PRODUCTION truthy or in a cluster worker (the primary decides);
+ *   2. never when TINA4_NO_BROWSER is truthy (true/1/yes/on);
+ *   3. never with --no-browser / a programmatic noBrowser (it can only veto);
+ *   4. never under CI.
+ */
+export declare function shouldOpenBrowser(isDevelopment: boolean, noBrowser?: boolean): boolean;
 /**
  * Resolve port and host with priority: explicit config > ENV var > default.
  * Exported for testability.

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

@@ -1,18 +1,3 @@
-/**
- * Tina4 session handlers — turn a failed `execFileSync` child into a readable cause.
- *
- * The session-handler interface is synchronous but every backend client is async,
- * so each command runs in a short-lived `node -e` child. When that child fails,
- * `execFileSync` throws an error whose `.message` begins "Command failed:" and
- * then embeds THE ENTIRE GENERATED SCRIPT — kilobytes of source with the real
- * reason nowhere in it. Every handler used to throw exactly that, so an
- * operator debugging a Redis outage got a wall of JavaScript instead of
- * "connect ECONNREFUSED 127.0.0.1:6379".
- *
- * The children already write the real reason to stderr; `execFileSync` captures
- * it on `err.stderr`. This module is the ONE place that prefers it, so the three
- * call sites (respClient, mongoClient, redisHandler's npm path) cannot drift.
- */
 /**
  * Extract the most useful one-line cause from a thrown `execFileSync` error.
  *

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

@@ -0,0 +1,28 @@
+import type { IncomingMessage, ServerResponse, Server } from "node:http";
+/**
+ * Answer through a ServerResponse with the rejection shape and close. Every
+ * header already on the response is dropped: the shape is exact. Node closes
+ * the connection once the answer is flushed (Connection: close), so the rest
+ * of a refused upload is never read.
+ */
+export declare function sendTransportRejection(res: ServerResponse, status: number, message: string, end?: {
+    (cb?: () => void): ServerResponse<IncomingMessage>;
+    (chunk: any, cb?: () => void): ServerResponse<IncomingMessage>;
+    (chunk: any, encoding: BufferEncoding, cb?: () => void): ServerResponse<IncomingMessage>;
+}): void;
+/**
+ * ADR-0068 section 2 for Node. node:http refuses an unsafe header where it is
+ * set (setHeader / appendHeader / writeHead). A header set straight on the raw
+ * response - past Tina4's own call-site check - used to surface as a route
+ * error page. Here the refusal is recorded instead, and whatever the handler
+ * sends next becomes the fixture's 500 {"error":"Invalid response header"},
+ * logged by header name. Tina4's own Response keeps refusing at the call site
+ * (its check runs before this layer is reached).
+ */
+export declare function guardUnsafeHeaders(res: ServerResponse): void;
+/**
+ * Create the HTTP server Tina4 listens with - the main port, its loopback
+ * siblings, the AI port and every cluster worker - so every one of them keeps
+ * the same limits and answers.
+ */
+export declare function createTina4HttpServer(handler: (req: IncomingMessage, res: ServerResponse) => unknown): Server;

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

@@ -1,19 +1,3 @@
-/**
- * Which upstream hops are allowed to speak for a client (ADR-0019).
- *
- * X-Forwarded-For is written by whoever sends it. Reading it unconditionally
- * lets any client choose its own rate-limit bucket, and - worse - choose
- * SOMEONE ELSE'S, which is a starvation primitive against a third party. So
- * the forwarding headers are believed only when the raw socket peer is a proxy
- * the operator has explicitly declared.
- *
- * Configured by TINA4_TRUSTED_PROXIES: comma-separated exact addresses and/or
- * CIDR ranges, IPv4 and IPv6, e.g. "10.0.0.0/8, 192.168.1.5, ::1, fd00::/8".
- * Empty or unset means trust NOTHING, which is the secure default.
- *
- * Zero-dependency: node: has no CIDR matcher, so the packing and prefix
- * comparison are done here over plain byte arrays.
- */
 /** [packed network address, prefix bits] */
 type Network = [Uint8Array, number];
 /**

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

@@ -198,6 +198,11 @@ export interface Tina4Config {
      *  and staticDir are resolved relative to this path instead of process.cwd(). */
     basePath?: string;
     routesDir?: string;
+    /**
+     * Never open a browser on start (ADR-0070 rule 3, the programmatic
+     * --no-browser). It can only veto: false does not force one open.
+     */
+    noBrowser?: boolean;
     modelsDir?: string;
     templatesDir?: string;
     staticDir?: string;

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

@@ -47,6 +47,7 @@ export declare class NATSBackplane implements WebSocketBackplane {
     private url;
     private subs;
     private ready;
+    private natsModuleUrl;
     constructor(url?: string);
     publish(channel: string, message: string): Promise<void>;
     subscribe(channel: string, callback: (message: string) => void): Promise<void>;

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

@@ -1,23 +1,3 @@
-/**
- * Tina4 WSDL/SOAP — SOAP 1.1 / WSDL 1.1 service base class.
- *
- * Auto-generates WSDL definitions and handles SOAP XML requests.
- * Zero external dependencies — uses simple string parsing for XML.
- *
- * Matches the PHP reference implementation (Tina4\WSDL).
- *
- *   import { WSDLService, WSDLOperation } from "@tina4/core";
- *
- *   class Calculator extends WSDLService {
- *     serviceName = "Calculator";
- *     serviceUrl = "/api/calculator";
- *
- *     @WSDLOperation({ output: { Result: "int" } })
- *     async Add(a: number, b: number): Promise<Record<string, unknown>> {
- *       return { Result: a + b };
- *     }
- *   }
- */
 export interface WSDLOperationMeta {
     name: string;
     description?: string;
@@ -34,8 +14,14 @@ interface WSDLOperationConfig {
  *
  *   @WSDLOperation({ description: "Add two numbers", input: { a: "int", b: "int" }, output: { Result: "int" } })
  *   async Add(a: number, b: number): Promise<Record<string, unknown>> { ... }
+ *
+ * Works under both decorator flavours: TC39 standard decorators (what tsx and
+ * esbuild compile by default: `(method, context)`) and TypeScript's
+ * experimentalDecorators (`(prototype, name, descriptor)`).
  */
-export declare function WSDLOperation(config?: WSDLOperationConfig): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function WSDLOperation(config?: WSDLOperationConfig): (target: unknown, context: string | symbol | {
+    name: string | symbol;
+}, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;
 export declare abstract class WSDLService {
     abstract serviceName: string;
     abstract serviceUrl: string;
@@ -72,7 +58,7 @@ export declare abstract class WSDLService {
     /**
      * Handle incoming SOAP request (parse XML, dispatch to method, return SOAP response).
      */
-    handle(soapXml?: string): Promise<string>;
+    handle(soapXml?: string | Uint8Array): Promise<string>;
     /**
      * Register this service's routes on a router.
      * GET /service-url?wsdl -> WSDL XML

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

@@ -241,7 +241,13 @@ export declare class Frond {
      */
     private applyFastFilter;
     private applyRenderedFilter;
-    private variablePermitted;
+    /**
+     * Sandbox gate for a WHOLE expression (F6/ADR-0077): refuse a dunder walk or
+     * a root variable outside the allow-list. Applied to output, if conditions,
+     * set right-hand sides and for iterables so none can smuggle a blocked
+     * variable past the per-output gate.
+     */
+    private sandboxExprOk;
     private resolveConcatenation;
     private applyRenderedFilters;
     private evalVarInner;

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

@@ -98,6 +98,12 @@ export declare class FirebirdAdapter implements DatabaseAdapter {
     /** Connect to Firebird. Must be called before using the adapter. */
     /** ADR-0044 required adapter capability. */
     getDatabaseType(): string;
+    /**
+     * Quote a name the ORM emits the way Firebird stores it: UPPER CASE (see
+     * fbQuote). An already-quoted name passes through - the escape hatch for a
+     * genuinely case-sensitive table. Python master: FirebirdAdapter.quote_identifier.
+     */
+    quoteIdentifier(name: string): string;
     /** ADR-0044: readable/writable native boolean. */
     autocommit: boolean;
     /**
@@ -186,6 +192,12 @@ export declare class FirebirdAdapter implements DatabaseAdapter {
         lastId?: number | bigint;
     }>;
     executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    /**
+     * Run a row-producing statement ONCE and return its rows, for
+     * Database.execute(). node-firebird's execute() returns no rows, so a SELECT
+     * or an `INSERT ... RETURNING` through execute() used to lose them.
+     */
+    executeRowsAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
     queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**

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

@@ -45,8 +45,19 @@ export declare class MssqlAdapter implements DatabaseAdapter {
      * `startAt` lets a caller that has already consumed N placeholders (an UPDATE
      * whose SET values are @p0..@p{N-1}) continue the numbering into a raw WHERE
      * fragment instead of restarting at @p0.
+     *
+     * Only REAL placeholders are rewritten: a `?` inside a string literal, a
+     * quoted identifier or a comment is left alone (tina4-python#138).
      */
     private convertPlaceholders;
+    /**
+     * The SQL the driver receives. With NO parameters it is sent EXACTLY as
+     * written (the cross-framework contract): there is nothing to bind.
+     *
+     * tina4: with parameters every `?` outside a literal, quoted identifier or
+     * comment is a placeholder.
+     */
+    private bindable;
     execute(sql: string, params?: unknown[]): unknown;
     executeMany(sql: string, paramsList: unknown[][]): {
         totalAffected: number;

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

@@ -23,6 +23,8 @@ export declare class MysqlAdapter implements DatabaseAdapter {
     /** Connect to MySQL. Must be called before using the adapter. */
     /** ADR-0044 required adapter capability. */
     getDatabaseType(): string;
+    /** MySQL identifiers are backtick-quoted; a double-quoted token is a string. */
+    quoteIdentifier(name: string): string;
     /** ADR-0044: readable/writable native boolean. */
     autocommit: boolean;
     /**

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

@@ -38,6 +38,17 @@ export declare class PostgresAdapter implements DatabaseAdapter {
     /** Ensure bytea columns are Buffer (already the case with pg). No-op guard. */
     private decodeBlobs;
     private convertPlaceholders;
+    /**
+     * The SQL the driver receives. With NO parameters it is sent EXACTLY as
+     * written (the cross-framework contract): there is nothing to bind, and the
+     * rewrite would turn PostgreSQL's jsonb operators `?`, `?|` and `?&` into
+     * unbound markers.
+     *
+     * tina4: with parameters every `?` outside a literal, quoted identifier or
+     * comment is a placeholder - use jsonb_exists(), jsonb_exists_any() or
+     * jsonb_exists_all() instead of the `?`, `?|` or `?&` operators.
+     */
+    private bindable;
     /**
      * Normalise an `id` column value (typed `unknown` because pg row values are
      * `unknown`) into the shape `_lastInsertId` / `DatabaseResult.lastId`

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

@@ -29,6 +29,21 @@ export interface Dialect {
      */
     marker(index: number): string;
 }
+/**
+ * Quote a table/column name the ORM emits, in one engine's identifier quotes.
+ *
+ * Port of the Python master's `quote_identifier` (adapter.py; Firebird's
+ * override upper-cases): idempotent (an already-quoted name is returned
+ * unchanged), dot-aware (`schema.table` quotes each part), and a non-identifier
+ * (`*`, `COUNT(*)`, an expression) is passed through untouched. An embedded
+ * closing quote is doubled.
+ *
+ * `upperCase` is Firebird's rule: an unquoted identifier is stored UPPER CASE,
+ * so a lower-case name must be quoted upper-case to match it.
+ */
+export declare function quoteIdentifierWith(name: string, open: string, close: string, upperCase?: boolean): string;
+/** The ANSI default: `"name"` (SQLite, PostgreSQL, MSSQL, ODBC). */
+export declare function quoteIdentifierAnsi(name: string): string;
 /** SQLite, and ODBC which follows the SQL standard spelling. */
 export declare const ANSI_DIALECT: Dialect;
 /** PostgreSQL: standard quoting, positional $N markers. */
@@ -43,6 +58,16 @@ export declare const MSSQL_DIALECT: Dialect;
  * adapter owns that rule and passes its own quoter in.
  */
 export declare function firebirdDialect(fbQuote: (name: string) => string): Dialect;
+/**
+ * Refuse a data or filter-map key that is not a plain identifier.
+ *
+ * tina4: ADR-0069 (G3) - the write helpers emit these keys as column names, and
+ * the dialect quoters do not escape, so a key must be a plain identifier
+ * (letters, digits, underscore, dollar; not starting with a digit) before any
+ * SQL is built. Valid names are emitted exactly as before. Table names are
+ * developer code and are not checked here.
+ */
+export declare function assertColumnNames(keys: Iterable<string>): void;
 /**
  * `INSERT INTO <table> (<cols>) VALUES (<markers>)`.
  *

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

@@ -36,6 +36,13 @@ export declare class SQLiteAdapter implements DatabaseAdapter {
     execute(sql: string, params?: unknown[]): unknown;
     executeMany(sql: string, paramsList: unknown[][]): DatabaseResult;
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /**
+     * Run a row-producing statement ONCE and return its rows, for
+     * Database.execute(). execute()'s run() discards rows, so a SELECT or an
+     * `INSERT ... RETURNING` through execute() used to lose them. A write still
+     * records its last insert id, exactly as execute() does.
+     */
+    executeRows<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;
     insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;

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

@@ -112,6 +112,11 @@ export declare class BaseModel {
      * SQLite URLs are initialised synchronously. Other engines require initDatabase()
      * to be called before first use.
      */
+    /**
+     * Quote a table/column name in the dialect of the adapter this model runs on
+     * (MySQL backticks, Firebird upper-cased, `"name"` elsewhere).
+     */
+    protected static quoteName(name: string): string;
     protected static getDb(): DatabaseAdapter;
     /**
      * Get the primary key field name (JS property name).

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

@@ -144,10 +144,31 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     private backendSetRows;
     private backendGetOne;
     private backendSetOne;
+    /**
+     * A write that arrives through a READ method (fetch/fetchOne/query of an
+     * `INSERT ... RETURNING`) is still a write: its result must never be cached
+     * (a repeat would answer from the cache and never insert) and it flushes the
+     * cache like every other write (tina4-python#133 contract).
+     */
+    private isWriteRead;
+    /** Run a write that came through a read method, then flush (never store). */
+    private runWrite;
+    private runWriteAsync;
     /** ADR-0044 required capability — delegates to the wrapped adapter. */
     connect(): void | Promise<void>;
+    /**
+     * The derived-table alias the COUNT probe needs, forwarded from the wrapped
+     * adapter. SQL Server and MySQL REQUIRE `FROM (<sql>) AS _count_query`; the
+     * probe reads this property off whatever adapter it is handed, and
+     * Database.create() hands it THIS wrapper. Without the forward the probe ran
+     * unaliased, the engine rejected it, the error was swallowed, and
+     * `result.count` silently became the page length on those two engines.
+     */
+    get countSubqueryAlias(): string | undefined;
     /** ADR-0044 required capability — delegates to the wrapped adapter. */
     getDatabaseType(): string;
+    /** Identifier quoting is the wrapped engine's, never the wrapper's. */
+    quoteIdentifier(name: string): string;
     /**
      * ADR-0044 required capability — a native boolean, readable and writable.
      * A getter/setter pair (not a plain field) so it genuinely delegates to the
@@ -158,6 +179,12 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     get supportsAtomicBatch(): boolean;
     set supportsAtomicBatch(value: boolean);
     execute(sql: string, params?: unknown[]): unknown;
+    /**
+     * Forward an adapter's row-returning execute (SQLite, Firebird), for
+     * Database.execute(). Resolves `undefined` when the wrapped adapter has none
+     * - WITHOUT running anything - so the caller falls back to execute().
+     */
+    executeRowsAsync(sql: string, params?: unknown[]): Promise<unknown[] | undefined>;
     executeMany(sql: string, paramsList: unknown[][]): import("./types.js").DatabaseResult | {
         totalAffected: number;
         lastId?: number | bigint;

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

@@ -28,8 +28,27 @@ export declare function stripTrailingSemicolons(sql: string): string;
  * the single chokepoint every public read/write flows through.
  */
 export declare function adapterFetch<T = Record<string, unknown>>(adapter: DatabaseAdapter, sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): Promise<T[]>;
+/**
+ * Quote a table/column name the ORM emits, in the bound adapter's dialect
+ * (MySQL backticks, Firebird upper-cased, `"name"` elsewhere). Python master:
+ * `Database.quote_identifier`. Only for framework-emitted identifiers - a
+ * user's raw SQL is never rewritten.
+ */
+export declare function quoteIdentifier(adapter: DatabaseAdapter | null | undefined, name: string): string;
 export declare function adapterQuery<T = Record<string, unknown>>(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<T[]>;
 export declare function adapterFetchOne<T = Record<string, unknown>>(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<T | null>;
+/**
+ * Run a row-producing statement through an adapter's own row-returning execute
+ * (SQLite's executeRows, Firebird's executeRowsAsync, or the cache wrapper
+ * forwarding either). `undefined` means the adapter has none and NOTHING ran.
+ */
+export declare function adapterExecuteRows(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<unknown[] | undefined>;
+/**
+ * The rows inside a driver's execute() result: pg and tedious carry `.rows`,
+ * mysql2 and odbc return the row array itself, and a MySQL CALL returns
+ * `[[rows], OkPacket]`. `undefined` when the result carries no row list.
+ */
+export declare function rowsFromExecuteResult(result: unknown): unknown[] | undefined;
 export declare function adapterExecute(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<unknown>;
 /**
  * ADR-0044: the adapter-level batch primitive, called exactly once by
@@ -277,6 +296,11 @@ export declare class Database {
      * the same Database don't clobber each other. startTransaction() sets the
      * pin via .enterWith(); commit()/rollback() clear it.
      */
+    private leases;
+    private discardedSlots;
+    private repairs;
+    private leaseOwner;
+    private operationStore;
     private txStore;
     /**
      * Create a Database wrapping an existing adapter.
@@ -317,8 +341,13 @@ export declare class Database {
      * that adapter is returned for every call so the whole transaction is
      * atomic on one connection. Otherwise pooled mode round-robins.
      */
+    private availableAdapter;
+    private reserveAdapter;
+    private releaseAdapter;
+    private repairDiscardedConnections;
+    private withConnectionOperation;
     private getNextAdapter;
-    /** Get the underlying adapter (for advanced / escape-hatch usage). */
+    /** Non-owning peek excluding leased connections. Use checkout/checkin for concurrent raw driver work. */
     getAdapter(): DatabaseAdapter;
     /** Get the pool size (0 = single connection mode). */
     poolSize(): number;
@@ -331,12 +360,8 @@ export declare class Database {
      * The caller is responsible for returning it via checkin().
      */
     checkout(): DatabaseAdapter;
-    /**
-     * Return a borrowed connection to the pool.
-     * For round-robin pools this is a no-op (connections stay in the pool array),
-     * but the method exists for API parity and future pooling strategies.
-     */
-    checkin(_adapter: DatabaseAdapter): void;
+    /** Only the borrowing async context can release an explicit lease. */
+    checkin(adapter: DatabaseAdapter): void;
     /**
      * Close all pooled connections and clear the pool.
      * Equivalent to close() but named for explicit pool teardown.
@@ -405,6 +430,12 @@ export declare class Database {
     fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: {
         noCache?: boolean;
     }): Promise<T[]>;
+    /**
+     * Close a write that ran through fetch()/fetchOne() the way execute() closes
+     * its own: auto-commit outside an explicit transaction, and leave it to the
+     * caller's commit()/rollback() inside one.
+     */
+    private commitFetchWrite;
     /**
      * Execute a write statement.
      *
@@ -459,6 +490,14 @@ export declare class Database {
      * throws rather than silently changing nothing (audit feature 4, P1).
      */
     update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseWriteResult>;
+    /**
+     * ADR-0069 (G3): a data or filter-map key must be a plain identifier - it is
+     * emitted as a column name. Checked here, before any adapter work, so every
+     * engine raises the same error; the SQL builders (sqlDialect) check again for
+     * callers that use an adapter directly. MongoDB builds no SQL and its keys are
+     * document paths, so it is left alone.
+     */
+    private assertWriteKeys;
     /** Delete rows. A filterless delete throws; use truncate() to empty a table. */
     delete(table: string, filter?: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseWriteResult>;
     /** Remove every row. The explicit spelling of a whole-table delete. */

package/types/orm/src/graph/graphUrl.d.ts

@@ -1,11 +1,3 @@
-/**
- * Graph connection URL parser — the DatabaseUrl sibling for graph engines.
- *
- * Parse a graph connection URL into its parts, the same way DatabaseUrl does for
- * SQL. `engine` is the CANONICAL name the factory selects an adapter by; a scheme
- * alias (bolt/neo4j/memgraph all speak Bolt/Cypher and share ONE adapter) resolves
- * to its engine here. See tina4-documentation/plan/v3/features/139-graph-databases.md.
- */
 /** The canonical graph engine names. */
 export type GraphEngine = "ultipa" | "bolt" | "arango";
 /** A parsed graph URL: engine, host, port, graph, credentials, params. */

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

@@ -15,7 +15,7 @@ export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, rec
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
 export type { AutoCrudOptions } from "./autoCrud.js";
-export { buildQuery, parseQueryString } from "./query.js";
+export { buildQuery, parseQueryString, UnknownFieldError, InvalidQueryParameterError } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";