@bobfrankston/mailx-store 0.1.50 → 0.1.52

package/db.d.ts

@@ -479,6 +479,17 @@ export declare class MailxDB {
      *  already open this just runs `fn` (its writes join the open txn);
      *  otherwise it owns a fresh BEGIN/COMMIT. `fn` MUST be synchronous so it
      *  can't span an await and leave a transaction open across a yield. */
+    /** Run a WAL checkpoint to bound the WAL file size. PASSIVE never blocks
+     *  on readers — it reclaims frames older than the oldest live snapshot and
+     *  returns immediately otherwise. Drive it from ONE connection (main) on a
+     *  timer so the WAL can't balloon while three connections share the file.
+     *  Returns {busy, log, checkpointed} (log = frames in WAL, checkpointed =
+     *  frames moved into the db) or null on error. */
+    checkpoint(mode?: "PASSIVE" | "FULL" | "RESTART" | "TRUNCATE"): {
+        busy: number;
+        log: number;
+        checkpointed: number;
+    } | null;
     runInTxn<T>(fn: () => T): T;
     /** Record an address used in sent mail */
     recordSentAddress(name: string, email: string): void;

package/db.js

@@ -452,6 +452,23 @@ export class MailxDB {
         }
         this.db.exec("PRAGMA journal_mode = WAL");
         this.db.exec("PRAGMA foreign_keys = ON");
+        // WAL hygiene. With THREE connections (main writer, sync-worker writer,
+        // read-worker reader) the WAL was never getting checkpointed — failed
+        // writes (two-writer contention) never commit, so the auto-checkpoint
+        // that normally fires on commit never ran, and the WAL ballooned to
+        // 71 MB (Bob 2026-06-14: every read/write crawled, `database is locked`
+        // everywhere, a bulk move took 51s and timed out). A bloated WAL is
+        // self-reinforcing: bigger WAL → slower writes → more lock failures →
+        // fewer commits → no checkpoint. Boot is the one moment main is the
+        // SOLE connection (read/sync workers spawn later), so TRUNCATE here
+        // resets the file to empty; `checkpoint()` on a timer keeps it small.
+        try {
+            const r = this.db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+            console.log(`  [db] boot WAL checkpoint: busy=${r?.busy} log=${r?.log} checkpointed=${r?.checkpointed}`);
+        }
+        catch (e) {
+            console.error(`  [db] boot WAL checkpoint failed: ${e?.message || e}`);
+        }
         // Multi-writer foundation for the sync-worker migration: once sync runs
         // on its own thread with its own write connection, it and the main
         // thread are two writers on one WAL file. WAL serializes writers, so a
@@ -2394,13 +2411,37 @@ export class MailxDB {
      *  already open this just runs `fn` (its writes join the open txn);
      *  otherwise it owns a fresh BEGIN/COMMIT. `fn` MUST be synchronous so it
      *  can't span an await and leave a transaction open across a yield. */
+    /** Run a WAL checkpoint to bound the WAL file size. PASSIVE never blocks
+     *  on readers — it reclaims frames older than the oldest live snapshot and
+     *  returns immediately otherwise. Drive it from ONE connection (main) on a
+     *  timer so the WAL can't balloon while three connections share the file.
+     *  Returns {busy, log, checkpointed} (log = frames in WAL, checkpointed =
+     *  frames moved into the db) or null on error. */
+    checkpoint(mode = "PASSIVE") {
+        try {
+            return this.db.prepare(`PRAGMA wal_checkpoint(${mode})`).get();
+        }
+        catch {
+            return null;
+        }
+    }
     runInTxn(fn) {
         if (this.db.isTransaction)
             return fn();
         this.db.exec("BEGIN");
+        const _t0 = Date.now();
         try {
             const r = fn();
             this.db.exec("COMMIT");
+            // Diagnostic: a write transaction held >1s on the MAIN connection is
+            // what locks out the sync-worker's prefetch write (Bob 2026-06-14
+            // "find the long main-thread transaction"). Log the call site so the
+            // next occurrence names itself instead of needing code archaeology.
+            const _ms = Date.now() - _t0;
+            if (_ms > 1000) {
+                const where = (new Error().stack || "").split("\n")[2]?.trim() || "?";
+                console.warn(`  [db] SLOW write txn ${_ms}ms (readOnly=${this.readOnly}) at ${where}`);
+            }
             return r;
         }
         catch (e) {
@@ -2620,7 +2661,13 @@ export class MailxDB {
         // straddling an `await` — the wrapper is nesting-safe (savepoints)
         // so it can't collide with the sync backfill's own transactions
         // when the two interleave across the yield below.
-        const WRITE_CHUNK = 500;
+        // 100, not 500: each chunk is one held write transaction, and the
+        // slow-txn logger caught these running 2+ SECONDS apiece under WAL
+        // pressure — long enough to lock out the sync worker's storeMessages
+        // ("database is locked"). Smaller chunks = shorter lock holds + a
+        // yield (below) after each, giving the worker write windows (Bob
+        // 2026-06-16, live debug).
+        const WRITE_CHUNK = 100;
         const entries = [...agg.entries()];
         for (let i = 0; i < entries.length; i += WRITE_CHUNK) {
             const slice = entries.slice(i, i + WRITE_CHUNK);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,7 +10,7 @@
   "license": "ISC",
   "dependencies": {
     "@bobfrankston/mailx-types": "^0.1.19",
-    "@bobfrankston/mailx-settings": "^0.1.27",
+    "@bobfrankston/mailx-settings": "^0.1.28",
     "@bobfrankston/mailx-bus": "^0.1.2",
     "mailparser": "^3.7.2"
   },
@@ -30,7 +30,7 @@
   ".transformedSnapshot": {
     "dependencies": {
       "@bobfrankston/mailx-types": "^0.1.19",
-      "@bobfrankston/mailx-settings": "^0.1.27",
+      "@bobfrankston/mailx-settings": "^0.1.28",
       "@bobfrankston/mailx-bus": "^0.1.2",
       "mailparser": "^3.7.2"
     }