@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/flag-push.d.ts

@@ -0,0 +1,69 @@
+import type { FifoQueueProducer, IMessageFlagPushRepository } from "@remit/data-ports";
+/**
+ * Event the reconciler (imap-worker `handleFlagPush`) drains. Carries ONLY
+ * our own message id + the flag field — never a UID and never the desired
+ * operation (that lives on the marker, resolved fresh at push time, epic
+ * #1281 invariant 1). The event stays valid across any amount of queue delay
+ * or a later local flip of the SAME field (which replaces the marker before
+ * this event is ever processed).
+ */
+export interface FlagPushEvent {
+    type: "FLAG_PUSH";
+    eventId: string;
+    timestamp: number;
+    accountId: string;
+    accountConfigId: string;
+    messageId: string;
+    flagName: string;
+}
+export interface FlagPushLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+export interface FlagPushConfig {
+    markerService: IMessageFlagPushRepository;
+    queue: FifoQueueProducer<FlagPushEvent>;
+    logger?: FlagPushLogger;
+}
+export type FlagPushOperationValue = "add" | "remove";
+/**
+ * Writes a pending flag-push marker and best-effort enqueues a wake-up hint
+ * (issue #1273, epic #1281). Called AFTER the caller (`FlagQueueService`) has
+ * already durably written the local `MessageFlag`/`ThreadMessage` state in
+ * the SAME request — the user's intent is durable the moment `flip` writes
+ * the marker, before the enqueue even runs.
+ *
+ * Mirrors `PlacementMoveService` (#1289)'s marker lifecycle, scoped per
+ * (`messageId`, `flagName`) instead of per `messageId` — a message can carry
+ * an independent pending read-state marker and pending star marker at once
+ * (epic FAQ: "a flag flip replaces a pending flag flip", scoped per field).
+ * `put` (not `create`) always resets the marker to `pending`, so a later flip
+ * of the SAME field simply replaces the earlier marker — "later intent wins
+ * locally".
+ *
+ * Unlike #1289's placement move (where an enqueue failure must propagate,
+ * because nothing besides the marker+enqueue sequence has committed the
+ * user's intent), the flag flip here is durable the instant the marker write
+ * lands — the enqueue is purely a latency optimization so the push does not
+ * have to wait for the next periodic sync tick. An enqueue failure is
+ * therefore swallowed on purpose: it must never fail the caller's request.
+ * It must also never be silent — logged with an `alert`-shaped entry so a
+ * string of failures (SQS itself unhealthy) is operationally visible, same
+ * convention as the enqueue this replaces (`flag-queue.ts`'s prior
+ * `flag_sync_enqueue_failed`).
+ */
+export declare class FlagPushService {
+    private markerService;
+    private queue;
+    private log;
+    constructor(config: FlagPushConfig);
+    flip: (params: {
+        accountId: string;
+        accountConfigId: string;
+        messageId: string;
+        mailboxId: string;
+        flagName: string;
+        operation: FlagPushOperationValue;
+    }) => Promise<void>;
+    private enqueueHint;
+}

package/dist/flag-push.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+/**
+ * Writes a pending flag-push marker and best-effort enqueues a wake-up hint
+ * (issue #1273, epic #1281). Called AFTER the caller (`FlagQueueService`) has
+ * already durably written the local `MessageFlag`/`ThreadMessage` state in
+ * the SAME request — the user's intent is durable the moment `flip` writes
+ * the marker, before the enqueue even runs.
+ *
+ * Mirrors `PlacementMoveService` (#1289)'s marker lifecycle, scoped per
+ * (`messageId`, `flagName`) instead of per `messageId` — a message can carry
+ * an independent pending read-state marker and pending star marker at once
+ * (epic FAQ: "a flag flip replaces a pending flag flip", scoped per field).
+ * `put` (not `create`) always resets the marker to `pending`, so a later flip
+ * of the SAME field simply replaces the earlier marker — "later intent wins
+ * locally".
+ *
+ * Unlike #1289's placement move (where an enqueue failure must propagate,
+ * because nothing besides the marker+enqueue sequence has committed the
+ * user's intent), the flag flip here is durable the instant the marker write
+ * lands — the enqueue is purely a latency optimization so the push does not
+ * have to wait for the next periodic sync tick. An enqueue failure is
+ * therefore swallowed on purpose: it must never fail the caller's request.
+ * It must also never be silent — logged with an `alert`-shaped entry so a
+ * string of failures (SQS itself unhealthy) is operationally visible, same
+ * convention as the enqueue this replaces (`flag-queue.ts`'s prior
+ * `flag_sync_enqueue_failed`).
+ */
+export class FlagPushService {
+    markerService;
+    queue;
+    log;
+    constructor(config) {
+        this.markerService = config.markerService;
+        this.queue = config.queue;
+        this.log = config.logger ?? noopLogger;
+    }
+    flip = async (params) => {
+        const { accountId, accountConfigId, messageId, mailboxId, flagName, operation, } = params;
+        await this.markerService.put({
+            messageId,
+            flagName,
+            accountId,
+            accountConfigId,
+            mailboxId,
+            operation,
+        });
+        await this.enqueueHint({ accountId, accountConfigId, messageId, flagName });
+    };
+    enqueueHint = async (params) => {
+        const event = {
+            type: "FLAG_PUSH",
+            eventId: randomUUID(),
+            timestamp: Date.now(),
+            ...params,
+        };
+        // The marker persisted in `flip` is the durable record — the queue,
+        // per the issue's own words. This send is only a wake-up hint: a
+        // queue-down failure must NOT fail the caller's flip (intent is
+        // already durable) and must NOT be silent either (standing rule: our
+        // infra failing is never a quiet blip). The periodic per-mailbox
+        // drain (issue #1273) still finds and pushes the marker regardless.
+        await this.queue
+            .send({
+            body: event,
+            groupId: params.accountId,
+            deduplicationId: event.eventId,
+        })
+            .then(async () => {
+            // Only advance past `pending` once the hint is CONFIRMED sent — a
+            // marker still `pending` is exactly the periodic drain's query
+            // target (`sync-messages.ts`'s `drainPendingFlagPushes`), so a
+            // failed send below must leave it there, never here.
+            await this.markerService
+                .updateState(params.messageId, params.flagName, "queued")
+                .catch(async (error) => {
+                // Fast-path race (review finding on #1292): the worker can
+                // drain AND delete the marker before this transition runs —
+                // SQS delivery + processing can outrun this .then(). The
+                // enqueue itself already succeeded, so re-check whether the
+                // marker still exists before treating this as an infra
+                // failure: if it's already gone, the push already completed
+                // and this is expected, routine — never the
+                // flag_push_hint_enqueue_failed alarm shape. Any OTHER
+                // failure (e.g. the re-check itself fails because the
+                // backend is genuinely down) still propagates to the outer
+                // catch below.
+                const stillPending = await this.markerService.find(params.messageId, params.flagName);
+                if (!stillPending) {
+                    this.log.info({ eventId: event.eventId, ...params }, "Marker already drained before the queued-state transition (fast-path race, harmless)");
+                    return;
+                }
+                throw error;
+            });
+            this.log.info({ eventId: event.eventId, ...params }, "Enqueued FLAG_PUSH wake-up hint");
+        })
+            .catch((error) => {
+            this.log.error({
+                alert: "flag_push_hint_enqueue_failed",
+                eventId: event.eventId,
+                ...params,
+                errorName: error?.name,
+                errorCode: error?.Code ??
+                    error?.code,
+            }, "Failed to enqueue FLAG_PUSH wake-up hint (marker persisted; the periodic sync tick will still drain it)");
+        });
+    };
+}

package/dist/flag-queue.d.ts

@@ -0,0 +1,175 @@
+import type { IMessageFlagRepository, IMessageRepository, IThreadMessageRepository } from "@remit/data-ports";
+import { StarColor } from "@remit/domain-enums";
+import type { FlagPushService } from "./flag-push.js";
+/**
+ * StarColor type derived from the StarColor const object
+ */
+type StarColorValue = (typeof StarColor)[keyof typeof StarColor];
+/**
+ * Logger interface
+ */
+export interface FlagQueueLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Input for updateFlags API method
+ */
+export interface UpdateFlagsInput {
+    isRead?: boolean;
+    isStarred?: boolean;
+    starColor?: StarColorValue;
+}
+/**
+ * Result of updateFlags API method
+ */
+export interface UpdateFlagsResult {
+    messageId: string;
+    isRead: boolean;
+    isStarred: boolean;
+}
+/**
+ * Configuration for FlagQueueService
+ */
+export interface FlagQueueConfig {
+    messageFlagService: IMessageFlagRepository;
+    messageService: IMessageRepository;
+    threadMessageService: IThreadMessageRepository;
+    flagPushService: FlagPushService;
+    logger?: FlagQueueLogger;
+}
+/**
+ * Service for marking messages as read/unread/starred, local-first with a
+ * durable pending-flag marker (issue #1273, epic #1281).
+ *
+ * Every flip below follows the SAME sequence: persist the pending marker
+ * FIRST via {@link FlagPushService.flip} (the durable record IMAP still owes
+ * this push, and best-effort enqueues a wake-up hint), THEN apply locally
+ * (MessageFlag + ThreadMessage). The marker write is what makes the user's
+ * intent durable — not the enqueue, which may fail freely (see
+ * `FlagPushService`'s own doc) — and writing it first means a crash before
+ * the local write leaves an unapplied local flip behind an already-durable
+ * marker, never a flipped flag with no marker (review finding on #1292;
+ * mirrors #1289's `PlacementMoveService.moveMessage` ordering). This class
+ * therefore no longer touches
+ * `Mailbox.unseenCount` at all: that field is a pure projection, recomputed
+ * only from IMAP (`doc/rules/data-flow.md`); the displayed count is adjusted
+ * at READ TIME from pending markers (`applyPendingMoveCountPrediction`,
+ * `packages/backend/src/derive/pendingMoveCounts.ts`).
+ *
+ * The service updates BOTH entities locally:
+ * - MessageFlag: The canonical flag record
+ * - ThreadMessage.isRead / hasStars / star: Denormalized for efficient queries
+ */
+export declare class FlagQueueService {
+    private messageFlagService;
+    private messageService;
+    private threadMessageService;
+    private flagPushService;
+    private log;
+    constructor(config: FlagQueueConfig);
+    /**
+     * Update ThreadMessage.isRead for ALL ThreadMessages matching this messageId.
+     *
+     * A message can exist in multiple mailboxes (e.g., inbox and archive), so we
+     * must update all instances to keep the isRead status consistent.
+     *
+     * The `composites` map carries the CURRENT values of every attribute that
+     * participates in a sort key. ElectroDB uses them for the conditional check
+     * on the existing row and combines them with `set()` to recompute the new
+     * sort keys. Passing the NEW `isRead` value here would make the conditional
+     * check fail (existing row still has the old value) and the patch would be
+     * misreported as NotFoundError, silently dropping the update.
+     *
+     * Handles race condition where ThreadMessage may be deleted between find and update.
+     */
+    private updateThreadMessageIsRead;
+    /**
+     * Update ThreadMessage.hasStars and star color for ALL ThreadMessages matching this messageId.
+     *
+     * A message can exist in multiple mailboxes (e.g., inbox and archive), so we
+     * must update all instances to keep the star status consistent.
+     *
+     * Handles race condition where ThreadMessage may be deleted between find and update.
+     */
+    private updateThreadMessageStars;
+    /**
+     * Flip one flag field: persist the pending marker FIRST, then apply
+     * locally. Every caller in this class routes through here so the marker
+     * write is never skipped. Returns whether a change actually happened —
+     * `false` for a redundant flip (already in the desired state), which
+     * every caller uses to skip the (otherwise redundant) ThreadMessage
+     * update too.
+     *
+     * Ordering matters (review finding on #1292): a marker written AFTER the
+     * local `MessageFlag` flip means a crash between the two awaits strands a
+     * flipped flag with no marker — no hint was ever sent, the pending-only
+     * drain never finds it (no marker to find), and message-sync never
+     * rewrites `MessageFlag` from IMAP for an existing row, so nothing else
+     * reconciles it either. That is a permanent, silent divergence — exactly
+     * the defect #1273 exists to kill. Writing the marker first (matching
+     * #1289's `PlacementMoveService.moveMessage` ordering) makes that
+     * scenario impossible: the marker's existence is the record of how far
+     * the sequence got, so a crash after it can strand at worst an
+     * un-applied LOCAL write behind an already-durable marker — recoverable
+     * (the caller's natural retry re-applies both steps; `put` and
+     * `addFlag`/`removeFlag` are both idempotent) — never the reverse.
+     *
+     * The current-state check (review finding on #1292) matters for a
+     * different reason: `markAsRead`/`markAsUnread`/`updateFlags` take the
+     * DESIRED boolean from the caller rather than deriving it from current
+     * state (unlike `toggleFlagged`, which already reads `hasFlag` first and
+     * so can never generate a redundant marker). A redundant "mark as read"
+     * on an already-read message would otherwise still write a fresh `add
+     * \Seen` marker; the read-time unseenCount prediction
+     * (`applyPendingMoveCountPrediction`) would then subtract one for a
+     * message IMAP already counts as seen, transiently under-counting the
+     * badge until the marker clears. Skipping the marker (and the local
+     * write) entirely when the flag already matches removes the false
+     * prediction at the source, not just its symptom.
+     */
+    private flipFlag;
+    /**
+     * Mark a message as read (add \Seen flag).
+     * Updates MessageFlag, ThreadMessage.isRead, and persists a pending
+     * flag-push marker for IMAP sync.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to mark as read
+     * @param accountId - The account ID for the IMAP sync event
+     */
+    markAsRead: (accountConfigId: string, messageId: string, accountId: string) => Promise<void>;
+    /**
+     * Mark a message as unread (remove \Seen flag).
+     * Updates MessageFlag, ThreadMessage.isRead, and persists a pending
+     * flag-push marker for IMAP sync.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to mark as unread
+     * @param accountId - The account ID for the IMAP sync event
+     */
+    markAsUnread: (accountConfigId: string, messageId: string, accountId: string) => Promise<void>;
+    /**
+     * Toggle the starred/flagged status of a message.
+     * Updates local state and persists a pending flag-push marker for IMAP
+     * sync.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to toggle
+     * @param accountId - The account ID for the IMAP sync event
+     * @returns true if flag was added, false if removed
+     */
+    toggleFlagged: (accountConfigId: string, messageId: string, accountId: string) => Promise<boolean>;
+    /**
+     * Update message flags using API-friendly input format.
+     * Maps isRead/isStarred to IMAP flags and updates ThreadMessage accordingly.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to update
+     * @param accountId - The account ID for the IMAP sync event
+     * @param input - The flag updates to apply
+     * @returns The current flag state after updates
+     */
+    updateFlags: (accountConfigId: string, messageId: string, accountId: string, input: UpdateFlagsInput) => Promise<UpdateFlagsResult>;
+}
+export {};

package/dist/flag-queue.js

@@ -0,0 +1,291 @@
+import { NotFoundError } from "@remit/data-ports/errors";
+import { MessageSystemFlag, StarColor } from "@remit/domain-enums";
+const noopLogger = {
+    info: () => { },
+    error: () => { },
+};
+/**
+ * Service for marking messages as read/unread/starred, local-first with a
+ * durable pending-flag marker (issue #1273, epic #1281).
+ *
+ * Every flip below follows the SAME sequence: persist the pending marker
+ * FIRST via {@link FlagPushService.flip} (the durable record IMAP still owes
+ * this push, and best-effort enqueues a wake-up hint), THEN apply locally
+ * (MessageFlag + ThreadMessage). The marker write is what makes the user's
+ * intent durable — not the enqueue, which may fail freely (see
+ * `FlagPushService`'s own doc) — and writing it first means a crash before
+ * the local write leaves an unapplied local flip behind an already-durable
+ * marker, never a flipped flag with no marker (review finding on #1292;
+ * mirrors #1289's `PlacementMoveService.moveMessage` ordering). This class
+ * therefore no longer touches
+ * `Mailbox.unseenCount` at all: that field is a pure projection, recomputed
+ * only from IMAP (`doc/rules/data-flow.md`); the displayed count is adjusted
+ * at READ TIME from pending markers (`applyPendingMoveCountPrediction`,
+ * `packages/backend/src/derive/pendingMoveCounts.ts`).
+ *
+ * The service updates BOTH entities locally:
+ * - MessageFlag: The canonical flag record
+ * - ThreadMessage.isRead / hasStars / star: Denormalized for efficient queries
+ */
+export class FlagQueueService {
+    messageFlagService;
+    messageService;
+    threadMessageService;
+    flagPushService;
+    log;
+    constructor(config) {
+        const { messageFlagService, messageService, threadMessageService, flagPushService, } = config;
+        this.messageFlagService = messageFlagService;
+        this.messageService = messageService;
+        this.threadMessageService = threadMessageService;
+        this.flagPushService = flagPushService;
+        this.log = config.logger ?? noopLogger;
+    }
+    /**
+     * Update ThreadMessage.isRead for ALL ThreadMessages matching this messageId.
+     *
+     * A message can exist in multiple mailboxes (e.g., inbox and archive), so we
+     * must update all instances to keep the isRead status consistent.
+     *
+     * The `composites` map carries the CURRENT values of every attribute that
+     * participates in a sort key. ElectroDB uses them for the conditional check
+     * on the existing row and combines them with `set()` to recompute the new
+     * sort keys. Passing the NEW `isRead` value here would make the conditional
+     * check fail (existing row still has the old value) and the patch would be
+     * misreported as NotFoundError, silently dropping the update.
+     *
+     * Handles race condition where ThreadMessage may be deleted between find and update.
+     */
+    updateThreadMessageIsRead = async (accountConfigId, messageId, isRead) => {
+        const threadMessages = await this.threadMessageService.findAllByMessageId(accountConfigId, messageId);
+        if (threadMessages.length === 0) {
+            this.log.info({ messageId }, "ThreadMessage not found for messageId - skipping isRead update");
+            return;
+        }
+        for (const threadMessage of threadMessages) {
+            try {
+                await this.threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, { isRead }, {
+                    composites: {
+                        sentDate: threadMessage.sentDate,
+                        mailboxId: threadMessage.mailboxId,
+                        isRead: threadMessage.isRead,
+                        isDeleted: threadMessage.isDeleted,
+                        hasStars: threadMessage.hasStars,
+                        hasAttachment: threadMessage.hasAttachment,
+                    },
+                });
+                this.log.info({ messageId, threadMessageId: threadMessage.threadMessageId, isRead }, "Updated ThreadMessage.isRead");
+            }
+            catch (err) {
+                if (err instanceof NotFoundError) {
+                    this.log.info({ messageId, threadMessageId: threadMessage.threadMessageId }, "ThreadMessage deleted during update - skipping isRead update");
+                    continue;
+                }
+                throw err;
+            }
+        }
+    };
+    /**
+     * Update ThreadMessage.hasStars and star color for ALL ThreadMessages matching this messageId.
+     *
+     * A message can exist in multiple mailboxes (e.g., inbox and archive), so we
+     * must update all instances to keep the star status consistent.
+     *
+     * Handles race condition where ThreadMessage may be deleted between find and update.
+     */
+    updateThreadMessageStars = async (accountConfigId, messageId, updates) => {
+        if (Object.keys(updates).length === 0)
+            return;
+        const threadMessages = await this.threadMessageService.findAllByMessageId(accountConfigId, messageId);
+        if (threadMessages.length === 0) {
+            this.log.info({ messageId }, "ThreadMessage not found for messageId - skipping star update");
+            return;
+        }
+        for (const threadMessage of threadMessages) {
+            try {
+                await this.threadMessageService.update(threadMessage.accountConfigId, threadMessage.threadMessageId, updates, {
+                    composites: {
+                        sentDate: threadMessage.sentDate,
+                        mailboxId: threadMessage.mailboxId,
+                        isRead: threadMessage.isRead,
+                        isDeleted: threadMessage.isDeleted,
+                        hasStars: threadMessage.hasStars,
+                        hasAttachment: threadMessage.hasAttachment,
+                    },
+                });
+                this.log.info({
+                    messageId,
+                    threadMessageId: threadMessage.threadMessageId,
+                    updates,
+                }, "Updated ThreadMessage stars");
+            }
+            catch (err) {
+                if (err instanceof NotFoundError) {
+                    this.log.info({ messageId, threadMessageId: threadMessage.threadMessageId }, "ThreadMessage deleted during update - skipping star update");
+                    continue;
+                }
+                throw err;
+            }
+        }
+    };
+    /**
+     * Flip one flag field: persist the pending marker FIRST, then apply
+     * locally. Every caller in this class routes through here so the marker
+     * write is never skipped. Returns whether a change actually happened —
+     * `false` for a redundant flip (already in the desired state), which
+     * every caller uses to skip the (otherwise redundant) ThreadMessage
+     * update too.
+     *
+     * Ordering matters (review finding on #1292): a marker written AFTER the
+     * local `MessageFlag` flip means a crash between the two awaits strands a
+     * flipped flag with no marker — no hint was ever sent, the pending-only
+     * drain never finds it (no marker to find), and message-sync never
+     * rewrites `MessageFlag` from IMAP for an existing row, so nothing else
+     * reconciles it either. That is a permanent, silent divergence — exactly
+     * the defect #1273 exists to kill. Writing the marker first (matching
+     * #1289's `PlacementMoveService.moveMessage` ordering) makes that
+     * scenario impossible: the marker's existence is the record of how far
+     * the sequence got, so a crash after it can strand at worst an
+     * un-applied LOCAL write behind an already-durable marker — recoverable
+     * (the caller's natural retry re-applies both steps; `put` and
+     * `addFlag`/`removeFlag` are both idempotent) — never the reverse.
+     *
+     * The current-state check (review finding on #1292) matters for a
+     * different reason: `markAsRead`/`markAsUnread`/`updateFlags` take the
+     * DESIRED boolean from the caller rather than deriving it from current
+     * state (unlike `toggleFlagged`, which already reads `hasFlag` first and
+     * so can never generate a redundant marker). A redundant "mark as read"
+     * on an already-read message would otherwise still write a fresh `add
+     * \Seen` marker; the read-time unseenCount prediction
+     * (`applyPendingMoveCountPrediction`) would then subtract one for a
+     * message IMAP already counts as seen, transiently under-counting the
+     * badge until the marker clears. Skipping the marker (and the local
+     * write) entirely when the flag already matches removes the false
+     * prediction at the source, not just its symptom.
+     */
+    flipFlag = async (accountId, accountConfigId, messageId, mailboxId, flagName, operation) => {
+        const alreadyInState = await this.messageFlagService.hasFlag(messageId, flagName);
+        if ((operation === "add" && alreadyInState) ||
+            (operation === "remove" && !alreadyInState)) {
+            this.log.info({ messageId, flagName, operation }, "Flag already in the desired state — skipping redundant marker + local write");
+            return false;
+        }
+        await this.flagPushService.flip({
+            accountId,
+            accountConfigId,
+            messageId,
+            mailboxId,
+            flagName,
+            operation,
+        });
+        if (operation === "add") {
+            await this.messageFlagService.addFlag(messageId, flagName);
+        }
+        else {
+            await this.messageFlagService.removeFlag(messageId, flagName);
+        }
+        return true;
+    };
+    /**
+     * Mark a message as read (add \Seen flag).
+     * Updates MessageFlag, ThreadMessage.isRead, and persists a pending
+     * flag-push marker for IMAP sync.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to mark as read
+     * @param accountId - The account ID for the IMAP sync event
+     */
+    markAsRead = async (accountConfigId, messageId, accountId) => {
+        const message = await this.messageService.get(messageId);
+        const changed = await this.flipFlag(accountId, accountConfigId, messageId, message.mailboxId, MessageSystemFlag.Seen, "add");
+        if (changed) {
+            await this.updateThreadMessageIsRead(accountConfigId, messageId, true);
+        }
+        this.log.info({ messageId, changed }, "Marked message as read (local, push pending)");
+    };
+    /**
+     * Mark a message as unread (remove \Seen flag).
+     * Updates MessageFlag, ThreadMessage.isRead, and persists a pending
+     * flag-push marker for IMAP sync.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to mark as unread
+     * @param accountId - The account ID for the IMAP sync event
+     */
+    markAsUnread = async (accountConfigId, messageId, accountId) => {
+        const message = await this.messageService.get(messageId);
+        const changed = await this.flipFlag(accountId, accountConfigId, messageId, message.mailboxId, MessageSystemFlag.Seen, "remove");
+        if (changed) {
+            await this.updateThreadMessageIsRead(accountConfigId, messageId, false);
+        }
+        this.log.info({ messageId, changed }, "Marked message as unread (local, push pending)");
+    };
+    /**
+     * Toggle the starred/flagged status of a message.
+     * Updates local state and persists a pending flag-push marker for IMAP
+     * sync.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to toggle
+     * @param accountId - The account ID for the IMAP sync event
+     * @returns true if flag was added, false if removed
+     */
+    toggleFlagged = async (accountConfigId, messageId, accountId) => {
+        const message = await this.messageService.get(messageId);
+        const hasFlag = await this.messageFlagService.hasFlag(messageId, MessageSystemFlag.Flagged);
+        const operation = hasFlag ? "remove" : "add";
+        await this.flipFlag(accountId, accountConfigId, messageId, message.mailboxId, MessageSystemFlag.Flagged, operation);
+        this.log.info({ messageId, operation }, "Toggled flagged status (local, push pending)");
+        return operation === "add";
+    };
+    /**
+     * Update message flags using API-friendly input format.
+     * Maps isRead/isStarred to IMAP flags and updates ThreadMessage accordingly.
+     *
+     * @param accountConfigId - The owning account config (tenant scope)
+     * @param messageId - The message to update
+     * @param accountId - The account ID for the IMAP sync event
+     * @param input - The flag updates to apply
+     * @returns The current flag state after updates
+     */
+    updateFlags = async (accountConfigId, messageId, accountId, input) => {
+        const message = await this.messageService.get(messageId);
+        // Handle isRead -> \Seen flag
+        if (input.isRead !== undefined) {
+            const changed = await this.flipFlag(accountId, accountConfigId, messageId, message.mailboxId, MessageSystemFlag.Seen, input.isRead ? "add" : "remove");
+            if (changed) {
+                await this.updateThreadMessageIsRead(accountConfigId, messageId, input.isRead);
+            }
+        }
+        // `hasStars` is the boolean of record (the byStarred index sort key) and
+        // the server-side \Flagged keyword; `star` is its presentation colour,
+        // whose absent state is the None sentinel. The two must never disagree,
+        // whichever field the caller sent:
+        //
+        //   isStarred alone  → colour follows the boolean (standard colour on,
+        //                      None off)
+        //   starColor alone  → boolean follows the colour, so `none` unstars and
+        //                      any real colour stars
+        //   both             → isStarred decides the boolean, starColor the colour
+        //
+        // The \Flagged push follows the resulting boolean in every case, so a
+        // colour-only request still reaches the server. `flipFlag` no-ops when the
+        // flag already holds the desired state.
+        if (input.isStarred !== undefined || input.starColor !== undefined) {
+            const starred = input.isStarred ??
+                (input.starColor ?? StarColor.None) !== StarColor.None;
+            const color = input.starColor ?? (starred ? StarColor.Yellow : StarColor.None);
+            await this.flipFlag(accountId, accountConfigId, messageId, message.mailboxId, MessageSystemFlag.Flagged, starred ? "add" : "remove");
+            // Update ThreadMessage hasStars and star color for ALL instances
+            await this.updateThreadMessageStars(accountConfigId, messageId, {
+                hasStars: starred,
+                star: color,
+            });
+        }
+        // Return current state
+        const isRead = await this.messageFlagService.hasFlag(messageId, MessageSystemFlag.Seen);
+        const isStarred = await this.messageFlagService.hasFlag(messageId, MessageSystemFlag.Flagged);
+        this.log.info({ messageId, isRead, isStarred, input }, "Updated message flags");
+        return { messageId, isRead, isStarred };
+    };
+}