@orkestrel/database 0.0.13 → 0.0.14

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

@@ -1,11 +1,11 @@
-import { ContractInterface } from '@orkestrel/contract';
-import { ContractShape } from '@orkestrel/contract';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FieldPath } from '@orkestrel/contract';
-import { Infer } from '@orkestrel/contract';
-import { JSONSchema } from '@orkestrel/contract';
+import 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.
@@ -31,6 +31,10 @@ import { JSONSchema } from '@orkestrel/contract';
  */
 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>;
 }
 
@@ -53,7 +57,7 @@ export declare type AggregateOperation = 'count' | 'sum' | 'average' | 'minimum'
 export declare function applyQuery(rows: readonly Row[], input?: QueryInput): readonly Row[];
 
 /**
- * Runs the FULL driver-conformance battery and collects 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.
  *
@@ -115,6 +119,11 @@ export declare function checkAbort(signal: AbortSignal | undefined): void;
 /**
  * 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
  */
@@ -123,6 +132,11 @@ export declare function cloneDriverMetadata(value: unknown): DriverMetadata;
 /**
  * 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
  */
@@ -131,6 +145,11 @@ export declare function cloneDriverSchema(value: unknown): readonly TableSchema[
 /**
  * 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
  */
@@ -208,7 +227,7 @@ export declare function computeAggregate(rows: readonly unknown[], operation: Ag
  * `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 {
@@ -242,11 +261,13 @@ export declare type ConditionOperator = 'equals' | 'not' | 'above' | 'below' | '
 export declare const CONFORMANCE_POSTS_SCHEMA: TableSchema;
 
 /**
- * Holds the fixed two-table schema every driver-conformance phase opens.
+ * 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.
+ * 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[];
 
@@ -268,7 +289,8 @@ export declare const CONFORMANCE_USERS_SCHEMA: TableSchema;
  * @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;
@@ -283,11 +305,13 @@ export declare interface ConformanceFinding {
  *
  * @remarks
  * Consumes only the first value {@link scanDriver} yields: because that
- * generator is lazy, every LATER phase never runs — true fail-fast, not
+ * 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
@@ -317,20 +341,29 @@ export declare function conformDriver(factory: () => DriverInterface): Promise<v
  *   `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>;
@@ -362,9 +395,21 @@ 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;
 }
 
@@ -376,6 +421,10 @@ export declare interface CursorInterface<T = Row> {
  * 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;
@@ -426,11 +475,11 @@ export declare type DatabaseErrorCode = 'CLOSED' | 'NOT_FOUND' | 'CONFLICT' | 'V
  * 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: every event is emitted directly and a
- * listener throw is routed to the emitter's OWN `error` handler (the `error` option), never
+ * 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 through `database.emitter.on(...)`.
  *
@@ -473,11 +522,35 @@ 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>;
     /**
      * Diffs a caller-supplied deployed schema against this database's declared
@@ -485,7 +558,7 @@ export declare interface DatabaseInterface<T extends TableMap = TableMap> {
      * 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
      *
@@ -554,7 +627,7 @@ export declare interface DatabaseOptions<T extends TableMap = TableMap> {
      * 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
@@ -596,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]>>;
 }
 
 /**
- * Supplies 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
@@ -612,7 +691,7 @@ export declare const DEFAULT_PRIMARY = "id";
  * Declares the storage primitive every backend implements — the whole of the bridge.
  *
  * @remarks
- * The REQUIRED surface is deliberately minimal: keyed read / write / atomic
+ * 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
@@ -632,7 +711,17 @@ export declare const DEFAULT_PRIMARY = "id";
  * 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>;
     /**
      * Captures table rows and returns a repeatable thunk that restores those rows —
@@ -723,9 +812,9 @@ export declare interface DriverMetadata {
  * @remarks
  * Primitives compare by SameValueZero (`NaN` equals itself; `+0` equals `-0`).
  * Arrays compare by index (same length, every element `equalsValue`). Plain
- * 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
+ * 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
@@ -812,6 +901,10 @@ export declare type IndexMap = Readonly<Record<string, ReadonlyArray<readonly st
 /**
  * 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 True if `value` is a complete {@link ColumnSchema}; false otherwise
  */
@@ -837,6 +930,12 @@ export declare function isDatabaseError(value: unknown): value is DatabaseError;
 /**
  * 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 True if `value` is complete {@link DriverMetadata}; false otherwise
  */
@@ -845,6 +944,10 @@ export declare function isDriverMetadata(value: unknown): value is DriverMetadat
 /**
  * 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 True if `value` is a table-schema collection with unique table names; false otherwise
  */
@@ -861,6 +964,10 @@ export declare function isKey(value: unknown): value is Key;
 /**
  * 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 True if `value` is a complete {@link Migration}; false otherwise
  */
@@ -869,6 +976,10 @@ export declare function isMigration(value: unknown): value is Migration;
 /**
  * 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 True if `value` is a complete {@link MigrationInput}; false otherwise
  */
@@ -877,6 +988,10 @@ export declare function isMigrationInput(value: unknown): value is MigrationInpu
 /**
  * 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 True if `value` is a complete {@link MigrationStep}; false otherwise
  */
@@ -885,6 +1000,10 @@ export declare function isMigrationStep(value: unknown): value is MigrationStep;
 /**
  * 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 True if `value` is a complete {@link TableSchema}; false otherwise
  */
@@ -919,7 +1038,7 @@ export declare type KeyFunction = () => Key;
  * 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
@@ -940,7 +1059,7 @@ export declare function matchesCondition(row: Row, condition: Condition): boolea
  * @remarks
  * `*` 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
+ * 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}.
  *
@@ -995,16 +1114,16 @@ export declare function matchesLikePattern(value: string, pattern: string): bool
 export declare function matchesQuery(row: Row, conditions: readonly Condition[]): boolean;
 
 /**
- * Matches 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,
  * 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
+ * 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),
@@ -1012,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)
+ * @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;
 
 /**
- * Sets 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 `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
+ * 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
@@ -1048,7 +1168,7 @@ export declare const MAX_PATTERN_LENGTH = 1024;
  * @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 (through
+ * 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
@@ -1083,7 +1203,7 @@ export declare class MemoryDriver implements DriverInterface {
      * 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, and an
      * unknown table mirrors `scan`'s empty-yield behavior.
@@ -1252,7 +1372,8 @@ 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;
@@ -1283,16 +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
+ * difference — a name-only diff would otherwise silently produce no step for
  * the drift, and versioned reconciliation would stamp over it. There is no
  * automatic in-place type-change step: the manual path is to add a new column,
  * copy/convert the data at the application layer, then remove the old column —
  * two separate plans, never a single implicit "alter" step.
  *
- * @param deployed - The table schemas currently applied
+ * @param 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`)
@@ -1324,6 +1445,8 @@ export declare type PrimaryMap = Readonly<Record<string, string>>;
 
 /**
  * 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.
  *
@@ -1362,25 +1485,52 @@ export declare interface QueryInput {
  * {@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>;
     /**
      * 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>;
 }
 
@@ -1461,14 +1611,14 @@ export declare type RowOf<C extends ColumnMap> = Infer<{
  * 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
+ * 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
+ * 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
@@ -1482,12 +1632,12 @@ export declare type RowOf<C extends ColumnMap> = Infer<{
  * 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
+ * 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
+ * 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
@@ -1566,18 +1716,57 @@ 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>;
 }
 
@@ -1599,17 +1788,17 @@ export declare interface TableDefinition {
 /**
  * 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
+ * `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 through `table.emitter.on(...)`. Declared as a `type` alias (
  * `EventMap` is a `type` kind).
@@ -1644,13 +1833,28 @@ 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[]>;
     /**
      * Counts contract-valid rows matching `input`'s conditions.
@@ -1666,7 +1870,7 @@ export declare interface TableInterface<T = Row> {
      * 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
@@ -1678,7 +1882,7 @@ export declare interface TableInterface<T = Row> {
      *
      * @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.
@@ -1770,8 +1974,17 @@ 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>>;
 }