Implement \Flagged virtual mailbox (SPECIAL-USE)

[scanner]

Summary

Implement the \Flagged SPECIAL-USE attribute (RFC 6154) as a virtual mailbox. Unlike the other SPECIAL-USE folders (\Trash, \Sent, \Drafts, \Junk, \Archive) which map to real MH directories on disk, \Flagged represents a dynamic view of all messages with the \Flagged flag set across all mailboxes.

Design

• Virtual mailbox: A \Flagged mailbox entry exists in the DB (like other mailboxes) but does not correspond to a directory on disk.
• New DB table: A flagged_messages table (or similar) tracks the UIDs of flagged messages. Each row references the UID and the mailbox the message actually lives in, stored in message-ID order.
• Flag change hooks: Whenever \Flagged is added to or removed from a message (via STORE command), update the flagged_messages table accordingly — adding or removing the message from the virtual mailbox.
• Message deletion hooks: When a message is deleted (EXPUNGE), remove it from the flagged_messages table if present.
• Safety mechanism: If an IMAP client accesses a message in the \Flagged mailbox that no longer exists or no longer has \Flagged set, treat it as expunged and send an appropriate EXPUNGE notification.
• LIST response: The \Flagged mailbox appears in LIST responses with the \Flagged SPECIAL-USE attribute.

Complexity

This is significantly more complex than the other SPECIAL-USE attributes because it requires:

1. Virtual mailbox concept (no disk directory)
2. New database table and migration
3. Hooks into STORE (flag changes) and EXPUNGE (message deletion)
4. Cross-mailbox UID mapping
5. Consistency/safety handling for stale entries

Related

• Depends on: Support SPECIAL-USE mailbox attributes (RFC 6154) #472 (SPECIAL-USE extension infrastructure)
• RFC 6154 Section 2: \Flagged attribute definition