@quereus/plugin-leveldb 3.3.0 → 4.1.0

package/README.md

@@ -1,166 +1,197 @@
-# @quereus/plugin-leveldb
-
-LevelDB storage plugin for Quereus. Provides persistent storage for Node.js environments using the [`@quereus/store`](../quereus-store/) module.
-
-## Features
-
-- **Fast**: LevelDB offers excellent read/write performance for key-value workloads
-- **Transaction isolation**: Read-your-own-writes and snapshot isolation by default
-- **Sorted keys**: Efficient range queries with ordered iteration
-- **ACID batches**: Atomic writes across multiple keys
-- **Compression**: Built-in Snappy compression for reduced disk usage
-
-## Installation
-
-```bash
-npm install @quereus/plugin-leveldb @quereus/store @quereus/isolation
-```
-
-## Quick Start
-
-### With registerPlugin (Recommended)
-
-```typescript
-import { Database, registerPlugin } from '@quereus/quereus';
-import leveldbPlugin from '@quereus/plugin-leveldb/plugin';
-
-const db = new Database();
-await registerPlugin(db, leveldbPlugin, { basePath: './data' });
-
-await db.exec(`
-	create table users (id integer primary key, name text)
-	using store
-`);
-
-// Full transaction isolation enabled by default
-await db.exec('BEGIN');
-await db.exec(`INSERT INTO users VALUES (1, 'Alice')`);
-const user = await db.get('SELECT * FROM users WHERE id = 1'); // Sees uncommitted insert
-await db.exec('COMMIT');
-```
-
-### Disabling Isolation
-
-If you need maximum performance and don't require read-your-own-writes within transactions:
-
-```typescript
-await registerPlugin(db, leveldbPlugin, { 
-	basePath: './data',
-	isolation: false  // Disable isolation layer
-});
-```
-
-### Direct Usage with Provider
-
-```typescript
-import { Database } from '@quereus/quereus';
-import { createLevelDBProvider } from '@quereus/plugin-leveldb';
-import { createIsolatedStoreModule } from '@quereus/store';
-
-const db = new Database();
-const provider = createLevelDBProvider({ basePath: './data' });
-
-// With isolation (recommended)
-const storeModule = createIsolatedStoreModule({ provider });
-db.registerModule('store', storeModule);
-
-await db.exec(`
-	create table users (id integer primary key, name text)
-	using store
-`);
-```
-
-## API
-
-### LevelDBStore
-
-Low-level KVStore implementation:
-
-```typescript
-import { LevelDBStore } from '@quereus/plugin-leveldb';
-
-const store = await LevelDBStore.open({ path: './data/mystore' });
-
-await store.put(key, value);
-const data = await store.get(key);
-await store.delete(key);
-
-// Range iteration
-for await (const { key, value } of store.iterate({ gte: startKey, lt: endKey })) {
-  console.log(key, value);
-}
-
-// Batch writes
-const batch = store.batch();
-batch.put(key1, value1);
-batch.put(key2, value2);
-batch.delete(key3);
-await batch.write();
-
-await store.close();
-```
-
-### LevelDBProvider
-
-Factory for managing multiple stores:
-
-```typescript
-import { createLevelDBProvider } from '@quereus/plugin-leveldb';
-
-const provider = createLevelDBProvider({ basePath: './data' });
-
-const userStore = await provider.getStore('main', 'users');  // ./data/main/users
-const catalogStore = await provider.getCatalogStore();       // ./data/__catalog__
-
-await provider.closeStore('main', 'users');
-await provider.closeAll();
-```
-
-## Configuration
-
-### Plugin Settings
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `basePath` | string | `'./data'` | Base directory for all stores |
-| `createIfMissing` | boolean | `true` | Create directories if they don't exist |
-| `moduleName` | string | `'store'` | Name to register the virtual table module under |
-
-### LevelDBStore Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `path` | string | required | Directory path for the database |
-| `createIfMissing` | boolean | `true` | Create database if it doesn't exist |
-
-## Example with Transactions
-
-```typescript
-import { Database, registerPlugin } from '@quereus/quereus';
-import leveldbPlugin from '@quereus/plugin-leveldb/plugin';
-
-const db = new Database();
-await registerPlugin(db, leveldbPlugin, { basePath: './data' });
-
-await db.exec(`create table accounts (id integer primary key, balance real) using store`);
-
-await db.exec('begin');
-try {
-  await db.exec(`update accounts set balance = balance - 100 where id = 1`);
-  await db.exec(`update accounts set balance = balance + 100 where id = 2`);
-  await db.exec('commit');
-} catch (e) {
-  await db.exec('rollback');
-  throw e;
-}
-```
-
-## Related Packages
-
-- [`@quereus/store`](../quereus-store/) - Core storage module (StoreModule, StoreTable)
-- [`@quereus/plugin-indexeddb`](../quereus-plugin-indexeddb/) - IndexedDB plugin for browsers
-
-## License
-
-MIT
-
+# @quereus/plugin-leveldb
+
+LevelDB storage plugin for Quereus. Provides persistent storage for Node.js environments using the [`@quereus/store`](../quereus-store/) module.
+
+## Features
+
+- **Fast**: LevelDB offers excellent read/write performance for key-value workloads
+- **Transaction isolation**: Read-your-own-writes and snapshot isolation by default
+- **Sorted keys**: Efficient range queries with ordered iteration
+- **Crash-safe commits**: A whole transaction's data + secondary-index writes commit in one atomic, durable LevelDB batch (see [Storage layout](#storage-layout))
+- **Compression**: Built-in Snappy compression for reduced disk usage
+
+## Storage layout
+
+All of a database's stores live inside **one physical LevelDB** at `basePath`,
+each as a [sublevel](https://github.com/Level/abstract-level#sublevel) keyed by
+its store name:
+
+| Logical store | Sublevel name |
+|---|---|
+| Table data | `{schema}.{table}` |
+| Secondary index | `{schema}.{table}_idx_{name}` |
+| Unified stats | `__stats__` |
+| Catalog (DDL) | `__catalog__` |
+
+Because every sublevel shares one physical store, a single chained batch commits
+across all of a table's sublevels (data + every secondary index) **atomically and
+durably** — closing the crash window where a per-store commit loop could leave a
+table's rows and its indexes divergent on disk. By default each commit is
+`fsync`'d so it survives power loss; see [`syncCommits`](#plugin-settings).
+
+> **Hard cutover (no on-disk migration).** This shared-root layout is the only
+> LevelDB layout. Databases written by the older per-directory layout
+> (`{basePath}/{schema}/{table}`, a separate LevelDB per table) are **not** read
+> by this version and must be re-created. Pre-1.0 dev data is expected to be
+> thrown away; there is no migration importer.
+
+## Installation
+
+```bash
+npm install @quereus/plugin-leveldb @quereus/store @quereus/isolation
+```
+
+## Quick Start
+
+### With registerPlugin (Recommended)
+
+```typescript
+import { Database, registerPlugin } from '@quereus/quereus';
+import leveldbPlugin from '@quereus/plugin-leveldb/plugin';
+
+const db = new Database();
+await registerPlugin(db, leveldbPlugin, { basePath: './data' });
+
+await db.exec(`
+	create table users (id integer primary key, name text)
+	using store
+`);
+
+// Full transaction isolation enabled by default
+await db.exec('BEGIN');
+await db.exec(`INSERT INTO users VALUES (1, 'Alice')`);
+const user = await db.get('SELECT * FROM users WHERE id = 1'); // Sees uncommitted insert
+await db.exec('COMMIT');
+```
+
+### Disabling Isolation
+
+If you need maximum performance and don't require read-your-own-writes within transactions:
+
+```typescript
+await registerPlugin(db, leveldbPlugin, { 
+	basePath: './data',
+	isolation: false  // Disable isolation layer
+});
+```
+
+### Direct Usage with Provider
+
+```typescript
+import { Database } from '@quereus/quereus';
+import { createLevelDBProvider } from '@quereus/plugin-leveldb';
+import { createIsolatedStoreModule } from '@quereus/store';
+
+const db = new Database();
+const provider = createLevelDBProvider({ basePath: './data' });
+
+// With isolation (recommended)
+const storeModule = createIsolatedStoreModule({ provider });
+db.registerModule('store', storeModule);
+
+await db.exec(`
+	create table users (id integer primary key, name text)
+	using store
+`);
+```
+
+## API
+
+### LevelDBStore
+
+Low-level KVStore implementation. `LevelDBStore.open()` opens a **standalone**
+single physical LevelDB database — useful for one-off key-value stores (e.g. sync
+metadata). The multi-table StoreModule backend does not use this directly; it
+opens one shared root and hands out sublevel-backed stores via `LevelDBProvider`.
+
+```typescript
+import { LevelDBStore } from '@quereus/plugin-leveldb';
+
+const store = await LevelDBStore.open({ path: './data/mystore' });
+
+await store.put(key, value);
+const data = await store.get(key);
+await store.delete(key);
+
+// Range iteration
+for await (const { key, value } of store.iterate({ gte: startKey, lt: endKey })) {
+  console.log(key, value);
+}
+
+// Batch writes
+const batch = store.batch();
+batch.put(key1, value1);
+batch.put(key2, value2);
+batch.delete(key3);
+await batch.write();
+
+await store.close();
+```
+
+### LevelDBProvider
+
+Factory for managing multiple stores:
+
+```typescript
+import { createLevelDBProvider } from '@quereus/plugin-leveldb';
+
+const provider = createLevelDBProvider({ basePath: './data' });
+
+// All stores are sublevels of the single LevelDB at ./data
+const userStore = await provider.getStore('main', 'users');  // sublevel main.users
+const catalogStore = await provider.getCatalogStore();       // sublevel __catalog__
+
+await provider.closeStore('main', 'users'); // drops the sublevel handle
+await provider.closeAll();                   // closes the shared root
+```
+
+## Configuration
+
+### Plugin Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `basePath` | string | `'./data'` | Directory of the single shared LevelDB database |
+| `createIfMissing` | boolean | `true` | Create the database if it doesn't exist |
+| `syncCommits` | boolean | `true` | `fsync` each transaction commit so it survives power loss (slower commits when on) |
+| `moduleName` | string | `'store'` | Name to register the virtual table module under |
+| `isolation` | boolean | `true` | Wrap with the isolation layer (read-your-own-writes, snapshot isolation) |
+
+### LevelDBStore Options (standalone `open`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `path` | string | required | Directory path for the database |
+| `createIfMissing` | boolean | `true` | Create database if it doesn't exist |
+
+## Example with Transactions
+
+```typescript
+import { Database, registerPlugin } from '@quereus/quereus';
+import leveldbPlugin from '@quereus/plugin-leveldb/plugin';
+
+const db = new Database();
+await registerPlugin(db, leveldbPlugin, { basePath: './data' });
+
+await db.exec(`create table accounts (id integer primary key, balance real) using store`);
+
+await db.exec('begin');
+try {
+  await db.exec(`update accounts set balance = balance - 100 where id = 1`);
+  await db.exec(`update accounts set balance = balance + 100 where id = 2`);
+  await db.exec('commit');
+} catch (e) {
+  await db.exec('rollback');
+  throw e;
+}
+```
+
+## Related Packages
+
+- [`@quereus/store`](../quereus-store/) - Core storage module (StoreModule, StoreTable)
+- [`@quereus/plugin-indexeddb`](../quereus-plugin-indexeddb/) - IndexedDB plugin for browsers
+
+## License
+
+MIT
+

package/dist/src/plugin.d.ts

@@ -10,16 +10,23 @@ import { StoreModule } from '@quereus/store';
  */
 export interface LevelDBPluginConfig {
     /**
-     * Base path for all LevelDB stores.
-     * Each table gets a subdirectory under this path.
+     * Base path for the single shared LevelDB database. Every table, index, the
+     * catalog, and stats live as sublevels inside this one physical store.
      * @default './data'
      */
     basePath?: string;
     /**
-     * Create directories if they don't exist.
+     * Create the database if it doesn't exist.
      * @default true
      */
     createIfMissing?: boolean;
+    /**
+     * fsync each transaction commit before resolving, so a committed transaction
+     * survives power loss. The cost is one fsync per commit; set false to trade
+     * durability for lower commit latency.
+     * @default true
+     */
+    syncCommits?: boolean;
     /**
      * Module name to register. Tables are created with `USING <moduleName>`.
      * @default 'store'

package/dist/src/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAA6B,MAAM,gBAAgB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC/B,GAAG,EAAE,QAAQ,EACb,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAM;;;;;EAwBrC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAA6B,MAAM,gBAAgB,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC/B,GAAG,EAAE,QAAQ,EACb,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAM;;;;;EA0BrC"}

package/dist/src/plugin.js

@@ -13,9 +13,11 @@ export default function register(_db, config = {}) {
     const createIfMissing = config.createIfMissing !== false;
     const moduleName = config.moduleName ?? 'store';
     const isolation = config.isolation ?? true;
+    const syncCommits = config.syncCommits !== false;
     const provider = new LevelDBProvider({
         basePath,
         createIfMissing,
+        syncCommits,
     });
     const storeModule = isolation
         ? createIsolatedStoreModule({ provider })

package/dist/src/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAiChD;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC/B,GAAa,EACb,SAAmC,EAAE;IAErC,MAAM,QAAQ,GAAI,MAAM,CAAC,QAAmB,IAAI,QAAQ,CAAC;IACzD,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,KAAK,KAAK,CAAC;IACzD,MAAM,UAAU,GAAI,MAAM,CAAC,UAAqB,IAAI,OAAO,CAAC;IAC5D,MAAM,SAAS,GAAI,MAAM,CAAC,SAAqB,IAAI,IAAI,CAAC;IAExD,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC;QACpC,QAAQ;QACR,eAAe;KACf,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,SAAS;QAC5B,CAAC,CAAC,yBAAyB,CAAC,EAAE,QAAQ,EAAE,CAAC;QACzC,CAAC,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;IAE7B,OAAO;QACN,OAAO,EAAE;YACR;gBACC,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,WAAW;aACnB;SACD;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAyChD;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC/B,GAAa,EACb,SAAmC,EAAE;IAErC,MAAM,QAAQ,GAAI,MAAM,CAAC,QAAmB,IAAI,QAAQ,CAAC;IACzD,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,KAAK,KAAK,CAAC;IACzD,MAAM,UAAU,GAAI,MAAM,CAAC,UAAqB,IAAI,OAAO,CAAC;IAC5D,MAAM,SAAS,GAAI,MAAM,CAAC,SAAqB,IAAI,IAAI,CAAC;IACxD,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,KAAK,KAAK,CAAC;IAEjD,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC;QACpC,QAAQ;QACR,eAAe;QACf,WAAW;KACX,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,SAAS;QAC5B,CAAC,CAAC,yBAAyB,CAAC,EAAE,QAAQ,EAAE,CAAC;QACzC,CAAC,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC;IAE7B,OAAO;QACN,OAAO,EAAE;YACR;gBACC,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,WAAW;aACnB;SACD;KACD,CAAC;AACH,CAAC"}

package/dist/src/provider.d.ts

@@ -1,45 +1,73 @@
 /**
- * LevelDB KVStore provider implementation.
+ * LevelDB KVStoreProvider — shared-root layout.
  *
- * Manages LevelDB stores for the StoreModule.
+ * All of a database's stores live inside ONE physical LevelDB at `basePath`, each
+ * as a sublevel keyed by its store name:
  *
- * Storage naming convention:
- *   {basePath}/{schema}/{table}              - Data store (row data)
- *   {basePath}/{schema}/{table}_idx_{name}   - Index store (secondary indexes)
- *   {basePath}/__stats__                     - Unified stats store (row counts for all tables)
- *   {basePath}/__catalog__                   - Catalog store (DDL metadata)
+ *   {schema}.{table}            - table data       (buildDataStoreName)
+ *   {schema}.{table}_idx_{name} - secondary index  (buildIndexStoreName)
+ *   __stats__                   - unified stats     (STATS_STORE_NAME)
+ *   __catalog__                 - catalog / DDL     (CATALOG_STORE_NAME)
+ *
+ * Because every sublevel shares one physical store, a single chained batch
+ * (`root.batch()…write()`) commits across sublevels atomically and durably — see
+ * {@link LevelDBProvider.beginAtomicBatch}. This is the crash-safe single commit
+ * that the prior per-directory layout (a separate ClassicLevel per table) could
+ * not provide: separate physical databases cannot share a write batch.
+ *
+ * HARD CUTOVER: this is the only LevelDB layout. Databases written by the prior
+ * per-directory layout (`{basePath}/{schema}/{table}`) are NOT read here and must
+ * be re-created (pre-1.0 dev data). There is no on-disk migration. See README.
  */
-import type { KVStore, KVStoreProvider } from '@quereus/store';
+import type { AtomicBatch, KVStore, KVStoreProvider } from '@quereus/store';
 /**
  * Options for creating a LevelDB provider.
  */
 export interface LevelDBProviderOptions {
     /**
-     * Base path for all LevelDB stores.
-     * Each table gets a subdirectory under this path.
+     * Base path for the single shared LevelDB database. Every table, index, the
+     * catalog, and stats live as sublevels inside this one physical store.
      */
     basePath: string;
     /**
-     * Create directories if they don't exist.
+     * Create the database if it doesn't exist.
      * @default true
      */
     createIfMissing?: boolean;
+    /**
+     * fsync each atomic transaction commit (the chained batch issued by
+     * {@link LevelDBProvider.beginAtomicBatch}) before resolving. Default true —
+     * a committed transaction then survives power loss, which is the crash-safe
+     * guarantee this layout exists to provide. The cost is one fsync per commit;
+     * set false to trade durability for lower commit latency.
+     * @default true
+     */
+    syncCommits?: boolean;
 }
 /**
- * LevelDB implementation of KVStoreProvider.
- *
- * Creates separate LevelDB databases for each table, stored
- * in subdirectories under the configured base path.
+ * LevelDB implementation of KVStoreProvider over a single shared root with one
+ * sublevel per logical store.
  */
 export declare class LevelDBProvider implements KVStoreProvider {
     private basePath;
     private createIfMissing;
+    private syncCommits;
+    /** The shared physical root, once opened. */
+    private root;
+    /** Memoized in-flight root open so concurrent first-opens share one handle. */
+    private rootOpening;
+    /** Cached store handles, keyed by store (sublevel) name. */
     private stores;
-    private storePaths;
-    private catalogStore;
-    private statsStore;
+    /** In-flight sublevel opens, keyed by store name, so concurrent callers dedupe. */
+    private storeOpening;
+    /**
+     * Sublevel + ownership proof for every store this provider produced. Used by the
+     * atomic batch to map a {@link KVStore} handle back to its sublevel and to reject
+     * a foreign handle (a non-LevelDB store, or one from another provider, is absent).
+     */
+    private sublevelByStore;
     constructor(options: LevelDBProviderOptions);
-    getStore(schemaName: string, tableName: string, options?: Record<string, unknown>): Promise<KVStore>;
+    getStore(schemaName: string, tableName: string, _options?: Record<string, unknown>): Promise<KVStore>;
     getIndexStore(schemaName: string, tableName: string, indexName: string): Promise<KVStore>;
     getStatsStore(_schemaName: string, _tableName: string): Promise<KVStore>;
     getCatalogStore(): Promise<KVStore>;
@@ -47,10 +75,38 @@ export declare class LevelDBProvider implements KVStoreProvider {
     closeIndexStore(schemaName: string, tableName: string, indexName: string): Promise<void>;
     closeAll(): Promise<void>;
     deleteIndexStore(schemaName: string, tableName: string, indexName: string): Promise<void>;
-    renameTableStores(schemaName: string, oldName: string, newName: string): Promise<void>;
-    deleteTableStores(schemaName: string, tableName: string): Promise<void>;
+    renameTableStores(schemaName: string, oldName: string, newName: string, indexNames: readonly string[]): Promise<void>;
+    deleteTableStores(schemaName: string, tableName: string, indexNames: readonly string[]): Promise<void>;
+    /**
+     * Open an atomic batch across this provider's sublevels, or undefined when the
+     * shared root has not been opened yet (no stores exist → nothing to commit).
+     *
+     * All sublevels share one physical LevelDB, so a single chained batch
+     * (`root.batch()…write()`) with each op targeting its sublevel commits them
+     * atomically and durably. The transaction coordinator uses this to commit a
+     * table's data + secondary-index stores in one physical batch, closing the
+     * crash window where a per-store loop could leave them divergent.
+     *
+     * In practice the coordinator only calls this once it has pending ops — which
+     * means stores (hence the root) were already opened — so the undefined branch
+     * is defensive (the coordinator falls back to per-store `batch()`).
+     */
+    beginAtomicBatch(): AtomicBatch | undefined;
+    /**
+     * Map a {@link KVStore} handle this provider handed out back to its sublevel.
+     * A handle not produced by this provider (wrong type, or from another provider)
+     * is absent from the ownership map — a programming error.
+     */
+    private resolveSublevel;
+    /** Open (memoized) the shared physical root database. */
+    private getRoot;
+    /** Create a sublevel handle over the shared root, with the store's byte encodings. */
+    private openSublevel;
     private getOrCreateStore;
+    private openSublevelStore;
     private closeStoreByName;
+    /** Clear a store's keyspace (sublevel.clear) and drop its cached handle. */
+    private clearAndDropStore;
 }
 /**
  * Create a LevelDB provider with the given options.

package/dist/src/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI/D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,eAAe;IACtD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,UAAU,CAA6B;gBAEnC,OAAO,EAAE,sBAAsB;IAKrC,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAMpG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMzF,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYxE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAWnC,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBzB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzF,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDtF,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAuC/D,gBAAgB;YAehB,gBAAgB;CAU9B;AAeD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAEtF"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAuC5E;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,eAAe;IACtD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,WAAW,CAAU;IAE7B,6CAA6C;IAC7C,OAAO,CAAC,IAAI,CAA0B;IACtC,+EAA+E;IAC/E,OAAO,CAAC,WAAW,CAAmC;IAEtD,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAmC;IACjD,mFAAmF;IACnF,OAAO,CAAC,YAAY,CAA4C;IAChE;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAoC;gBAE/C,OAAO,EAAE,sBAAsB;IAMrC,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzF,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBzB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzF,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0ErH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5G;;;;;;;;;;;;;OAaG;IACH,gBAAgB,IAAI,WAAW,GAAG,SAAS;IAM3C;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAWvB,yDAAyD;YAC3C,OAAO;IAoBrB,sFAAsF;IACtF,OAAO,CAAC,YAAY;YAON,gBAAgB;YA2BhB,iBAAiB;YASjB,gBAAgB;IAU9B,4EAA4E;YAC9D,iBAAiB;CAK/B;AAqDD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAEtF"}