@bobfrankston/mailx-store 0.1.48 → 0.1.50

package/db.d.ts

@@ -15,6 +15,7 @@ export declare class MailxDB {
     readonly readOnly: boolean;
     constructor(dbDir: string, opts?: {
         readOnly?: boolean;
+        skipMigrations?: boolean;
     });
     /** Fail loud + early if expected columns are missing. Cheap (PRAGMA only
      *  runs at startup). The user-facing message names the recovery command. */
@@ -399,6 +400,15 @@ export declare class MailxDB {
     } | null;
     /** Clear a UID's prefetch-failure record after a successful fetch. */
     clearPrefetchFailure(accountId: string, folderId: number, uid: number): void;
+    /** Wipe ALL prefetch-failure backoffs. Called once per boot: the backoff is
+     *  a within-SESSION optimisation (it stops a poison body being re-fetched
+     *  every 60s cycle), so a fresh session should give every body another try —
+     *  the network may have recovered, and crucially a body backed off by a
+     *  transient cause (a two-writer DB lock, a Dovecot 300s timeout) shouldn't
+     *  stay suppressed for up to 12h (Bob 2026-06-14: "lots of predownloading
+     *  not happening"). Genuine poison bodies simply re-fail once and re-back-off
+     *  for the session — no per-cycle loop. */
+    clearAllPrefetchFailures(): number;
     /** Highest server UID we've seen in this folder. After the
      *  message_folders refactor, this reads from the membership table
      *  rather than messages.uid — a server-side move from this folder

package/db.js

@@ -412,6 +412,22 @@ export class MailxDB {
         const dbPath = path.join(dbDir, "mailx.db");
         this.readOnly = !!opts.readOnly;
         this.db = new DatabaseSync(dbPath);
+        if (opts.skipMigrations && !opts.readOnly) {
+            // Write-capable connection that does NOT run schema/migrations —
+            // used by the sync worker, which opens its own writer AFTER the
+            // main thread has already built the schema. Two threads running the
+            // DDL/backfills concurrently would race on the WAL write lock.
+            this.db.exec("PRAGMA journal_mode = WAL");
+            this.db.exec("PRAGMA foreign_keys = ON");
+            // 10s (vs the main thread's 5s): this is the BACKGROUND writer (sync,
+            // prefetch); waiting a bit longer for the foreground's lock is fine.
+            // NOT higher because busy_timeout BLOCKS this thread synchronously
+            // (it can't forward sync events while parked) — for longer holds the
+            // prefetch write path uses an ASYNC retry that yields between
+            // attempts instead. Fixes prefetch "database is locked" (Bob 2026-06-14).
+            this.db.exec("PRAGMA busy_timeout = 10000");
+            return;
+        }
         if (this.readOnly) {
             // Read-worker connection (Phase 0 read isolation). The main-thread
             // MailxDB has ALREADY created the schema and run every migration /
@@ -430,10 +446,19 @@ export class MailxDB {
             // so readers see committed snapshots with no journal_mode call.
             this.db.exec("PRAGMA foreign_keys = ON");
             this.db.exec("PRAGMA query_only = ON");
+            // A reader can briefly collide with a WAL checkpoint; wait, don't throw.
+            this.db.exec("PRAGMA busy_timeout = 5000");
             return;
         }
         this.db.exec("PRAGMA journal_mode = WAL");
         this.db.exec("PRAGMA foreign_keys = ON");
+        // 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
+        // collision returns SQLITE_BUSY *immediately* by default — busy_timeout
+        // makes the loser WAIT for the lock (up to 5s) instead of failing. Safe
+        // and inert today (single writer); required before the worker lands.
+        this.db.exec("PRAGMA busy_timeout = 5000");
         this.db.exec(SCHEMA);
         this.migrateFtsSchema();
         // Purge phantom uid=0 rows (invalid IMAP UID — empty stub letters, the
@@ -550,6 +575,15 @@ export class MailxDB {
         // this column landed. One UPDATE + an id roundtrip per row — cheap
         // at our row counts, runs once per DB upgrade.
         this.backfillUuids();
+        // Per-boot: clear prefetch-failure backoffs so transiently-failed bodies
+        // (two-writer DB lock, Dovecot timeout) get a fresh try this session
+        // instead of staying suppressed for up to 12h. See clearAllPrefetchFailures.
+        try {
+            const cleared = this.clearAllPrefetchFailures();
+            if (cleared > 0)
+                console.log(`  [db] cleared ${cleared} prefetch-failure backoff(s) for a fresh session`);
+        }
+        catch { /* non-fatal */ }
         // One-shot cleanup: the retired insertOptimisticSentRow path wrote
         // synthetic-negative-UID rows into Sent. Those rows are stale (the
         // real server-synced row eventually appears with a positive UID),
@@ -2216,6 +2250,22 @@ export class MailxDB {
     clearPrefetchFailure(accountId, folderId, uid) {
         this.db.prepare("DELETE FROM prefetch_failures WHERE account_id = ? AND folder_id = ? AND uid = ?").run(accountId, folderId, uid);
     }
+    /** Wipe ALL prefetch-failure backoffs. Called once per boot: the backoff is
+     *  a within-SESSION optimisation (it stops a poison body being re-fetched
+     *  every 60s cycle), so a fresh session should give every body another try —
+     *  the network may have recovered, and crucially a body backed off by a
+     *  transient cause (a two-writer DB lock, a Dovecot 300s timeout) shouldn't
+     *  stay suppressed for up to 12h (Bob 2026-06-14: "lots of predownloading
+     *  not happening"). Genuine poison bodies simply re-fail once and re-back-off
+     *  for the session — no per-cycle loop. */
+    clearAllPrefetchFailures() {
+        try {
+            return this.db.prepare("DELETE FROM prefetch_failures").run().changes;
+        }
+        catch {
+            return 0;
+        }
+    }
     /** Highest server UID we've seen in this folder. After the
      *  message_folders refactor, this reads from the membership table
      *  rather than messages.uid — a server-side move from this folder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "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.26",
+    "@bobfrankston/mailx-settings": "^0.1.27",
     "@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.26",
+      "@bobfrankston/mailx-settings": "^0.1.27",
       "@bobfrankston/mailx-bus": "^0.1.2",
       "mailparser": "^3.7.2"
     }