@orkestrel/database 0.0.6 → 0.0.7

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

@@ -6,25 +6,24 @@ 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';
+export declare type AggregateOperation = 'count' | 'sum' | 'average' | 'minimum' | 'maximum';
 
 /**
- * Apply a {@link Criteria} to rows — filter, then sort, then page.
+ * Apply a {@link QueryInput} 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
+ * part of the input 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
+ * @param input - 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[];
+export declare function applyQuery(rows: readonly Row[], input?: QueryInput): readonly Row[];
 
 /**
  * Run the FULL driver-conformance battery and collect every violation — the
@@ -50,15 +49,25 @@ export declare function applyCriteria(rows: readonly Row[], criteria?: Criteria)
 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.
+ * Return a fresh row whose primary column is authoritatively bound to its storage key.
+ *
+ * @param row - The caller row
+ * @param primary - The primary column
+ * @param key - The authoritative storage key
+ * @returns A fresh row with the bound primary
+ */
+export declare function bindRowKey(row: Row, primary: string, key: Key): Row;
+
+/**
+ * Throw when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
+ * abort 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`).
+ * mint signals with native APIs such as `AbortSignal.timeout(ms)` or
+ * `new AbortController()`.
  *
  * @param signal - The signal to check, if any
  * @returns Nothing — returns normally while the signal is live
@@ -77,59 +86,28 @@ export declare function auditDriver(factory: () => DriverInterface): Promise<rea
 export declare function checkAbort(signal: AbortSignal | undefined): void;
 
 /**
- * A pending condition opened by a query's `where` / `and` / `or`.
+ * Clone unknown driver metadata into a distinct deeply frozen snapshot.
  *
- * @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.
+ * @param value - Unknown metadata
+ * @returns Owned driver metadata
  */
-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>;
-}
+export declare function cloneDriverMetadata(value: unknown): DriverMetadata;
 
 /**
- * A pending condition opened by `where` / `and` / `or`.
+ * Clone unknown driver schema into a distinct deeply frozen snapshot.
  *
- * @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>;
-}
+ * @param value - Unknown table schema collection
+ * @returns Owned driver schema
+ */
+export declare function cloneDriverSchema(value: unknown): readonly TableSchema[];
+
+/**
+ * Clone unknown migration input into a distinct deeply frozen snapshot.
+ *
+ * @param value - Unknown migration input
+ * @returns Owned migration input
+ */
+export declare function cloneMigrationInput(value: unknown): MigrationInput;
 
 /**
  * One table's columns — a map of column name to its value {@link ContractShape}.
@@ -141,25 +119,27 @@ export declare interface ClauseInterface<T = Row> {
  * 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>>;
+export declare type ColumnMap = 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`).
+ * One column of a {@link TableSchema} — its name, portable {@link ColumnStorage}, and
+ * whether it independently accepts absence (`optional`) and explicit `null`
+ * (`nullable`).
  */
 export declare interface ColumnSchema {
     readonly name: string;
-    readonly type: ColumnType;
+    readonly storage: ColumnStorage;
+    readonly optional: boolean;
     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
+ * by `shapeToColumnStorage`; `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';
+export declare type ColumnStorage = 'text' | 'integer' | 'real' | 'boolean' | 'json' | 'blob';
 
 /**
  * A total ordering over arbitrary values — the comparator behind sorting and the
@@ -191,7 +171,7 @@ export declare function compareValues(left: unknown, right: unknown): number;
  * @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;
+export declare function computeAggregate(rows: readonly unknown[], operation: AggregateOperation, column: FieldPath): number | undefined;
 
 /**
  * One compiled WHERE condition.
@@ -208,9 +188,12 @@ export declare interface Condition {
     readonly column: FieldPath;
     readonly operator: ConditionOperator;
     readonly values: readonly unknown[];
-    readonly connector: Connector;
+    readonly connector: ConditionConnector;
 }
 
+/** How a {@link Condition} joins to the running result of the conditions before it. */
+export declare type ConditionConnector = 'and' | 'or';
+
 /**
  * A WHERE operator — the comparison a single {@link Condition} applies.
  *
@@ -261,9 +244,6 @@ export declare interface ConformanceFinding {
  */
 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.
  *
@@ -273,10 +253,10 @@ export declare type Connector = 'and' | 'or';
  * 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.
+ * optional `primary` and `indexes` maps.
  *
- * @param options - The driver, the `tables` column map, optional `keys`, and an
- *                   optional `name`
+ * @param options - The driver, `tables`, and optional `primary`, `indexes`,
+ *   `name`, `generator`, `version`, and emitter hooks
  * @returns A typed {@link DatabaseInterface}
  *
  * @example
@@ -290,12 +270,12 @@ export declare type Connector = 'and' | 'or';
  * 		users: { id: stringShape(), age: integerShape() },
  * 		posts: { slug: stringShape(), title: stringShape() },
  * 	},
- * 	keys: { posts: 'slug' },
+ * 	primary: { 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>;
+export declare function createDatabase<const T extends TableMap>(options: DatabaseOptions<T>): DatabaseInterface<T>;
 
 /**
  * Create the in-memory reference {@link DriverInterface}.
@@ -308,49 +288,17 @@ export declare function createDatabase<const T extends TablesShape>(options: Dat
  */
 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.
+ * Promise operations execute serially in invocation order, and one rejection
+ * does not prevent later admitted work. `done` is `true` once iteration has
+ * advanced past the last key. `close` is synchronous and terminal: it clears
+ * the current value, queued work becomes a no-op, and in-flight work never
+ * republishes a value after settling.
  */
 export declare interface CursorInterface<T = Row> {
     readonly value: T | undefined;
@@ -363,82 +311,27 @@ export declare interface CursorInterface<T = Row> {
 }
 
 /**
- * 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.
+ * A typed database view over one shared internal lifecycle and storage context.
  *
  * @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> {
+ * Each view owns only its table contracts, primary columns, indexes, and key
+ * generator. Imported views register their physical schemas with the same
+ * internal context before opening begins, so every view observes one driver,
+ * merged schema, emitter, status, transaction boundary, and terminal close.
+ */
+export declare class Database<T extends TableMap = TableMap> 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>>;
+    import<U extends TableMap>(tables: U, primary?: PrimaryMap): DatabaseInterface<U>;
+    export(): Readonly<Record<string, TableDefinition>>;
     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>;
+    transaction<R>(scope: (transaction: DatabaseStorageInterface<T>) => Promise<R>, options?: OperationOptions): Promise<R>;
+    migrate(deployed: readonly TableSchema[], options?: OperationOptions): Promise<Migration>;
 }
 
 /**
@@ -448,8 +341,8 @@ export declare class Database<T extends TablesShape = TablesShape> implements Da
  * 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
+ * row that fails its table's contract (`VALIDATION`), an aborted operation whose
+ * {@link OperationOptions.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
@@ -478,9 +371,10 @@ export declare type DatabaseErrorCode = 'CLOSED' | 'NOT_FOUND' | 'CONFLICT' | 'V
  * 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(...)`.
+ * relevant transition: `commit` only after the scope succeeds, `rollback` only after the
+ * rollback operation completes (it OBSERVES the propagated scope error; that exact reason
+ * still propagates). A rollback failure propagates instead and emits no misleading
+ * `rollback` event. 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
@@ -492,11 +386,11 @@ export declare type DatabaseEventMap = {
     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. */
+    /** A transaction scope began after its native boundary or fallback snapshot was acquired. */
     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. */
+    /** A transaction scope failed and rollback completed — the exact propagated scope error. */
     readonly rollback: readonly [error: unknown];
     /** A {@link Migration} plan was applied via `migrate` — the applied plan. */
     readonly migrate: readonly [migration: Migration];
@@ -512,22 +406,21 @@ export declare type DatabaseEventMap = {
  * 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.
+ * data); `export` produces a portable {@link TableDefinition} per table for moving a
+ * schema between databases or environments. `transaction` runs a table-only
+ * scoped callback through a native driver transaction when available, otherwise
+ * through the universal whole-store snapshot floor.
  */
-export declare interface DatabaseInterface<T extends TablesShape = TablesShape> {
+export declare interface DatabaseInterface<T extends TableMap = TableMap> {
     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>>;
+    import<U extends TableMap>(tables: U, primary?: PrimaryMap): DatabaseInterface<U>;
+    export(): Readonly<Record<string, TableDefinition>>;
     open(): Promise<void>;
     close(): Promise<void>;
-    transaction<R>(scope: () => Promise<R>, options?: ReadOptions): Promise<R>;
+    transaction<R>(scope: (transaction: DatabaseStorageInterface<T>) => Promise<R>, options?: OperationOptions): Promise<R>;
     /**
      * Diff a caller-supplied deployed schema against this database's declared
      * schema (its `tables`, as configured) via `planMigration`, apply the
@@ -542,11 +435,20 @@ export declare interface DatabaseInterface<T extends TablesShape = TablesShape>
      * 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.
+     * entry. For explicit `migrate`, driver open and migration apply form one
+     * readiness transition: status and the `open` event publish only after apply
+     * succeeds. A failed explicit apply blocks ordinary open/table work with that
+     * exact failure until a later explicit `migrate` succeeds; `close` remains
+     * available. Automatic versioned open has a separate lifecycle: successful
+     * physical driver open publishes `open` status and one `open` event before
+     * reconciliation. If reconciliation fails, its readiness Promise and table
+     * work reject until a later automatic retry succeeds on the same physical
+     * handle. Emits the `migrate` event after a successful apply. Explicit
+     * migration still accepts the caller's deployed schema; versioned open uses
+     * {@link DatabaseOptions.version} with a driver's paired `metadata` / `stamp`
+     * capabilities to persist and reconcile deployed version metadata.
      */
-    migrate(deployed: readonly TableSchema[], options?: ReadOptions): Promise<Migration>;
+    migrate(deployed: readonly TableSchema[], options?: OperationOptions): Promise<Migration>;
 }
 
 /**
@@ -554,37 +456,55 @@ export declare interface DatabaseInterface<T extends TablesShape = TablesShape>
  *
  * @remarks
  * `driver` is the storage backend; `tables` declares each table's columns;
- * `keys` overrides the primary-key column per table ({@link DEFAULT_PRIMARY}
+ * `primary` 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).
+ * `generator` is the authoritative key-generation override a table uses when a
+ * written row's primary is exactly `undefined`. When omitted, the table uses
+ * global `crypto.randomUUID()`; numeric primary keys require a custom generator.
  */
-export declare interface DatabaseOptions<T extends TablesShape = TablesShape> {
+export declare interface DatabaseOptions<T extends TableMap = TableMap> {
     readonly on?: EmitterHooks<DatabaseEventMap>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /**
+     * The listener-error handler shared by the database and every table emitter.
+     *
+     * @remarks
+     * Listener throws from root, imported, and transaction-scoped handles route
+     * here as `(error, event)`, never to a domain event and never into the
+     * completed operation.
+     */
     readonly error?: EmitterErrorHandler;
     readonly driver: DriverInterface;
     readonly tables: T;
-    readonly keys?: TableKeys;
-    readonly indexes?: TableIndexes;
+    readonly primary?: PrimaryMap;
+    readonly indexes?: IndexMap;
     readonly name?: string;
-    readonly key?: KeyFunction;
+    /**
+     * The authoritative key-generation override for a keyless write.
+     *
+     * @remarks
+     * Omit it to use global `crypto.randomUUID()`. A numeric primary requires a
+     * custom generator. Explicit primary values never invoke this function. A
+     * custom generator throw is `VALIDATION`; a host
+     * `crypto.randomUUID()` failure is `DRIVER`. An invalid returned key is
+     * `VALIDATION`; neither branch falls back or retries.
+     */
+    readonly generator?: KeyFunction;
     /**
      * The declared schema version.
      *
      * @remarks
-     * Only meaningful when the driver implements BOTH {@link DriverInterface.meta}
+     * Only meaningful when the driver implements BOTH {@link DriverInterface.metadata}
      * 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.
+     * driver's persisted {@link DriverMetadata}:
+     * - **Fresh store** (`metadata()` returns `undefined` after the durable
+     *   driver proves absence) — 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,
@@ -592,13 +512,14 @@ export declare interface DatabaseOptions<T extends TablesShape = TablesShape> {
      *   `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.
+     * - **Stored version === `version`** — the persisted and declared schemas
+     *   must still match. Schema drift throws `DatabaseError` `MIGRATION`;
+     *   otherwise `open()` is a 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.
+     * A non-empty version upgrade passes both the plan and target metadata to
+     * {@link DriverInterface.migrate} as one {@link MigrationInput}; the driver
+     * settles both atomically. A zero-step version transition may use `stamp`
+     * directly because no schema or rows change.
      */
     readonly version?: number;
 }
@@ -607,45 +528,28 @@ export declare interface DatabaseOptions<T extends TablesShape = TablesShape> {
 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".
+ * A database view valid only inside one {@link DatabaseInterface.transaction}
+ * scope.
  *
  * @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
- * ```
+ * The view exposes only declared tables backed by the driver's scoped
+ * {@link StorageInterface}. It cannot open, close, import, migrate, or nest
+ * a transaction. The view and every table captured from it throw `CONFLICT`
+ * after the scope settles.
  */
-export declare function deepEqual(left: unknown, right: unknown): boolean;
+export declare interface DatabaseStorageInterface<T extends TableMap = TableMap> {
+    table<K extends keyof T & string>(name: K): TableInterface<RowOf<T[K]>>;
+}
 
 /**
- * The primary-key column assumed when {@link TableKeys} does not name one.
+ * The primary-key column assumed when {@link PrimaryMap} 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`.
+ * lean on, so a table without a `primary` override 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 —
@@ -661,21 +565,24 @@ export declare type Direction = 'ascending' | 'descending';
  * `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`;
+ * stored state) and upsert-overwrite; simultaneous same-key `insert` calls
+ * produce exactly one commit and one `CONFLICT`; pre-aborted `write`,
+ * `insert`, and `delete` calls leave storage unchanged; `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
+ * round-trips structurally (via {@link equalsValue}). 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.
+ * exists, `commit` persists and `rollback` restores; when both `metadata` and
+ * `stamp` exist, a fresh store's `metadata()` is `undefined`, and after
+ * `stamp({ version, schema })`, `metadata()` 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
@@ -706,107 +613,92 @@ export declare function driverFindings(factory: () => DriverInterface): AsyncIte
  * 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
+ * The REQUIRED surface is deliberately minimal: keyed read / write / atomic
+ * insert / 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
+ * optional `records?` / `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).
+ * `false` rather than throwing (AGENTS §12). Metadata has the same ownership
+ * boundary across every implementation: `stamp` and `migrate` snapshot
+ * {@link DriverMetadata} at entry, while `metadata` returns a distinct deeply frozen
+ * snapshot. A durable driver returns `undefined` only when it proves the
+ * metadata record or durable store is absent. Existing unreadable or malformed
+ * durable state fails `open` / `metadata` closed; it is never treated as fresh,
+ * rewritten, or repaired automatically.
  */
-export declare interface DriverInterface {
+export declare interface DriverInterface extends StorageInterface {
     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).
+     * Capture table rows and return a repeatable thunk that restores those rows —
+     * the primitive transactions are built on.
      *
      * @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.
+     * Snapshots are row-only: they never restore schema or driver metadata.
+     * `tables` omitted captures every current table. `tables` provided captures
+     * only existing named tables. Rollback skips captured tables removed since
+     * capture and leaves every uncaptured or later-added 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.
+     * Optional native transaction scope. The driver owns acquisition, commit or
+     * rollback, release, and invalidation of the scoped capability.
      */
-    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>;
+    transaction?<R>(scope: (storage: StorageInterface) => Promise<R>): Promise<R>;
 }
 
 /**
- * Persisted schema metadata a versioning driver stores verbatim and returns on
- * demand.
+ * Persisted schema metadata a versioning driver owns as an immutable snapshot.
  *
  * @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.
+ * A driver snapshots metadata when it enters through `stamp` or a
+ * {@link MigrationInput}, so later caller mutation cannot alter stored version
+ * state. `metadata()` returns a distinct deeply frozen owned snapshot, never the
+ * driver's internal reference. `undefined` distinguishes a fresh store from an
+ * upgradable one: it means the store has never been stamped, not that it is at
+ * version zero.
  */
-export declare interface DriverMeta {
+export declare interface DriverMetadata {
     readonly version: number;
     readonly schema: readonly TableSchema[];
 }
 
+/**
+ * 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 `equalsValue`). 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 `equalsValue` 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`. Container pairs are tracked iteratively, so self-referential and
+ * mutually cyclic arrays/records terminate without consuming the call stack.
+ * Hostile proxy traps and accessors are contained as a non-match.
+ *
+ * @param left - The left value
+ * @param right - The right value
+ * @returns Whether `left` and `right` are structurally equal
+ *
+ * @example
+ * ```ts
+ * equalsValue(Number.NaN, Number.NaN) // true
+ * equalsValue({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }) // true
+ * equalsValue({ a: undefined }, {}) // false — present-undefined ≠ absent
+ * ```
+ */
+export declare function equalsValue(left: unknown, right: unknown): boolean;
+
 /**
  * Read a row's primary key from a column, when it is a usable {@link Key}.
  *
@@ -818,11 +710,11 @@ 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}).
+ * and aggregate paths (no sort/page, unlike {@link applyQuery}).
  *
  * @remarks
  * An empty condition list matches every row (returned as-is, no copy). Folds
- * each row through {@link matchesCriteria}.
+ * each row through {@link matchesQuery}.
  *
  * @param rows - The rows to filter
  * @param conditions - The conditions to apply (empty matches everything)
@@ -839,35 +731,23 @@ export declare function extractKey(row: Row, column: string): Key | undefined;
 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.
+ * Per-table secondary indexes — `{ [table]: groups }`, each group one
+ * (possibly compound) index of column names.
  *
  * @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
- * ```
+ * 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 PrimaryMap}.
  */
-export declare function generateUUID(random?: RandomFunction): string;
+export declare type IndexMap = Readonly<Record<string, readonly (readonly string[])[]>>;
 
-export declare function globMatch(value: string, pattern: string): boolean;
+/**
+ * Test whether a value is a portable column schema.
+ *
+ * @param value - The value to test
+ * @returns Whether `value` is a complete {@link ColumnSchema}
+ */
+export declare function isColumnSchema(value: unknown): value is ColumnSchema;
 
 /**
  * Narrow an unknown caught value to a {@link DatabaseError}.
@@ -887,53 +767,82 @@ export declare function globMatch(value: string, pattern: string): boolean;
 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`).
+ * Test whether a value is persisted driver metadata.
  *
- * @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 Whether `value` is complete {@link DriverMetadata}
+ */
+export declare function isDriverMetadata(value: unknown): value is DriverMetadata;
+
+/**
+ * Test whether a value is a complete portable driver schema.
  *
  * @param value - The value to test
- * @returns `true` when `value` is a well-formed `DriverMeta`
+ * @returns Whether `value` is a table-schema collection with unique table names
+ */
+export declare function isDriverSchema(value: unknown): value is readonly TableSchema[];
+
+/**
+ * Test whether a value is a usable database key.
  *
- * @example
- * ```ts
- * isDriverMeta({ version: 1, schema: [] }) // true
- * isDriverMeta({ version: 1, schema: [{ name: 'users' }] }) // false
- * ```
+ * @param value - The value to test
+ * @returns Whether `value` is a string or finite number
+ */
+export declare function isKey(value: unknown): value is Key;
+
+/**
+ * Test whether a value is an ordered migration plan.
+ *
+ * @param value - The value to test
+ * @returns Whether `value` is a complete {@link Migration}
+ */
+export declare function isMigration(value: unknown): value is Migration;
+
+/**
+ * Test whether a value is one atomic migration request.
+ *
+ * @param value - The value to test
+ * @returns Whether `value` is a complete {@link MigrationInput}
+ */
+export declare function isMigrationInput(value: unknown): value is MigrationInput;
+
+/**
+ * Test whether a value is one ordered migration step.
+ *
+ * @param value - The value to test
+ * @returns Whether `value` is a complete {@link MigrationStep}
+ */
+export declare function isMigrationStep(value: unknown): value is MigrationStep;
+
+/**
+ * Test whether a value is a portable table schema.
+ *
+ * @param value - The value to test
+ * @returns Whether `value` is a complete {@link TableSchema}
  */
-export declare function isDriverMeta(value: unknown): value is DriverMeta;
+export declare function isTableSchema(value: unknown): value is TableSchema;
 
 /**
  * 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.
+ * primary keys both express without coercion. The default generated key is a
+ * UUID string; configure a custom generator for numeric primary keys.
  */
 export declare type Key = string | number;
 
 /**
- * A caller-supplied key minting function.
+ * A key-generating 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.
+ * Supplied through {@link DatabaseOptions.generator} as an authoritative
+ * override when an application needs a non-UUID key or controlled generation.
+ * When omitted, a keyless write uses the global `crypto.randomUUID()`. Numeric
+ * primary keys therefore require a custom generator.
  */
 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.
  *
@@ -942,10 +851,10 @@ export declare function likeMatch(value: string, pattern: string): boolean;
  * 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
+ * / `any` / `none`) uses {@link equalsValue} — 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
+ * object. This is a semantics change from ranking: `equalsValue` 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
@@ -957,6 +866,10 @@ export declare function likeMatch(value: string, pattern: string): boolean;
  */
 export declare function matchesCondition(row: Row, condition: Condition): boolean;
 
+export declare function matchesGlobPattern(value: string, pattern: string): boolean;
+
+export declare function matchesLikePattern(value: string, pattern: string): boolean;
+
 /**
  * Fold a row through a list of conditions, joining each by its connector.
  *
@@ -970,14 +883,47 @@ export declare function matchesCondition(row: Row, condition: Condition): boolea
  * @param conditions - The conditions to fold
  * @returns Whether the row satisfies the combined conditions
  */
-export declare function matchesCriteria(row: Row, conditions: readonly Condition[]): boolean;
+export declare function matchesQuery(row: Row, conditions: readonly Condition[]): boolean;
+
+/**
+ * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+ * engine behind {@link matchesLikePattern} and {@link matchesGlobPattern}.
+ *
+ * @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` input 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 matchesWildcardPattern(value: string, pattern: string, any: string, single: string, fold: boolean): 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
+ * input over the wire, so `matchesLikePattern` / `matchesGlobPattern` 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 ×
@@ -998,21 +944,24 @@ export declare const MAX_PATTERN_LENGTH = 1024;
  * 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`
+ * would still share nested object/array references. Metadata instead routes
+ * through `cloneDriverMetadata`: `stamp` and migration snapshot exact JSON at
+ * ingress, and `metadata` returns a distinct deeply frozen owned copy. `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.
+ * implements the same required 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>;
+    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>;
     /**
@@ -1021,17 +970,17 @@ export declare class MemoryDriver implements DriverInterface {
      * @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
+     * `input.conditions` (via {@link matchesQuery}) 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
+     * walked for a small page. `input.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
+     * @param input - The filter / offset / limit to apply lazily
      *
      * @example
      * ```ts
@@ -1040,49 +989,51 @@ export declare class MemoryDriver implements DriverInterface {
      * }
      * ```
      */
-    stream(table: string, criteria: Criteria): AsyncIterable<Row>;
+    stream(table: string, input: QueryInput): 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.
+     * Capture owns rows, schema, and one session-local table identity. Replay
+     * adapts rows to each surviving same-identity table's current schema before
+     * changing storage. Removed or replaced tables are skipped; uncaptured and
+     * later-added tables retain their current rows. Schema and metadata are never
+     * restored.
      *
      * @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
+     * Return the persisted {@link DriverMetadata}, 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.
+     * like the rest of this driver's storage. The returned value is a distinct
+     * deeply frozen owned snapshot. A driver-conformance-valid implementation of
+     * the optional `metadata` / `stamp` pair.
      *
-     * @returns The last-stamped {@link DriverMeta}, or `undefined`
+     * @returns The last-stamped {@link DriverMetadata}, or `undefined`
      */
-    meta(): Promise<DriverMeta | undefined>;
+    metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist `meta` verbatim for a later `meta()` to return.
+     * Persist an owned snapshot for a later `metadata()` to return.
      *
-     * @param meta - The {@link DriverMeta} to persist
+     * @param metadata - The {@link DriverMetadata} to persist
      */
-    stamp(meta: DriverMeta): Promise<void>;
+    stamp(metadata: DriverMetadata): Promise<void>;
     /**
      * Apply a {@link Migration} plan'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.
+     * Steps apply against an isolated candidate. Rows, schema changes, and
+     * optional metadata publish together only after the whole request succeeds.
      *
-     * @param plan - The migration plan to apply
+     * @param input - The migration plan and optional metadata to settle atomically
      */
-    migrate(plan: Migration): Promise<void>;
+    migrate(input: MigrationInput): Promise<void>;
 }
 
 /**
@@ -1124,6 +1075,19 @@ export declare interface Migration {
     readonly steps: readonly MigrationStep[];
 }
 
+/**
+ * One atomic migration request.
+ *
+ * @remarks
+ * `plan` carries the schema changes. `metadata`, when present, is the snapshot that
+ * must settle in the same atomic unit as those changes so a failed migration
+ * cannot expose a new schema under stale version metadata.
+ */
+export declare interface MigrationInput {
+    readonly plan: Migration;
+    readonly metadata?: DriverMetadata;
+}
+
 /**
  * One step of a {@link Migration} plan — a single schema change applied to one
  * table.
@@ -1158,12 +1122,42 @@ export declare type MigrationStep = {
     readonly index: readonly string[];
 };
 
+/**
+ * Canonicalize an unknown driver schema into a distinct deeply frozen snapshot.
+ *
+ * @remarks
+ * Table and column lists are sorted by name. The index list is sorted by the
+ * complete serialized tuple while column order inside each compound index is
+ * preserved because it carries index semantics. Validation and ownership flow
+ * through {@link cloneDriverSchema} before and after projection.
+ *
+ * @param value - Unknown driver schema
+ * @returns A validated, owned canonical schema
+ */
+export declare function normalizeDriverSchema(value: unknown): readonly TableSchema[];
+
+/**
+ * Options for an abortable operation.
+ *
+ * @remarks
+ * When `signal` aborts, the operation throws a {@link DatabaseError} with code
+ * `ABORTED` carrying `signal.reason` in `context`. Reads check at their
+ * documented boundaries; point mutations propagate the signal through the
+ * driver to the backend commit point.
+ */
+export declare interface OperationOptions {
+    readonly signal?: AbortSignal;
+}
+
 /** One ordering term — a column ({@link FieldPath}, flat or nested) and its direction. */
 export declare interface Order {
     readonly column: FieldPath;
-    readonly direction: Direction;
+    readonly direction: OrderDirection;
 }
 
+/** A sort direction. */
+export declare type OrderDirection = 'ascending' | 'descending';
+
 /**
  * Structurally diff a deployed and a declared table set into a {@link Migration}
  * plan.
@@ -1177,11 +1171,12 @@ export declare interface Order {
  * `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.
+ * plan labels only; versioning drivers persist and reconcile them through
+ * {@link DriverMetadata}.
  *
  * A column present in BOTH schemas under the same name but with a different
- * `type` or `nullable` throws a `MIGRATION` {@link DatabaseError} naming the
+ * `storage`, `optional`, or `nullable` value 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
@@ -1194,14 +1189,16 @@ export declare interface Order {
  * @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`
+ * @throws A `MIGRATION` {@link DatabaseError} when a shared table's primary or
+ * a shared column's `storage`, `optional`, or `nullable` differs, or when a
+ * required non-null column would be added to an existing table without a
+ * portable backfill
  *
  * @example
  * ```ts
  * const plan = planMigration(
- * 	[{ name: 'users', primary: 'id', columns: [], indexes: [] }],
- * 	[{ name: 'users', primary: 'id', columns: [{ name: 'age', type: 'integer', nullable: false }], indexes: [] }],
+ * 	[{ name: 'users', primary: 'id', columns: [{ name: 'id', storage: 'text', optional: false, nullable: false }], indexes: [] }],
+ * 	[{ name: 'users', primary: 'id', columns: [{ name: 'id', storage: 'text', optional: false, nullable: false }, { name: 'age', storage: 'integer', optional: true, nullable: false }], indexes: [] }],
  * )
  * // plan.steps === [{ operation: 'column.add', table: 'users', column: { name: 'age', ... } }]
  * ```
@@ -1209,74 +1206,62 @@ export declare interface Order {
 export declare function planMigration(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number): Migration;
 
 /**
- * A fluent query builder bound to one table.
+ * Per-table primary-key column overrides — `{ [table]: column }`.
  *
  * @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 table absent from this map keys its rows by {@link DEFAULT_PRIMARY} (`id`).
+ * Kept separate from {@link TableMap} so the table map stays purely columns.
+ */
+export declare type PrimaryMap = Readonly<Record<string, string>>;
+
+/**
+ * Sequentially project migration steps over a canonical validated owned schema.
+ * Adding a required non-null column to an existing table rejects with
+ * `MIGRATION`; optional-only and nullable-only additions remain portable.
+ *
+ * @param schema - The initial deployed schema
+ * @param steps - The ordered migration steps
+ * @returns A fresh owned final schema
+ */
+export declare function projectMigrationSchema(schema: readonly TableSchema[], steps: readonly MigrationStep[]): readonly TableSchema[];
+
+/**
+ * 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 `QueryInput` stays portable across backends. When present, `limit` and
+ * `offset` must be finite nonnegative integers. Zero is valid: `limit: 0`
+ * selects an empty page and `offset: 0` skips nothing.
+ */
+export declare interface QueryInput {
+    readonly conditions?: readonly Condition[];
+    readonly order?: readonly Order[];
+    readonly limit?: number;
+    readonly offset?: number;
 }
 
 /**
  * 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
+ * `condition` appends one portable condition and `order` appends one portable
+ * ordering term. `filter` adds a post-fetch JavaScript predicate (applied after
+ * the backend read, before paging). The terminals (`collect` / `find` / `count`
+ * / `aggregate`) 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>;
+    condition(input: Condition): QueryInterface<T>;
+    order(input: Order): QueryInterface<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>;
+    collect(): Promise<readonly T[]>;
+    find(): Promise<T | undefined>;
     count(): Promise<number>;
     /**
      * Lazy per-row evaluation of this query's conditions / filters / offset /
@@ -1288,51 +1273,43 @@ export declare interface QueryInterface<T = Row> {
      * {@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;
+    stream(options?: OperationOptions): AsyncIterable<T>;
+    aggregate(operation: AggregateOperation, column: FieldPath): Promise<number | undefined>;
 }
 
 /** 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 the `objectShape`
+ * The row type a table's {@link ColumnMap} describe — `Infer` of the `objectShape`
  * the database wraps them in.
  *
  * @remarks
  * Contract 0.0.4's non-distributive `Infer` resolves the OPEN case (the broad
- * `Columns` — e.g. when a database is held at its default type) directly:
- * `RowOf<Columns>` and {@link Row} are mutually assignable, so no short-circuit
+ * `ColumnMap` — e.g. when a database is held at its default type) directly:
+ * `RowOf<ColumnMap>` and {@link Row} are mutually assignable, so no short-circuit
  * to `Row` and no `additionalProperties: false` pin are needed — `Infer` no
  * longer trips TS's instantiation-depth guard over the open shape, and the
  * inferred row matches the CLOSED object `objectShape(columns)` builds at
  * runtime (its additional-properties parameter defaults to `false`) for every
  * concrete column map.
  */
-export declare type RowOf<C extends Columns> = Infer<{
+export declare type RowOf<C extends ColumnMap> = Infer<{
     readonly type: 'object';
     readonly properties: C;
 }>;
 
 /**
- * Map a column's {@link ContractShape} to its portable {@link ColumnType} — the
+ * Project one contract shape into a portable column schema.
+ *
+ * @param name - The column name
+ * @param shape - The column contract shape
+ * @returns The portable storage and independent absence/null acceptance
+ */
+export declare function shapeToColumnSchema(name: string, shape: ContractShape): ColumnSchema;
+
+/**
+ * Map a column's {@link ContractShape} to its portable {@link ColumnStorage} — the
  * value a `TableSchema` carries so a native backend can declare a real column.
  *
  * @remarks
@@ -1349,13 +1326,13 @@ export declare type RowOf<C extends Columns> = Infer<{
  *
  * @example
  * ```ts
- * shapeToColumnType(stringShape()) // 'text'
- * shapeToColumnType(integerShape()) // 'integer'
- * shapeToColumnType(optionalShape(integerShape())) // 'integer'
- * shapeToColumnType(objectShape({ a: stringShape() })) // 'json'
+ * shapeToColumnStorage(stringShape()) // 'text'
+ * shapeToColumnStorage(integerShape()) // 'integer'
+ * shapeToColumnStorage(optionalShape(integerShape())) // 'integer'
+ * shapeToColumnStorage(objectShape({ a: stringShape() })) // 'json'
  * ```
  */
-export declare function shapeToColumnType(shape: ContractShape): ColumnType;
+export declare function shapeToColumnStorage(shape: ContractShape): ColumnStorage;
 
 /**
  * Sort rows by an ordering specification, leaving the input untouched.
@@ -1371,102 +1348,44 @@ export declare function shapeToColumnType(shape: ContractShape): ColumnType;
 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.
+ * The storage operations available only inside a driver's transaction scope.
  *
  * @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`.
+ * A driver owns acquisition, commit or rollback, release, and lifetime. This
+ * capability exposes storage work only: it has no public `commit` / `rollback`,
+ * cannot start a nested transaction, and throws `CONFLICT` after its scope
+ * settles. Optional native read and migration hooks mirror the owning driver;
+ * callers fall back to `scan` when a native read hook is absent.
+ */
+export declare interface StorageInterface {
+    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>;
+    clear(table: string): Promise<void>;
+    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>;
+    migrate?(input: MigrationInput): Promise<void>;
+    metadata?(): Promise<DriverMetadata | undefined>;
+    stamp?(metadata: DriverMetadata): Promise<void>;
+}
+
+/**
+ * One table's portable definition, produced by `export` — the unit of schema /
+ * migration exchange across environments.
  *
  * @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>>;
+ * `schema` is the JSON Schema (universally portable, serializable); `columns` is
+ * the source column map, which re-imports losslessly via `import` within a
+ * TypeScript environment. `primary` is the primary-key column.
+ */
+export declare interface TableDefinition {
+    readonly primary: string;
+    readonly columns: ColumnMap;
+    readonly schema: JSONSchema;
 }
 
 /**
@@ -1474,9 +1393,6 @@ export declare class Table<T = Row> implements TableInterface<T> {
  * 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
@@ -1490,48 +1406,22 @@ export declare class Table<T = Row> implements TableInterface<T> {
  * 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> = {
+export declare type TableEventMap = {
     /** A row was written (set / added / updated) — the affected key (no value payload). */
-    readonly write: readonly [key: TKey];
+    readonly write: readonly [key: Key];
     /** A row was removed — the affected key. */
-    readonly remove: readonly [key: TKey];
+    readonly remove: readonly [key: Key];
     /** 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`
+ * row whose primary is `undefined` receives a generated key. `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`).
@@ -1553,43 +1443,39 @@ export declare interface TableInterface<T = Row> {
     has(key: Key): Promise<boolean>;
     has(keys: readonly Key[]): Promise<readonly boolean[]>;
     keys(): Promise<readonly Key[]>;
-    records(criteria?: Criteria, options?: ReadOptions): Promise<readonly T[]>;
+    records(input?: QueryInput, options?: OperationOptions): Promise<readonly T[]>;
     /**
-     * Count rows matching `criteria`'s conditions.
+     * Count contract-valid rows matching `input`'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.
+     * Paging is ignored. Like `records()` / `scan()`, `count()` narrows every
+     * candidate through the table contract, so a non-conforming stored row does
+     * not consume the count.
      */
-    count(criteria?: Criteria, options?: ReadOptions): Promise<number>;
+    count(input?: QueryInput, options?: OperationOptions): Promise<number>;
     /**
-     * Compute an aggregate over `column` across rows matching `criteria`'s
+     * Compute an aggregate over `column` across rows matching `input`'s
      * conditions.
      *
      * @remarks
-     * Like {@link TableInterface.count}, `aggregate` operates on STORED rows
-     * WITHOUT the contract guard that `records()` / `scan()` apply — a
+     * Unlike {@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>;
+    aggregate(operation: AggregateOperation, column: FieldPath, input?: QueryInput, options?: OperationOptions): Promise<number | undefined>;
     /**
      * Lazy filtered iteration over the table's rows.
      *
      * @remarks
-     * `criteria`'s `conditions` / `offset` / `limit` are honored lazily as rows
+     * `input`'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>;
+    scan(input?: QueryInput, options?: OperationOptions): AsyncIterable<T>;
     /**
      * Upsert one or more rows.
      *
@@ -1597,7 +1483,7 @@ export declare interface TableInterface<T = Row> {
      * @param options - Optional abort signal
      * @returns The row's key
      */
-    set(row: T, options?: ReadOptions): Promise<Key>;
+    set(row: T, options?: OperationOptions): Promise<Key>;
     /**
      * Upsert one or more rows.
      *
@@ -1610,7 +1496,7 @@ export declare interface TableInterface<T = Row> {
      * 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[]>;
+    set(rows: readonly T[], options?: OperationOptions): Promise<readonly Key[]>;
     /**
      * Insert one or more rows, throwing `CONFLICT` on a duplicate key.
      *
@@ -1618,7 +1504,7 @@ export declare interface TableInterface<T = Row> {
      * @param options - Optional abort signal
      * @returns The row's key
      */
-    add(row: T, options?: ReadOptions): Promise<Key>;
+    add(row: T, options?: OperationOptions): Promise<Key>;
     /**
      * Insert one or more rows, throwing `CONFLICT` on a duplicate key.
      *
@@ -1631,7 +1517,7 @@ export declare interface TableInterface<T = Row> {
      * 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[]>;
+    add(rows: readonly T[], options?: OperationOptions): Promise<readonly Key[]>;
     /**
      * Apply a partial change to one or more rows.
      *
@@ -1640,7 +1526,7 @@ export declare interface TableInterface<T = Row> {
      * @param options - Optional abort signal
      * @returns `true` when the row existed and was updated
      */
-    update(key: Key, changes: Partial<T>, options?: ReadOptions): Promise<boolean>;
+    update(key: Key, changes: Partial<T>, options?: OperationOptions): Promise<boolean>;
     /**
      * Apply a partial change to one or more rows.
      *
@@ -1654,7 +1540,7 @@ export declare interface TableInterface<T = Row> {
      * 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[]>;
+    update(keys: readonly Key[], changes: Partial<T>, options?: OperationOptions): Promise<readonly boolean[]>;
     /**
      * Delete one or more rows.
      *
@@ -1662,7 +1548,7 @@ export declare interface TableInterface<T = Row> {
      * @param options - Optional abort signal
      * @returns `true` when the row existed and was removed
      */
-    remove(key: Key, options?: ReadOptions): Promise<boolean>;
+    remove(key: Key, options?: OperationOptions): Promise<boolean>;
     /**
      * Delete one or more rows.
      *
@@ -1675,20 +1561,20 @@ export declare interface TableInterface<T = Row> {
      * 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[]>;
+    remove(keys: readonly Key[], options?: OperationOptions): Promise<readonly boolean[]>;
     clear(): Promise<void>;
     query(): QueryInterface<T>;
     cursor(): Promise<CursorInterface<T>>;
 }
 
 /**
- * Per-table primary-key column overrides — `{ [table]: column }`.
+ * A database's table schema — a map of table name to its {@link ColumnMap}.
  *
  * @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.
+ * Each table's row type is `Infer` of its columns (see {@link RowOf}); primary-key
+ * columns are named separately via {@link PrimaryMap}.
  */
-export declare type TableKeys = Readonly<Record<string, string>>;
+export declare type TableMap = Readonly<Record<string, ColumnMap>>;
 
 /**
  * A backend-agnostic description of one table — what `open` hands each driver so a
@@ -1696,7 +1582,7 @@ export declare type TableKeys = Readonly<Record<string, string>>;
  *
  * @remarks
  * Derived by the database from its `tables` contract shapes ({@link ColumnSchema}
- * per column, via `shapeToColumnType`), its `keys` (`primary`), and its `indexes` option
+ * per column, via `shapeToColumnStorage`), its `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`.
  */
@@ -1708,64 +1594,17 @@ export declare interface TableSchema {
 }
 
 /**
- * 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.
+ * Validate the paging fields of a portable query.
  *
  * @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.
+ * A present `limit` or `offset` must be a finite nonnegative integer; zero is
+ * valid. Validation is deterministic (`limit` before `offset`). Non-finite
+ * values are rendered as strings in error context so JSON serialization cannot
+ * collapse `NaN` or infinity to `null`.
  *
- * 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;
+ * @param input - The portable query whose paging fields to validate
+ * @throws {@link DatabaseError} `VALIDATION` when a paging field is invalid
+     */
+ export declare function validatePage(input?: QueryInput): void;
 
-export { }
+ export { }