@orkestrel/database 0.0.1 → 0.0.3

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

@@ -1,11 +1,1766 @@
-export type * from './types.js';
-export * from './constants.js';
-export * from './errors.js';
-export * from './helpers.js';
-export * from './factories.js';
-export * from './Database.js';
-export * from './drivers/MemoryDriver.js';
-export * from './Table.js';
-export * from './Query.js';
-export * from './Clause.js';
-export * from './Cursor.js';
+import { ContractInterface } from '@orkestrel/contract';
+import { ContractShape } from '@orkestrel/contract';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { FieldPath } from '@orkestrel/contract';
+import { Infer } from '@orkestrel/contract';
+import { JSONSchema } from '@orkestrel/contract';
+import { RandomFunction } from '@orkestrel/contract';
+
+/** An aggregate computed over a numeric column. */
+export declare type AggregateFunction = 'count' | 'sum' | 'average' | 'minimum' | 'maximum';
+
+/**
+ * Apply a {@link Criteria} to rows — filter, then sort, then page.
+ *
+ * @remarks
+ * The whole portable read pipeline in one place: conditions filter, `order`
+ * sorts, and `offset` / `limit` window the result. Each step is skipped when its
+ * part of the criteria is absent. The reference {@link DriverInterface} backends
+ * lean on this rather than each re-deriving it.
+ *
+ * @param rows - The rows to process (typically a table's full `scan`)
+ * @param criteria - The read specification, or `undefined` for all rows as-is
+ * @returns The filtered, sorted, paged rows
+ */
+export declare function applyCriteria(rows: readonly Row[], criteria?: Criteria): readonly Row[];
+
+/**
+ * Run the FULL driver-conformance battery and collect every violation — the
+ * audit entry point for a driver author who wants a complete report rather
+ * than a single fail-fast throw.
+ *
+ * @remarks
+ * Drains {@link driverFindings} to completion: every phase runs regardless
+ * of earlier violations, so a driver breaking two independent invariants
+ * reports both. An empty array means the driver is fully conformant.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @returns Every violated invariant found, in phase order (empty when fully conformant)
+ *
+ * @example
+ * ```ts
+ * import { auditDriver, createMemoryDriver } from '@orkestrel/database'
+ *
+ * const findings = await auditDriver(() => createMemoryDriver())
+ * for (const finding of findings) console.log(`${finding.check}: ${finding.message}`)
+ * ```
+ */
+export declare function auditDriver(factory: () => DriverInterface): Promise<readonly ConformanceFinding[]>;
+
+/**
+ * Throw when an {@link ReadOptions.signal | AbortSignal} has fired — the shared
+ * cancellation gate checked at operation boundaries and between streamed rows.
+ *
+ * @remarks
+ * A no-op for `undefined` or a live signal, so callers thread `options?.signal`
+ * straight through. When the signal has aborted, throws an `ABORTED`
+ * {@link DatabaseError} carrying the signal's `reason` in its context — callers
+ * mint signals with whatever tool they like (`AbortSignal.timeout(ms)`,
+ * `new AbortController()`, `@orkestrel/abort`).
+ *
+ * @param signal - The signal to check, if any
+ * @returns Nothing — returns normally while the signal is live
+ * @throws An `ABORTED` {@link DatabaseError} when the signal has aborted
+ *
+ * @example
+ * ```ts
+ * import { checkAbort } from '@orkestrel/database'
+ *
+ * const controller = new AbortController()
+ * checkAbort(controller.signal) // returns
+ * controller.abort('too slow')
+ * checkAbort(controller.signal) // throws DatabaseError('ABORTED', …)
+ * ```
+ */
+export declare function checkAbort(signal: AbortSignal | undefined): void;
+
+/**
+ * A pending condition opened by a query's `where` / `and` / `or`.
+ *
+ * @remarks
+ * Holds the column, the connector that will join this condition to the ones
+ * before it, and a recorder the owning query supplies. Each operator builds the
+ * {@link Condition}, hands it to the recorder, and returns the query — so the
+ * fluent chain flows straight back into the builder without exposing a mutator.
+ */
+export declare class Clause<T = Record<string, unknown>> implements ClauseInterface<T> {
+    #private;
+    constructor(record: (condition: Condition) => QueryInterface<T>, column: FieldPath, connector: Connector);
+    equals(value: unknown): QueryInterface<T>;
+    not(value: unknown): QueryInterface<T>;
+    above(value: unknown): QueryInterface<T>;
+    below(value: unknown): QueryInterface<T>;
+    from(value: unknown): QueryInterface<T>;
+    to(value: unknown): QueryInterface<T>;
+    between(lower: unknown, upper: unknown): QueryInterface<T>;
+    like(pattern: string): QueryInterface<T>;
+    glob(pattern: string): QueryInterface<T>;
+    starts(prefix: string): QueryInterface<T>;
+    ends(suffix: string): QueryInterface<T>;
+    any(values: readonly unknown[]): QueryInterface<T>;
+    none(values: readonly unknown[]): QueryInterface<T>;
+    absent(): QueryInterface<T>;
+    present(): QueryInterface<T>;
+}
+
+/**
+ * A pending condition opened by `where` / `and` / `or`.
+ *
+ * @remarks
+ * Each operator records its condition against the query and returns the query,
+ * so the chain continues fluently. `absent` / `present` take no operand;
+ * `between` takes two; `any` / `none` take a list.
+ */
+export declare interface ClauseInterface<T = Row> {
+    equals(value: unknown): QueryInterface<T>;
+    not(value: unknown): QueryInterface<T>;
+    above(value: unknown): QueryInterface<T>;
+    below(value: unknown): QueryInterface<T>;
+    from(value: unknown): QueryInterface<T>;
+    to(value: unknown): QueryInterface<T>;
+    between(lower: unknown, upper: unknown): QueryInterface<T>;
+    like(pattern: string): QueryInterface<T>;
+    glob(pattern: string): QueryInterface<T>;
+    starts(prefix: string): QueryInterface<T>;
+    ends(suffix: string): QueryInterface<T>;
+    any(values: readonly unknown[]): QueryInterface<T>;
+    none(values: readonly unknown[]): QueryInterface<T>;
+    absent(): QueryInterface<T>;
+    present(): QueryInterface<T>;
+}
+
+/**
+ * One table's columns — a map of column name to its value {@link ContractShape}.
+ *
+ * @remarks
+ * This is exactly the property map an `objectShape` takes. A table row is always
+ * an object, so you write the columns directly (`{ id: stringShape(), … }`) and
+ * the database wraps them in an `objectShape` for you — no redundant `objectShape`
+ * at the table level. (Nested object *columns* still use `objectShape`, since a
+ * column is not always an object.)
+ */
+export declare type Columns = Readonly<Record<string, ContractShape>>;
+
+/**
+ * One column of a {@link TableSchema} — its name, portable {@link ColumnType}, and
+ * whether it is nullable (its shape is `optionalShape` / `nullableShape`).
+ */
+export declare interface ColumnSchema {
+    readonly name: string;
+    readonly type: ColumnType;
+    readonly nullable: boolean;
+}
+
+/**
+ * A portable storage type for a column — the backend maps it to its native type
+ * (SQLite affinity, an IndexedDB value). Derived from a column's `ContractShape`
+ * by `shapeToColumnType`; `json` covers object/array/union/raw values a backend stores
+ * as JSON text and can `json_extract` for nested-field queries.
+ */
+export declare type ColumnType = 'text' | 'integer' | 'real' | 'boolean' | 'json' | 'blob';
+
+/**
+ * A total ordering over arbitrary values — the comparator behind sorting and the
+ * range operators.
+ *
+ * @remarks
+ * Values of different types order by a fixed type rank (`undefined` < `null` <
+ * boolean < number < string < other); same-typed values compare naturally.
+ * `NaN` sorts after every other number and equal to itself, so the comparator
+ * is total and never returns `NaN`.
+ *
+ * @param left - The left value
+ * @param right - The right value
+ * @returns `-1`, `0`, or `1`
+ */
+export declare function compareValues(left: unknown, right: unknown): number;
+
+/**
+ * Compute an aggregate over a column across rows.
+ *
+ * @remarks
+ * `count` returns the row count. The numeric aggregates coerce each cell with
+ * the contracts `parseNumber` (so `'42'` counts) and ignore non-numeric cells;
+ * over zero numeric values they return `undefined` — the SQL `NULL` of an empty
+ * aggregate.
+ *
+ * @param rows - The rows to aggregate (non-record entries are ignored)
+ * @param operation - The aggregate to compute
+ * @param column - The column to aggregate
+ * @returns The aggregate value, or `undefined` when undefined for the inputs
+ */
+export declare function computeAggregate(rows: readonly unknown[], operation: AggregateFunction, column: FieldPath): number | undefined;
+
+/**
+ * One compiled WHERE condition.
+ *
+ * @remarks
+ * `values` carries the operands the operator needs — none for `absent` /
+ * `present`, one for most, two for `between`, a list for `any` / `none`.
+ * `connector` folds this condition into the accumulated result left-to-right;
+ * the first condition's connector seeds the fold and is otherwise ignored.
+ * `column` is a {@link FieldPath}: a single string is ONE column (never split on
+ * `.`), an array descends into a nested (object/`json`) value.
+ */
+export declare interface Condition {
+    readonly column: FieldPath;
+    readonly operator: ConditionOperator;
+    readonly values: readonly unknown[];
+    readonly connector: Connector;
+}
+
+/**
+ * A WHERE operator — the comparison a single {@link Condition} applies.
+ *
+ * @remarks
+ * Each maps to a SQL operator and an IndexedDB read strategy (a key range where
+ * the bounds allow it, a scanned predicate otherwise). The set is closed to
+ * comparisons expressible on both backends.
+ */
+export declare type ConditionOperator = 'equals' | 'not' | 'above' | 'below' | 'from' | 'to' | 'between' | 'like' | 'glob' | 'starts' | 'ends' | 'any' | 'none' | 'absent' | 'present';
+
+/**
+ * One violated invariant from the driver-conformance battery.
+ *
+ * @remarks
+ * Mirrors the payload shape of a `DatabaseError` `CONFORMANCE` `context` —
+ * `check` names the invariant, `message` describes the violation, and
+ * `context` carries the offending table / key / value that failed it.
+ */
+export declare interface ConformanceFinding {
+    readonly check: string;
+    readonly message: string;
+    readonly context: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Run the driver-conformance battery, throwing on the first violated
+ * invariant — the fail-fast entry point most callers (test setup, CI smoke
+ * checks) want.
+ *
+ * @remarks
+ * A thin driver over {@link driverFindings}: because that generator is
+ * lazy, consuming only its first yielded value means every LATER phase
+ * never runs — true fail-fast, not merely "report only the first". The
+ * thrown error is byte-compatible with the historical shape: a
+ * `CONFORMANCE` {@link DatabaseError} whose `message` is the finding's
+ * `message` and whose `context` is `{ check, ...finding.context }`.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @returns Nothing — resolves once every phase has passed
+ * @throws A `CONFORMANCE` {@link DatabaseError} on the first violated invariant
+ *
+ * @example
+ * ```ts
+ * import { conformDriver, createMemoryDriver } from '@orkestrel/database'
+ *
+ * await conformDriver(() => createMemoryDriver()) // resolves when every invariant holds
+ * ```
+ */
+export declare function conformDriver(factory: () => DriverInterface): Promise<void>;
+
+/** How a {@link Condition} joins to the running result of the conditions before it. */
+export declare type Connector = 'and' | 'or';
+
+/**
+ * Create a database over a driver and a declared `tables` schema.
+ *
+ * @remarks
+ * `tables` maps each name to its columns (a `column → shape` map); the database
+ * wraps each in an `objectShape`, so you never write `objectShape` at the table
+ * level. The `const` type parameter captures the literal names and columns, so
+ * `db.table('users')` is checked against the schema and typed by `Infer` of its
+ * columns — no annotations. Name a non-`id` primary-key column per table via the
+ * optional `keys` map.
+ *
+ * @param options - The driver, the `tables` column map, optional `keys`, and an
+ *                   optional `name`
+ * @returns A typed {@link DatabaseInterface}
+ *
+ * @example
+ * ```ts
+ * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
+ * import { integerShape, stringShape } from '@orkestrel/contract'
+ *
+ * const db = createDatabase({
+ * 	driver: createMemoryDriver(),
+ * 	tables: {
+ * 		users: { id: stringShape(), age: integerShape() },
+ * 		posts: { slug: stringShape(), title: stringShape() },
+ * 	},
+ * 	keys: { posts: 'slug' },
+ * })
+ * await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
+ * ```
+ */
+export declare function createDatabase<const T extends TablesShape>(options: DatabaseOptions<T>): DatabaseInterface<T>;
+
+/**
+ * Create the in-memory reference {@link DriverInterface}.
+ *
+ * @remarks
+ * Backed by nested maps with no I/O — the same driver runs in a browser or on a
+ * server, making it the natural choice for tests and ephemeral storage.
+ *
+ * @returns A fresh in-memory driver
+ */
+export declare function createMemoryDriver(): DriverInterface;
+
+/**
+ * A serializable read specification — everything a backend needs to compile one
+ * read, free of JS callbacks so any backend can honor it.
+ *
+ * @remarks
+ * The post-fetch `filter` predicate lives on {@link QueryInterface}, never here,
+ * so `Criteria` stays portable across backends.
+ */
+export declare interface Criteria {
+    readonly conditions?: readonly Condition[];
+    readonly order?: readonly Order[];
+    readonly limit?: number;
+    readonly offset?: number;
+}
+
+/**
+ * A forward row cursor for bulk in-place mutation.
+ *
+ * @remarks
+ * Iterates a snapshot of the table's keys captured when the cursor was opened,
+ * reading each row lazily through the owning table — so a mutation made during
+ * iteration cannot corrupt the walk, and a key removed mid-iteration is simply
+ * skipped. `update` and `remove` act on the row at the current position.
+ */
+export declare class Cursor<T = Record<string, unknown>> implements CursorInterface<T> {
+    #private;
+    constructor(table: TableInterface<T>, keys: readonly Key[]);
+    get value(): T | undefined;
+    get index(): number;
+    get done(): boolean;
+    next(): Promise<void>;
+    update(changes: Partial<T>): Promise<void>;
+    remove(): Promise<void>;
+    close(): void;
+}
+
+/**
+ * A forward row cursor for bulk in-place mutation.
+ *
+ * @remarks
+ * Iterates a snapshot of the table's keys taken at creation; `update` and
+ * `remove` act on the row at the current position through the owning table.
+ * `done` is `true` once iteration has advanced past the last key.
+ */
+export declare interface CursorInterface<T = Row> {
+    readonly value: T | undefined;
+    readonly index: number;
+    readonly done: boolean;
+    next(): Promise<void>;
+    update(changes: Partial<T>): Promise<void>;
+    remove(): Promise<void>;
+    close(): void;
+}
+
+/**
+ * A database — the ergonomic entry point over a {@link DriverInterface}.
+ *
+ * @remarks
+ * Owns the driver and a `tables` shape map, connecting the driver lazily on first
+ * use so a freshly created database is immediately usable. `table(name)` returns
+ * a table typed by that table's shape `Infer`. `import` registers more tables and
+ * returns a database re-typed with them over the **same** driver and storage;
+ * `export` emits a portable {@link TableExport} per table. `transaction` snapshots
+ * the driver, runs the scope, and rolls every table back if it throws — an
+ * optimistic model that works uniformly across backends rather than reconciling
+ * SQL's and IndexedDB's incompatible native transactions.
+ *
+ * @remarks
+ * - **Versioned (optional).** When {@link DatabaseOptions.version} is set and the driver
+ *   implements both {@link DriverInterface.meta} and {@link DriverInterface.stamp},
+ *   `open()` reconciles the driver's persisted {@link DriverMeta} against the declared
+ *   version INSIDE the same lazy-connect chain, AFTER the `open` event fires — see
+ *   {@link DatabaseOptions.version} for the full reconciliation contract.
+ * - **Observable (§13).** The owned {@link emitter} ({@link DatabaseEventMap}) carries the
+ *   connection + transaction lifecycle — `open` / `close` / `transaction` / `commit` /
+ *   `rollback` — for fire-and-forget observers, ALONGSIDE each table's per-row events. Every
+ *   event is emitted directly, strictly AFTER the relevant transition: `commit` only after
+ *   the scope succeeds, `rollback` only after every table is restored. The `rollback` emit
+ *   OBSERVES the propagated error — it never swallows it (the original throw propagates
+ *   exactly as before). The emitter isolates a listener throw and routes it to its `error`
+ *   handler (the `error` option), so observation can never reorder, throw into, or corrupt
+ *   the snapshot / commit / rollback flow.
+ */
+export declare class Database<T extends TablesShape = TablesShape> implements DatabaseInterface<T> {
+    #private;
+    constructor(options: DatabaseOptions<T>);
+    get emitter(): EmitterInterface<DatabaseEventMap>;
+    get name(): string;
+    get status(): DatabaseStatus;
+    table<K extends keyof T & string>(name: K): TableInterface<RowOf<T[K]>>;
+    import<U extends TablesShape>(tables: U, keys?: TableKeys): DatabaseInterface<U>;
+    export(): Readonly<Record<string, TableExport>>;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Run `scope` transactionally: commit its writes on success, roll every table
+     * back if it throws.
+     *
+     * @remarks
+     * When the driver implements the optional native {@link DriverInterface.transaction}
+     * hook, that native `commit` / `rollback` handle drives the transaction; otherwise
+     * the universal snapshot floor (`driver.snapshot()`) runs unchanged. Either path
+     * emits the same `transaction` / `commit` / `rollback` lifecycle (AGENTS §13).
+     * `options.signal` is checked ONCE at entry, before connecting or starting any
+     * transactional work — an already-aborted signal throws `ABORTED` and neither the
+     * native hook nor the snapshot floor is invoked. Nesting is unguarded and
+     * unsupported exactly as before: this is a single-writer model, not reentrant.
+     * On the native path, a `scope` throw rolls back via the native handle; a
+     * native `commit` failure propagates as-is with no rollback attempt — the
+     * engine owns transaction state after a failed COMMIT.
+     *
+     * @param scope - The transactional work to run
+     * @param options - `{ signal }` to abort before the transaction starts
+     * @returns The scope's resolved value
+     * @throws An `ABORTED` {@link DatabaseError} when `options.signal` has already fired
+     */
+    transaction<R>(scope: () => Promise<R>, options?: ReadOptions): Promise<R>;
+    /**
+     * Diff `deployed` against this database's declared schema and apply the
+     * resulting plan through the driver's optional `migrate` hook.
+     *
+     * @param deployed - The schema currently deployed, as {@link TableSchema}s
+     * @param options - `{ signal }` to abort before the migration starts
+     * @returns The applied {@link Migration} plan
+     * @throws A `MIGRATION` {@link DatabaseError} when the driver does not
+     * implement `migrate`, or when a step references an unknown table
+     * (propagated from the driver)
+     * @throws An `ABORTED` {@link DatabaseError} when `options.signal` has
+     * already fired at entry
+     */
+    migrate(deployed: readonly TableSchema[], options?: ReadOptions): Promise<Migration>;
+}
+
+/**
+ * An error thrown by the database layer.
+ *
+ * @remarks
+ * Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
+ * offending table / key. Thrown for: operating on a closed database (`CLOSED`), a
+ * `resolve` miss (`NOT_FOUND`), an `add` onto an existing key (`CONFLICT`), a
+ * row that fails its table's contract (`VALIDATION`), a cancelled operation whose
+ * {@link ReadOptions.signal} aborted (`ABORTED`, carrying `signal.reason` in
+ * `context`), an inapplicable {@link Migration} plan (`MIGRATION`), a
+ * driver that violates a {@link DriverInterface} invariant, thrown by the
+ * `conformDriver` helper (`CONFORMANCE`), and an unexpected infrastructure
+ * fault surfaced by a driver seam — e.g. a filesystem failure while
+ * persisting (`DRIVER`) — as opposed to expected domain conditions, which
+ * keep their specific codes.
+ */
+export declare class DatabaseError extends Error {
+    readonly code: DatabaseErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: DatabaseErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/** A machine-readable {@link DatabaseError} code. */
+export declare type DatabaseErrorCode = 'CLOSED' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION' | 'ABORTED' | 'MIGRATION' | 'CONFORMANCE' | 'DRIVER';
+
+/**
+ * The push observation surface of a {@link DatabaseInterface} (AGENTS §13) — the
+ * connection + transaction lifecycle a fire-and-forget observer (logging, metrics,
+ * tracing, cache invalidation) subscribes to.
+ *
+ * @remarks
+ * Pure signals carrying no row data — these are the database-level (not per-row)
+ * moments, so a non-generic map stays lean (per-row writes are {@link TableEventMap}).
+ * Listener isolation is the emitter's (AGENTS §13): every event is emitted directly and a
+ * listener throw is routed to the emitter's OWN `error` handler (the `error` option), never
+ * onto this domain map and never into the snapshot / commit / rollback flow — so a buggy
+ * observer can never reorder, throw into, or corrupt a transaction. Every emit sits AFTER the
+ * relevant transition: `commit` only after the scope succeeds, `rollback` only after every
+ * table has been restored (it OBSERVES the propagated error; the original throw still
+ * propagates exactly as before). Subscribe via `database.emitter.on(...)`.
+ *
+ * Declared as a `type` alias (not `interface extends EventMap`, §4.5 — `EventMap` is a
+ * `type` kind): a type-literal satisfies the `EventMap` constraint
+ * (`Record<string, readonly unknown[]>`) structurally, whereas an interface lacks the
+ * required index signature.
+ */
+export declare type DatabaseEventMap = {
+    /** The driver connected (`open`, or the lazy first-use connect completed). */
+    readonly open: readonly [];
+    /** The database was closed (the driver released). */
+    readonly close: readonly [];
+    /** A transaction scope began — the store was snapshotted, the scope is about to run. */
+    readonly transaction: readonly [];
+    /** A transaction scope completed successfully (no rollback). */
+    readonly commit: readonly [];
+    /** A transaction scope threw and every table was rolled back — the propagated error. */
+    readonly rollback: readonly [error: unknown];
+    /** A {@link Migration} plan was applied via `migrate` — the applied plan. */
+    readonly migrate: readonly [migration: Migration];
+};
+
+/**
+ * A database — the ergonomic entry point that owns the driver and its tables.
+ *
+ * @remarks
+ * A database is a typed view over a set of tables on one driver. Tables are
+ * declared up front in `createDatabase({ tables })` and reached, fully typed,
+ * with `table(name)`. The driver connects lazily on first use, so a freshly
+ * created database is immediately usable. `import` defines more than one table
+ * from a shape map and returns a new typed view of **those** tables over the
+ * same driver and storage (so views can be split by concern and still share
+ * data); `export` produces a portable {@link TableExport} per table for moving a
+ * schema between databases or environments. `transaction` snapshots the store,
+ * runs the scope, and rolls every table back if it throws — an optimistic model
+ * that works uniformly across backends rather than reconciling SQL's and
+ * IndexedDB's incompatible native transactions.
+ */
+export declare interface DatabaseInterface<T extends TablesShape = TablesShape> {
+    readonly emitter: EmitterInterface<DatabaseEventMap>;
+    readonly name: string;
+    readonly status: DatabaseStatus;
+    table<K extends keyof T & string>(name: K): TableInterface<RowOf<T[K]>>;
+    import<U extends TablesShape>(tables: U, keys?: TableKeys): DatabaseInterface<U>;
+    export(): Readonly<Record<string, TableExport>>;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    transaction<R>(scope: () => Promise<R>, options?: ReadOptions): Promise<R>;
+    /**
+     * Diff a caller-supplied deployed schema against this database's declared
+     * schema (its `tables`, as configured) via `planMigration`, apply the
+     * resulting plan through the driver's optional `migrate` hook, and return
+     * the applied plan.
+     *
+     * @param deployed - The schema currently deployed, as {@link TableSchema}s
+     * @param options - Optional abort signal, checked at entry
+     * @returns The applied {@link Migration} plan
+     *
+     * @remarks
+     * Throws `DatabaseError` `MIGRATION` when the driver does not implement
+     * `migrate`, or when a step references an unknown table (propagated from
+     * the driver). Throws `ABORTED` when `options.signal` has already fired at
+     * entry. Emits the `migrate` event after a successful apply. Version
+     * TRACKING (persisting `from` / `to`) remains deferred to persistent
+     * backends — the caller owns knowing what was deployed.
+     */
+    migrate(deployed: readonly TableSchema[], options?: ReadOptions): Promise<Migration>;
+}
+
+/**
+ * Options for `createDatabase`.
+ *
+ * @remarks
+ * `driver` is the storage backend; `tables` declares each table's columns;
+ * `keys` overrides the primary-key column per table ({@link DEFAULT_PRIMARY}
+ * otherwise); `indexes` declares secondary indexes per table (contracts don't
+ * express them) that flow into each derived {@link TableSchema}; `name` labels
+ * the database; `on` wires initial {@link DatabaseEventMap} listeners (§8); `error`
+ * is the emitter's listener-error handler (§13 — a listener throw routes here);
+ * `key` is the key factory a table uses when a written row lacks its primary
+ * key — without one, writing a keyless row is a `VALIDATION` error (the core
+ * mints no keys itself).
+ */
+export declare interface DatabaseOptions<T extends TablesShape = TablesShape> {
+    readonly on?: EmitterHooks<DatabaseEventMap>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly driver: DriverInterface;
+    readonly tables: T;
+    readonly keys?: TableKeys;
+    readonly indexes?: TableIndexes;
+    readonly name?: string;
+    readonly key?: KeyFunction;
+    /**
+     * The declared schema version.
+     *
+     * @remarks
+     * Only meaningful when the driver implements BOTH {@link DriverInterface.meta}
+     * and {@link DriverInterface.stamp} (a versioning driver); unset, or a
+     * non-versioning driver, leaves `open()` unchanged from today's behavior.
+     * When set and the driver versions, `open()` reconciles against the
+     * driver's persisted {@link DriverMeta}:
+     * - **Fresh store** (`meta()` returns `undefined`) — no migration is
+     *   possible (there is nothing deployed to diff against), so `open()`
+     *   simply `stamp`s `{ version, schema }` for next time.
+     * - **Stored version < `version`** — `planMigration(stored.schema, declared
+     *   schema)` computes the upgrade plan, applied via the driver's optional
+     *   `migrate` hook. If `migrate` is absent and the plan is non-empty,
+     *   `open()` throws `DatabaseError` `MIGRATION`. On success, `open()`
+     *   `stamp`s the new `{ version, schema }` and emits the `migrate` event.
+     * - **Stored version > `version`** — the store is newer than the declared
+     *   schema; `open()` throws `DatabaseError` `MIGRATION`.
+     * - **Stored version === `version`** — no-op.
+     *
+     * When the driver ALSO implements {@link DriverInterface.transaction}, the
+     * `migrate` + `stamp` pair applies atomically through that native handle
+     * (all-or-nothing, rolled back cleanly on a mid-plan failure); otherwise the
+     * pair applies sequentially, with a small documented window in which a `stamp`
+     * failure after a successful `migrate` can leave new data under old meta.
+     */
+    readonly version?: number;
+}
+
+/** The lifecycle state of a {@link DatabaseInterface}. */
+export declare type DatabaseStatus = 'idle' | 'open' | 'closed';
+
+/**
+ * Structural equality by SameValueZero leaves — the comparator behind conformance
+ * checks and any test/fixture that needs "same data", not "same reference".
+ *
+ * @remarks
+ * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
+ * Arrays compare by index (same length, every element `deepEqual`). Plain
+ * records (via `isRecord`) compare by their OWN enumerable keys: same key
+ * COUNT and, for every key in `left`, `right` has that key (`Object.hasOwn`)
+ * with a `deepEqual` value — so a key present with value `undefined` is NOT
+ * equal to that key being absent (both differ in `Object.keys` membership).
+ * Anything else (functions, class instances, mismatched shapes) falls through
+ * to `false`. There is no cycle detection — a cyclic input recurses forever;
+ * callers pass acyclic data (rows, plans, config).
+ *
+ * @param left - The left value
+ * @param right - The right value
+ * @returns Whether `left` and `right` are structurally equal
+ *
+ * @example
+ * ```ts
+ * deepEqual(Number.NaN, Number.NaN) // true
+ * deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+ * deepEqual({ a: undefined }, {}) // false — present-undefined ≠ absent
+ * ```
+ */
+export declare function deepEqual(left: unknown, right: unknown): boolean;
+
+/**
+ * The primary-key column assumed when {@link TableKeys} does not name one.
+ *
+ * @remarks
+ * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
+ * lean on, so a table that omits `key` keys its rows by `id`.
+ */
+export declare const DEFAULT_PRIMARY = "id";
+
+/** A sort direction. */
+export declare type Direction = 'ascending' | 'descending';
+
+/**
+ * Run the driver-conformance battery against a fresh {@link DriverInterface}
+ * per phase, yielding one {@link ConformanceFinding} per violated invariant —
+ * the shared invariant suite every backend (in-memory, SQLite, IndexedDB)
+ * must uphold to be a drop-in {@link DriverInterface}.
+ *
+ * @remarks
+ * Framework-agnostic: no test-runner or Node imports, only sibling core
+ * modules — so it runs equally from a unit test, a smoke script, or a new
+ * driver's own README. Opens a fixed two-table schema (`users` keyed by the
+ * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
+ * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
+ * `read` of a missing key returns `undefined`; `write`/`read` round-trip with
+ * DEEP copy-in/copy-out isolation (mutating the caller's row — including a
+ * NESTED field — after `write`, or a row `read` returns, never perturbs
+ * stored state) and upsert-overwrite; `delete` returns `true` then `false`;
+ * `keys`/`scan` yield in ascending key order; `clear` empties only its target
+ * table; `snapshot`'s rollback thunk restores pre-snapshot state, including a
+ * NESTED field mutated in place on a read-back row between capture and
+ * restore; a scoped `snapshot(['users'])` rolls back only the named table,
+ * leaving a concurrent mutation to another table intact; a
+ * non-`id` primary key (`posts.slug`) round-trips; a nested-object row
+ * round-trips structurally (via {@link deepEqual}). The optional surface is
+ * presence-gated: when `migrate` exists, a `column.remove` plan strips the
+ * column from stored rows and a plan referencing an unknown table throws
+ * `DatabaseError` `MIGRATION`; when `stream` exists, it yields only
+ * condition-matching rows and honors `offset`/`limit`; when `transaction`
+ * exists, `commit` persists and `rollback` restores; when both `meta` and
+ * `stamp` exist, a fresh store's `meta()` is `undefined`, and after
+ * `stamp({ version, schema })`, `meta()` returns the exact stamped value.
+ *
+ * Each phase runs within a `try`/`catch`: an EXPECTED mismatch yields a
+ * finding built from the assertion, while an UNEXPECTED throw (a driver
+ * crash mid-phase) is caught and yielded as a finding too, naming the phase
+ * as `check` and carrying the caught error in `context.error` — a broken
+ * driver can never escape the battery as an unhandled rejection. Within a
+ * phase, the FIRST violated assertion yields and the phase stops (matching
+ * the historical fail-fast shape at phase granularity); the generator then
+ * moves on to the next phase regardless. Because this is a **generator**,
+ * consuming only the first yielded value reproduces true fail-fast (later
+ * phases never run) — that is exactly what {@link conformDriver} does.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @yields One {@link ConformanceFinding} per violated invariant, in phase order
+ *
+ * @example
+ * ```ts
+ * import { createMemoryDriver, driverFindings } from '@orkestrel/database'
+ *
+ * for await (const finding of driverFindings(() => createMemoryDriver())) {
+ * 	console.log(finding.check, finding.message)
+ * }
+ * ```
+ */
+export declare function driverFindings(factory: () => DriverInterface): AsyncIterable<ConformanceFinding>;
+
+/**
+ * The storage primitive every backend implements — the whole of the bridge.
+ *
+ * @remarks
+ * The REQUIRED surface is deliberately minimal: keyed read / write / delete, an
+ * ordered `scan`, a key listing, and a `snapshot` that backs transactions — the
+ * irreducible primitive. There is **no** required query, count, or aggregate
+ * here: all of that is one query engine in the core (`helpers.ts`) running over
+ * `scan`, so a new backend implements a handful of tiny methods rather than
+ * re-deriving WHERE compilation. `open` now receives a derived
+ * {@link TableSchema}`[]` (columns, types, primary, indexes) so a native backend
+ * can build real tables and indexes; a scan-only backend reads only `name`. The
+ * optional `records?` / `count?` / `aggregate?` are native overrides the engine
+ * falls back from (AGENTS §21). The API is async (Promises) because IndexedDB is; synchronous
+ * backends resolve immediately. Lookups that may miss return `undefined` /
+ * `false` rather than throwing (AGENTS §12).
+ */
+export declare interface DriverInterface {
+    open(schema: readonly TableSchema[]): Promise<void>;
+    close(): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row): Promise<void>;
+    delete(table: string, key: Key): Promise<boolean>;
+    keys(table: string): Promise<readonly Key[]>;
+    scan(table: string): AsyncIterable<Row>;
+    clear(table: string): Promise<void>;
+    /**
+     * Capture the current state and return a thunk that rolls every table back to
+     * it — the primitive transactions are built on (SQL `SAVEPOINT`, an IndexedDB
+     * key buffer, a cloned map).
+     *
+     * @remarks
+     * `tables` omitted captures/rolls back the WHOLE store (existing behavior).
+     * `tables` provided captures/restores ONLY the named tables — the returned
+     * rollback thunk leaves every other table untouched.
+     */
+    snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
+    /**
+     * Optional native filtered read (AGENTS §21). A backend that can evaluate a
+     * {@link Criteria} natively (SQL `WHERE` + `ORDER`/`LIMIT`, an index range)
+     * implements this; `Table` prefers it and falls back to `applyCriteria` over
+     * `scan` when it is absent. Must honor the full criteria (filter, order, page).
+     */
+    records?(table: string, criteria: Criteria): Promise<readonly Row[]>;
+    /**
+     * Optional native count (AGENTS §21). Counts rows matching the criteria's
+     * conditions (paging is irrelevant to a count); `Table` falls back to counting
+     * the engine-filtered `scan` when absent.
+     */
+    count?(table: string, criteria: Criteria): Promise<number>;
+    /**
+     * Optional native aggregate (AGENTS §21). A backend that can compute an
+     * aggregate natively (SQL `COUNT`/`SUM`/`AVG`/`MIN`/`MAX`, an indexed count)
+     * implements this; `Table.aggregate` prefers it and otherwise falls back to
+     * `computeAggregate` over the native-filtered (or scanned) rows. Aggregates
+     * ignore paging, so `criteria` carries only conditions.
+     */
+    aggregate?(table: string, operation: AggregateFunction, column: FieldPath, criteria: Criteria): Promise<number | undefined>;
+    /**
+     * Optional native transaction (BEGIN). When present, the engine uses the
+     * returned {@link TransactionInterface}'s `commit` / `rollback` instead of
+     * the snapshot-based rollback floor.
+     */
+    transaction?(): Promise<TransactionInterface>;
+    /**
+     * Optional natively filtered lazy iteration — a {@link Criteria}-aware
+     * streaming read. Drivers without it are served by the core scan fallback
+     * (filtering `scan` lazily).
+     */
+    stream?(table: string, criteria: Criteria): AsyncIterable<Row>;
+    /**
+     * Optional native migration — applies a {@link Migration} plan directly.
+     * Throws `DatabaseError` `MIGRATION` when a step references an unknown
+     * table.
+     */
+    migrate?(plan: Migration): Promise<void>;
+    /**
+     * Optional persisted-metadata read (PAIRED with {@link stamp} — a driver
+     * implements both or neither). Returns the {@link DriverMeta} last stamped,
+     * or `undefined` when the store has never been stamped.
+     */
+    meta?(): Promise<DriverMeta | undefined>;
+    /**
+     * Optional persisted-metadata write (PAIRED with {@link meta} — a driver
+     * implements both or neither). Persists `meta` verbatim for a later `meta()`
+     * to return.
+     */
+    stamp?(meta: DriverMeta): Promise<void>;
+}
+
+/**
+ * Persisted schema metadata a versioning driver stores verbatim and returns on
+ * demand.
+ *
+ * @remarks
+ * The driver never introspects this payload — it hands back exactly what was
+ * last stamped via {@link DriverInterface.stamp}. `meta()` returning `undefined`
+ * is how a fresh store is distinguished from an upgradable one: it means the
+ * store has never been stamped, not that it is at version zero.
+ */
+export declare interface DriverMeta {
+    readonly version: number;
+    readonly schema: readonly TableSchema[];
+}
+
+/**
+ * Read a row's primary key from a column, when it is a usable {@link Key}.
+ *
+ * @param row - The row to read
+ * @param column - The primary-key column name
+ * @returns The key (a string or finite number), or `undefined`
+ */
+export declare function extractKey(row: Row, column: string): Key | undefined;
+
+/**
+ * Filter rows by a list of conditions — the shared basis for a table's count
+ * and aggregate paths (no sort/page, unlike {@link applyCriteria}).
+ *
+ * @remarks
+ * An empty condition list matches every row (returned as-is, no copy). Folds
+ * each row through {@link matchesCriteria}.
+ *
+ * @param rows - The rows to filter
+ * @param conditions - The conditions to apply (empty matches everything)
+ * @returns The matching rows
+ *
+ * @example
+ * ```ts
+ * filterRows(
+ * 	[{ age: 30 }, { age: 12 }],
+ * 	[{ column: 'age', operator: 'above', values: [18], connector: 'and' }],
+ * ) // => [{ age: 30 }]
+ * ```
+ */
+export declare function filterRows(rows: readonly Row[], conditions: readonly Condition[]): readonly Row[];
+
+/**
+ * Generate an RFC 4122 version 4 UUID from a number source — no host crypto global.
+ *
+ * @remarks
+ * Draws exactly {@link UUID_BYTE_COUNT} values from `random`, one per byte, then
+ * forces the version (`4`) and variant (`10xx`) bits. The default source is
+ * `Math.random` — a pure-ECMAScript intrinsic, so generation works on every host;
+ * pass a seeded source (`seededRandom` from `@orkestrel/contract`) and reuse it
+ * across calls for reproducible sequences in tests and fixtures — production
+ * identifiers should keep the default source, whose engine entropy is far larger
+ * than a 32-bit seed. Each byte is floored and masked, so a source straying
+ * outside `[0, 1)` (negative, `>= 1`, `NaN`, `Infinity`) can never yield a
+ * malformed UUID. Suitable as a collision-resistant record identifier — not a
+ * cryptographic token; never use one as a secret.
+ *
+ * @param random - A number source returning values in the half-open range `[0, 1)` (defaults to `Math.random`)
+ * @returns A lowercase RFC 4122 version 4 UUID
+ *
+ * @example
+ * ```ts
+ * import { generateUUID } from '@orkestrel/database'
+ * import { seededRandom } from '@orkestrel/contract'
+ *
+ * generateUUID() // e.g. '9b2f7c1e-3d4a-4f6b-8e2d-5a1c0b9f8e7d'
+ * generateUUID(seededRandom(42)) // the same UUID on every run
+ * ```
+ */
+export declare function generateUUID(random?: RandomFunction): string;
+
+export declare function globMatch(value: string, pattern: string): boolean;
+
+/**
+ * Narrow an unknown caught value to a {@link DatabaseError}.
+ *
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns `true` when `value` is a {@link DatabaseError}
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	await users.add(row)
+ * } catch (error) {
+ * 	if (isDatabaseError(error) && error.code === 'CONFLICT') await users.set(row)
+ * }
+ * ```
+ */
+export declare function isDatabaseError(value: unknown): value is DatabaseError;
+
+/**
+ * Whether a value is a well-formed {@link DriverMeta} — the boundary guard a
+ * versioning driver's `meta()` narrows a stored (structured-clone or
+ * `JSON.parse`d) value through before trusting it, replacing the per-driver
+ * duplicated narrowing every backend used to hand-roll (AGENTS §14: never `as`).
+ *
+ * @remarks
+ * Total and total-recursive over the whole shape: a finite `version`, and a
+ * `schema` array of well-formed {@link TableSchema} entries — each a `name` /
+ * `primary` string pair, a `columns` array of well-formed {@link ColumnSchema}
+ * entries (a `name` string, a {@link ColumnType} literal, a `nullable`
+ * boolean), and an `indexes` array of string arrays. Anything off-shape
+ * (including a non-record) returns `false` rather than throwing.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a well-formed `DriverMeta`
+ *
+ * @example
+ * ```ts
+ * isDriverMeta({ version: 1, schema: [] }) // true
+ * isDriverMeta({ version: 1, schema: [{ name: 'users' }] }) // false
+ * ```
+ */
+export declare function isDriverMeta(value: unknown): value is DriverMeta;
+
+/**
+ * A primary key — the value identifying a row within its table.
+ *
+ * @remarks
+ * `string | number` is the intersection of what IndexedDB key ranges and SQL
+ * primary keys both express without coercion. Auto-generated keys are UUID
+ * strings; supply your own to use numeric keys.
+ */
+export declare type Key = string | number;
+
+/**
+ * A caller-supplied key minting function.
+ *
+ * @remarks
+ * Environment surfaces provide implementations (the server's `node:crypto`-backed
+ * `generateKey`); the core mints no keys itself. Supplied via
+ * {@link DatabaseOptions.key} and used by a table when a written row lacks its
+ * primary key. Without one, writing a keyless row is a `VALIDATION` error.
+ */
+export declare type KeyFunction = () => Key;
+
+export declare function likeMatch(value: string, pattern: string): boolean;
+
+/**
+ * Evaluate one {@link Condition} against a row — the per-operator predicate.
+ *
+ * @remarks
+ * Reads the condition's column — a `FieldPath`, resolved with `resolveField` (a
+ * string is one column; an array descends a nested value) — and applies the
+ * operator. Range operators (`above` / `below` / `from` / `to` / `between`) use
+ * {@link compareValues}, the total order; the equality family (`equals` / `not`
+ * / `any` / `none`) uses {@link deepEqual} — STRUCTURAL equality, not the total
+ * order's rank-5-collapses-all-objects behavior, so `equals` on an object/array
+ * operand only matches a structurally-equal value, never every row holding any
+ * object. This is a semantics change from ranking: `deepEqual` is SameValueZero
+ * on leaves, so `NaN` now equals `NaN` under `equals` / `any` (it never matched
+ * anything under the old rank-based comparison). `like` / `glob` / `starts` /
+ * `ends` match only strings; `absent` / `present` test nullishness. Total — a
+ * type mismatch is simply a non-match.
+ *
+ * @param row - The row to test
+ * @param condition - The condition to apply
+ * @returns Whether the row satisfies the condition
+ */
+export declare function matchesCondition(row: Row, condition: Condition): boolean;
+
+/**
+ * Fold a row through a list of conditions, joining each by its connector.
+ *
+ * @remarks
+ * Evaluated left-to-right: the first condition seeds the result, and each later
+ * condition combines with `&&` (`and`) or `||` (`or`). An empty list matches
+ * every row. There is no operator precedence — conditions combine in the order
+ * the query builder recorded them.
+ *
+ * @param row - The row to test
+ * @param conditions - The conditions to fold
+ * @returns Whether the row satisfies the combined conditions
+ */
+export declare function matchesCriteria(row: Row, conditions: readonly Condition[]): boolean;
+
+/**
+ * The longest `LIKE` / `GLOB` pattern the wildcard matcher accepts before rejecting it.
+ *
+ * @remarks
+ * A ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
+ * criteria over the wire, so `likeMatch` / `globMatch` run attacker-controlled
+ * patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+ * backtracking regex (`.*`-segments-separated-by-literals against a long input is the
+ * catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
+ * pattern). Capping the pattern length bounds that pattern factor, leaving a match
+ * linear in the value length whatever the pattern. A longer pattern throws a
+ * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
+ */
+export declare const MAX_PATTERN_LENGTH = 1024;
+
+/**
+ * The reference {@link DriverInterface} — nested maps, no I/O.
+ *
+ * @remarks
+ * The in-between made concrete: it runs identically in a browser or on a server,
+ * so it is the storage behind tests, ephemeral caches, and any code that wants
+ * the database API without a persistent backend. Rows are DEEP-copied (via
+ * `structuredClone`) in and out — at `write`, `read`, `scan`, `stream`, and both
+ * snapshot capture and restore — so a caller mutating a nested field of an input
+ * row, a returned row, or a row mutated in place between snapshot and rollback
+ * can never perturb stored state (AGENTS §11); a shallow `{ ...row }` spread
+ * would still share nested object/array references. `snapshot`
+ * clones every table to give transactions an exact rollback point. `scan` and
+ * `keys` yield in key order — sorted by the core {@link compareValues} total
+ * order, the same contract the SQLite (`ORDER BY`) and IndexedDB (key-ordered
+ * reads) backends honor, so an unordered read agrees across every backend rather
+ * than leaking Map insertion order. A persistent backend (IndexedDB, SQLite)
+ * implements the same nine methods over real storage.
+ */
+export declare class MemoryDriver implements DriverInterface {
+    #private;
+    open(schema: readonly TableSchema[]): Promise<void>;
+    close(): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row): Promise<void>;
+    delete(table: string, key: Key): Promise<boolean>;
+    keys(table: string): Promise<readonly Key[]>;
+    scan(table: string): AsyncIterable<Row>;
+    /**
+     * Natively filtered lazy iteration — the {@link DriverInterface.stream} hook.
+     *
+     * @remarks
+     * Iterates the table's keys in the same key order `scan` and `keys` yield
+     * (sorted by {@link compareValues}), testing each row against
+     * `criteria.conditions` (via {@link matchesCriteria}) before counting it
+     * toward `offset` / `limit`. Both are applied lazily as matches are found —
+     * `offset` matches are skipped without being yielded, and iteration stops the
+     * instant `limit` yields have been produced, so a large table is never fully
+     * walked for a small page. `criteria.order` is IGNORED (the same contract as
+     * `TableInterface.scan` and `QueryInterface.stream`): streaming yields key
+     * order, sorted output is `records()`'s job. Rows yield copy-out (AGENTS
+     * §11), and an unknown table mirrors `scan`'s empty-yield behavior.
+     *
+     * @param table - The table to stream
+     * @param criteria - The filter / offset / limit to apply lazily
+     *
+     * @example
+     * ```ts
+     * for await (const row of driver.stream('users', { conditions, limit: 10 })) {
+     *   // one matched row at a time, in key order
+     * }
+     * ```
+     */
+    stream(table: string, criteria: Criteria): AsyncIterable<Row>;
+    clear(table: string): Promise<void>;
+    /**
+     * Capture the current state and return a thunk that rolls back to it.
+     *
+     * @remarks
+     * `tables` omitted clones and restores the WHOLE store, byte-identical to the
+     * prior whole-store behavior. `tables` provided clones ONLY the named tables,
+     * and the returned thunk restores ONLY those — every other table keeps
+     * whatever it was mutated to after the snapshot was taken.
+     *
+     * @param tables - The table names to scope the snapshot to; omitted captures every table
+     * @returns A thunk that restores the captured tables
+     */
+    snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
+    /**
+     * Return the persisted {@link DriverMeta}, or `undefined` when the store has
+     * never been stamped.
+     *
+     * @remarks
+     * In-process only — the metadata lives in this instance's memory, exactly
+     * like the rest of this driver's storage. A driver-conformance-valid
+     * implementation of the optional `meta` / `stamp` pair.
+     *
+     * @returns The last-stamped {@link DriverMeta}, or `undefined`
+     */
+    meta(): Promise<DriverMeta | undefined>;
+    /**
+     * Persist `meta` verbatim for a later `meta()` to return.
+     *
+     * @param meta - The {@link DriverMeta} to persist
+     */
+    stamp(meta: DriverMeta): Promise<void>;
+    /**
+     * Apply a {@link Migration} plan's steps against the in-memory store.
+     *
+     * @remarks
+     * A multi-step plan applies its steps sequentially and is NOT atomic — a
+     * failure partway through a plan leaves the earlier steps already applied.
+     *
+     * @param plan - The migration plan to apply
+     */
+    migrate(plan: Migration): Promise<void>;
+}
+
+/**
+ * Apply one table's {@link MigrationStep}s to its rows — a pure row transform.
+ *
+ * @remarks
+ * `column.remove` drops that field from every row (a fresh copy — inputs are
+ * never mutated, AGENTS §11); `column.add` leaves rows as-is (an absent field
+ * reads as `undefined`, backfill is application policy). `table.add` /
+ * `table.remove` / `index.add` / `index.remove` are no-ops here (they operate
+ * on storage shape, not row shape). Steps for tables other than the one
+ * `rows` belongs to are ignored — pass only the steps relevant to this table.
+ *
+ * @param rows - The table's current rows
+ * @param steps - The migration steps to apply (typically one table's slice of a {@link Migration})
+ * @returns A new array of transformed rows; `rows` is never mutated
+ *
+ * @example
+ * ```ts
+ * const rows = [{ id: 'a', name: 'Ada', legacy: true }]
+ * migrateRows(rows, [{ operation: 'column.remove', table: 'users', column: 'legacy' }])
+ * // => [{ id: 'a', name: 'Ada' }]
+ * ```
+ */
+export declare function migrateRows(rows: readonly Row[], steps: readonly MigrationStep[]): readonly Row[];
+
+/**
+ * A schema migration plan — an ordered set of {@link MigrationStep}s moving a
+ * database from one schema version to another.
+ *
+ * @remarks
+ * `from` / `to` are the source and target schema versions; `steps` runs in
+ * order. Applied natively via {@link DriverInterface.migrate} when a driver
+ * implements it.
+ */
+export declare interface Migration {
+    readonly from: number;
+    readonly to: number;
+    readonly steps: readonly MigrationStep[];
+}
+
+/**
+ * One step of a {@link Migration} plan — a single schema change applied to one
+ * table.
+ *
+ * @remarks
+ * `operation` names the axis it splits on (AGENTS §4.4): adding / removing a
+ * whole table, a column, or an index. A driver's optional `migrate` applies each
+ * step natively; a step referencing an unknown table throws `DatabaseError`
+ * `MIGRATION`.
+ */
+export declare type MigrationStep = {
+    readonly operation: 'table.add';
+    readonly table: TableSchema;
+} | {
+    readonly operation: 'table.remove';
+    readonly table: string;
+} | {
+    readonly operation: 'column.add';
+    readonly table: string;
+    readonly column: ColumnSchema;
+} | {
+    readonly operation: 'column.remove';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly operation: 'index.add';
+    readonly table: string;
+    readonly index: readonly string[];
+} | {
+    readonly operation: 'index.remove';
+    readonly table: string;
+    readonly index: readonly string[];
+};
+
+/** One ordering term — a column ({@link FieldPath}, flat or nested) and its direction. */
+export declare interface Order {
+    readonly column: FieldPath;
+    readonly direction: Direction;
+}
+
+/**
+ * Structurally diff a deployed and a declared table set into a {@link Migration}
+ * plan.
+ *
+ * @remarks
+ * Tables present in `declared` but not `deployed` become `table.add` steps
+ * (carrying the full declared {@link TableSchema}); tables present in
+ * `deployed` but not `declared` become `table.remove` steps. Tables present in
+ * both are diffed column-by-column (by name) and index-group-by-index-group
+ * (by deep equality of the column-name array), each producing `column.add` /
+ * `column.remove` / `index.add` / `index.remove` steps. Step order is
+ * deterministic: every `table.remove`, then every `table.add`, then each
+ * shared table's column/index changes in `declared` order. `from` / `to` are
+ * plan labels only — version tracking itself is deferred to persistent
+ * backends.
+ *
+ * A column present in BOTH schemas under the same name but with a different
+ * `type` or `nullable` throws a `MIGRATION` {@link DatabaseError} naming the
+ * table, the column, and the from→to difference — a name-only diff would
+ * otherwise silently produce NO step for the drift, and versioned
+ * reconciliation would stamp over it. There is no automatic in-place
+ * type-change step: the manual path is to add a new column, copy/convert the
+ * data at the application layer, then remove the old column — two separate
+ * plans, never a single implicit "alter" step.
+ *
+ * @param deployed - The table schemas currently applied
+ * @param declared - The table schemas the caller wants applied
+ * @param from - The plan's source version label (defaults to `0`)
+ * @param to - The plan's target version label (defaults to `1`)
+ * @returns The migration plan moving `deployed` toward `declared`
+ * @throws A `MIGRATION` {@link DatabaseError} when a shared column's `type` or
+ * `nullable` differs between `deployed` and `declared`
+ *
+ * @example
+ * ```ts
+ * const plan = planMigration(
+ * 	[{ name: 'users', primary: 'id', columns: [], indexes: [] }],
+ * 	[{ name: 'users', primary: 'id', columns: [{ name: 'age', type: 'integer', nullable: false }], indexes: [] }],
+ * )
+ * // plan.steps === [{ operation: 'column.add', table: 'users', column: { name: 'age', ... } }]
+ * ```
+ */
+export declare function planMigration(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number): Migration;
+
+/**
+ * A fluent query builder bound to one table.
+ *
+ * @remarks
+ * Accumulates conditions, ordering, JS filters, and a page; each builder method
+ * mutates and returns the same instance, so a chain reads as one statement. The
+ * portable parts (conditions, order, page) compile into a {@link Criteria} the
+ * table resolves; a `filter` predicate is applied in memory after the read and
+ * before paging, so it composes with the rest without a backend ever seeing a
+ * JS callback.
+ */
+export declare class Query<T = Record<string, unknown>> implements QueryInterface<T> {
+    #private;
+    constructor(table: TableInterface<T>);
+    where(column: FieldPath): ClauseInterface<T>;
+    and(column: FieldPath): ClauseInterface<T>;
+    or(column: FieldPath): ClauseInterface<T>;
+    filter(predicate: (row: T) => boolean): QueryInterface<T>;
+    ascending(column: FieldPath): QueryInterface<T>;
+    descending(column: FieldPath): QueryInterface<T>;
+    limit(count: number): QueryInterface<T>;
+    offset(count: number): QueryInterface<T>;
+    all(): Promise<readonly T[]>;
+    first(): Promise<T | undefined>;
+    count(): Promise<number>;
+    /**
+     * Lazy per-row evaluation of this query's conditions / filters / offset /
+     * limit.
+     *
+     * @remarks
+     * `order` and its comparators are IGNORED (streaming yields unsorted, as rows
+     * are evaluated one at a time). Same abort semantics as
+     * `TableInterface.scan`: the signal (if any) is checked before each yield,
+     * and breaking out early closes the underlying source.
+     *
+     * @param options - `signal` to cancel the iteration; checked before each yield
+     * @returns An async iterable of matching rows
+     */
+    stream(options?: ReadOptions): AsyncIterable<T>;
+    aggregate(operation: AggregateFunction, column: FieldPath): Promise<number | undefined>;
+    sum(column: FieldPath): Promise<number | undefined>;
+    average(column: FieldPath): Promise<number | undefined>;
+    minimum(column: FieldPath): Promise<number | undefined>;
+    maximum(column: FieldPath): Promise<number | undefined>;
+}
+
+/**
+ * A fluent query builder.
+ *
+ * @remarks
+ * `where` / `and` / `or` open a {@link ClauseInterface} whose operator
+ * closes the condition and returns the query. `filter` adds a post-fetch JS
+ * predicate (applied after the backend read, before paging). The terminals
+ * (`all` / `first` / `count` / the aggregates) execute against the table; each
+ * call mutates and returns the same builder, so a chain reads as one statement.
+ * Every `column` is a {@link FieldPath} — a string is one column, an array
+ * descends a nested value.
+ */
+export declare interface QueryInterface<T = Row> {
+    where(column: FieldPath): ClauseInterface<T>;
+    and(column: FieldPath): ClauseInterface<T>;
+    or(column: FieldPath): ClauseInterface<T>;
+    filter(predicate: (row: T) => boolean): QueryInterface<T>;
+    ascending(column: FieldPath): QueryInterface<T>;
+    descending(column: FieldPath): QueryInterface<T>;
+    limit(count: number): QueryInterface<T>;
+    offset(count: number): QueryInterface<T>;
+    all(): Promise<readonly T[]>;
+    first(): Promise<T | undefined>;
+    count(): Promise<number>;
+    /**
+     * Lazy per-row evaluation of this query's conditions / filters / offset /
+     * limit.
+     *
+     * @remarks
+     * `order` and its comparators are IGNORED (streaming yields unsorted, as
+     * rows are evaluated one at a time). Same abort semantics as
+     * {@link TableInterface.scan}: the signal (if any) is checked before each
+     * yield, and breaking out early closes the underlying source.
+     */
+    stream(options?: ReadOptions): AsyncIterable<T>;
+    sum(column: FieldPath): Promise<number | undefined>;
+    average(column: FieldPath): Promise<number | undefined>;
+    minimum(column: FieldPath): Promise<number | undefined>;
+    maximum(column: FieldPath): Promise<number | undefined>;
+    aggregate(operation: AggregateFunction, column: FieldPath): Promise<number | undefined>;
+}
+
+/**
+ * Options for a cancellable read / iteration operation.
+ *
+ * @remarks
+ * When `signal` aborts, the operation throws a {@link DatabaseError} with code
+ * `ABORTED` carrying `signal.reason` in `context`. `TableInterface.scan` and
+ * `QueryInterface.stream` check the signal before each yield; other read
+ * methods check it at entry.
+ */
+export declare interface ReadOptions {
+    readonly signal?: AbortSignal;
+}
+
+/** A table row — a plain record of column values keyed by column name. */
+export declare type Row = Record<string, unknown>;
+
+/**
+ * The row type a table's {@link Columns} describe — `Infer` of its `objectShape`.
+ *
+ * @remarks
+ * The broad `Columns` (an open `column → shape` map, e.g. when a database is held
+ * at its default type) short-circuits to {@link Row}: there is nothing concrete to
+ * infer, and expanding `Infer` over the open shape would trip TS's
+ * instantiation-depth guard. Concrete column maps infer their exact row.
+ */
+export declare type RowOf<C extends Columns> = [Columns] extends [C] ? Row : Infer<{
+    readonly type: 'object';
+    readonly properties: C;
+}>;
+
+/**
+ * Map a column's {@link ContractShape} to its portable {@link ColumnType} — the
+ * value a `TableSchema` carries so a native backend can declare a real column.
+ *
+ * @remarks
+ * `string` → `text`; `number` → `integer` when the shape is integer-only, else
+ * `real`; `boolean` → `boolean`. A `literal` takes the type of its values
+ * (all-boolean → `boolean`, all-integer → `integer`, mixed/fractional numbers →
+ * `real`, anything else → `text`). `optional` / `nullable` unwrap to their inner
+ * type (nullability is tracked separately). `null` / `object` / `array` / `union` /
+ * `json` / `raw` → `json`: a backend stores them as JSON text and can `json_extract`
+ * for nested `FieldPath` queries. A scan-only backend ignores the result.
+ *
+ * @param shape - The column's contract shape
+ * @returns The portable column type
+ *
+ * @example
+ * ```ts
+ * shapeToColumnType(stringShape()) // 'text'
+ * shapeToColumnType(integerShape()) // 'integer'
+ * shapeToColumnType(optionalShape(integerShape())) // 'integer'
+ * shapeToColumnType(objectShape({ a: stringShape() })) // 'json'
+ * ```
+ */
+export declare function shapeToColumnType(shape: ContractShape): ColumnType;
+
+/**
+ * Sort rows by an ordering specification, leaving the input untouched.
+ *
+ * @remarks
+ * Applies the terms in priority order — the first term that distinguishes two
+ * rows decides — using {@link compareValues}, reversing for `descending`.
+ *
+ * @param rows - The rows to sort
+ * @param order - The ordering terms in priority order
+ * @returns A new, sorted array
+ */
+export declare function sortRows(rows: readonly Row[], order: readonly Order[]): readonly Row[];
+
+/**
+ * A table — typed keyed CRUD plus fluent query and cursor access over a driver.
+ *
+ * @remarks
+ * The table's contract is the load-bearing piece: writes go through `parse`
+ * (coercing inputs and rejecting rows that don't fit with a `VALIDATION` throw),
+ * reads come back through the contract guard (narrowing a stored {@link Row} to
+ * the table's type — no assertion, AGENTS §1), and `contract` is exposed for
+ * introspection and seeding. The driver only stores and scans; all querying is
+ * the shared core engine in `helpers.ts`.
+ *
+ * @remarks
+ * - **Observable (§13).** The owned {@link emitter} ({@link TableEventMap}) carries the
+ *   per-row mutation moments — `write` (set / add / update), `remove`, `clear` — for
+ *   fire-and-forget observers (cache invalidation, sync, an audit log), ALONGSIDE the
+ *   database-level lifecycle. Events carry the affected KEY only (no value payload, to
+ *   keep fan-out lean); reads / queries / counts are not emitted. Every event is emitted
+ *   directly, strictly AFTER the driver write / delete / clear completes; the emitter
+ *   isolates a listener throw and routes it to its `error` handler (the `error` option),
+ *   so a buggy observer can never corrupt a write or perturb a transaction.
+ */
+export declare class Table<T = Row> implements TableInterface<T> {
+    #private;
+    constructor(ready: () => Promise<void>, driver: DriverInterface, name: string, key: string, contract: ContractInterface<T>, generate?: KeyFunction, on?: EmitterHooks<TableEventMap>, error?: EmitterErrorHandler);
+    get emitter(): EmitterInterface<TableEventMap>;
+    get name(): string;
+    get primary(): string;
+    get contract(): ContractInterface<T>;
+    get(key: Key): Promise<T | undefined>;
+    get(keys: readonly Key[]): Promise<readonly (T | undefined)[]>;
+    resolve(key: Key): Promise<T>;
+    resolve(keys: readonly Key[]): Promise<readonly T[]>;
+    has(key: Key): Promise<boolean>;
+    has(keys: readonly Key[]): Promise<readonly boolean[]>;
+    keys(): Promise<readonly Key[]>;
+    records(criteria?: Criteria, options?: ReadOptions): Promise<readonly T[]>;
+    /**
+     * Count rows matching `criteria`'s conditions.
+     *
+     * @remarks
+     * Unlike {@link records}, which narrows every row through the table's
+     * contract guard before returning it, `count` operates on STORED rows
+     * WITHOUT that guard (both the native `driver.count` hook and the
+     * `filterRows`-over-`#collect()` fallback count raw storage) — so it can
+     * exceed `(await records(criteria)).length` when storage holds rows that
+     * no longer conform to the table's contract (legacy or migrated data).
+     *
+     * @param criteria - Optional conditions to filter by (paging is ignored)
+     * @param options - `{ signal }` to abort
+     * @returns The count of matching stored rows
+     */
+    count(criteria?: Criteria, options?: ReadOptions): Promise<number>;
+    /**
+     * Compute an aggregate over `column` across rows matching `criteria`'s
+     * conditions.
+     *
+     * @remarks
+     * Like {@link count}, `aggregate` operates on STORED rows WITHOUT the
+     * contract guard {@link records} / {@link scan} apply — a non-conforming
+     * stored row still contributes to the computed aggregate when it matches
+     * the conditions, even though it would never appear in `records()`'s
+     * output.
+     *
+     * @param operation - The aggregate to compute
+     * @param column - The column to aggregate
+     * @param criteria - Optional conditions to filter by (paging is ignored)
+     * @param options - `{ signal }` to abort
+     * @returns The aggregate value, or `undefined` when undefined for the inputs
+     */
+    aggregate(operation: AggregateFunction, column: FieldPath, criteria?: Criteria, options?: ReadOptions): Promise<number | undefined>;
+    /**
+     * Stream the table's rows matching `criteria`, applying offset/limit paging.
+     *
+     * @remarks
+     * `criteria.limit` counts rows that pass BOTH the criteria conditions AND the
+     * table's contract guard (a stored row that fails the guard is skipped and
+     * does not count toward `limit`) — this can differ from {@link records}'s
+     * `limit`, which a driver's optional native `records` hook applies BEFORE
+     * the contract guard runs, when storage holds rows that no longer conform
+     * to the table's contract.
+     *
+     * @param criteria - Optional conditions plus offset/limit paging
+     * @param options - `{ signal }` to abort mid-stream
+     * @returns An async iterable of matching, guard-conforming rows
+     */
+    scan(criteria?: Criteria, options?: ReadOptions): AsyncIterable<T>;
+    set(row: T, options?: ReadOptions): Promise<Key>;
+    set(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
+    add(row: T, options?: ReadOptions): Promise<Key>;
+    add(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
+    update(key: Key, changes: Partial<T>, options?: ReadOptions): Promise<boolean>;
+    update(keys: readonly Key[], changes: Partial<T>, options?: ReadOptions): Promise<readonly boolean[]>;
+    remove(key: Key, options?: ReadOptions): Promise<boolean>;
+    remove(keys: readonly Key[], options?: ReadOptions): Promise<readonly boolean[]>;
+    clear(): Promise<void>;
+    query(): QueryInterface<T>;
+    cursor(): Promise<CursorInterface<T>>;
+}
+
+/**
+ * The push observation surface of a {@link TableInterface} (AGENTS §13) — the per-row
+ * mutation moments a fire-and-forget observer (cache invalidation, sync, an audit log)
+ * subscribes to, ALONGSIDE the database-level {@link DatabaseEventMap}.
+ *
+ * @typeParam TKey - The table's primary-key type (a {@link Key}); the events carry the
+ *   affected key so the map is `TableEventMap<TKey>`.
+ *
+ * @remarks
+ * Events carry the affected KEY only — never the row value — to keep fan-out lean and
+ * avoid leaking row data through the observation channel; a consumer that needs the
+ * value re-reads it by key. Any row put — `set`, `add`, or `update` — emits a single
+ * `write` (the consumer re-reads if it needs to know what changed); a delete emits
+ * `remove`; emptying the table emits `clear`. Reads / queries / counts are NOT emitted
+ * (too hot, and a reader does not mutate). Listener isolation is the emitter's (AGENTS §13):
+ * every event is emitted directly and a listener throw is routed to the emitter's `error`
+ * handler (the `error` option), never onto this map, and sits AFTER the driver write / delete
+ * / clear has completed — so a throwing observer can never corrupt a write or perturb a
+ * transaction. Subscribe via `table.emitter.on(...)`. Declared as a `type` alias (§4.5 —
+ * `EventMap` is a `type` kind).
+ */
+export declare type TableEventMap<TKey extends Key = Key> = {
+    /** A row was written (set / added / updated) — the affected key (no value payload). */
+    readonly write: readonly [key: TKey];
+    /** A row was removed — the affected key. */
+    readonly remove: readonly [key: TKey];
+    /** The table was cleared (every row removed). */
+    readonly clear: readonly [];
+};
+
+/**
+ * One table's portable definition, produced by `export` — the unit of schema /
+ * migration exchange across environments.
+ *
+ * @remarks
+ * `schema` is the JSON Schema (universally portable, serializable); `columns` is
+ * the source column map, which re-imports losslessly via `import` within a
+ * TypeScript environment. `key` is the primary-key column.
+ */
+export declare interface TableExport {
+    readonly key: string;
+    readonly columns: Columns;
+    readonly schema: JSONSchema;
+}
+
+/**
+ * Per-table secondary indexes — `{ [table]: groups }`, each group one
+ * (possibly compound) index of column names.
+ *
+ * @remarks
+ * Contracts don't express indexes, so they're declared here on `createDatabase`
+ * and flow into each {@link TableSchema}'s `indexes` (SQLite `CREATE INDEX`,
+ * IndexedDB `createIndex`). Mirrors {@link TableKeys}.
+ */
+export declare type TableIndexes = Readonly<Record<string, readonly (readonly string[])[]>>;
+
+/**
+ * A table — typed keyed CRUD plus fluent query and cursor access.
+ *
+ * @remarks
+ * Writes are coerced through the table's contract: a string input to a numeric
+ * column is normalized, and a row that cannot be coerced throws `VALIDATION`. A
+ * row missing its key is assigned a generated UUID. `get` returns `undefined`
+ * when a key is absent; `resolve` throws `NOT_FOUND`. `set` upserts; `add`
+ * inserts and throws `CONFLICT` on a duplicate key. `contract` exposes the
+ * compiled contract for introspection (`schema`) and fixtures (`generate`).
+ *
+ * The keyed methods batch by overload (AGENTS §9.2): pass one key/row for one
+ * result, or an array for an array of results in the same order — a single verb,
+ * never `getMany` / `setAll`. Batches run as independent sequential operations;
+ * wrap them in `transaction` for atomicity.
+ */
+export declare interface TableInterface<T = Row> {
+    readonly emitter: EmitterInterface<TableEventMap>;
+    readonly name: string;
+    readonly primary: string;
+    readonly contract: ContractInterface<T>;
+    get(key: Key): Promise<T | undefined>;
+    get(keys: readonly Key[]): Promise<readonly (T | undefined)[]>;
+    resolve(key: Key): Promise<T>;
+    resolve(keys: readonly Key[]): Promise<readonly T[]>;
+    has(key: Key): Promise<boolean>;
+    has(keys: readonly Key[]): Promise<readonly boolean[]>;
+    keys(): Promise<readonly Key[]>;
+    records(criteria?: Criteria, options?: ReadOptions): Promise<readonly T[]>;
+    /**
+     * Count rows matching `criteria`'s conditions.
+     *
+     * @remarks
+     * `records()` / `scan()` narrow every row through the table's contract
+     * guard before returning it, so a non-conforming stored row (legacy data,
+     * a row from before a migration) never appears in their results. `count`
+     * operates on STORED rows WITHOUT that guard — it counts whatever
+     * conditions-matches in storage, guard-conforming or not. This means
+     * `count()` CAN exceed `(await records(criteria)).length` when storage
+     * holds rows that no longer conform to the table's contract.
+     */
+    count(criteria?: Criteria, options?: ReadOptions): Promise<number>;
+    /**
+     * Compute an aggregate over `column` across rows matching `criteria`'s
+     * conditions.
+     *
+     * @remarks
+     * Like {@link TableInterface.count}, `aggregate` operates on STORED rows
+     * WITHOUT the contract guard that `records()` / `scan()` apply — a
+     * non-conforming stored row still contributes to the aggregate (or to the
+     * `count` operation's tally) when it matches the conditions, even though
+     * it would never appear in `records()`'s output.
+     */
+    aggregate(operation: AggregateFunction, column: FieldPath, criteria?: Criteria, options?: ReadOptions): Promise<number | undefined>;
+    /**
+     * Lazy filtered iteration over the table's rows.
+     *
+     * @remarks
+     * `criteria`'s `conditions` / `offset` / `limit` are honored lazily as rows
+     * stream; `order` is intentionally IGNORED — streaming yields driver
+     * key-order, sorted output is `records()`'s job. Breaking out of the
+     * iteration early closes the underlying source. The signal (if any) is
+     * checked before each yield.
+     */
+    scan(criteria?: Criteria, options?: ReadOptions): AsyncIterable<T>;
+    /**
+     * Upsert one or more rows.
+     *
+     * @param row - The row to upsert
+     * @param options - Optional abort signal
+     * @returns The row's key
+     */
+    set(row: T, options?: ReadOptions): Promise<Key>;
+    /**
+     * Upsert one or more rows.
+     *
+     * @param rows - The rows to upsert
+     * @param options - Optional abort signal, checked at entry and between items
+     * @returns Each row's key, in order
+     *
+     * @remarks
+     * The signal (if any) is checked at entry and between items; an abort
+     * surfaces as `DatabaseError` `ABORTED`. Already-applied items stay
+     * applied — there is no rollback. Wrap in `transaction()` for atomicity.
+     */
+    set(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
+    /**
+     * Insert one or more rows, throwing `CONFLICT` on a duplicate key.
+     *
+     * @param row - The row to insert
+     * @param options - Optional abort signal
+     * @returns The row's key
+     */
+    add(row: T, options?: ReadOptions): Promise<Key>;
+    /**
+     * Insert one or more rows, throwing `CONFLICT` on a duplicate key.
+     *
+     * @param rows - The rows to insert
+     * @param options - Optional abort signal, checked at entry and between items
+     * @returns Each row's key, in order
+     *
+     * @remarks
+     * The signal (if any) is checked at entry and between items; an abort
+     * surfaces as `DatabaseError` `ABORTED`. Already-applied items stay
+     * applied — there is no rollback. Wrap in `transaction()` for atomicity.
+     */
+    add(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
+    /**
+     * Apply a partial change to one or more rows.
+     *
+     * @param key - The key of the row to update
+     * @param changes - The partial changes to apply
+     * @param options - Optional abort signal
+     * @returns `true` when the row existed and was updated
+     */
+    update(key: Key, changes: Partial<T>, options?: ReadOptions): Promise<boolean>;
+    /**
+     * Apply a partial change to one or more rows.
+     *
+     * @param keys - The keys of the rows to update
+     * @param changes - The partial changes to apply to each row
+     * @param options - Optional abort signal, checked at entry and between items
+     * @returns Each row's update result, in order
+     *
+     * @remarks
+     * The signal (if any) is checked at entry and between items; an abort
+     * surfaces as `DatabaseError` `ABORTED`. Already-applied items stay
+     * applied — there is no rollback. Wrap in `transaction()` for atomicity.
+     */
+    update(keys: readonly Key[], changes: Partial<T>, options?: ReadOptions): Promise<readonly boolean[]>;
+    /**
+     * Delete one or more rows.
+     *
+     * @param key - The key of the row to remove
+     * @param options - Optional abort signal
+     * @returns `true` when the row existed and was removed
+     */
+    remove(key: Key, options?: ReadOptions): Promise<boolean>;
+    /**
+     * Delete one or more rows.
+     *
+     * @param keys - The keys of the rows to remove
+     * @param options - Optional abort signal, checked at entry and between items
+     * @returns Each row's removal result, in order
+     *
+     * @remarks
+     * The signal (if any) is checked at entry and between items; an abort
+     * surfaces as `DatabaseError` `ABORTED`. Already-applied items stay
+     * applied — there is no rollback. Wrap in `transaction()` for atomicity.
+     */
+    remove(keys: readonly Key[], options?: ReadOptions): Promise<readonly boolean[]>;
+    clear(): Promise<void>;
+    query(): QueryInterface<T>;
+    cursor(): Promise<CursorInterface<T>>;
+}
+
+/**
+ * Per-table primary-key column overrides — `{ [table]: column }`.
+ *
+ * @remarks
+ * A table absent from this map keys its rows by {@link DEFAULT_PRIMARY} (`id`).
+ * Kept separate from {@link TablesShape} so the table map stays purely columns.
+ */
+export declare type TableKeys = Readonly<Record<string, string>>;
+
+/**
+ * A backend-agnostic description of one table — what `open` hands each driver so a
+ * native backend can create real tables and indexes.
+ *
+ * @remarks
+ * Derived by the database from its `tables` contract shapes ({@link ColumnSchema}
+ * per column, via `shapeToColumnType`), its `keys` (`primary`), and its `indexes` option
+ * (`indexes`, each entry one possibly-compound index of column names). A scan-only
+ * backend (the reference `MemoryDriver`) ignores everything but `name`.
+ */
+export declare interface TableSchema {
+    readonly name: string;
+    readonly primary: string;
+    readonly columns: readonly ColumnSchema[];
+    readonly indexes: readonly (readonly string[])[];
+}
+
+/**
+ * A database's table schema — a map of table name to its {@link Columns}.
+ *
+ * @remarks
+ * Each table's row type is `Infer` of its columns (see {@link RowOf}); primary-key
+ * columns are named separately via {@link TableKeys}.
+ */
+export declare type TablesShape = Readonly<Record<string, Columns>>;
+
+/**
+ * The handle a driver's native `transaction` hook returns.
+ *
+ * @remarks
+ * `commit` finalizes the native BEGIN; `rollback` undoes it. When a driver
+ * implements {@link DriverInterface.transaction}, the engine uses this handle
+ * instead of the snapshot-based rollback floor.
+ */
+export declare interface TransactionInterface {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+
+/** The number of bytes encoded by an RFC 4122 UUID. */
+export declare const UUID_BYTE_COUNT = 16;
+
+/** The number of distinct values one UUID byte may hold. */
+export declare const UUID_BYTE_RANGE = 256;
+
+/**
+ * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+ * engine behind {@link likeMatch} and {@link globMatch}.
+ *
+ * @remarks
+ * A backtracking RegExp (`a%b%c` → `^a.*b.*c$`) is CATASTROPHIC on a hostile pattern:
+ * `.*` segments separated by literals, matched against a long non-matching input, blow
+ * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it
+ * (AGENTS §6.5, now that the authed server runs model-supplied `list` criteria over the
+ * wire). So this builds NO regex. It runs the classic GREEDY TWO-POINTER wildcard match:
+ * the `any` wildcard records its position and, on a later mismatch, backtracks ONLY to
+ * that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
+ * never the exponential / polynomial backtracking a regex would do. The pattern length
+ * is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
+ * bounding the pattern factor so a match stays linear in the value length whatever the
+ * pattern.
+ *
+ * The `any` wildcard matches any run (including empty); `single` matches exactly one
+ * char; every other pattern char matches itself LITERALLY (a pattern `.` / `(` / `\` is
+ * a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
+ * BEFORE a literal match, so a value that literally contains the wildcard char never
+ * shadows the wildcard. Case folding is applied to BOTH sides when `fold` is set.
+ *
+ * @param value - The value to test
+ * @param pattern - The wildcard pattern
+ * @param any - The any-run wildcard char (`%` for `LIKE`, `*` for `GLOB`)
+ * @param single - The single-char wildcard char (`_` for `LIKE`, `?` for `GLOB`)
+ * @param fold - Whether to match case-INSENSITIVELY (`LIKE` folds; `GLOB` does not)
+ * @returns Whether `value` matches `pattern`
+ * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
+ */
+export declare function wildcardMatch(value: string, pattern: string, any: string, single: string, fold: boolean): boolean;
+
+export { }