@orkestrel/database 0.0.6 → 0.0.8

package/dist/src/server/index.d.ts

@@ -1,116 +1,155 @@
-import { AggregateFunction } from '../core/index.ts';
-import { AggregateFunction as AggregateFunction_2 } from '../../core/index.ts';
-import { ColumnType } from '../core/index.ts';
+import { AggregateOperation } from '../core/index.ts';
+import { AggregateOperation as AggregateOperation_2 } from '../../core/index.ts';
+import { ColumnSchema } from '../core/index.ts';
+import { ColumnStorage } from '../core/index.ts';
 import { Condition } from '../core/index.ts';
-import { Criteria } from '../core/index.ts';
-import { Criteria as Criteria_2 } from '../../core/index.ts';
 import { DriverInterface } from '../core/index.ts';
 import { DriverInterface as DriverInterface_2 } from '../../core/index.ts';
-import { DriverMeta } from '../../core/index.ts';
+import { DriverMetadata } from '../../core/index.ts';
 import { FieldPath } from '@orkestrel/contract';
 import { Key } from '../../core/index.ts';
-import { Migration } from '../../core/index.ts';
+import { MigrationInput } from '../../core/index.ts';
 import { MigrationStep } from '../core/index.ts';
+import { OperationOptions } from '../../core/index.ts';
 import { Order } from '../core/index.ts';
+import { QueryInput } from '../core/index.ts';
+import { QueryInput as QueryInput_2 } from '../../core/index.ts';
 import { Row } from '../core/index.ts';
 import { Row as Row_2 } from '../../core/index.ts';
+import { SQLiteRow } from '@orkestrel/sqlite';
+import { SQLiteValue } from '@orkestrel/sqlite';
+import { StorageInterface } from '../../core/index.ts';
 import { TableSchema } from '../core/index.ts';
 import { TableSchema as TableSchema_2 } from '../../core/index.ts';
-import { TransactionInterface } from '../../core/index.ts';
 
 /**
- * Compile an {@link AggregateFunction} over a {@link FieldPath} to its SQL
- * aggregate expression — the SELECT body the SQLite driver's native `aggregate`
- * runs.
- *
- * @remarks
- * `count` → `COUNT(*)` (counting all matched ROWS, not non-null column values —
- * mirroring the engine's `computeAggregate('count')`, which is `rows.length`); the
- * numeric aggregates wrap the column's read expression (a flat column, or a nested
- * `json_extract` path) in `SUM` / `AVG` / `MIN` / `MAX`. Over zero matched rows
- * `COUNT(*)` is `0` and the numeric aggregates are SQL `NULL` (→ `undefined`),
- * matching the engine.
+ * Compile an {@link AggregateOperation} over a {@link FieldPath}.
  *
  * @param operation - The aggregate to compute
- * @param column - The column (or nested path) to aggregate
+ * @param column - The column or nested path to aggregate
  * @returns The SQL aggregate expression
- *
- * @example
- * ```ts
- * aggregateSQL('count', 'age') // 'COUNT(*)'
- * aggregateSQL('sum', 'age') // 'SUM("age")'
- * aggregateSQL('average', ['payload', 'score']) // 'AVG(json_extract("payload", \'$.score\'))'
- * ```
  */
-export declare function aggregateSQL(operation: AggregateFunction, column: FieldPath): string;
+export declare function compileAggregateSQL(operation: AggregateOperation, column: FieldPath): string;
 
 /**
- * Map a portable {@link ColumnType} to its SQLite column type.
- *
- * @remarks
- * `text` / `json` → `TEXT` (JSON is stored as text and read back with
- * `json_extract` for nested-field queries); `integer` / `boolean` → `INTEGER`
- * (a boolean stores `1` / `0`); `real` → `REAL`; `blob` → `BLOB`. No `NOT NULL`
- * is ever emitted — the contract validates required-ness; the database is just
- * storage (AGENTS §14, the typed layer above imposes the shape).
+ * Map a portable {@link ColumnStorage} to its SQLite column type.
  *
- * @param type - The portable column type
+ * @param storage - The portable column type
  * @returns The SQLite column type keyword
- *
- * @example
- * ```ts
- * columnSQL('integer') // 'INTEGER'
- * columnSQL('json') // 'TEXT'
- * ```
  */
-export declare function columnSQL(type: ColumnType): string;
+export declare function compileColumnSQL(storage: ColumnStorage): string;
 
 /**
- * Compile a {@link Criteria} into the SQL clause that follows a table name, with
- * its bound parameters in clause order.
+ * Compile one condition to its `<column> <operator>` SQL fragment and the parameters
+ * it binds — engine-exact under SQL's three-valued NULL logic.
  *
  * @remarks
- * The driver's native `records` / `count` path: it assembles
- * `[where, orderBy, limitOffset]` (each possibly empty) into one clause so a
- * `SELECT * FROM <table> <clause>` runs the whole read in the engine instead of
- * over a JS `scan`. The WHERE fold is parenthesized **left-to-right** to mirror
- * the core engine's `matchesCriteria` (not SQL's native AND-over-OR precedence),
- * so a native and an engine read return identical rows. Each operand is encoded
- * via `encodeValue`: a flat column uses its declared schema type, while a nested
- * `FieldPath` (a `json_extract` read) encodes each operand as the native scalar
- * the extract returns — derived from the operand's runtime type — so it compares.
- * The 15 operators map per the databases guide's operator table, with
- * `starts` / `ends` using `LIKE … ESCAPE '\'` and an empty `any` / `none` list
- * collapsing to a constant. A `undefined` criteria (or one with no parts)
- * compiles to an empty clause.
+ * Every operand is run through `encodeValue`, so a bound value matches the SQL
+ * the column side compiles to. A flat column encodes operands with its DECLARED
+ * schema type (a flat `json` column → `JSON.stringify`); a nested `FieldPath`
+ * encodes each operand as the NATIVE scalar `json_extract` returns, derived from
+ * the operand's runtime type (per-operand, since `between` / `any` / `none` can
+ * mix types). `any` / `none` collapse an empty list to a constant (`0` matches
+ * nothing, `1` matches all) with no parameters.
  *
- * @param criteria - The read specification, or `undefined` for all rows
- * @param schema - The table's schema (column types for operand encoding)
- * @returns The SQL tail and its bound parameters
+ * The core engine's total order ranks `undefined` (rank 0) BELOW `null`
+ * (rank 1) (see `compareValues`), so a MISSING/`NULL` column MATCHES
+ * `below` / `to` / a scalar `not` / `none` — the opposite of raw SQL, where a
+ * comparison against `NULL` is `NULL` (excluded). This fragment replicates the
+ * engine exactly. Truth table (`value` = the engine's decoded field read; a
+ * FLAT column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
+ * flat `value` is NEVER a present `null` — only a NESTED path can be
+ * present-but-`null`):
+ *
+ * ```text
+ * operator            | value=undefined (absent)      | value=null (nested only) | value=scalar
+ * --------------------|--------------------------------|---------------------------|-------------
+ * equals, first=null  | no match                       | MATCH                     | no match
+ * equals, first=X     | no match                       | no match                  | value===X
+ * not, first=null     | MATCH (flat: unconditionally;  | no match                  | MATCH
+ *                     |   nested: absent still matches)|                           |
+ * not, first=X        | MATCH                          | MATCH                     | value!==X
+ * below/to, first=X   | MATCH (rank 0 < rank(X))       | MATCH (rank 1 < rank(X))  | rank compare
+ * none, list=[…]       | MATCH (no scalar rank-equal)   | MATCH                     | not-in-list
+ * any, list=[…]        | no match                       | no match                  | in-list
+ * above/from/between  | no match                       | no match                  | rank compare
+ * like/glob/starts/…  | no match (not a string)        | no match                  | string test
+ * present              | false                          | false                     | true
+ * absent                | true                           | true                      | false
+ * ```
+ *
+ * A flat SQL `NULL` represents absence or explicit null according to its
+ * {@link ColumnSchema}; optional-and-nullable columns use a storage-class
+ * sentinel to distinguish the two. The native exactness gate therefore
+ * refines every optional or nullable scalar comparison through the core engine.
+ * This compiler still emits a total SQL fragment for direct consumers.
+ *
+ * A NESTED path can be present-but-`null` (a stored JSON `null`), which
+ * `json_extract` reads back as SQL `NULL` — indistinguishable from an ABSENT
+ * path. `json_type(col, path)` disambiguates them (`'null'` for present-null,
+ * SQL `NULL` for absent), so nested `equals` / `not` against a `null` operand
+ * compile through `json_type` instead of `IS NULL` / `IS NOT NULL`.
+ *
+ * Every other MATCH-on-null-or-absent row is expressed uniformly (flat and
+ * nested alike) as `(<column> <op> ? OR <column> IS NULL)` — for a nested
+ * path, `json_extract` already collapses BOTH absent and present-null to SQL
+ * `NULL`, so `IS NULL` catches both in one clause; for a flat column there is
+ * only the absent case to catch.
+ *
+ * @param condition - The condition to compile
+ * @param schema - The table's schema (for declared column types)
+ * @returns The SQL fragment and its bound parameters
  *
  * @example
  * ```ts
- * compileCriteria({ conditions: [{ column: 'age', operator: 'from', values: [18], connector: 'and' }] }, schema)
- * // { sql: 'WHERE "age" >= ? ORDER BY "id"', params: [18] }
+ * compileConditionSQL({ column: 'age', operator: 'above', values: [18], connector: 'and' }, schema)
+ * // { sql: '"age" > ?', parameters: [18] }
+ * compileConditionSQL({ column: 'age', operator: 'below', values: [18], connector: 'and' }, schema)
+ * // { sql: '("age" < ? OR "age" IS NULL)', parameters: [18] }
  * ```
  */
-export declare function compileCriteria(criteria: Criteria | undefined, schema: TableSchema): CompiledSQL;
+export declare function compileConditionSQL(condition: Condition, schema: TableSchema): CompiledSQL;
 
 /**
  * A parameterized SQL fragment or statement plus its bind values.
  *
  * @remarks
  * Produced by the pure SQL compilers (`compilers.ts`) that turn a core
- * `Criteria` (or a table definition) into SQL text with `?` placeholders, and
- * consumed by the SQLite driver, which runs `sql` with `params` bound in
- * order — no further assembly. Keeping `sql` and `params` together prevents
+ * `QueryInput` (or a table definition) into SQL text with `?` placeholders, and
+ * consumed by the SQLite driver, which runs `sql` with `parameters` bound in
+ * order — no further assembly. Keeping `sql` and `parameters` together prevents
  * the two from drifting apart across compile and execute.
  */
 export declare interface CompiledSQL {
     readonly sql: string;
-    readonly params: readonly SQLiteValue[];
+    readonly parameters: readonly SQLiteValue[];
 }
 
+/**
+ * Compile a {@link FieldPath} to the SQL expression that reads it.
+ *
+ * @param path - The field path
+ * @returns The SQL expression selecting the value
+ */
+export declare function compileFieldSQL(path: FieldPath): string;
+
+/**
+ * Compile a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
+ * expression — the {@link compileFieldSQL} `json_extract` sibling used to tell a
+ * PRESENT JSON `null` apart from an ABSENT path (both read back as SQL `NULL`
+ * through `json_extract`, but `json_type` reports `'null'` for the former and
+ * SQL `NULL` for the latter).
+ *
+ * @param path - The nested field path (a column plus its JSON keys)
+ * @returns The SQL expression reading the value's JSON type
+ *
+ * @example
+ * ```ts
+ * compileJSONTypeSQL(['payload', 'user', 'id']) // "json_type(\"payload\", '$.user.id')"
+ * ```
+ */
+export declare function compileJSONTypeSQL(path: readonly string[]): string;
+
 /**
  * Compile the ORDER BY clause from the order terms, always ending with the
  * primary key as the final determinant.
@@ -152,20 +191,51 @@ export declare function compileOrder(order: readonly Order[] | undefined, schema
  *
  * @example
  * ```ts
- * compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', params: [5] }
+ * compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', parameters: [5] }
  * ```
  */
 export declare function compilePage(limit: number | undefined, offset: number | undefined): CompiledSQL;
 
+/**
+ * Compile a {@link QueryInput} into the SQL clause that follows a table name, with
+ * its bound parameters in clause order.
+ *
+ * @remarks
+ * The driver's native `records` / `count` path: it assembles
+ * `[where, orderBy, limitOffset]` (each possibly empty) into one clause so a
+ * `SELECT * FROM <table> <clause>` runs the whole read in the engine instead of
+ * over a JS `scan`. The WHERE fold is parenthesized **left-to-right** to mirror
+ * the core engine's `matchesQuery` (not SQL's native AND-over-OR precedence),
+ * so a native and an engine read return identical rows. Each operand is encoded
+ * via `encodeValue`: a flat column uses its declared schema type, while a nested
+ * `FieldPath` (a `json_extract` read) encodes each operand as the native scalar
+ * the extract returns — derived from the operand's runtime type — so it compares.
+ * The 15 operators map per the databases guide's operator table, with
+ * `starts` / `ends` using `LIKE … ESCAPE '\'` and an empty `any` / `none` list
+ * collapsing to a constant. An `undefined` input (or one with no parts)
+ * compiles to an empty clause.
+ *
+ * @param input - The read specification, or `undefined` for all rows
+ * @param schema - The table's schema (column types for operand encoding)
+ * @returns The SQL tail and its bound parameters
+ *
+ * @example
+ * ```ts
+ * compileQuerySQL({ conditions: [{ column: 'age', operator: 'from', values: [18], connector: 'and' }] }, schema)
+ * // { sql: 'WHERE "age" >= ? ORDER BY "id"', parameters: [18] }
+ * ```
+ */
+export declare function compileQuerySQL(input: QueryInput | undefined, schema: TableSchema): CompiledSQL;
+
 /**
  * Fold the conditions into one WHERE clause, parenthesizing progressively
- * left-to-right so the grouping matches the engine's `matchesCriteria` fold.
+ * left-to-right so the grouping matches the engine's `matchesQuery` fold.
  *
  * @remarks
  * The first condition's connector is ignored, per the {@link Condition} types.
- * Every fragment (see {@link fragment}'s truth table) replicates the core
+ * Every fragment (see {@link compileConditionSQL}'s truth table) replicates the core
  * engine's total order EXACTLY under SQL's three-valued NULL logic, so this
- * clause matches `applyCriteria` row-for-row over the same table — a native
+ * clause matches `applyQuery` row-for-row over the same table — a native
  * `records` / `count` read never disagrees with a scan-and-filter fallback.
  *
  * @param conditions - The conditions to fold
@@ -175,7 +245,7 @@ export declare function compilePage(limit: number | undefined, offset: number |
  * @example
  * ```ts
  * compileWhere([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
- * // { sql: 'WHERE "age" >= ?', params: [18] }
+ * // { sql: 'WHERE "age" >= ?', parameters: [18] }
  * ```
  */
 export declare function compileWhere(conditions: readonly Condition[], schema: TableSchema): CompiledSQL;
@@ -184,9 +254,9 @@ export declare function compileWhere(conditions: readonly Condition[], schema: T
  * Create a persistent JSON-file {@link DriverInterface} for the core database layer.
  *
  * @remarks
- * Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
- * relations stack against a single JSON file instead of memory — the `Database` /
- * `Table` / `Query` / relations API is unchanged; only where the bytes live changes.
+ * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
+ * database against a single JSON file instead of memory — the `Database` /
+ * `Table` / `Query` API is unchanged; only where the bytes live changes.
  * The driver is the reference `MemoryDriver` plus JSON-file persistence: `open` loads
  * the file, every mutation flushes the whole store back, and querying runs through
  * the core engine over `scan` (it is scan-only — no native `records` / `count` /
@@ -215,19 +285,20 @@ export declare function createJSONDriver(path: string): DriverInterface;
  * Create a trusted-mode SQLite {@link DriverInterface} for the core database layer.
  *
  * @remarks
- * Pass it to `createDatabase` from `@orkestrel/database` to run the whole typed database +
- * relations stack against a real SQLite database — the `Database` / `Table` /
- * `Query` / relations API is unchanged; only where the bytes live changes. Built
+ * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
+ * database against a real SQLite database — the `Database` / `Table` /
+ * `Query` API is unchanged; only where the bytes live changes. Built
  * on the published `@orkestrel/sqlite` synchronous wrapper: `open` issues real
  * typed `CREATE TABLE` / `CREATE INDEX` statements (reopen-safe) plus a reserved
- * `_meta` table for `meta()` / `stamp()` — avoid naming a table `_meta`.
+ * `_metadata` table for `metadata()` / `stamp()` — avoid naming a table `_metadata`.
  * Querying, paging, and aggregation run natively (`records` / `count` /
  * `aggregate` / `stream`); `transaction` and `migrate` use real `BEGIN` /
  * `COMMIT` / `ROLLBACK`, so `migrate` is atomic even mid-plan.
  *
- * @param options - A bare database file path (`':memory:'` by default, for
- *   back-compat), or a full {@link SQLiteDriverOptions} bag (`path`,
- *   `readonly`, `timeout`, `foreignKeys`, `pragmas`)
+ * @param options - The {@link SQLiteDriverOptions} bag (`path`, `readonly`,
+ *   `timeout`, `references`, `pragmas`); `references` directly enables or
+ *   disables foreign-key enforcement, and omission retains the upstream
+ *   default; omit the whole bag for an in-memory database
  * @returns A {@link DriverInterface} backed by SQLite
  *
  * @example
@@ -237,30 +308,16 @@ export declare function createJSONDriver(path: string): DriverInterface;
  * import { createSQLiteDriver } from '@orkestrel/database/server'
  *
  * const db = createDatabase({
- * 	driver: createSQLiteDriver('data/app.sqlite'),
+ * 	driver: createSQLiteDriver({ path: 'data/app.sqlite' }),
  * 	tables: { users: { id: stringShape(), name: stringShape() } },
  * })
  * await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to app.sqlite
  *
- * // Or with options:
+ * // Or with additional options:
  * createSQLiteDriver({ path: 'data/app.sqlite', pragmas: { journal_mode: 'WAL' } })
  * ```
  */
-export declare function createSQLiteDriver(options?: string | SQLiteDriverOptions): DriverInterface;
-
-/**
- * The declared storage type of a flat (string) column, read from the schema.
- *
- * @param column - The column name
- * @param schema - The table's schema
- * @returns The column's {@link ColumnType}, or `undefined` if the schema does not carry it
- *
- * @example
- * ```ts
- * declaredType('age', schema) // 'integer'
- * ```
- */
-export declare function declaredType(column: string, schema: TableSchema): ColumnType | undefined;
+export declare function createSQLiteDriver(options?: SQLiteDriverOptions): DriverInterface;
 
 /**
  * Decode a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
@@ -269,9 +326,8 @@ export declare function declaredType(column: string, schema: TableSchema): Colum
  * Decodes each declared column with {@link decodeValue} and **omits** any column
  * whose decoded value is `undefined` — so an absent / `NULL` optional column does
  * not surface as `{ bio: undefined }`, matching how the contract's optional
- * columns expect absence. A known, documented edge: a non-optional `nullableShape`
- * column storing `null` round-trips to absent (a `null` cell decodes to
- * `undefined`, and an `undefined` value is omitted).
+ * columns expect absence. Nullable-only SQL `NULL` cells remain explicit
+ * `null`; optional-and-nullable columns use their storage-class sentinel.
  *
  * @param row - The stored SQLite row
  * @param schema - The table's schema
@@ -285,27 +341,51 @@ export declare function declaredType(column: string, schema: TableSchema): Colum
 export declare function decodeRow(row: SQLiteRow, schema: TableSchema): Row;
 
 /**
- * Decode a stored {@link SQLiteValue} back to its JS value for a column's type —
+ * Decode a stored {@link SQLiteValue} back to its JS value for a declared column —
  * the exact inverse of {@link encodeValue}.
  *
  * @remarks
- * A `boolean` column reads `1` / `0` back to `true` / `false` (a stored `null`
- * → `undefined`); a `json` column `JSON.parse`s a string (anything else →
- * `undefined`); every other type passes the value through, mapping a stored
- * `NULL` to `undefined`. NULL decodes to `undefined` so {@link decodeRow} can
- * omit absent columns.
+ * Stored values must use the declared SQLite storage class. SQL `NULL` decodes
+ * to explicit `null` only for nullable-only columns and otherwise to absence.
+ * Optional-and-nullable sentinels decode to explicit `null`; malformed values
+ * decode to `undefined` so {@link decodeRow} omits them.
  *
  * @param value - The stored SQLite value
- * @param type - The column's portable storage type
- * @returns The decoded JS value (`undefined` for a stored `NULL`)
+ * @param column - The declared storage and absence/null contract
+ * @returns The decoded JS value, or `undefined` for absence/malformed storage
  *
  * @example
  * ```ts
- * decodeValue(1, 'boolean') // true
- * decodeValue('{"a":1}', 'json') // { a: 1 }
+ * decodeValue(1, booleanColumn) // true
+ * decodeValue('{"a":1}', jsonColumn) // { a: 1 }
  * ```
  */
-export declare function decodeValue(value: SQLiteValue, type: ColumnType): unknown;
+export declare function decodeValue(value: SQLiteValue, column: ColumnSchema): unknown;
+
+/**
+ * Build a collision-free SQL index name for a table + column-group index —
+ * shared by the compiler module's `schemaToIndexes` and `stepToSQL`,
+ * so a plan-built index name always matches one `open` would have created.
+ *
+ * @remarks
+ * A naive `idx_<table>_<cols joined by _>` is AMBIGUOUS: table `'a_b'` with
+ * column `'c'` and table `'a'` with columns `['b', 'c']` both produce
+ * `idx_a_b_c`. This encodes each part (the table name, then each column name)
+ * length-prefixed (`<len>_<part>`) so the boundary between parts is always
+ * unambiguous, however the names themselves are punctuated.
+ *
+ * @param table - The table name
+ * @param columns - The index's column names, in order
+ * @returns The deterministic, collision-free index identifier (unquoted)
+ *
+ * @example
+ * ```ts
+ * deriveSQLiteIndexName('users', ['name']) // 'idx_5_users_4_name'
+ * deriveSQLiteIndexName('a_b', ['c']) // 'idx_3_a_b_1_c'
+ * deriveSQLiteIndexName('a', ['b', 'c']) // 'idx_1_a_1_b_1_c'
+ * ```
+ */
+export declare function deriveSQLiteIndexName(table: string, columns: readonly string[]): string;
 
 /**
  * Encode a whole {@link Row} to a {@link SQLiteRow} by its table's schema.
@@ -327,28 +407,25 @@ export declare function decodeValue(value: SQLiteValue, type: ColumnType): unkno
 export declare function encodeRow(row: Row, schema: TableSchema): SQLiteRow;
 
 /**
- * Encode a JS value to its stored {@link SQLiteValue} for a column's type.
+ * Encode a JS value to its stored {@link SQLiteValue} for a declared column.
  *
  * @remarks
- * The forward half of the bridge, total (AGENTS §14): a value that does not fit
- * its column's storage type encodes to `null` rather than throwing. A `boolean`
- * column stores `1` / `0` (and `null` / `undefined` → `null`); a `json` column
- * stores `JSON.stringify` (or `null` for `null` / `undefined`); `integer` /
- * `real` keep a `number` / `bigint`, else `null`; `text` keeps a `string`, else
- * `null`; `blob` keeps a `Uint8Array`, else `null`. Narrowed with `typeof` /
- * `instanceof`, never `as`.
+ * The codec is total: a malformed value encodes to SQL `NULL`. Absence always
+ * uses SQL `NULL`. A nullable-only column also uses SQL `NULL` for explicit
+ * `null`; an optional-and-nullable column uses a storage-class sentinel so
+ * absence and explicit `null` remain distinct.
  *
  * @param value - The JS value to store
- * @param type - The column's portable storage type
+ * @param column - The declared storage and absence/null contract
  * @returns The value SQLite stores
  *
  * @example
  * ```ts
- * encodeValue(true, 'boolean') // 1
- * encodeValue({ a: 1 }, 'json') // '{"a":1}'
+ * encodeValue(true, booleanColumn) // 1
+ * encodeValue({ a: 1 }, jsonColumn) // '{"a":1}'
  * ```
  */
-export declare function encodeValue(value: unknown, type: ColumnType): SQLiteValue;
+export declare function encodeValue(value: unknown, column: ColumnSchema): SQLiteValue;
 
 /**
  * Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
@@ -365,7 +442,7 @@ export declare function encodeValue(value: unknown, type: ColumnType): SQLiteVal
 export declare function escapeLike(text: string): string;
 
 /**
- * The declared {@link ColumnType}s whose SQL EQUALITY comparisons (`equals` /
+ * The declared {@link ColumnStorage}s whose SQL EQUALITY comparisons (`equals` /
  * `not` / `any` / `none`) and `starts` / `ends` compiles are provably
  * engine-exact under declared-type trust — `text` / `integer` / `real` /
  * `boolean`; a `json` or `blob` column always refines instead.
@@ -380,23 +457,20 @@ export declare function escapeLike(text: string): string;
  * compares UTF-16 CODE-UNIT order. The two orders diverge for supplementary-
  * plane characters (code points ≥ U+10000, e.g. many emoji): a lead surrogate
  * (`\uD800`–`\uDBFF`) sorts BELOW ``–`￿` in code-unit order, while
- * its code point sorts ABOVE them. So `isExactCondition`'s range family and
- * `isExactOrder` exclude `text`, refining through the core engine instead. A
- * future opt-in "trusted collation" mode (the caller vouches the column's
- * values are BMP-only, or a custom SQLite collation matching `compareValues`
- * is registered) could restore native text ranges/ordering.
+ * its code point sorts ABOVE them. So `matchesConditionExactly`'s range family and
+ * `matchesOrderExactly` exclude `text`, refining through the core engine instead.
  */
-export declare const EXACT_COLUMN_TYPES: readonly ColumnType[];
+export declare const EXACT_COLUMN_STORAGE: readonly ColumnStorage[];
 
 /**
- * The declared {@link ColumnType}s whose SQL RANGE comparisons
+ * The declared {@link ColumnStorage}s whose SQL RANGE comparisons
  * (`above` / `below` / `from` / `to` / `between`) and `ORDER BY` compiles are
  * provably engine-exact — `integer` / `real` / `boolean` only. `text` is
- * excluded: see {@link EXACT_COLUMN_TYPES}'s remarks for the BINARY-collation
+ * excluded: see {@link EXACT_COLUMN_STORAGE}'s remarks for the BINARY-collation
  * (code-point) vs. JS `<` (code-unit) divergence on supplementary-plane
  * characters.
  */
-export declare const EXACT_RANGE_COLUMN_TYPES: readonly ColumnType[];
+export declare const EXACT_RANGE_COLUMN_STORAGE: readonly ColumnStorage[];
 
 /**
  * Extract a stored row's values in a declared positional order.
@@ -420,239 +494,77 @@ export declare const EXACT_RANGE_COLUMN_TYPES: readonly ColumnType[];
 export declare function extractValues(row: SQLiteRow, names: readonly string[], table: string): readonly SQLiteValue[];
 
 /**
- * Compile a {@link FieldPath} to the SQL expression that reads it.
- *
- * @remarks
- * A single string is ONE column — `quote(path)`. An array descends a JSON column:
- * the first element is the (quoted) column, the rest a `json_extract` path
- * (`json_extract("payload", '$.user.id')`), matching the guide's nested-field
- * examples (simple identifier keys). The string's value is never split on `.`
- * (AGENTS — `FieldPath` semantics): a dotted string is one column literally.
- *
- * @param path - The field path (a column, or a column + nested keys)
- * @returns The SQL expression selecting the value
- *
- * @example
- * ```ts
- * fieldColumn('payload') // '"payload"'
- * fieldColumn(['payload', 'user', 'id']) // 'json_extract("payload", \'$.user.id\')'
- * ```
- */
-export declare function fieldColumn(path: FieldPath): string;
-
-/**
- * Compile one condition to its `<column> <operator>` SQL fragment and the params
- * it binds — engine-exact under SQL's three-valued NULL logic.
- *
- * @remarks
- * Every operand is run through `encodeValue`, so a bound value matches the SQL
- * the column side compiles to. A flat column encodes operands with its DECLARED
- * schema type (a flat `json` column → `JSON.stringify`); a nested `FieldPath`
- * encodes each operand as the NATIVE scalar `json_extract` returns, derived from
- * the operand's runtime type (per-operand, since `between` / `any` / `none` can
- * mix types). `any` / `none` collapse an empty list to a constant (`0` matches
- * nothing, `1` matches all) with no params.
- *
- * The core engine's total order ranks `undefined` (rank 0) BELOW `null`
- * (rank 1) (see `compareValues`), so a MISSING/`NULL` column MATCHES
- * `below` / `to` / a scalar `not` / `none` — the opposite of raw SQL, where a
- * comparison against `NULL` is `NULL` (excluded). This fragment replicates the
- * engine exactly. Truth table (`value` = the engine's decoded field read; a
- * FLAT column's stored `NULL` decodes to `undefined` per `decodeRow`, so a
- * flat `value` is NEVER a present `null` — only a NESTED path can be
- * present-but-`null`):
- *
- * ```text
- * operator            | value=undefined (absent)      | value=null (nested only) | value=scalar
- * --------------------|--------------------------------|---------------------------|-------------
- * equals, first=null  | no match                       | MATCH                     | no match
- * equals, first=X     | no match                       | no match                  | value===X
- * not, first=null     | MATCH (flat: unconditionally;  | no match                  | MATCH
- *                     |   nested: absent still matches)|                           |
- * not, first=X        | MATCH                          | MATCH                     | value!==X
- * below/to, first=X   | MATCH (rank 0 < rank(X))       | MATCH (rank 1 < rank(X))  | rank compare
- * none, list=[…]       | MATCH (no scalar rank-equal)   | MATCH                     | not-in-list
- * any, list=[…]        | no match                       | no match                  | in-list
- * above/from/between  | no match                       | no match                  | rank compare
- * like/glob/starts/…  | no match (not a string)        | no match                  | string test
- * present              | false                          | false                     | true
- * absent                | true                           | true                      | false
- * ```
- *
- * Because a flat column's `NULL` always decodes to `undefined`, `equals`
- * against a `null` operand needs no special flat compilation (`col = ?`
- * binding a `NULL` param is already always-false in SQL, matching "no match"
- * above) — but flat `not` against `null` must match EVERY row (both the
- * absent and the scalar rows), which `col != ? OR col IS NULL` cannot express
- * (it only catches the `IS NULL` row), so a flat `not`-with-`null`-operand
- * compiles to the constant `1`.
- *
- * A NESTED path can be present-but-`null` (a stored JSON `null`), which
- * `json_extract` reads back as SQL `NULL` — indistinguishable from an ABSENT
- * path. `json_type(col, path)` disambiguates them (`'null'` for present-null,
- * SQL `NULL` for absent), so nested `equals` / `not` against a `null` operand
- * compile through `json_type` instead of `IS NULL` / `IS NOT NULL`.
- *
- * Every other MATCH-on-null-or-absent row is expressed uniformly (flat and
- * nested alike) as `(<column> <op> ? OR <column> IS NULL)` — for a nested
- * path, `json_extract` already collapses BOTH absent and present-null to SQL
- * `NULL`, so `IS NULL` catches both in one clause; for a flat column there is
- * only the absent case to catch.
- *
- * @param condition - The condition to compile
- * @param schema - The table's schema (for declared column types)
- * @returns The SQL fragment and its bound parameters
- *
- * @example
- * ```ts
- * fragment({ column: 'age', operator: 'above', values: [18], connector: 'and' }, schema)
- * // { sql: '"age" > ?', params: [18] }
- * fragment({ column: 'age', operator: 'below', values: [18], connector: 'and' }, schema)
- * // { sql: '("age" < ? OR "age" IS NULL)', params: [18] }
- * ```
- */
-export declare function fragment(condition: Condition, schema: TableSchema): CompiledSQL;
-
-/**
- * Generate a fresh unique key — a v4 UUID string, backed by `node:crypto`.
- *
- * @remarks
- * Supply this as {@link import('@orkestrel/database').DatabaseOptions.key} so a table mints
- * a key when a written row lacks its primary-key value. Strings work as keys on
- * every backend; supply your own key values directly to use numeric keys instead.
+ * The declared storage type of a flat (string) column, read from the schema.
  *
- * @returns A new UUID string
+ * @param column - The column name
+ * @param schema - The table's schema
+ * @returns The column's {@link ColumnStorage}, or `undefined` if the schema does not carry it
  *
  * @example
  * ```ts
- * const db = createDatabase({ driver, tables, key: generateKey })
+ * findColumnStorage('age', schema) // 'integer'
  * ```
  */
-export declare function generateKey(): string;
+export declare function findColumnStorage(column: string, schema: TableSchema): ColumnStorage | undefined;
 
 /**
- * Build a collision-free SQL index name for a table + column-group index —
- * shared by {@link schemaToIndexes} (an `open`-time `CREATE INDEX`) and
- * {@link stepToSQL}'s `index.add` / `index.remove` (a migration-time DDL),
- * so a plan-built index name always matches one `open` would have created.
+ * The storage type a nested (`json_extract`) operand encodes as, derived from its
+ * RUNTIME value — NOT `json`.
  *
  * @remarks
- * A naive `idx_<table>_<cols joined by _>` is AMBIGUOUS: table `'a_b'` with
- * column `'c'` and table `'a'` with columns `['b', 'c']` both produce
- * `idx_a_b_c`. This encodes each part (the table name, then each column name)
- * length-prefixed (`<len>_<part>`) so the boundary between parts is always
- * unambiguous, however the names themselves are punctuated.
+ * `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
+ * `1` / `0`, a number as-is, a string as-is), so the operand must encode to that
+ * same scalar to compare. A boolean → `'boolean'` (→ `1` / `0`); a number →
+ * `'integer'` / `'real'`; a bigint → `'integer'`; a string → `'text'`; `null` /
+ * `undefined` → `'text'` (encodes to `null`); an object / array → `'json'` (the
+ * edge of comparing against a json subtree).
  *
- * @param table - The table name
- * @param columns - The index's column names, in order
- * @returns The deterministic, collision-free index identifier (unquoted)
+ * @param value - The runtime operand value
+ * @returns The {@link ColumnStorage} to encode it as
  *
  * @example
  * ```ts
- * indexName('users', ['name']) // 'idx_5_users_4_name'
- * indexName('a_b', ['c']) // 'idx_3_a_b_1_c'
- * indexName('a', ['b', 'c']) // 'idx_1_a_1_b_1_c'
+ * inferValueStorage(true) // 'boolean'
+ * inferValueStorage(9) // 'integer'
  * ```
  */
-export declare function indexName(table: string, columns: readonly string[]): string;
-
-/**
- * Whether one {@link Condition} compiles to SQL that is PROVABLY identical to
- * the core engine's `matchesCondition` for every value its column's declared
- * type can store.
- *
- * @remarks
- * `false` for a nested `FieldPath` (an array), a column absent from `schema`,
- * or a column whose declared type is not `text` / `integer` / `real` /
- * `boolean` (a `json` / `blob` column) — EXCEPT `absent` / `present`, which
- * compile to `IS NULL` / `IS NOT NULL` and match `decodeRow`'s "a stored NULL
- * decodes to `undefined`" rule for every column type, so they are exact
- * regardless of declared type. `equals` / `not` require a operand matching the
- * column's declared type (a `null` / `undefined` operand is never exact here —
- * `encodeRow` stores both an explicit `null` and an absent field as SQL NULL,
- * so native `IS NULL` semantics cannot match the engine's `deepEqual`-over-
- * decoded-rows truth). `above` / `below` / `from` / `to` / `between` are exact
- * ONLY for a declared type in {@link EXACT_RANGE_COLUMN_TYPES} (`integer` /
- * `real` / `boolean`) — a `text` column's range conditions REFINE, because
- * SQLite's default BINARY collation orders TEXT by Unicode CODE POINT while
- * the core engine's `compareValues` orders JS strings by UTF-16 CODE UNIT,
- * and the two diverge for supplementary-plane characters (see
- * {@link EXACT_COLUMN_TYPES}'s remarks for the full rationale).
- * `any` / `none` require a NON-EMPTY list where every element matches (an empty
- * list is exact under neither: the engine's `any([])` matches nothing while
- * `none([])` matches everything, and SQL `IN ()` is a syntax error) — these
- * stay exact on `text` (byte equality is collation-independent and engine-
- * identical). `starts` / `ends` are exact only on a `text` column with a
- * string operand (case-sensitive `substr` compile, see {@link fragment}) —
- * likewise collation-independent. `like` / `glob` are NEVER exact — SQLite
- * `LIKE` folds case ASCII-only against the engine's Unicode fold, and `GLOB`
- * has character classes the engine treats literally.
- *
- * @param condition - The condition to test
- * @param schema - The table's schema
- * @returns Whether `condition` is exact
- */
-export declare function isExactCondition(condition: Condition, schema: TableSchema): boolean;
-
-/**
- * Whether a whole {@link Criteria} is exact — every condition and every order
- * term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` /
- * `OFFSET` are always engine-identical).
- *
- * @param criteria - The criteria to test
- * @param schema - The table's schema
- * @returns Whether every part of `criteria` is exact
- */
-export declare function isExactCriteria(criteria: Criteria, schema: TableSchema): boolean;
-
-/**
- * Whether one {@link Order} term's column compiles to an `ORDER BY` that
- * matches the engine's {@link import('@src/core').sortRows} exactly.
- *
- * @remarks
- * `false` for a nested `FieldPath`, a column absent from `schema`, or a
- * declared type outside {@link EXACT_RANGE_COLUMN_TYPES} (`integer` / `real` /
- * `boolean`). `text` is NOT exact here: SQLite's default BINARY collation
- * orders TEXT by Unicode code point while the core engine's `compareValues`
- * orders JS strings by UTF-16 code unit, and the two diverge for
- * supplementary-plane characters (see {@link EXACT_COLUMN_TYPES}'s remarks) —
- * a `text` order term REFINES through the core engine instead.
- *
- * @param order - The order term to test
- * @param schema - The table's schema
- * @returns Whether `order` is exact
- */
-export declare function isExactOrder(order: Order, schema: TableSchema): boolean;
+export declare function inferValueStorage(value: unknown): ColumnStorage;
 
 /**
  * A persistent {@link DriverInterface} backed by a single JSON file — the
  * reference {@link MemoryDriver} plus file load / flush.
  *
  * @remarks
- * A decorator, not a reimplementation: every primitive delegates to an inner
- * {@link MemoryDriver}, so querying, key-order `scan` / `keys`, and capture-replay
- * `snapshot` are inherited unchanged — this layer adds only persistence. `open`
+ * A decorator, not a reimplementation: storage primitives delegate to an inner
+ * {@link MemoryDriver}, while this layer owns persistence, writer ordering,
+ * isolated transactions, and queued row-snapshot restoration. `open`
  * loads the file into memory; every mutation (`write` / `delete` / `clear`) flushes
- * the whole store back. The file is one JSON object, `{ meta?: DriverMeta, tables: {
- * [name]: rows } }` — `meta` is present only once the store has been `stamp`ed
- * (an unstamped store serializes the old `{ tables }` shape, preserving
- * backward compatibility); a per-table array of rows, each row carrying its own
+ * the whole store back. The file is one JSON object, `{ metadata?: DriverMetadata, tables: {
+ * [name]: rows } }` — `metadata` is present only once the store has been `stamp`ed
+ * (an unstamped store omits `metadata`); a per-table array of rows, each row carrying its own
  * primary (the table contract), so the key is recovered on load with
  * {@link extractKey} and the file need not store it. The parsed JSON crosses the
  * boundary as `unknown` and is narrowed with {@link isRecord} / {@link extractKey},
- * never asserted (AGENTS §14): a missing, corrupt, or wrong-shaped file starts
- * empty rather than throwing, and a malformed row (or malformed `meta`) is
- * skipped/dropped rather than thrown on. It is scan-only — it implements none of
- * the optional native `records` / `count` / `aggregate` hooks, so the core engine
+ * never asserted (AGENTS §14). A read that reports no document there starts empty —
+ * `ENOENT` for a plain absence, and `ENOTDIR` for a path whose parent is not a
+ * directory, which no later write could find either; every other read failure or
+ * invalid existing document fails closed without publication, mutation, or
+ * automatic repair. It is scan-only — it implements none of
+ * the optional native `records` / `aggregate` hooks, so the core engine
  * over `scan` answers every query. For development, small datasets, and portable /
  * inspectable data; for large or concurrent workloads reach for a SQLite-backed
  * driver.
  *
- * A failure in the write path ({@link JSONDriver.#serialize} — `mkdir` /
- * `writeFile` / `rename`) is wrapped and rethrown as `DatabaseError` `DRIVER`,
- * carrying the target `path` in its context; the read path ({@link
- * JSONDriver.#load}) tolerance above is a separate, deliberate contract and is
- * never touched by this wrapping.
+ * Metadata crosses {@link cloneDriverMetadata} at parsed-file ingress, public and
+ * scoped write ingress, candidate/root publication, serialization, and copy-out.
+ * Callers therefore cannot mutate queued metadata, and `metadata()` always returns a
+ * distinct deeply frozen snapshot. A failure in the write path ({@link
+ * JSONDriver.#serialize} — `mkdir` / `writeFile` / `rename`) is wrapped and
+ * rethrown as `DatabaseError` `DRIVER`, carrying the target `path` and native
+ * `cause` in its context. If temporary-file cleanup also fails, the top-level
+ * `DRIVER` context additionally carries `temp` and `cleanup`; a precommit abort
+ * remains an `ABORTED` `DatabaseError` in `context.cause`. The fail-closed read path
+ * ({@link JSONDriver.#document}) remains separate from this write-error contract.
  */
 export declare class JSONDriver implements DriverInterface_2 {
     #private;
@@ -660,92 +572,153 @@ export declare class JSONDriver implements DriverInterface_2 {
     open(schema: readonly TableSchema_2[]): Promise<void>;
     close(): Promise<void>;
     read(table: string, key: Key): Promise<Row_2 | undefined>;
-    write(table: string, key: Key, row: Row_2): Promise<void>;
-    delete(table: string, key: Key): Promise<boolean>;
+    write(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    insert(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    delete(table: string, key: Key, options?: OperationOptions): Promise<boolean>;
     keys(table: string): Promise<readonly Key[]>;
     scan(table: string): AsyncIterable<Row_2>;
     /**
      * Natively filtered lazy iteration — delegates to the inner {@link MemoryDriver}.
      *
      * @remarks
-     * Semantics are the memory driver's own: `criteria.conditions` filters, `offset`
-     * / `limit` page lazily, and `criteria.order` is ignored (streaming yields key
+     * Semantics are the memory driver's own: `input.conditions` filters, `offset`
+     * / `limit` page lazily, and `input.order` is ignored (streaming yields key
      * order; sorted output is `records()`'s job).
      *
      * @param table - The table to stream
-     * @param criteria - The filter / offset / limit to apply lazily
+     * @param input - The filter / offset / limit to apply lazily
      */
-    stream(table: string, criteria: Criteria_2): AsyncIterable<Row_2>;
+    stream(table: string, input: QueryInput_2): AsyncIterable<Row_2>;
     clear(table: string): Promise<void>;
     /**
-     * Begin a native transaction — flush-coalescing over the inner {@link MemoryDriver}.
+     * Run an isolated native transaction callback over a candidate memory store.
      *
      * @remarks
-     * Single-writer: throws `DatabaseError` `CONFLICT` if a transaction is already
-     * active — this driver does not support nesting. On begin, captures the inner
-     * memory rollback thunk via `#memory.snapshot()` and suppresses per-mutation
-     * `#flush` — `write` / `delete` / `clear` still mutate memory but no longer
-     * touch the file, so N mutations under the handle cost ONE file write instead
-     * of N. `commit()` releases the suppression and performs that one atomic
-     * `#flush()`, persisting the transaction's net state. `rollback()` restores
-     * memory via the captured snapshot thunk, then `#flush()`s so the file reflects
-     * the restored state. Outside a transaction, behavior is unchanged — every
-     * mutation flushes on its own. Calling `commit` / `rollback` a second time (on
-     * either method, in either order) throws `DatabaseError` `CONFLICT`.
+     * Single-writer: nesting and root operations while active throw `CONFLICT`.
+     * The callback receives a capability over cloned rows, schema, and metadata.
+     * Fulfillment atomically serializes that candidate and publishes it to root
+     * memory only after file replacement succeeds. Rejection or persistence
+     * failure discards the candidate, and every captured capability call after
+     * settlement throws `CONFLICT`.
      *
-     * @returns A {@link TransactionInterface} handle to `commit` or `rollback`
+     * @returns The callback's resolved value
+     */
+    transaction<R>(scope: (storage: StorageInterface) => Promise<R>): Promise<R>;
+    /**
+     * Capture an owned row snapshot at an exact writer-queue position.
+     *
+     * @remarks
+     * Capture owns table names, schemas, rows, and one session-local identity per
+     * table. Rollback is repeatable: it clones the then-current root into a
+     * candidate, adapts captured rows to each surviving same-identity table
+     * through the portable migration engine, persists the candidate with current
+     * metadata, and publishes memory only after file replacement succeeds.
+     * Removed, replaced, uncaptured, and later-added tables remain untouched.
+     *
+     * @param tables - Existing tables to capture; omitted captures every current table
+     * @returns A repeatable rollback operation
      */
-    transaction(): Promise<TransactionInterface>;
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
-    meta(): Promise<DriverMeta | undefined>;
+    metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist `meta` verbatim for a later `meta()` to return.
+     * Persist an owned metadata snapshot for a later `metadata()` to copy out.
      *
      * @remarks
-     * Respects the same defer-flush suppression as `write` / `delete` / `clear`
-     * (see {@link JSONDriver.transaction} @remarks) — stamping inside an active
-     * transaction updates memory but does not flush until the transaction settles.
+     * Root stamping conflicts while a transaction is active. The scoped
+     * {@link StorageInterface.stamp} updates candidate metadata and publishes
+     * with the candidate rows on callback fulfillment.
      *
-     * @param meta - The {@link DriverMeta} to persist
+     * @param metadata - The {@link DriverMetadata} to persist
      */
-    stamp(meta: DriverMeta): Promise<void>;
+    stamp(metadata: DriverMetadata): Promise<void>;
     /**
-     * Apply a {@link Migration} plan by delegating to the inner {@link MemoryDriver},
-     * then persist the migrated state.
+     * Apply one atomic {@link MigrationInput} through an isolated candidate.
      *
      * @remarks
-     * The inner `MemoryDriver.migrate` applies each step (adding/removing tables,
-     * adding/removing columns from stored rows, no-op index steps) and throws
-     * `DatabaseError` `MIGRATION` for a step referencing an unknown table — that
-     * error propagates untouched. `table.add` / `table.remove` steps also update
-     * this driver's own declared `#schema`, mirroring the bookkeeping `open` does,
-     * so a subsequent `#flush` / `#load` round-trip includes (or drops) the table.
-     * A successful migration ends with one atomic `#flush()` so the new state
-     * survives a close and reopen. A multi-step plan applies its steps
-     * sequentially and is NOT atomic — a failure partway through a plan leaves
-     * the earlier steps already applied.
+     * The candidate receives every plan step plus optional metadata. Its complete
+     * rows, derived schema, and metadata serialize through one atomic file
+     * replacement before root memory changes. Any migration or persistence failure
+     * therefore leaves root state and the prior file exact.
      *
-     * @param plan - The migration plan to apply
+     * @param input - The plan and optional metadata to settle together
      */
-    migrate(plan: Migration): Promise<void>;
+    migrate(input: MigrationInput): Promise<void>;
 }
 
 /**
- * Compile a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
- * expression — the {@link fieldColumn} `json_extract` sibling used to tell a
- * PRESENT JSON `null` apart from an ABSENT path (both read back as SQL `NULL`
- * through `json_extract`, but `json_type` reports `'null'` for the former and
- * SQL `NULL` for the latter).
+ * Whether a caught filesystem error reports that nothing is there to read.
  *
- * @param path - The nested field path (a column plus its JSON keys)
- * @returns The SQL expression reading the value's JSON type
+ * @remarks
+ * Two codes carry that meaning: `ENOENT` is a plain absence, and `ENOTDIR` is a
+ * path whose parent is not a directory — an absence in the stronger sense, since
+ * no file can exist at that name and no later write could find one. Hosts
+ * disagree about which of the two they report for the second shape, so a driver
+ * that reads only `ENOENT` opens on one host and fails closed on another over
+ * the same tree.
+ *
+ * Every other code — a permission refusal, a symlink loop, an unreadable
+ * existing file — is a real failure and stays one.
+ *
+ * A caught value that is not a coded `Error` is not a report about a path, so it
+ * answers `false` rather than being read for a `code` any object could carry.
+ *
+ * @param error - The caught value to classify; any runtime is accepted
+ * @returns `true` when the error reports that the path holds nothing
  *
  * @example
  * ```ts
- * jsonTypeColumn(['payload', 'user', 'id']) // "json_type(\"payload\", '$.user.id')"
+ * matchesAbsentPath(Object.assign(new Error('gone'), { code: 'ENOENT' })) // true
+ * matchesAbsentPath(Object.assign(new Error('denied'), { code: 'EACCES' })) // false
+ * matchesAbsentPath('ENOENT') // false
  * ```
  */
-export declare function jsonTypeColumn(path: readonly string[]): string;
+export declare function matchesAbsentPath(error: unknown): boolean;
+
+/**
+ * Determine whether SQLite can execute an aggregate exactly like the core engine.
+ *
+ * @param operation - Aggregate operation
+ * @param column - Aggregate field
+ * @param schema - Current table schema
+ * @returns Whether native aggregation is exact
+ */
+export declare function matchesAggregateExactly(operation: AggregateOperation, column: FieldPath, schema: TableSchema): boolean;
+
+/**
+ * Whether one {@link Condition} compiles to SQL that is PROVABLY identical to
+ * the core engine's `matchesCondition` for every value its column's declared
+ * type can store.
+ *
+ * @remarks
+ * `false` for a nested `FieldPath` (an array) or a column absent from `schema`.
+ * `absent` / `present` are exact unless a column is both optional and nullable.
+ * In that combined case the storage sentinel for explicit `null` is not SQL
+ * `NULL`, while the core treats both absence and explicit `null` as absent.
+ * Every scalar operator refines when the column is optional
+ * OR nullable, because SQL null semantics and the core total order differ.
+ * Required non-null `equals` / `not` require an operand matching the declared
+ * storage and exclude `json` / `blob`. `above` / `below` / `from` / `to` /
+ * `between` are exact only for {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` /
+ * `real` / `boolean`) — a `text` column's range conditions REFINE, because
+ * SQLite's default BINARY collation orders TEXT by Unicode CODE POINT while
+ * the core engine's `compareValues` orders JS strings by UTF-16 CODE UNIT,
+ * and the two diverge for supplementary-plane characters (see
+ * {@link EXACT_COLUMN_STORAGE}'s remarks for the full rationale).
+ * `any` / `none` require a NON-EMPTY list where every element matches (an empty
+ * list is exact under neither: the engine's `any([])` matches nothing while
+ * `none([])` matches everything, and SQL `IN ()` is a syntax error) — these
+ * stay exact on `text` (byte equality is collation-independent and engine-
+ * identical). `starts` / `ends` are exact only on a `text` column with a
+ * string operand (case-sensitive `substr` compile, see {@link compileConditionSQL}) —
+ * likewise collation-independent. `like` / `glob` are NEVER exact — SQLite
+ * `LIKE` folds case ASCII-only against the engine's Unicode fold, and `GLOB`
+ * has character classes the engine treats literally.
+ *
+ * @param condition - The condition to test
+ * @param schema - The table's schema
+ * @returns Whether `condition` is exact
+ */
+export declare function matchesConditionExactly(condition: Condition, schema: TableSchema): boolean;
 
 /**
  * Whether a value's runtime type matches a column's declared exact type —
@@ -753,7 +726,7 @@ export declare function jsonTypeColumn(path: readonly string[]): string;
  *
  * @remarks
  * `text` ↔ string, `integer` / `real` ↔ FINITE number (`NaN` / `±Infinity`
- * fail), `boolean` ↔ boolean. Backs {@link isExactCondition}'s operand checks.
+ * fail), `boolean` ↔ boolean. Backs {@link matchesConditionExactly}'s operand checks.
  *
  * @param value - The condition operand to test
  * @param type - The column's declared portable type
@@ -765,18 +738,57 @@ export declare function jsonTypeColumn(path: readonly string[]): string;
  * matchesDeclaredType(Number.NaN, 'integer') // false — only finite numbers
  * ```
  */
-export declare function matchesDeclaredType(value: unknown, type: ColumnType): boolean;
+export declare function matchesDeclaredStorage(value: unknown, storage: ColumnStorage): boolean;
+
+/**
+ * Whether one {@link Order} term's column compiles to an `ORDER BY` that
+ * matches the engine's {@link import('@src/core').sortRows} exactly.
+ *
+ * @remarks
+ * `false` for a nested `FieldPath`, a column absent from `schema`, or a
+ * declared type outside {@link EXACT_RANGE_COLUMN_STORAGE} (`integer` / `real` /
+ * `boolean`). `text` is NOT exact here: SQLite's default BINARY collation
+ * orders TEXT by Unicode code point while the core engine's `compareValues`
+ * orders JS strings by UTF-16 code unit, and the two diverge for
+ * supplementary-plane characters (see {@link EXACT_COLUMN_STORAGE}'s remarks) —
+ * a `text` order term REFINES through the core engine instead.
+ *
+ * @param order - The order term to test
+ * @param schema - The table's schema
+ * @returns Whether `order` is exact
+ */
+export declare function matchesOrderExactly(order: Order, schema: TableSchema): boolean;
+
+/**
+ * Whether a whole {@link QueryInput} is exact — every condition and every order
+ * term is exact. `limit` / `offset` never affect exactness (SQL `LIMIT` /
+ * `OFFSET` are always engine-identical).
+ *
+ * @param input - The query input to test
+ * @param schema - The table's schema
+ * @returns Whether every part of `input` is exact
+ */
+export declare function matchesQueryExactly(input: QueryInput, schema: TableSchema): boolean;
+
+/**
+ * Test a declared SQLite type against a portable storage affinity.
+ *
+ * @param declared - Native declared type
+ * @param storage - Portable column storage
+ * @returns Whether SQLite's official affinity rules yield the expected affinity
+ */
+export declare function matchesSQLiteAffinity(declared: unknown, storage: ColumnStorage): boolean;
 
 /**
  * The reserved metadata table the {@link SQLiteDriver} creates on `open` to
- * persist its stamped `DriverMeta` (`version` + declared schema JSON) — the
- * SQLite realization of the `meta` / `stamp` driver hooks.
+ * persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the
+ * SQLite realization of the `metadata` / `stamp` driver hooks.
  *
  * @remarks
- * A single-row table (`id = 1`). A user table named `_meta` collides with the
+ * A single-row table (`id = 1`). A user table named `_metadata` collides with the
  * reservation — the caller's concern to avoid, documented on the driver class.
  */
-export declare const META_TABLE = "_meta";
+export declare const METADATA_TABLE = "_metadata";
 
 /**
  * Quote a SQL identifier (a table or column name) so any characters are literal.
@@ -791,48 +803,24 @@ export declare const META_TABLE = "_meta";
  *
  * @example
  * ```ts
- * quote('order') // '"order"'
+ * quoteIdentifier('order') // '"order"'
  * ```
  */
-export declare function quote(identifier: string): string;
+export declare function quoteIdentifier(identifier: string): string;
 
 /**
- * Project a {@link TableSchema} to the `CREATE INDEX IF NOT EXISTS` statements a
- * SQLite driver's `open` issues for its declared indexes.
+ * Project a {@link TableSchema} to its declared SQLite indexes.
  *
- * @remarks
- * One statement per index group; the index name is built by {@link indexName}
- * (collision-free and deterministic), matching the driver's naming so a
- * repeated `open` is idempotent.
- *
- * @param schema - The table's schema
- * @returns One `CREATE INDEX IF NOT EXISTS …` statement per declared index
- *
- * @example
- * ```ts
- * schemaToIndexes(schema)
- * // ['CREATE INDEX IF NOT EXISTS "idx_5_users_4_name" ON "users" ("name")']
- * ```
+ * @param schema - The table schema
+ * @returns One statement per declared index
  */
 export declare function schemaToIndexes(schema: TableSchema): readonly string[];
 
 /**
- * Project a {@link TableSchema} to the `CREATE TABLE IF NOT EXISTS` statement a
- * SQLite driver's `open` issues for it.
- *
- * @remarks
- * Each column compiles to `<quoted name> <columnSQL(type)>`; the statement ends
- * with `PRIMARY KEY (<quoted primary>)`. No `NOT NULL` is emitted — the contract
- * validates required-ness, the database is just storage (AGENTS §14).
+ * Project a {@link TableSchema} to its `CREATE TABLE IF NOT EXISTS` statement.
  *
- * @param schema - The table's schema
- * @returns The `CREATE TABLE IF NOT EXISTS …` statement
- *
- * @example
- * ```ts
- * schemaToTable(schema)
- * // 'CREATE TABLE IF NOT EXISTS "users" ("id" TEXT, "age" INTEGER, PRIMARY KEY ("id"))'
- * ```
+ * @param schema - The table schema
+ * @returns The complete table declaration
  */
 export declare function schemaToTable(schema: TableSchema): string;
 
@@ -846,21 +834,23 @@ export declare function schemaToTable(schema: TableSchema): string;
  * raw `node:sqlite`. `open` issues `CREATE TABLE IF NOT EXISTS` with real typed
  * columns (mapped from each {@link TableSchema}'s portable column types) and a
  * `PRIMARY KEY`, plus a `CREATE INDEX IF NOT EXISTS` per declared index (both
- * reopen-safe), and readies a reserved `_meta` single-row table `meta()` /
- * `stamp()` read and write — **a user table named `_meta` collides with it**;
+ * reopen-safe), and readies a reserved `_metadata` single-row table `metadata()` /
+ * `stamp()` read and write — **a user table named `_metadata` collides with it**;
  * avoid the name. Rows cross the boundary through the codecs in `helpers.ts`
  * (`json` columns store / parse JSON text, a `boolean` stores `1` / `0`), so the
  * typed layer above imposes the exact shape (AGENTS §14). `write` is an
- * `INSERT OR REPLACE` upsert — the `Table` layer detects a `CONFLICT` via a
- * prior `has`, so this never translates a constraint error; a backend
- * `SQLiteError` otherwise propagates unchanged. Querying, ordering, paging, and
- * aggregation are native: `records` / `count` / `stream` compile a `Criteria`
- * to SQL with `compileCriteria`, and `aggregate` runs a SQL
- * `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` (via `aggregateSQL`) over the same compiled
- * WHERE. `transaction` wraps native `BEGIN` / `COMMIT` / `ROLLBACK` with
- * double-settle guards. `migrate` runs the plan's projected DDL
- * ({@link import('../helpers.js').stepToSQL}) inside whichever native
- * transaction is active: joined into an already-open `transaction()` handle
+ * `INSERT OR REPLACE` upsert, while `insert` uses a plain `INSERT` and maps its
+ * atomic primary-key constraint failure to `CONFLICT`; every other backend
+ * `SQLiteError` is contained by the same `DatabaseError` boundary described
+ * below. Querying, ordering, paging, and
+ * aggregation is native: `records` / `stream` compile a `QueryInput`
+ * to SQL with `compileQuerySQL`, and `aggregate` runs a SQL
+ * `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` (via `compileAggregateSQL`) over the same compiled
+ * WHERE. `transaction` runs a callback inside native `BEGIN` / `COMMIT` /
+ * `ROLLBACK`, passing a scoped storage capability that becomes invalid after
+ * settlement. `migrate` runs the plan's projected DDL
+ * ({@link import('../compilers.js').stepToSQL}) inside whichever native
+ * transaction is active: joined into the active transaction callback
  * when one exists (the core's versioned reconcile path wraps migrate + stamp
  * in one native `BEGIN`, and node:sqlite rejects a nested `BEGIN`), or inside
  * its own `database.transaction` otherwise — a mid-plan failure rolls back
@@ -885,67 +875,72 @@ export declare function schemaToTable(schema: TableSchema): string;
  */
 export declare class SQLiteDriver implements DriverInterface_2 {
     #private;
-    constructor(path: string, options?: SQLiteDriverOptions);
+    constructor(options?: SQLiteDriverOptions);
     open(schema: readonly TableSchema_2[]): Promise<void>;
     close(): Promise<void>;
     read(table: string, key: Key): Promise<Row_2 | undefined>;
-    write(table: string, key: Key, row: Row_2): Promise<void>;
-    delete(table: string, key: Key): Promise<boolean>;
+    write(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    insert(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    delete(table: string, key: Key, options?: OperationOptions): Promise<boolean>;
     keys(table: string): Promise<readonly Key[]>;
     scan(table: string): AsyncIterable<Row_2>;
     clear(table: string): Promise<void>;
-    records(table: string, criteria: Criteria_2): Promise<readonly Row_2[]>;
-    count(table: string, criteria: Criteria_2): Promise<number>;
-    aggregate(table: string, operation: AggregateFunction_2, column: FieldPath, criteria: Criteria_2): Promise<number | undefined>;
-    stream(table: string, criteria: Criteria_2): AsyncIterable<Row_2>;
+    records(table: string, input: QueryInput_2): Promise<readonly Row_2[]>;
+    aggregate(table: string, operation: AggregateOperation_2, column: FieldPath, input: QueryInput_2): Promise<number | undefined>;
+    stream(table: string, input: QueryInput_2): AsyncIterable<Row_2>;
     /**
      * Begin a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
      *
      * @remarks
-     * Calling `commit` or `rollback` a second time (on either method, in either
-     * order) throws `DatabaseError` `CONFLICT`.
+     * The callback receives a scoped {@link StorageInterface}. Fulfillment
+     * commits and returns its value; rejection rolls back and preserves the
+     * original error. Root operations and nesting conflict while active, and a
+     * captured capability conflicts after settlement.
      *
-     * @returns A {@link TransactionInterface} handle to `commit` or `rollback`
+     * @returns The callback's resolved value
      */
-    transaction(): Promise<TransactionInterface>;
+    transaction<R>(scope: (storage: StorageInterface) => Promise<R>): Promise<R>;
     /**
      * Apply a {@link Migration} plan by executing each step's projected DDL
-     * ({@link import('../helpers.js').stepToSQL}).
+     * ({@link import('../compilers.js').stepToSQL}).
      *
      * @remarks
      * Atomicity is provided by whichever native transaction is active: when
-     * this driver's own `transaction()` hook already has a handle open (the
+     * this driver's own `transaction()` callback is active (the
      * core's versioned reconcile / migrate path joins migrate + stamp under
      * one native `BEGIN`), the plan's DDL runs directly inside that enclosing
-     * transaction — a mid-plan failure propagates out and the CALLER's
-     * `commit`/`rollback` provides atomicity. node:sqlite (and SQLite
+     * transaction — a mid-plan failure rejects the callback and the driver
+     * rolls it back. node:sqlite (and SQLite
      * generally) rejects a nested `BEGIN`, so this driver must never open a
      * second native transaction while one is already open. Otherwise (no
      * enclosing transaction), `migrate` wraps the plan in its own native
      * `database.transaction` — atomic on its own: a mid-plan failure rolls
-     * back every DDL statement already applied by the plan. A step
-     * referencing a table not in this driver's declared schema (and that is
-     * not itself a `table.add`) throws `DatabaseError` `MIGRATION` before any
-     * DDL for that step runs, propagating out of whichever transaction is
-     * active (which rolls back on a throw).
+     * back every DDL statement already applied by the plan. A scoped migration
+     * uses one fixed internal savepoint literal because the published SQLite
+     * wrapper intentionally exposes raw `exec` but no savepoint manager. That
+     * savepoint contains a caught inner migration so the outer callback
+     * transaction remains active and may continue safely. A step referencing a
+     * table not in this driver's declared schema (and that is not itself a
+     * `table.add`) throws `DatabaseError` `MIGRATION` before any DDL for that
+     * step runs.
      *
-     * @param plan - The migration plan to apply
+     * @param input - The migration plan and optional metadata stamp to apply atomically
      */
-    migrate(plan: Migration): Promise<void>;
+    migrate(input: MigrationInput): Promise<void>;
     /**
-     * Read the persisted {@link DriverMeta} from the reserved `_meta` table.
+     * Read the persisted {@link DriverMetadata} from the reserved `_metadata` table.
      *
-     * @returns The last-stamped `DriverMeta`, or `undefined` when never stamped
+     * @returns The last-stamped `DriverMetadata`, or `undefined` when never stamped
      *   (or the stored row is malformed)
      */
-    meta(): Promise<DriverMeta | undefined>;
+    metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist `meta` verbatim (as JSON) into the reserved `_meta` table's single
-     * row.
+     * Persist an owned metadata snapshot into the reserved `_metadata` table's
+     * single row.
      *
-     * @param meta - The {@link DriverMeta} to persist
+     * @param metadata - The {@link DriverMetadata} to persist
      */
-    stamp(meta: DriverMeta): Promise<void>;
+    stamp(metadata: DriverMetadata): Promise<void>;
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
 }
 
@@ -957,8 +952,9 @@ export declare class SQLiteDriver implements DriverInterface_2 {
  * `path` is the database file path (`':memory:'` when omitted); `readonly`
  * opens the connection read-only (a write then fails as a typed `DRIVER`
  * {@link DatabaseError}); `timeout` is the busy-timeout in milliseconds before
- * a locked database fails `BUSY`; `foreignKeys` enables foreign-key
- * constraint enforcement. `pragmas` is an ordered record of PRAGMA name to
+ * a locked database fails `BUSY`; `references` enables or disables foreign-key
+ * constraint enforcement, while omission retains the upstream default.
+ * `pragmas` is an ordered record of PRAGMA name to
  * value, applied via the wrapper's `pragma()` right after `connect()`, in
  * insertion order (e.g. `{ journal_mode: 'WAL' }`). Core rows are
  * number-typed — this driver never surfaces a `bigint`, so a stored integer
@@ -969,107 +965,16 @@ export declare interface SQLiteDriverOptions {
     readonly path?: string;
     readonly readonly?: boolean;
     readonly timeout?: number;
-    readonly foreignKeys?: boolean;
+    readonly references?: boolean;
     readonly pragmas?: Readonly<Record<string, string | number>>;
 }
 
 /**
- * One row as a SQLite binding returns it — a plain object keyed by column name.
- *
- * @remarks
- * Every column value is a {@link SQLiteValue}. The SQLite driver decodes each
- * raw row into this shape before handing it to the core query engine; nothing
- * above the driver ever sees SQLite's native row representation directly.
- */
-export declare type SQLiteRow = Record<string, SQLiteValue>;
-
-/**
- * The value domain a SQLite binding accepts as a bound parameter and returns
- * from a row.
- *
- * @remarks
- * Mirrors SQLite's storage classes (`NULL`, `INTEGER`, `REAL`, `TEXT`, `BLOB`)
- * at the TypeScript boundary: `null`, `number` / `bigint` for integer and
- * floating-point values, `string` for text, and `Uint8Array` for blobs. This
- * type is pure — it names the shape a value must have to cross the binding,
- * independent of any concrete sqlite package (`node:sqlite`, `better-sqlite3`,
- * etc.), so a driver can encode/decode against it without importing one.
- */
-export declare type SQLiteValue = null | number | bigint | string | Uint8Array;
-
-/**
- * Project one {@link MigrationStep} onto its table's declared {@link TableSchema}
- * — the bookkeeping counterpart to {@link stepToSQL} (which projects the DDL a
- * driver's `migrate` runs against the live database).
- *
- * @remarks
- * `column.add` / `column.remove` add / filter the named column;
- * `index.add` / `index.remove` add / filter the matching index group (an exact
- * ordered match on `index`). `table.add` / `table.remove` act on a WHOLE
- * schema map rather than one table's shape, so they are the caller's concern
- * (a driver's `migrate` applies them directly against its table map) — passed
- * here, they return `schema` unchanged.
- *
- * @param schema - The table's current declared schema
- * @param step - The migration step to project onto it
- * @returns The table's schema after the step
- *
- * @example
- * ```ts
- * stepToSchema(schema, { operation: 'column.remove', table: 'users', column: 'legacy' })
- * // schema with the 'legacy' column dropped from `columns`
- * ```
- */
-export declare function stepToSchema(schema: TableSchema, step: MigrationStep): TableSchema;
-
-/**
- * Project one {@link MigrationStep} to the DDL statement(s) a SQLite driver's
- * `migrate` executes for it.
- *
- * @remarks
- * `table.add` emits the `CREATE TABLE` plus one `CREATE INDEX` per declared
- * index (via {@link schemaToTable} / {@link schemaToIndexes}); `table.remove`
- * emits `DROP TABLE IF EXISTS`; `column.add` / `column.remove` emit `ALTER
- * TABLE … ADD COLUMN` / `… DROP COLUMN`; `index.add` / `index.remove` emit
- * `CREATE INDEX IF NOT EXISTS` / `DROP INDEX IF EXISTS`, naming the index the
- * same way `schemaToIndexes` does (`idx_<table>_<columns joined by _>`) so a
- * plan-built index matches one `open` would have created. Whether the named
- * table actually exists is the caller's concern (a driver's `migrate` checks
- * its own declared schema before running these statements) — this projection
- * is pure and never inspects live state.
- *
- * @param step - The migration step to project
- * @returns The DDL statement(s) that apply the step
+ * Project one {@link MigrationStep} to SQLite DDL.
  *
- * @example
- * ```ts
- * stepToSQL({ operation: 'column.remove', table: 'users', column: 'legacy' })
- * // ['ALTER TABLE "users" DROP COLUMN "legacy"']
- * ```
+ * @param step - The migration step
+ * @returns The statements that apply the step
  */
 export declare function stepToSQL(step: MigrationStep): readonly string[];
 
-/**
- * The storage type a nested (`json_extract`) operand encodes as, derived from its
- * RUNTIME value — NOT `json`.
- *
- * @remarks
- * `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
- * `1` / `0`, a number as-is, a string as-is), so the operand must encode to that
- * same scalar to compare. A boolean → `'boolean'` (→ `1` / `0`); a number →
- * `'integer'` / `'real'`; a bigint → `'integer'`; a string → `'text'`; `null` /
- * `undefined` → `'text'` (encodes to `null`); an object / array → `'json'` (the
- * edge of comparing against a json subtree).
- *
- * @param value - The runtime operand value
- * @returns The {@link ColumnType} to encode it as
- *
- * @example
- * ```ts
- * valueType(true) // 'boolean'
- * valueType(9) // 'integer'
- * ```
- */
-export declare function valueType(value: unknown): ColumnType;
-
 export { }