tina4-nodejs 3.13.98 → 3.13.100

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.
      */

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

@@ -144,8 +144,21 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     private backendSetRows;
     private backendGetOne;
     private backendSetOne;
+    /** ADR-0044 required capability — delegates to the wrapped adapter. */
+    connect(): void | Promise<void>;
+    /** ADR-0044 required capability — delegates to the wrapped adapter. */
+    getDatabaseType(): 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
+     * wrapped adapter rather than drifting out of sync with its real setting.
+     */
+    get autocommit(): boolean;
+    set autocommit(value: boolean);
+    get supportsAtomicBatch(): boolean;
+    set supportsAtomicBatch(value: boolean);
     execute(sql: string, params?: unknown[]): unknown;
-    executeMany(sql: string, paramsList: unknown[][]): {
+    executeMany(sql: string, paramsList: unknown[][]): import("./types.js").DatabaseResult | {
         totalAffected: number;
         lastId?: number | bigint;
     };
@@ -173,6 +186,19 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): Promise<T | null>;
     queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    /**
+     * ADR-0044: the async passthrough executeMany() itself was missing (unlike
+     * its executeAsync/insertAsync siblings above), so adapterExecuteMany()'s
+     * `(adapter as any).executeManyAsync` check found nothing on THIS wrapper
+     * and fell through to the synchronous executeMany() below — which forwards
+     * to the wrapped adapter's OWN sync executeMany(), the throwing "Use
+     * executeManyAsync()" stub on every async-native adapter (Postgres/MySQL/
+     * MSSQL/Firebird/Mongo). Real bug, caught by executeManyFacadeTxn.test.ts.
+     */
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<import("./types.js").DatabaseResult | {
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
     insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
     updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
     deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult>;

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

@@ -31,6 +31,32 @@ export declare function adapterFetch<T = Record<string, unknown>>(adapter: Datab
 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>;
 export declare function adapterExecute(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<unknown>;
+/**
+ * ADR-0044: the adapter-level batch primitive, called exactly once by
+ * Database#executeMany (never looped) — one aggregate DatabaseResult for the
+ * whole batch. Normalises whichever native shape an adapter returns: SQLite's
+ * `{success, affectedRows, lastId}` (the shared write shape already used by
+ * insert/update/delete) or an async-native adapter's `{totalAffected, lastId}`
+ * (pre-ADR-0044 shape, not yet unified per-adapter — normalised HERE at the
+ * one chokepoint every public write flows through, so the facade's contract
+ * is uniform without touching each of the five adapter files' internals).
+ */
+export declare function adapterExecuteMany(adapter: DatabaseAdapter, sql: string, paramsList: unknown[][]): Promise<import("./types.js").DatabaseResult>;
+/**
+ * Insert one row (or a batch) through the adapter's OWN native insert path
+ * (each adapter's `buildInsert()`/`Dialect`, feature 3's SQL builder
+ * consolidation) instead of hand-built SQL. This is the ONLY correct way to
+ * insert into a caller-named table/columns: Firebird's Dialect quotes only
+ * when it has to (an unquoted identifier folds to UPPERCASE, so quoting a
+ * lower-case name makes it unfindable — SQL error -204 "Table unknown"),
+ * while PostgreSQL/MSSQL/SQLite quote unconditionally. A caller that hand-
+ * quotes with one fixed style (e.g. always `"col"`) works on three engines
+ * and silently breaks on the fourth. seedTable()/seedOrm() route through
+ * this so their engine portability matches insert()/insertAsync()'s, which
+ * the write-path + provider contract suites already prove on all four real
+ * engines (features 9/10/11/12).
+ */
+export declare function adapterInsert(adapter: DatabaseAdapter, table: string, data: Record<string, unknown>): Promise<unknown>;
 export declare function adapterStartTransaction(adapter: DatabaseAdapter): Promise<void>;
 export declare function adapterCommit(adapter: DatabaseAdapter): Promise<void>;
 export declare function adapterRollback(adapter: DatabaseAdapter): Promise<void>;
@@ -394,7 +420,19 @@ export declare class Database {
      * `try/catch` and convert, rather than testing the return value.
      */
     execute(sql: string, params?: unknown[]): Promise<boolean | unknown>;
-    /** Insert one row (object) or a batch of rows (array of objects) into a table. */
+    /**
+     * Insert one row (object) or a batch of rows (array of objects) into a table.
+     *
+     * FAIL LOUD, matching update()/delete()/truncate(): a real driver failure
+     * (e.g. a NOT NULL / UNIQUE constraint violation) throws rather than
+     * resolving to `{ success: false, affectedRows: 0 }`. The async adapters
+     * (Postgres/MySQL/MSSQL/Firebird) already throw directly from insertAsync();
+     * SQLiteAdapter.insert() is the one adapter that CATCHES the driver error
+     * and returns a `{ success: false, error }` result instead (its own
+     * documented contract for the synchronous path) — assertWrote is what
+     * converts that into the same thrown DatabaseException every other engine
+     * already produces, exactly as it already does for update/delete/truncate.
+     */
     insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseWriteResult>;
     /**
      * The table's primary-key column, introspected once and cached.
@@ -487,16 +525,28 @@ export declare class Database {
         nullable?: boolean;
         default?: unknown;
         primaryKey?: boolean;
+        primaryKeyPosition?: number | null;
     }[]>;
     /**
-     * Execute a SQL statement with multiple parameter sets (batch insert/update).
-     * Wraps all executions in a single transaction for atomicity and performance.
+     * Execute a SQL statement with multiple parameter sets as ONE aggregate
+     * batch (ADR-0044). Wraps the single delegated call in a transaction for
+     * atomicity — never loops #execute itself.
+     *
+     * BREAKING (ADR-0044, pre-3.14.0): used to return one result PER ROW
+     * (`unknown[]`, callers indexed into it) built by the FACADE looping
+     * execute()/adapterExecute() per chunk or per row. It now delegates to the
+     * adapter's OWN executeMany/executeManyAsync exactly once (DBA-D02: facade
+     * delegates once, never a facade row loop) and returns the SAME shared
+     * DatabaseResult shape insert()/update()/delete() already return
+     * ({success, affectedRows, lastId}) — affectedRows is the total ROW count,
+     * never the number of chunks/statements. A caller that indexed into the old
+     * per-row array must switch to inspecting the aggregate result.
      *
      * @param sql - The SQL statement with parameter placeholders.
-     * @param paramSets - Array of parameter arrays, one per execution.
-     * @returns Array of results from each execution.
+     * @param paramSets - Array of parameter arrays, one per row.
+     * @returns The aggregate DatabaseResult for the whole batch.
      */
-    executeMany(sql: string, paramSets?: unknown[][]): Promise<unknown[]>;
+    executeMany(sql: string, paramSets?: unknown[][]): Promise<DatabaseWriteResult>;
     /** Return the last execute() error message, or null. */
     getError(): string | null;
     /**

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

@@ -1,14 +1,15 @@
 export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, QueryOptions, RelationshipDefinition, } from "./types.js";
+export { REQUIRED_ADAPTER_CAPABILITIES, NOT_REQUIRED_ON_ADAPTER } from "./types.js";
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
 export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
-export { adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterStartTransaction, adapterCommit, adapterRollback, adapterTableExists, adapterTables, adapterColumns, adapterCreateTable, extractLastInsertId, } from "./database.js";
+export { adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterInsert, adapterStartTransaction, adapterCommit, adapterRollback, adapterTableExists, adapterTables, adapterColumns, adapterCreateTable, extractLastInsertId, } from "./database.js";
 export type { DatabaseConfig } from "./database.js";
 export { DatabaseUrl, redactCredentials } from "./databaseUrl.js";
 export type { DatabaseEngine } from "./databaseUrl.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";
-export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, recordMigration, applyMigration, rollback, getAppliedMigrations, getLastBatchMigrations, removeMigrationRecord, migrate, createMigration, status, Migration, splitStatements, parseSetTerm, normalizeQuotes, sortMigrationFiles, shouldSkipCreateTable, } from "./migration.js";
+export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, recordMigration, applyMigration, rollback, getAppliedMigrations, getLastBatchMigrations, removeMigrationRecord, migrate, createMigration, status, Migration, splitStatements, parseSetTerm, normalizeQuotes, sortMigrationFiles, shouldSkipCreateTable, shouldSkipForFirebird, } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
 export type { AutoCrudOptions } from "./autoCrud.js";

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

@@ -1,5 +1,14 @@
 import type { DatabaseAdapter } from "./types.js";
 import type { DiscoveredModel } from "./model.js";
+/**
+ * If stmt is an ALTER TABLE ... ADD on Firebird and the column already exists,
+ * returns a skip reason string. Returns null if the statement should execute normally.
+ *
+ * Exported (like its shouldSkipCreateTable sibling) so it can be driven
+ * directly against a REAL Firebird connection in
+ * test/migrationContract.test.ts -- no fake adapter needed.
+ */
+export declare function shouldSkipForFirebird(db: DatabaseAdapter, stmt: string): Promise<string | null>;
 /**
  * Make CREATE TABLE idempotent on engines lacking IF NOT EXISTS.
  *
@@ -53,17 +62,26 @@ export declare function removeMigrationRecord(name: string): Promise<void>;
 /**
  * Rollback the last batch of migrations using .down.sql files.
  *
- * For each migration in the last batch (in reverse order):
- * 1. Looks for a corresponding .down.sql file on disk
- * 2. If found, reads and executes the SQL statements
- * 3. If not found, logs a warning
- * 4. Deletes the tracking record either way
+ * FAIL-SAFE (MIG-DEC-02, reuses the Python reference model): for each
+ * migration in the last batch (in reverse order), the down artifact must
+ * actually run before the tracking record is removed. A MISSING .down.sql
+ * (or, on the legacy Map API, no registered down function) or a FAILING down
+ * statement now THROWS instead of logging a warning/error and still deleting
+ * the record — the old behaviour was the exact MIG-ROLLBACK-DROPS-LEDGER bug:
+ * the schema stayed applied but the ledger row vanished, silently untracked.
+ * The DELETE runs inside the SAME transaction as the down statements, so a
+ * partially-executed down (some statements ran, a later one failed) rolls
+ * back too — no half-reversed schema left behind either.
  *
  * @param migrationsDir - Directory containing migration files (default: "migrations")
  * @param delimiter - SQL statement delimiter (default: ";")
  * @returns Array of the down-migration files that were run, e.g.
  *   "000001_create_users.down.sql". (The legacy down-FUNCTION Map API returns the
  *   bare migration name instead, since no .down.sql file is involved there.)
+ * @throws When a migration in the batch has no down artifact, or its down
+ *   statement(s) fail — the batch stops at that migration; earlier
+ *   migrations in the SAME call that already rolled back stay rolled back
+ *   (each is its own transaction).
  *
  * NOTE on return form (intentional, cross-framework): migration return values reflect
  * WHAT each method acted on, so the forms differ by method and that is by design (not

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

@@ -10,5 +10,8 @@ export declare function buildQuery(tableName: string, options: QueryOptions, ext
     sql: string;
     countSql: string;
     params: unknown[];
+    limit: number;
+    offset: number;
+    page: number;
 };
 export declare function parseQueryString(query: Record<string, string>): QueryOptions;

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

@@ -21,7 +21,18 @@ export interface SeedOptions {
     overrides?: Record<string, unknown>;
     /** Delete every existing row in the target before seeding (P2). */
     clear?: boolean;
-    /** PRNG seed for reproducible FakeData output (P3). */
+    /**
+     * PRNG seed for reproducible FakeData output (P3). Honoured by seedOrm and
+     * seedModels, which build and seed their own FakeData internally.
+     *
+     * NOT honoured by seedTable (SEED-TABLE-SEED-INERT, SEED-DEC-01, ratified
+     * 2026-08-11 — same principle as the no-op ForeignKeyField on_delete):
+     * seedTable has no generators of its own to seed — fieldMap callables are
+     * opaque — so this used to be a silent no-op there. Passing it to seedTable
+     * now THROWS instead. Build your own `new FakeData(seed)` and close over it
+     * in fieldMap: `const fake = new FakeData(42); seedTable(db, table, count,
+     * { name: () => fake.name() })`.
+     */
     seed?: number;
     /** Re-raise on the first failed row instead of skipping it (P1). */
     strict?: boolean;
@@ -63,8 +74,10 @@ export declare function autoFieldMap(db: DatabaseAdapter, table: string, fake?:
  *                   (or a static value). If not provided, no rows are inserted.
  * @param overrides - (legacy positional) Static values applied to every row.
  *                   Prefer `opts.overrides`.
- * @param opts - Seed options: `{ overrides, clear, seed, strict }`.
+ * @param opts - Seed options: `{ overrides, clear, strict }`. `opts.seed` is
+ *   NOT honoured here (see {@link SeedOptions.seed}) and throws if supplied.
  * @returns A SeedSummary `{ seeded, failed, errors }`.
+ * @throws {Error} If `opts.seed` is defined (SEED-TABLE-SEED-INERT removal).
  *
  * @example
  *   const fake = new FakeData();

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

@@ -31,18 +31,31 @@ export declare class SQLTranslator {
      * Does NOT convert if OFFSET is present (TOP doesn't support it).
      */
     static limitToTop(sql: string): string;
+    /** Replace string literals, quoted identifiers and comments with opaque
+     * `\x00N\x00` tokens (doubled-quote escapes handled). */
+    private static maskLiterals;
+    /** Inverse of maskLiterals. */
+    private static restoreLiterals;
+    private static readonly PRIMARY;
     /**
-     * Convert || concatenation to CONCAT() for MySQL/MSSQL.
+     * Convert `||` string concatenation to `CONCAT(...)` for MySQL/MSSQL.
      *
-     * 'a' || 'b' || 'c'  →  CONCAT('a', 'b', 'c')
+     * Rewrites ONLY `||` operators joining expression operands OUTSIDE any string
+     * literal or comment, and only the operand chain — never the whole statement:
+     *   SELECT a || b FROM t   ->  SELECT CONCAT(a, b) FROM t
+     *   WHERE data = 'a||b'    ->  WHERE data = 'a||b'   (literal untouched)
      */
     static concatPipesToFunc(sql: string): string;
     /**
-     * Convert TRUE/FALSE to 1/0 for engines without boolean type (Firebird).
+     * Convert bare TRUE/FALSE to 1/0 for engines without a boolean type. A
+     * TRUE/FALSE INSIDE a string literal is data and is left untouched
+     * (`WHERE label = 'TRUE'` is preserved).
      */
     static booleanToInt(sql: string): string;
     /**
-     * Convert ILIKE to LOWER() LIKE LOWER() for engines without ILIKE.
+     * Convert `col ILIKE pattern` to `LOWER(col) LIKE LOWER(pattern)` for engines
+     * without ILIKE. The pattern operand is captured whole (a multi-word
+     * `'%two words%'` survives) and an ILIKE INSIDE a string literal is untouched.
      */
     static ilikeToLike(sql: string): string;
     /**

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

@@ -1,4 +1,4 @@
-export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
+export type FieldType = "string" | "integer" | "number" | "numeric" | "decimal" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
 export interface FieldDefinition {
     type: FieldType;
     primaryKey?: boolean;
@@ -10,6 +10,15 @@ export interface FieldDefinition {
     min?: number;
     max?: number;
     pattern?: string;
+    /**
+     * For type "decimal": the fixed precision/scale of a real DECIMAL(p, s)
+     * column. `number`/`numeric` stay a floating type (the documented money
+     * guidance); a `decimal` field keeps the declared scale in the COLUMN, so
+     * createTable emits DECIMAL(precision, scale) — identical on
+     * PostgreSQL/MySQL/MSSQL/Firebird/SQLite. Default 10 / 2 when omitted.
+     */
+    precision?: number;
+    scale?: number;
     /** For type "foreignKey": the referenced model name (string) */
     references?: string;
     /** For type "foreignKey": override the has-many property name on the referenced model */
@@ -50,6 +59,12 @@ export interface ColumnInfo {
     nullable?: boolean;
     default?: unknown;
     primaryKey?: boolean;
+    /**
+     * ADR-0044 amendment (Feature 5 Decision 7, 2026-08-10): null for a
+     * non-key column; for a composite key this is the 1-based DECLARED
+     * PRIMARY KEY (...) order, not table-column order.
+     */
+    primaryKeyPosition?: number | null;
 }
 export interface DatabaseResult {
     success: boolean;
@@ -57,44 +72,88 @@ export interface DatabaseResult {
     lastId?: number | bigint | string;
     error?: string;
 }
+/**
+ * ADR-0044 (feature 3, plan/v3/fixtures/adapter_contract.json): the exact
+ * fourteen adapter capabilities every DatabaseAdapter implementation must
+ * provide (DBA-S01). Kept as data so the conformance suite can check it
+ * without a second hand-maintained copy of the list.
+ */
+export declare const REQUIRED_ADAPTER_CAPABILITIES: readonly ["connect", "close", "getDatabaseType", "execute", "executeMany", "fetch", "fetchOne", "startTransaction", "commit", "rollback", "autocommit", "getTables", "getColumns", "tableExists"];
+/**
+ * ADR-0044 NOT_REQUIRED_ON_ADAPTER (DBA-S03): engine-neutral composition that
+ * the adapter CONTRACT does not require. Node keeps these as REQUIRED
+ * TypeScript interface members anyway (unlike Python/PHP/Ruby's stricter
+ * runtime reflection) because `database.ts`/`cachedDatabase.ts` call them
+ * directly at dozens of sites with no optional-chaining guard, so making them
+ * TS-optional ripples into a much larger refactor than this pass covers;
+ * this constant records the ADR's INTENT for the conformance suite to check
+ * even though the compiler will not enforce their absence.
+ */
+export declare const NOT_REQUIRED_ON_ADAPTER: readonly ["query", "insert", "update", "delete", "truncate", "fetchAll", "createTable", "addColumn", "lastInsertId", "error", "sqlTranslation"];
 export interface DatabaseAdapter {
+    /** Connect (ADR-0044 canonical lifecycle name). May be sync or async. */
+    connect(): void | Promise<void>;
+    /** Return the canonical, credential-free engine name ("sqlite", "postgres", ...). */
+    getDatabaseType(): string;
     /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
     execute(sql: string, params?: unknown[]): unknown;
-    /** Execute a single SQL statement with multiple parameter sets (batch). */
-    executeMany(sql: string, paramsList: unknown[][]): {
+    /**
+     * Execute a single SQL statement with multiple parameter sets as ONE
+     * aggregate result (ADR-0044). The shared write shape `DatabaseResult`
+     * ({success, affectedRows, lastId?}) is the target; the pre-ADR-0044 async
+     * adapters (Postgres/MySQL/MSSQL/Firebird/Mongo) still return their
+     * original `{totalAffected, lastId?}` shape internally today — the union
+     * covers both while `adapterExecuteMany()` in database.ts normalises
+     * whichever shape it receives at the one chokepoint every public batch
+     * write flows through.
+     */
+    executeMany(sql: string, paramsList: unknown[][]): DatabaseResult | {
         totalAffected: number;
         lastId?: number | bigint;
     };
-    /** Query rows. */
-    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
-    /** Fetch rows with optional pagination (limit/skip). */
+    /** Fetch rows with optional pagination (limit/skip). Native list, no envelope. */
     fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
-    /** Fetch a single row or null. */
+    /** Fetch a single row or null. No pagination count probe. */
     fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
-    /** Insert one or more rows into a table, returns result with lastId. */
-    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
-    /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
-    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
-    /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
-    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
     /** Start a transaction. */
     startTransaction(): void;
     /** Commit the current transaction. */
     commit(): void;
     /** Rollback the current transaction. */
     rollback(): void;
+    /**
+     * Native boolean, readable and writable. A plain field is the idiomatic JS
+     * shape for "readable and writable" — no getter/setter ceremony needed.
+     */
+    autocommit: boolean;
+    /**
+     * ADR-0044 / DBA-P02: whether this adapter's deployment can guarantee an
+     * atomic multi-row batch write. Every built-in adapter defaults true (see
+     * each adapter's field initializer); a deployment that genuinely 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;
     /** List all tables in the database. */
     getTables(): string[];
     /** List columns with types for a table. */
     getColumns(table: string): ColumnInfo[];
-    /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
-    lastInsertId(): number | bigint | string | null;
     /** Close the connection. */
     close(): void;
     /** Check if a table exists. */
     tableExists(name: string): boolean;
-    /** Create a table from field definitions. */
+    /** Insert one or more rows into a table, returns result with lastId. */
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
+    /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
+    /** Query rows (legacy convenience, superseded by fetch). */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /** Create a table from field definitions (legacy, DDL composition lives above the adapter). */
     createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    /** Get the last inserted id (legacy — prefer DatabaseResult.lastId from execute/executeMany). */
+    lastInsertId(): number | bigint | string | null;
     /** Get raw column info (legacy, used by migration). */
     getTableColumns?(name: string): Array<{
         name: string;