homegraph 1.2.0 → 1.5.0

package/dist/db/sqlite-adapter.js

@@ -2,39 +2,152 @@
 /**
  * SQLite Adapter
  *
- * Thin wrapper over Node's built-in `node:sqlite` (`DatabaseSync`), exposed
- * through a small better-sqlite3-shaped interface so the rest of the codebase
- * is storage-agnostic.
+ * Three-tier selection (first success wins):
+ *   1. `node:sqlite` (`DatabaseSync`) — real SQLite + WAL + FTS5, Node ≥22.5
+ *   2. `better-sqlite3` — native addon (optionalDependency)
+ *   3. `node-sqlite3-wasm` — last-resort fallback (no WAL; slower / lock-prone)
  *
- * HomeGraph ships with a bundled Node runtime, so `node:sqlite` (real SQLite,
- * with WAL + FTS5) is always available — there is no native build step and no
- * wasm fallback. When run from source instead, it requires Node >= 22.5.
+ * Library hosts on Node 20–22.4 land on (2) or (3). Node ≥22.5 prefers (1) and
+ * skips the native build. Override with `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|native|wasm`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WASM_FALLBACK_FIX_RECIPE = void 0;
+exports.buildWasmFallbackBanner = buildWasmFallbackBanner;
+exports.isNodeSqliteAvailable = isNodeSqliteAvailable;
+exports.isNativeSqliteAvailable = isNativeSqliteAvailable;
 exports.createDatabase = createDatabase;
+/**
+ * One-line recovery hint when WASM is active (no WAL — slower / lock-prone).
+ */
+exports.WASM_FALLBACK_FIX_RECIPE = 'upgrade to Node.js 22.5+ (uses built-in node:sqlite), or ' +
+    '`xcode-select --install` (macOS) / `apt install build-essential` (Debian/Ubuntu) ' +
+    'then `npm rebuild better-sqlite3`.';
+/**
+ * Banner shown to stderr when falling back to WASM.
+ */
+function buildWasmFallbackBanner(priorErrors) {
+    const sep = '─'.repeat(72);
+    const lines = [
+        sep,
+        '[HomeGraph] WASM SQLite fallback active (node:sqlite + better-sqlite3 unavailable)',
+        sep,
+        'Indexing and sync will be 5-10x slower than a WAL backend, and concurrent',
+        'reads can hit "database is locked". Prefer Node 22.5+ or better-sqlite3.',
+        '',
+        'Fix — use built-in SQLite (best when you can):',
+        '  Use Node.js 22.5 or newer, then restart homegraph',
+        '',
+        'Fix — native better-sqlite3:',
+        '  macOS:  xcode-select --install && npm rebuild better-sqlite3',
+        '  Linux:  sudo apt install build-essential python3 make && npm rebuild better-sqlite3',
+        '  Any:    npm install better-sqlite3 --save',
+        '',
+        'Verify after fix: `homegraph status` should show Backend: node-sqlite or native.',
+    ];
+    if (priorErrors) {
+        lines.push('', `Prior load errors: ${priorErrors}`);
+    }
+    lines.push(sep);
+    return lines.join('\n');
+}
+function translateNamedParams(sql) {
+    const paramOrder = [];
+    const rewritten = sql.replace(/@(\w+)/g, (_match, name) => {
+        paramOrder.push(name);
+        return '?';
+    });
+    if (paramOrder.length === 0) {
+        return { sql, paramOrder: null };
+    }
+    return { sql: rewritten, paramOrder };
+}
+function resolveParams(params, paramOrder) {
+    if (params.length === 0)
+        return undefined;
+    if (paramOrder &&
+        params.length === 1 &&
+        params[0] !== null &&
+        typeof params[0] === 'object' &&
+        !Array.isArray(params[0]) &&
+        !(params[0] instanceof Buffer) &&
+        !(params[0] instanceof Uint8Array)) {
+        const obj = params[0];
+        return paramOrder.map(name => obj[name]);
+    }
+    if (params.length === 1)
+        return params[0];
+    return params;
+}
+function isBusyError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return /SQLITE_BUSY|database is locked/i.test(msg);
+}
+function sleepSync(ms) {
+    try {
+        const sab = new SharedArrayBuffer(4);
+        const ia = new Int32Array(sab);
+        Atomics.wait(ia, 0, 0, ms);
+    }
+    catch {
+        const end = Date.now() + ms;
+        while (Date.now() < end) {
+            /* busy-wait */
+        }
+    }
+}
+function withBusyRetry(fn, attempts = 10, baseDelayMs = 50) {
+    let last;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            last = error;
+            if (!isBusyError(error) || i === attempts - 1)
+                throw error;
+            sleepSync(baseDelayMs * (i + 1));
+        }
+    }
+    throw last;
+}
+/** True when `require('node:sqlite').DatabaseSync` succeeds. */
+function isNodeSqliteAvailable() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require('node:sqlite');
+        return typeof mod?.DatabaseSync === 'function';
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `require('better-sqlite3')` succeeds. */
+function isNativeSqliteAvailable() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        require('better-sqlite3');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Wraps Node's built-in `node:sqlite` (`DatabaseSync`) to match the
  * better-sqlite3 interface the rest of the code expects.
- *
- * node:sqlite is real SQLite compiled into Node, so it supports WAL, FTS5,
- * mmap, and `@named` params natively — the only shims needed are the
- * better-sqlite3 conveniences node:sqlite omits: a `.pragma()` helper, a
- * `.transaction()` helper, and `open` (node:sqlite exposes `isOpen`).
  */
 class NodeSqliteAdapter {
     _db;
-    constructor(dbPath) {
+    _txDepth = 0;
+    constructor(dbPath, opts) {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { DatabaseSync } = require('node:sqlite');
-        this._db = new DatabaseSync(dbPath);
+        this._db = opts?.readOnly ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
     }
     get open() {
         return this._db.isOpen;
     }
     prepare(sql) {
-        // node:sqlite matches better-sqlite3's calling convention (variadic
-        // positional args, or a single object for @named params), so params forward
-        // through unchanged.
         const stmt = this._db.prepare(sql);
         return {
             run(...params) {
@@ -60,14 +173,10 @@ class NodeSqliteAdapter {
     }
     pragma(str, options) {
         const trimmed = str.trim();
-        // Write pragma ("key = value"): node:sqlite is real SQLite, so every pragma
-        // (WAL, mmap, synchronous, …) applies as-is.
         if (trimmed.includes('=')) {
             this._db.exec(`PRAGMA ${trimmed}`);
             return;
         }
-        // Read pragma. Default: the row object (e.g. { journal_mode: 'wal' }).
-        // `{ simple: true }` returns just the single column value, like better-sqlite3.
         const row = this._db.prepare(`PRAGMA ${trimmed}`).get();
         if (options?.simple) {
             return row && typeof row === 'object' ? Object.values(row)[0] : row;
@@ -76,42 +185,189 @@ class NodeSqliteAdapter {
     }
     transaction(fn) {
         return (...args) => {
+            if (this._txDepth > 0) {
+                this._txDepth++;
+                try {
+                    return fn(...args);
+                }
+                finally {
+                    this._txDepth--;
+                }
+            }
             this._db.exec('BEGIN');
+            this._txDepth = 1;
             try {
                 const result = fn(...args);
                 this._db.exec('COMMIT');
+                this._txDepth = 0;
                 return result;
             }
             catch (error) {
                 this._db.exec('ROLLBACK');
+                this._txDepth = 0;
                 throw error;
             }
         };
     }
     close() {
-        // node:sqlite's DatabaseSync.close() throws if already closed; make it
-        // idempotent to match better-sqlite3 (callers may close more than once).
         if (this._db.isOpen)
             this._db.close();
     }
 }
-/**
- * Create a database connection backed by `node:sqlite`.
- *
- * Returns the active backend alongside the db so each `DatabaseConnection` can
- * report it per-instance — MCP can open multiple project DBs in one process, so
- * a process-global would race.
- */
-function createDatabase(dbPath) {
+class WasmDatabaseAdapter {
+    _db;
+    _openStmts = new Set();
+    _txDepth = 0;
+    constructor(dbPath, opts) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Database } = require('node-sqlite3-wasm');
+        this._db = opts?.readOnly ? new Database(dbPath, 'readonly') : new Database(dbPath);
+    }
+    get open() {
+        return this._db.isOpen;
+    }
+    prepare(sql) {
+        const { sql: rewrittenSql, paramOrder } = translateNamedParams(sql);
+        const stmt = this._db.prepare(rewrittenSql);
+        this._openStmts.add(stmt);
+        return {
+            run(...params) {
+                const resolved = resolveParams(params, paramOrder);
+                const result = resolved !== undefined ? stmt.run(resolved) : stmt.run();
+                return {
+                    changes: result?.changes ?? 0,
+                    lastInsertRowid: result?.lastInsertRowid ?? 0,
+                };
+            },
+            get(...params) {
+                const resolved = resolveParams(params, paramOrder);
+                return withBusyRetry(() => resolved !== undefined ? stmt.get(resolved) : stmt.get());
+            },
+            all(...params) {
+                const resolved = resolveParams(params, paramOrder);
+                return withBusyRetry(() => resolved !== undefined ? stmt.all(resolved) : stmt.all());
+            },
+            iterate(...params) {
+                const resolved = resolveParams(params, paramOrder);
+                if (typeof stmt.iterate === 'function') {
+                    return withBusyRetry(() => resolved !== undefined ? stmt.iterate(resolved) : stmt.iterate());
+                }
+                const rows = withBusyRetry(() => resolved !== undefined ? stmt.all(resolved) : stmt.all());
+                return rows[Symbol.iterator]();
+            },
+        };
+    }
+    exec(sql) {
+        this._db.exec(sql);
+    }
+    pragma(str, options) {
+        const trimmed = str.trim();
+        if (trimmed.includes('=')) {
+            const eqIdx = trimmed.indexOf('=');
+            const key = trimmed.substring(0, eqIdx).trim();
+            const value = trimmed.substring(eqIdx + 1).trim();
+            if (key === 'journal_mode' && value.toUpperCase() === 'WAL') {
+                this._db.exec('PRAGMA journal_mode = DELETE');
+                return;
+            }
+            if (key === 'mmap_size')
+                return;
+            if (key === 'synchronous' && value.toUpperCase() === 'NORMAL') {
+                this._db.exec('PRAGMA synchronous = FULL');
+                return;
+            }
+            this._db.exec(`PRAGMA ${key} = ${value}`);
+            return;
+        }
+        const readStmt = this._db.prepare(`PRAGMA ${trimmed}`);
+        const result = readStmt.get();
+        readStmt.finalize();
+        if (options?.simple) {
+            return result && typeof result === 'object' ? Object.values(result)[0] : result;
+        }
+        return result;
+    }
+    transaction(fn) {
+        return (...args) => {
+            if (this._txDepth > 0) {
+                this._txDepth++;
+                try {
+                    return fn(...args);
+                }
+                finally {
+                    this._txDepth--;
+                }
+            }
+            this._db.exec('BEGIN');
+            this._txDepth = 1;
+            try {
+                const result = fn(...args);
+                this._db.exec('COMMIT');
+                this._txDepth = 0;
+                return result;
+            }
+            catch (error) {
+                this._db.exec('ROLLBACK');
+                this._txDepth = 0;
+                throw error;
+            }
+        };
+    }
+    close() {
+        for (const stmt of this._openStmts) {
+            try {
+                stmt.finalize();
+            }
+            catch {
+                /* already finalized */
+            }
+        }
+        this._openStmts.clear();
+        this._db.close();
+    }
+}
+function resolveBackendOrder() {
+    const raw = process.env.HOMEGRAPH_SQLITE_BACKEND?.trim().toLowerCase();
+    if (raw === 'node-sqlite' || raw === 'native' || raw === 'wasm') {
+        return [raw];
+    }
+    return ['node-sqlite', 'native', 'wasm'];
+}
+function tryOpenBackend(backend, dbPath, opts) {
     try {
-        return { db: new NodeSqliteAdapter(dbPath), backend: 'node-sqlite' };
+        if (backend === 'node-sqlite') {
+            return { db: new NodeSqliteAdapter(dbPath, opts), backend: 'node-sqlite' };
+        }
+        if (backend === 'native') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const Database = require('better-sqlite3');
+            const db = opts?.readOnly ? new Database(dbPath, { readonly: true }) : new Database(dbPath);
+            return { db: db, backend: 'native' };
+        }
+        return { db: new WasmDatabaseAdapter(dbPath, opts), backend: 'wasm' };
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        throw new Error('Failed to open SQLite via the built-in node:sqlite module.\n' +
-            'HomeGraph requires node:sqlite (Node.js 22.5+). Install the self-contained\n' +
-            'HomeGraph release (it bundles a compatible Node), or run on Node 22.5+.\n' +
-            `Underlying error: ${msg}`);
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Create a database connection.
+ * Order: node:sqlite → better-sqlite3 → node-sqlite3-wasm (unless overridden).
+ */
+function createDatabase(dbPath, opts) {
+    const order = resolveBackendOrder();
+    const errors = [];
+    for (const backend of order) {
+        const result = tryOpenBackend(backend, dbPath, opts);
+        if ('db' in result) {
+            if (result.backend === 'wasm') {
+                console.warn(buildWasmFallbackBanner(errors.join(' | ') || undefined));
+            }
+            return result;
+        }
+        errors.push(`${backend}: ${result.error}`);
     }
+    throw new Error(`Failed to load any SQLite backend (tried ${order.join(' → ')}).\n` +
+        errors.map(e => `  ${e}`).join('\n'));
 }
 //# sourceMappingURL=sqlite-adapter.js.map

package/dist/db/sqlite-adapter.js.map

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

package/dist/db/wal-valve.d.ts

@@ -0,0 +1,119 @@
+/**
+ * WAL checkpoint valve — bounds WAL growth while auto-checkpointing is
+ * deferred during a bulk index (#1231).
+ *
+ * Why deferral: SQLite's default `wal_autocheckpoint` (1000 pages) re-writes
+ * hot B-tree/FTS pages into the main DB file over and over during a bulk
+ * index — measured at ~95% of ALL disk I/O, and the difference between 45s
+ * and 19+ minutes on HDD-class storage (150 random IOPS). Deferring
+ * checkpoints turns the store into pure sequential WAL appends; each backfill
+ * pass writes distinct pages once, in page order (≈ sequential).
+ *
+ * Why a valve: unbounded deferral is its own failure mode, both measured in
+ * the #1231 repro. The WAL duplicates hot pages per COMMIT, so it grows far
+ * faster than the DB (5.9GB WAL for a ~340MB DB on a 3.3k-file index) —
+ * filling the disk, and poisoning every subsequent read that must page
+ * through it (the first resolution-phase read blocked the main thread >60s
+ * and the #850 liveness watchdog killed the healthy index). The valve
+ * watches WAL growth on a timer and, past a soft threshold, backfills with
+ * `PRAGMA wal_checkpoint(PASSIVE)` on a worker-thread connection — PASSIVE
+ * never blocks the writer, and off-thread means the main thread (and the
+ * watchdog heartbeat) keep turning regardless of how long a backfill takes.
+ *
+ * The load-bearing subtlety: a WAL file's SIZE never shrinks. After a full
+ * backfill, the writer's next commit RESTARTS the WAL from the top and the
+ * frames recycle inside the same file — so raw size says nothing about the
+ * un-backfilled backlog, and a size-triggered valve degenerates into firing
+ * (and pausing the writer) forever once the file passes its threshold
+ * (measured: guava crawled at ~9min per 160 files). Instead the valve
+ * tracks `sizeAtLastFullBackfill` — refreshed whenever a checkpoint reports
+ * `log === checkpointed` (everything backfilled) — and triggers on GROWTH
+ * beyond that baseline, which only happens when genuinely un-backfilled
+ * frames push past the file's high-water mark.
+ *
+ * Backpressure: if the writer outruns the checkpointer past a hard cap of
+ * growth (2× soft), {@link backpressure} pauses the writer (at a safe,
+ * between-transactions boundary) until a FULL backfill lands. One in-flight
+ * pass is not enough: on a disk saturated by the writer, every concurrent
+ * PASSIVE pass is already stale by the time it finishes (the writer appended
+ * past its snapshot), so neither SQLite's WAL wrap nor the baseline ever
+ * trigger and the WAL grows without bound (measured: 5.9GB on guava at 150
+ * IOPS, then a >60s read stall and a watchdog kill). With the writer parked,
+ * the next pass covers everything, the WAL wraps on the following commit,
+ * and the pause is the disk's honest catch-up cost — the correct terminal
+ * mode when hardware genuinely can't keep up with the append rate.
+ */
+import type { DatabaseConnection } from './index';
+/**
+ * Resolve the valve's soft threshold from the `HOMEGRAPH_WAL_VALVE_MB`
+ * override; non-numeric / non-positive values fall back to the default.
+ */
+export declare function resolveWalValveMb(envVal: string | undefined, dbSizeBytes?: number): number;
+export declare class WalCheckpointValve {
+    private readonly db;
+    private readonly intervalMs;
+    private timer;
+    private inflight;
+    /** Writer pause in progress (hard cap breached): passes loop until a full backfill. */
+    private pause;
+    /**
+     * WAL file size observed when a checkpoint last reported the ENTIRE WAL
+     * backfilled. Growth is measured against this baseline — see the header
+     * comment for why absolute size cannot be used.
+     */
+    private sizeAtLastFullBackfill;
+    private readonly softBytes;
+    private readonly hardBytes;
+    private readonly fileCapBytes;
+    /**
+     * Futility latch: consecutive backfill give-ups (a reader pinning the WAL)
+     * disable further writer pauses for a cooldown, so a pinned phase degrades
+     * to the pre-valve behavior (unbounded WAL, folded when the pinner exits)
+     * instead of burning a 20-pass checkpoint attempt — each pass a worker
+     * thread + fresh connection — at EVERY over-cap boundary. That churn is
+     * what turned a pinned kernel-scale resolution from slow into OOM-killed
+     * (§7a.1 run 1: 22GB WAL, exit 137 at an envelope the pre-fix build
+     * survived).
+     */
+    private consecutiveGiveUps;
+    private futileUntil;
+    constructor(db: DatabaseConnection, softMb?: number, intervalMs?: number, log?: (msg: string) => void);
+    private readonly log;
+    private mb;
+    /** Un-backfilled growth estimate: bytes the WAL has grown past the last full backfill. */
+    private growthBytes;
+    /** Begin watching the WAL. Idempotent; the timer never holds the loop open. */
+    start(): void;
+    /** Stop watching. Any in-flight checkpoint keeps running — await drain(). */
+    stop(): void;
+    /** One poll: fire an off-thread passive checkpoint when growth passes the soft threshold. */
+    check(): void;
+    /**
+     * Writer-side backstop, called at a between-transactions boundary. Returns
+     * null (no wait) while growth is under the hard cap; past it, returns a
+     * promise that resolves only once a FULL backfill has landed — see the
+     * header comment for why a single pass is not enough on a saturated disk.
+     */
+    backpressure(): Promise<void> | null;
+    /** Await any in-flight checkpoint and writer pause. */
+    drain(): Promise<void>;
+    /**
+     * Phase-boundary fold: backfill the ENTIRE WAL now (off-thread, awaited).
+     * Called between bulk phases — e.g. after parsing, before resolution's
+     * first reads — so the next phase never pages a bulk-write-sized WAL on
+     * the main thread (the post-parse read against a multi-GB WAL is what
+     * blew the #850 watchdog's 60s window in the #1231 repro). The await
+     * keeps the event loop (and the watchdog heartbeat) turning.
+     */
+    foldNow(): Promise<void>;
+    /**
+     * With the writer parked on the returned promise, loop passive passes until
+     * one reports the entire WAL backfilled (typically the second: the first
+     * drains the pass that was already running against a stale snapshot). Gives
+     * up after a bounded number of passes — e.g. a reader pinning the WAL —
+     * because unbounded WAL growth degrades; a wedged writer never recovers.
+     */
+    private backfillFully;
+    private fire;
+}
+//# sourceMappingURL=wal-valve.d.ts.map

package/dist/db/wal-valve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal-valve.d.ts","sourceRoot":"","sources":["../../src/db/wal-valve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAalD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAc1F;AAED,qBAAa,kBAAkB;IA6B3B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAEnB,OAAO,CAAC,QAAQ,CAAC,UAAU;IA9B7B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAA8B;IAC9C,uFAAuF;IACvF,OAAO,CAAC,KAAK,CAA8B;IAC3C;;;;OAIG;IACH,OAAO,CAAC,sBAAsB,CAAK;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,WAAW,CAAK;gBAGL,EAAE,EAAE,kBAAkB,EACvC,MAAM,GAAE,MAA8D,EACrD,UAAU,GAAE,MAA0B,EACvD,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe;IAavC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAE5C,OAAO,CAAC,EAAE;IAIV,0FAA0F;IAC1F,OAAO,CAAC,WAAW;IAInB,+EAA+E;IAC/E,KAAK,IAAI,IAAI;IAkBb,6EAA6E;IAC7E,IAAI,IAAI,IAAI;IAOZ,6FAA6F;IAC7F,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAqBpC,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;;;;;OAMG;YACW,aAAa;IAkC3B,OAAO,CAAC,IAAI;CA8Bb"}