@orkestrel/database 0.0.12 → 0.0.14

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

@@ -1,17 +1,48 @@
-import { ContractInterface } from '@orkestrel/contract';
-import { ContractShape } from '@orkestrel/contract';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FieldPath } from '@orkestrel/contract';
-import { Infer } from '@orkestrel/contract';
-import { JSONSchema } from '@orkestrel/contract';
-
-/** An aggregate computed over a numeric column. */
+import type { ContractInterface } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { FieldPath } from '@orkestrel/contract';
+import type { Infer } from '@orkestrel/contract';
+import type { JSONSchema } from '@orkestrel/contract';
+
+/**
+ * Represents the admission boundary a scoped operation enters before it runs.
+ *
+ * @remarks
+ * The one contract the root database context and a transaction scope both
+ * expose: `accepting` reports whether the boundary still admits work, and
+ * `track` enters an operation into the boundary's ledger so whoever stops the
+ * boundary can contain everything already accepted. A streamed read enters each
+ * continuation independently through the same pair, so an idle iterator never
+ * pins the boundary open.
+ *
+ * @example
+ * ```ts
+ * import type { AdmissionInterface } from '@orkestrel/database'
+ *
+ * const boundary: AdmissionInterface = {
+ * 	accepting: true,
+ * 	track: (operation) => operation(),
+ * }
+ * await boundary.track(async () => 42) // 42
+ * ```
+ */
+export declare interface AdmissionInterface {
+    readonly accepting: boolean;
+    /**
+     * Enters one operation into the boundary's ledger so whoever stops the boundary
+     * contains everything already accepted.
+     */
+    track<R>(operation: () => Promise<R>): Promise<R>;
+}
+
+/** Names an aggregate computed over a numeric column. */
 export declare type AggregateOperation = 'count' | 'sum' | 'average' | 'minimum' | 'maximum';
 
 /**
- * Apply a {@link QueryInput} to rows — filter, then sort, then page.
+ * Applies a {@link QueryInput} to rows — filter, then sort, then page.
  *
  * @remarks
  * The whole portable read pipeline in one place: conditions filter, `order`
@@ -26,12 +57,12 @@ export declare type AggregateOperation = 'count' | 'sum' | 'average' | 'minimum'
 export declare function applyQuery(rows: readonly Row[], input?: QueryInput): readonly Row[];
 
 /**
- * Run the FULL driver-conformance battery and collect every violation — the
+ * Runs the full driver-conformance battery and collects every violation — the
  * audit entry point for a driver author who wants a complete report rather
  * than a single fail-fast throw.
  *
  * @remarks
- * Drains {@link driverFindings} to completion: every phase runs regardless
+ * Drains {@link scanDriver} to completion: every phase runs regardless
  * of earlier violations, so a driver breaking two independent invariants
  * reports both. An empty array means the driver is fully conformant.
  *
@@ -49,7 +80,7 @@ export declare function applyQuery(rows: readonly Row[], input?: QueryInput): re
 export declare function auditDriver(factory: () => DriverInterface): Promise<readonly ConformanceFinding[]>;
 
 /**
- * Return a fresh row whose primary column is authoritatively bound to its storage key.
+ * Returns a fresh row whose primary column is authoritatively bound to its storage key.
  *
  * @param row - The caller row
  * @param primary - The primary column
@@ -59,7 +90,7 @@ export declare function auditDriver(factory: () => DriverInterface): Promise<rea
 export declare function bindRowKey(row: Row, primary: string, key: Key): Row;
 
 /**
- * Throw when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
+ * Throws when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
  * abort gate checked at operation boundaries and between streamed rows.
  *
  * @remarks
@@ -86,7 +117,12 @@ export declare function bindRowKey(row: Row, primary: string, key: Key): Row;
 export declare function checkAbort(signal: AbortSignal | undefined): void;
 
 /**
- * Clone unknown driver metadata into a distinct deeply frozen snapshot.
+ * Clones unknown driver metadata into a distinct deeply frozen snapshot.
+ *
+ * @remarks
+ * The clone is validated as {@link DriverMetadata} before it is returned, so a
+ * malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+ * `context.path === 'metadata'` rather than surfacing a raw Contract or caller error.
  *
  * @param value - Unknown metadata
  * @returns Owned driver metadata
@@ -94,7 +130,12 @@ export declare function checkAbort(signal: AbortSignal | undefined): void;
 export declare function cloneDriverMetadata(value: unknown): DriverMetadata;
 
 /**
- * Clone unknown driver schema into a distinct deeply frozen snapshot.
+ * Clones unknown driver schema into a distinct deeply frozen snapshot.
+ *
+ * @remarks
+ * The clone is validated as a table-schema collection before it is returned, so a
+ * malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+ * `context.path === 'schema'` rather than surfacing a raw Contract or caller error.
  *
  * @param value - Unknown table schema collection
  * @returns Owned driver schema
@@ -102,7 +143,12 @@ export declare function cloneDriverMetadata(value: unknown): DriverMetadata;
 export declare function cloneDriverSchema(value: unknown): readonly TableSchema[];
 
 /**
- * Clone unknown migration input into a distinct deeply frozen snapshot.
+ * Clones unknown migration input into a distinct deeply frozen snapshot.
+ *
+ * @remarks
+ * The clone is validated as a {@link MigrationInput} before it is returned, so a
+ * malformed or hostile value throws a `VALIDATION` {@link DatabaseError} at
+ * `context.path === 'migration'` rather than surfacing a raw Contract or caller error.
  *
  * @param value - Unknown migration input
  * @returns Owned migration input
@@ -110,7 +156,7 @@ export declare function cloneDriverSchema(value: unknown): readonly TableSchema[
 export declare function cloneMigrationInput(value: unknown): MigrationInput;
 
 /**
- * One table's columns — a map of column name to its value {@link ContractShape}.
+ * Represents one table's columns — a map of column name to its value {@link ContractShape}.
  *
  * @remarks
  * This is exactly the property map an `objectShape` takes. A table row is always
@@ -122,7 +168,7 @@ export declare function cloneMigrationInput(value: unknown): MigrationInput;
 export declare type ColumnMap = Readonly<Record<string, ContractShape>>;
 
 /**
- * One column of a {@link TableSchema} — its name, portable {@link ColumnStorage}, and
+ * Represents one column of a {@link TableSchema} — its name, portable {@link ColumnStorage}, and
  * whether it independently accepts absence (`optional`) and explicit `null`
  * (`nullable`).
  */
@@ -134,7 +180,7 @@ export declare interface ColumnSchema {
 }
 
 /**
- * A portable storage type for a column — the backend maps it to its native type
+ * Names 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 `shapeToColumnStorage`; `json` covers object/array/union/raw values a backend stores
  * as JSON text and can `json_extract` for nested-field queries.
@@ -142,8 +188,8 @@ export declare interface ColumnSchema {
 export declare type ColumnStorage = 'text' | 'integer' | 'real' | 'boolean' | 'json' | 'blob';
 
 /**
- * A total ordering over arbitrary values — the comparator behind sorting and the
- * range operators.
+ * Compares two arbitrary values under one total order — the comparator behind
+ * sorting and the range operators.
  *
  * @remarks
  * Values of different types order by a fixed type rank (`undefined` < `null` <
@@ -158,7 +204,7 @@ export declare type ColumnStorage = 'text' | 'integer' | 'real' | 'boolean' | 'j
 export declare function compareValues(left: unknown, right: unknown): number;
 
 /**
- * Compute an aggregate over a column across rows.
+ * Computes an aggregate over a column across rows.
  *
  * @remarks
  * `count` returns the row count. The numeric aggregates coerce each cell with
@@ -174,14 +220,14 @@ export declare function compareValues(left: unknown, right: unknown): number;
 export declare function computeAggregate(rows: readonly unknown[], operation: AggregateOperation, column: FieldPath): number | undefined;
 
 /**
- * One compiled WHERE condition.
+ * Represents one compiled WHERE condition.
  *
  * @remarks
  * `values` carries the operands the operator needs — none for `absent` /
  * `present`, one for most, two for `between`, a list for `any` / `none`.
  * `connector` folds this condition into the accumulated result left-to-right;
  * the first condition's connector seeds the fold and is otherwise ignored.
- * `column` is a {@link FieldPath}: a single string is ONE column (never split on
+ * `column` is a {@link FieldPath}: a single string is one column (never split on
  * `.`), an array descends into a nested (object/`json`) value.
  */
 export declare interface Condition {
@@ -191,11 +237,11 @@ export declare interface Condition {
     readonly connector: ConditionConnector;
 }
 
-/** How a {@link Condition} joins to the running result of the conditions before it. */
+/** Names 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.
+ * Represents a WHERE operator — the comparison a single {@link Condition} applies.
  *
  * @remarks
  * Each maps to a SQL operator and an IndexedDB read strategy (a key range where
@@ -205,12 +251,46 @@ export declare type ConditionConnector = 'and' | 'or';
 export declare type ConditionOperator = 'equals' | 'not' | 'above' | 'below' | 'from' | 'to' | 'between' | 'like' | 'glob' | 'starts' | 'ends' | 'any' | 'none' | 'absent' | 'present';
 
 /**
- * One violated invariant from the driver-conformance battery.
+ * Describes the `posts` table the driver-conformance battery opens — keyed by a non-`id`
+ * `slug` primary column.
+ *
+ * @remarks
+ * Pairs with {@link CONFORMANCE_USERS_SCHEMA} so one battery exercises both
+ * primary-key shapes: the default `id` and an explicit override.
+ */
+export declare const CONFORMANCE_POSTS_SCHEMA: TableSchema;
+
+/**
+ * Holds the fixed `users` and `posts` schema every driver-conformance phase opens.
+ *
+ * @remarks
+ * Each phase mints a fresh driver and opens this exact schema, so a finding
+ * names a violated invariant rather than a setup difference between phases. The
+ * array and each schema in it are frozen, so a consumer holding it cannot change
+ * what a later phase opens.
+ */
+export declare const CONFORMANCE_SCHEMA: readonly TableSchema[];
+
+/**
+ * Describes the `users` table the driver-conformance battery opens — keyed by the default
+ * `id` primary column.
+ *
+ * @remarks
+ * `age` is optional and `meta` is a declared `json` column, so the battery's
+ * nested-round-trip phase is fair to a typed-column backend: a SQL driver
+ * persists only declared columns, while a schemaless backend ignores the
+ * declarations entirely.
+ */
+export declare const CONFORMANCE_USERS_SCHEMA: TableSchema;
+
+/**
+ * Represents one violated invariant from the driver-conformance battery.
  *
  * @remarks
  * Mirrors the payload shape of a `DatabaseError` `CONFORMANCE` `context` —
  * `check` names the invariant, `message` describes the violation, and
- * `context` carries the offending table / key / value that failed it.
+ * `context` carries the offending table / key / value that failed it. Yielded one at a
+ * time by {@link scanDriver} and collected whole by {@link auditDriver}.
  */
 export declare interface ConformanceFinding {
     readonly check: string;
@@ -219,17 +299,19 @@ export declare interface ConformanceFinding {
 }
 
 /**
- * Run the driver-conformance battery, throwing on the first violated
+ * Runs the driver-conformance battery, throwing on the first violated
  * invariant — the fail-fast entry point most callers (test setup, CI smoke
  * checks) want.
  *
  * @remarks
- * A thin driver over {@link driverFindings}: because that generator is
- * lazy, consuming only its first yielded value means every LATER phase
- * never runs — true fail-fast, not merely "report only the first". The
+ * Consumes only the first value {@link scanDriver} yields: because that
+ * generator is lazy, every later phase never runs — true fail-fast, not
+ * merely "report only the first". The
  * thrown error is byte-compatible with the historical shape: a
  * `CONFORMANCE` {@link DatabaseError} whose `message` is the finding's
- * `message` and whose `context` is `{ check, ...finding.context }`.
+ * `message` and whose `context` is `{ check, ...finding.context }`. The battery
+ * takes a driver factory and reports through a throw, so it binds no test
+ * framework and runs from any runner.
  *
  * @param factory - Mints a fresh, unopened driver instance (called once per phase)
  * @returns Nothing — resolves once every phase has passed
@@ -245,40 +327,49 @@ export declare interface ConformanceFinding {
 export declare function conformDriver(factory: () => DriverInterface): Promise<void>;
 
 /**
- * Create a database over a driver and a declared `tables` schema.
+ * Creates a database over a driver and a declared `tables` schema.
  *
  * @remarks
  * `tables` maps each name to its columns (a `column → shape` map); the database
  * wraps each in an `objectShape`, so you never write `objectShape` at the table
  * level. The `const` type parameter captures the literal names and columns, so
  * `db.table('users')` is checked against the schema and typed by `Infer` of its
- * columns — no annotations. Name a non-`id` primary-key column per table via the
- * optional `primary` and `indexes` maps.
+ * columns — no annotations. Name a non-`id` primary-key column per table through
+ * the optional `primary` and `indexes` maps.
  *
  * @param options - The driver, `tables`, and optional `primary`, `indexes`,
  *   `name`, `generator`, `version`, and emitter hooks
  * @returns A typed {@link DatabaseInterface}
  *
- * @example
+ * @example Create a database
  * ```ts
  * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
  * import { integerShape, stringShape } from '@orkestrel/contract'
  *
  * const db = createDatabase({
- * 	driver: createMemoryDriver(),
+ * 	driver: createMemoryDriver(), // any DriverInterface — a persistent backend swaps in, same API
  * 	tables: {
- * 		users: { id: stringShape(), age: integerShape() },
+ * 		users: { id: stringShape(), name: stringShape(), age: integerShape() },
  * 		posts: { slug: stringShape(), title: stringShape() },
  * 	},
- * 	primary: { posts: 'slug' },
+ * 	primary: { posts: 'slug' }, // non-`id` primary-key columns, per table
  * })
- * await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
+ *
+ * const users = db.table('users') // hold the handle; TableInterface<{ id; name; age }>
+ *
+ * await users.set({ id: 'u1', name: 'Ada', age: 36 }) // coerced + validated through the contract
+ * await users.get('u1') // typed { id; name; age } | undefined — narrowed, never `as`
+ * await users
+ * 	.query()
+ * 	.condition({ column: 'age', operator: 'from', values: [18], connector: 'and' })
+ * 	.order({ column: 'age', direction: 'descending' })
+ * 	.collect() // typed rows
  * ```
  */
 export declare function createDatabase<const T extends TableMap>(options: DatabaseOptions<T>): DatabaseInterface<T>;
 
 /**
- * Create the in-memory reference {@link DriverInterface}.
+ * Creates the in-memory reference {@link DriverInterface}.
  *
  * @remarks
  * Backed by nested maps with no I/O — the same driver runs in a browser or on a
@@ -289,7 +380,7 @@ export declare function createDatabase<const T extends TableMap>(options: Databa
 export declare function createMemoryDriver(): DriverInterface;
 
 /**
- * A forward row cursor for bulk in-place mutation.
+ * Walks a table's rows forward for bulk in-place mutation.
  *
  * @remarks
  * Iterates a snapshot of the table's keys taken at creation; `update` and
@@ -304,20 +395,36 @@ export declare interface CursorInterface<T = Row> {
     readonly value: T | undefined;
     readonly index: number;
     readonly done: boolean;
+    /**
+     * Advances to the next present row.
+     */
     next(): Promise<void>;
+    /**
+     * Merges changes into the row at the current position.
+     */
     update(changes: Partial<T>): Promise<void>;
+    /**
+     * Deletes the row at the current position.
+     */
     remove(): Promise<void>;
+    /**
+     * Closes the cursor terminally, so every later operation is a no-op.
+     */
     close(): void;
 }
 
 /**
- * A typed database view over one shared internal lifecycle and storage context.
+ * Exposes a typed view over one shared internal lifecycle and storage context.
  *
  * @remarks
  * 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.
+ *
+ * The view owns the driver and its declared `tables`, connects that driver lazily on
+ * first use, `import`s further tables and `export`s their portable definitions, and
+ * runs `transaction` scopes over the shared context.
  */
 export declare class Database<T extends TableMap = TableMap> implements DatabaseInterface<T> {
     #private;
@@ -335,7 +442,7 @@ export declare class Database<T extends TableMap = TableMap> implements Database
 }
 
 /**
- * An error thrown by the database layer.
+ * Represents an error thrown by the database layer.
  *
  * @remarks
  * Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
@@ -346,7 +453,7 @@ export declare class Database<T extends TableMap = TableMap> implements Database
  * `context`), an inapplicable {@link Migration} plan (`MIGRATION`), a
  * driver that violates a {@link DriverInterface} invariant, thrown by the
  * `conformDriver` helper (`CONFORMANCE`), and an unexpected infrastructure
- * fault surfaced by a driver seam — e.g. a filesystem failure while
+ * fault surfaced by a driver seam — for example a filesystem failure while
  * persisting (`DRIVER`) — as opposed to expected domain conditions, which
  * keep their specific codes.
  */
@@ -356,48 +463,48 @@ export declare class DatabaseError extends Error {
     constructor(code: DatabaseErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
 }
 
-/** A machine-readable {@link DatabaseError} code. */
+/** Names a machine-readable {@link DatabaseError} code. */
 export declare type DatabaseErrorCode = 'CLOSED' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION' | 'ABORTED' | 'MIGRATION' | 'CONFORMANCE' | 'DRIVER';
 
 /**
- * The push observation surface of a {@link DatabaseInterface} (AGENTS §13) — the
+ * Describes the push observation surface of a {@link DatabaseInterface} — the
  * connection + transaction lifecycle a fire-and-forget observer (logging, metrics,
  * tracing, cache invalidation) subscribes to.
  *
  * @remarks
  * Pure signals carrying no row data — these are the database-level (not per-row)
  * moments, so a non-generic map stays lean (per-row writes are {@link TableEventMap}).
- * Listener isolation is the emitter's (AGENTS §13): every event is emitted directly and a
- * listener throw is routed to the emitter's OWN `error` handler (the `error` option), never
+ * Listener isolation is the emitter's: every event is emitted directly and a
+ * listener throw is routed to the emitter's own `error` handler (the `error` option), never
  * onto this domain map and never into the snapshot / commit / rollback flow — so a buggy
- * observer can never reorder, throw into, or corrupt a transaction. Every emit sits AFTER the
+ * 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 the
- * rollback operation completes (it OBSERVES the propagated scope error; that exact reason
+ * 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(...)`.
+ * `rollback` event. Subscribe through `database.emitter.on(...)`.
  *
- * Declared as a `type` alias (not `interface extends EventMap`, §4.5 — `EventMap` is a
+ * Declared as a `type` alias (not `interface extends EventMap` — `EventMap` is a
  * `type` kind): a type-literal satisfies the `EventMap` constraint
  * (`Record<string, readonly unknown[]>`) structurally, whereas an interface lacks the
  * required index signature.
  */
 export declare type DatabaseEventMap = {
-    /** The driver connected (`open`, or the lazy first-use connect completed). */
+    /** Signals that the driver connected (`open`, or the lazy first-use connect completed). */
     readonly open: readonly [];
-    /** The database was closed (the driver released). */
+    /** Signals that the database was closed (the driver released). */
     readonly close: readonly [];
-    /** A transaction scope began after its native boundary or fallback snapshot was acquired. */
+    /** Signals that a transaction scope began after its native boundary or fallback snapshot was acquired. */
     readonly transaction: readonly [];
-    /** A transaction scope completed successfully (no rollback). */
+    /** Signals that a transaction scope completed successfully (no rollback). */
     readonly commit: readonly [];
-    /** A transaction scope failed and rollback completed — the exact propagated scope error. */
+    /** Signals that 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. */
+    /** Signals that a {@link Migration} plan was applied through `migrate` — the applied plan. */
     readonly migrate: readonly [migration: Migration];
 };
 
 /**
- * A database — the ergonomic entry point that owns the driver and its tables.
+ * Represents a database — the ergonomic entry point that owns the driver and its tables.
  *
  * @remarks
  * A database is a typed view over a set of tables on one driver. Tables are
@@ -415,19 +522,43 @@ export declare interface DatabaseInterface<T extends TableMap = TableMap> {
     readonly emitter: EmitterInterface<DatabaseEventMap>;
     readonly name: string;
     readonly status: DatabaseStatus;
+    /**
+     * Returns the typed handle for a declared table.
+     */
     table<K extends keyof T & string>(name: K): TableInterface<RowOf<T[K]>>;
+    /**
+     * Defines a further shape map of tables as a typed view over the same driver and storage.
+     */
     import<U extends TableMap>(tables: U, primary?: PrimaryMap): DatabaseInterface<U>;
+    /**
+     * Returns one portable {@link TableDefinition} per declared table.
+     */
     export(): Readonly<Record<string, TableDefinition>>;
+    /**
+     * Connects the driver eagerly, ahead of the lazy connect on first use.
+     */
     open(): Promise<void>;
+    /**
+     * Closes the database and releases its driver.
+     */
     close(): Promise<void>;
+    /**
+     * Runs a scope over a {@link DatabaseStorageInterface}, committing when the callback
+     * fulfills and rolling back when it rejects.
+     *
+     * @remarks
+     * A native driver transaction carries the scope where the driver offers one;
+     * otherwise the universal whole-store snapshot floor does. `options.signal` is
+     * checked once, at entry.
+     */
     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
-     * resulting plan through the driver's optional `migrate` hook, and return
+     * Diffs a caller-supplied deployed schema against this database's declared
+     * schema (its `tables`, as configured) through `planMigration`, applies the
+     * resulting plan through the driver's optional `migrate` hook, and returns
      * the applied plan.
      *
-     * @param deployed - The schema currently deployed, as {@link TableSchema}s
+     * @param deployed - The deployed schema, as {@link TableSchema}s
      * @param options - Optional abort signal, checked at entry
      * @returns The applied {@link Migration} plan
      *
@@ -459,8 +590,8 @@ export declare interface DatabaseInterface<T extends TableMap = TableMap> {
  * `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);
+ * the database; `on` wires initial {@link DatabaseEventMap} listeners; `error`
+ * is the emitter's listener-error handler (a listener throw routes here);
  * `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.
@@ -468,7 +599,7 @@ export declare interface DatabaseInterface<T extends TableMap = TableMap> {
 export declare interface DatabaseOptions<T extends TableMap = TableMap> {
     readonly on?: EmitterHooks<DatabaseEventMap>;
     /**
-     * The listener-error handler shared by the database and every table emitter.
+     * Holds the listener-error handler shared by the database and every table emitter.
      *
      * @remarks
      * Listener throws from root, imported, and transaction-scoped handles route
@@ -482,31 +613,31 @@ export declare interface DatabaseOptions<T extends TableMap = TableMap> {
     readonly indexes?: IndexMap;
     readonly name?: string;
     /**
-     * The authoritative key-generation override for a keyless write.
+     * Holds 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.
+     * 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.
+     * Holds the declared schema version.
      *
      * @remarks
-     * Only meaningful when the driver implements BOTH {@link DriverInterface.metadata}
+     * 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 DriverMetadata}:
+     * When set and the driver versions, `open()` reconciles against the 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.
+     *   deployed to diff against), so `open()` stamps `{ version, schema }` for
+     *   next time.
      * - **Stored version < `version`** — `planMigration(stored.schema, declared
-     *   schema)` computes the upgrade plan, applied via the driver's optional
+     *   schema)` computes the upgrade plan, applied through the driver's optional
      *   `migrate` hook. If `migrate` is absent and the plan is non-empty,
      *   `open()` throws `DatabaseError` `MIGRATION`. On success, `open()`
      *   `stamp`s the new `{ version, schema }` and emits the `migrate` event.
@@ -524,11 +655,11 @@ export declare interface DatabaseOptions<T extends TableMap = TableMap> {
     readonly version?: number;
 }
 
-/** The lifecycle state of a {@link DatabaseInterface}. */
+/** Names the lifecycle state of a {@link DatabaseInterface}. */
 export declare type DatabaseStatus = 'idle' | 'open' | 'closed';
 
 /**
- * A database view valid only inside one {@link DatabaseInterface.transaction}
+ * Represents a database view valid only inside one {@link DatabaseInterface.transaction}
  * scope.
  *
  * @remarks
@@ -538,11 +669,17 @@ export declare type DatabaseStatus = 'idle' | 'open' | 'closed';
  * after the scope settles.
  */
 export declare interface DatabaseStorageInterface<T extends TableMap = TableMap> {
+    /**
+     * Returns a table bound to the active transaction scope.
+     *
+     * @remarks
+     * The returned table throws `CONFLICT` for work started after the scope settles.
+     */
     table<K extends keyof T & string>(name: K): TableInterface<RowOf<T[K]>>;
 }
 
 /**
- * The primary-key column assumed when {@link PrimaryMap} does not name one.
+ * Supplies the primary-key column, `'id'`, assumed when {@link PrimaryMap} does not name one.
  *
  * @remarks
  * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
@@ -551,93 +688,43 @@ export declare interface DatabaseStorageInterface<T extends TableMap = TableMap>
 export declare const DEFAULT_PRIMARY = "id";
 
 /**
- * Run the driver-conformance battery against a fresh {@link DriverInterface}
- * per phase, yielding one {@link ConformanceFinding} per violated invariant —
- * the shared invariant suite every backend (in-memory, SQLite, IndexedDB)
- * must uphold to be a drop-in {@link DriverInterface}.
+ * Declares the storage primitive every backend implements — the whole of the bridge.
  *
  * @remarks
- * Framework-agnostic: no test-runner or Node imports, only sibling core
- * modules — so it runs equally from a unit test, a smoke script, or a new
- * driver's own README. Opens a fixed two-table schema (`users` keyed by the
- * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
- * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
- * `read` of a missing key returns `undefined`; `write`/`read` round-trip with
- * DEEP copy-in/copy-out isolation (mutating the caller's row — including a
- * NESTED field — after `write`, or a row `read` returns, never perturbs
- * stored state) and upsert-overwrite; 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 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 `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
- * crash mid-phase) is caught and yielded as a finding too, naming the phase
- * as `check` and carrying the caught error in `context.error` — a broken
- * driver can never escape the battery as an unhandled rejection. Within a
- * phase, the FIRST violated assertion yields and the phase stops (matching
- * the historical fail-fast shape at phase granularity); the generator then
- * moves on to the next phase regardless. Because this is a **generator**,
- * consuming only the first yielded value reproduces true fail-fast (later
- * phases never run) — that is exactly what {@link conformDriver} does.
- *
- * @param factory - Mints a fresh, unopened driver instance (called once per phase)
- * @yields One {@link ConformanceFinding} per violated invariant, in phase order
- *
- * @example
- * ```ts
- * import { createMemoryDriver, driverFindings } from '@orkestrel/database'
- *
- * for await (const finding of driverFindings(() => createMemoryDriver())) {
- * 	console.log(finding.check, finding.message)
- * }
- * ```
- */
-export declare function driverFindings(factory: () => DriverInterface): AsyncIterable<ConformanceFinding>;
-
-/**
- * The storage primitive every backend implements — the whole of the bridge.
- *
- * @remarks
- * The REQUIRED surface is deliberately minimal: keyed read / write / 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?` / `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). Metadata has the same ownership
+ * 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` 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?` / `aggregate?` are native overrides the
+ * engine falls back from. The API is async (Promises) because IndexedDB is;
+ * synchronous backends resolve immediately. Lookups that may miss return
+ * `undefined` / `false` rather than throwing. 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
+ * {@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 extends StorageInterface {
+    /**
+     * Readies the tables from a derived {@link TableSchema} list.
+     *
+     * @remarks
+     * A native backend builds real tables and indexes from the derived columns,
+     * types, primary, and index groups; a scan-only backend reads `name` alone.
+     */
     open(schema: readonly TableSchema[]): Promise<void>;
+    /**
+     * Releases the backend.
+     */
     close(): Promise<void>;
     /**
-     * Capture table rows and return a repeatable thunk that restores those rows —
+     * Captures table rows and returns a repeatable thunk that restores those rows —
      * the primitive transactions are built on.
      *
      * @remarks
@@ -648,14 +735,61 @@ export declare interface DriverInterface extends StorageInterface {
      */
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
     /**
-     * Optional native transaction scope. The driver owns acquisition, commit or
-     * rollback, release, and invalidation of the scoped capability.
+     * Opens a native transaction scope — an optional driver hook. The driver owns acquisition,
+     * commit or rollback, release, and invalidation of the scoped capability.
      */
     transaction?<R>(scope: (storage: StorageInterface) => Promise<R>): Promise<R>;
 }
 
 /**
- * Persisted schema metadata a versioning driver owns as an immutable snapshot.
+ * Forms the internal continuation boundary for a root driver async iterator.
+ *
+ * @remarks
+ * A driver transaction can begin while a caller holds an idle root iterator.
+ * Every `next` therefore checks the driver's root-state guard immediately
+ * before and after advancing the source. A failed continuation terminalizes the
+ * iterator, discards any row produced before the post-advance guard failed, and
+ * attempts source cleanup exactly once.
+ *
+ * A driver implementing the published `DriverInterface` extension seam wraps its
+ * own source iterator in one so a root `scan` / `stream` cannot outlive the
+ * driver state it was opened against.
+ *
+ * @typeParam T - The value the wrapped source yields
+ *
+ * @example
+ * ```ts
+ * import type { Row } from '@orkestrel/database'
+ * import { DatabaseError, DriverIterator } from '@orkestrel/database'
+ *
+ * // Inside a driver's `scan`, over its own row source and root-state guard.
+ * declare const rows: AsyncIterator<Row>
+ * declare const transacting: () => boolean
+ * const scan = new DriverIterator(rows, () => {
+ * 	if (transacting()) {
+ * 		throw new DatabaseError('CONFLICT', 'scan: a transaction is active')
+ * 	}
+ * })
+ * for await (const row of scan) row // one row at a time, guarded around each advance
+ * ```
+ */
+export declare class DriverIterator<T> implements AsyncIterableIterator<T> {
+    #private;
+    /**
+     * Wraps one source iterator in the continuation boundary.
+     *
+     * @param source - The driver's own row iterator, advanced once per `next`
+     * @param guard - The root-state check, run immediately before and after each advance; it throws to terminalize the iteration
+     */
+    constructor(source: AsyncIterator<T>, guard: () => void);
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    next(): Promise<IteratorResult<T>>;
+    return(): Promise<IteratorResult<T>>;
+    throw(error?: unknown): Promise<IteratorResult<T>>;
+}
+
+/**
+ * Represents persisted schema metadata a versioning driver owns as an immutable snapshot.
  *
  * @remarks
  * A driver snapshots metadata when it enters through `stamp` or a
@@ -671,15 +805,16 @@ export declare interface DriverMetadata {
 }
 
 /**
- * Structural equality by SameValueZero leaves — the comparator behind conformance
- * checks and any test/fixture that needs "same data", not "same reference".
+ * Compares two values structurally 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
+ * records (through `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
@@ -688,7 +823,7 @@ export declare interface DriverMetadata {
  *
  * @param left - The left value
  * @param right - The right value
- * @returns Whether `left` and `right` are structurally equal
+ * @returns True if `left` and `right` are structurally equal; false otherwise
  *
  * @example
  * ```ts
@@ -700,7 +835,7 @@ export declare interface DriverMetadata {
 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}.
+ * Reads a row's primary key from a column, when it is a usable {@link Key}.
  *
  * @param row - The row to read
  * @param column - The primary-key column name
@@ -709,7 +844,7 @@ export declare function equalsValue(left: unknown, right: unknown): boolean;
 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
+ * Filters rows by a list of conditions — the shared basis for a table's count
  * and aggregate paths (no sort/page, unlike {@link applyQuery}).
  *
  * @remarks
@@ -731,7 +866,29 @@ export declare function extractKey(row: Row, column: string): Key | undefined;
 export declare function filterRows(rows: readonly Row[], conditions: readonly Condition[]): readonly Row[];
 
 /**
- * Per-table secondary indexes — `{ [table]: groups }`, each group one
+ * Reads one flat column's declaration out of a table schema.
+ *
+ * @remarks
+ * The single lookup behind every declared-column question — storage type,
+ * optionality, and nullability all come off the returned {@link ColumnSchema},
+ * so a caller that needs more than one of them reads them from one result. A
+ * nested {@link FieldPath} names no declared column, so resolve the path's head
+ * before calling. A schema that does not declare the column returns `undefined`.
+ *
+ * @param name - The flat column name
+ * @param schema - The table's schema
+ * @returns The column's {@link ColumnSchema}, or `undefined` when the schema does not declare it
+ *
+ * @example
+ * ```ts
+ * findColumn('age', schema)?.storage // 'integer'
+ * findColumn('absent', schema) // undefined
+ * ```
+ */
+export declare function findColumn(name: string, schema: TableSchema): ColumnSchema | undefined;
+
+/**
+ * Holds per-table secondary indexes — `{ [table]: groups }`, each group one
  * (possibly compound) index of column names.
  *
  * @remarks
@@ -742,18 +899,22 @@ export declare function filterRows(rows: readonly Row[], conditions: readonly Co
 export declare type IndexMap = Readonly<Record<string, ReadonlyArray<readonly string[]>>>;
 
 /**
- * Test whether a value is a portable column schema.
+ * Checks whether a value is a portable column schema.
+ *
+ * @remarks
+ * Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+ * contained as a non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is a complete {@link ColumnSchema}
+ * @returns True if `value` is a complete {@link ColumnSchema}; false otherwise
  */
 export declare function isColumnSchema(value: unknown): value is ColumnSchema;
 
 /**
- * Narrow an unknown caught value to a {@link DatabaseError}.
+ * Narrows an unknown caught value to a {@link DatabaseError}.
  *
  * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is a {@link DatabaseError}
+ * @returns True if `value` is a {@link DatabaseError}; false otherwise
  *
  * @example
  * ```ts
@@ -767,63 +928,89 @@ export declare function isColumnSchema(value: unknown): value is ColumnSchema;
 export declare function isDatabaseError(value: unknown): value is DatabaseError;
 
 /**
- * Test whether a value is persisted driver metadata.
+ * Checks whether a value is persisted driver metadata.
+ *
+ * @remarks
+ * The boundary check a versioning driver's `metadata()` narrows a stored or
+ * deserialized record through, so no call site needs an assertion. Total over any
+ * input: a hostile getter, a revoked proxy, or a cyclic value is contained as a
+ * non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is complete {@link DriverMetadata}
+ * @returns True if `value` is complete {@link DriverMetadata}; false otherwise
  */
 export declare function isDriverMetadata(value: unknown): value is DriverMetadata;
 
 /**
- * Test whether a value is a complete portable driver schema.
+ * Checks whether a value is a complete portable driver schema.
+ *
+ * @remarks
+ * Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+ * contained as a non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is a table-schema collection with unique table names
+ * @returns True if `value` is a table-schema collection with unique table names; false otherwise
  */
 export declare function isDriverSchema(value: unknown): value is readonly TableSchema[];
 
 /**
- * Test whether a value is a usable database key.
+ * Checks whether a value is a usable database key.
  *
  * @param value - The value to test
- * @returns Whether `value` is a string or finite number
+ * @returns True if `value` is a string or a finite number; false otherwise
  */
 export declare function isKey(value: unknown): value is Key;
 
 /**
- * Test whether a value is an ordered migration plan.
+ * Checks whether a value is an ordered migration plan.
+ *
+ * @remarks
+ * Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+ * contained as a non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is a complete {@link Migration}
+ * @returns True if `value` is a complete {@link Migration}; false otherwise
  */
 export declare function isMigration(value: unknown): value is Migration;
 
 /**
- * Test whether a value is one atomic migration request.
+ * Checks whether a value is one atomic migration request.
+ *
+ * @remarks
+ * Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+ * contained as a non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is a complete {@link MigrationInput}
+ * @returns True if `value` is a complete {@link MigrationInput}; false otherwise
  */
 export declare function isMigrationInput(value: unknown): value is MigrationInput;
 
 /**
- * Test whether a value is one ordered migration step.
+ * Checks whether a value is one ordered migration step.
+ *
+ * @remarks
+ * Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+ * contained as a non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is a complete {@link MigrationStep}
+ * @returns True if `value` is a complete {@link MigrationStep}; false otherwise
  */
 export declare function isMigrationStep(value: unknown): value is MigrationStep;
 
 /**
- * Test whether a value is a portable table schema.
+ * Checks whether a value is a portable table schema.
+ *
+ * @remarks
+ * Total over any input: a hostile getter, a revoked proxy, or a cyclic value is
+ * contained as a non-match rather than a throw.
  *
  * @param value - The value to test
- * @returns Whether `value` is a complete {@link TableSchema}
+ * @returns True if `value` is a complete {@link TableSchema}; false otherwise
  */
 export declare function isTableSchema(value: unknown): value is TableSchema;
 
 /**
- * A primary key — the value identifying a row within its table.
+ * Represents a primary key — the value identifying a row within its table.
  *
  * @remarks
  * `string | number` is the intersection of what IndexedDB key ranges and SQL
@@ -833,7 +1020,7 @@ export declare function isTableSchema(value: unknown): value is TableSchema;
 export declare type Key = string | number;
 
 /**
- * A key-generating function.
+ * Represents a key-generating function.
  *
  * @remarks
  * Supplied through {@link DatabaseOptions.generator} as an authoritative
@@ -844,56 +1031,75 @@ export declare type Key = string | number;
 export declare type KeyFunction = () => Key;
 
 /**
- * Evaluate one {@link Condition} against a row — the per-operator predicate.
+ * Evaluates one {@link Condition} against a row — the per-operator predicate.
  *
  * @remarks
  * Reads the condition's column — a `FieldPath`, resolved with `resolveField` (a
  * string is one column; an array descends a nested value) — and applies the
  * operator. Range operators (`above` / `below` / `from` / `to` / `between`) use
  * {@link compareValues}, the total order; the equality family (`equals` / `not`
- * / `any` / `none`) uses {@link equalsValue} — 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: `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
- * type mismatch is simply a non-match.
+ * type mismatch is a non-match.
  *
  * @param row - The row to test
  * @param condition - The condition to apply
- * @returns Whether the row satisfies the condition
+ * @returns True if the row satisfies the condition; false otherwise
  */
 export declare function matchesCondition(row: Row, condition: Condition): boolean;
 
 /**
- * Match a query against a value as a case-insensitive ordered subsequence.
+ * Matches a value against a `GLOB` pattern, preserving case.
  *
  * @remarks
- * Every query character must appear in order in the value, but the characters
- * do not need to be contiguous. Query characters are literal, including
- * whitespace. Matching applies JavaScript `toLowerCase()` to both inputs
- * without locale-specific folding or Unicode normalization. An empty query
- * matches every value.
+ * `*` matches any run of characters (including none) and `?` matches exactly one
+ * character; every other pattern character matches itself literally, so a
+ * character class such as `[a-z]` is not interpreted. Runs on
+ * {@link matchesWildcardPattern}, so the match is linear in the value length and
+ * the pattern is capped at {@link MAX_PATTERN_LENGTH}.
  *
- * @param value - The text searched for the query's characters
- * @param query - The characters that must all appear in order
- * @returns Whether the case-folded query is a subsequence of the case-folded value
+ * @param value - The value to test
+ * @param pattern - The `GLOB` pattern
+ * @returns True if `value` matches `pattern` case-sensitively; false otherwise
+ * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
  *
  * @example
  * ```ts
- * matchesFuzzy('Database', 'dbe') // true
- * matchesFuzzy('Database', 'abd') // false
+ * matchesGlobPattern('hello', 'h*o') // true — `*` spans any run
+ * matchesGlobPattern('Hello', 'h*o') // false — `GLOB` is case-sensitive
  * ```
  */
-export declare function matchesFuzzy(value: string, query: string): boolean;
-
 export declare function matchesGlobPattern(value: string, pattern: string): boolean;
 
+/**
+ * Matches a value against a SQL `LIKE` pattern, folding case.
+ *
+ * @remarks
+ * `%` matches any run of characters (including none) and `_` matches exactly one
+ * character; every other pattern character matches itself literally. Runs on
+ * {@link matchesWildcardPattern}, so the match is linear in the value length and
+ * the pattern is capped at {@link MAX_PATTERN_LENGTH}.
+ *
+ * @param value - The value to test
+ * @param pattern - The `LIKE` pattern
+ * @returns True if `value` matches `pattern` under case folding; false otherwise
+ * @throws A `VALIDATION` {@link DatabaseError} when `pattern` exceeds {@link MAX_PATTERN_LENGTH}
+ *
+ * @example
+ * ```ts
+ * matchesLikePattern('Hello', 'h%o') // true — `%` spans any run, and case folds
+ * matchesLikePattern('Hello', 'h_llo') // true — `_` matches exactly one character
+ * ```
+ */
 export declare function matchesLikePattern(value: string, pattern: string): boolean;
 
 /**
- * Fold a row through a list of conditions, joining each by its connector.
+ * Folds a row through a list of conditions, joining each by its connector.
  *
  * @remarks
  * Evaluated left-to-right: the first condition seeds the result, and each later
@@ -903,21 +1109,21 @@ export declare function matchesLikePattern(value: string, pattern: string): bool
  *
  * @param row - The row to test
  * @param conditions - The conditions to fold
- * @returns Whether the row satisfies the combined conditions
+ * @returns True if the row satisfies the combined conditions; false otherwise
  */
 export declare function matchesQuery(row: Row, conditions: readonly Condition[]): boolean;
 
 /**
- * Match a value against a wildcard pattern in LINEAR time — the shared, ReDoS-SAFE
+ * Matches 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:
+ * 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
+ * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it,
+ * while a `LIKE` / `GLOB` pattern is a caller-supplied operand this package cannot
+ * trust. 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),
@@ -925,28 +1131,29 @@ export declare function matchesQuery(row: Row, conditions: readonly Condition[])
  * pattern.
  *
  * The `any` wildcard matches any run (including empty); `single` matches exactly one
- * char; every other pattern char matches itself LITERALLY (a pattern `.` / `(` / `\` is
+ * 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.
+ * 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`
+ * @param fold - Whether to match case-insensitively (`LIKE` folds; `GLOB` does not)
+ * @returns True if `value` matches `pattern`; false otherwise
  * @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.
+ * Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before
+ * rejecting it.
  *
  * @remarks
- * A ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
- * input over the wire, so `matchesLikePattern` / `matchesGlobPattern` run attacker-controlled
- * patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+ * A `LIKE` / `GLOB` pattern is a caller-supplied operand, so
+ * `matchesLikePattern` / `matchesGlobPattern` run patterns this package cannot
+ * trust. The matcher is the linear greedy two-pointer wildcard match — never a
  * backtracking regex (`.*`-segments-separated-by-literals against a long input is the
  * catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
  * pattern). Capping the pattern length bounds that pattern factor, leaving a match
@@ -956,16 +1163,16 @@ export declare function matchesWildcardPattern(value: string, pattern: string, a
 export declare const MAX_PATTERN_LENGTH = 1024;
 
 /**
- * The reference {@link DriverInterface} — nested maps, no I/O.
+ * Implements the reference {@link DriverInterface} — nested maps, no I/O.
  *
  * @remarks
  * The in-between made concrete: it runs identically in a browser or on a server,
  * so it is the storage behind tests, ephemeral caches, and any code that wants
- * the database API without a persistent backend. Rows are DEEP-copied (via
+ * the database API without a persistent backend. Rows are deep-copied (through
  * `structuredClone`) in and out — at `write`, `read`, `scan`, `stream`, and both
  * snapshot capture and restore — so a caller mutating a nested field of an input
  * row, a returned row, or a row mutated in place between snapshot and rollback
- * can never perturb stored state (AGENTS §11); a shallow `{ ...row }` spread
+ * can never perturb stored state; a shallow `{ ...row }` spread
  * 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`
@@ -987,19 +1194,19 @@ export declare class MemoryDriver implements DriverInterface {
     keys(table: string): Promise<readonly Key[]>;
     scan(table: string): AsyncIterable<Row>;
     /**
-     * Natively filtered lazy iteration — the {@link DriverInterface.stream} hook.
+     * Iterates rows lazily with native filtering — the {@link DriverInterface.stream} hook.
      *
      * @remarks
      * Iterates the table's keys in the same key order `scan` and `keys` yield
      * (sorted by {@link compareValues}), testing each row against
-     * `input.conditions` (via {@link matchesQuery}) before counting it
+     * `input.conditions` (through {@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. `input.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.
+     * order, sorted output is `records()`'s job. Rows yield copy-out, and an
+     * unknown table mirrors `scan`'s empty-yield behavior.
      *
      * @param table - The table to stream
      * @param input - The filter / offset / limit to apply lazily
@@ -1014,7 +1221,7 @@ export declare class MemoryDriver implements DriverInterface {
     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.
+     * Captures the current state and returns a thunk that rolls back to it.
      *
      * @remarks
      * Capture owns rows, schema, and one session-local table identity. Replay
@@ -1028,7 +1235,7 @@ export declare class MemoryDriver implements DriverInterface {
      */
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
     /**
-     * Return the persisted {@link DriverMetadata}, or `undefined` when the store has
+     * Returns the persisted {@link DriverMetadata}, or `undefined` when the store has
      * never been stamped.
      *
      * @remarks
@@ -1041,13 +1248,13 @@ export declare class MemoryDriver implements DriverInterface {
      */
     metadata(): Promise<DriverMetadata | undefined>;
     /**
-     * Persist an owned snapshot for a later `metadata()` to return.
+     * Persists an owned snapshot for a later `metadata()` to return.
      *
      * @param metadata - The {@link DriverMetadata} to persist
      */
     stamp(metadata: DriverMetadata): Promise<void>;
     /**
-     * Apply a {@link Migration} plan's steps against the in-memory store.
+     * Applies a {@link Migration} plan's steps against the in-memory store.
      *
      * @remarks
      * Steps apply against an isolated candidate. Rows, schema changes, and
@@ -1059,11 +1266,11 @@ export declare class MemoryDriver implements DriverInterface {
 }
 
 /**
- * Apply one table's {@link MigrationStep}s to its rows — a pure row transform.
+ * Applies one table's {@link MigrationStep}s to its rows — a pure row transform.
  *
  * @remarks
  * `column.remove` drops that field from every row (a fresh copy — inputs are
- * never mutated, AGENTS §11); `column.add` leaves rows as-is (an absent field
+ * never mutated); `column.add` leaves rows as-is (an absent field
  * reads as `undefined`, backfill is application policy). `table.add` /
  * `table.remove` / `index.add` / `index.remove` are no-ops here (they operate
  * on storage shape, not row shape). Steps for tables other than the one
@@ -1083,12 +1290,12 @@ export declare class MemoryDriver implements DriverInterface {
 export declare function migrateRows(rows: readonly Row[], steps: readonly MigrationStep[]): readonly Row[];
 
 /**
- * A schema migration plan — an ordered set of {@link MigrationStep}s moving a
+ * Represents a schema migration plan — an ordered set of {@link MigrationStep}s moving a
  * database from one schema version to another.
  *
  * @remarks
  * `from` / `to` are the source and target schema versions; `steps` runs in
- * order. Applied natively via {@link DriverInterface.migrate} when a driver
+ * order. Applied natively through {@link DriverInterface.migrate} when a driver
  * implements it.
  */
 export declare interface Migration {
@@ -1098,7 +1305,7 @@ export declare interface Migration {
 }
 
 /**
- * One atomic migration request.
+ * Represents one atomic migration request.
  *
  * @remarks
  * `plan` carries the schema changes. `metadata`, when present, is the snapshot that
@@ -1111,11 +1318,11 @@ export declare interface MigrationInput {
 }
 
 /**
- * One step of a {@link Migration} plan — a single schema change applied to one
+ * Represents one step of a {@link Migration} plan — a single schema change applied to one
  * table.
  *
  * @remarks
- * `operation` names the axis it splits on (AGENTS §4.4): adding / removing a
+ * `operation` names the axis it splits on: adding / removing a
  * whole table, a column, or an index. A driver's optional `migrate` applies each
  * step natively; a step referencing an unknown table throws `DatabaseError`
  * `MIGRATION`.
@@ -1145,7 +1352,7 @@ export declare type MigrationStep = {
 };
 
 /**
- * Canonicalize an unknown driver schema into a distinct deeply frozen snapshot.
+ * Canonicalizes 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
@@ -1165,23 +1372,24 @@ export declare function normalizeDriverSchema(value: unknown): readonly TableSch
  * 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.
+ * driver to the backend commit point. A streamed read — {@link TableInterface.scan}
+ * or {@link QueryInterface.stream} — checks the signal before each yield.
  */
 export declare interface OperationOptions {
     readonly signal?: AbortSignal;
 }
 
-/** One ordering term — a column ({@link FieldPath}, flat or nested) and its direction. */
+/** Represents one ordering term — a column ({@link FieldPath}, flat or nested) and its direction. */
 export declare interface Order {
     readonly column: FieldPath;
     readonly direction: OrderDirection;
 }
 
-/** A sort direction. */
+/** Names a sort direction. */
 export declare type OrderDirection = 'ascending' | 'descending';
 
 /**
- * Structurally diff a deployed and a declared table set into a {@link Migration}
+ * Diffs a deployed and a declared table set structurally into a {@link Migration}
  * plan.
  *
  * @remarks
@@ -1196,17 +1404,16 @@ export declare type OrderDirection = 'ascending' | 'descending';
  * 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
+ * A column present in both schemas under the same name but with a different
  * `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
- * type-change step: the manual path is to add a new column, copy/convert the
- * data at the application layer, then remove the old column — two separate
- * plans, never a single implicit "alter" step.
- *
- * @param deployed - The table schemas currently applied
+ * {@link DatabaseError} naming the table, the column, and the from→to
+ * difference — a name-only diff would otherwise silently produce no step for
+ * the drift, and versioned reconciliation would stamp over it. There is no
+ * automatic in-place type-change step: the manual path is to add a new column,
+ * copy/convert the data at the application layer, then remove the old column —
+ * two separate plans, never a single implicit "alter" step.
+ *
+ * @param deployed - The already-applied table schemas
  * @param declared - The table schemas the caller wants applied
  * @param from - The plan's source version label (defaults to `0`)
  * @param to - The plan's target version label (defaults to `1`)
@@ -1228,7 +1435,7 @@ export declare type OrderDirection = 'ascending' | 'descending';
 export declare function planMigration(deployed: readonly TableSchema[], declared: readonly TableSchema[], from?: number, to?: number): Migration;
 
 /**
- * Per-table primary-key column overrides — `{ [table]: column }`.
+ * Holds per-table primary-key column overrides — `{ [table]: column }`.
  *
  * @remarks
  * A table absent from this map keys its rows by {@link DEFAULT_PRIMARY} (`id`).
@@ -1237,7 +1444,9 @@ export declare function planMigration(deployed: readonly TableSchema[], declared
 export declare type PrimaryMap = Readonly<Record<string, string>>;
 
 /**
- * Sequentially project migration steps over a canonical validated owned schema.
+ * Projects migration steps sequentially over a canonical validated owned schema.
+ *
+ * @remarks
  * Adding a required non-null column to an existing table rejects with
  * `MIGRATION`; optional-only and nullable-only additions remain portable.
  *
@@ -1248,7 +1457,7 @@ export declare type PrimaryMap = Readonly<Record<string, string>>;
 export declare function projectMigrationSchema(schema: readonly TableSchema[], steps: readonly MigrationStep[]): readonly TableSchema[];
 
 /**
- * A serializable read specification — everything a backend needs to compile one
+ * Represents a serializable read specification — everything a backend needs to compile one
  * read, free of JS callbacks so any backend can honor it.
  *
  * @remarks
@@ -1265,50 +1474,118 @@ export declare interface QueryInput {
 }
 
 /**
- * A fluent query builder.
+ * Builds a read through a fluent chain.
  *
  * @remarks
  * `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.
+ * / `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> {
+    /**
+     * Adds one portable condition, including its explicit connector.
+     */
     condition(input: Condition): QueryInterface<T>;
+    /**
+     * Adds one portable ordering term — a column and a direction.
+     */
     order(input: Order): QueryInterface<T>;
+    /**
+     * Adds a post-fetch JavaScript predicate.
+     */
     filter(predicate: (row: T) => boolean): QueryInterface<T>;
+    /**
+     * Caps the result count.
+     */
     limit(count: number): QueryInterface<T>;
+    /**
+     * Skips the leading rows.
+     */
     offset(count: number): QueryInterface<T>;
+    /**
+     * Executes the accumulated read and collects every matching row.
+     */
     collect(): Promise<readonly T[]>;
+    /**
+     * Executes the accumulated read and returns the first match, or `undefined`.
+     */
     find(): Promise<T | undefined>;
+    /**
+     * Executes the accumulated read and returns the match count.
+     */
     count(): Promise<number>;
     /**
-     * Lazy per-row evaluation of this query's conditions / filters / offset /
-     * limit.
+     * Evaluates this query's conditions / filters / offset / limit lazily, row
+     * by row.
      *
      * @remarks
-     * `order` and its comparators are IGNORED (streaming yields unsorted, as
+     * `order` and its comparators are ignored (streaming yields unsorted, as
      * rows are evaluated one at a time). Same abort semantics as
      * {@link TableInterface.scan}: the signal (if any) is checked before each
      * yield, and breaking out early closes the underlying source.
      */
     stream(options?: OperationOptions): AsyncIterable<T>;
+    /**
+     * Executes a named aggregate over one column.
+     */
     aggregate(operation: AggregateOperation, column: FieldPath): Promise<number | undefined>;
 }
 
-/** A table row — a plain record of column values keyed by column name. */
+/**
+ * Requires one declared table's columns out of a table map.
+ *
+ * @remarks
+ * The overload preserves the map's own value type for a statically known table
+ * name, so a typed view keeps its row type without an assertion. An undeclared
+ * table is a caller error rather than an absence, so it throws instead of
+ * returning `undefined`.
+ *
+ * @param tables - The declared table map
+ * @param name - The table name
+ * @returns The table's {@link ColumnMap}
+ * @throws A `NOT_FOUND` {@link DatabaseError} when `tables` does not declare `name`
+ *
+ * @example
+ * ```ts
+ * requireColumns({ users: { id: stringShape() } }, 'users') // { id: … }
+ * ```
+ */
+export declare function requireColumns<T extends TableMap, K extends keyof T & string>(tables: T, name: K): T[K];
+
+export declare function requireColumns(tables: TableMap, name: string): ColumnMap;
+
+/**
+ * Resolves the primary-key column one table keys its rows by.
+ *
+ * @remarks
+ * A table absent from the {@link PrimaryMap} keys its rows by
+ * {@link DEFAULT_PRIMARY}, so this is total over any table name.
+ *
+ * @param primary - The per-table primary-key overrides
+ * @param name - The table name
+ * @returns The table's primary-key column
+ *
+ * @example
+ * ```ts
+ * resolvePrimary({ posts: 'slug' }, 'posts') // 'slug'
+ * resolvePrimary({ posts: 'slug' }, 'users') // 'id' — the default primary
+ * ```
+ */
+export declare function resolvePrimary(primary: PrimaryMap, name: string): string;
+
+/** Represents 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 ColumnMap} describe — `Infer` of the `objectShape`
+ * Represents 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
- * `ColumnMap` — e.g. when a database is held at its default type) directly:
+ * `ColumnMap` — for example 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
@@ -1317,12 +1594,71 @@ export declare type Row = Record<string, unknown>;
  * concrete column map.
  */
 export declare type RowOf<C extends ColumnMap> = Infer<{
-    readonly type: 'object';
+    readonly category: 'object';
     readonly properties: C;
 }>;
 
 /**
- * Project one contract shape into a portable column schema.
+ * Walks the driver-conformance battery against a fresh {@link DriverInterface}
+ * per phase, yielding one {@link ConformanceFinding} per violated invariant —
+ * the shared invariant suite every backend (in-memory, SQLite, IndexedDB)
+ * must uphold to be a drop-in {@link DriverInterface}.
+ *
+ * @remarks
+ * Framework-agnostic: no test-runner or Node imports, only sibling core
+ * modules — so it runs equally from a unit test, a smoke script, or a new
+ * driver's own README. Opens a fixed two-table schema (`users` keyed by the
+ * default `id`, `posts` keyed by a non-id `slug`) and, calling `factory()`
+ * fresh for each phase so failures stay isolated, verifies: `open`/`close`;
+ * `read` of a missing key returns `undefined`; `write`/`read` round-trip
+ * with deep copy-in/copy-out isolation (mutating the caller's row —
+ * including a nested field — after `write`, or a row `read` returns, never
+ * perturbs stored state) and upsert-overwrite; 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
+ * (through {@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 `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
+ * crash mid-phase) is caught and yielded as a finding too, naming the phase
+ * as `check` and carrying the caught error in `context.error` — a broken
+ * driver can never escape the battery as an unhandled rejection. Within a
+ * phase, the first violated assertion yields and the phase stops (matching
+ * the historical fail-fast shape at phase granularity); the generator then
+ * moves on to the next phase regardless. Because this is a **generator**,
+ * consuming only the first yielded value reproduces true fail-fast (later
+ * phases never run) — that is exactly what {@link conformDriver} does.
+ *
+ * @param factory - Mints a fresh, unopened driver instance (called once per phase)
+ * @yields One {@link ConformanceFinding} per violated invariant, in phase order
+ *
+ * @example
+ * ```ts
+ * import { createMemoryDriver, scanDriver } from '@orkestrel/database'
+ *
+ * for await (const finding of scanDriver(() => createMemoryDriver())) {
+ * 	console.log(finding.check, finding.message)
+ * }
+ * ```
+ */
+export declare function scanDriver(factory: () => DriverInterface): AsyncIterable<ConformanceFinding>;
+
+/**
+ * Projects one contract shape into a portable column schema.
  *
  * @param name - The column name
  * @param shape - The column contract shape
@@ -1331,7 +1667,7 @@ export declare type RowOf<C extends ColumnMap> = Infer<{
 export declare function shapeToColumnSchema(name: string, shape: ContractShape): ColumnSchema;
 
 /**
- * Map a column's {@link ContractShape} to its portable {@link ColumnStorage} — the
+ * Maps 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
@@ -1357,7 +1693,7 @@ export declare function shapeToColumnSchema(name: string, shape: ContractShape):
 export declare function shapeToColumnStorage(shape: ContractShape): ColumnStorage;
 
 /**
- * Sort rows by an ordering specification, leaving the input untouched.
+ * Sorts rows by an ordering specification, leaving the input untouched.
  *
  * @remarks
  * Applies the terms in priority order — the first term that distinguishes two
@@ -1370,7 +1706,7 @@ export declare function shapeToColumnStorage(shape: ContractShape): ColumnStorag
 export declare function sortRows(rows: readonly Row[], order: readonly Order[]): readonly Row[];
 
 /**
- * The storage operations available only inside a driver's transaction scope.
+ * Declares the storage operations available only inside a driver's transaction scope.
  *
  * @remarks
  * A driver owns acquisition, commit or rollback, release, and lifetime. This
@@ -1380,28 +1716,67 @@ export declare function sortRows(rows: readonly Row[], order: readonly Order[]):
  * callers fall back to `scan` when a native read hook is absent.
  */
 export declare interface StorageInterface {
+    /**
+     * Reads one row by key.
+     */
     read(table: string, key: Key): Promise<Row | undefined>;
+    /**
+     * Writes one row at a key.
+     */
     write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
+    /**
+     * Inserts one row atomically, rejecting `CONFLICT` when its key already exists.
+     */
     insert(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
+    /**
+     * Deletes one row by key.
+     */
     delete(table: string, key: Key, options?: OperationOptions): Promise<boolean>;
+    /**
+     * Lists a table's keys.
+     */
     keys(table: string): Promise<readonly Key[]>;
+    /**
+     * Iterates a table's rows in ascending key order.
+     */
     scan(table: string): AsyncIterable<Row>;
+    /**
+     * Empties a table.
+     */
     clear(table: string): Promise<void>;
+    /**
+     * Reads the rows matching a {@link QueryInput} natively — an optional hook.
+     */
     records?(table: string, input: QueryInput): Promise<readonly Row[]>;
+    /**
+     * Computes an aggregate over a column natively — an optional hook.
+     */
     aggregate?(table: string, operation: AggregateOperation, column: FieldPath, input: QueryInput): Promise<number | undefined>;
+    /**
+     * Iterates the natively filtered rows lazily — an optional hook.
+     */
     stream?(table: string, input: QueryInput): AsyncIterable<Row>;
+    /**
+     * Applies one atomic {@link MigrationInput} — an optional hook.
+     */
     migrate?(input: MigrationInput): Promise<void>;
+    /**
+     * Reads the persisted {@link DriverMetadata} as a deeply frozen copy — an optional hook.
+     */
     metadata?(): Promise<DriverMetadata | undefined>;
+    /**
+     * Writes the persisted {@link DriverMetadata}, snapshot at entry — an optional hook.
+     */
     stamp?(metadata: DriverMetadata): Promise<void>;
 }
 
 /**
- * One table's portable definition, produced by `export` — the unit of schema /
+ * Represents 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
+ * the source column map, which re-imports losslessly through `import` within a
  * TypeScript environment. `primary` is the primary-key column.
  */
 export declare interface TableDefinition {
@@ -1411,34 +1786,34 @@ export declare interface TableDefinition {
 }
 
 /**
- * The push observation surface of a {@link TableInterface} (AGENTS §13) — the per-row
+ * Describes the push observation surface of a {@link TableInterface} — the per-row
  * mutation moments a fire-and-forget observer (cache invalidation, sync, an audit log)
- * subscribes to, ALONGSIDE the database-level {@link DatabaseEventMap}.
+ * subscribes to, alongside the database-level {@link DatabaseEventMap}.
  *
  * @remarks
- * Events carry the affected KEY only — never the row value — to keep fan-out lean and
+ * Events carry the affected key only — never the row value — to keep fan-out lean and
  * avoid leaking row data through the observation channel; a consumer that needs the
  * value re-reads it by key. Any row put — `set`, `add`, or `update` — emits a single
  * `write` (the consumer re-reads if it needs to know what changed); a delete emits
- * `remove`; emptying the table emits `clear`. Reads / queries / counts are NOT emitted
- * (too hot, and a reader does not mutate). Listener isolation is the emitter's (AGENTS §13):
+ * `remove`; emptying the table emits `clear`. Reads / queries / counts are not emitted
+ * (too hot, and a reader does not mutate). Listener isolation is the emitter's:
  * every event is emitted directly and a listener throw is routed to the emitter's `error`
- * handler (the `error` option), never onto this map, and sits AFTER the driver write / delete
+ * handler (the `error` option), never onto this map, and sits after the driver write / delete
  * / clear has completed — so a throwing observer can never corrupt a write or perturb a
- * transaction. Subscribe via `table.emitter.on(...)`. Declared as a `type` alias (§4.5 —
+ * transaction. Subscribe through `table.emitter.on(...)`. Declared as a `type` alias (
  * `EventMap` is a `type` kind).
  */
 export declare type TableEventMap = {
-    /** A row was written (set / added / updated) — the affected key (no value payload). */
+    /** Signals that a row was written (set / added / updated) — the affected key (no value payload). */
     readonly write: readonly [key: Key];
-    /** A row was removed — the affected key. */
+    /** Signals that a row was removed — the affected key. */
     readonly remove: readonly [key: Key];
-    /** The table was cleared (every row removed). */
+    /** Signals that the table was cleared (every row removed). */
     readonly clear: readonly [];
 };
 
 /**
- * A table — typed keyed CRUD plus fluent query and cursor access.
+ * Exposes typed keyed CRUD plus fluent query and cursor access.
  *
  * @remarks
  * Writes are coerced through the table's contract: a string input to a numeric
@@ -1448,7 +1823,7 @@ export declare type TableEventMap = {
  * inserts and throws `CONFLICT` on a duplicate key. `contract` exposes the
  * compiled contract for introspection (`schema`) and fixtures (`generate`).
  *
- * The keyed methods batch by overload (AGENTS §9.2): pass one key/row for one
+ * The keyed methods batch by overload: pass one key/row for one
  * result, or an array for an array of results in the same order — a single verb,
  * never `getMany` / `setAll`. Batches run as independent sequential operations;
  * wrap them in `transaction` for atomicity.
@@ -1458,16 +1833,31 @@ export declare interface TableInterface<T = Row> {
     readonly name: string;
     readonly primary: string;
     readonly contract: ContractInterface<T>;
+    /**
+     * Reads one row by key, or one row per key for a list — `undefined` for each miss.
+     */
     get(key: Key): Promise<T | undefined>;
     get(keys: readonly Key[]): Promise<ReadonlyArray<T | undefined>>;
+    /**
+     * Reads one row by key, or one row per key for a list, throwing `NOT_FOUND` on a miss.
+     */
     resolve(key: Key): Promise<T>;
     resolve(keys: readonly Key[]): Promise<readonly T[]>;
+    /**
+     * Reports whether one key exists, or one result per key for a list.
+     */
     has(key: Key): Promise<boolean>;
     has(keys: readonly Key[]): Promise<readonly boolean[]>;
+    /**
+     * Lists every primary key in order.
+     */
     keys(): Promise<readonly Key[]>;
+    /**
+     * Reads the contract-valid rows matching an optional {@link QueryInput}.
+     */
     records(input?: QueryInput, options?: OperationOptions): Promise<readonly T[]>;
     /**
-     * Count contract-valid rows matching `input`'s conditions.
+     * Counts contract-valid rows matching `input`'s conditions.
      *
      * @remarks
      * Paging is ignored. Like `records()` / `scan()`, `count()` narrows every
@@ -1476,11 +1866,11 @@ export declare interface TableInterface<T = Row> {
      */
     count(input?: QueryInput, options?: OperationOptions): Promise<number>;
     /**
-     * Compute an aggregate over `column` across rows matching `input`'s
+     * Computes an aggregate over `column` across rows matching `input`'s
      * conditions.
      *
      * @remarks
-     * Unlike {@link TableInterface.count}, `aggregate` operates on STORED rows
+     * 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
@@ -1488,18 +1878,18 @@ export declare interface TableInterface<T = Row> {
      */
     aggregate(operation: AggregateOperation, column: FieldPath, input?: QueryInput, options?: OperationOptions): Promise<number | undefined>;
     /**
-     * Lazy filtered iteration over the table's rows.
+     * Iterates the table's rows lazily with filtering.
      *
      * @remarks
      * `input`'s `conditions` / `offset` / `limit` are honored lazily as rows
-     * stream; `order` is intentionally IGNORED — streaming yields driver
+     * 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(input?: QueryInput, options?: OperationOptions): AsyncIterable<T>;
     /**
-     * Upsert one or more rows.
+     * Upserts one or more rows.
      *
      * @param row - The row to upsert
      * @param options - Optional abort signal
@@ -1507,7 +1897,7 @@ export declare interface TableInterface<T = Row> {
      */
     set(row: T, options?: OperationOptions): Promise<Key>;
     /**
-     * Upsert one or more rows.
+     * Upserts one or more rows.
      *
      * @param rows - The rows to upsert
      * @param options - Optional abort signal, checked at entry and between items
@@ -1520,7 +1910,7 @@ export declare interface TableInterface<T = Row> {
      */
     set(rows: readonly T[], options?: OperationOptions): Promise<readonly Key[]>;
     /**
-     * Insert one or more rows, throwing `CONFLICT` on a duplicate key.
+     * Inserts one or more rows, throwing `CONFLICT` on a duplicate key.
      *
      * @param row - The row to insert
      * @param options - Optional abort signal
@@ -1528,7 +1918,7 @@ export declare interface TableInterface<T = Row> {
      */
     add(row: T, options?: OperationOptions): Promise<Key>;
     /**
-     * Insert one or more rows, throwing `CONFLICT` on a duplicate key.
+     * Inserts one or more rows, throwing `CONFLICT` on a duplicate key.
      *
      * @param rows - The rows to insert
      * @param options - Optional abort signal, checked at entry and between items
@@ -1541,16 +1931,16 @@ export declare interface TableInterface<T = Row> {
      */
     add(rows: readonly T[], options?: OperationOptions): Promise<readonly Key[]>;
     /**
-     * Apply a partial change to one or more rows.
+     * Applies a partial change to one or more rows.
      *
      * @param key - The key of the row to update
      * @param changes - The partial changes to apply
      * @param options - Optional abort signal
-     * @returns `true` when the row existed and was updated
+     * @returns True if the row existed and was updated; false otherwise
      */
     update(key: Key, changes: Partial<T>, options?: OperationOptions): Promise<boolean>;
     /**
-     * Apply a partial change to one or more rows.
+     * Applies a partial change to one or more rows.
      *
      * @param keys - The keys of the rows to update
      * @param changes - The partial changes to apply to each row
@@ -1564,15 +1954,15 @@ export declare interface TableInterface<T = Row> {
      */
     update(keys: readonly Key[], changes: Partial<T>, options?: OperationOptions): Promise<readonly boolean[]>;
     /**
-     * Delete one or more rows.
+     * Deletes one or more rows.
      *
      * @param key - The key of the row to remove
      * @param options - Optional abort signal
-     * @returns `true` when the row existed and was removed
+     * @returns True if the row existed and was removed; false otherwise
      */
     remove(key: Key, options?: OperationOptions): Promise<boolean>;
     /**
-     * Delete one or more rows.
+     * Deletes one or more rows.
      *
      * @param keys - The keys of the rows to remove
      * @param options - Optional abort signal, checked at entry and between items
@@ -1584,27 +1974,36 @@ export declare interface TableInterface<T = Row> {
      * applied — there is no rollback. Wrap in `transaction()` for atomicity.
      */
     remove(keys: readonly Key[], options?: OperationOptions): Promise<readonly boolean[]>;
+    /**
+     * Empties the table.
+     */
     clear(): Promise<void>;
+    /**
+     * Opens a fluent query builder over the table.
+     */
     query(): QueryInterface<T>;
+    /**
+     * Opens a forward row cursor for bulk mutation.
+     */
     cursor(): Promise<CursorInterface<T>>;
 }
 
 /**
- * A database's table schema — a map of table name to its {@link ColumnMap}.
+ * Represents a database's table schema — a map of table name to its {@link ColumnMap}.
  *
  * @remarks
  * Each table's row type is `Infer` of its columns (see {@link RowOf}); primary-key
- * columns are named separately via {@link PrimaryMap}.
+ * columns are named separately through {@link PrimaryMap}.
  */
 export declare type TableMap = Readonly<Record<string, ColumnMap>>;
 
 /**
- * A backend-agnostic description of one table — what `open` hands each driver so a
+ * Represents a backend-agnostic description of one table — what `open` hands each driver so a
  * native backend can create real tables and indexes.
  *
  * @remarks
  * Derived by the database from its `tables` contract shapes ({@link ColumnSchema}
- * per column, via `shapeToColumnStorage`), its `primary`, and its `indexes` option
+ * per column, through `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`.
  */
@@ -1616,7 +2015,7 @@ export declare interface TableSchema {
 }
 
 /**
- * Validate the paging fields of a portable query.
+ * Validates the paging fields of a portable query.
  *
  * @remarks
  * A present `limit` or `offset` must be a finite nonnegative integer; zero is