@meshline/storage-node 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meshline contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# Meshline SQLite storage for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`NodeSqliteStore` provides persistent transactional storage for a Meshline
+application on **Node.js 24 or later**. The package is ESM with TypeScript declarations.
+
+## Install and configure
+
+Install this adapter and the matching core together:
+
+```sh
+npm install @meshline/sdk@0.1.0-alpha.1 @meshline/storage-node@0.1.0-alpha.1
+```
+
+Import `NodeSqliteStore` from `@meshline/storage-node` and construct it
+with a database path. Create the parent directory yourself. Construction does no
+I/O; call `migrate()`, then pass the store to `MeshlineClient` and initialize the
+client. Direct store consumers call `initialize({ context, accountId })` instead.
+
+The [Node session example](https://github.com/meshline-network/sdk/blob/main/typescript/examples/node.ts)
+also configures `@meshline/transport-node` and handles cleanup.
+
+## Persistence
+
+One database stores one network/account/local device. Retain it with the same
+persistent secret protector across restarts. WAL and full synchronization are
+enabled. Transactions atomically compare revisions and commit records plus cursors.
+Conflicts surface to the caller.
+
+Query readers hold their own read-only transaction and must be disposed.
+Dispose the store after the client, relay pool, and readers have stopped.
+Database contents are not encrypted; the SDK's secret protector covers selected
+secrets, not message text or the entire file. This database format is not
+interchangeable with the .NET SDK's SQLite format.
+
+Database calls use synchronous `node:sqlite`. Keep large workloads in an
+application-owned worker when event-loop latency matters.
+
+[Storage guide](https://github.com/meshline-network/sdk/blob/main/typescript/docs/guides/storage-and-pagination.md)
+· [Platform limits](https://github.com/meshline-network/sdk/blob/main/typescript/docs/platforms.md)

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { type MeshlineStore, type QueryReader, type RecordQuery, type StorageBinding, type StoredRecord, type StoreMutation, type StoreSnapshot } from '@meshline/sdk';
+/** SQLite WAL storage with explicit migration, account binding, and fixed readers. */
+export declare class NodeSqliteStore implements MeshlineStore {
+    readonly path: string;
+    private database;
+    private initialized;
+    private disposed;
+    private disposal;
+    private readonly readers;
+    constructor(path: string);
+    migrate(signal?: AbortSignal): Promise<void>;
+    initialize(binding: StorageBinding, signal?: AbortSignal): Promise<void>;
+    read(queries: readonly RecordQuery[], signal?: AbortSignal): Promise<StoreSnapshot>;
+    commit(expectedVersion: number, mutations: readonly StoreMutation[], signal?: AbortSignal): Promise<number>;
+    openQuery(query: RecordQuery, signal?: AbortSignal): Promise<QueryReader<StoredRecord>>;
+    dispose(): Promise<void>;
+    private assertOpen;
+    private connection;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAGH,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAC3E,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAC5D,MAAM,eAAe,CAAC;AAiBvB,sFAAsF;AACtF,qBAAa,eAAgB,YAAW,aAAa;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAEnD,YAAY,IAAI,EAAE,MAAM,EAGvB;IAEK,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBjD;IAEK,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB7E;IAEK,IAAI,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAaxF;IAEK,MAAM,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBhH;IAEK,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,CAa5F;IAED,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvB;IAED,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,UAAU;CAKrB"}

package/dist/index.js

@@ -0,0 +1,249 @@
+import { DatabaseSync } from 'node:sqlite';
+import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import { StateConflictError, bindingJson, canonicalJson, parseJson, prepareCommit, requireBatchCount, requireObject, throwIfAborted, validateRecordQuery, } from '@meshline/sdk';
+function decodeRow(row) {
+    return { collection: row.collection, key: row.key, revision: row.revision, value: requireObject(parseJson(row.value)) };
+}
+function selection(query) {
+    validateRecordQuery(query);
+    const parameters = [query.collection];
+    let where = 'collection = ?';
+    if (query.key !== undefined) {
+        where += ' AND key = ?';
+        parameters.push(query.key);
+    }
+    else if (query.prefix !== undefined) {
+        where += ' AND key >= ? AND key < ?';
+        parameters.push(query.prefix, query.prefix + '\uffff');
+    }
+    return { where, parameters, order: query.reverse ? 'DESC' : 'ASC' };
+}
+/** SQLite WAL storage with explicit migration, account binding, and fixed readers. */
+export class NodeSqliteStore {
+    path;
+    database;
+    initialized = false;
+    disposed = false;
+    disposal;
+    readers = new Set();
+    constructor(path) {
+        if (!path.trim() || path === ':memory:')
+            throw new TypeError('A persistent SQLite file path is required.');
+        this.path = resolve(path);
+    }
+    async migrate(signal) {
+        this.assertOpen();
+        throwIfAborted(signal);
+        if (this.database)
+            throw new Error('Migrate before initializing the store.');
+        const database = new DatabaseSync(this.path);
+        try {
+            database.exec('PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; BEGIN IMMEDIATE;');
+            try {
+                const version = database.prepare('PRAGMA user_version').get().user_version;
+                if (version > 1)
+                    throw new Error(`Unsupported database schema ${version}.`);
+                if (version === 0)
+                    database.exec(`
+                    CREATE TABLE meshline_meta (id INTEGER PRIMARY KEY CHECK(id = 1), binding TEXT, version INTEGER NOT NULL CHECK(version >= 0));
+                    INSERT INTO meshline_meta VALUES (1, NULL, 0);
+                    CREATE TABLE meshline_records (collection TEXT NOT NULL, key TEXT NOT NULL, revision INTEGER NOT NULL, value TEXT NOT NULL,
+                        PRIMARY KEY(collection, key)) WITHOUT ROWID;
+                    PRAGMA user_version = 1;
+                `);
+                throwIfAborted(signal);
+                database.exec('COMMIT');
+            }
+            catch (error) {
+                database.exec('ROLLBACK');
+                throw error;
+            }
+        }
+        finally {
+            database.close();
+        }
+    }
+    async initialize(binding, signal) {
+        this.assertOpen();
+        throwIfAborted(signal);
+        const encoded = bindingJson(binding);
+        if (this.initialized) {
+            const existing = this.connection().prepare('SELECT binding FROM meshline_meta WHERE id = 1').get();
+            if (existing.binding !== encoded)
+                throw new Error('Database is bound to another network or account.');
+            return;
+        }
+        if (!statSync(this.path).isFile())
+            throw new Error('Database must be explicitly migrated before initialization.');
+        const database = new DatabaseSync(this.path, { open: true, readOnly: false });
+        try {
+            const version = database.prepare('PRAGMA user_version').get().user_version;
+            if (version !== 1)
+                throw new Error('Database must be explicitly migrated before initialization.');
+            database.exec('PRAGMA busy_timeout = 5000; PRAGMA synchronous = FULL; BEGIN IMMEDIATE;');
+            try {
+                const current = database.prepare('SELECT binding FROM meshline_meta WHERE id = 1').get();
+                if (current.binding !== null && current.binding !== encoded)
+                    throw new Error('Database is bound to another network or account.');
+                if (current.binding === null)
+                    database.prepare('UPDATE meshline_meta SET binding = ? WHERE id = 1').run(encoded);
+                throwIfAborted(signal);
+                database.exec('COMMIT');
+            }
+            catch (error) {
+                database.exec('ROLLBACK');
+                throw error;
+            }
+            this.database = database;
+            this.initialized = true;
+        }
+        catch (error) {
+            database.close();
+            throw error;
+        }
+    }
+    async read(queries, signal) {
+        const selections = queries.map(selection);
+        throwIfAborted(signal);
+        const database = this.connection();
+        database.exec('BEGIN DEFERRED');
+        try {
+            const version = database.prepare('SELECT version FROM meshline_meta WHERE id = 1').get().version;
+            const sets = selections.map(query => database.prepare(`SELECT * FROM meshline_records WHERE ${query.where} ORDER BY key ${query.order}`)
+                .all(...query.parameters).map(decodeRow));
+            throwIfAborted(signal);
+            database.exec('COMMIT');
+            return { version, sets };
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    async commit(expectedVersion, mutations, signal) {
+        const changes = prepareCommit(expectedVersion, mutations);
+        throwIfAborted(signal);
+        const database = this.connection();
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            const version = database.prepare('SELECT version FROM meshline_meta WHERE id = 1').get().version;
+            if (version !== expectedVersion)
+                throw new StateConflictError('Database revision changed before commit.');
+            const next = expectedVersion + 1;
+            const put = database.prepare('INSERT INTO meshline_records VALUES (?, ?, ?, ?) ON CONFLICT(collection, key) DO UPDATE SET revision = excluded.revision, value = excluded.value');
+            const remove = database.prepare('DELETE FROM meshline_records WHERE collection = ? AND key = ?');
+            for (const change of changes) {
+                if (change.kind === 'put')
+                    put.run(change.collection, change.key, next, canonicalJson(change.value));
+                else
+                    remove.run(change.collection, change.key);
+            }
+            database.prepare('UPDATE meshline_meta SET version = ? WHERE id = 1').run(next);
+            throwIfAborted(signal);
+            database.exec('COMMIT');
+            return next;
+        }
+        catch (error) {
+            database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    async openQuery(query, signal) {
+        this.connection();
+        const selected = selection(query);
+        throwIfAborted(signal);
+        const database = new DatabaseSync(this.path, { readOnly: true });
+        try {
+            database.exec('PRAGMA busy_timeout = 5000; BEGIN DEFERRED;');
+            // Fix the WAL snapshot now, not on the first application read.
+            database.prepare('SELECT version FROM meshline_meta WHERE id = 1').get();
+            const reader = new SqliteReader(database, selected, () => this.readers.delete(reader));
+            this.readers.add(reader);
+            return reader;
+        }
+        catch (error) {
+            database.close();
+            throw error;
+        }
+    }
+    dispose() {
+        if (this.disposal)
+            return this.disposal;
+        this.disposed = true;
+        this.disposal = (async () => {
+            const errors = [];
+            for (const reader of this.readers) {
+                try {
+                    await reader.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            try {
+                this.database?.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            this.database = undefined;
+            if (errors.length)
+                throw new AggregateError(errors, 'Failed to dispose SQLite storage.');
+        })();
+        return this.disposal;
+    }
+    assertOpen() { if (this.disposed)
+        throw new Error('Store is disposed.'); }
+    connection() {
+        this.assertOpen();
+        if (!this.initialized || !this.database)
+            throw new Error('Store is not initialized.');
+        return this.database;
+    }
+}
+class SqliteReader {
+    database;
+    query;
+    released;
+    offset = 0;
+    disposed = false;
+    completed = false;
+    constructor(database, query, released) {
+        this.database = database;
+        this.query = query;
+        this.released = released;
+    }
+    async readNext(count, signal) {
+        if (this.disposed)
+            throw new Error('Reader is disposed.');
+        requireBatchCount(count);
+        throwIfAborted(signal);
+        if (this.completed)
+            return [];
+        const rows = this.database.prepare(`SELECT * FROM meshline_records WHERE ${this.query.where} ORDER BY key ${this.query.order} LIMIT ? OFFSET ?`)
+            .all(...this.query.parameters, count, this.offset);
+        const values = rows.map(decodeRow);
+        throwIfAborted(signal);
+        this.offset += values.length;
+        this.completed = values.length < count;
+        return values;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        try {
+            this.database.exec('ROLLBACK');
+        }
+        finally {
+            try {
+                this.database.close();
+            }
+            finally {
+                this.released();
+            }
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@meshline/storage-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "description": "Transactional SQLite storage for the Meshline TypeScript SDK",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@meshline/sdk": "0.1.0-alpha.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meshline-network/sdk.git",
+    "directory": "typescript/packages/storage-node"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import {
+    StateConflictError, bindingJson, canonicalJson, parseJson, prepareCommit,
+    requireBatchCount, requireObject, throwIfAborted, validateRecordQuery,
+    type MeshlineStore, type QueryReader, type RecordQuery, type StorageBinding,
+    type StoredRecord, type StoreMutation, type StoreSnapshot,
+} from '@meshline/sdk';
+
+interface Row { collection: string; key: string; revision: number; value: string }
+
+function decodeRow(row: Row): StoredRecord {
+    return { collection: row.collection, key: row.key, revision: row.revision, value: requireObject(parseJson(row.value)) };
+}
+
+function selection(query: RecordQuery): { where: string; parameters: SQLInputValue[]; order: string } {
+    validateRecordQuery(query);
+    const parameters: SQLInputValue[] = [query.collection];
+    let where = 'collection = ?';
+    if (query.key !== undefined) { where += ' AND key = ?'; parameters.push(query.key); }
+    else if (query.prefix !== undefined) { where += ' AND key >= ? AND key < ?'; parameters.push(query.prefix, query.prefix + '\uffff'); }
+    return { where, parameters, order: query.reverse ? 'DESC' : 'ASC' };
+}
+
+/** SQLite WAL storage with explicit migration, account binding, and fixed readers. */
+export class NodeSqliteStore implements MeshlineStore {
+    readonly path: string;
+    private database: DatabaseSync | undefined;
+    private initialized = false;
+    private disposed = false;
+    private disposal: Promise<void> | undefined;
+    private readonly readers = new Set<SqliteReader>();
+
+    constructor(path: string) {
+        if (!path.trim() || path === ':memory:') throw new TypeError('A persistent SQLite file path is required.');
+        this.path = resolve(path);
+    }
+
+    async migrate(signal?: AbortSignal): Promise<void> {
+        this.assertOpen();
+        throwIfAborted(signal);
+        if (this.database) throw new Error('Migrate before initializing the store.');
+        const database = new DatabaseSync(this.path);
+        try {
+            database.exec('PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; BEGIN IMMEDIATE;');
+            try {
+                const version = (database.prepare('PRAGMA user_version').get() as { user_version: number }).user_version;
+                if (version > 1) throw new Error(`Unsupported database schema ${version}.`);
+                if (version === 0) database.exec(`
+                    CREATE TABLE meshline_meta (id INTEGER PRIMARY KEY CHECK(id = 1), binding TEXT, version INTEGER NOT NULL CHECK(version >= 0));
+                    INSERT INTO meshline_meta VALUES (1, NULL, 0);
+                    CREATE TABLE meshline_records (collection TEXT NOT NULL, key TEXT NOT NULL, revision INTEGER NOT NULL, value TEXT NOT NULL,
+                        PRIMARY KEY(collection, key)) WITHOUT ROWID;
+                    PRAGMA user_version = 1;
+                `);
+                throwIfAborted(signal);
+                database.exec('COMMIT');
+            } catch (error) { database.exec('ROLLBACK'); throw error; }
+        } finally { database.close(); }
+    }
+
+    async initialize(binding: StorageBinding, signal?: AbortSignal): Promise<void> {
+        this.assertOpen();
+        throwIfAborted(signal);
+        const encoded = bindingJson(binding);
+        if (this.initialized) {
+            const existing = this.connection().prepare('SELECT binding FROM meshline_meta WHERE id = 1').get() as { binding: string };
+            if (existing.binding !== encoded) throw new Error('Database is bound to another network or account.');
+            return;
+        }
+        if (!statSync(this.path).isFile()) throw new Error('Database must be explicitly migrated before initialization.');
+        const database = new DatabaseSync(this.path, { open: true, readOnly: false });
+        try {
+            const version = (database.prepare('PRAGMA user_version').get() as { user_version: number }).user_version;
+            if (version !== 1) throw new Error('Database must be explicitly migrated before initialization.');
+            database.exec('PRAGMA busy_timeout = 5000; PRAGMA synchronous = FULL; BEGIN IMMEDIATE;');
+            try {
+                const current = database.prepare('SELECT binding FROM meshline_meta WHERE id = 1').get() as { binding: string | null };
+                if (current.binding !== null && current.binding !== encoded) throw new Error('Database is bound to another network or account.');
+                if (current.binding === null) database.prepare('UPDATE meshline_meta SET binding = ? WHERE id = 1').run(encoded);
+                throwIfAborted(signal);
+                database.exec('COMMIT');
+            } catch (error) { database.exec('ROLLBACK'); throw error; }
+            this.database = database;
+            this.initialized = true;
+        } catch (error) { database.close(); throw error; }
+    }
+
+    async read(queries: readonly RecordQuery[], signal?: AbortSignal): Promise<StoreSnapshot> {
+        const selections = queries.map(selection);
+        throwIfAborted(signal);
+        const database = this.connection();
+        database.exec('BEGIN DEFERRED');
+        try {
+            const version = (database.prepare('SELECT version FROM meshline_meta WHERE id = 1').get() as { version: number }).version;
+            const sets = selections.map(query => (database.prepare(`SELECT * FROM meshline_records WHERE ${query.where} ORDER BY key ${query.order}`)
+                .all(...query.parameters) as unknown as Row[]).map(decodeRow));
+            throwIfAborted(signal);
+            database.exec('COMMIT');
+            return { version, sets };
+        } catch (error) { database.exec('ROLLBACK'); throw error; }
+    }
+
+    async commit(expectedVersion: number, mutations: readonly StoreMutation[], signal?: AbortSignal): Promise<number> {
+        const changes = prepareCommit(expectedVersion, mutations);
+        throwIfAborted(signal);
+        const database = this.connection();
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            const version = (database.prepare('SELECT version FROM meshline_meta WHERE id = 1').get() as { version: number }).version;
+            if (version !== expectedVersion) throw new StateConflictError('Database revision changed before commit.');
+            const next = expectedVersion + 1;
+            const put = database.prepare('INSERT INTO meshline_records VALUES (?, ?, ?, ?) ON CONFLICT(collection, key) DO UPDATE SET revision = excluded.revision, value = excluded.value');
+            const remove = database.prepare('DELETE FROM meshline_records WHERE collection = ? AND key = ?');
+            for (const change of changes) {
+                if (change.kind === 'put') put.run(change.collection, change.key, next, canonicalJson(change.value));
+                else remove.run(change.collection, change.key);
+            }
+            database.prepare('UPDATE meshline_meta SET version = ? WHERE id = 1').run(next);
+            throwIfAborted(signal);
+            database.exec('COMMIT');
+            return next;
+        } catch (error) { database.exec('ROLLBACK'); throw error; }
+    }
+
+    async openQuery(query: RecordQuery, signal?: AbortSignal): Promise<QueryReader<StoredRecord>> {
+        this.connection();
+        const selected = selection(query);
+        throwIfAborted(signal);
+        const database = new DatabaseSync(this.path, { readOnly: true });
+        try {
+            database.exec('PRAGMA busy_timeout = 5000; BEGIN DEFERRED;');
+            // Fix the WAL snapshot now, not on the first application read.
+            database.prepare('SELECT version FROM meshline_meta WHERE id = 1').get();
+            const reader = new SqliteReader(database, selected, () => this.readers.delete(reader));
+            this.readers.add(reader);
+            return reader;
+        } catch (error) { database.close(); throw error; }
+    }
+
+    dispose(): Promise<void> {
+        if (this.disposal) return this.disposal;
+        this.disposed = true;
+        this.disposal = (async () => {
+            const errors: unknown[] = [];
+            for (const reader of this.readers) { try { await reader.dispose(); } catch (error) { errors.push(error); } }
+            try { this.database?.close(); } catch (error) { errors.push(error); }
+            this.database = undefined;
+            if (errors.length) throw new AggregateError(errors, 'Failed to dispose SQLite storage.');
+        })();
+        return this.disposal;
+    }
+
+    private assertOpen(): void { if (this.disposed) throw new Error('Store is disposed.'); }
+    private connection(): DatabaseSync {
+        this.assertOpen();
+        if (!this.initialized || !this.database) throw new Error('Store is not initialized.');
+        return this.database;
+    }
+}
+
+class SqliteReader implements QueryReader<StoredRecord> {
+    private offset = 0;
+    private disposed = false;
+    private completed = false;
+
+    constructor(private readonly database: DatabaseSync, private readonly query: ReturnType<typeof selection>, private readonly released: () => void) {}
+
+    async readNext(count: number, signal?: AbortSignal): Promise<readonly StoredRecord[]> {
+        if (this.disposed) throw new Error('Reader is disposed.');
+        requireBatchCount(count);
+        throwIfAborted(signal);
+        if (this.completed) return [];
+        const rows = this.database.prepare(`SELECT * FROM meshline_records WHERE ${this.query.where} ORDER BY key ${this.query.order} LIMIT ? OFFSET ?`)
+            .all(...this.query.parameters, count, this.offset) as unknown as Row[];
+        const values = rows.map(decodeRow);
+        throwIfAborted(signal);
+        this.offset += values.length;
+        this.completed = values.length < count;
+        return values;
+    }
+
+    async dispose(): Promise<void> {
+        if (this.disposed) return;
+        this.disposed = true;
+        try { this.database.exec('ROLLBACK'); }
+        finally { try { this.database.close(); } finally { this.released(); } }
+    }
+}