om-memory-system 3.0.0

package/dist/services/turso/shard-manager.d.ts

@@ -0,0 +1,38 @@
+import type { ShardInfo } from "./types.js";
+import type { TursoDb } from "./turso-db.js";
+export declare class TursoShardManager {
+    private metadataDb;
+    private metadataPath;
+    private initPromise;
+    private readonly writeLocks;
+    reset(): void;
+    withScopeWriteLock<T>(scope: "user" | "project", scopeHash: string, fn: () => Promise<T>): Promise<T>;
+    private ensureInitialized;
+    private initMetadataDb;
+    getShardPath(scope: "user" | "project", scopeHash: string, shardIndex: number): string;
+    private resolveStoredPath;
+    getActiveShard(scope: "user" | "project", scopeHash: string): Promise<ShardInfo | null>;
+    getAllShards(scope: "user" | "project", scopeHash: string): Promise<ShardInfo[]>;
+    createShard(scope: "user" | "project", scopeHash: string, shardIndex: number): Promise<ShardInfo>;
+    registerExistingShard(scope: "user" | "project", scopeHash: string, shardIndex: number, dbPath: string, vectorCount: number, isActive: boolean): Promise<ShardInfo>;
+    initShardDb(db: TursoDb, dimensions?: number, embeddingModel?: string): Promise<void>;
+    private rowToShardInfo;
+    private hasMatchingEmbeddingDimensions;
+    private syncShardVectorCount;
+    private isShardValid;
+    getWriteShard(scope: "user" | "project", scopeHash: string): Promise<ShardInfo>;
+    private markShardReadOnly;
+    incrementVectorCount(shardId: number): Promise<void>;
+    decrementVectorCount(shardId: number): Promise<void>;
+    setVectorCount(shardId: number, count: number): Promise<void>;
+    getShardById(shardId: number): Promise<ShardInfo | null>;
+    getShardByPath(dbPath: string): Promise<ShardInfo | null>;
+    deleteShard(shardId: number): Promise<void>;
+    archiveShard(shardId: number, reason: string, archivePathOverride?: string): Promise<string | null>;
+    /**
+     * Reassign a registered shard to a new scope hash and on-disk filename.
+     * Caller must close the DB connection and rename the file before calling this.
+     */
+    reassignShardScope(shardId: number, newScopeHash: string, newDbPath: string, vectorCount: number, isActive: boolean): Promise<ShardInfo>;
+}
+export declare const tursoShardManager: TursoShardManager;

package/dist/services/turso/shard-manager.js

@@ -0,0 +1,496 @@
+import { join, basename, resolve, relative } from "node:path";
+import { existsSync, renameSync, unlinkSync } from "node:fs";
+import { CONFIG } from "../../config.js";
+import { assertSafeScopeHash } from "../memory-scope.js";
+import { tursoConnectionManager } from "./connection-manager.js";
+import { log } from "../logger.js";
+import { assertNoTursoMigrationInProgress } from "./operation-lock.js";
+import { withCrossProcessWriteLock } from "./cross-process-write-lock.js";
+import { withSqliteFileLockRetry } from "./sqlite-handle-release.js";
+const METADATA_DB_NAME = "metadata.db";
+function getValidatedEmbeddingDimensions(dimensions = CONFIG.embeddingDimensions) {
+    const dims = dimensions;
+    if (!Number.isInteger(dims) || dims <= 0 || dims > 65536) {
+        throw new Error(`Invalid embeddingDimensions config: ${dims}`);
+    }
+    return dims;
+}
+function isUniqueConstraintError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("UNIQUE constraint failed") || message.includes("SQLITE_CONSTRAINT");
+}
+export class TursoShardManager {
+    metadataDb = null;
+    metadataPath = "";
+    initPromise = null;
+    writeLocks = new Map();
+    reset() {
+        this.metadataDb = null;
+        this.initPromise = null;
+        this.metadataPath = "";
+        this.writeLocks.clear();
+    }
+    async withScopeWriteLock(scope, scopeHash, fn) {
+        const key = `${scope}:${scopeHash}`;
+        const previous = this.writeLocks.get(key) ?? Promise.resolve();
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const next = previous.catch(() => undefined).then(() => gate);
+        this.writeLocks.set(key, next);
+        await previous.catch(() => undefined);
+        try {
+            // In-process queue first, then the cross-process advisory lock: every
+            // writer takes them in the same order, and the file lock arbitrates
+            // between processes (OpenCode + Pi, or any two writers) so that shard
+            // allocation, vector-count sync, and the insert itself run as one
+            // critical section per scope.
+            return await withCrossProcessWriteLock(scope, scopeHash, fn);
+        }
+        finally {
+            release();
+            if (this.writeLocks.get(key) === next) {
+                this.writeLocks.delete(key);
+            }
+        }
+    }
+    async ensureInitialized() {
+        if (this.metadataDb && this.initPromise) {
+            await this.initPromise;
+            return this.metadataDb;
+        }
+        if (this.initPromise) {
+            await this.initPromise;
+            if (this.metadataDb)
+                return this.metadataDb;
+        }
+        this.initPromise = (async () => {
+            try {
+                this.metadataPath = join(CONFIG.storagePath, METADATA_DB_NAME);
+                this.metadataDb = await tursoConnectionManager.getConnection(this.metadataPath);
+                await this.initMetadataDb(this.metadataDb);
+            }
+            catch (error) {
+                this.initPromise = null;
+                this.metadataDb = null;
+                throw error;
+            }
+        })();
+        await this.initPromise;
+        return this.metadataDb;
+    }
+    async initMetadataDb(db) {
+        await db.batch([
+            {
+                sql: `
+          CREATE TABLE IF NOT EXISTS shards (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            scope TEXT NOT NULL,
+            scope_hash TEXT NOT NULL,
+            shard_index INTEGER NOT NULL,
+            db_path TEXT NOT NULL,
+            vector_count INTEGER DEFAULT 0,
+            is_active INTEGER DEFAULT 1,
+            created_at INTEGER NOT NULL,
+            UNIQUE(scope, scope_hash, shard_index)
+          )
+        `,
+            },
+            {
+                sql: `
+          CREATE INDEX IF NOT EXISTS idx_active_shards
+          ON shards(scope, scope_hash, is_active)
+        `,
+            },
+        ]);
+    }
+    getShardPath(scope, scopeHash, shardIndex) {
+        assertSafeScopeHash(scopeHash);
+        const scopeDir = resolve(CONFIG.storagePath, `${scope}s`);
+        const fullPath = resolve(join(scopeDir, `${scope}_${scopeHash}_shard_${shardIndex}.db`));
+        const relativePath = relative(scopeDir, fullPath);
+        if (relativePath.startsWith("..") || relativePath.includes("..")) {
+            throw new Error(`Shard path escapes storage directory: ${fullPath}`);
+        }
+        return fullPath;
+    }
+    resolveStoredPath(storedPath, scope) {
+        const fileName = basename(storedPath);
+        return join(CONFIG.storagePath, `${scope}s`, fileName);
+    }
+    async getActiveShard(scope, scopeHash) {
+        const metadataDb = await this.ensureInitialized();
+        const row = await metadataDb.get(`
+      SELECT * FROM shards
+      WHERE scope = ? AND scope_hash = ? AND is_active = 1
+      ORDER BY shard_index DESC LIMIT 1
+    `, [scope, scopeHash]);
+        if (!row)
+            return null;
+        return this.rowToShardInfo(row);
+    }
+    async getAllShards(scope, scopeHash) {
+        const metadataDb = await this.ensureInitialized();
+        const rows = scopeHash === ""
+            ? await metadataDb.all(`
+          SELECT * FROM shards
+          WHERE scope = ?
+          ORDER BY shard_index ASC
+        `, [scope])
+            : await metadataDb.all(`
+          SELECT * FROM shards
+          WHERE scope = ? AND scope_hash = ?
+          ORDER BY shard_index ASC
+        `, [scope, scopeHash]);
+        return rows.map((row) => this.rowToShardInfo(row));
+    }
+    async createShard(scope, scopeHash, shardIndex) {
+        const metadataDb = await this.ensureInitialized();
+        const fullPath = this.getShardPath(scope, scopeHash, shardIndex);
+        const storedPath = join(`${scope}s`, basename(fullPath)).replace(/\\/g, "/");
+        const now = Date.now();
+        // Initialize the shard file BEFORE inserting the registry row. If init throws
+        // (disk full, permissions), the registry stays free of an orphan row that points
+        // at an uninitialized file — such a row would later fail isShardValid on every
+        // getWriteShard and brick all writes to this scope. initShardDb is idempotent.
+        const shardDb = await tursoConnectionManager.getConnection(fullPath);
+        await this.initShardDb(shardDb);
+        let result;
+        try {
+            result = await metadataDb.execute(`
+      INSERT INTO shards (scope, scope_hash, shard_index, db_path, vector_count, is_active, created_at)
+      VALUES (?, ?, ?, ?, 0, 1, ?)
+    `, [scope, scopeHash, shardIndex, storedPath, now]);
+        }
+        catch (error) {
+            if (isUniqueConstraintError(error)) {
+                const existing = await metadataDb.get(`
+          SELECT * FROM shards
+          WHERE scope = ? AND scope_hash = ? AND shard_index = ?
+        `, [scope, scopeHash, shardIndex]);
+                if (existing) {
+                    return this.rowToShardInfo(existing);
+                }
+            }
+            throw error;
+        }
+        return {
+            id: Number(result.lastInsertRowid),
+            scope,
+            scopeHash,
+            shardIndex,
+            dbPath: fullPath,
+            vectorCount: 0,
+            isActive: true,
+            createdAt: now,
+        };
+    }
+    async registerExistingShard(scope, scopeHash, shardIndex, dbPath, vectorCount, isActive) {
+        assertSafeScopeHash(scopeHash);
+        const metadataDb = await this.ensureInitialized();
+        const storedPath = join(`${scope}s`, basename(dbPath)).replace(/\\/g, "/");
+        const now = Date.now();
+        await metadataDb.execute(`
+        INSERT INTO shards (
+          scope, scope_hash, shard_index, db_path, vector_count, is_active, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(scope, scope_hash, shard_index) DO UPDATE SET
+          db_path = excluded.db_path,
+          vector_count = excluded.vector_count,
+          is_active = excluded.is_active
+      `, [scope, scopeHash, shardIndex, storedPath, vectorCount, isActive ? 1 : 0, now]);
+        const row = await metadataDb.get(`SELECT * FROM shards WHERE scope = ? AND scope_hash = ? AND shard_index = ?`, [scope, scopeHash, shardIndex]);
+        if (!row) {
+            throw new Error(`Failed to register shard ${scope}/${scopeHash}#${shardIndex}`);
+        }
+        return this.rowToShardInfo(row);
+    }
+    async initShardDb(db, dimensions = CONFIG.embeddingDimensions, embeddingModel = CONFIG.embeddingModel) {
+        const dims = getValidatedEmbeddingDimensions(dimensions);
+        await db.batch([
+            {
+                sql: `
+          CREATE TABLE IF NOT EXISTS shard_metadata (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+          )
+        `,
+            },
+            {
+                sql: `
+          INSERT OR REPLACE INTO shard_metadata (key, value)
+          VALUES ('embedding_dimensions', ?)
+        `,
+                args: [String(dims)],
+            },
+            {
+                sql: `
+          INSERT OR REPLACE INTO shard_metadata (key, value)
+          VALUES ('embedding_model', ?)
+        `,
+                args: [embeddingModel],
+            },
+            {
+                sql: `
+          CREATE TABLE IF NOT EXISTS memories (
+            id TEXT PRIMARY KEY,
+            content TEXT NOT NULL,
+            vector F32_BLOB(${dims}) NOT NULL,
+            tags_vector F32_BLOB(${dims}),
+            container_tag TEXT NOT NULL,
+            tags TEXT,
+            type TEXT,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL,
+            metadata TEXT,
+            display_name TEXT,
+            user_name TEXT,
+            user_email TEXT,
+            project_path TEXT,
+            project_name TEXT,
+            git_repo_url TEXT,
+            is_pinned INTEGER DEFAULT 0
+          )
+        `,
+            },
+            {
+                sql: `CREATE INDEX IF NOT EXISTS idx_container_tag ON memories(container_tag)`,
+            },
+            {
+                sql: `CREATE INDEX IF NOT EXISTS idx_type ON memories(type)`,
+            },
+            {
+                sql: `CREATE INDEX IF NOT EXISTS idx_created_at ON memories(created_at DESC)`,
+            },
+            {
+                sql: `CREATE INDEX IF NOT EXISTS idx_is_pinned ON memories(is_pinned)`,
+            },
+            {
+                sql: `
+          CREATE INDEX IF NOT EXISTS memories_vec_idx
+          ON memories (libsql_vector_idx(
+            vector,
+            'metric=cosine',
+            'compress_neighbors=float8',
+            'max_neighbors=20'
+          ))
+        `,
+            },
+            {
+                sql: `
+          CREATE INDEX IF NOT EXISTS memories_tags_vec_idx
+          ON memories (libsql_vector_idx(
+            tags_vector,
+            'metric=cosine',
+            'compress_neighbors=float8',
+            'max_neighbors=20'
+          ))
+          WHERE tags_vector IS NOT NULL
+        `,
+            },
+        ]);
+    }
+    rowToShardInfo(row) {
+        return {
+            id: Number(row.id),
+            scope: row.scope,
+            scopeHash: String(row.scope_hash),
+            shardIndex: Number(row.shard_index),
+            dbPath: this.resolveStoredPath(String(row.db_path), String(row.scope)),
+            vectorCount: Number(row.vector_count),
+            isActive: Number(row.is_active) === 1,
+            createdAt: Number(row.created_at),
+        };
+    }
+    async hasMatchingEmbeddingDimensions(db, shard) {
+        const row = await db.get(`SELECT value FROM shard_metadata WHERE key = 'embedding_dimensions'`);
+        if (!row?.value) {
+            log("Shard missing embedding_dimensions metadata", {
+                dbPath: shard.dbPath,
+                shardId: shard.id,
+            });
+            return false;
+        }
+        const storedDimensions = Number(row.value);
+        if (storedDimensions !== getValidatedEmbeddingDimensions()) {
+            log("Shard embedding dimensions mismatch", {
+                dbPath: shard.dbPath,
+                shardId: shard.id,
+                storedDimensions,
+                configDimensions: CONFIG.embeddingDimensions,
+            });
+            return false;
+        }
+        return true;
+    }
+    async syncShardVectorCount(shard) {
+        const db = await tursoConnectionManager.getConnection(shard.dbPath);
+        const row = await db.get(`SELECT COUNT(*) as count FROM memories`);
+        const count = Number(row?.count ?? 0);
+        if (count === shard.vectorCount) {
+            return shard;
+        }
+        const metadataDb = await this.ensureInitialized();
+        await metadataDb.run(`UPDATE shards SET vector_count = ? WHERE id = ?`, [count, shard.id]);
+        return { ...shard, vectorCount: count };
+    }
+    async isShardValid(shard) {
+        if (!existsSync(shard.dbPath)) {
+            log("Shard DB file missing", { dbPath: shard.dbPath, shardId: shard.id });
+            return false;
+        }
+        try {
+            const db = await tursoConnectionManager.getConnection(shard.dbPath);
+            const result = await db.get(`SELECT name FROM sqlite_master WHERE type='table' AND name='memories'`);
+            if (!result) {
+                log("Shard DB missing 'memories' table", {
+                    dbPath: shard.dbPath,
+                    shardId: shard.id,
+                });
+                return false;
+            }
+            if (!(await this.hasMatchingEmbeddingDimensions(db, shard))) {
+                return false;
+            }
+            return true;
+        }
+        catch (error) {
+            log("Error validating shard DB", {
+                dbPath: shard.dbPath,
+                error: String(error),
+            });
+            return false;
+        }
+    }
+    async getWriteShard(scope, scopeHash) {
+        assertNoTursoMigrationInProgress();
+        for (let attempt = 0; attempt < 3; attempt++) {
+            let shard = await this.getActiveShard(scope, scopeHash);
+            if (!shard) {
+                return this.createShard(scope, scopeHash, 0);
+            }
+            if (!(await this.isShardValid(shard))) {
+                throw new Error(`Shard ${shard.scope}/${shard.scopeHash}#${shard.shardIndex} is incompatible or corrupt. ` +
+                    `The original database was left untouched at ${shard.dbPath}; run the migration or restore it before writing.`);
+            }
+            shard = await this.syncShardVectorCount(shard);
+            if (shard.vectorCount >= CONFIG.maxVectorsPerShard) {
+                await this.markShardReadOnly(shard.id);
+                return this.createShard(scope, scopeHash, shard.shardIndex + 1);
+            }
+            return shard;
+        }
+        throw new Error(`Failed to resolve write shard for ${scope}/${scopeHash}`);
+    }
+    async markShardReadOnly(shardId) {
+        const metadataDb = await this.ensureInitialized();
+        await metadataDb.run(`UPDATE shards SET is_active = 0 WHERE id = ?`, [shardId]);
+    }
+    async incrementVectorCount(shardId) {
+        const metadataDb = await this.ensureInitialized();
+        await metadataDb.run(`UPDATE shards SET vector_count = vector_count + 1 WHERE id = ?`, [
+            shardId,
+        ]);
+    }
+    async decrementVectorCount(shardId) {
+        const metadataDb = await this.ensureInitialized();
+        await metadataDb.run(`UPDATE shards SET vector_count = vector_count - 1 WHERE id = ? AND vector_count > 0`, [shardId]);
+    }
+    async setVectorCount(shardId, count) {
+        if (!Number.isInteger(count) || count < 0) {
+            throw new Error(`Invalid vector count: ${count}`);
+        }
+        const metadataDb = await this.ensureInitialized();
+        await metadataDb.run(`UPDATE shards SET vector_count = ? WHERE id = ?`, [count, shardId]);
+    }
+    async getShardById(shardId) {
+        const metadataDb = await this.ensureInitialized();
+        const row = await metadataDb.get(`SELECT * FROM shards WHERE id = ?`, [shardId]);
+        return row ? this.rowToShardInfo(row) : null;
+    }
+    async getShardByPath(dbPath) {
+        const metadataDb = await this.ensureInitialized();
+        const fileName = basename(dbPath);
+        // Stored db_path is always `<scope>s/<basename>` (see createShard/registerExistingShard),
+        // so anchor on the "/" separator. Escape LIKE metacharacters in the filename — otherwise
+        // the "_" in shard names like `user_<hash>_0.db` would match any character.
+        const escaped = fileName.replace(/[\\%_]/g, "\\$&");
+        const row = await metadataDb.get(`SELECT * FROM shards WHERE db_path LIKE '%/' || ? ESCAPE '\\'`, [escaped]);
+        if (!row)
+            return null;
+        return this.rowToShardInfo(row);
+    }
+    async deleteShard(shardId) {
+        const metadataDb = await this.ensureInitialized();
+        const row = await metadataDb.get(`SELECT * FROM shards WHERE id = ?`, [shardId]);
+        if (!row)
+            return;
+        const fullPath = this.resolveStoredPath(String(row.db_path), String(row.scope));
+        await tursoConnectionManager.closeConnection(fullPath);
+        try {
+            if (existsSync(fullPath)) {
+                await withSqliteFileLockRetry(() => unlinkSync(fullPath));
+            }
+        }
+        catch (error) {
+            log("Error deleting shard file", {
+                dbPath: fullPath,
+                error: String(error),
+            });
+        }
+        await metadataDb.run(`DELETE FROM shards WHERE id = ?`, [shardId]);
+    }
+    async archiveShard(shardId, reason, archivePathOverride) {
+        const metadataDb = await this.ensureInitialized();
+        const row = await metadataDb.get(`SELECT * FROM shards WHERE id = ?`, [shardId]);
+        if (!row)
+            return null;
+        const fullPath = this.resolveStoredPath(String(row.db_path), String(row.scope));
+        await tursoConnectionManager.closeConnection(fullPath);
+        const archivePath = archivePathOverride ?? `${fullPath}.${reason}-${process.pid}-${Date.now()}.bak`;
+        const scopeDir = resolve(CONFIG.storagePath, `${String(row.scope)}s`);
+        const archiveRelativePath = relative(scopeDir, resolve(archivePath));
+        if (archiveRelativePath.startsWith("..") || archiveRelativePath.includes("..")) {
+            throw new Error(`Archive path escapes storage directory: ${archivePath}`);
+        }
+        if (existsSync(fullPath)) {
+            await withSqliteFileLockRetry(() => renameSync(fullPath, archivePath));
+        }
+        try {
+            await metadataDb.run(`DELETE FROM shards WHERE id = ?`, [shardId]);
+        }
+        catch (error) {
+            if (existsSync(archivePath) && !existsSync(fullPath)) {
+                await withSqliteFileLockRetry(() => renameSync(archivePath, fullPath));
+            }
+            throw error;
+        }
+        return existsSync(archivePath) ? archivePath : null;
+    }
+    /**
+     * Reassign a registered shard to a new scope hash and on-disk filename.
+     * Caller must close the DB connection and rename the file before calling this.
+     */
+    async reassignShardScope(shardId, newScopeHash, newDbPath, vectorCount, isActive) {
+        assertSafeScopeHash(newScopeHash);
+        const metadataDb = await this.ensureInitialized();
+        const row = await metadataDb.get(`SELECT * FROM shards WHERE id = ?`, [shardId]);
+        if (!row) {
+            throw new Error(`Shard ${shardId} not found in metadata registry`);
+        }
+        const scope = String(row.scope);
+        const storedPath = join(`${scope}s`, basename(newDbPath)).replace(/\\/g, "/");
+        await metadataDb.run(`
+      UPDATE shards
+      SET scope_hash = ?, db_path = ?, vector_count = ?, is_active = ?
+      WHERE id = ?
+    `, [newScopeHash, storedPath, vectorCount, isActive ? 1 : 0, shardId]);
+        const updated = await metadataDb.get(`SELECT * FROM shards WHERE id = ?`, [shardId]);
+        if (!updated) {
+            throw new Error(`Failed to reassign shard ${shardId}`);
+        }
+        return this.rowToShardInfo(updated);
+    }
+}
+export const tursoShardManager = new TursoShardManager();

package/dist/services/turso/sqlite-handle-release.d.ts

@@ -0,0 +1,16 @@
+export declare const RETRYABLE_FILE_LOCK_CODES: Set<string>;
+/**
+ * libsql 0.5.x leaves prepared-statement handles alive until garbage collection.
+ * Collect them before Windows file swaps/removals that require exclusive access.
+ *
+ * Upstream: https://github.com/tursodatabase/libsql-js/issues/228
+ */
+export declare function collectReleasedSqliteHandles(): Promise<void>;
+/**
+ * Retries Windows file mutations while stable libsql releases native handles.
+ * The operation runs at most `maxRetries + 1` times: the initial attempt plus
+ * up to `maxRetries` retries. Non-lock errors and non-Windows platforms fail
+ * immediately. The default covers every entry in the delay table, matching the
+ * pre-parameter behavior exactly.
+ */
+export declare function withSqliteFileLockRetry<T>(operation: () => T | Promise<T>, maxRetries?: number): Promise<T>;

package/dist/services/turso/sqlite-handle-release.js

@@ -0,0 +1,56 @@
+const GC_PASSES = 3;
+const FILE_LOCK_RETRY_DELAYS_MS = [25, 50, 100, 200, 400, 800, 1600, 3200];
+export const RETRYABLE_FILE_LOCK_CODES = new Set(["EBUSY", "EPERM", "EACCES"]);
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * libsql 0.5.x leaves prepared-statement handles alive until garbage collection.
+ * Collect them before Windows file swaps/removals that require exclusive access.
+ *
+ * Upstream: https://github.com/tursodatabase/libsql-js/issues/228
+ */
+export async function collectReleasedSqliteHandles() {
+    if (process.platform !== "win32")
+        return;
+    const runtime = globalThis;
+    const bunGc = runtime.Bun?.gc;
+    const globalGc = runtime.gc;
+    if (!bunGc && !globalGc)
+        return;
+    for (let pass = 0; pass < GC_PASSES; pass += 1) {
+        bunGc?.(true);
+        globalGc?.();
+        await delay(0);
+    }
+}
+/**
+ * Retries Windows file mutations while stable libsql releases native handles.
+ * The operation runs at most `maxRetries + 1` times: the initial attempt plus
+ * up to `maxRetries` retries. Non-lock errors and non-Windows platforms fail
+ * immediately. The default covers every entry in the delay table, matching the
+ * pre-parameter behavior exactly.
+ */
+export async function withSqliteFileLockRetry(operation, maxRetries = FILE_LOCK_RETRY_DELAYS_MS.length) {
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+        throw new TypeError("maxRetries must be a non-negative integer");
+    }
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const code = error?.code;
+            const retryDelay = FILE_LOCK_RETRY_DELAYS_MS[attempt];
+            if (process.platform !== "win32" ||
+                !code ||
+                !RETRYABLE_FILE_LOCK_CODES.has(code) ||
+                retryDelay === undefined ||
+                attempt >= maxRetries) {
+                throw error;
+            }
+            await collectReleasedSqliteHandles();
+            await delay(retryDelay);
+        }
+    }
+}

package/dist/services/turso/turso-db.d.ts

@@ -0,0 +1,18 @@
+import type { Client, InArgs, ResultSet, Transaction } from "@libsql/client";
+type Row = Record<string, unknown>;
+export declare class TursoDb {
+    private readonly client;
+    constructor(client: Client);
+    getClient(): Client;
+    execute(sql: string, args?: InArgs): Promise<ResultSet>;
+    batch(statements: Array<{
+        sql: string;
+        args?: InArgs;
+    }>, mode?: "write" | "read"): Promise<ResultSet[]>;
+    get<T extends Row = Row>(sql: string, args?: InArgs): Promise<T | null>;
+    all<T extends Row = Row>(sql: string, args?: InArgs): Promise<T[]>;
+    run(sql: string, args?: InArgs): Promise<number>;
+    transaction<T>(mode: "write" | "read", fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export {};

package/dist/services/turso/turso-db.js

@@ -0,0 +1,53 @@
+export class TursoDb {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    getClient() {
+        return this.client;
+    }
+    async execute(sql, args) {
+        return this.client.execute({ sql, args: args ?? [] });
+    }
+    async batch(statements, mode = "write") {
+        return this.client.batch(statements.map((statement) => ({
+            sql: statement.sql,
+            args: statement.args ?? [],
+        })), mode);
+    }
+    async get(sql, args) {
+        const result = await this.execute(sql, args);
+        return result.rows[0] ?? null;
+    }
+    async all(sql, args) {
+        const result = await this.execute(sql, args);
+        return result.rows;
+    }
+    async run(sql, args) {
+        const result = await this.execute(sql, args);
+        return Number(result.rowsAffected ?? 0);
+    }
+    async transaction(mode, fn) {
+        const tx = await this.client.transaction(mode);
+        try {
+            const value = await fn(tx);
+            await tx.commit();
+            return value;
+        }
+        catch (error) {
+            try {
+                await tx.rollback();
+            }
+            catch {
+                // ignore rollback errors after a failed statement / already-closed tx
+            }
+            throw error;
+        }
+        finally {
+            tx.close();
+        }
+    }
+    async close() {
+        this.client.close();
+    }
+}