@orkestrel/database 0.0.13 → 0.0.15

package/README.md

@@ -1,11 +1,15 @@
 # @orkestrel/database
 
-A typed database abstraction for the `@orkestrel` line — one public
-`Database` over internal table/query engines and pluggable storage drivers at
-the seams. Consumers use `TableInterface` and `QueryInterface`. Built to sit beside
-`@orkestrel/contract` (validation) and `@orkestrel/emitter` (observable
-lifecycle), reusing both directly. `TableInterface.cursor()` exposes the
-`CursorInterface` contract for serial bulk mutation.
+> One typed database API for keyed rows, fluent queries, cursors, and
+> whole-store transactions, running unchanged over an in-memory map, a JSON
+> file, SQLite, or IndexedDB.
+
+Declare your tables with the `createDatabase` function, hold each
+`TableInterface` it hands back, and reach rows by key or through the fluent
+`query()` builder. `TableInterface.cursor()` opens the `CursorInterface`
+contract for serial bulk mutation. Built on `@orkestrel/contract` for
+validation and `@orkestrel/emitter` for the observation surface, reusing both
+directly. Part of the `@orkestrel` line.
 
 ## Install
 

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

@@ -1,19 +1,16 @@
-import { ColumnStorage } from '@orkestrel/database';
-import { Condition } from '@orkestrel/database';
+import type { ColumnStorage } from '@orkestrel/database';
+import type { Condition } from '@orkestrel/database';
 import { DatabaseError } from '@orkestrel/database';
-import { DriverInterface } from '@orkestrel/database';
-import { DriverInterface as DriverInterface_2 } from '@orkestrel/database';
-import { DriverMetadata } from '@orkestrel/database';
-import { IndexedDBError } from '@orkestrel/indexeddb';
-import { Key } from '@orkestrel/database';
-import { MigrationInput } from '@orkestrel/database';
-import { OperationOptions } from '@orkestrel/database';
-import { QueryInput } from '@orkestrel/database';
-import { QueryInput as QueryInput_2 } from '@orkestrel/database';
-import { Row } from '@orkestrel/database';
-import { StoreDefinition } from '@orkestrel/indexeddb';
-import { TableSchema } from '@orkestrel/database';
-import { TableSchema as TableSchema_2 } from '@orkestrel/database';
+import type { DriverInterface } from '@orkestrel/database';
+import type { DriverMetadata } from '@orkestrel/database';
+import type { IndexedDBError } from '@orkestrel/indexeddb';
+import type { Key } from '@orkestrel/database';
+import type { MigrationInput } from '@orkestrel/database';
+import type { OperationOptions } from '@orkestrel/database';
+import type { QueryInput } from '@orkestrel/database';
+import type { Row } from '@orkestrel/database';
+import type { StoreDefinition } from '@orkestrel/indexeddb';
+import type { TableSchema } from '@orkestrel/database';
 
 /**
  * Translates one {@link Condition} to the `IDBKeyRange` it maps to, when its
@@ -24,14 +21,14 @@ import { TableSchema as TableSchema_2 } from '@orkestrel/database';
  * Only the comparison operators (`equals`/`above`/`below`/`from`/`to`/`between`)
  * translate to a key range that a typed (string/number) column can back with an
  * IndexedDB store/index read — see {@link selectPlan} for the caveats that
- * decide WHICH of `below`/`to` may drive a SECONDARY-index read versus the
+ * decide which of `below`/`to` may drive a secondary-index read versus the
  * primary store only (a column-type / absent-row concern, not a range-shape
  * one). `starts` is excluded — its prefix range can miss strings past U+FFFF;
  * the membership / negation / pattern / existence operators (`not`/`like`/`glob`/
  * `ends`/`any`/`none`/`absent`/`present`) have no single exact range. The operand
  * guard (`typeof` string/number) rejects a non-scalar value (for example an array, a
  * boolean) that is not a usable key. `between` additionally guards against a
- * REVERSED pair (`first > second`): native `IDBKeyRange.bound` throws a raw
+ * reversed pair (`first > second`): native `IDBKeyRange.bound` throws a raw
  * `DataError` `DOMException` for a lower bound above the upper bound, so a
  * reversed pair returns `undefined` here (falls back to a full scan, which the
  * engine then correctly resolves to an empty result) rather than letting a
@@ -47,7 +44,7 @@ import { TableSchema as TableSchema_2 } from '@orkestrel/database';
 export declare function conditionToRange(condition: Condition): IDBKeyRange | undefined;
 
 /**
- * Creates a persistent IndexedDB {@link DriverInterface} for the core database layer.
+ * Creates a persistent IndexedDB {@link DriverInterface} for a browser database name.
  *
  * @remarks
  * Pass it to `createDatabase` from `@orkestrel/database` to run the typed database
@@ -74,7 +71,7 @@ export declare function conditionToRange(condition: Condition): IDBKeyRange | un
  * await db.table('users').set({ id: 'u1', name: 'Ada' }) // persisted to IndexedDB
  * ```
  */
-export declare function createIndexedDBDriver(name: string): DriverInterface_2;
+export declare function createIndexedDBDriver(name: string): DriverInterface;
 
 /**
  * Derives an IndexedDB index name for a declared column group — a bare column
@@ -83,14 +80,14 @@ export declare function createIndexedDBDriver(name: string): DriverInterface_2;
  *
  * @remarks
  * Naming a compound index by joining its columns with `_` (`['a', 'b'] →
- * 'a_b'`) collides with a single-column index over a column LITERALLY named
+ * 'a_b'`) collides with a single-column index over a column literally named
  * `'a_b'` — the same name, two different key paths (`'a_b'` vs `['a', 'b']`),
  * which either throws a native `ConstraintError` from a duplicate
  * `createIndex` call at open, or (worse) lets {@link selectPlan}'s name-based
- * lookup match the wrong index. A single-column index keeps the BARE column
+ * lookup match the wrong index. A single-column index keeps the bare column
  * name — {@link selectPlan} matches `available.includes(condition.column)` by
  * that exact name, so a single-column index must stay named after its column
- * verbatim. A compound index instead encodes each column as a LENGTH-PREFIXED
+ * verbatim. A compound index instead encodes each column as a length-prefixed
  * segment (`'2#1:a1:b'`), so the boundary between columns is self-describing
  * and cannot be reconstructed by any other column list — including one
  * containing a column that happens to look like an encoded segment.
@@ -155,28 +152,28 @@ export declare const INDEXABLE_STORAGE: readonly ColumnStorage[];
  * {@link Migration} plan natively: IndexedDB schema DDL (creating/dropping a
  * store, creating/dropping an index) is legal only inside a versionchange
  * transaction (`onupgradeneeded`), so `migrate` closes the current connection
- * and opens a FRESH one at `version + 1` with an `upgrade` hook that walks the
+ * and opens a fresh one at `version + 1` with an `upgrade` hook that walks the
  * plan's steps — dropping stores, adding/removing indexes on the raw
  * `IDBTransaction`, and rewriting rows for `column.remove` through a cursor walk
  * (the one step needing to touch existing data; `column.add` is a no-op — this
  * driver stores whatever a row carries, so there is nothing to backfill). A
- * step referencing an unknown table is validated BEFORE the reconnect, so a
+ * step referencing an unknown table is validated before the reconnect, so a
  * `MIGRATION` `DatabaseError` never wastes a version bump.
  *
  * @remarks
- * This unit deliberately OMITS `aggregate` / `transaction`. There is no native
+ * This unit deliberately omits `aggregate` / `transaction`. There is no native
  * `aggregate` (IndexedDB has no native SUM/AVG); the engine over the narrowed
  * `records` covers it. `transaction` is impossible here: the wrapper
  * auto-commits an `IDBTransaction` when control yields outside its request
  * chain, so arbitrary callback awaits cannot remain inside one native
  * transaction. Every atomic multi-operation sequence in this driver
- * (`snapshot`'s rollback) instead runs entirely inside ONE `db.write(...)`
+ * (`snapshot`'s rollback) instead runs entirely inside one `db.write(...)`
  * scope.
  */
 export declare class IndexedDBDriver implements DriverInterface {
     #private;
     constructor(name: string);
-    open(schema: readonly TableSchema_2[]): Promise<void>;
+    open(schema: readonly TableSchema[]): Promise<void>;
     close(): Promise<void>;
     read(table: string, key: Key): Promise<Row | undefined>;
     write(table: string, key: Key, row: Row, options?: OperationOptions): Promise<void>;
@@ -185,8 +182,8 @@ export declare class IndexedDBDriver implements DriverInterface {
     keys(table: string): Promise<readonly Key[]>;
     scan(table: string): AsyncIterable<Row>;
     clear(table: string): Promise<void>;
-    records(table: string, input: QueryInput_2): Promise<readonly Row[]>;
-    stream(table: string, input: QueryInput_2): AsyncIterable<Row>;
+    records(table: string, input: QueryInput): Promise<readonly Row[]>;
+    stream(table: string, input: QueryInput): AsyncIterable<Row>;
     snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
     /**
      * Returns the persisted {@link DriverMetadata}, or `undefined` when the store has
@@ -213,11 +210,11 @@ export declare class IndexedDBDriver implements DriverInterface {
      *
      * @remarks
      * IndexedDB schema DDL is legal only inside `onupgradeneeded`, so this closes
-     * the current connection and opens a FRESH one at `version + 1`, declaring
-     * every currently-known store (plus {@link METADATA_STORE}) so nothing is lost,
-     * and applying `table.remove` / `index.add` / `index.remove` /
+     * the current connection and opens a fresh one at `version + 1`, declaring
+     * every store known at that point (plus {@link METADATA_STORE}) so nothing is
+     * lost, and applying `table.remove` / `index.add` / `index.remove` /
      * `column.remove` inside `upgrade`. Every step's `table` is validated against
-     * the driver's own `#schema` BEFORE the reconnect — an unknown-table step
+     * the driver's own `#schema` before the reconnect — an unknown-table step
      * throws `DatabaseError` `MIGRATION` without ever bumping the version.
      * `table.add` / `column.add` need no upgrade-time action: `table.add` is
      * created by the wrapper's built-in create-missing-stores pass (its
@@ -260,7 +257,7 @@ export declare function mapIndexedDBError(error: IndexedDBError): DatabaseError;
 
 /**
  * Maps a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
- * for use INSIDE `migrate()` — the one context where `UPGRADE` means the
+ * for use inside `migrate()` — the one context where `UPGRADE` means the
  * migration itself failed, not a generic driver fault.
  *
  * @remarks
@@ -277,13 +274,13 @@ export declare function mapIndexedDBError(error: IndexedDBError): DatabaseError;
 export declare function mapMigrationError(error: IndexedDBError): DatabaseError;
 
 /**
- * Names the reserved out-of-line store the {@link IndexedDBDriver} stamps its
- * {@link DriverMetadata} into.
+ * Names the reserved out-of-line store `__metadata__` the {@link IndexedDBDriver}
+ * stamps its {@link DriverMetadata} into.
  *
  * @remarks
- * Backs the driver's `metadata` / `stamp` hooks. A user table declared with this
- * exact name collides with the driver's own bookkeeping, so a caller must avoid
- * it; the collision is caught at `open`.
+ * Backs the driver's `metadata` / `stamp` hooks. A user table named `__metadata__`
+ * collides with the driver's own bookkeeping, so a caller must avoid it; the
+ * collision is caught at `open`.
  */
 export declare const METADATA_STORE = "__metadata__";
 
@@ -292,7 +289,8 @@ export declare const METADATA_STORE = "__metadata__";
  * a read. An omitted `index` selects the primary store; an omitted `range`
  * performs a full scan. The plan is always a superset of the matching rows;
  * the core engine refines it to the exact result. An empty plan (`{}`) is a
- * primary-store full scan.
+ * primary-store full scan. The `@orkestrel/database/browser` entry point exports
+ * this type.
  */
 export declare interface QueryPlan {
     readonly index?: string;
@@ -302,6 +300,11 @@ export declare interface QueryPlan {
 /**
  * Projects a table schema into the IndexedDB wrapper's store definition.
  *
+ * @remarks
+ * The definition is what an ordered versionchange migration creates the store
+ * from, carrying each declared index under the name {@link deriveIndexedDBIndexName}
+ * derives for its column group.
+ *
  * @param schema - Portable table schema
  * @returns Store definition with declared indexes
  */
@@ -312,7 +315,7 @@ export declare function schemaToStore(schema: TableSchema): StoreDefinition;
  * store) and {@link IDBKeyRange} to narrow by, falling back to a full scan.
  *
  * @remarks
- * Pushdown is sound ONLY when every condition is `and`-joined: the engine folds
+ * Pushdown is sound only when every condition is `and`-joined: the engine folds
  * conditions left-to-right (`c1 && c2 && … && cn`), so the result is a subset of
  * each — narrowing on any one is then a valid superset. A single `or` breaks that
  * (a row can match through a later condition the range would exclude), so any `or`
@@ -326,21 +329,21 @@ export declare function schemaToStore(schema: TableSchema): StoreDefinition;
  * type (`boolean`/`json`/`blob`), uses a non-comparison operator, or has a
  * non-scalar operand cannot push and is skipped.
  *
- * **`below`/`to` may drive a SECONDARY-index range only when the column has NO
+ * **`below`/`to` may drive a secondary-index range only when the column has no
  * absent/null rows to lose — which this planner cannot verify from the schema
- * alone, so it restricts them to the PRIMARY store, where that is always true.**
- * The engine's total order (`compareValues`, see `@src/core`) ranks
- * `undefined` (absent) and `null` BELOW every number/string, so
- * `matchesCondition('below' | 'to', …)` is TRUE for a row whose field is absent
- * or `null` — but a secondary IndexedDB index has NO ENTRY for a row whose
+ * alone, so it restricts them to the primary store, where that is always true.**
+ * The engine's total order (`compareValues`, see `@orkestrel/database`) ranks
+ * `undefined` (absent) and `null` below every number/string, so
+ * `matchesCondition('below' | 'to', …)` is true for a row whose field is absent
+ * or `null` — but a secondary IndexedDB index has no entry for a row whose
  * indexed field is absent/`null`, so a `below`/`to` range read against that
- * index would SILENTLY DROP those rows (they can never be over-fetched, only
+ * index would silently drop those rows (they can never be over-fetched, only
  * missed — the one shape of lossiness this planner must never produce). The
- * table's PRIMARY key is exempt: a row's primary-key value is always present
+ * table's primary key is exempt: a row's primary-key value is always present
  * and never `null` (it is the row's identity, enforced at write time), so a
  * `below`/`to` range against the primary store can never exclude an
  * absent/null-keyed row because no such row exists. `equals`/`above`/`from`/
- * `between` stay index-eligible on ANY orderable column, primary or secondary:
+ * `between` stay index-eligible on any orderable column, primary or secondary:
  * each is bounded below by a scalar (`equals`/`between`'s lower bound, `above`/
  * `from`'s lower bound), and every scalar strictly out-ranks `undefined`/`null`
  * in the total order, so an absent/null-valued row can never satisfy them — the
@@ -354,7 +357,7 @@ export declare function schemaToStore(schema: TableSchema): StoreDefinition;
  * metadata.
  *
  * When no condition qualifies the plan is a full scan (`{}`) and the engine
- * does everything. The plan is always a SUPERSET of the
+ * does everything. The plan is always a superset of the
  * matching rows — the only correctness contract — so the driver may safely run
  * the exact engine over it.
  *

package/dist/src/browser/index.js

@@ -1,3 +1,4 @@
+import { isString } from "@orkestrel/contract";
 import { DatabaseError, applyQuery, bindRowKey, checkAbort, cloneDriverMetadata, cloneMigrationInput, compareValues, equalsValue, extractKey, findColumn, isDatabaseError, isKey, matchesQuery, migrateRows, normalizeDriverSchema, planMigration, projectMigrationSchema, validatePage } from "../core/index.js";
 import { createIndexedDBDatabase, isIndexedDBError, rangeAboveKey, rangeBelowKey, rangeFromKey, rangeToKey } from "@orkestrel/indexeddb";
 //#region src/browser/constants.ts
@@ -19,13 +20,13 @@ var INDEXABLE_STORAGE = Object.freeze([
 	"real"
 ]);
 /**
-* Names the reserved out-of-line store the {@link IndexedDBDriver} stamps its
-* {@link DriverMetadata} into.
+* Names the reserved out-of-line store `__metadata__` the {@link IndexedDBDriver}
+* stamps its {@link DriverMetadata} into.
 *
 * @remarks
-* Backs the driver's `metadata` / `stamp` hooks. A user table declared with this
-* exact name collides with the driver's own bookkeeping, so a caller must avoid
-* it; the collision is caught at `open`.
+* Backs the driver's `metadata` / `stamp` hooks. A user table named `__metadata__`
+* collides with the driver's own bookkeeping, so a caller must avoid it; the
+* collision is caught at `open`.
 */
 var METADATA_STORE = "__metadata__";
 //#endregion
@@ -39,14 +40,14 @@ var METADATA_STORE = "__metadata__";
 * Only the comparison operators (`equals`/`above`/`below`/`from`/`to`/`between`)
 * translate to a key range that a typed (string/number) column can back with an
 * IndexedDB store/index read — see {@link selectPlan} for the caveats that
-* decide WHICH of `below`/`to` may drive a SECONDARY-index read versus the
+* decide which of `below`/`to` may drive a secondary-index read versus the
 * primary store only (a column-type / absent-row concern, not a range-shape
 * one). `starts` is excluded — its prefix range can miss strings past U+FFFF;
 * the membership / negation / pattern / existence operators (`not`/`like`/`glob`/
 * `ends`/`any`/`none`/`absent`/`present`) have no single exact range. The operand
 * guard (`typeof` string/number) rejects a non-scalar value (for example an array, a
 * boolean) that is not a usable key. `between` additionally guards against a
-* REVERSED pair (`first > second`): native `IDBKeyRange.bound` throws a raw
+* reversed pair (`first > second`): native `IDBKeyRange.bound` throws a raw
 * `DataError` `DOMException` for a lower bound above the upper bound, so a
 * reversed pair returns `undefined` here (falls back to a full scan, which the
 * engine then correctly resolves to an empty result) rather than letting a
@@ -85,7 +86,7 @@ function conditionToRange(condition) {
 * store) and {@link IDBKeyRange} to narrow by, falling back to a full scan.
 *
 * @remarks
-* Pushdown is sound ONLY when every condition is `and`-joined: the engine folds
+* Pushdown is sound only when every condition is `and`-joined: the engine folds
 * conditions left-to-right (`c1 && c2 && … && cn`), so the result is a subset of
 * each — narrowing on any one is then a valid superset. A single `or` breaks that
 * (a row can match through a later condition the range would exclude), so any `or`
@@ -99,21 +100,21 @@ function conditionToRange(condition) {
 * type (`boolean`/`json`/`blob`), uses a non-comparison operator, or has a
 * non-scalar operand cannot push and is skipped.
 *
-* **`below`/`to` may drive a SECONDARY-index range only when the column has NO
+* **`below`/`to` may drive a secondary-index range only when the column has no
 * absent/null rows to lose — which this planner cannot verify from the schema
-* alone, so it restricts them to the PRIMARY store, where that is always true.**
+* alone, so it restricts them to the primary store, where that is always true.**
 * The engine's total order (`compareValues`, see `@src/core`) ranks
-* `undefined` (absent) and `null` BELOW every number/string, so
-* `matchesCondition('below' | 'to', …)` is TRUE for a row whose field is absent
-* or `null` — but a secondary IndexedDB index has NO ENTRY for a row whose
+* `undefined` (absent) and `null` below every number/string, so
+* `matchesCondition('below' | 'to', …)` is true for a row whose field is absent
+* or `null` — but a secondary IndexedDB index has no entry for a row whose
 * indexed field is absent/`null`, so a `below`/`to` range read against that
-* index would SILENTLY DROP those rows (they can never be over-fetched, only
+* index would silently drop those rows (they can never be over-fetched, only
 * missed — the one shape of lossiness this planner must never produce). The
-* table's PRIMARY key is exempt: a row's primary-key value is always present
+* table's primary key is exempt: a row's primary-key value is always present
 * and never `null` (it is the row's identity, enforced at write time), so a
 * `below`/`to` range against the primary store can never exclude an
 * absent/null-keyed row because no such row exists. `equals`/`above`/`from`/
-* `between` stay index-eligible on ANY orderable column, primary or secondary:
+* `between` stay index-eligible on any orderable column, primary or secondary:
 * each is bounded below by a scalar (`equals`/`between`'s lower bound, `above`/
 * `from`'s lower bound), and every scalar strictly out-ranks `undefined`/`null`
 * in the total order, so an absent/null-valued row can never satisfy them — the
@@ -127,7 +128,7 @@ function conditionToRange(condition) {
 * metadata.
 *
 * When no condition qualifies the plan is a full scan (`{}`) and the engine
-* does everything. The plan is always a SUPERSET of the
+* does everything. The plan is always a superset of the
 * matching rows — the only correctness contract — so the driver may safely run
 * the exact engine over it.
 *
@@ -149,7 +150,7 @@ function selectPlan(input, schema, available) {
 	const conditions = input?.conditions ?? [];
 	if (conditions.slice(1).some((condition) => condition.connector === "or")) return {};
 	for (const condition of conditions) {
-		if (typeof condition.column !== "string") continue;
+		if (!isString(condition.column)) continue;
 		const column = findColumn(condition.column, schema);
 		if (column === void 0 || !INDEXABLE_STORAGE.includes(column.storage)) continue;
 		const range = conditionToRange(condition);
@@ -209,7 +210,7 @@ function mapIndexedDBError(error) {
 }
 /**
 * Maps a backend {@link IndexedDBError} to the portable `DatabaseError` taxonomy
-* for use INSIDE `migrate()` — the one context where `UPGRADE` means the
+* for use inside `migrate()` — the one context where `UPGRADE` means the
 * migration itself failed, not a generic driver fault.
 *
 * @remarks
@@ -234,14 +235,14 @@ function mapMigrationError(error) {
 *
 * @remarks
 * Naming a compound index by joining its columns with `_` (`['a', 'b'] →
-* 'a_b'`) collides with a single-column index over a column LITERALLY named
+* 'a_b'`) collides with a single-column index over a column literally named
 * `'a_b'` — the same name, two different key paths (`'a_b'` vs `['a', 'b']`),
 * which either throws a native `ConstraintError` from a duplicate
 * `createIndex` call at open, or (worse) lets {@link selectPlan}'s name-based
-* lookup match the wrong index. A single-column index keeps the BARE column
+* lookup match the wrong index. A single-column index keeps the bare column
 * name — {@link selectPlan} matches `available.includes(condition.column)` by
 * that exact name, so a single-column index must stay named after its column
-* verbatim. A compound index instead encodes each column as a LENGTH-PREFIXED
+* verbatim. A compound index instead encodes each column as a length-prefixed
 * segment (`'2#1:a1:b'`), so the boundary between columns is self-describing
 * and cannot be reconstructed by any other column list — including one
 * containing a column that happens to look like an encoded segment.
@@ -263,6 +264,11 @@ function deriveIndexedDBIndexName(columns) {
 /**
 * Projects a table schema into the IndexedDB wrapper's store definition.
 *
+* @remarks
+* The definition is what an ordered versionchange migration creates the store
+* from, carrying each declared index under the name {@link deriveIndexedDBIndexName}
+* derives for its column group.
+*
 * @param schema - Portable table schema
 * @returns Store definition with declared indexes
 */
@@ -312,22 +318,22 @@ function schemaToStore(schema) {
 * {@link Migration} plan natively: IndexedDB schema DDL (creating/dropping a
 * store, creating/dropping an index) is legal only inside a versionchange
 * transaction (`onupgradeneeded`), so `migrate` closes the current connection
-* and opens a FRESH one at `version + 1` with an `upgrade` hook that walks the
+* and opens a fresh one at `version + 1` with an `upgrade` hook that walks the
 * plan's steps — dropping stores, adding/removing indexes on the raw
 * `IDBTransaction`, and rewriting rows for `column.remove` through a cursor walk
 * (the one step needing to touch existing data; `column.add` is a no-op — this
 * driver stores whatever a row carries, so there is nothing to backfill). A
-* step referencing an unknown table is validated BEFORE the reconnect, so a
+* step referencing an unknown table is validated before the reconnect, so a
 * `MIGRATION` `DatabaseError` never wastes a version bump.
 *
 * @remarks
-* This unit deliberately OMITS `aggregate` / `transaction`. There is no native
+* This unit deliberately omits `aggregate` / `transaction`. There is no native
 * `aggregate` (IndexedDB has no native SUM/AVG); the engine over the narrowed
 * `records` covers it. `transaction` is impossible here: the wrapper
 * auto-commits an `IDBTransaction` when control yields outside its request
 * chain, so arbitrary callback awaits cannot remain inside one native
 * transaction. Every atomic multi-operation sequence in this driver
-* (`snapshot`'s rollback) instead runs entirely inside ONE `db.write(...)`
+* (`snapshot`'s rollback) instead runs entirely inside one `db.write(...)`
 * scope.
 */
 var IndexedDBDriver = class {
@@ -568,11 +574,11 @@ var IndexedDBDriver = class {
 	*
 	* @remarks
 	* IndexedDB schema DDL is legal only inside `onupgradeneeded`, so this closes
-	* the current connection and opens a FRESH one at `version + 1`, declaring
-	* every currently-known store (plus {@link METADATA_STORE}) so nothing is lost,
-	* and applying `table.remove` / `index.add` / `index.remove` /
+	* the current connection and opens a fresh one at `version + 1`, declaring
+	* every store known at that point (plus {@link METADATA_STORE}) so nothing is
+	* lost, and applying `table.remove` / `index.add` / `index.remove` /
 	* `column.remove` inside `upgrade`. Every step's `table` is validated against
-	* the driver's own `#schema` BEFORE the reconnect — an unknown-table step
+	* the driver's own `#schema` before the reconnect — an unknown-table step
 	* throws `DatabaseError` `MIGRATION` without ever bumping the version.
 	* `table.add` / `column.add` need no upgrade-time action: `table.add` is
 	* created by the wrapper's built-in create-missing-stores pass (its
@@ -824,7 +830,7 @@ var IndexedDBDriver = class {
 //#endregion
 //#region src/browser/factories.ts
 /**
-* Creates a persistent IndexedDB {@link DriverInterface} for the core database layer.
+* Creates a persistent IndexedDB {@link DriverInterface} for a browser database name.
 *
 * @remarks
 * Pass it to `createDatabase` from `@orkestrel/database` to run the typed database