@bobfrankston/rmfmail 1.0.546 → 1.0.548

package/packages/mailx-service/reconciler.ts

@@ -0,0 +1,151 @@
+/**
+ * Reconciler — single background loop that drains the SyncQueue, polls
+ * for server changes, and emits state events the UI listens for.
+ *
+ * Local-first contract: the Reconciler is the ONLY code path that touches
+ * IMAP / Gmail API on behalf of UI actions. UI handlers commit locally
+ * and enqueue; the Reconciler picks up and mirrors. Reads from the UI
+ * never await the Reconciler.
+ *
+ * What this owns today:
+ * - body-fetch lane: drains `SyncQueue.nextBodyFetch()`, calls
+ *   `imapManager.fetchMessageBody`, emits `bodyAvailable` / `bodyFetchError`.
+ *   This is the new piece; previously body fetches happened inline on
+ *   every getMessage call.
+ * - sync-state pill events: emits `syncStateChanged` so the UI can show
+ *   "Sync OK / Syncing N items".
+ *
+ * What it delegates (intentional — no duplication):
+ * - message-action drain: ImapManager already runs a 30s actionsInterval
+ *   that processes both outbox (processSendActions) and sync_actions
+ *   (processSyncActions) per account. Per plan decision #5, outbox stays
+ *   under ImapManager; we don't fork that work.
+ * - poll loops (per-account quick check, full sync, prefetch, tombstone
+ *   prune): all owned by ImapManager's startPeriodicSync. The Reconciler
+ *   does NOT shadow them — back-pressure on those timers can be added
+ *   later via a single `setBackPressure(level)` hook.
+ *
+ * Part of docs/local-first-plan.md (step 4).
+ */
+
+import type { ImapManager } from "@bobfrankston/mailx-imap";
+import type { MailxDB } from "@bobfrankston/mailx-store";
+import type { SyncQueue } from "./sync-queue.js";
+
+export interface ReconcilerOptions {
+    /** Max concurrent body fetches across all accounts (in addition to
+     *  per-account semaphore in ImapManager). Keeps the interactive lane
+     *  responsive even when prefetch is hammering. */
+    bodyFetchConcurrency?: number;
+    /** Periodic emit of syncStateChanged — drives the UI status pill. */
+    statusEmitIntervalMs?: number;
+}
+
+const DEFAULTS: Required<ReconcilerOptions> = {
+    bodyFetchConcurrency: 2,
+    statusEmitIntervalMs: 5_000,
+};
+
+export class Reconciler {
+    private opts: Required<ReconcilerOptions>;
+    private running = false;
+    private statusTimer: ReturnType<typeof setInterval> | null = null;
+    private inFlightFetches = 0;
+
+    constructor(
+        private db: MailxDB,
+        private imapManager: ImapManager,
+        private queue: SyncQueue,
+        opts: ReconcilerOptions = {},
+    ) {
+        this.opts = { ...DEFAULTS, ...opts };
+    }
+
+    start(): void {
+        if (this.running) return;
+        this.running = true;
+
+        // Status pill: emit current totals every few seconds so the UI
+        // can show "Syncing N items" without polling.
+        this.statusTimer = setInterval(() => {
+            const counts = this.queue.pendingCount();
+            this.imapManager.emit("syncStateChanged", { ...counts, inFlightFetches: this.inFlightFetches });
+        }, this.opts.statusEmitIntervalMs);
+
+        // Kick the body-fetch loop.
+        this.pumpBodyFetches();
+    }
+
+    stop(): void {
+        this.running = false;
+        if (this.statusTimer) { clearInterval(this.statusTimer); this.statusTimer = null; }
+    }
+
+    /** User-visible "sync now" — runs an immediate poll on all accounts
+     *  (or just one) without waiting for the next periodic tick. */
+    syncNow(accountId?: string): void {
+        const accts = accountId ? [{ id: accountId }] : this.db.getAccounts();
+        for (const a of accts) {
+            this.imapManager.processSyncActions(a.id).catch(() => { /* */ });
+        }
+    }
+
+    /** Drain the body-fetch lane up to `bodyFetchConcurrency`. Each
+     *  fetch is fire-and-forget; on completion it kicks the pump again
+     *  so a queue that grows during work stays drained. */
+    private pumpBodyFetches(): void {
+        if (!this.running) return;
+        while (this.inFlightFetches < this.opts.bodyFetchConcurrency) {
+            const next = this.queue.nextBodyFetch();
+            if (!next) return;
+            this.inFlightFetches++;
+            (async () => {
+                try {
+                    const raw = await this.imapManager.fetchMessageBody(next.accountId, next.folderId, next.uid);
+                    if (raw) {
+                        this.imapManager.emit("bodyAvailable", {
+                            accountId: next.accountId, folderId: next.folderId, uid: next.uid,
+                        });
+                    }
+                } catch (err: any) {
+                    if (err?.isNotFound) {
+                        try {
+                            this.db.deleteMessage(next.accountId, next.uid);
+                            this.db.recalcFolderCounts(next.folderId);
+                            this.imapManager.emit("messageRemoved", {
+                                accountId: next.accountId, folderId: next.folderId, uid: next.uid,
+                            });
+                        } catch { /* */ }
+                    } else {
+                        const msg = err?.message || "body fetch failed";
+                        const transient = /connection|Too many|UNAVAILABLE|rate|429|5\d\d|timeout|ENOTFOUND|ECONNRESET|ETIMEDOUT/i.test(msg);
+                        // Transient: re-enqueue (budget=3) so the next pump
+                        // tick retries. Surface the error only when the
+                        // budget is exhausted — otherwise we'd flash banners
+                        // for every blip on a slow server.
+                        if (transient && this.queue.requeueBodyFetch(next)) {
+                            // Backoff so we don't immediately re-hit the same
+                            // wedge. Body-fetch lane is in-memory; setTimeout
+                            // is fine.
+                            const backoffMs = 500 * Math.pow(2, next.attempts);
+                            setTimeout(() => this.pumpBodyFetches(), backoffMs);
+                        } else {
+                            this.imapManager.emit("bodyFetchError", {
+                                accountId: next.accountId, folderId: next.folderId, uid: next.uid,
+                                error: msg, transient,
+                            });
+                        }
+                    }
+                } finally {
+                    this.inFlightFetches--;
+                    this.pumpBodyFetches();
+                }
+            })();
+        }
+    }
+
+    /** External nudge — call after enqueueing a high-priority body fetch. */
+    kick(): void {
+        this.pumpBodyFetches();
+    }
+}

package/packages/mailx-service/sync-queue.d.ts

@@ -0,0 +1,79 @@
+/**
+ * SyncQueue — the formal enqueue surface for server-side mirroring of
+ * local actions.
+ *
+ * Local-first contract: every UI write commits to the local store first,
+ * then hands off here. Nothing in this file does network I/O; the
+ * Reconciler drains the queue.
+ *
+ * Implementation note: the underlying persistence already exists. Message
+ * ops live in `sync_actions` (drained by ImapManager.processSyncActions),
+ * non-message ops in `store_sync` (drained by the per-domain workers).
+ * This class is the public API surface — call sites switch to it so the
+ * architecture's seam is visible, the rules are enforceable, and we can
+ * later bolt on body-fetch / draft-push / send-push lanes without
+ * touching every call site again.
+ *
+ * Priority lanes (interactive > sync > prefetch > backfill) are tracked
+ * here as ordering hints; the actual scheduler is in the Reconciler.
+ *
+ * Part of docs/local-first-plan.md (steps 3-4).
+ */
+import type { MailxDB } from "@bobfrankston/mailx-store";
+import type { ImapManager } from "@bobfrankston/mailx-imap";
+export type Lane = "interactive" | "sync" | "prefetch" | "backfill";
+/** In-memory body-fetch dedupe + ordering. We keep this as a Set rather
+ *  than persisted rows because body fetches are idempotent (the file is
+ *  named after the (folder, uid) pair) and a re-fetch on next click is
+ *  cheap if a process crash drops the queued item. */
+interface BodyFetchKey {
+    accountId: string;
+    folderId: number;
+    uid: number;
+    lane: Lane;
+    attempts: number;
+}
+export declare class SyncQueue {
+    private db;
+    private imapManager;
+    private bodyFetches;
+    constructor(db: MailxDB, imapManager: ImapManager);
+    /** Queue a server-side move. The local rows have already been moved in
+     *  the DB; the mirror reaches the server on the next reconciler pass. */
+    enqueueMove(accountId: string, uid: number, fromFolderId: number, toFolderId: number): void;
+    /** Queue a server-side flag update (\Seen, \Flagged, \Answered, etc.). */
+    enqueueFlag(accountId: string, uid: number, folderId: number, flags: string[]): void;
+    /** Queue a server-side delete (or trash, depending on action). */
+    enqueueDelete(accountId: string, uid: number, folderId: number, kind?: "delete" | "trash"): void;
+    /** Queue an IMAP APPEND of a draft body. Drafts already have crash
+     *  recovery via the editing/.eml on disk, so this lane is in-memory
+     *  fire-and-forget for now — the architectural value is centralizing
+     *  the call site, not adding a second on-disk store for the same
+     *  bytes. The reconciler retries on transient IMAP failure via the
+     *  existing sync_actions backoff after first failure. */
+    enqueueDraftPush(accountId: string, rawMessage: string, previousDraftUid?: number, draftId?: string): void;
+    /** Queue an outbox send. Today the outbox/<acct>/*.ltr directory IS
+     *  the queue and a separate worker drains it; this seam is reserved
+     *  for when that worker moves under the reconciler. */
+    enqueueSend(_accountId: string, _outboxId: string): void;
+    /** Request a body fetch. Dedupes per (account, folder, uid). The
+     *  `lane` argument hints urgency: `interactive` is a click; `prefetch`
+     *  is the background backfiller; `backfill` is the one-time post-sync
+     *  catch-up. Reconciler picks higher priority first. */
+    enqueueBodyFetch(accountId: string, folderId: number, uid: number, lane?: Lane): void;
+    /** Re-enqueue a transient failure — the reconciler calls this after a
+     *  fetch errored with a transient code. Returns `true` if the item was
+     *  put back in the queue (still under retry budget) or `false` if its
+     *  budget is exhausted (caller surfaces the error to the UI). */
+    requeueBodyFetch(key: BodyFetchKey, maxAttempts?: number): boolean;
+    /** Pop the next body-fetch task at or above `maxLane`. Used by the
+     *  reconciler to drain interactive clicks before prefetch backfill. */
+    nextBodyFetch(maxLane?: Lane): BodyFetchKey | null;
+    /** Pending count for diagnostics + the sync-status pill. */
+    pendingCount(): {
+        messageActions: number;
+        bodyFetches: number;
+    };
+}
+export {};
+//# sourceMappingURL=sync-queue.d.ts.map

package/packages/mailx-service/sync-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-queue.d.ts","sourceRoot":"","sources":["sync-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,MAAM,IAAI,GAAG,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpE;;;sDAGsD;AACtD,UAAU,YAAY;IAAG,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAEzG,qBAAa,SAAS;IAId,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,WAAW;IAJvB,OAAO,CAAC,WAAW,CAAmC;gBAG1C,EAAE,EAAE,OAAO,EACX,WAAW,EAAE,WAAW;IAKpC;6EACyE;IACzE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAK3F,0EAA0E;IAC1E,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAKpF,kEAAkE;IAClE,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,QAAQ,GAAG,OAAkB,GAAG,IAAI;IAK1G;;;;;6DAKyD;IACzD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAO1G;;2DAEuD;IACvD,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAMxD;;;4DAGwD;IACxD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,IAAoB,GAAG,IAAI;IAYpG;;;qEAGiE;IACjE,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,WAAW,SAAI,GAAG,OAAO;IAQ7D;2EACuE;IACvE,aAAa,CAAC,OAAO,GAAE,IAAiB,GAAG,YAAY,GAAG,IAAI;IAY9D,4DAA4D;IAC5D,YAAY,IAAI;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;CAMlE"}

package/packages/mailx-service/sync-queue.js

@@ -0,0 +1,118 @@
+/**
+ * SyncQueue — the formal enqueue surface for server-side mirroring of
+ * local actions.
+ *
+ * Local-first contract: every UI write commits to the local store first,
+ * then hands off here. Nothing in this file does network I/O; the
+ * Reconciler drains the queue.
+ *
+ * Implementation note: the underlying persistence already exists. Message
+ * ops live in `sync_actions` (drained by ImapManager.processSyncActions),
+ * non-message ops in `store_sync` (drained by the per-domain workers).
+ * This class is the public API surface — call sites switch to it so the
+ * architecture's seam is visible, the rules are enforceable, and we can
+ * later bolt on body-fetch / draft-push / send-push lanes without
+ * touching every call site again.
+ *
+ * Priority lanes (interactive > sync > prefetch > backfill) are tracked
+ * here as ordering hints; the actual scheduler is in the Reconciler.
+ *
+ * Part of docs/local-first-plan.md (steps 3-4).
+ */
+export class SyncQueue {
+    db;
+    imapManager;
+    bodyFetches = new Map();
+    constructor(db, imapManager) {
+        this.db = db;
+        this.imapManager = imapManager;
+    }
+    // ── Message-mirror enqueues (commit local DB row first; then call here) ──
+    /** Queue a server-side move. The local rows have already been moved in
+     *  the DB; the mirror reaches the server on the next reconciler pass. */
+    enqueueMove(accountId, uid, fromFolderId, toFolderId) {
+        this.db.queueSyncAction(accountId, "move", uid, fromFolderId, { targetFolderId: toFolderId });
+        this.imapManager.processSyncActions(accountId).catch(() => { });
+    }
+    /** Queue a server-side flag update (\Seen, \Flagged, \Answered, etc.). */
+    enqueueFlag(accountId, uid, folderId, flags) {
+        this.db.queueSyncAction(accountId, "flags", uid, folderId, { flags });
+        this.imapManager.processSyncActions(accountId).catch(() => { });
+    }
+    /** Queue a server-side delete (or trash, depending on action). */
+    enqueueDelete(accountId, uid, folderId, kind = "delete") {
+        this.db.queueSyncAction(accountId, kind, uid, folderId, {});
+        this.imapManager.processSyncActions(accountId).catch(() => { });
+    }
+    /** Queue an IMAP APPEND of a draft body. Drafts already have crash
+     *  recovery via the editing/.eml on disk, so this lane is in-memory
+     *  fire-and-forget for now — the architectural value is centralizing
+     *  the call site, not adding a second on-disk store for the same
+     *  bytes. The reconciler retries on transient IMAP failure via the
+     *  existing sync_actions backoff after first failure. */
+    enqueueDraftPush(accountId, rawMessage, previousDraftUid, draftId) {
+        this.imapManager.saveDraft(accountId, rawMessage, previousDraftUid, draftId).catch((e) => {
+            console.error(`  [sync-queue] draft push deferred (${draftId}): ${e?.message || e}`);
+            this.imapManager.emit("draftSaveDeferred", { accountId, draftId, error: String(e?.message || e) });
+        });
+    }
+    /** Queue an outbox send. Today the outbox/<acct>/*.ltr directory IS
+     *  the queue and a separate worker drains it; this seam is reserved
+     *  for when that worker moves under the reconciler. */
+    enqueueSend(_accountId, _outboxId) {
+        // No-op — outbox dir-based queue stays as-is per plan decision #5.
+    }
+    // ── Body fetch lane (in-memory; idempotent) ──
+    /** Request a body fetch. Dedupes per (account, folder, uid). The
+     *  `lane` argument hints urgency: `interactive` is a click; `prefetch`
+     *  is the background backfiller; `backfill` is the one-time post-sync
+     *  catch-up. Reconciler picks higher priority first. */
+    enqueueBodyFetch(accountId, folderId, uid, lane = "interactive") {
+        const key = `${accountId}:${folderId}:${uid}`;
+        const existing = this.bodyFetches.get(key);
+        if (existing) {
+            // Upgrade lane if the new caller is more urgent.
+            const rank = { interactive: 0, sync: 1, prefetch: 2, backfill: 3 };
+            if (rank[lane] < rank[existing.lane])
+                existing.lane = lane;
+            return;
+        }
+        this.bodyFetches.set(key, { accountId, folderId, uid, lane, attempts: 0 });
+    }
+    /** Re-enqueue a transient failure — the reconciler calls this after a
+     *  fetch errored with a transient code. Returns `true` if the item was
+     *  put back in the queue (still under retry budget) or `false` if its
+     *  budget is exhausted (caller surfaces the error to the UI). */
+    requeueBodyFetch(key, maxAttempts = 3) {
+        if (key.attempts + 1 >= maxAttempts)
+            return false;
+        const k = `${key.accountId}:${key.folderId}:${key.uid}`;
+        // Don't downgrade lane on retry; keep the one the original caller set.
+        this.bodyFetches.set(k, { ...key, attempts: key.attempts + 1 });
+        return true;
+    }
+    /** Pop the next body-fetch task at or above `maxLane`. Used by the
+     *  reconciler to drain interactive clicks before prefetch backfill. */
+    nextBodyFetch(maxLane = "backfill") {
+        const rank = { interactive: 0, sync: 1, prefetch: 2, backfill: 3 };
+        const cap = rank[maxLane];
+        let best = null;
+        for (const v of this.bodyFetches.values()) {
+            if (rank[v.lane] > cap)
+                continue;
+            if (!best || rank[v.lane] < rank[best.lane])
+                best = v;
+        }
+        if (best)
+            this.bodyFetches.delete(`${best.accountId}:${best.folderId}:${best.uid}`);
+        return best;
+    }
+    /** Pending count for diagnostics + the sync-status pill. */
+    pendingCount() {
+        return {
+            messageActions: this.db.getTotalPendingSyncCount(),
+            bodyFetches: this.bodyFetches.size,
+        };
+    }
+}
+//# sourceMappingURL=sync-queue.js.map

package/packages/mailx-service/sync-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-queue.js","sourceRoot":"","sources":["sync-queue.ts"],"names":[],"mappings":"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"}

package/packages/mailx-service/sync-queue.ts

@@ -0,0 +1,134 @@
+/**
+ * SyncQueue — the formal enqueue surface for server-side mirroring of
+ * local actions.
+ *
+ * Local-first contract: every UI write commits to the local store first,
+ * then hands off here. Nothing in this file does network I/O; the
+ * Reconciler drains the queue.
+ *
+ * Implementation note: the underlying persistence already exists. Message
+ * ops live in `sync_actions` (drained by ImapManager.processSyncActions),
+ * non-message ops in `store_sync` (drained by the per-domain workers).
+ * This class is the public API surface — call sites switch to it so the
+ * architecture's seam is visible, the rules are enforceable, and we can
+ * later bolt on body-fetch / draft-push / send-push lanes without
+ * touching every call site again.
+ *
+ * Priority lanes (interactive > sync > prefetch > backfill) are tracked
+ * here as ordering hints; the actual scheduler is in the Reconciler.
+ *
+ * Part of docs/local-first-plan.md (steps 3-4).
+ */
+
+import type { MailxDB } from "@bobfrankston/mailx-store";
+import type { ImapManager } from "@bobfrankston/mailx-imap";
+
+export type Lane = "interactive" | "sync" | "prefetch" | "backfill";
+
+/** In-memory body-fetch dedupe + ordering. We keep this as a Set rather
+ *  than persisted rows because body fetches are idempotent (the file is
+ *  named after the (folder, uid) pair) and a re-fetch on next click is
+ *  cheap if a process crash drops the queued item. */
+interface BodyFetchKey { accountId: string; folderId: number; uid: number; lane: Lane; attempts: number }
+
+export class SyncQueue {
+    private bodyFetches = new Map<string, BodyFetchKey>();
+
+    constructor(
+        private db: MailxDB,
+        private imapManager: ImapManager,
+    ) {}
+
+    // ── Message-mirror enqueues (commit local DB row first; then call here) ──
+
+    /** Queue a server-side move. The local rows have already been moved in
+     *  the DB; the mirror reaches the server on the next reconciler pass. */
+    enqueueMove(accountId: string, uid: number, fromFolderId: number, toFolderId: number): void {
+        this.db.queueSyncAction(accountId, "move", uid, fromFolderId, { targetFolderId: toFolderId });
+        this.imapManager.processSyncActions(accountId).catch(() => { /* retried by reconciler */ });
+    }
+
+    /** Queue a server-side flag update (\Seen, \Flagged, \Answered, etc.). */
+    enqueueFlag(accountId: string, uid: number, folderId: number, flags: string[]): void {
+        this.db.queueSyncAction(accountId, "flags", uid, folderId, { flags });
+        this.imapManager.processSyncActions(accountId).catch(() => { /* retried */ });
+    }
+
+    /** Queue a server-side delete (or trash, depending on action). */
+    enqueueDelete(accountId: string, uid: number, folderId: number, kind: "delete" | "trash" = "delete"): void {
+        this.db.queueSyncAction(accountId, kind, uid, folderId, {});
+        this.imapManager.processSyncActions(accountId).catch(() => { /* retried */ });
+    }
+
+    /** Queue an IMAP APPEND of a draft body. Drafts already have crash
+     *  recovery via the editing/.eml on disk, so this lane is in-memory
+     *  fire-and-forget for now — the architectural value is centralizing
+     *  the call site, not adding a second on-disk store for the same
+     *  bytes. The reconciler retries on transient IMAP failure via the
+     *  existing sync_actions backoff after first failure. */
+    enqueueDraftPush(accountId: string, rawMessage: string, previousDraftUid?: number, draftId?: string): void {
+        this.imapManager.saveDraft(accountId, rawMessage, previousDraftUid, draftId).catch((e: any) => {
+            console.error(`  [sync-queue] draft push deferred (${draftId}): ${e?.message || e}`);
+            this.imapManager.emit("draftSaveDeferred", { accountId, draftId, error: String(e?.message || e) });
+        });
+    }
+
+    /** Queue an outbox send. Today the outbox/<acct>/*.ltr directory IS
+     *  the queue and a separate worker drains it; this seam is reserved
+     *  for when that worker moves under the reconciler. */
+    enqueueSend(_accountId: string, _outboxId: string): void {
+        // No-op — outbox dir-based queue stays as-is per plan decision #5.
+    }
+
+    // ── Body fetch lane (in-memory; idempotent) ──
+
+    /** Request a body fetch. Dedupes per (account, folder, uid). The
+     *  `lane` argument hints urgency: `interactive` is a click; `prefetch`
+     *  is the background backfiller; `backfill` is the one-time post-sync
+     *  catch-up. Reconciler picks higher priority first. */
+    enqueueBodyFetch(accountId: string, folderId: number, uid: number, lane: Lane = "interactive"): void {
+        const key = `${accountId}:${folderId}:${uid}`;
+        const existing = this.bodyFetches.get(key);
+        if (existing) {
+            // Upgrade lane if the new caller is more urgent.
+            const rank: Record<Lane, number> = { interactive: 0, sync: 1, prefetch: 2, backfill: 3 };
+            if (rank[lane] < rank[existing.lane]) existing.lane = lane;
+            return;
+        }
+        this.bodyFetches.set(key, { accountId, folderId, uid, lane, attempts: 0 });
+    }
+
+    /** Re-enqueue a transient failure — the reconciler calls this after a
+     *  fetch errored with a transient code. Returns `true` if the item was
+     *  put back in the queue (still under retry budget) or `false` if its
+     *  budget is exhausted (caller surfaces the error to the UI). */
+    requeueBodyFetch(key: BodyFetchKey, maxAttempts = 3): boolean {
+        if (key.attempts + 1 >= maxAttempts) return false;
+        const k = `${key.accountId}:${key.folderId}:${key.uid}`;
+        // Don't downgrade lane on retry; keep the one the original caller set.
+        this.bodyFetches.set(k, { ...key, attempts: key.attempts + 1 });
+        return true;
+    }
+
+    /** Pop the next body-fetch task at or above `maxLane`. Used by the
+     *  reconciler to drain interactive clicks before prefetch backfill. */
+    nextBodyFetch(maxLane: Lane = "backfill"): BodyFetchKey | null {
+        const rank: Record<Lane, number> = { interactive: 0, sync: 1, prefetch: 2, backfill: 3 };
+        const cap = rank[maxLane];
+        let best: BodyFetchKey | null = null;
+        for (const v of this.bodyFetches.values()) {
+            if (rank[v.lane] > cap) continue;
+            if (!best || rank[v.lane] < rank[best.lane]) best = v;
+        }
+        if (best) this.bodyFetches.delete(`${best.accountId}:${best.folderId}:${best.uid}`);
+        return best;
+    }
+
+    /** Pending count for diagnostics + the sync-status pill. */
+    pendingCount(): { messageActions: number; bodyFetches: number } {
+        return {
+            messageActions: this.db.getTotalPendingSyncCount(),
+            bodyFetches: this.bodyFetches.size,
+        };
+    }
+}