@orkestrel/database 0.0.12 → 0.0.14

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

@@ -1,29 +1,24 @@
-import { AggregateOperation } from '@orkestrel/database';
-import { AggregateOperation as AggregateOperation_2 } from '@orkestrel/database';
-import { ColumnSchema } from '@orkestrel/database';
-import { ColumnStorage } from '@orkestrel/database';
-import { Condition } from '@orkestrel/database';
-import { DriverInterface } from '@orkestrel/database';
-import { DriverInterface as DriverInterface_2 } from '@orkestrel/database';
-import { DriverMetadata } from '@orkestrel/database';
-import { FieldPath } from '@orkestrel/contract';
-import { Key } from '@orkestrel/database';
-import { MigrationInput } from '@orkestrel/database';
-import { MigrationStep } from '@orkestrel/database';
-import { OperationOptions } from '@orkestrel/database';
-import { Order } from '@orkestrel/database';
-import { QueryInput } from '@orkestrel/database';
-import { QueryInput as QueryInput_2 } from '@orkestrel/database';
-import { Row } from '@orkestrel/database';
-import { Row as Row_2 } from '@orkestrel/database';
-import { SQLiteRow } from '@orkestrel/sqlite';
-import { SQLiteValue } from '@orkestrel/sqlite';
-import { StorageInterface } from '@orkestrel/database';
-import { TableSchema } from '@orkestrel/database';
-import { TableSchema as TableSchema_2 } from '@orkestrel/database';
-
-/**
- * Compile an {@link AggregateOperation} over a {@link FieldPath}.
+import type { AggregateOperation } from '@orkestrel/database';
+import type { ColumnSchema } from '@orkestrel/database';
+import type { ColumnStorage } from '@orkestrel/database';
+import type { Condition } from '@orkestrel/database';
+import type { DriverInterface } from '@orkestrel/database';
+import type { DriverMetadata } from '@orkestrel/database';
+import type { FieldPath } from '@orkestrel/contract';
+import type { Key } from '@orkestrel/database';
+import type { MigrationInput } from '@orkestrel/database';
+import type { MigrationStep } from '@orkestrel/database';
+import type { OperationOptions } from '@orkestrel/database';
+import type { Order } from '@orkestrel/database';
+import type { QueryInput } from '@orkestrel/database';
+import type { Row } from '@orkestrel/database';
+import type { SQLiteRow } from '@orkestrel/sqlite';
+import type { SQLiteValue } from '@orkestrel/sqlite';
+import type { StorageInterface } from '@orkestrel/database';
+import type { TableSchema } from '@orkestrel/database';
+
+/**
+ * Compiles an {@link AggregateOperation} over a {@link FieldPath}.
  *
  * @param operation - The aggregate to compute
  * @param column - The column or nested path to aggregate
@@ -32,7 +27,7 @@ import { TableSchema as TableSchema_2 } from '@orkestrel/database';
 export declare function compileAggregateSQL(operation: AggregateOperation, column: FieldPath): string;
 
 /**
- * Map a portable {@link ColumnStorage} to its SQLite column type.
+ * Maps a portable {@link ColumnStorage} to its SQLite column type.
  *
  * @param storage - The portable column type
  * @returns The SQLite column type keyword
@@ -40,25 +35,25 @@ export declare function compileAggregateSQL(operation: AggregateOperation, colum
 export declare function compileColumnSQL(storage: ColumnStorage): string;
 
 /**
- * Compile one condition to its `<column> <operator>` SQL fragment and the parameters
+ * Compiles one condition to its `<column> <operator>` SQL fragment and the parameters
  * 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
+ * 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
+ * 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.
  *
- * The core engine's total order ranks `undefined` (rank 0) BELOW `null`
- * (rank 1) (see `compareValues`), so a MISSING/`NULL` column MATCHES
+ * 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
+ * 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
@@ -84,15 +79,15 @@ export declare function compileColumnSQL(storage: ColumnStorage): string;
  * 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
+ * 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
+ * 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.
  *
@@ -111,7 +106,8 @@ export declare function compileColumnSQL(storage: ColumnStorage): string;
 export declare function compileConditionSQL(condition: Condition, schema: TableSchema): CompiledSQL;
 
 /**
- * A parameterized SQL fragment or statement plus its bind values.
+ * Represents a parameterized SQL fragment or statement plus its bind values. The
+ * `@orkestrel/database/server` entry point exports this type.
  *
  * @remarks
  * Produced by the pure SQL compilers (`compilers.ts`) that turn a core
@@ -126,7 +122,11 @@ export declare interface CompiledSQL {
 }
 
 /**
- * Compile a {@link FieldPath} to the SQL expression that reads it.
+ * Compiles a {@link FieldPath} to the SQL expression that reads it.
+ *
+ * @remarks
+ * A flat path compiles to the quoted column; a nested path compiles to a
+ * `json_extract` over the head column with the rest of the path as its accessor.
  *
  * @param path - The field path
  * @returns The SQL expression selecting the value
@@ -134,9 +134,9 @@ export declare interface CompiledSQL {
 export declare function compileFieldSQL(path: FieldPath): string;
 
 /**
- * Compile a NESTED {@link FieldPath} to the `json_type(<col>, <path>)` SQL
+ * Compiles 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`
+ * 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).
  *
@@ -151,14 +151,14 @@ export declare function compileFieldSQL(path: FieldPath): string;
 export declare function compileJSONTypeSQL(path: readonly string[]): string;
 
 /**
- * Compile the ORDER BY clause from the order terms, always ending with the
+ * Compiles the ORDER BY clause from the order terms, always ending with the
  * primary key as the final determinant.
  *
  * @remarks
  * The native `records` read then resolves ties in key order, matching a
  * primary-key-ordered `scan` and the core engine's stable `sortRows` over a
  * key-ordered scan (and IndexedDB's key-ordered reads), so a native read equals
- * the scan path (AGENTS §21 / §22 native ↔ engine parity). SQLite without an
+ * the scan path — native ↔ engine parity. SQLite without an
  * `ORDER BY` returns rowid (insertion) order, and an explicit order alone breaks
  * ties by rowid too — both diverge from every key-ordered backend. The
  * tie-breaker is ASCENDING regardless of the explicit directions: the engine's
@@ -172,14 +172,14 @@ export declare function compileJSONTypeSQL(path: readonly string[]): string;
  *
  * @example
  * ```ts
- * compileOrder([{ column: 'age', direction: 'descending' }], schema)
+ * compileOrderSQL([{ column: 'age', direction: 'descending' }], schema)
  * // 'ORDER BY "age" DESC, "id"'
  * ```
  */
-export declare function compileOrder(order: readonly Order[] | undefined, schema: TableSchema): string;
+export declare function compileOrderSQL(order: readonly Order[] | undefined, schema: TableSchema): string;
 
 /**
- * Compile the LIMIT / OFFSET clause.
+ * Compiles the LIMIT / OFFSET clause.
  *
  * @remarks
  * An offset without a limit uses `LIMIT -1` (SQLite's "no limit") so OFFSET is
@@ -191,13 +191,13 @@ export declare function compileOrder(order: readonly Order[] | undefined, schema
  *
  * @example
  * ```ts
- * compilePage(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', parameters: [5] }
+ * compilePageSQL(undefined, 5) // { sql: 'LIMIT -1 OFFSET ?', parameters: [5] }
  * ```
  */
-export declare function compilePage(limit: number | undefined, offset: number | undefined): CompiledSQL;
+export declare function compilePageSQL(limit: number | undefined, offset: number | undefined): CompiledSQL;
 
 /**
- * Compile a {@link QueryInput} into the SQL clause that follows a table name, with
+ * Compiles a {@link QueryInput} into the SQL clause that follows a table name, with
  * its bound parameters in clause order.
  *
  * @remarks
@@ -207,11 +207,13 @@ export declare function compilePage(limit: number | undefined, offset: number |
  * 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
+ * through `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
+ * Every operator maps per the databases guide's operator table, with
+ * `starts` / `ends` compiling to a code-point `substr` slice guarded by
+ * `typeof(<column>) = 'text'` (case-sensitive, matching the engine's
+ * `String.prototype.startsWith` / `endsWith`) and an empty `any` / `none` list
  * collapsing to a constant. An `undefined` input (or one with no parts)
  * compiles to an empty clause.
  *
@@ -228,13 +230,13 @@ export declare function compilePage(limit: number | undefined, offset: number |
 export declare function compileQuerySQL(input: QueryInput | undefined, schema: TableSchema): CompiledSQL;
 
 /**
- * Fold the conditions into one WHERE clause, parenthesizing progressively
+ * Folds the conditions into one WHERE clause, parenthesizing progressively
  * 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 compileConditionSQL}'s truth table) replicates the core
- * engine's total order EXACTLY under SQL's three-valued NULL logic, so this
+ * engine's total order exactly under SQL's three-valued NULL logic, so this
  * clause matches `applyQuery` row-for-row over the same table — a native
  * `records` / `count` read never disagrees with a scan-and-filter fallback.
  *
@@ -244,14 +246,14 @@ export declare function compileQuerySQL(input: QueryInput | undefined, schema: T
  *
  * @example
  * ```ts
- * compileWhere([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
+ * compileWhereSQL([{ column: 'age', operator: 'from', values: [18], connector: 'and' }], schema)
  * // { sql: 'WHERE "age" >= ?', parameters: [18] }
  * ```
  */
-export declare function compileWhere(conditions: readonly Condition[], schema: TableSchema): CompiledSQL;
+export declare function compileWhereSQL(conditions: readonly Condition[], schema: TableSchema): CompiledSQL;
 
 /**
- * Create a persistent JSON-file {@link DriverInterface} for the core database layer.
+ * Creates a persistent JSON-file {@link DriverInterface} for a given path.
  *
  * @remarks
  * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
@@ -259,9 +261,10 @@ export declare function compileWhere(conditions: readonly Condition[], schema: T
  * `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` /
- * `aggregate`). A missing, corrupt, or wrong-shaped file starts empty rather than
- * throwing.
+ * the core engine's `matchesQuery`. The driver implements the native `stream`
+ * hook and neither `records` nor `aggregate`, so the engine answers every query
+ * on either path. A missing, corrupt, or wrong-shaped file starts empty rather
+ * than throwing.
  *
  * @param path - The JSON file path data is loaded from and flushed to
  * @returns A {@link DriverInterface} backed by a JSON file
@@ -282,7 +285,8 @@ export declare function compileWhere(conditions: readonly Condition[], schema: T
 export declare function createJSONDriver(path: string): DriverInterface;
 
 /**
- * Create a trusted-mode SQLite {@link DriverInterface} for the core database layer.
+ * Creates a trusted-mode, server-native SQLite {@link DriverInterface} for a database path,
+ * or for `:memory:` when the options bag omits one.
  *
  * @remarks
  * Pass it to `createDatabase` from `@orkestrel/database` to run the typed
@@ -320,7 +324,7 @@ export declare function createJSONDriver(path: string): DriverInterface;
 export declare function createSQLiteDriver(options?: SQLiteDriverOptions): DriverInterface;
 
 /**
- * Decode a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
+ * Decodes a stored {@link SQLiteRow} back to a {@link Row} by its table's schema.
  *
  * @remarks
  * Decodes each declared column with {@link decodeValue} and **omits** any column
@@ -341,7 +345,7 @@ export declare function createSQLiteDriver(options?: SQLiteDriverOptions): Drive
 export declare function decodeRow(row: SQLiteRow, schema: TableSchema): Row;
 
 /**
- * Decode a stored {@link SQLiteValue} back to its JS value for a declared column —
+ * Decodes a stored {@link SQLiteValue} back to its JS value for a declared column —
  * the exact inverse of {@link encodeValue}.
  *
  * @remarks
@@ -363,12 +367,12 @@ export declare function decodeRow(row: SQLiteRow, schema: TableSchema): Row;
 export declare function decodeValue(value: SQLiteValue, column: ColumnSchema): unknown;
 
 /**
- * Build a collision-free SQL index name for a table + column-group index —
+ * Builds 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
+ * 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
@@ -388,7 +392,7 @@ export declare function decodeValue(value: SQLiteValue, column: ColumnSchema): u
 export declare function deriveSQLiteIndexName(table: string, columns: readonly string[]): string;
 
 /**
- * Encode a whole {@link Row} to a {@link SQLiteRow} by its table's schema.
+ * Encodes a whole {@link Row} to a {@link SQLiteRow} by its table's schema.
  *
  * @remarks
  * Encodes each declared column's value with {@link encodeValue}; columns the row
@@ -407,7 +411,7 @@ export declare function deriveSQLiteIndexName(table: string, columns: readonly s
 export declare function encodeRow(row: Row, schema: TableSchema): SQLiteRow;
 
 /**
- * Encode a JS value to its stored {@link SQLiteValue} for a declared column.
+ * Encodes a JS value to its stored {@link SQLiteValue} for a declared column.
  *
  * @remarks
  * The codec is total: a malformed value encodes to SQL `NULL`. Absence always
@@ -428,42 +432,28 @@ export declare function encodeRow(row: Row, schema: TableSchema): SQLiteRow;
 export declare function encodeValue(value: unknown, column: ColumnSchema): SQLiteValue;
 
 /**
- * Escape `\`, `%`, and `_` (each with a leading `\`) so a `starts` / `ends`
- * operand is matched literally under the `LIKE … ESCAPE '\'` clause.
- *
- * @param text - The raw operand text
- * @returns The text with LIKE metacharacters escaped
- *
- * @example
- * ```ts
- * escapeLike('50%_off') // '50\\%\\_off'
- * ```
- */
-export declare function escapeLike(text: string): string;
-
-/**
- * The declared {@link ColumnStorage}s whose SQL EQUALITY comparisons (`equals` /
+ * Lists 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.
  *
  * @remarks
- * This set governs equality and prefix/suffix matching only. RANGE
+ * This set governs equality and prefix/suffix matching only. Range
  * comparisons (`above` / `below` / `from` / `to` / `between`) and `ORDER BY`
- * are exact for `integer` / `real` / `boolean` but NOT for `text`: compiled
+ * are exact for `integer` / `real` / `boolean` but not for `text`: compiled
  * SQL orders/ranges under SQLite's default BINARY collation, which compares
- * TEXT byte-for-byte as UTF-8 — equivalent to Unicode CODE-POINT order —
+ * TEXT byte-for-byte as UTF-8 — equivalent to Unicode code-point order —
  * while the core engine's `compareValues` orders JS strings with `<`, which
- * 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 `matchesConditionExactly`'s range family and
+ * compares UTF-16 code-unit order. The two orders diverge for supplementary-
+ * plane characters (code points ≥ U+10000, for example many emoji): a lead surrogate
+ * (`\uD800`–`\uDBFF`) sorts below ``–`￿` in code-unit order, while
+ * 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_STORAGE: readonly ColumnStorage[];
 
 /**
- * The declared {@link ColumnStorage}s whose SQL RANGE comparisons
+ * Lists 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_STORAGE}'s remarks for the BINARY-collation
@@ -473,7 +463,7 @@ export declare const EXACT_COLUMN_STORAGE: readonly ColumnStorage[];
 export declare const EXACT_RANGE_COLUMN_STORAGE: readonly ColumnStorage[];
 
 /**
- * Extract a stored row's values in a declared positional order.
+ * Extracts a stored row's values in a declared positional order.
  *
  * @remarks
  * SQLite statements bind arrays positionally. Every requested column must be
@@ -494,22 +484,8 @@ export declare const EXACT_RANGE_COLUMN_STORAGE: readonly ColumnStorage[];
 export declare function extractValues(row: SQLiteRow, names: readonly string[], table: string): readonly SQLiteValue[];
 
 /**
- * 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 ColumnStorage}, or `undefined` if the schema does not carry it
- *
- * @example
- * ```ts
- * findColumnStorage('age', schema) // 'integer'
- * ```
- */
-export declare function findColumnStorage(column: string, schema: TableSchema): ColumnStorage | undefined;
-
-/**
- * The storage type a nested (`json_extract`) operand encodes as, derived from its
- * RUNTIME value — NOT `json`.
+ * Reads the storage type a nested (`json_extract`) operand encodes as from its
+ * runtime value, never as `json`.
  *
  * @remarks
  * `json_extract` returns the unquoted, natively-typed scalar (a JSON boolean as
@@ -531,7 +507,7 @@ export declare function findColumnStorage(column: string, schema: TableSchema):
 export declare function inferValueStorage(value: unknown): ColumnStorage;
 
 /**
- * A persistent {@link DriverInterface} backed by a single JSON file — the
+ * Implements a persistent {@link DriverInterface} backed by a single JSON file — the
  * reference {@link MemoryDriver} plus file load / flush.
  *
  * @remarks
@@ -545,15 +521,15 @@ export declare function inferValueStorage(value: unknown): ColumnStorage;
  * 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 read that reports no document there starts empty —
+ * never asserted. 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.
+ * automatic repair. It implements the optional native `stream` hook that
+ * `TableInterface.scan` prefers over `scan`, and neither `records` nor
+ * `aggregate`, so the core engine's `matchesQuery` answers every query on
+ * either path. For development, small datasets, and portable / inspectable
+ * data; for large or concurrent workloads reach for a SQLite-backed driver.
  *
  * Metadata crosses {@link cloneDriverMetadata} at parsed-file ingress, public and
  * scoped write ingress, candidate/root publication, serialization, and copy-out.
@@ -566,19 +542,19 @@ export declare function inferValueStorage(value: unknown): ColumnStorage;
  * 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 {
+export declare class JSONDriver implements DriverInterface {
     #private;
     constructor(path: string);
-    open(schema: readonly TableSchema_2[]): Promise<void>;
+    open(schema: readonly TableSchema[]): Promise<void>;
     close(): Promise<void>;
-    read(table: string, key: Key): Promise<Row_2 | undefined>;
-    write(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
-    insert(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
+    insert(table: string, key: Key, row: Row, 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>;
+    scan(table: string): AsyncIterable<Row>;
     /**
-     * Natively filtered lazy iteration — delegates to the inner {@link MemoryDriver}.
+     * Iterates rows lazily with native filtering — delegates to the inner {@link MemoryDriver}.
      *
      * @remarks
      * Semantics are the memory driver's own: `input.conditions` filters, `offset`
@@ -588,10 +564,10 @@ export declare class JSONDriver implements DriverInterface_2 {
      * @param table - The table to stream
      * @param input - The filter / offset / limit to apply lazily
      */
-    stream(table: string, input: QueryInput_2): AsyncIterable<Row_2>;
+    stream(table: string, input: QueryInput): AsyncIterable<Row>;
     clear(table: string): Promise<void>;
     /**
-     * Run an isolated native transaction callback over a candidate memory store.
+     * Runs an isolated native transaction callback over a candidate memory store.
      *
      * @remarks
      * Single-writer: nesting and root operations while active throw `CONFLICT`.
@@ -605,7 +581,7 @@ export declare class JSONDriver implements DriverInterface_2 {
      */
     transaction<R>(scope: (storage: StorageInterface) => Promise<R>): Promise<R>;
     /**
-     * Capture an owned row snapshot at an exact writer-queue position.
+     * Captures an owned row snapshot at an exact writer-queue position.
      *
      * @remarks
      * Capture owns table names, schemas, rows, and one session-local identity per
@@ -621,7 +597,7 @@ export declare class JSONDriver implements DriverInterface_2 {
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
     metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist an owned metadata snapshot for a later `metadata()` to copy out.
+     * Persists an owned metadata snapshot for a later `metadata()` to copy out.
      *
      * @remarks
      * Root stamping conflicts while a transaction is active. The scoped
@@ -632,7 +608,7 @@ export declare class JSONDriver implements DriverInterface_2 {
      */
     stamp(metadata: DriverMetadata): Promise<void>;
     /**
-     * Apply one atomic {@link MigrationInput} through an isolated candidate.
+     * Applies one atomic {@link MigrationInput} through an isolated candidate.
      *
      * @remarks
      * The candidate receives every plan step plus optional metadata. Its complete
@@ -646,7 +622,7 @@ export declare class JSONDriver implements DriverInterface_2 {
 }
 
 /**
- * Whether a caught filesystem error reports that nothing is there to read.
+ * Reports whether a caught filesystem error says that nothing is there to read.
  *
  * @remarks
  * Two codes carry that meaning: `ENOENT` is a plain absence, and `ENOTDIR` is a
@@ -663,7 +639,7 @@ export declare class JSONDriver implements DriverInterface_2 {
  * 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
+ * @returns True if the error reports that the path holds nothing; false otherwise
  *
  * @example
  * ```ts
@@ -675,19 +651,19 @@ export declare class JSONDriver implements DriverInterface_2 {
 export declare function matchesAbsentPath(error: unknown): boolean;
 
 /**
- * Determine whether SQLite can execute an aggregate exactly like the core engine.
+ * Reports 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
+ * @returns True if native aggregation is exact; false otherwise
  */
 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.
+ * Reports 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`.
@@ -699,88 +675,95 @@ export declare function matchesAggregateExactly(operation: AggregateOperation, c
  * 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,
+ * `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
+ * `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
+ * 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
+ * @returns True if `condition` is exact; false otherwise
  */
 export declare function matchesConditionExactly(condition: Condition, schema: TableSchema): boolean;
 
 /**
- * Whether a value's runtime type matches a column's declared exact type —
- * the operand side of the declared-type-trust proof.
+ * Reports whether a value's runtime type matches a column's declared exact type
+ * — the operand side of the declared-type-trust proof.
  *
  * @remarks
- * `text` ↔ string, `integer` / `real` ↔ FINITE number (`NaN` / `±Infinity`
+ * `text` ↔ string, `integer` / `real` ↔ finite number (`NaN` / `±Infinity`
  * fail), `boolean` ↔ boolean. Backs {@link matchesConditionExactly}'s operand checks.
  *
  * @param value - The condition operand to test
- * @param type - The column's declared portable type
- * @returns `true` when the operand's runtime type matches the declared type
+ * @param storage - The column's declared portable storage type
+ * @returns True if the operand's runtime type matches the declared type; false otherwise
  *
  * @example
  * ```ts
- * matchesDeclaredType('Ada', 'text') // true
- * matchesDeclaredType(Number.NaN, 'integer') // false — only finite numbers
+ * matchesDeclaredStorage('Ada', 'text') // true
+ * matchesDeclaredStorage(Number.NaN, 'integer') // false — only finite numbers
  * ```
  */
 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.
+ * Reports whether one {@link Order} term's column compiles to an `ORDER BY`
+ * that matches the engine's {@link import('@orkestrel/database').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
+ * `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.
+ * a `text` order term refines through the core engine instead. The column must
+ * also be required and non-null: an optional or nullable column refines, because
+ * SQL orders its `NULL`s ahead of every value while the core total order ranks
+ * `undefined` before `null` before every other value.
  *
  * @param order - The order term to test
  * @param schema - The table's schema
- * @returns Whether `order` is exact
+ * @returns True if `order` is exact; false otherwise
  */
 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).
+ * Reports 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).
+ *
+ * @remarks
+ * The gate {@link import('./drivers/SQLiteDriver.js').SQLiteDriver} checks before
+ * trusting a native SQL read over a full-scan refine through the core engine.
  *
  * @param input - The query input to test
  * @param schema - The table's schema
- * @returns Whether every part of `input` is exact
+ * @returns True if every part of `input` is exact; false otherwise
  */
 export declare function matchesQueryExactly(input: QueryInput, schema: TableSchema): boolean;
 
 /**
- * Test a declared SQLite type against a portable storage affinity.
+ * Checks 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
+ * @returns True if SQLite's official affinity rules yield the expected affinity; false otherwise
  */
 export declare function matchesSQLiteAffinity(declared: unknown, storage: ColumnStorage): boolean;
 
 /**
- * The reserved metadata table the {@link SQLiteDriver} creates on `open` to
+ * Names the reserved metadata table the {@link SQLiteDriver} creates on `open` to
  * persist its stamped `DriverMetadata` (`version` + declared schema JSON) — the
  * SQLite realization of the `metadata` / `stamp` driver hooks.
  *
@@ -791,7 +774,7 @@ export declare function matchesSQLiteAffinity(declared: unknown, storage: Column
 export declare const METADATA_TABLE = "_metadata";
 
 /**
- * Quote a SQL identifier (a table or column name) so any characters are literal.
+ * Quotes a SQL identifier (a table or column name) so any characters are literal.
  *
  * @remarks
  * Wraps the name in double quotes and doubles any embedded quote — the standard
@@ -809,7 +792,11 @@ export declare const METADATA_TABLE = "_metadata";
 export declare function quoteIdentifier(identifier: string): string;
 
 /**
- * Project a {@link TableSchema} to its declared SQLite indexes.
+ * Projects a {@link TableSchema} to its declared SQLite indexes.
+ *
+ * @remarks
+ * Each statement is a `CREATE INDEX IF NOT EXISTS` named by
+ * {@link deriveSQLiteIndexName}, so a reopen re-issues the set safely.
  *
  * @param schema - The table schema
  * @returns One statement per declared index
@@ -817,7 +804,7 @@ export declare function quoteIdentifier(identifier: string): string;
 export declare function schemaToIndexes(schema: TableSchema): readonly string[];
 
 /**
- * Project a {@link TableSchema} to its `CREATE TABLE IF NOT EXISTS` statement.
+ * Projects a {@link TableSchema} to its `CREATE TABLE IF NOT EXISTS` statement.
  *
  * @param schema - The table schema
  * @returns The complete table declaration
@@ -825,8 +812,8 @@ export declare function schemaToIndexes(schema: TableSchema): readonly string[];
 export declare function schemaToTable(schema: TableSchema): string;
 
 /**
- * The SQLite {@link DriverInterface} — the server-native, trusted-mode backend
- * built on the published `@orkestrel/sqlite` synchronous wrapper.
+ * Implements the {@link DriverInterface} over SQLite — the server-native, trusted-mode
+ * backend built on the published `@orkestrel/sqlite` synchronous wrapper.
  *
  * @remarks
  * A thin adapter: it implements the storage primitives the core database layer
@@ -837,59 +824,58 @@ export declare function schemaToTable(schema: TableSchema): string;
  * 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
+ * (`json` columns store / parse JSON text, a `boolean` stores `1` / `0`), so
+ * the typed layer above imposes the exact shape. `write` is an
  * `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
- * atomically either way, an improvement over the non-atomic `MemoryDriver` /
- * `JSONDriver` migrate; a step referencing an undeclared table throws
+ * 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` (through
+ * `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.transact` otherwise — a mid-plan failure rolls
+ * back atomically either way, an improvement over the non-atomic `MemoryDriver`
+ * / `JSONDriver` migrate; a step referencing an undeclared table throws
  * `DatabaseError` `MIGRATION` before any DDL for that step runs. `snapshot` is
- * capture-replay (SELECT the
- * named tables' rows, replay via DELETE + INSERT OR REPLACE inside a native
- * transaction on rollback) rather than a SQL `SAVEPOINT`, since the core
- * `transaction` calls the rollback thunk only on failure with no commit-on-
- * success signal — a long-lived `SAVEPOINT` would leave the connection
- * uncommitted (lost on close). Every backend interaction runs through `#guard`,
- * which maps a thrown backend `SQLiteError` (or any unexpected non-`SQLiteError`
- * throw) to a typed {@link DatabaseError} — never a raw backend error escapes
- * `DriverInterface`: `CONSTRAINT` → `CONFLICT`, the wrapper's own `CLOSED` →
- * `CLOSED`, `BUSY` (a locked database that outlasted the configured `timeout`)
- * → a retryable `DRIVER` (`context.retryable` is `true`), and `UNKNOWN` / any
- * other throw → `DRIVER`. The original error is preserved as `context.cause`.
- * A `DatabaseError` this driver throws directly (`CLOSED` from the `#require`
- * gate, `NOT_FOUND` from `#table`, `MIGRATION` from a migration-plan fault)
- * passes through `#guard` unchanged, never re-wrapped.
- */
-export declare class SQLiteDriver implements DriverInterface_2 {
+ * capture-replay (SELECT the named tables' rows, replay through DELETE + INSERT OR
+ * REPLACE inside a native transaction on rollback) rather than a SQL
+ * `SAVEPOINT`, since the core `transaction` calls the rollback thunk only on
+ * failure with no commit-on-success signal — a long-lived `SAVEPOINT` would
+ * leave the connection uncommitted (lost on close). Every backend interaction
+ * runs through `#guard`, which maps a thrown backend `SQLiteError` (or any
+ * unexpected non-`SQLiteError` throw) to a typed {@link DatabaseError} — never
+ * a raw backend error escapes `DriverInterface`: `CONSTRAINT` → `CONFLICT`, the
+ * wrapper's own `CLOSED` → `CLOSED`, `BUSY` (a locked database that outlasted
+ * the configured `timeout`) → a retryable `DRIVER` (`context.retryable` is
+ * `true`), and `UNKNOWN` / any other throw → `DRIVER`. The original error is
+ * preserved as `context.cause`. A `DatabaseError` this driver throws directly
+ * (`CLOSED` from the `#require` gate, `NOT_FOUND` from `#table`, `MIGRATION`
+ * from a migration-plan fault) passes through `#guard` unchanged, never
+ * re-wrapped.
+ */
+export declare class SQLiteDriver implements DriverInterface {
     #private;
     constructor(options?: SQLiteDriverOptions);
-    open(schema: readonly TableSchema_2[]): Promise<void>;
+    open(schema: readonly TableSchema[]): Promise<void>;
     close(): Promise<void>;
-    read(table: string, key: Key): Promise<Row_2 | undefined>;
-    write(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
-    insert(table: string, key: Key, row: Row_2, options?: OperationOptions): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
+    insert(table: string, key: Key, row: Row, 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>;
+    scan(table: string): AsyncIterable<Row>;
     clear(table: string): Promise<void>;
-    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>;
+    records(table: string, input: QueryInput): Promise<readonly Row[]>;
+    aggregate(table: string, operation: AggregateOperation, column: FieldPath, input: QueryInput): Promise<number | undefined>;
+    stream(table: string, input: QueryInput): AsyncIterable<Row>;
     /**
-     * Begin a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
+     * Begins a native transaction — real `BEGIN`, `COMMIT`, `ROLLBACK`.
      *
      * @remarks
      * The callback receives a scoped {@link StorageInterface}. Fulfillment
@@ -901,23 +887,22 @@ export declare class SQLiteDriver implements DriverInterface_2 {
      */
     transaction<R>(scope: (storage: StorageInterface) => Promise<R>): Promise<R>;
     /**
-     * Apply a {@link Migration} plan by executing each step's projected DDL
+     * Applies a {@link Migration} plan by executing each step's projected DDL
      * ({@link import('../compilers.js').stepToSQL}).
      *
      * @remarks
-     * Atomicity is provided by whichever native transaction is active: when
-     * 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 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
+     * Atomicity is provided by whichever native transaction is active: when 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 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 scoped migration
      * uses one fixed internal savepoint literal because the published SQLite
-     * wrapper intentionally exposes raw `exec` but no savepoint manager. That
+     * wrapper intentionally exposes raw `execute` 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
@@ -928,14 +913,14 @@ export declare class SQLiteDriver implements DriverInterface_2 {
      */
     migrate(input: MigrationInput): Promise<void>;
     /**
-     * Read the persisted {@link DriverMetadata} from the reserved `_metadata` table.
+     * Reads the persisted {@link DriverMetadata} from the reserved `_metadata` table.
      *
      * @returns The last-stamped `DriverMetadata`, or `undefined` when never stamped
      *   (or the stored row is malformed)
      */
     metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist an owned metadata snapshot into the reserved `_metadata` table's
+     * Persists an owned metadata snapshot into the reserved `_metadata` table's
      * single row.
      *
      * @param metadata - The {@link DriverMetadata} to persist
@@ -945,7 +930,8 @@ export declare class SQLiteDriver implements DriverInterface_2 {
 }
 
 /**
- * Options for {@link import('./factories.js').createSQLiteDriver}.
+ * Configures {@link import('./factories.js').createSQLiteDriver}. The
+ * `@orkestrel/database/server` entry point exports this type.
  *
  * @remarks
  * Threaded into the underlying `@orkestrel/sqlite` wrapper's connection.
@@ -954,11 +940,11 @@ export declare class SQLiteDriver implements DriverInterface_2 {
  * {@link DatabaseError}); `timeout` is the busy-timeout in milliseconds before
  * 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
- * beyond `Number.MAX_SAFE_INTEGER` reads back imprecisely (the wrapper's own
+ * `pragmas` is an ordered record of PRAGMA name to value, applied through the
+ * wrapper's `pragma()` right after `connect()`, in insertion order (for
+ * example `{ journal_mode: 'WAL' }`). Core rows are number-typed — this driver
+ * never surfaces a `bigint`, so a stored integer beyond
+ * `Number.MAX_SAFE_INTEGER` reads back imprecisely (the wrapper's own
  * `bigints` option is not exposed here).
  */
 export declare interface SQLiteDriverOptions {
@@ -970,7 +956,11 @@ export declare interface SQLiteDriverOptions {
 }
 
 /**
- * Project one {@link MigrationStep} to SQLite DDL.
+ * Projects one {@link MigrationStep} to SQLite DDL.
+ *
+ * @remarks
+ * These are the statements the SQLite driver's `migrate` executes for the step,
+ * inside whichever native transaction is active.
  *
  * @param step - The migration step
  * @returns The statements that apply the step