@ryanstark24/sfgraph-core 1.1.0

package/dist/storage/sqlite/load-better-sqlite3.js

@@ -0,0 +1,188 @@
+/**
+ * Centralized loader for `better-sqlite3` that converts the cryptic native
+ * "NODE_MODULE_VERSION X / was compiled against Y" runtime error into a
+ * `SfgraphError(E_NATIVE_ABI_MISMATCH, ...)` with actionable, copy-paste
+ * recovery commands.
+ *
+ * The most common cause is an IDE-spawned MCP child running a different Node
+ * binary than the shell that did `pnpm install` / `pnpm rebuild`. Cursor and
+ * VS Code ship their own Node; if the shell Node ABI differs, the prebuilt
+ * binding loaded into the IDE child fails to dlopen.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { ErrorCode, SfgraphError } from "@ryanstark24/sfgraph-shared";
+/** ABI mismatch detection heuristic. Matches the V8 / Node-API messages
+ *  produced when the loaded `.node` file was compiled against a different
+ *  NODE_MODULE_VERSION than the running process. */
+export function isAbiMismatch(message) {
+    return (/NODE_MODULE_VERSION/.test(message) ||
+        /was compiled against a different Node\.?js version/i.test(message) ||
+        /Module did not self-register/i.test(message));
+}
+function detectPackageManager() {
+    const ua = process.env.npm_config_user_agent ?? "";
+    if (/pnpm/.test(ua))
+        return { pm: "pnpm", rebuildCmd: "pnpm rebuild better-sqlite3" };
+    if (/yarn/.test(ua))
+        return { pm: "yarn", rebuildCmd: "yarn rebuild better-sqlite3" };
+    if (/bun/.test(ua))
+        return { pm: "bun", rebuildCmd: "bun pm rebuild better-sqlite3" };
+    if (/npm/.test(ua))
+        return { pm: "npm", rebuildCmd: "npm rebuild better-sqlite3" };
+    return { pm: "unknown", rebuildCmd: "npm rebuild better-sqlite3" };
+}
+/** Attempt to locate the resolved path of the better-sqlite3 binding for
+ *  diagnostics. Returns null on failure — never throws. */
+function resolveBindingPath(requireFn) {
+    try {
+        // require.resolve isn't directly typed on the Loader; round-trip via the
+        // module record.
+        const mod = requireFn("better-sqlite3");
+        void mod; // touch to ensure load succeeded; caller already handles that path
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatAbiMismatchMessage(original, hint, bindingPath) {
+    const lines = [
+        "Failed to load native module `better-sqlite3` — ABI mismatch.",
+        "",
+        `  Node:           ${process.version}  (ABI / NODE_MODULE_VERSION: ${process.versions.modules})`,
+        `  exec path:      ${process.execPath}`,
+    ];
+    if (bindingPath)
+        lines.push(`  binding path:   ${bindingPath}`);
+    lines.push("", "  Underlying error:", `    ${original.message.split("\n")[0]}`, "", "  Recovery:", `    ${hint.rebuildCmd}`, "", "  Note: when the MCP server is spawned by an IDE (Cursor, VS Code, Claude", "  Desktop), the IDE may use a different Node binary than your shell.", "  If `sfgraph doctor` reports a mismatch, re-run the rebuild using the", "  IDE's Node (or pin an absolute node path via `sfgraph install --local", "  --pin-node <path>`).");
+    return lines.join("\n");
+}
+/**
+ * If `err` is a native-binding ABI mismatch (matched by `isAbiMismatch`),
+ * convert it to a `SfgraphError(E_NATIVE_ABI_MISMATCH, ...)` with the
+ * full diagnostic message and recovery commands. Otherwise return null
+ * (caller should rethrow the original).
+ *
+ * Use this around `new Database(...)` calls or in `catch` blocks where
+ * `import Database from "better-sqlite3"` was used statically (the binding
+ * load is deferred until the first construction in some Node versions).
+ */
+export function wrapAbiError(err) {
+    if (!(err instanceof Error))
+        return null;
+    if (!isAbiMismatch(err.message))
+        return null;
+    const hint = detectPackageManager();
+    return new SfgraphError(ErrorCode.E_NATIVE_ABI_MISMATCH, formatAbiMismatchMessage(err, hint, null), { cause: err });
+}
+/**
+ * Locate the better-sqlite3 package directory (where package.json lives)
+ * by resolving the module entry and walking up. Returns null on failure —
+ * the auto-rebuild path then falls through to the manual error.
+ */
+function locateBetterSqlite3Dir(req) {
+    try {
+        if (typeof req.resolve !== "function")
+            return null;
+        let dir = path.dirname(req.resolve("better-sqlite3"));
+        // Walk up until we find package.json with the right name. The require.resolve
+        // typically lands inside lib/, so 1-3 levels of ".." gets us there.
+        for (let i = 0; i < 6; i++) {
+            const pkg = path.join(dir, "package.json");
+            if (existsSync(pkg))
+                return dir;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compile better-sqlite3 from source against the currently-running Node.
+ * Uses the package's own `build-release` npm script, which invokes node-gyp
+ * with the right target. process.execPath is inherited via env so node-gyp
+ * targets THIS node, not whatever is on PATH.
+ *
+ * Returns true on success. Prints progress to stderr so the user sees
+ * what's happening — a 20-30 second rebuild can otherwise look like a
+ * hang.
+ */
+function rebuildBetterSqlite3(pkgDir) {
+    process.stderr.write(`\nsfgraph: better-sqlite3 native binding doesn't match Node ${process.version} — rebuilding from source…\n`);
+    const result = spawnSync("npm", ["run", "build-release"], {
+        cwd: pkgDir,
+        stdio: ["ignore", "ignore", "inherit"],
+        env: {
+            ...process.env,
+            // Ensure node-gyp targets the running Node, not whatever default it
+            // would pick up from PATH.
+            npm_config_target: process.versions.node,
+            npm_config_runtime: "node",
+            npm_config_target_arch: process.arch,
+            npm_config_target_platform: process.platform,
+        },
+    });
+    if (result.status === 0) {
+        process.stderr.write("sfgraph: rebuild succeeded — retrying load.\n");
+        return true;
+    }
+    process.stderr.write("sfgraph: rebuild failed; falling back to manual remediation.\n");
+    return false;
+}
+/**
+ * Load `better-sqlite3` via the provided `require` (or one we synthesize from
+ * import.meta.url). On ABI mismatch:
+ *   - if `autoRebuild` is true, attempt a from-source rebuild against the
+ *     currently-running Node and retry the load. This eliminates the
+ *     "two Nodes on PATH" foot-gun for nvm + Homebrew users.
+ *   - otherwise (or if the rebuild fails), throw
+ *     `SfgraphError(E_NATIVE_ABI_MISMATCH)` with copy-paste recovery.
+ * On any other failure, rethrow as-is.
+ */
+export function loadBetterSqlite3(requireFn, opts = {}) {
+    const req = requireFn ?? createRequire(import.meta.url);
+    try {
+        return req("better-sqlite3");
+    }
+    catch (e) {
+        const err = e;
+        if (!isAbiMismatch(err.message))
+            throw err;
+        if (opts.autoRebuild) {
+            const pkgDir = locateBetterSqlite3Dir(req);
+            if (pkgDir && rebuildBetterSqlite3(pkgDir)) {
+                // Bust the require cache so the next call re-dlopens the freshly
+                // compiled .node file instead of reusing the in-memory failed module.
+                try {
+                    const r = req;
+                    if (r.cache && r.resolve) {
+                        const k = r.resolve("better-sqlite3");
+                        delete r.cache[k];
+                    }
+                }
+                catch {
+                    /* best effort */
+                }
+                try {
+                    return req("better-sqlite3");
+                }
+                catch (retryErr) {
+                    // Fall through to the formatted error below.
+                    err.message = `${err.message}\n\nretry after rebuild also failed: ${retryErr.message}`;
+                }
+            }
+        }
+        const hint = detectPackageManager();
+        const bindingPath = resolveBindingPath(req);
+        throw new SfgraphError(ErrorCode.E_NATIVE_ABI_MISMATCH, formatAbiMismatchMessage(err, hint, bindingPath), { cause: err });
+    }
+}
+//# sourceMappingURL=load-better-sqlite3.js.map

package/dist/storage/sqlite/load-better-sqlite3.js.map

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

package/dist/storage/sqlite/migrations.d.ts

@@ -0,0 +1,18 @@
+import type { BetterSqlite3Database, Migration } from "../interfaces.js";
+export declare const MIGRATIONS: Migration[];
+export interface MigrationRunnerOpts {
+    backupDir: string;
+    retainBackups: number;
+}
+export declare class MigrationRunner {
+    private readonly db;
+    private readonly migrations;
+    private readonly opts;
+    constructor(db: BetterSqlite3Database, migrations: Migration[], opts: MigrationRunnerOpts);
+    private getCurrentVersion;
+    private validateRegistry;
+    private backup;
+    private rotateBackups;
+    applyPending(): void;
+}
+//# sourceMappingURL=migrations.d.ts.map

package/dist/storage/sqlite/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/migrations.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEzE,eAAO,MAAM,UAAU,EAAE,SAAS,EAwMjC,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAFJ,EAAE,EAAE,qBAAqB,EACzB,UAAU,EAAE,SAAS,EAAE,EACvB,IAAI,EAAE,mBAAmB;IAG5C,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,aAAa;IAqBrB,YAAY,IAAI,IAAI;CAsBrB"}

package/dist/storage/sqlite/migrations.js

@@ -0,0 +1,291 @@
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import { MigrationError } from "@ryanstark24/sfgraph-shared";
+import * as sqliteVec from "sqlite-vec";
+export const MIGRATIONS = [
+    {
+        version: 1,
+        description: "initial registry + snapshot tables",
+        up(db) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS _sfgraph_schema_version (
+          version INTEGER PRIMARY KEY,
+          applied_at INTEGER NOT NULL,
+          description TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS _sfgraph_orgs (
+          id TEXT PRIMARY KEY,
+          alias TEXT NOT NULL,
+          instance_url TEXT NOT NULL,
+          api_version TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS _sfgraph_node_labels (
+          label TEXT PRIMARY KEY,
+          table_name TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS _sfgraph_edge_types (
+          rel_type TEXT PRIMARY KEY,
+          table_name TEXT NOT NULL,
+          created_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS _sfgraph_snapshots (
+          id TEXT PRIMARY KEY,
+          org_id TEXT NOT NULL,
+          label TEXT NOT NULL,
+          created_at INTEGER NOT NULL,
+          is_auto INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS _sfgraph_snapshots_org_created
+          ON _sfgraph_snapshots(org_id, created_at);
+        CREATE TABLE IF NOT EXISTS _sfgraph_node_snapshots (
+          snapshot_id TEXT NOT NULL,
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          label TEXT NOT NULL,
+          attributes TEXT NOT NULL,
+          source_hash TEXT NOT NULL,
+          first_seen_at INTEGER NOT NULL,
+          last_seen_at INTEGER NOT NULL,
+          last_modified_at INTEGER NOT NULL,
+          PRIMARY KEY(snapshot_id, org_id, qualified_name)
+        );
+        CREATE TABLE IF NOT EXISTS _sfgraph_edge_snapshots (
+          snapshot_id TEXT NOT NULL,
+          org_id TEXT NOT NULL,
+          src_qname TEXT NOT NULL,
+          dst_qname TEXT NOT NULL,
+          rel_type TEXT NOT NULL,
+          attributes TEXT NOT NULL,
+          first_seen_at INTEGER NOT NULL,
+          last_seen_at INTEGER NOT NULL,
+          PRIMARY KEY(snapshot_id, org_id, src_qname, dst_qname, rel_type)
+        );
+      `);
+        },
+    },
+    {
+        version: 2,
+        description: "node index lookup",
+        up(db) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS _sfgraph_node_index (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          label TEXT NOT NULL,
+          PRIMARY KEY(org_id, qualified_name)
+        );
+      `);
+        },
+    },
+    {
+        version: 4,
+        description: "org last_synced_at",
+        up(db) {
+            // SQLite forbids ALTER TABLE ADD COLUMN with a non-constant default; NULL is fine.
+            db.exec("ALTER TABLE _sfgraph_orgs ADD COLUMN last_synced_at INTEGER");
+        },
+    },
+    {
+        version: 5,
+        description: "phase 6 analysis tables (findings, dead-code, governor, test coverage)",
+        up(db) {
+            // NOTE: Spec called for PK using IFNULL(line,0) but SQLite doesn't allow
+            // expressions in PRIMARY KEY declarations. Divergence: store -1 sentinel
+            // for "no specific line" findings and include `line` as a plain PK column.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS _sfgraph_findings (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          rule_id TEXT NOT NULL,
+          line INTEGER NOT NULL DEFAULT -1,
+          severity TEXT NOT NULL,
+          message TEXT NOT NULL,
+          evidence TEXT,
+          computed_at INTEGER NOT NULL,
+          PRIMARY KEY(org_id, qualified_name, rule_id, line)
+        );
+        CREATE INDEX IF NOT EXISTS _sfgraph_findings_qname
+          ON _sfgraph_findings(org_id, qualified_name);
+        CREATE INDEX IF NOT EXISTS _sfgraph_findings_rule
+          ON _sfgraph_findings(org_id, rule_id, severity);
+
+        CREATE TABLE IF NOT EXISTS _sfgraph_dead_code_scores (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          score REAL NOT NULL,
+          confidence TEXT NOT NULL,
+          reasons TEXT NOT NULL,
+          computed_at INTEGER NOT NULL,
+          PRIMARY KEY(org_id, qualified_name)
+        );
+        CREATE INDEX IF NOT EXISTS _sfgraph_dead_code_conf
+          ON _sfgraph_dead_code_scores(org_id, confidence, score);
+
+        CREATE TABLE IF NOT EXISTS _sfgraph_governor_risks (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          risk_type TEXT NOT NULL,
+          evidence TEXT,
+          line INTEGER NOT NULL DEFAULT -1,
+          computed_at INTEGER NOT NULL,
+          PRIMARY KEY(org_id, qualified_name, risk_type, line)
+        );
+        CREATE INDEX IF NOT EXISTS _sfgraph_governor_type
+          ON _sfgraph_governor_risks(org_id, risk_type);
+
+        CREATE TABLE IF NOT EXISTS _sfgraph_test_coverage (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          test_count INTEGER NOT NULL,
+          computed_at INTEGER NOT NULL,
+          PRIMARY KEY(org_id, qualified_name)
+        );
+        CREATE INDEX IF NOT EXISTS _sfgraph_test_coverage_low
+          ON _sfgraph_test_coverage(org_id, test_count);
+      `);
+        },
+    },
+    {
+        version: 6,
+        description: "snippet store (source text + lazy LLM explanations)",
+        up(db) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS _sfgraph_snippets (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          source_format TEXT NOT NULL,
+          source_text TEXT NOT NULL,
+          start_line INTEGER,
+          end_line INTEGER,
+          source_hash TEXT NOT NULL,
+          llm_explanation TEXT,
+          explained_at INTEGER,
+          PRIMARY KEY (org_id, qualified_name)
+        );
+        CREATE INDEX IF NOT EXISTS idx_snippets_org ON _sfgraph_snippets (org_id);
+      `);
+        },
+    },
+    {
+        version: 3,
+        description: "vector tables (sqlite-vec)",
+        up(db) {
+            sqliteVec.load(db);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS _sfgraph_node_vector_meta (
+          org_id TEXT NOT NULL,
+          qualified_name TEXT NOT NULL,
+          content_hash TEXT NOT NULL,
+          label TEXT NOT NULL,
+          vec_rowid INTEGER NOT NULL,
+          PRIMARY KEY(org_id, qualified_name)
+        );
+        CREATE INDEX IF NOT EXISTS _sfgraph_node_vector_meta_hash
+          ON _sfgraph_node_vector_meta(content_hash);
+        CREATE TABLE IF NOT EXISTS _sfgraph_bundle_vector_meta (
+          org_id TEXT NOT NULL,
+          bundle_id TEXT NOT NULL,
+          content_hash TEXT NOT NULL,
+          vec_rowid INTEGER NOT NULL,
+          PRIMARY KEY(org_id, bundle_id)
+        );
+        CREATE VIRTUAL TABLE IF NOT EXISTS _sfgraph_node_vectors USING vec0(
+          org_id TEXT PARTITION KEY,
+          embedding float[384]
+        );
+        CREATE VIRTUAL TABLE IF NOT EXISTS _sfgraph_bundle_vectors USING vec0(
+          org_id TEXT PARTITION KEY,
+          embedding float[384]
+        );
+      `);
+        },
+    },
+];
+export class MigrationRunner {
+    db;
+    migrations;
+    opts;
+    constructor(db, migrations, opts) {
+        this.db = db;
+        this.migrations = migrations;
+        this.opts = opts;
+    }
+    getCurrentVersion() {
+        const row = this.db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='_sfgraph_schema_version'")
+            .get();
+        if (!row)
+            return 0;
+        const r = this.db.prepare("SELECT MAX(version) AS v FROM _sfgraph_schema_version").get();
+        return r?.v ?? 0;
+    }
+    validateRegistry() {
+        const seen = new Set();
+        for (const m of this.migrations) {
+            if (seen.has(m.version)) {
+                throw new MigrationError(`SF_DUPLICATE_MIGRATION: duplicate migration version ${m.version}`);
+            }
+            seen.add(m.version);
+        }
+    }
+    backup(currentVersion) {
+        const dbName = this.db.name;
+        if (!dbName || dbName === ":memory:" || dbName === "")
+            return;
+        if (!existsSync(this.opts.backupDir)) {
+            mkdirSync(this.opts.backupDir, { recursive: true });
+        }
+        const ts = Date.now();
+        const base = path.basename(dbName);
+        const dest = path.join(this.opts.backupDir, `${base}.v${currentVersion}.${ts}.sqlite`);
+        // better-sqlite3 backup is async; use VACUUM INTO for a sync snapshot.
+        this.db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+        this.rotateBackups();
+    }
+    rotateBackups() {
+        if (!existsSync(this.opts.backupDir))
+            return;
+        const entries = readdirSync(this.opts.backupDir)
+            .filter((f) => f.endsWith(".sqlite"))
+            .map((f) => {
+            const full = path.join(this.opts.backupDir, f);
+            return { full, mtime: statSync(full).mtimeMs };
+        })
+            .sort((a, b) => b.mtime - a.mtime);
+        for (let i = this.opts.retainBackups; i < entries.length; i += 1) {
+            const entry = entries[i];
+            if (entry) {
+                try {
+                    unlinkSync(entry.full);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+    applyPending() {
+        this.validateRegistry();
+        const sorted = [...this.migrations].sort((a, b) => a.version - b.version);
+        let current = this.getCurrentVersion();
+        for (const m of sorted) {
+            if (m.version <= current)
+                continue;
+            // Only back up if there's prior state worth preserving.
+            if (current > 0) {
+                this.backup(current);
+            }
+            const apply = this.db.transaction(() => {
+                m.up(this.db);
+                this.db
+                    .prepare("INSERT INTO _sfgraph_schema_version(version, applied_at, description) VALUES (?, ?, ?)")
+                    .run(m.version, Date.now(), m.description);
+            });
+            apply();
+            current = m.version;
+        }
+    }
+}
+//# sourceMappingURL=migrations.js.map

package/dist/storage/sqlite/migrations.js.map

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

package/dist/storage/sqlite/snapshot-store.d.ts

@@ -0,0 +1,31 @@
+import type { OrgId, QualifiedName, Sha256 } from "@ryanstark24/sfgraph-shared";
+import type { Snapshot } from "../../domain/index.js";
+import type { BetterSqlite3Database, EdgeDiff, NodeDiff, SnapshotStore } from "../interfaces.js";
+export interface SqliteSnapshotStoreOptions {
+    dbPath: string;
+    backupDir?: string;
+    retainBackups?: number;
+    db?: BetterSqlite3Database;
+    skipMigrations?: boolean;
+}
+export declare class SqliteSnapshotStore implements SnapshotStore {
+    readonly db: BetterSqlite3Database;
+    private readonly ownsDb;
+    private readonly opts;
+    private initialized;
+    constructor(opts: SqliteSnapshotStoreOptions);
+    init(): Promise<void>;
+    private getNodeLabelTables;
+    private getEdgeRelTables;
+    createSnapshot(orgId: OrgId, label: string, isAuto: boolean): Snapshot;
+    listSnapshots(orgId: OrgId): Snapshot[];
+    getSnapshot(id: string): Snapshot | null;
+    deleteSnapshot(id: string): void;
+    private readNodes;
+    private readEdges;
+    diffNodes(orgId: OrgId, fromId: string | "current", toId: string | "current"): NodeDiff;
+    diffEdges(orgId: OrgId, fromId: string | "current", toId: string | "current"): EdgeDiff;
+    prune(orgId: OrgId, retainDays: number): number;
+}
+export type { QualifiedName, Sha256 };
+//# sourceMappingURL=snapshot-store.d.ts.map

package/dist/storage/sqlite/snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/snapshot-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAEhF,OAAO,KAAK,EAA+B,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAIjG,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,qBAAqB,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAkED,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,EAAE,EAAE,qBAAqB,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,WAAW,CAAS;gBAEhB,IAAI,EAAE,0BAA0B;IAqBtC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,gBAAgB;IASxB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ;IAoCtE,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,EAAE;IASvC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAOxC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAShC,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,SAAS;IA6BjB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ;IAuBvF,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ;IAgBvF,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAUhD;AAGD,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC"}