@bobfrankston/mailx-sync 0.1.22 → 0.1.24

package/gmail.d.ts

@@ -71,6 +71,26 @@ export declare class GmailApiProvider implements MailProvider {
     /** Folder path → Gmail label id. System folders map to uppercase label
      *  constants; anything else is treated as a user label (identical name). */
     private folderPathToLabelId;
+    /** Gmail system label ids that the API forbids renaming — labels.patch on
+     *  any of these returns 400. The folder tree must refuse a rename of the
+     *  folders that map to them. */
+    private static readonly SYSTEM_LABELS;
+    /** Rename (and/or reparent) a Gmail label. Gmail has no folders — a
+     *  "folder" is a label and the hierarchy is encoded in the label NAME as a
+     *  slash-path ("Parent/Child"). So both rename-in-place and reparent are the
+     *  same operation: PATCH the label to a new full name.
+     *
+     *  - `oldPath` is the current label name (== path in our folder model).
+     *  - `newName` is the new LEAF name.
+     *  - `newParentPath` (optional) is the destination parent label's path; when
+     *    given, the new full name becomes `<newParentPath>/<newName>`, otherwise
+     *    we keep the old parent prefix and just swap the leaf.
+     *
+     *  System labels (INBOX/SENT/…) can't be renamed — reject with a clear
+     *  message the UI surfaces. We resolve the label id from the live label list
+     *  rather than trusting name-as-id, because a user label's id is an opaque
+     *  `Label_NN` on some accounts even though the name matches. */
+    renameFolder(oldPath: string, newName: string, newParentPath?: string): Promise<void>;
     getUids(folder: string): Promise<number[]>;
     close(): Promise<void>;
     /** Map folder path to Gmail label query term */

package/gmail.js

@@ -322,7 +322,18 @@ export class GmailApiProvider {
         // is self-limiting. Otherwise cap at the recent 200.
         const cap = options.since ? 0 : 200;
         const ids = await this.listMessageIds(query, cap);
-        return this.batchFetch(ids, options);
+        // Skip IDs already in the local store: the listing above is one cheap
+        // call, but fetching each message's metadata is a sequential per-ID GET
+        // (~200ms). Without this, a routine sync re-fetched all ~200 recent
+        // messages every time (~40s) just to discover nothing was new. With the
+        // caller's known-UID set, steady state fetches zero (Bob 2026-06-27).
+        const fresh = options.knownUids
+            ? ids.filter(id => !options.knownUids.has(idToUid(id)))
+            : ids;
+        if (options.knownUids) {
+            console.log(`[gmail] fetchSince ${folder}: ${ids.length} listed, ${ids.length - fresh.length} already stored, fetching ${fresh.length}`);
+        }
+        return this.batchFetch(fresh, options);
     }
     async fetchByDate(folder, since, before, options = {}, onChunk) {
         const afterDate = this.formatDate(since);
@@ -630,6 +641,49 @@ export class GmailApiProvider {
             return ""; // no-op — archive is absence-of-INBOX
         return path; // user label — name-as-id
     }
+    /** Gmail system label ids that the API forbids renaming — labels.patch on
+     *  any of these returns 400. The folder tree must refuse a rename of the
+     *  folders that map to them. */
+    static SYSTEM_LABELS = new Set([
+        "INBOX", "SENT", "DRAFT", "TRASH", "SPAM", "CHAT",
+        "IMPORTANT", "STARRED", "UNREAD",
+    ]);
+    /** Rename (and/or reparent) a Gmail label. Gmail has no folders — a
+     *  "folder" is a label and the hierarchy is encoded in the label NAME as a
+     *  slash-path ("Parent/Child"). So both rename-in-place and reparent are the
+     *  same operation: PATCH the label to a new full name.
+     *
+     *  - `oldPath` is the current label name (== path in our folder model).
+     *  - `newName` is the new LEAF name.
+     *  - `newParentPath` (optional) is the destination parent label's path; when
+     *    given, the new full name becomes `<newParentPath>/<newName>`, otherwise
+     *    we keep the old parent prefix and just swap the leaf.
+     *
+     *  System labels (INBOX/SENT/…) can't be renamed — reject with a clear
+     *  message the UI surfaces. We resolve the label id from the live label list
+     *  rather than trusting name-as-id, because a user label's id is an opaque
+     *  `Label_NN` on some accounts even though the name matches. */
+    async renameFolder(oldPath, newName, newParentPath) {
+        const sysId = this.folderPathToLabelId(oldPath);
+        if (GmailApiProvider.SYSTEM_LABELS.has(sysId) || sysId === "" /* All Mail */) {
+            throw new Error(`"${oldPath}" is a Gmail system label and can't be renamed.`);
+        }
+        const data = await this.fetch("/labels");
+        const labels = data.labels || [];
+        const match = labels.find(l => l.name === oldPath);
+        if (!match)
+            throw new Error(`Gmail label "${oldPath}" not found`);
+        if (match.type === "system") {
+            throw new Error(`"${oldPath}" is a Gmail system label and can't be renamed.`);
+        }
+        const newFullName = (newParentPath && newParentPath.length)
+            ? `${newParentPath}/${newName}`
+            : (oldPath.includes("/") ? `${oldPath.slice(0, oldPath.lastIndexOf("/"))}/${newName}` : newName);
+        await this.fetch(`/labels/${match.id}`, {
+            method: "PATCH",
+            body: JSON.stringify({ name: newFullName }),
+        });
+    }
     async getUids(folder) {
         const query = `in:${this.folderToLabel(folder)}`;
         const ids = await this.listMessageIds(query, 10000);

package/outlook.d.ts

@@ -1,37 +1,138 @@
 /**
  * Microsoft Graph API provider — replaces IMAP for Outlook.com/Office 365 accounts.
- * Uses Graph API for reliable, fast mail sync.
+ * Uses Graph API for reliable, fast mail sync with native write-back.
  *
  * SOURCE OF TRUTH: this file is the canonical Outlook provider for mailx.
  * Same Provider abstraction as Gmail and IMAP, lives alongside them so future
  * Android Outlook support uses the same code with no re-implementation.
- * Currently only desktop instantiates it.
  *
- * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews).
- * No Node-specific imports.
+ * Modeled on gmail.ts (the gold-standard provider): shared module-level token
+ * bucket, robust 429/5xx retry with Retry-After + shared cooldown + terminal
+ * cooldown, and provider_id-first identity for every per-message op. Graph's
+ * string IDs ARE identity; the integer uid is a sort/display convenience only.
+ * See the imap_uid_not_identity lesson — any per-message op keyed solely by the
+ * hashed uid must list-and-hash, which is capped and breaks on large folders,
+ * so we always prefer the caller-supplied Graph id.
+ *
+ * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews),
+ * atob/btoa, Uint8Array, TextDecoder, TextEncoder. No Node-specific imports
+ * (no node:*, no Buffer) — this runs in the Android WebView too.
  */
 import type { MailProvider, ProviderFolder, ProviderMessage, FetchOptions } from "./types.js";
 export declare class OutlookApiProvider implements MailProvider {
     private tokenProvider;
     constructor(tokenProvider: () => Promise<string>);
+    /** Hierarchical display path → Graph folder id, plus id → id (self) so a raw
+     *  Graph id passed back in still resolves. Populated by listFolders. Instance-
+     *  scoped (not module-shared like rateState) because folder ids are per-
+     *  mailbox: two accounts share throttle state but never folder identity. */
+    private folderIds;
+    /** Turn whatever the dispatcher hands us (a hierarchical display path like
+     *  "Projects/2026/Invoices", a Graph well-known name, or a raw Graph id)
+     *  into a Graph folder id usable in a /mailFolders/{id} URL or as a move
+     *  destinationId. Disambiguation order:
+     *    (a) Graph well-known name (inbox/drafts/…) → pass through; it IS an id.
+     *    (b) Known hierarchical path or already-an-id in the map → mapped id.
+     *    (c) Map empty (fresh instance — listFolders hasn't run this session,
+     *        as happens for move/rename which never list first) → list once to
+     *        populate, then re-check.
+     *    (d) Still unknown → return as-is (back-compat: assume it's a raw Graph
+     *        id we simply haven't catalogued, e.g. a destination outside the
+     *        listed set). */
+    private resolveFolder;
+    /** Block until (a) cooldown has elapsed and (b) a token is available.
+     *  Token-bucket refill happens lazily on each call. Copy of gmail.ts's
+     *  acquireToken so all providers share one throttling discipline. */
+    private acquireToken;
+    /** Compute a retry delay from the attempt number + an optional Retry-After
+     *  header (seconds OR HTTP-date). Full jitter, capped. Shared by the JSON
+     *  fetch and the raw fetch so both back off identically. Graph signals
+     *  throttling via 429 + Retry-After — it has no 403-quota equivalent, so
+     *  (unlike gmail.ts) there's no quota-403 branch. */
+    private retryDelay;
     private fetch;
-    /** Fetch raw bytes (for RFC 2822 $value endpoint) */
+    /** Fetch raw bytes (for RFC 2822 $value endpoint). Goes through the same
+     *  acquireToken + 429/5xx retry discipline as the JSON fetch — a body
+     *  prefetch must not side-step the throttle and re-trigger a cooldown. */
     private fetchRaw;
     listFolders(): Promise<ProviderFolder[]>;
+    /** Recurse into child folders. `parentPath` is the HIERARCHICAL display path
+     *  of the parent (e.g. "Projects/2026"), so a child's path nests fully
+     *  ("Projects/2026/Invoices") rather than flattening to one level. */
     private fetchChildFolders;
     /** Convert Graph message to ProviderMessage */
     private parseMessage;
-    /** Stable integer UID from Graph string ID */
+    /** Stable integer UID from Graph string ID. NOT identity — only a
+     *  sort/display convenience. Every per-message op prefers the Graph id. */
     private idToUid;
-    /** List messages in a folder with optional date filter */
+    /** List messages in a folder with optional $filter. Tracks whether
+     *  pagination was capped so getUids can flag truncation for reconcile. */
     private listMessages;
     fetchSince(folder: string, sinceUid: number, options?: FetchOptions): Promise<ProviderMessage[]>;
     fetchByDate(folder: string, since: Date, before: Date, options?: FetchOptions, onChunk?: (msgs: ProviderMessage[]) => void): Promise<ProviderMessage[]>;
     fetchByUids(folder: string, uids: number[], options?: FetchOptions): Promise<ProviderMessage[]>;
     fetchOne(folder: string, uid: number, options?: FetchOptions): Promise<ProviderMessage | null>;
+    /** Bulk-fetch raw bodies for many UIDs in one folder. Lists the folder
+     *  once to build a uid→Graph-id map, then pulls each wanted message's MIME
+     *  via /$value with bounded concurrency (4 workers). We deliberately do NOT
+     *  use Graph $batch multipart here: bounded-concurrency individual GETs are
+     *  simpler and Graph's per-request reliability doesn't need the fragile
+     *  multipart parsing. Mirrors gmail.ts's fetchBodiesIndividually shape. */
+    fetchBodiesBatch(folder: string, uids: number[], onBody: (uid: number, source: string) => void): Promise<void>;
+    /** Apply the absolute flag state to a message. Graph model: isRead boolean
+     *  + flag.flagStatus. We send both so the end state matches regardless of
+     *  prior state (idempotent, safe to retry). */
+    setFlags(folder: string, uid: number, flags: string[], providerId?: string): Promise<void>;
+    /** Move a message to Deleted Items. Graph's well-known folder name
+     *  "deleteditems" is accepted as a move destination. */
+    trashMessage(folder: string, uid: number, providerId?: string): Promise<void>;
+    /** Move a message to another folder. `toFolder` is the client's `path` (a
+     *  hierarchical display path) — resolve it to the Graph destination id. The
+     *  source folder is only needed for the resolveId list-and-hash fallback,
+     *  which resolveFolder handles internally via listMessages. */
+    moveMessage(fromFolder: string, uid: number, toFolder: string, providerId?: string): Promise<void>;
+    /** POST /messages/{id}/move, treating 404 as already-done.
+     *
+     *  CRITICAL (differs from Gmail): a Graph move returns a NEW message id in
+     *  the destination — the source id we hold becomes invalid. So if a move
+     *  succeeds server-side but the ACK is lost, the queued retry re-fires with
+     *  the now-stale id and Graph answers 404. Throwing there would exhaust the
+     *  sync-action retries and `clearTombstoneForUid` would RESURRECT a message
+     *  that was actually moved (the exact "deletions un-happening" class the
+     *  Gmail provider_id fix killed). A 404 on a move means "it's no longer
+     *  here" — which is the goal — so we swallow it as success. */
+    private moveById;
+    /** Rename and/or reparent a mail folder. `folderPath` and `newParentPath`
+     *  are the client's hierarchical display paths — resolve each to its Graph
+     *  id before use.
+     *
+     *  - Rename: PATCH /mailFolders/{id} { displayName }.
+     *  - Reparent: POST /mailFolders/{id}/move { destinationId }.
+     *  Both can apply in one call: move first (so the folder lands under the new
+     *  parent), then patch the display name.
+     *
+     *  Well-known folders (inbox/sentitems/drafts/deleteditems/junkemail/archive)
+     *  must not be renamed — Graph rejects it, and it would corrupt the special-
+     *  use mapping. We guard on both the well-known name (the path may be the bare
+     *  name) and the folder's leaf display name, lower-cased. */
+    renameFolder(folderPath: string, newName: string, newParentPath?: string): Promise<void>;
+    /** Send a full RFC822 MIME message via Graph's /sendMail. Graph accepts a
+     *  base64-encoded MIME payload when the request Content-Type is text/plain
+     *  and the body is the base64 string. We don't route this through the JSON
+     *  fetch() helper (different content type) but still acquire a token and
+     *  apply a simple inline retry. */
+    sendRaw(mime: string): Promise<void>;
+    /** Resolve a Graph message id: prefer the caller-supplied provider_id;
+     *  otherwise list-and-hash (capped) and throw if not found. Centralizes the
+     *  rationale shared by setFlags/trash/move — the cap means a write to a
+     *  message past the most-recent ~1000 fails loudly rather than silently
+     *  hitting the wrong message. */
+    private resolveId;
     getUids(folder: string): Promise<number[]>;
     close(): Promise<void>;
-    /** Add RFC 2822 source to messages (batch) */
+    /** Add RFC 2822 source to messages by pulling each /$value. Sequential —
+     *  bodies-with-source paths are already date- or uid-bounded so the count
+     *  is small; bulk prefetch uses fetchBodiesBatch's worker pool instead. */
     private addSources;
 }
 //# sourceMappingURL=outlook.d.ts.map

package/outlook.js

@@ -1,14 +1,22 @@
 /**
  * Microsoft Graph API provider — replaces IMAP for Outlook.com/Office 365 accounts.
- * Uses Graph API for reliable, fast mail sync.
+ * Uses Graph API for reliable, fast mail sync with native write-back.
  *
  * SOURCE OF TRUTH: this file is the canonical Outlook provider for mailx.
  * Same Provider abstraction as Gmail and IMAP, lives alongside them so future
  * Android Outlook support uses the same code with no re-implementation.
- * Currently only desktop instantiates it.
  *
- * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews).
- * No Node-specific imports.
+ * Modeled on gmail.ts (the gold-standard provider): shared module-level token
+ * bucket, robust 429/5xx retry with Retry-After + shared cooldown + terminal
+ * cooldown, and provider_id-first identity for every per-message op. Graph's
+ * string IDs ARE identity; the integer uid is a sort/display convenience only.
+ * See the imap_uid_not_identity lesson — any per-message op keyed solely by the
+ * hashed uid must list-and-hash, which is capped and breaks on large folders,
+ * so we always prefer the caller-supplied Graph id.
+ *
+ * Platform requirements: globalThis.fetch (Node 18+ and all browsers/WebViews),
+ * atob/btoa, Uint8Array, TextDecoder, TextEncoder. No Node-specific imports
+ * (no node:*, no Buffer) — this runs in the Android WebView too.
  */
 const GRAPH = "https://graph.microsoft.com/v1.0/me";
 /** Map Graph well-known folder names to specialUse */
@@ -20,37 +28,208 @@ const WELL_KNOWN = {
     junkemail: "junk",
     archive: "archive",
 };
+/** Rate-limit + cooldown state shared across all OutlookApiProvider instances.
+ *  Graph throttles per mailbox/app, not per JS object, so sharing state here
+ *  prevents a fresh `new OutlookApiProvider(...)` from side-stepping the
+ *  cooldown by creating a new instance. Single-account setups won't notice;
+ *  multi-account setups are slightly over-throttled, which is safer than
+ *  burning through Graph's tolerance. Mirrors gmail.ts's rateState exactly. */
+const rateState = {
+    tokens: 0,
+    lastRefill: 0,
+    cooldownUntil: 0,
+    /** Tokens refilled per second (keeps us well under Graph's per-app caps). */
+    rate: 8,
+    /** Max burst above steady state. */
+    burst: 8,
+};
+rateState.tokens = rateState.burst;
+rateState.lastRefill = Date.now();
+/** Base64-encode raw bytes without Node's Buffer. btoa wants a binary string
+ *  (one char per byte); building it with String.fromCharCode(...wholeArray)
+ *  blows the call-stack on large MIME, so we chunk. Used for /sendMail, where
+ *  Graph expects the full RFC822 message as a base64 payload. */
+function toBase64(bytes) {
+    let binary = "";
+    const CHUNK = 0x8000; // 32 KB per fromCharCode call — safely under arg limits
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        const slice = bytes.subarray(i, i + CHUNK);
+        binary += String.fromCharCode.apply(null, slice);
+    }
+    return btoa(binary);
+}
+/** Graph well-known folder identifiers. These strings are valid folder ids in
+ *  any /mailFolders/{id} URL or move destinationId — Graph accepts them
+ *  interchangeably with the opaque GUID. resolveFolder lets them pass through
+ *  untouched so callers (trash → "deleteditems") work even on a fresh instance
+ *  whose hierarchical-path map hasn't been populated yet. */
+const WELL_KNOWN_IDS = new Set([
+    "inbox", "drafts", "sentitems", "deleteditems", "junkemail", "archive",
+]);
 export class OutlookApiProvider {
     tokenProvider;
     constructor(tokenProvider) {
         this.tokenProvider = tokenProvider;
     }
+    /** Hierarchical display path → Graph folder id, plus id → id (self) so a raw
+     *  Graph id passed back in still resolves. Populated by listFolders. Instance-
+     *  scoped (not module-shared like rateState) because folder ids are per-
+     *  mailbox: two accounts share throttle state but never folder identity. */
+    folderIds = new Map();
+    /** Turn whatever the dispatcher hands us (a hierarchical display path like
+     *  "Projects/2026/Invoices", a Graph well-known name, or a raw Graph id)
+     *  into a Graph folder id usable in a /mailFolders/{id} URL or as a move
+     *  destinationId. Disambiguation order:
+     *    (a) Graph well-known name (inbox/drafts/…) → pass through; it IS an id.
+     *    (b) Known hierarchical path or already-an-id in the map → mapped id.
+     *    (c) Map empty (fresh instance — listFolders hasn't run this session,
+     *        as happens for move/rename which never list first) → list once to
+     *        populate, then re-check.
+     *    (d) Still unknown → return as-is (back-compat: assume it's a raw Graph
+     *        id we simply haven't catalogued, e.g. a destination outside the
+     *        listed set). */
+    async resolveFolder(pathOrId) {
+        if (WELL_KNOWN_IDS.has(pathOrId))
+            return pathOrId;
+        const hit = this.folderIds.get(pathOrId);
+        if (hit)
+            return hit;
+        if (this.folderIds.size === 0) {
+            // Lazy populate: move/rename are reached without a prior listFolders
+            // on a fresh provider instance. One list call fills the map.
+            await this.listFolders();
+            const after = this.folderIds.get(pathOrId);
+            if (after)
+                return after;
+        }
+        return pathOrId;
+    }
+    /** Block until (a) cooldown has elapsed and (b) a token is available.
+     *  Token-bucket refill happens lazily on each call. Copy of gmail.ts's
+     *  acquireToken so all providers share one throttling discipline. */
+    async acquireToken() {
+        // Respect an active cooldown first — refuse to even try until it ends.
+        const now = Date.now();
+        if (rateState.cooldownUntil > now) {
+            const waitMs = rateState.cooldownUntil - now;
+            console.log(`  [outlook] cooldown: waiting ${(waitMs / 1000).toFixed(1)}s before next request`);
+            await new Promise(r => setTimeout(r, waitMs));
+        }
+        // Lazy refill, then spin-wait in chunks until a token is ready.
+        while (true) {
+            const t = Date.now();
+            const elapsedSec = (t - rateState.lastRefill) / 1000;
+            rateState.tokens = Math.min(rateState.burst, rateState.tokens + elapsedSec * rateState.rate);
+            rateState.lastRefill = t;
+            if (rateState.tokens >= 1) {
+                rateState.tokens -= 1;
+                return;
+            }
+            const waitMs = Math.max(20, ((1 - rateState.tokens) / rateState.rate) * 1000);
+            await new Promise(r => setTimeout(r, waitMs));
+        }
+    }
+    /** Compute a retry delay from the attempt number + an optional Retry-After
+     *  header (seconds OR HTTP-date). Full jitter, capped. Shared by the JSON
+     *  fetch and the raw fetch so both back off identically. Graph signals
+     *  throttling via 429 + Retry-After — it has no 403-quota equivalent, so
+     *  (unlike gmail.ts) there's no quota-403 branch. */
+    retryDelay(attempt, retryAfter) {
+        const baseDelayMs = 1000;
+        const maxDelayMs = 60_000;
+        let delay = baseDelayMs * Math.pow(2, attempt);
+        if (retryAfter) {
+            const asInt = parseInt(retryAfter, 10);
+            if (!isNaN(asInt))
+                delay = asInt * 1000;
+            else {
+                const when = Date.parse(retryAfter);
+                if (!isNaN(when))
+                    delay = Math.max(0, when - Date.now());
+            }
+        }
+        delay = Math.min(maxDelayMs, delay);
+        // Full jitter to avoid synchronized retries across parallel workers.
+        return Math.floor(delay * (0.5 + Math.random() * 0.5));
+    }
     async fetch(path, options = {}) {
         const token = await this.tokenProvider();
-        const res = await globalThis.fetch(`${GRAPH}${path}`, {
-            ...options,
-            headers: {
-                "Authorization": `Bearer ${token}`,
-                "Content-Type": "application/json",
-                ...options.headers,
-            },
-        });
-        if (!res.ok) {
-            const err = await res.text().catch(() => "");
-            throw new Error(`Graph API ${res.status}: ${err.substring(0, 200)}`);
+        const maxAttempts = 6;
+        let lastStatus = 0;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            await this.acquireToken();
+            const res = await globalThis.fetch(`${GRAPH}${path}`, {
+                ...options,
+                headers: {
+                    "Authorization": `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    ...options.headers,
+                },
+            });
+            // Graph throttling = 429 with Retry-After. Treat 5xx the same way:
+            // transient server-side, worth a backed-off retry.
+            if (res.status === 429 || res.status >= 500) {
+                lastStatus = res.status;
+                const retryAfter = res.headers.get("Retry-After");
+                const delay = this.retryDelay(attempt, retryAfter);
+                // Install a shared cooldown so *other* in-flight workers wait
+                // too, not just this one. Prevents 5 parallel workers each
+                // retrying independently and keeping the mailbox throttled.
+                rateState.cooldownUntil = Math.max(rateState.cooldownUntil, Date.now() + delay);
+                console.log(`  [outlook] ${res.status} (attempt ${attempt + 1}/${maxAttempts}), waiting ${(delay / 1000).toFixed(1)}s${retryAfter ? ` (Retry-After: ${retryAfter})` : ""}...`);
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            if (!res.ok) {
+                const err = await res.text().catch(() => "");
+                throw new Error(`Graph API ${res.status}: ${err.substring(0, 200)}`);
+            }
+            // 204 No Content (PATCH/move/etc.) has no JSON body — don't choke.
+            if (res.status === 204)
+                return null;
+            const text = await res.text();
+            return text ? JSON.parse(text) : null;
         }
-        return res.json();
+        // Exhausted all retries — Graph is clearly throttling hard. Park every
+        // subsequent request behind a long cooldown so the next periodic sync
+        // doesn't immediately fire another 6 retries into the same limit.
+        // 5 minutes is a floor — a longer incoming Retry-After still wins via
+        // the per-attempt cooldown set above.
+        const TERMINAL_COOLDOWN_MS = 5 * 60_000;
+        rateState.cooldownUntil = Math.max(rateState.cooldownUntil, Date.now() + TERMINAL_COOLDOWN_MS);
+        console.log(`  [outlook] exhausted ${maxAttempts} retries — parking further requests for ${TERMINAL_COOLDOWN_MS / 1000}s`);
+        throw new Error(`Graph API: failed after ${maxAttempts} retries (last status ${lastStatus})`);
     }
-    /** Fetch raw bytes (for RFC 2822 $value endpoint) */
+    /** Fetch raw bytes (for RFC 2822 $value endpoint). Goes through the same
+     *  acquireToken + 429/5xx retry discipline as the JSON fetch — a body
+     *  prefetch must not side-step the throttle and re-trigger a cooldown. */
     async fetchRaw(path) {
         const token = await this.tokenProvider();
-        const res = await globalThis.fetch(`${GRAPH}${path}`, {
-            headers: { "Authorization": `Bearer ${token}` },
-        });
-        if (!res.ok) {
-            throw new Error(`Graph API ${res.status} on raw fetch`);
+        const maxAttempts = 6;
+        let lastStatus = 0;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            await this.acquireToken();
+            const res = await globalThis.fetch(`${GRAPH}${path}`, {
+                headers: { "Authorization": `Bearer ${token}` },
+            });
+            if (res.status === 429 || res.status >= 500) {
+                lastStatus = res.status;
+                const retryAfter = res.headers.get("Retry-After");
+                const delay = this.retryDelay(attempt, retryAfter);
+                rateState.cooldownUntil = Math.max(rateState.cooldownUntil, Date.now() + delay);
+                console.log(`  [outlook raw] ${res.status} (attempt ${attempt + 1}/${maxAttempts}), waiting ${(delay / 1000).toFixed(1)}s${retryAfter ? ` (Retry-After: ${retryAfter})` : ""}...`);
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            if (!res.ok) {
+                const err = await res.text().catch(() => "");
+                throw new Error(`Graph API ${res.status} on raw fetch: ${err.substring(0, 200)}`);
+            }
+            return res.text();
         }
-        return res.text();
+        const TERMINAL_COOLDOWN_MS = 5 * 60_000;
+        rateState.cooldownUntil = Math.max(rateState.cooldownUntil, Date.now() + TERMINAL_COOLDOWN_MS);
+        throw new Error(`Graph API raw: failed after ${maxAttempts} retries (last status ${lastStatus})`);
     }
     async listFolders() {
         const folders = [];
@@ -58,17 +237,29 @@ export class OutlookApiProvider {
         while (url) {
             const data = await this.fetch(url);
             for (const f of data.value || []) {
+                const name = f.displayName || f.id;
                 const specialUse = WELL_KNOWN[f.displayName?.toLowerCase()] || "";
+                // Top-level path is just the display name. The client builds its
+                // folder TREE by splitting `path` on the delimiter, so `path`
+                // must be the HIERARCHICAL display path, not the flat Graph id —
+                // otherwise the whole tree collapses to one level and same-leaf-
+                // name folders under different parents look like duplicates.
+                const path = name;
                 folders.push({
-                    path: f.id,
-                    name: f.displayName || f.id,
+                    path,
+                    name,
                     delimiter: "/",
                     specialUse,
                     flags: [],
                 });
-                // Fetch child folders
+                // Record both directions so resolveFolder can turn the path back
+                // into a Graph id, and a raw id round-trips unchanged.
+                this.folderIds.set(path, f.id);
+                this.folderIds.set(f.id, f.id);
+                // Fetch child folders — pass the hierarchical path (not the bare
+                // display name) so deep paths nest correctly.
                 if (f.childFolderCount > 0) {
-                    const children = await this.fetchChildFolders(f.id, f.displayName);
+                    const children = await this.fetchChildFolders(f.id, path);
                     folders.push(...children);
                 }
             }
@@ -76,22 +267,34 @@ export class OutlookApiProvider {
         }
         return folders;
     }
-    async fetchChildFolders(parentId, parentName) {
+    /** Recurse into child folders. `parentPath` is the HIERARCHICAL display path
+     *  of the parent (e.g. "Projects/2026"), so a child's path nests fully
+     *  ("Projects/2026/Invoices") rather than flattening to one level. */
+    async fetchChildFolders(parentId, parentPath) {
         const folders = [];
-        const data = await this.fetch(`/mailFolders/${parentId}/childFolders?$top=100`);
-        for (const f of data.value || []) {
-            const path = `${parentName}/${f.displayName}`;
-            folders.push({
-                path: f.id,
-                name: f.displayName,
-                delimiter: "/",
-                specialUse: "",
-                flags: [],
-            });
-            if (f.childFolderCount > 0) {
-                const children = await this.fetchChildFolders(f.id, path);
-                folders.push(...children);
+        let url = `/mailFolders/${parentId}/childFolders?$top=100`;
+        while (url) {
+            const data = await this.fetch(url);
+            for (const f of data.value || []) {
+                const name = f.displayName || f.id;
+                // Child path = parent's hierarchical path + this leaf, joined by
+                // the delimiter the client splits on.
+                const path = `${parentPath}/${name}`;
+                folders.push({
+                    path,
+                    name,
+                    delimiter: "/",
+                    specialUse: "",
+                    flags: [],
+                });
+                this.folderIds.set(path, f.id);
+                this.folderIds.set(f.id, f.id);
+                if (f.childFolderCount > 0) {
+                    const children = await this.fetchChildFolders(f.id, path);
+                    folders.push(...children);
+                }
             }
+            url = data["@odata.nextLink"]?.replace(`${GRAPH}`, "") || "";
         }
         return folders;
     }
@@ -101,12 +304,12 @@ export class OutlookApiProvider {
             ? [{ name: msg.from.emailAddress.name, address: msg.from.emailAddress.address }]
             : [];
         const to = (msg.toRecipients || []).map((r) => ({
-            name: r.emailAddress?.name, address: r.emailAddress?.address
+            name: r.emailAddress?.name, address: r.emailAddress?.address,
         }));
         const cc = (msg.ccRecipients || []).map((r) => ({
-            name: r.emailAddress?.name, address: r.emailAddress?.address
+            name: r.emailAddress?.name, address: r.emailAddress?.address,
         }));
-        // Graph uses string IDs — hash to integer UID
+        // Graph uses string IDs — hash to integer UID for sort/display.
         const uid = this.idToUid(msg.id);
         return {
             uid,
@@ -115,6 +318,13 @@ export class OutlookApiProvider {
             date: msg.receivedDateTime ? new Date(msg.receivedDateTime) : null,
             subject: msg.subject || "",
             from, to, cc,
+            // Threading headers aren't reliably returned on the list path
+            // ($select=...,internetMessageHeaders is flaky / requires a per-item
+            // expand). We leave them empty here; the full MIME pulled by
+            // fetchOne/$value or fetchBodiesBatch carries In-Reply-To/References,
+            // so threading is recovered downstream from the raw source.
+            inReplyTo: "",
+            references: [],
             seen: msg.isRead === true,
             flagged: msg.flag?.flagStatus === "flagged",
             answered: false,
@@ -123,34 +333,67 @@ export class OutlookApiProvider {
             source,
         };
     }
-    /** Stable integer UID from Graph string ID */
+    /** Stable integer UID from Graph string ID. NOT identity — only a
+     *  sort/display convenience. Every per-message op prefers the Graph id. */
     idToUid(id) {
-        // Graph IDs are long base64 strings — hash to 48-bit int
+        // Graph IDs are long base64 strings — hash to a positive int.
         let hash = 0;
         for (let i = 0; i < id.length; i++) {
             hash = ((hash << 5) - hash + id.charCodeAt(i)) | 0;
         }
         return Math.abs(hash);
     }
-    /** List messages in a folder with optional date filter */
-    async listMessages(folderId, filter = "", top = 500) {
+    /** List messages in a folder with optional $filter. Tracks whether
+     *  pagination was capped so getUids can flag truncation for reconcile. */
+    async listMessages(folderId, filter = "", top = 500, ordered = true) {
+        // folderId may be a hierarchical display path (the client's `path`) — map
+        // it back to the Graph id this URL needs. Resolving here covers every
+        // read path: fetchSince/fetchByDate/fetchByUids/getUids/fetchBodiesBatch
+        // and the fetchOne/resolveId list-and-hash fallbacks all route through.
+        const id = await this.resolveFolder(folderId);
         const messages = [];
         const select = "id,subject,from,toRecipients,ccRecipients,receivedDateTime,isRead,isDraft,flag,internetMessageId,hasAttachments";
-        let url = `/mailFolders/${folderId}/messages?$select=${select}&$top=${Math.min(top, 100)}&$orderby=receivedDateTime desc`;
+        // $orderby is only worth its cost when the caller needs newest-first
+        // (the display/sync fetches). For id-only sweeps (getUids,
+        // fetchBodiesBatch, resolveId) order is irrelevant, and Graph can throw
+        // InefficientFilter when $orderby is combined with deep pagination of a
+        // large unfiltered folder — so those callers pass ordered=false.
+        let url = `/mailFolders/${id}/messages?$select=${select}&$top=${Math.min(top, 100)}`;
+        if (ordered)
+            url += `&$orderby=receivedDateTime desc`;
         if (filter)
-            url += `&$filter=${filter}`;
-        while (url && messages.length < top) {
+            url += `&$filter=${encodeURIComponent(filter)}`;
+        let truncated = false;
+        while (url) {
             const data = await this.fetch(url);
             messages.push(...(data.value || []));
-            url = data["@odata.nextLink"]?.replace(`${GRAPH}`, "") || "";
+            const next = data["@odata.nextLink"]?.replace(`${GRAPH}`, "") || "";
+            if (!next)
+                break;
+            if (messages.length >= top) {
+                // Hit the caller's cap but the server has more pages. Flag it
+                // so reconcile-style callers refuse to treat this as complete.
+                truncated = true;
+                break;
+            }
+            url = next;
         }
+        messages._truncated = truncated;
         return messages;
     }
     async fetchSince(folder, sinceUid, options = {}) {
-        // Fetch recent messages — caller filters by UID
-        const msgs = await this.listMessages(folder, "", 200);
+        // The hashed uid is NOT monotonic — filtering `m.uid > sinceUid`
+        // silently drops new mail whose hash falls below the high-water mark
+        // (same trap gmail.ts documents). When the caller bounds by date, use
+        // a receivedDateTime filter; otherwise just return the recent page and
+        // let the caller reconcile by Graph id.
+        void sinceUid;
+        const filter = options.since ? `receivedDateTime ge ${options.since.toISOString()}` : "";
+        const cap = options.since ? 0 : 200;
+        // cap 0 → effectively unbounded (date filter is self-limiting); use a
+        // high ceiling so listMessages still terminates.
+        const msgs = await this.listMessages(folder, filter, cap === 0 ? 10000 : cap);
         let results = msgs.map(m => this.parseMessage(m));
-        results = results.filter(m => m.uid > sinceUid);
         if (options.source) {
             results = await this.addSources(results);
         }
@@ -158,7 +401,8 @@ export class OutlookApiProvider {
     }
     async fetchByDate(folder, since, before, options = {}, onChunk) {
         const filter = `receivedDateTime ge ${since.toISOString()} and receivedDateTime lt ${before.toISOString()}`;
-        const msgs = await this.listMessages(folder, filter);
+        // Date-bounded — let pagination drain the full range (high ceiling).
+        const msgs = await this.listMessages(folder, filter, 10000);
         const all = [];
         const chunkSize = 25;
         for (let i = 0; i < msgs.length; i += chunkSize) {
@@ -175,7 +419,7 @@ export class OutlookApiProvider {
     }
     async fetchByUids(folder, uids, options = {}) {
         const uidSet = new Set(uids);
-        const msgs = await this.listMessages(folder, "", 1000);
+        const msgs = await this.listMessages(folder, "", 10000, false);
         let results = msgs.map(m => this.parseMessage(m)).filter(m => uidSet.has(m.uid));
         if (options.source) {
             results = await this.addSources(results);
@@ -183,22 +427,236 @@ export class OutlookApiProvider {
         return results;
     }
     async fetchOne(folder, uid, options = {}) {
-        const msgs = await this.listMessages(folder, "", 500);
-        const msg = msgs.find(m => this.idToUid(m.id) === uid);
-        if (!msg)
+        // Caller passes providerId straight from the DB row when available —
+        // skips the list-the-whole-folder round trip entirely (mirrors
+        // gmail.ts). With the Graph id we GET the message directly, and pull
+        // the full MIME via /$value only when source is requested.
+        const id = options.providerId;
+        if (id) {
+            const select = "id,subject,from,toRecipients,ccRecipients,receivedDateTime,isRead,isDraft,flag,internetMessageId,hasAttachments";
+            const msg = await this.fetch(`/messages/${id}?$select=${select}`);
+            if (!msg)
+                return null;
+            let source = "";
+            if (options.source) {
+                source = await this.fetchRaw(`/messages/${id}/$value`);
+            }
+            return this.parseMessage(msg, source);
+        }
+        // Fallback: no providerId — list-and-hash, capped. Warn because this is
+        // the slow/lossy path (a message past the cap won't be found).
+        console.warn(`  [outlook] fetchOne UID ${uid} in ${folder}: no providerId, falling back to capped list-and-hash`);
+        const msgs = await this.listMessages(folder, "", 1000, false);
+        const found = msgs.find(m => this.idToUid(m.id) === uid);
+        if (!found)
             return null;
         let source = "";
         if (options.source) {
-            source = await this.fetchRaw(`/messages/${msg.id}/$value`);
+            source = await this.fetchRaw(`/messages/${found.id}/$value`);
+        }
+        return this.parseMessage(found, source);
+    }
+    /** Bulk-fetch raw bodies for many UIDs in one folder. Lists the folder
+     *  once to build a uid→Graph-id map, then pulls each wanted message's MIME
+     *  via /$value with bounded concurrency (4 workers). We deliberately do NOT
+     *  use Graph $batch multipart here: bounded-concurrency individual GETs are
+     *  simpler and Graph's per-request reliability doesn't need the fragile
+     *  multipart parsing. Mirrors gmail.ts's fetchBodiesIndividually shape. */
+    async fetchBodiesBatch(folder, uids, onBody) {
+        if (uids.length === 0)
+            return;
+        const msgs = await this.listMessages(folder, "", 10000, false);
+        const uidToId = new Map();
+        for (const m of msgs)
+            uidToId.set(this.idToUid(m.id), m.id);
+        const wanted = [];
+        for (const uid of uids) {
+            const id = uidToId.get(uid);
+            if (id)
+                wanted.push({ uid, id }); // skip uids that don't resolve
+        }
+        if (wanted.length === 0)
+            return;
+        const CONCURRENCY = 4;
+        let cursor = 0;
+        const worker = async () => {
+            while (cursor < wanted.length) {
+                const idx = cursor++;
+                const { uid, id } = wanted[idx];
+                try {
+                    const source = await this.fetchRaw(`/messages/${id}/$value`);
+                    onBody(uid, source);
+                }
+                catch (e) {
+                    // Per-message error must not abort the whole batch.
+                    console.error(`  [outlook prefetch] UID ${uid}: ${e.message}`);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(CONCURRENCY, wanted.length) }, () => worker()));
+    }
+    /** Apply the absolute flag state to a message. Graph model: isRead boolean
+     *  + flag.flagStatus. We send both so the end state matches regardless of
+     *  prior state (idempotent, safe to retry). */
+    async setFlags(folder, uid, flags, providerId) {
+        // Prefer the caller-supplied Graph id (stored provider_id). Without it
+        // we fall back to a capped list-and-hash, which misses any message past
+        // the cap — so flagging an older message would throw, the flag would
+        // never reach Graph, and the local star would revert on next sync.
+        // Same rationale as gmail.ts's setFlags.
+        const id = await this.resolveId(folder, uid, providerId, "setFlags");
+        const flagSet = new Set(flags);
+        await this.fetch(`/messages/${id}`, {
+            method: "PATCH",
+            body: JSON.stringify({
+                isRead: flagSet.has("\\Seen"),
+                flag: { flagStatus: flagSet.has("\\Flagged") ? "flagged" : "notFlagged" },
+            }),
+        });
+    }
+    /** Move a message to Deleted Items. Graph's well-known folder name
+     *  "deleteditems" is accepted as a move destination. */
+    async trashMessage(folder, uid, providerId) {
+        const id = await this.resolveId(folder, uid, providerId, "trashMessage");
+        await this.moveById(id, "deleteditems");
+    }
+    /** Move a message to another folder. `toFolder` is the client's `path` (a
+     *  hierarchical display path) — resolve it to the Graph destination id. The
+     *  source folder is only needed for the resolveId list-and-hash fallback,
+     *  which resolveFolder handles internally via listMessages. */
+    async moveMessage(fromFolder, uid, toFolder, providerId) {
+        const id = await this.resolveId(fromFolder, uid, providerId, "moveMessage");
+        const dest = await this.resolveFolder(toFolder);
+        await this.moveById(id, dest);
+    }
+    /** POST /messages/{id}/move, treating 404 as already-done.
+     *
+     *  CRITICAL (differs from Gmail): a Graph move returns a NEW message id in
+     *  the destination — the source id we hold becomes invalid. So if a move
+     *  succeeds server-side but the ACK is lost, the queued retry re-fires with
+     *  the now-stale id and Graph answers 404. Throwing there would exhaust the
+     *  sync-action retries and `clearTombstoneForUid` would RESURRECT a message
+     *  that was actually moved (the exact "deletions un-happening" class the
+     *  Gmail provider_id fix killed). A 404 on a move means "it's no longer
+     *  here" — which is the goal — so we swallow it as success. */
+    async moveById(id, destinationId) {
+        try {
+            await this.fetch(`/messages/${id}/move`, {
+                method: "POST",
+                body: JSON.stringify({ destinationId }),
+            });
+        }
+        catch (e) {
+            if (/\b404\b/.test(e?.message || ""))
+                return; // already moved / gone
+            throw e;
+        }
+    }
+    /** Rename and/or reparent a mail folder. `folderPath` and `newParentPath`
+     *  are the client's hierarchical display paths — resolve each to its Graph
+     *  id before use.
+     *
+     *  - Rename: PATCH /mailFolders/{id} { displayName }.
+     *  - Reparent: POST /mailFolders/{id}/move { destinationId }.
+     *  Both can apply in one call: move first (so the folder lands under the new
+     *  parent), then patch the display name.
+     *
+     *  Well-known folders (inbox/sentitems/drafts/deleteditems/junkemail/archive)
+     *  must not be renamed — Graph rejects it, and it would corrupt the special-
+     *  use mapping. We guard on both the well-known name (the path may be the bare
+     *  name) and the folder's leaf display name, lower-cased. */
+    async renameFolder(folderPath, newName, newParentPath) {
+        // Guard against renaming a special-use folder. The path's leaf segment is
+        // the display name Graph would also expose as a well-known name.
+        const leaf = (folderPath.split("/").pop() || folderPath).toLowerCase();
+        if (WELL_KNOWN[leaf] || WELL_KNOWN_IDS.has(folderPath.toLowerCase())) {
+            throw new Error(`"${newName}" maps to a well-known Outlook folder and can't be renamed.`);
+        }
+        const id = await this.resolveFolder(folderPath);
+        if (newParentPath && newParentPath.length) {
+            const dest = await this.resolveFolder(newParentPath);
+            await this.fetch(`/mailFolders/${id}/move`, {
+                method: "POST",
+                body: JSON.stringify({ destinationId: dest }),
+            });
         }
-        return this.parseMessage(msg, source);
+        await this.fetch(`/mailFolders/${id}`, {
+            method: "PATCH",
+            body: JSON.stringify({ displayName: newName }),
+        });
+    }
+    /** Send a full RFC822 MIME message via Graph's /sendMail. Graph accepts a
+     *  base64-encoded MIME payload when the request Content-Type is text/plain
+     *  and the body is the base64 string. We don't route this through the JSON
+     *  fetch() helper (different content type) but still acquire a token and
+     *  apply a simple inline retry. */
+    async sendRaw(mime) {
+        // Encode the MIME as UTF-8 bytes, then base64 (Buffer-free). btoa on a
+        // unicode string would mangle multi-byte chars, so go via TextEncoder.
+        const bytes = new TextEncoder().encode(mime);
+        const payload = toBase64(bytes);
+        const maxAttempts = 6;
+        let lastStatus = 0;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            await this.acquireToken();
+            const token = await this.tokenProvider();
+            const res = await globalThis.fetch(`${GRAPH}/sendMail`, {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${token}`,
+                    "Content-Type": "text/plain",
+                },
+                body: payload,
+            });
+            if (res.status === 429 || res.status >= 500) {
+                lastStatus = res.status;
+                const retryAfter = res.headers.get("Retry-After");
+                const delay = this.retryDelay(attempt, retryAfter);
+                rateState.cooldownUntil = Math.max(rateState.cooldownUntil, Date.now() + delay);
+                console.log(`  [outlook sendMail] ${res.status} (attempt ${attempt + 1}/${maxAttempts}), waiting ${(delay / 1000).toFixed(1)}s...`);
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            // /sendMail returns 202 Accepted with an empty body on success.
+            if (!res.ok) {
+                const err = await res.text().catch(() => "");
+                throw new Error(`Graph sendMail ${res.status}: ${err.substring(0, 200)}`);
+            }
+            return;
+        }
+        throw new Error(`Graph sendMail: failed after ${maxAttempts} retries (last status ${lastStatus})`);
+    }
+    /** Resolve a Graph message id: prefer the caller-supplied provider_id;
+     *  otherwise list-and-hash (capped) and throw if not found. Centralizes the
+     *  rationale shared by setFlags/trash/move — the cap means a write to a
+     *  message past the most-recent ~1000 fails loudly rather than silently
+     *  hitting the wrong message. */
+    async resolveId(folder, uid, providerId, op) {
+        if (providerId)
+            return providerId;
+        const msgs = await this.listMessages(folder, "", 1000, false);
+        const found = msgs.find(m => this.idToUid(m.id) === uid);
+        if (!found)
+            throw new Error(`Graph ${op}: UID ${uid} not found in ${folder} (no providerId, past list cap)`);
+        return found.id;
     }
     async getUids(folder) {
-        const msgs = await this.listMessages(folder, "", 10000);
-        return msgs.map(m => this.idToUid(m.id));
+        const msgs = await this.listMessages(folder, "", 10000, false);
+        const result = msgs.map(m => this.idToUid(m.id));
+        // Propagate the truncation flag so reconcile refuses to delete when the
+        // server list was capped (mirrors gmail.ts) — otherwise a truncated
+        // page would look like "these are all the messages" and the rest would
+        // be deleted from the local DB.
+        if (msgs._truncated)
+            result._truncated = true;
+        return result;
+    }
+    async close() {
+        // No persistent connection to close.
     }
-    async close() { }
-    /** Add RFC 2822 source to messages (batch) */
+    /** Add RFC 2822 source to messages by pulling each /$value. Sequential —
+     *  bodies-with-source paths are already date- or uid-bounded so the count
+     *  is small; bulk prefetch uses fetchBodiesBatch's worker pool instead. */
     async addSources(messages) {
         for (const msg of messages) {
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-sync",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Platform-agnostic mail provider implementations + sync orchestration. Single source of truth for Gmail/IMAP/Outlook protocol code, consumed by both desktop (Node) and Android (WebView) — eliminates the parallel mailx-imap/mailx-store-web Gmail providers that drifted in practice.",
   "main": "index.js",
   "types": "index.ts",
@@ -19,7 +19,7 @@
   "author": "Bob Frankston",
   "license": "ISC",
   "dependencies": {
-    "@bobfrankston/iflow-direct": "^0.1.53",
+    "@bobfrankston/iflow-direct": "^0.1.55",
     "@bobfrankston/tcp-transport": "^0.1.7"
   },
   "exports": {
@@ -44,7 +44,7 @@
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/iflow-direct": "^0.1.53",
+      "@bobfrankston/iflow-direct": "^0.1.55",
       "@bobfrankston/tcp-transport": "^0.1.7"
     }
   }

package/types.d.ts

@@ -47,6 +47,14 @@ export interface FetchOptions {
      *  the default page-count cap doesn't silently truncate a large folder
      *  to the last ~200 messages. */
     since?: Date;
+    /** UIDs already present in the local store for this folder. Providers whose
+     *  incremental sync re-lists a fixed recent page (Gmail — IDs aren't
+     *  monotonic, so it can't use a high-water mark) use this to SKIP fetching
+     *  metadata for messages already stored: list IDs (one cheap call), drop the
+     *  known ones, fetch only the genuinely-new. Steady state (nothing new) then
+     *  costs one list call and zero per-message GETs instead of re-fetching 200
+     *  one-by-one (~40s on mobile → near-instant) (Bob 2026-06-27). */
+    knownUids?: Set<number>;
 }
 /**
  * A mail provider that can list folders, fetch messages, and perform actions.
@@ -70,6 +78,11 @@ export interface MailProvider {
      *  its native model — e.g. Gmail's UNREAD / STARRED labels.
      *  Optional: IMAP uses the existing STORE path in sync-manager code. */
     setFlags?(folder: string, uid: number, flags: string[]): Promise<void>;
+    /** Rename and/or reparent a folder/label. `newParentPath` is the
+     *  destination parent (Gmail: parent label path; Outlook: parent Graph id);
+     *  omit for a rename-in-place. Optional: IMAP renames via the iflow client's
+     *  mailboxRename, not through this interface. */
+    renameFolder?(folderPath: string, newName: string, newParentPath?: string): Promise<void>;
     /** Close/cleanup */
     close(): Promise<void>;
 }