homegraph 1.4.1 → 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

@@ -48,11 +48,10 @@ 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): number;
+export declare function resolveWalValveMb(envVal: string | undefined, dbSizeBytes?: number): number;
 export declare class WalCheckpointValve {
     private readonly db;
     private readonly intervalMs;
-    private readonly log;
     private timer;
     private inflight;
     /** Writer pause in progress (hard cap breached): passes loop until a full backfill. */
@@ -65,7 +64,21 @@ export declare class WalCheckpointValve {
     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;

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

@@ -1 +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;AAWlD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMpE;AAED,qBAAa,kBAAkB;IAe3B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAEnB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAjBtB,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;gBAGhB,EAAE,EAAE,kBAAkB,EACvC,MAAM,GAAE,MAA8D,EACrD,UAAU,GAAE,MAA0B,EACtC,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe;IAMxD,OAAO,CAAC,EAAE;IAIV,0FAA0F;IAC1F,OAAO,CAAC,WAAW;IAInB,+EAA+E;IAC/E,KAAK,IAAI,IAAI;IAMb,6EAA6E;IAC7E,IAAI,IAAI,IAAI;IAOZ,6FAA6F;IAC7F,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAYpC,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;;;;;OAMG;YACW,aAAa;IAc3B,OAAO,CAAC,IAAI;CAoBb"}
+{"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"}

package/dist/db/wal-valve.js

@@ -51,6 +51,8 @@ exports.resolveWalValveMb = resolveWalValveMb;
 const DEFAULT_WAL_VALVE_MB = 256;
 /** Hard cap = this × soft threshold; past it the writer pauses for a full backfill. */
 const HARD_CAP_MULTIPLIER = 2;
+/** File cap = this × soft threshold; past it the barrier also TRUNCATEs the file. */
+const FILE_CAP_MULTIPLIER = 4;
 /** Passes attempted per writer pause before giving up (a pinned reader could stall forever). */
 const MAX_PAUSED_BACKFILL_PASSES = 20;
 /** How often the timer looks at the WAL file size. */
@@ -59,18 +61,25 @@ const CHECK_INTERVAL_MS = 2000;
  * Resolve the valve's soft threshold from the `HOMEGRAPH_WAL_VALVE_MB`
  * override; non-numeric / non-positive values fall back to the default.
  */
-function resolveWalValveMb(envVal) {
+function resolveWalValveMb(envVal, dbSizeBytes) {
     if (envVal !== undefined && envVal !== '') {
         const n = Number(envVal);
         if (Number.isFinite(n) && n > 0)
             return Math.floor(n);
     }
+    // Scale with the project when the caller knows the DB size: every fold
+    // re-writes hot B-tree pages into the main file (the #1231 pathology in
+    // bounded form — 111s of a kernel-scale batch loop at the flat 256MB cap,
+    // §7a.2), so a big project affords a proportionally bigger transient WAL
+    // (~dbSize/4 soft ⇒ file cap ≈ dbSize) in exchange for ~4× fewer folds.
+    if (dbSizeBytes !== undefined && dbSizeBytes > 0) {
+        return Math.min(2048, Math.max(DEFAULT_WAL_VALVE_MB, Math.floor(dbSizeBytes / 4 / (1024 * 1024))));
+    }
     return DEFAULT_WAL_VALVE_MB;
 }
 class WalCheckpointValve {
     db;
     intervalMs;
-    log;
     timer = null;
     inflight = null;
     /** Writer pause in progress (hard cap breached): passes loop until a full backfill. */
@@ -83,13 +92,33 @@ class WalCheckpointValve {
     sizeAtLastFullBackfill = 0;
     softBytes;
     hardBytes;
+    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).
+     */
+    consecutiveGiveUps = 0;
+    futileUntil = 0;
     constructor(db, softMb = resolveWalValveMb(process.env.HOMEGRAPH_WAL_VALVE_MB), intervalMs = CHECK_INTERVAL_MS, log = () => { }) {
         this.db = db;
         this.intervalMs = intervalMs;
-        this.log = log;
         this.softBytes = softMb * 1024 * 1024;
         this.hardBytes = this.softBytes * HARD_CAP_MULTIPLIER;
+        this.fileCapBytes = this.softBytes * FILE_CAP_MULTIPLIER;
+        // HOMEGRAPH_WAL_VALVE_DEBUG=1 surfaces valve decisions to stderr without
+        // needing the caller's verbose plumbing — the observability gap that let
+        // §7a.1 run 1 fail silently (give-ups were verbose-gated and invisible).
+        this.log = process.env.HOMEGRAPH_WAL_VALVE_DEBUG
+            ? (m) => console.error(`[wal-valve] ${m}`)
+            : log;
     }
+    log;
     mb(n) {
         return `${Math.round(n / 1024 / 1024)}MB`;
     }
@@ -101,7 +130,19 @@ class WalCheckpointValve {
     start() {
         if (this.timer)
             return;
-        this.timer = setInterval(() => this.check(), this.intervalMs);
+        // One armed line per run under either diagnostics env: §7a.1's failed
+        // kernel-scale runs burned three 25-minute cycles before "is the valve
+        // even alive?" could be answered.
+        if (process.env.HOMEGRAPH_SYNTH_TIMINGS || process.env.HOMEGRAPH_WAL_VALVE_DEBUG) {
+            console.error(`[wal-valve] armed soft=${this.mb(this.softBytes)} hard=${this.mb(this.hardBytes)} wal=${this.mb(this.db.getWalSizeBytes())}`);
+        }
+        let ticks = 0;
+        this.timer = setInterval(() => {
+            if ((++ticks % 15) === 0) {
+                this.log(`alive: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)} inflight=${this.inflight ? 'y' : 'n'} paused=${this.pause ? 'y' : 'n'}`);
+            }
+            this.check();
+        }, this.intervalMs);
         this.timer.unref?.();
     }
     /** Stop watching. Any in-flight checkpoint keeps running — await drain(). */
@@ -125,7 +166,17 @@ class WalCheckpointValve {
     backpressure() {
         if (this.pause)
             return this.pause;
-        if (this.growthBytes() <= this.hardBytes)
+        if (Date.now() < this.futileUntil)
+            return null; // pinned reader — parking is churn, not progress
+        // Two independent triggers:
+        //  - growth: un-backfilled BACKLOG past the hard cap (the original valve).
+        //  - file size: a WAL can stay fully backfilled and still grow without
+        //    bound — the writer only restarts at frame 0 if a commit finds no
+        //    reader marks, which §7a.1's instrumented run showed never happens
+        //    in practice (file marched 361→721MB through two COMPLETE
+        //    backfills). Past the file cap, park and TRUNCATE at the barrier —
+        //    the backfill part is instant when the backlog is already folded.
+        if (this.growthBytes() <= this.hardBytes && this.db.getWalSizeBytes() <= this.fileCapBytes)
             return null;
         this.log(`backpressure: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)} — pausing writer for full backfill`);
         const t0 = Date.now();
@@ -176,16 +227,39 @@ class WalCheckpointValve {
                 return; // checkpoint machinery unavailable — don't spin
             this.log(`backfill pass ${i + 1}: busy=${res.busy} log=${res.log} checkpointed=${res.checkpointed} wal=${this.mb(this.db.getWalSizeBytes())}`);
             if (res.busy === 0 && res.log === res.checkpointed) {
+                // Backfill complete AND we are at a parked barrier (backfillFully only
+                // runs under a writer pause): the no-reader window is guaranteed, so
+                // chop the FILE too — a fully-backfilled WAL otherwise keeps growing
+                // whenever commits land while pool readers hold marks (§7a.1: 22GB
+                // on-disk at kernel scale despite backfills). A racing reader turns
+                // this into a no-op (busy=1); the passive result above still stands.
+                const trunc = await this.db.checkpointWalTruncate();
+                if (trunc)
+                    this.log(`truncate: busy=${trunc.busy} wal=${this.mb(this.db.getWalSizeBytes())}`);
                 this.sizeAtLastFullBackfill = this.db.getWalSizeBytes();
+                this.consecutiveGiveUps = 0;
+                this.futileUntil = 0;
                 return;
             }
         }
-        this.log(`backfill gave up after ${MAX_PAUSED_BACKFILL_PASSES} passes — WAL stays unbounded this cycle`);
+        this.consecutiveGiveUps++;
+        if (this.consecutiveGiveUps >= 2) {
+            this.futileUntil = Date.now() + 60_000;
+        }
+        const msg = `backfill gave up after ${MAX_PAUSED_BACKFILL_PASSES} passes (streak ${this.consecutiveGiveUps}${this.futileUntil ? ', parking disabled 60s' : ''}) — a reader is pinning the WAL`;
+        this.log(msg);
+        // Give-ups are rare and load-bearing for §7a.1-class diagnosis — surface
+        // them on any timing-instrumented run, not just valve-debug ones.
+        if (process.env.HOMEGRAPH_SYNTH_TIMINGS && !process.env.HOMEGRAPH_WAL_VALVE_DEBUG) {
+            console.error(`[wal-valve] ${msg}`);
+        }
     }
     fire() {
+        this.log(`fire: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)}`);
         const p = this.db
             .checkpointWalPassive()
             .then((res) => {
+            this.log(`timer pass: ${res ? `busy=${res.busy} log=${res.log} checkpointed=${res.checkpointed}` : 'null (machinery unavailable)'} wal=${this.mb(this.db.getWalSizeBytes())}`);
             // Full backfill (busy 0, every log frame checkpointed) ⇒ the writer's
             // next commit wraps the WAL; the file's current size becomes the new
             // growth baseline. A partial pass (writer appended during it, or a
@@ -194,6 +268,14 @@ class WalCheckpointValve {
             // SQLite reports log = checkpointed = -1, which is harmless here.
             if (res && res.busy === 0 && res.log === res.checkpointed) {
                 this.sizeAtLastFullBackfill = this.db.getWalSizeBytes();
+                // NO truncate here. A truncate checkpoint that starts against an
+                // ACTIVE writer wins the lock race and then blocks that writer for
+                // its entire backfill — after a multi-GB single-transaction burst
+                // (edge-index recreate) that exceeds the writer's 5s busy_timeout
+                // and fails the index with "database is locked" (§7a.2 record run).
+                // The file chop happens exclusively at parked barriers
+                // (backpressure/foldNow), where the writer is awaiting us by
+                // construction and cannot collide.
             }
         })
             .catch(() => { })