@bobfrankston/rmfmail 1.0.707 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/rmfmail",
-  "version": "1.0.707",
+  "version": "1.1.2",
   "description": "Local-first email client with IMAP sync and standalone native app",
   "type": "module",
   "main": "bin/mailx.js",
@@ -9,6 +9,7 @@
   },
   "workspaces": [
     "packages/mailx-types",
+    "packages/mailx-bus",
     "packages/mailx-host",
     "packages/mailx-send",
     "packages/mailx-compose",
@@ -36,7 +37,7 @@
     "@bobfrankston/iflow-direct": "^0.1.44",
     "@bobfrankston/mailx-host": "^0.1.12",
     "@bobfrankston/mailx-imap": "^0.1.44",
-    "@bobfrankston/mailx-store-web": "^0.1.6",
+    "@bobfrankston/mailx-store-web": "^0.1.7",
     "@bobfrankston/mailx-sync": "^0.1.16",
     "@bobfrankston/miscinfo": "^1.0.10",
     "@bobfrankston/msger": "^0.1.378",
@@ -116,7 +117,7 @@
       "@bobfrankston/iflow-direct": "^0.1.44",
       "@bobfrankston/mailx-host": "^0.1.12",
       "@bobfrankston/mailx-imap": "^0.1.44",
-      "@bobfrankston/mailx-store-web": "^0.1.6",
+      "@bobfrankston/mailx-store-web": "^0.1.7",
       "@bobfrankston/mailx-sync": "^0.1.16",
       "@bobfrankston/miscinfo": "^1.0.10",
       "@bobfrankston/msger": "^0.1.378",

package/packages/mailx-bus/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @bobfrankston/mailx-bus
+ *
+ * Typed message bus that connects mailx's factors. Each factor (DB, sync,
+ * UI, compose, calendar, …) is a peer that publishes/subscribes to events
+ * and serves/calls request-reply methods over the same bus.
+ *
+ * **Why this exists.** mailx historically had one monolithic service on one
+ * Node event loop: UI reads, IMAP sync, body parsing, OAuth refresh, prefetch,
+ * calendar polling — all on the same thread. A 14-minute synchronous freeze
+ * in any one path froze every other path. There was no separation between
+ * "answer a click" and "wait for Dovecot." The bus is the mechanism that
+ * makes those independent: a factor freezing is local; other factors keep
+ * answering.
+ *
+ * **Shape.** A bus exposes two primitives:
+ *   - `publish(topic, payload)` / `subscribe(topic, handler)` — fire-and-
+ *     forget events. Many subscribers per topic.
+ *   - `request(method, args) → Promise<result>` / `register(method, handler)`
+ *     — RPC. One handler per method. Caller awaits the reply.
+ *
+ * No method-name dispatch on a god object. Each factor declares the topics
+ * and methods it owns. Other factors hold a reference to the bus, not to
+ * each other.
+ *
+ * **Two transports, one interface.**
+ *   - `InProcessBus`: in-memory Map of handlers. Used in tests, in Android
+ *     (single-threaded JS), and for the same-thread half of a bridge.
+ *   - `WorkerBus`: connects to a peer via `worker_threads.MessagePort` (Node)
+ *     or `MessagePort` (browser). Uses `postMessage`, with structured
+ *     clone, so the two sides can live in different threads.
+ *
+ * Both implement `Bus`. Callers write against `Bus`. Where the peer lives is
+ * a deploy decision, not an API decision.
+ *
+ * **Buffer/Uint8Array note (Node).** `worker_threads.postMessage` clones a
+ * Node `Buffer` as a plain `Uint8Array`. Callers passing binary data through
+ * the bus across a worker boundary must accept that the receiving side sees
+ * `Uint8Array` — they should re-wrap with `Buffer.from(u.buffer, u.byteOffset,
+ * u.byteLength)` before handing the value to APIs that test
+ * `Buffer.isBuffer(x)`. The bus does not do this transparently; it is a
+ * transport concern that varies by what the payload actually is.
+ *
+ * **Errors.** A handler that throws is converted to a rejection on the
+ * caller's `request()` promise. The error's `message` survives the
+ * structured-clone barrier; the stack trace does not (Node strips it).
+ *
+ * **Lifecycle.** Subscribers receive a `dispose()` function from `subscribe`.
+ * Registered methods receive one from `register`. Dispose unhooks. A bus
+ * itself has no global teardown — closing the underlying port (when using
+ * `WorkerBus`) is the caller's responsibility.
+ */
+/** Method handler — receives the request payload, returns the response. May
+ *  be async. A throw becomes a request() rejection on the caller. */
+export type MethodHandler<A = any, R = any> = (args: A) => R | Promise<R>;
+/** Topic handler — fire-and-forget; the return value is ignored. */
+export type TopicHandler<P = any> = (payload: P) => void;
+/** Unsubscribe / unregister token returned from `subscribe` / `register`. */
+export type Dispose = () => void;
+export interface Bus {
+    /** Fire an event. Returns synchronously; subscribers are invoked
+     *  asynchronously (next microtask) so a publisher doesn't observe its
+     *  own re-entry. */
+    publish<P = any>(topic: string, payload: P): void;
+    /** Listen to events on `topic`. Returns a dispose function. */
+    subscribe<P = any>(topic: string, handler: TopicHandler<P>): Dispose;
+    /** Call `method` on its registered handler. The result Promise resolves
+     *  with whatever the handler returned, or rejects with the error. */
+    request<A = any, R = any>(method: string, args: A): Promise<R>;
+    /** Register the handler for `method`. Only one handler per method —
+     *  registering twice throws on the second call. Returns a dispose
+     *  function that unregisters. */
+    register<A = any, R = any>(method: string, handler: MethodHandler<A, R>): Dispose;
+}
+/** Single-process bus. Both sides of every call share a JavaScript heap.
+ *  Used in tests, in Android (single-threaded JS), and on whichever side of
+ *  a worker boundary is the host.
+ *
+ *  publish() defers subscriber dispatch to the next microtask so a
+ *  publisher's stack doesn't deepen indefinitely if a handler republishes
+ *  on the same topic. */
+export declare class InProcessBus implements Bus {
+    private topics;
+    private methods;
+    publish<P>(topic: string, payload: P): void;
+    subscribe<P>(topic: string, handler: TopicHandler<P>): Dispose;
+    request<A, R>(method: string, args: A): Promise<R>;
+    register<A, R>(method: string, handler: MethodHandler<A, R>): Dispose;
+}
+/** Anything that quacks like a MessagePort — Node's `worker_threads.parentPort`
+ *  and `Worker` instances, browser's `MessagePort`, etc. */
+export interface MessagePortLike {
+    postMessage(value: any): void;
+    on?(event: "message", handler: (value: any) => void): void;
+    addEventListener?(event: "message", handler: (e: MessageEvent) => void): void;
+}
+/** Cross-thread bus. Each side instantiates a `WorkerBus` over its end of a
+ *  `MessageChannel`. The two sides are mirror images: subscribing on side A
+ *  causes events published on side B to flow over the wire to A. Requests
+ *  initiated on side A are served by whoever registered the method on side B.
+ *
+ *  Topology assumed by this implementation: exactly two endpoints. Multi-
+ *  party busses (>2 peers) need a hub topology and aren't covered here. */
+export declare class WorkerBus implements Bus {
+    private port;
+    private localSubs;
+    /** Methods registered on THIS side. Requests arriving over the wire
+     *  for these methods are dispatched locally. */
+    private localMethods;
+    /** Pending requests we sent to the peer, awaiting reply. */
+    private pending;
+    private nextId;
+    constructor(port: MessagePortLike);
+    publish<P>(topic: string, payload: P): void;
+    subscribe<P>(topic: string, handler: TopicHandler<P>): Dispose;
+    request<A, R>(method: string, args: A): Promise<R>;
+    register<A, R>(method: string, handler: MethodHandler<A, R>): Dispose;
+    private handleIncoming;
+}
+//# sourceMappingURL=index.d.ts.map

package/packages/mailx-bus/index.d.ts.map

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

package/packages/mailx-bus/index.js

@@ -0,0 +1,238 @@
+/**
+ * @bobfrankston/mailx-bus
+ *
+ * Typed message bus that connects mailx's factors. Each factor (DB, sync,
+ * UI, compose, calendar, …) is a peer that publishes/subscribes to events
+ * and serves/calls request-reply methods over the same bus.
+ *
+ * **Why this exists.** mailx historically had one monolithic service on one
+ * Node event loop: UI reads, IMAP sync, body parsing, OAuth refresh, prefetch,
+ * calendar polling — all on the same thread. A 14-minute synchronous freeze
+ * in any one path froze every other path. There was no separation between
+ * "answer a click" and "wait for Dovecot." The bus is the mechanism that
+ * makes those independent: a factor freezing is local; other factors keep
+ * answering.
+ *
+ * **Shape.** A bus exposes two primitives:
+ *   - `publish(topic, payload)` / `subscribe(topic, handler)` — fire-and-
+ *     forget events. Many subscribers per topic.
+ *   - `request(method, args) → Promise<result>` / `register(method, handler)`
+ *     — RPC. One handler per method. Caller awaits the reply.
+ *
+ * No method-name dispatch on a god object. Each factor declares the topics
+ * and methods it owns. Other factors hold a reference to the bus, not to
+ * each other.
+ *
+ * **Two transports, one interface.**
+ *   - `InProcessBus`: in-memory Map of handlers. Used in tests, in Android
+ *     (single-threaded JS), and for the same-thread half of a bridge.
+ *   - `WorkerBus`: connects to a peer via `worker_threads.MessagePort` (Node)
+ *     or `MessagePort` (browser). Uses `postMessage`, with structured
+ *     clone, so the two sides can live in different threads.
+ *
+ * Both implement `Bus`. Callers write against `Bus`. Where the peer lives is
+ * a deploy decision, not an API decision.
+ *
+ * **Buffer/Uint8Array note (Node).** `worker_threads.postMessage` clones a
+ * Node `Buffer` as a plain `Uint8Array`. Callers passing binary data through
+ * the bus across a worker boundary must accept that the receiving side sees
+ * `Uint8Array` — they should re-wrap with `Buffer.from(u.buffer, u.byteOffset,
+ * u.byteLength)` before handing the value to APIs that test
+ * `Buffer.isBuffer(x)`. The bus does not do this transparently; it is a
+ * transport concern that varies by what the payload actually is.
+ *
+ * **Errors.** A handler that throws is converted to a rejection on the
+ * caller's `request()` promise. The error's `message` survives the
+ * structured-clone barrier; the stack trace does not (Node strips it).
+ *
+ * **Lifecycle.** Subscribers receive a `dispose()` function from `subscribe`.
+ * Registered methods receive one from `register`. Dispose unhooks. A bus
+ * itself has no global teardown — closing the underlying port (when using
+ * `WorkerBus`) is the caller's responsibility.
+ */
+// ── In-process implementation ─────────────────────────────────────────────
+/** Single-process bus. Both sides of every call share a JavaScript heap.
+ *  Used in tests, in Android (single-threaded JS), and on whichever side of
+ *  a worker boundary is the host.
+ *
+ *  publish() defers subscriber dispatch to the next microtask so a
+ *  publisher's stack doesn't deepen indefinitely if a handler republishes
+ *  on the same topic. */
+export class InProcessBus {
+    topics = new Map();
+    methods = new Map();
+    publish(topic, payload) {
+        const handlers = this.topics.get(topic);
+        if (!handlers || handlers.size === 0)
+            return;
+        // Snapshot so a subscriber that disposes itself during dispatch
+        // doesn't perturb iteration of the live set.
+        const snapshot = Array.from(handlers);
+        queueMicrotask(() => {
+            for (const h of snapshot) {
+                try {
+                    h(payload);
+                }
+                catch (e) {
+                    console.error(`[bus] subscriber for "${topic}" threw: ${e?.message || e}`);
+                }
+            }
+        });
+    }
+    subscribe(topic, handler) {
+        let set = this.topics.get(topic);
+        if (!set) {
+            set = new Set();
+            this.topics.set(topic, set);
+        }
+        set.add(handler);
+        return () => { set.delete(handler); };
+    }
+    async request(method, args) {
+        const handler = this.methods.get(method);
+        if (!handler)
+            throw new Error(`bus: no handler registered for "${method}"`);
+        // Always async — a handler that throws synchronously would otherwise
+        // bypass the Promise rejection path. Wrap in Promise.resolve().
+        return Promise.resolve().then(() => handler(args));
+    }
+    register(method, handler) {
+        if (this.methods.has(method)) {
+            throw new Error(`bus: "${method}" is already registered`);
+        }
+        this.methods.set(method, handler);
+        return () => { this.methods.delete(method); };
+    }
+}
+/** Cross-thread bus. Each side instantiates a `WorkerBus` over its end of a
+ *  `MessageChannel`. The two sides are mirror images: subscribing on side A
+ *  causes events published on side B to flow over the wire to A. Requests
+ *  initiated on side A are served by whoever registered the method on side B.
+ *
+ *  Topology assumed by this implementation: exactly two endpoints. Multi-
+ *  party busses (>2 peers) need a hub topology and aren't covered here. */
+export class WorkerBus {
+    port;
+    localSubs = new Map();
+    /** Methods registered on THIS side. Requests arriving over the wire
+     *  for these methods are dispatched locally. */
+    localMethods = new Map();
+    /** Pending requests we sent to the peer, awaiting reply. */
+    pending = new Map();
+    nextId = 1;
+    constructor(port) {
+        this.port = port;
+        const onMessage = (raw) => {
+            const msg = (raw && typeof raw === "object" && "data" in raw) ? raw.data : raw;
+            this.handleIncoming(msg);
+        };
+        if (typeof port.on === "function")
+            port.on("message", onMessage);
+        else if (typeof port.addEventListener === "function")
+            port.addEventListener("message", onMessage);
+    }
+    publish(topic, payload) {
+        // Local subscribers fire immediately (same-side publish/subscribe is
+        // allowed). The peer receives a publish message and dispatches there.
+        const local = this.localSubs.get(topic);
+        if (local && local.size > 0) {
+            const snapshot = Array.from(local);
+            queueMicrotask(() => {
+                for (const h of snapshot) {
+                    try {
+                        h(payload);
+                    }
+                    catch (e) {
+                        console.error(`[bus] subscriber for "${topic}" threw: ${e?.message || e}`);
+                    }
+                }
+            });
+        }
+        this.port.postMessage({ kind: "publish", topic, payload });
+    }
+    subscribe(topic, handler) {
+        let set = this.localSubs.get(topic);
+        if (!set) {
+            set = new Set();
+            this.localSubs.set(topic, set);
+        }
+        set.add(handler);
+        return () => { set.delete(handler); };
+    }
+    async request(method, args) {
+        // Prefer local handler if one is registered on this side (allows a
+        // factor to bundle with the bus for in-process testing).
+        const local = this.localMethods.get(method);
+        if (local)
+            return Promise.resolve().then(() => local(args));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.port.postMessage({ kind: "request", method, args, id });
+        });
+    }
+    register(method, handler) {
+        if (this.localMethods.has(method)) {
+            throw new Error(`bus: "${method}" is already registered`);
+        }
+        this.localMethods.set(method, handler);
+        return () => { this.localMethods.delete(method); };
+    }
+    handleIncoming(msg) {
+        if (!msg || typeof msg !== "object")
+            return;
+        switch (msg.kind) {
+            case "publish": {
+                if (typeof msg.topic !== "string")
+                    return;
+                const subs = this.localSubs.get(msg.topic);
+                if (!subs || subs.size === 0)
+                    return;
+                const snapshot = Array.from(subs);
+                queueMicrotask(() => {
+                    for (const h of snapshot) {
+                        try {
+                            h(msg.payload);
+                        }
+                        catch (e) {
+                            console.error(`[bus] subscriber for "${msg.topic}" threw: ${e?.message || e}`);
+                        }
+                    }
+                });
+                return;
+            }
+            case "request": {
+                if (typeof msg.method !== "string" || typeof msg.id !== "number")
+                    return;
+                const handler = this.localMethods.get(msg.method);
+                if (!handler) {
+                    this.port.postMessage({ kind: "reply", id: msg.id, error: `no handler registered for "${msg.method}"` });
+                    return;
+                }
+                Promise.resolve()
+                    .then(() => handler(msg.args))
+                    .then(result => this.port.postMessage({ kind: "reply", id: msg.id, result }))
+                    .catch(e => this.port.postMessage({ kind: "reply", id: msg.id, error: e?.message || String(e) }));
+                return;
+            }
+            case "reply": {
+                if (typeof msg.id !== "number")
+                    return;
+                const entry = this.pending.get(msg.id);
+                if (!entry)
+                    return;
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    entry.reject(new Error(msg.error));
+                else
+                    entry.resolve(msg.result);
+                return;
+            }
+            // subscribe-add/remove/register-add/remove are reserved for a
+            // future optimisation where the bus only forwards events the
+            // peer is interested in. Today every publish crosses the wire;
+            // subscribers filter locally. Cheap enough at our volumes.
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/packages/mailx-bus/index.js.map

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

package/packages/mailx-bus/index.ts

@@ -0,0 +1,264 @@
+/**
+ * @bobfrankston/mailx-bus
+ *
+ * Typed message bus that connects mailx's factors. Each factor (DB, sync,
+ * UI, compose, calendar, …) is a peer that publishes/subscribes to events
+ * and serves/calls request-reply methods over the same bus.
+ *
+ * **Why this exists.** mailx historically had one monolithic service on one
+ * Node event loop: UI reads, IMAP sync, body parsing, OAuth refresh, prefetch,
+ * calendar polling — all on the same thread. A 14-minute synchronous freeze
+ * in any one path froze every other path. There was no separation between
+ * "answer a click" and "wait for Dovecot." The bus is the mechanism that
+ * makes those independent: a factor freezing is local; other factors keep
+ * answering.
+ *
+ * **Shape.** A bus exposes two primitives:
+ *   - `publish(topic, payload)` / `subscribe(topic, handler)` — fire-and-
+ *     forget events. Many subscribers per topic.
+ *   - `request(method, args) → Promise<result>` / `register(method, handler)`
+ *     — RPC. One handler per method. Caller awaits the reply.
+ *
+ * No method-name dispatch on a god object. Each factor declares the topics
+ * and methods it owns. Other factors hold a reference to the bus, not to
+ * each other.
+ *
+ * **Two transports, one interface.**
+ *   - `InProcessBus`: in-memory Map of handlers. Used in tests, in Android
+ *     (single-threaded JS), and for the same-thread half of a bridge.
+ *   - `WorkerBus`: connects to a peer via `worker_threads.MessagePort` (Node)
+ *     or `MessagePort` (browser). Uses `postMessage`, with structured
+ *     clone, so the two sides can live in different threads.
+ *
+ * Both implement `Bus`. Callers write against `Bus`. Where the peer lives is
+ * a deploy decision, not an API decision.
+ *
+ * **Buffer/Uint8Array note (Node).** `worker_threads.postMessage` clones a
+ * Node `Buffer` as a plain `Uint8Array`. Callers passing binary data through
+ * the bus across a worker boundary must accept that the receiving side sees
+ * `Uint8Array` — they should re-wrap with `Buffer.from(u.buffer, u.byteOffset,
+ * u.byteLength)` before handing the value to APIs that test
+ * `Buffer.isBuffer(x)`. The bus does not do this transparently; it is a
+ * transport concern that varies by what the payload actually is.
+ *
+ * **Errors.** A handler that throws is converted to a rejection on the
+ * caller's `request()` promise. The error's `message` survives the
+ * structured-clone barrier; the stack trace does not (Node strips it).
+ *
+ * **Lifecycle.** Subscribers receive a `dispose()` function from `subscribe`.
+ * Registered methods receive one from `register`. Dispose unhooks. A bus
+ * itself has no global teardown — closing the underlying port (when using
+ * `WorkerBus`) is the caller's responsibility.
+ */
+
+/** Method handler — receives the request payload, returns the response. May
+ *  be async. A throw becomes a request() rejection on the caller. */
+export type MethodHandler<A = any, R = any> = (args: A) => R | Promise<R>;
+
+/** Topic handler — fire-and-forget; the return value is ignored. */
+export type TopicHandler<P = any> = (payload: P) => void;
+
+/** Unsubscribe / unregister token returned from `subscribe` / `register`. */
+export type Dispose = () => void;
+
+export interface Bus {
+    /** Fire an event. Returns synchronously; subscribers are invoked
+     *  asynchronously (next microtask) so a publisher doesn't observe its
+     *  own re-entry. */
+    publish<P = any>(topic: string, payload: P): void;
+    /** Listen to events on `topic`. Returns a dispose function. */
+    subscribe<P = any>(topic: string, handler: TopicHandler<P>): Dispose;
+    /** Call `method` on its registered handler. The result Promise resolves
+     *  with whatever the handler returned, or rejects with the error. */
+    request<A = any, R = any>(method: string, args: A): Promise<R>;
+    /** Register the handler for `method`. Only one handler per method —
+     *  registering twice throws on the second call. Returns a dispose
+     *  function that unregisters. */
+    register<A = any, R = any>(method: string, handler: MethodHandler<A, R>): Dispose;
+}
+
+// ── In-process implementation ─────────────────────────────────────────────
+
+/** Single-process bus. Both sides of every call share a JavaScript heap.
+ *  Used in tests, in Android (single-threaded JS), and on whichever side of
+ *  a worker boundary is the host.
+ *
+ *  publish() defers subscriber dispatch to the next microtask so a
+ *  publisher's stack doesn't deepen indefinitely if a handler republishes
+ *  on the same topic. */
+export class InProcessBus implements Bus {
+    private topics = new Map<string, Set<TopicHandler>>();
+    private methods = new Map<string, MethodHandler>();
+
+    publish<P>(topic: string, payload: P): void {
+        const handlers = this.topics.get(topic);
+        if (!handlers || handlers.size === 0) return;
+        // Snapshot so a subscriber that disposes itself during dispatch
+        // doesn't perturb iteration of the live set.
+        const snapshot = Array.from(handlers);
+        queueMicrotask(() => {
+            for (const h of snapshot) {
+                try { h(payload); } catch (e: any) { console.error(`[bus] subscriber for "${topic}" threw: ${e?.message || e}`); }
+            }
+        });
+    }
+
+    subscribe<P>(topic: string, handler: TopicHandler<P>): Dispose {
+        let set = this.topics.get(topic);
+        if (!set) { set = new Set(); this.topics.set(topic, set); }
+        set.add(handler as TopicHandler);
+        return () => { set!.delete(handler as TopicHandler); };
+    }
+
+    async request<A, R>(method: string, args: A): Promise<R> {
+        const handler = this.methods.get(method);
+        if (!handler) throw new Error(`bus: no handler registered for "${method}"`);
+        // Always async — a handler that throws synchronously would otherwise
+        // bypass the Promise rejection path. Wrap in Promise.resolve().
+        return Promise.resolve().then(() => handler(args)) as Promise<R>;
+    }
+
+    register<A, R>(method: string, handler: MethodHandler<A, R>): Dispose {
+        if (this.methods.has(method)) {
+            throw new Error(`bus: "${method}" is already registered`);
+        }
+        this.methods.set(method, handler as MethodHandler);
+        return () => { this.methods.delete(method); };
+    }
+}
+
+// ── Worker / MessagePort implementation ───────────────────────────────────
+
+/** Anything that quacks like a MessagePort — Node's `worker_threads.parentPort`
+ *  and `Worker` instances, browser's `MessagePort`, etc. */
+export interface MessagePortLike {
+    postMessage(value: any): void;
+    on?(event: "message", handler: (value: any) => void): void;       // Node
+    addEventListener?(event: "message", handler: (e: MessageEvent) => void): void;  // browser
+}
+
+interface WireMessage {
+    kind: "publish" | "request" | "reply" | "subscribe-add" | "subscribe-remove" | "register-add" | "register-remove";
+    topic?: string;
+    method?: string;
+    payload?: any;
+    args?: any;
+    result?: any;
+    error?: string;
+    /** Correlation id for request/reply. */
+    id?: number;
+}
+
+/** Cross-thread bus. Each side instantiates a `WorkerBus` over its end of a
+ *  `MessageChannel`. The two sides are mirror images: subscribing on side A
+ *  causes events published on side B to flow over the wire to A. Requests
+ *  initiated on side A are served by whoever registered the method on side B.
+ *
+ *  Topology assumed by this implementation: exactly two endpoints. Multi-
+ *  party busses (>2 peers) need a hub topology and aren't covered here. */
+export class WorkerBus implements Bus {
+    private port: MessagePortLike;
+    private localSubs = new Map<string, Set<TopicHandler>>();
+    /** Methods registered on THIS side. Requests arriving over the wire
+     *  for these methods are dispatched locally. */
+    private localMethods = new Map<string, MethodHandler>();
+    /** Pending requests we sent to the peer, awaiting reply. */
+    private pending = new Map<number, { resolve: (r: any) => void; reject: (e: any) => void }>();
+    private nextId = 1;
+
+    constructor(port: MessagePortLike) {
+        this.port = port;
+        const onMessage = (raw: any): void => {
+            const msg = (raw && typeof raw === "object" && "data" in raw) ? (raw as MessageEvent).data : raw;
+            this.handleIncoming(msg as WireMessage);
+        };
+        if (typeof port.on === "function") port.on("message", onMessage);
+        else if (typeof port.addEventListener === "function") port.addEventListener("message", onMessage);
+    }
+
+    publish<P>(topic: string, payload: P): void {
+        // Local subscribers fire immediately (same-side publish/subscribe is
+        // allowed). The peer receives a publish message and dispatches there.
+        const local = this.localSubs.get(topic);
+        if (local && local.size > 0) {
+            const snapshot = Array.from(local);
+            queueMicrotask(() => {
+                for (const h of snapshot) {
+                    try { h(payload); } catch (e: any) { console.error(`[bus] subscriber for "${topic}" threw: ${e?.message || e}`); }
+                }
+            });
+        }
+        this.port.postMessage({ kind: "publish", topic, payload } as WireMessage);
+    }
+
+    subscribe<P>(topic: string, handler: TopicHandler<P>): Dispose {
+        let set = this.localSubs.get(topic);
+        if (!set) { set = new Set(); this.localSubs.set(topic, set); }
+        set.add(handler as TopicHandler);
+        return () => { set!.delete(handler as TopicHandler); };
+    }
+
+    async request<A, R>(method: string, args: A): Promise<R> {
+        // Prefer local handler if one is registered on this side (allows a
+        // factor to bundle with the bus for in-process testing).
+        const local = this.localMethods.get(method);
+        if (local) return Promise.resolve().then(() => local(args)) as Promise<R>;
+        const id = this.nextId++;
+        return new Promise<R>((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.port.postMessage({ kind: "request", method, args, id } as WireMessage);
+        });
+    }
+
+    register<A, R>(method: string, handler: MethodHandler<A, R>): Dispose {
+        if (this.localMethods.has(method)) {
+            throw new Error(`bus: "${method}" is already registered`);
+        }
+        this.localMethods.set(method, handler as MethodHandler);
+        return () => { this.localMethods.delete(method); };
+    }
+
+    private handleIncoming(msg: WireMessage): void {
+        if (!msg || typeof msg !== "object") return;
+        switch (msg.kind) {
+            case "publish": {
+                if (typeof msg.topic !== "string") return;
+                const subs = this.localSubs.get(msg.topic);
+                if (!subs || subs.size === 0) return;
+                const snapshot = Array.from(subs);
+                queueMicrotask(() => {
+                    for (const h of snapshot) {
+                        try { h(msg.payload); } catch (e: any) { console.error(`[bus] subscriber for "${msg.topic}" threw: ${e?.message || e}`); }
+                    }
+                });
+                return;
+            }
+            case "request": {
+                if (typeof msg.method !== "string" || typeof msg.id !== "number") return;
+                const handler = this.localMethods.get(msg.method);
+                if (!handler) {
+                    this.port.postMessage({ kind: "reply", id: msg.id, error: `no handler registered for "${msg.method}"` } as WireMessage);
+                    return;
+                }
+                Promise.resolve()
+                    .then(() => handler(msg.args))
+                    .then(result => this.port.postMessage({ kind: "reply", id: msg.id, result } as WireMessage))
+                    .catch(e => this.port.postMessage({ kind: "reply", id: msg.id, error: e?.message || String(e) } as WireMessage));
+                return;
+            }
+            case "reply": {
+                if (typeof msg.id !== "number") return;
+                const entry = this.pending.get(msg.id);
+                if (!entry) return;
+                this.pending.delete(msg.id);
+                if (msg.error) entry.reject(new Error(msg.error));
+                else entry.resolve(msg.result);
+                return;
+            }
+            // subscribe-add/remove/register-add/remove are reserved for a
+            // future optimisation where the bus only forwards events the
+            // peer is interested in. Today every publish crosses the wire;
+            // subscribers filter locally. Cheap enough at our volumes.
+        }
+    }
+}

package/packages/mailx-bus/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@bobfrankston/mailx-bus",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "release": "npmglobalize"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BobFrankston/mailx-bus.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/mailx-bus/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": ".",
+    "rootDir": "."
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules", "prev", "cruft", "tests"]
+}

package/packages/mailx-service/db-worker-client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Main-thread client for the DB factor worker.
+ *
+ * Spawns `db-worker.js` in a Node `worker_thread`, performs the init
+ * handshake (passes dbPath + storePath), and returns a `WorkerBus` the
+ * caller can use to send read requests and subscribe to DB events.
+ *
+ * The init handshake is a single `{kind:"init"}` postMessage followed by an
+ * `{kind:"init-ok"}` or `{kind:"init-error"}` reply. This is done OUTSIDE
+ * the WorkerBus message protocol so a bus method can't accidentally race
+ * the construction of LocalStore inside the worker.
+ *
+ * Failure mode: if the worker can't load (the file is missing in a packaged
+ * build, the DB can't be opened, etc.), `spawnDbWorker()` rejects. The
+ * caller can fall back to in-process LocalStore — same code, same answers,
+ * just shares the event loop with whatever else is running on main. That's
+ * the legacy path; the worker is the new default but we don't paint
+ * ourselves into a corner.
+ */
+import { Worker } from "node:worker_threads";
+import { WorkerBus } from "@bobfrankston/mailx-bus";
+export interface SpawnedDbWorker {
+    bus: WorkerBus;
+    worker: Worker;
+    /** Stop the worker. After this, requests over the bus reject. */
+    close(): Promise<void>;
+}
+export declare function spawnDbWorker(opts: {
+    dbPath: string;
+    storePath: string;
+}): Promise<SpawnedDbWorker>;
+//# sourceMappingURL=db-worker-client.d.ts.map

package/packages/mailx-service/db-worker-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-worker-client.d.ts","sourceRoot":"","sources":["db-worker-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAwB,MAAM,yBAAyB,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CA0CzG"}

package/packages/mailx-service/db-worker-client.js

@@ -0,0 +1,66 @@
+/**
+ * Main-thread client for the DB factor worker.
+ *
+ * Spawns `db-worker.js` in a Node `worker_thread`, performs the init
+ * handshake (passes dbPath + storePath), and returns a `WorkerBus` the
+ * caller can use to send read requests and subscribe to DB events.
+ *
+ * The init handshake is a single `{kind:"init"}` postMessage followed by an
+ * `{kind:"init-ok"}` or `{kind:"init-error"}` reply. This is done OUTSIDE
+ * the WorkerBus message protocol so a bus method can't accidentally race
+ * the construction of LocalStore inside the worker.
+ *
+ * Failure mode: if the worker can't load (the file is missing in a packaged
+ * build, the DB can't be opened, etc.), `spawnDbWorker()` rejects. The
+ * caller can fall back to in-process LocalStore — same code, same answers,
+ * just shares the event loop with whatever else is running on main. That's
+ * the legacy path; the worker is the new default but we don't paint
+ * ourselves into a corner.
+ */
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { WorkerBus } from "@bobfrankston/mailx-bus";
+export async function spawnDbWorker(opts) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const workerPath = join(here, "db-worker.js");
+    const worker = new Worker(workerPath);
+    // Don't let the worker prevent process exit. Phase 1 design choice — the
+    // service shuts down cleanly via its own gracefulShutdown which closes
+    // the worker explicitly; without unref, a stuck worker could block exit.
+    worker.unref();
+    // Init handshake — promise resolves on init-ok, rejects on init-error.
+    await new Promise((resolve, reject) => {
+        const onMessage = (msg) => {
+            if (!msg || typeof msg !== "object")
+                return;
+            if (msg.kind === "init-ok") {
+                worker.off("message", onMessage);
+                resolve();
+            }
+            else if (msg.kind === "init-error") {
+                worker.off("message", onMessage);
+                reject(new Error(`db-worker init: ${msg.error}`));
+            }
+            // Ignore other messages (bus traffic) — the bus is built AFTER
+            // we resolve, so any bus message arriving here is stale.
+        };
+        worker.on("message", onMessage);
+        worker.on("error", (e) => {
+            worker.off("message", onMessage);
+            reject(e);
+        });
+        worker.postMessage({ kind: "init", dbPath: opts.dbPath, storePath: opts.storePath });
+    });
+    // Wrap the post-init port in a WorkerBus on this side. The worker has
+    // already wrapped its parentPort in a WorkerBus inside its init handler.
+    const bus = new WorkerBus(worker);
+    return {
+        bus,
+        worker,
+        async close() {
+            await worker.terminate();
+        },
+    };
+}
+//# sourceMappingURL=db-worker-client.js.map

package/packages/mailx-service/db-worker-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-worker-client.js","sourceRoot":"","sources":["db-worker-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAwB,MAAM,yBAAyB,CAAC;AAS1E,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAA2C;IAC3E,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC;IACtC,yEAAyE;IACzE,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,CAAC;IAEf,uEAAuE;IACvE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,SAAS,GAAG,CAAC,GAAQ,EAAQ,EAAE;YACjC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,OAAO;YAC5C,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;gBACjC,OAAO,EAAE,CAAC;YACd,CAAC;iBAAM,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACnC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;gBACjC,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACtD,CAAC;YACD,+DAA+D;YAC/D,yDAAyD;QAC7D,CAAC,CAAC;QACF,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAQ,EAAE,EAAE;YAC5B,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACjC,MAAM,CAAC,CAAC,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,sEAAsE;IACtE,yEAAyE;IACzE,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC,MAAoC,CAAC,CAAC;IAEhE,OAAO;QACH,GAAG;QACH,MAAM;QACN,KAAK,CAAC,KAAK;YACP,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;QAC7B,CAAC;KACJ,CAAC;AACN,CAAC"}

package/packages/mailx-service/db-worker-client.ts

@@ -0,0 +1,75 @@
+/**
+ * Main-thread client for the DB factor worker.
+ *
+ * Spawns `db-worker.js` in a Node `worker_thread`, performs the init
+ * handshake (passes dbPath + storePath), and returns a `WorkerBus` the
+ * caller can use to send read requests and subscribe to DB events.
+ *
+ * The init handshake is a single `{kind:"init"}` postMessage followed by an
+ * `{kind:"init-ok"}` or `{kind:"init-error"}` reply. This is done OUTSIDE
+ * the WorkerBus message protocol so a bus method can't accidentally race
+ * the construction of LocalStore inside the worker.
+ *
+ * Failure mode: if the worker can't load (the file is missing in a packaged
+ * build, the DB can't be opened, etc.), `spawnDbWorker()` rejects. The
+ * caller can fall back to in-process LocalStore — same code, same answers,
+ * just shares the event loop with whatever else is running on main. That's
+ * the legacy path; the worker is the new default but we don't paint
+ * ourselves into a corner.
+ */
+
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { WorkerBus, type MessagePortLike } from "@bobfrankston/mailx-bus";
+
+export interface SpawnedDbWorker {
+    bus: WorkerBus;
+    worker: Worker;
+    /** Stop the worker. After this, requests over the bus reject. */
+    close(): Promise<void>;
+}
+
+export async function spawnDbWorker(opts: { dbPath: string; storePath: string }): Promise<SpawnedDbWorker> {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const workerPath = join(here, "db-worker.js");
+    const worker = new Worker(workerPath);
+    // Don't let the worker prevent process exit. Phase 1 design choice — the
+    // service shuts down cleanly via its own gracefulShutdown which closes
+    // the worker explicitly; without unref, a stuck worker could block exit.
+    worker.unref();
+
+    // Init handshake — promise resolves on init-ok, rejects on init-error.
+    await new Promise<void>((resolve, reject) => {
+        const onMessage = (msg: any): void => {
+            if (!msg || typeof msg !== "object") return;
+            if (msg.kind === "init-ok") {
+                worker.off("message", onMessage);
+                resolve();
+            } else if (msg.kind === "init-error") {
+                worker.off("message", onMessage);
+                reject(new Error(`db-worker init: ${msg.error}`));
+            }
+            // Ignore other messages (bus traffic) — the bus is built AFTER
+            // we resolve, so any bus message arriving here is stale.
+        };
+        worker.on("message", onMessage);
+        worker.on("error", (e: Error) => {
+            worker.off("message", onMessage);
+            reject(e);
+        });
+        worker.postMessage({ kind: "init", dbPath: opts.dbPath, storePath: opts.storePath });
+    });
+
+    // Wrap the post-init port in a WorkerBus on this side. The worker has
+    // already wrapped its parentPort in a WorkerBus inside its init handler.
+    const bus = new WorkerBus(worker as unknown as MessagePortLike);
+
+    return {
+        bus,
+        worker,
+        async close(): Promise<void> {
+            await worker.terminate();
+        },
+    };
+}

package/packages/mailx-service/db-worker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DB factor — Node worker thread.
+ *
+ * Owns the SQLite handle and FileMessageStore. Serves the UI-read surface
+ * (getFolders, getMessages, getUnifiedInbox, getMessage, searchMessages,
+ * searchContacts, getThreadMessages) over `mailx-bus`. Subscribes to write
+ * events from the sync factor (Phase 2) and emits `db:messageAdded` /
+ * `db:messageRemoved` / `db:flagChanged` so the UI can update incrementally
+ * without re-asking.
+ *
+ * **Why a worker.** Until now every UI click had to traverse the same Node
+ * event loop the sync code runs on. A 14-minute synchronous freeze in the
+ * sync path (Dovecot SELECT hang, Prefirst.OIA backfill loop) starved every
+ * UI read. The IPC pipe handler couldn't even be scheduled. From the user's
+ * perspective: Sent shows empty, message bodies never load, autocomplete
+ * dies, drafts can't save. All of those have one cause: the read path
+ * shares an event loop with the write/sync path.
+ *
+ * In this worker, the read path is on its own thread. Sync can freeze for
+ * an hour and the user's click still gets a 5 ms answer from local SQLite.
+ *
+ * **Topology**. Main thread spawns this worker once, holds a `WorkerBus` over
+ * the `parentPort`. The worker also holds a `WorkerBus` over `parentPort` and
+ * registers its handlers. Two ends of the same channel, mirror APIs.
+ *
+ * **DB connection**. `better-sqlite3` is in-process synchronous, so the
+ * worker opens its OWN connection to the same `.db` file. WAL mode (set in
+ * `MailxDB`) makes concurrent readers safe; writes still happen on the main
+ * thread for Phase 1 and the worker sees committed rows immediately.
+ * Phase 2 moves writes to the sync worker, which routes through this worker
+ * for any UI-visible mutation so the LRU/cache here can update in lock-step.
+ *
+ * **No mailparser here.** Body parsing is the parse-worker's job. This
+ * worker reads the .eml bytes off disk and delegates parsing via
+ * `parseSerial` (which already postMessages to its own worker). Two workers
+ * either side of this thread; the read coordinator is purely an indexer.
+ */
+export {};
+//# sourceMappingURL=db-worker.d.ts.map

package/packages/mailx-service/db-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-worker.d.ts","sourceRoot":"","sources":["db-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG"}

package/packages/mailx-service/db-worker.js

@@ -0,0 +1,104 @@
+/**
+ * DB factor — Node worker thread.
+ *
+ * Owns the SQLite handle and FileMessageStore. Serves the UI-read surface
+ * (getFolders, getMessages, getUnifiedInbox, getMessage, searchMessages,
+ * searchContacts, getThreadMessages) over `mailx-bus`. Subscribes to write
+ * events from the sync factor (Phase 2) and emits `db:messageAdded` /
+ * `db:messageRemoved` / `db:flagChanged` so the UI can update incrementally
+ * without re-asking.
+ *
+ * **Why a worker.** Until now every UI click had to traverse the same Node
+ * event loop the sync code runs on. A 14-minute synchronous freeze in the
+ * sync path (Dovecot SELECT hang, Prefirst.OIA backfill loop) starved every
+ * UI read. The IPC pipe handler couldn't even be scheduled. From the user's
+ * perspective: Sent shows empty, message bodies never load, autocomplete
+ * dies, drafts can't save. All of those have one cause: the read path
+ * shares an event loop with the write/sync path.
+ *
+ * In this worker, the read path is on its own thread. Sync can freeze for
+ * an hour and the user's click still gets a 5 ms answer from local SQLite.
+ *
+ * **Topology**. Main thread spawns this worker once, holds a `WorkerBus` over
+ * the `parentPort`. The worker also holds a `WorkerBus` over `parentPort` and
+ * registers its handlers. Two ends of the same channel, mirror APIs.
+ *
+ * **DB connection**. `better-sqlite3` is in-process synchronous, so the
+ * worker opens its OWN connection to the same `.db` file. WAL mode (set in
+ * `MailxDB`) makes concurrent readers safe; writes still happen on the main
+ * thread for Phase 1 and the worker sees committed rows immediately.
+ * Phase 2 moves writes to the sync worker, which routes through this worker
+ * for any UI-visible mutation so the LRU/cache here can update in lock-step.
+ *
+ * **No mailparser here.** Body parsing is the parse-worker's job. This
+ * worker reads the .eml bytes off disk and delegates parsing via
+ * `parseSerial` (which already postMessages to its own worker). Two workers
+ * either side of this thread; the read coordinator is purely an indexer.
+ */
+import { parentPort } from "node:worker_threads";
+import { WorkerBus } from "@bobfrankston/mailx-bus";
+import { MailxDB, FileMessageStore } from "@bobfrankston/mailx-store";
+import { LocalStore } from "./local-store.js";
+if (!parentPort) {
+    throw new Error("db-worker: must be spawned as a worker, parentPort is null");
+}
+// Wait for the init message before constructing the DB — the main thread
+// owns the resolved paths and passes them in.
+let store = null;
+let initialized = false;
+parentPort.once("message", async (msg) => {
+    if (msg?.kind !== "init") {
+        parentPort.postMessage({ kind: "init-error", error: `expected "init" message, got ${JSON.stringify(msg)}` });
+        return;
+    }
+    try {
+        const db = new MailxDB(msg.dbPath);
+        const bodyStore = new FileMessageStore(msg.storePath);
+        store = new LocalStore(db, bodyStore);
+        initialized = true;
+        // Now that the store is up, register handlers and ack init.
+        registerHandlers(store);
+        parentPort.postMessage({ kind: "init-ok" });
+    }
+    catch (e) {
+        parentPort.postMessage({ kind: "init-error", error: e?.message || String(e) });
+    }
+});
+function registerHandlers(s) {
+    // The bus speaks over `parentPort`. `WorkerBus` reads the same channel
+    // we just consumed `init` from — that's fine, `once()` removes the
+    // single-shot listener and the bus's own `on("message")` takes over.
+    const bus = new WorkerBus(parentPort);
+    // ── Folders ─────────────────────────────────────────────────────
+    bus.register("db:getFolders", ({ accountId }) => s.getFolders(accountId));
+    // ── Message list ────────────────────────────────────────────────
+    bus.register("db:getMessages", (q) => s.getMessages(q));
+    bus.register("db:getUnifiedInbox", ({ page = 1, pageSize = 50 }) => s.getUnifiedInbox(page, pageSize));
+    bus.register("db:searchMessages", ({ query, page = 1, pageSize = 50, accountId, folderId, includeTrashSpam = false }) => s.searchMessages(query, page, pageSize, accountId, folderId, includeTrashSpam));
+    // ── Single message (envelope + body) ────────────────────────────
+    bus.register("db:getMessage", ({ accountId, uid, allowRemote = false, folderId }) => s.getMessage(accountId, uid, allowRemote, folderId));
+    bus.register("db:getThreadMessages", ({ accountId, threadId }) => s.getThreadMessages?.(accountId, threadId) ?? []);
+    // ── Contacts read (lookups) ─────────────────────────────────────
+    bus.register("db:searchContacts", ({ query, limit }) => s.searchContacts?.(query, limit) ?? []);
+    // ── Accounts (read-only DB shape) ───────────────────────────────
+    bus.register("db:getAccounts", () => s.getAccounts());
+    // ── Config-cache invalidation ──────────────────────────────────
+    // Main thread receives `configChanged` events (allowlist.jsonc etc.)
+    // and publishes them; the worker invalidates its in-LocalStore caches
+    // so the next read sees the fresh JSONC.
+    bus.subscribe("config:changed", () => {
+        s.invalidateConfigCaches();
+    });
+}
+// Defensive: if the bus is ever asked something before init completes, the
+// caller gets a clear error rather than a hang. Mirrors the init-error path.
+parentPort.on("message", (msg) => {
+    if (!initialized && msg && typeof msg === "object" && msg.kind === "request") {
+        parentPort.postMessage({
+            kind: "reply",
+            id: msg.id,
+            error: "db-worker: not initialized — main thread must send {kind:'init'} first",
+        });
+    }
+});
+//# sourceMappingURL=db-worker.js.map

package/packages/mailx-service/db-worker.js.map

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

package/packages/mailx-service/db-worker.ts

@@ -0,0 +1,153 @@
+/**
+ * DB factor — Node worker thread.
+ *
+ * Owns the SQLite handle and FileMessageStore. Serves the UI-read surface
+ * (getFolders, getMessages, getUnifiedInbox, getMessage, searchMessages,
+ * searchContacts, getThreadMessages) over `mailx-bus`. Subscribes to write
+ * events from the sync factor (Phase 2) and emits `db:messageAdded` /
+ * `db:messageRemoved` / `db:flagChanged` so the UI can update incrementally
+ * without re-asking.
+ *
+ * **Why a worker.** Until now every UI click had to traverse the same Node
+ * event loop the sync code runs on. A 14-minute synchronous freeze in the
+ * sync path (Dovecot SELECT hang, Prefirst.OIA backfill loop) starved every
+ * UI read. The IPC pipe handler couldn't even be scheduled. From the user's
+ * perspective: Sent shows empty, message bodies never load, autocomplete
+ * dies, drafts can't save. All of those have one cause: the read path
+ * shares an event loop with the write/sync path.
+ *
+ * In this worker, the read path is on its own thread. Sync can freeze for
+ * an hour and the user's click still gets a 5 ms answer from local SQLite.
+ *
+ * **Topology**. Main thread spawns this worker once, holds a `WorkerBus` over
+ * the `parentPort`. The worker also holds a `WorkerBus` over `parentPort` and
+ * registers its handlers. Two ends of the same channel, mirror APIs.
+ *
+ * **DB connection**. `better-sqlite3` is in-process synchronous, so the
+ * worker opens its OWN connection to the same `.db` file. WAL mode (set in
+ * `MailxDB`) makes concurrent readers safe; writes still happen on the main
+ * thread for Phase 1 and the worker sees committed rows immediately.
+ * Phase 2 moves writes to the sync worker, which routes through this worker
+ * for any UI-visible mutation so the LRU/cache here can update in lock-step.
+ *
+ * **No mailparser here.** Body parsing is the parse-worker's job. This
+ * worker reads the .eml bytes off disk and delegates parsing via
+ * `parseSerial` (which already postMessages to its own worker). Two workers
+ * either side of this thread; the read coordinator is purely an indexer.
+ */
+
+import { parentPort } from "node:worker_threads";
+import { WorkerBus, type MessagePortLike } from "@bobfrankston/mailx-bus";
+import { MailxDB, FileMessageStore } from "@bobfrankston/mailx-store";
+import { LocalStore } from "./local-store.js";
+import type { MessageQuery } from "@bobfrankston/mailx-types";
+
+if (!parentPort) {
+    throw new Error("db-worker: must be spawned as a worker, parentPort is null");
+}
+
+interface InitMessage {
+    kind: "init";
+    dbPath: string;
+    storePath: string;
+}
+
+// Wait for the init message before constructing the DB — the main thread
+// owns the resolved paths and passes them in.
+let store: LocalStore | null = null;
+let initialized = false;
+
+parentPort.once("message", async (msg: InitMessage) => {
+    if (msg?.kind !== "init") {
+        parentPort!.postMessage({ kind: "init-error", error: `expected "init" message, got ${JSON.stringify(msg)}` });
+        return;
+    }
+    try {
+        const db = new MailxDB(msg.dbPath);
+        const bodyStore = new FileMessageStore(msg.storePath);
+        store = new LocalStore(db, bodyStore);
+        initialized = true;
+        // Now that the store is up, register handlers and ack init.
+        registerHandlers(store);
+        parentPort!.postMessage({ kind: "init-ok" });
+    } catch (e: any) {
+        parentPort!.postMessage({ kind: "init-error", error: e?.message || String(e) });
+    }
+});
+
+function registerHandlers(s: LocalStore): void {
+    // The bus speaks over `parentPort`. `WorkerBus` reads the same channel
+    // we just consumed `init` from — that's fine, `once()` removes the
+    // single-shot listener and the bus's own `on("message")` takes over.
+    const bus = new WorkerBus(parentPort as unknown as MessagePortLike);
+
+    // ── Folders ─────────────────────────────────────────────────────
+    bus.register<{ accountId: string }, any[]>(
+        "db:getFolders",
+        ({ accountId }) => s.getFolders(accountId),
+    );
+
+    // ── Message list ────────────────────────────────────────────────
+    bus.register<MessageQuery, any>(
+        "db:getMessages",
+        (q) => s.getMessages(q),
+    );
+
+    bus.register<{ page?: number; pageSize?: number }, any>(
+        "db:getUnifiedInbox",
+        ({ page = 1, pageSize = 50 }) => s.getUnifiedInbox(page, pageSize),
+    );
+
+    bus.register<
+        { query: string; page?: number; pageSize?: number; accountId?: string; folderId?: number; includeTrashSpam?: boolean },
+        any
+    >(
+        "db:searchMessages",
+        ({ query, page = 1, pageSize = 50, accountId, folderId, includeTrashSpam = false }) =>
+            s.searchMessages(query, page, pageSize, accountId, folderId, includeTrashSpam),
+    );
+
+    // ── Single message (envelope + body) ────────────────────────────
+    bus.register<{ accountId: string; uid: number; allowRemote?: boolean; folderId?: number }, any>(
+        "db:getMessage",
+        ({ accountId, uid, allowRemote = false, folderId }) =>
+            s.getMessage(accountId, uid, allowRemote, folderId),
+    );
+
+    bus.register<{ accountId: string; threadId: string }, any[]>(
+        "db:getThreadMessages",
+        ({ accountId, threadId }) => (s as any).getThreadMessages?.(accountId, threadId) ?? [],
+    );
+
+    // ── Contacts read (lookups) ─────────────────────────────────────
+    bus.register<{ query: string; limit?: number }, any[]>(
+        "db:searchContacts",
+        ({ query, limit }) => (s as any).searchContacts?.(query, limit) ?? [],
+    );
+
+    // ── Accounts (read-only DB shape) ───────────────────────────────
+    bus.register<void, any[]>(
+        "db:getAccounts",
+        () => s.getAccounts(),
+    );
+
+    // ── Config-cache invalidation ──────────────────────────────────
+    // Main thread receives `configChanged` events (allowlist.jsonc etc.)
+    // and publishes them; the worker invalidates its in-LocalStore caches
+    // so the next read sees the fresh JSONC.
+    bus.subscribe<{ filename?: string }>("config:changed", () => {
+        s.invalidateConfigCaches();
+    });
+}
+
+// Defensive: if the bus is ever asked something before init completes, the
+// caller gets a clear error rather than a hang. Mirrors the init-error path.
+parentPort.on("message", (msg: any) => {
+    if (!initialized && msg && typeof msg === "object" && msg.kind === "request") {
+        parentPort!.postMessage({
+            kind: "reply",
+            id: msg.id,
+            error: "db-worker: not initialized — main thread must send {kind:'init'} first",
+        });
+    }
+});

package/packages/mailx-service/package.json

@@ -9,6 +9,7 @@
   },
   "license": "ISC",
   "dependencies": {
+    "@bobfrankston/mailx-bus": "file:../mailx-bus",
     "@bobfrankston/mailx-imap": "file:../mailx-imap",
     "@bobfrankston/mailx-settings": "file:../mailx-settings",
     "@bobfrankston/mailx-store": "file:../mailx-store",

package/packages/mailx-store/parse-worker.js

@@ -42,7 +42,23 @@ parentPort.on("message", async (msg) => {
     // worker since _warmupPromise is already resolved.
     await _warmupPromise;
     try {
-        const result = await simpleParser(source);
+        // CRITICAL: `Buffer` sent across `worker_threads.postMessage` arrives
+        // as plain `Uint8Array` (Node docs: "Buffer instances passed to
+        // Worker.postMessage() are passed as Uint8Array instances when
+        // received"). mailparser's `simpleParser` uses `Buffer.isBuffer(input)`
+        // to discriminate Buffer / string / Stream. A Uint8Array fails that
+        // check and gets routed to the Stream branch, which calls
+        // `input.once("end", …)` and immediately throws
+        //   `input.once is not a function`
+        // Re-wrap with `Buffer.from(src.buffer, src.byteOffset, src.byteLength)`
+        // — zero-copy view over the same memory, but with the Buffer prototype
+        // so `Buffer.isBuffer` is true.
+        let normalized = source;
+        if (source instanceof Uint8Array && !Buffer.isBuffer(source)) {
+            const u = source;
+            normalized = Buffer.from(u.buffer, u.byteOffset, u.byteLength);
+        }
+        const result = await simpleParser(normalized);
         parentPort.postMessage({ id, ok: true, result });
     }
     catch (e) {

package/packages/mailx-store/parse-worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse-worker.js","sourceRoot":"","sources":["parse-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AAEvD,IAAI,CAAC,UAAU,EAAE,CAAC;IACd,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;AACrF,CAAC;AAOD,0EAA0E;AAC1E,kEAAkE;AAClE,yEAAyE;AACzE,0EAA0E;AAC1E,qEAAqE;AACrE,uEAAuE;AACvE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC7B,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAC3C,wDAAwD;MACtD,0CAA0C;MAC1C,iDAAiD;MACjD,gDAAgD,EAClD,MAAM,CACT,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;IACT,kEAAkE;IAClE,UAAW,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AAClE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAA8D,CAAC,CAAC,CAAC;AAE/E,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAiB,EAAE,EAAE;IACjD,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC3B,oEAAoE;IACpE,kEAAkE;IAClE,mDAAmD;IACnD,MAAM,cAAc,CAAC;IACrB,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,UAAW,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,UAAW,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"parse-worker.js","sourceRoot":"","sources":["parse-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AAEvD,IAAI,CAAC,UAAU,EAAE,CAAC;IACd,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;AACrF,CAAC;AAOD,0EAA0E;AAC1E,kEAAkE;AAClE,yEAAyE;AACzE,0EAA0E;AAC1E,qEAAqE;AACrE,uEAAuE;AACvE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC7B,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAC3C,wDAAwD;MACtD,0CAA0C;MAC1C,iDAAiD;MACjD,gDAAgD,EAClD,MAAM,CACT,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;IACT,kEAAkE;IAClE,UAAW,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AAClE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAA8D,CAAC,CAAC,CAAC;AAE/E,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAiB,EAAE,EAAE;IACjD,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC3B,oEAAoE;IACpE,kEAAkE;IAClE,mDAAmD;IACnD,MAAM,cAAc,CAAC;IACrB,IAAI,CAAC;QACD,sEAAsE;QACtE,gEAAgE;QAChE,+DAA+D;QAC/D,wEAAwE;QACxE,oEAAoE;QACpE,0DAA0D;QAC1D,gDAAgD;QAChD,mCAAmC;QACnC,yEAAyE;QACzE,uEAAuE;QACvE,gCAAgC;QAChC,IAAI,UAAU,GAAW,MAAM,CAAC;QAChC,IAAI,MAAM,YAAY,UAAU,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3D,MAAM,CAAC,GAAG,MAAoB,CAAC;YAC/B,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;QAC9C,UAAW,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzD,UAAW,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;AACL,CAAC,CAAC,CAAC"}

package/packages/mailx-store/parse-worker.ts

@@ -53,7 +53,23 @@ parentPort.on("message", async (msg: ParseRequest) => {
     // worker since _warmupPromise is already resolved.
     await _warmupPromise;
     try {
-        const result = await simpleParser(source);
+        // CRITICAL: `Buffer` sent across `worker_threads.postMessage` arrives
+        // as plain `Uint8Array` (Node docs: "Buffer instances passed to
+        // Worker.postMessage() are passed as Uint8Array instances when
+        // received"). mailparser's `simpleParser` uses `Buffer.isBuffer(input)`
+        // to discriminate Buffer / string / Stream. A Uint8Array fails that
+        // check and gets routed to the Stream branch, which calls
+        // `input.once("end", …)` and immediately throws
+        //   `input.once is not a function`
+        // Re-wrap with `Buffer.from(src.buffer, src.byteOffset, src.byteLength)`
+        // — zero-copy view over the same memory, but with the Buffer prototype
+        // so `Buffer.isBuffer` is true.
+        let normalized: Source = source;
+        if (source instanceof Uint8Array && !Buffer.isBuffer(source)) {
+            const u = source as Uint8Array;
+            normalized = Buffer.from(u.buffer, u.byteOffset, u.byteLength);
+        }
+        const result = await simpleParser(normalized);
         parentPort!.postMessage({ id, ok: true, result });
     } catch (e: unknown) {
         const error = e instanceof Error ? e.message : String(e);