@bobfrankston/mailx-store 0.1.11 → 0.1.12

package/db.d.ts

@@ -148,6 +148,20 @@ export declare class MailxDB {
     updateLastSync(accountId: string, timestamp: number): void;
     upsertFolder(accountId: string, folderPath: string, name: string, specialUse: string, delimiter: string): number;
     getFolders(accountId: string): Folder[];
+    /** Append a row to the audit_log table. Every destructive operation on
+     *  the messages table writes here so "where did the rows go?" has an
+     *  authoritative answer. Cheap insert, indexed by ts and (account, folder). */
+    audit(entry: {
+        kind: "delete-msg" | "delete-bulk" | "migration" | "manual" | string;
+        accountId?: string;
+        folderId?: number;
+        uid?: number;
+        count?: number;
+        messageId?: string;
+        subject?: string;
+        reason?: string;
+        source?: string;
+    }): void;
     deleteFolder(folderId: number): void;
     markFolderRead(folderId: number): void;
     deleteAllMessages(accountId: string, folderId: number): void;
@@ -204,8 +218,9 @@ export declare class MailxDB {
     getMessageCount(accountId: string, folderId: number): number;
     /** Get all UIDs for a folder */
     getUidsForFolder(accountId: string, folderId: number): number[];
-    /** Delete a message by account + UID */
-    deleteMessage(accountId: string, uid: number): void;
+    /** Delete a message by account + UID. Reason is propagated into the
+     *  audit_log so the DB carries an authoritative trail of every removal. */
+    deleteMessage(accountId: string, uid: number, reason?: string, source?: string): void;
     /** Recalculate folder total/unread counts from actual messages */
     recalcFolderCounts(folderId: number): void;
     /** Bulk insert within a transaction for sync performance */

package/db.js

@@ -285,6 +285,35 @@ const SCHEMA = `
         updated_at INTEGER NOT NULL,
         PRIMARY KEY(scope, key)
     );
+
+    -- Audit trail of every destructive DB operation. Writes ONLY — the row
+    -- inserted here records the deletion the caller is about to (or just
+    -- did) commit on the messages table. Lets the user retroactively answer
+    -- "where did my Sent rows go?" — every deletion has a row with
+    -- kind/reason/folder/uid + caller stack hint. Trivial cost (rows are
+    -- tiny), no retention policy yet — kept indefinitely.
+    --
+    -- kind values:
+    --   delete-msg      single message removed (sync_actions drain, body
+    --                   fetch reported isNotFound, reconcile)
+    --   delete-bulk     bulk delete (reconcile pruning, emptyFolder, etc.)
+    --   migration       schema migrations that touch messages
+    --   manual          direct user "rebuild" / "wipe folder"
+    CREATE TABLE IF NOT EXISTS audit_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        account_id TEXT,
+        folder_id INTEGER,
+        uid INTEGER,
+        count INTEGER,
+        message_id TEXT,
+        subject TEXT,
+        reason TEXT,
+        source TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_audit_log_ts ON audit_log(ts);
+    CREATE INDEX IF NOT EXISTS idx_audit_log_folder ON audit_log(account_id, folder_id);
 `;
 export class MailxDB {
     db;
@@ -344,8 +373,10 @@ export class MailxDB {
             const purgedFlag = this.getKv("schema", "drop_synthetic_uids_v1");
             if (!purgedFlag) {
                 const r = this.db.prepare("DELETE FROM messages WHERE uid < 0").run();
-                if (r.changes) {
-                    console.log(`  [migration] dropped ${r.changes} synthetic-UID rows from messages`);
+                const count = r.changes || 0;
+                if (count > 0) {
+                    console.log(`  [migration] dropped ${count} synthetic-UID rows from messages`);
+                    this.audit({ kind: "migration", count, reason: "drop_synthetic_uids_v1 — purge negative-UID optimistic-Sent rows", source: "MailxDB constructor" });
                 }
                 this.setKv("schema", "drop_synthetic_uids_v1", "1");
             }
@@ -930,8 +961,24 @@ export class MailxDB {
         }
         return folders;
     }
+    /** Append a row to the audit_log table. Every destructive operation on
+     *  the messages table writes here so "where did the rows go?" has an
+     *  authoritative answer. Cheap insert, indexed by ts and (account, folder). */
+    audit(entry) {
+        try {
+            this.db.prepare(`INSERT INTO audit_log (ts, kind, account_id, folder_id, uid, count, message_id, subject, reason, source)
+                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(Date.now(), entry.kind, entry.accountId ?? null, entry.folderId ?? null, entry.uid ?? null, entry.count ?? null, entry.messageId ?? null, entry.subject ?? null, entry.reason ?? null, entry.source ?? null);
+        }
+        catch (e) {
+            // Audit must never break the operation it's auditing.
+            console.error(`  [audit] failed: ${e?.message || e}`);
+        }
+    }
     deleteFolder(folderId) {
-        this.db.prepare("DELETE FROM messages WHERE folder_id = ?").run(folderId);
+        const r = this.db.prepare("DELETE FROM messages WHERE folder_id = ?").run(folderId);
+        const count = r.changes || 0;
+        if (count > 0)
+            this.audit({ kind: "delete-bulk", folderId, count, reason: "folder deleted", source: "deleteFolder" });
         this.db.prepare("DELETE FROM folders WHERE id = ?").run(folderId);
     }
     markFolderRead(folderId) {
@@ -939,7 +986,10 @@ export class MailxDB {
         this.recalcFolderCounts(folderId);
     }
     deleteAllMessages(accountId, folderId) {
-        this.db.prepare("DELETE FROM messages WHERE account_id = ? AND folder_id = ?").run(accountId, folderId);
+        const r = this.db.prepare("DELETE FROM messages WHERE account_id = ? AND folder_id = ?").run(accountId, folderId);
+        const count = r.changes || 0;
+        if (count > 0)
+            this.audit({ kind: "delete-bulk", accountId, folderId, count, reason: "deleteAllMessages (emptyFolder)", source: "deleteAllMessages" });
         this.recalcFolderCounts(folderId);
     }
     updateFolderCounts(folderId, total, unread) {
@@ -1231,11 +1281,25 @@ export class MailxDB {
         const rows = this.db.prepare("SELECT uid FROM messages WHERE account_id = ? AND folder_id = ?").all(accountId, folderId);
         return rows.map(r => r.uid);
     }
-    /** Delete a message by account + UID */
-    deleteMessage(accountId, uid) {
-        // Get folderId before deleting so we can update counts
-        const msg = this.db.prepare("SELECT folder_id FROM messages WHERE account_id = ? AND uid = ?").get(accountId, uid);
-        this.db.prepare("DELETE FROM messages WHERE account_id = ? AND uid = ?").run(accountId, uid);
+    /** Delete a message by account + UID. Reason is propagated into the
+     *  audit_log so the DB carries an authoritative trail of every removal. */
+    deleteMessage(accountId, uid, reason, source) {
+        // Get folderId + message_id + subject before deleting so the audit
+        // row carries enough context to identify what was removed.
+        const msg = this.db.prepare("SELECT folder_id, message_id, subject FROM messages WHERE account_id = ? AND uid = ?").get(accountId, uid);
+        const r = this.db.prepare("DELETE FROM messages WHERE account_id = ? AND uid = ?").run(accountId, uid);
+        if (r.changes && msg) {
+            this.audit({
+                kind: "delete-msg",
+                accountId,
+                folderId: msg.folder_id,
+                uid,
+                messageId: msg.message_id || undefined,
+                subject: msg.subject || undefined,
+                reason: reason || "deleteMessage (no reason)",
+                source: source || "db.deleteMessage",
+            });
+        }
         // Refresh folder counts
         if (msg)
             this.recalcFolderCounts(msg.folder_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-store",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",