feat(mail): add governed JMAP mailbox sync and search

docs/MAIL_PROTOCOL_ROADMAP.md

@@ -1,17 +1,20 @@
 # Mail Protocol Roadmap
 
-GovOPlaN Mail focuses on SMTP sending and IMAP mailbox access. It also provides
-an explicitly enabled, bounded POP3 legacy-import path. JMAP remains deferred
-until the IMAP mailbox MVP and protocol-neutral mailbox contract are stable.
+GovOPlaN Mail uses SMTP for sending and supports read-only mailbox access over
+IMAP or JMAP. It also provides an explicitly enabled, bounded POP3
+legacy-import path. The first JMAP slice is implemented on the stable,
+protocol-neutral mailbox contract.
 
 ## Current Baseline
 
 - SMTP is the send protocol.
-- IMAP is the read/append protocol.
+- IMAP is the established read/append protocol and remains unchanged.
+- JMAP is an opt-in read-only sync/search protocol; it is not used for sending
+  or append-to-Sent.
 - POP3 is an optional legacy migration source, never a general mailbox
   protocol or default profile endpoint.
-- Mail profile policy, encrypted credentials, mailbox folder parsing, test
-  buttons, and read-only mailbox UI are built around SMTP and IMAP.
+- Mail profile policy, encrypted credentials, connection diagnostics, and the
+  read-only mailbox UI cover SMTP/IMAP/JMAP endpoints as applicable.
 
 This baseline matches the first production use case: send campaign mail, append
 sent copies when configured, and inspect mailboxes read-only.
@@ -40,8 +43,8 @@ the S/MIME profile is stable.
 
 ## JMAP
 
-JMAP is the preferred future sync/search protocol where target mail servers
-support it.
+JMAP is the preferred sync/search protocol where target mail servers support
+RFC 8620 Core and RFC 8621 Mail capabilities.
 
 Reasons:
 
@@ -50,12 +53,25 @@ Reasons:
 - modern search and thread models
 - better fit for browser-facing mailbox UX through a server proxy
 
-JMAP should be added only after:
+The implemented first slice provides:
 
-- the IMAP mailbox MVP has stable folder/message pagination behavior
-- mail profile policy can express protocol-specific availability
-- mailbox UI can handle protocol-neutral folder/message DTOs
-- test infrastructure includes at least one reliable JMAP server target
+- authenticated Session discovery with Bearer or Basic credentials;
+- explicit account selection or primary Mail-account selection;
+- folder hierarchy projection through `Mailbox/get`;
+- server-side text search and pagination through `Email/query` plus bounded
+  summaries and details through `Email/get`;
+- incremental state through bounded `Email/changes`, with an explicit full
+  refresh when the provider can no longer calculate changes;
+- per-endpoint response and body-value bounds;
+- a dedicated JMAP hostname policy and fail-closed cross-origin API discovery;
+  and
+- protocol-neutral folder/message DTOs and mailbox UI selection while keeping
+  the IMAP path unchanged.
+
+The current boundary is read-only. JMAP submission, mailbox/message mutation,
+threads, calendars, contacts, push subscriptions, binary attachment download,
+and automatic background synchronization are deferred until a separately
+governed slice needs them.
 
 ## POP3
 
@@ -84,5 +100,7 @@ legacy source rollout is an explicit operational action.
 ## Decision
 
 Keep the implemented POP3 surface limited to governed legacy import. Do not
-expand it into mailbox browsing. Design protocol-neutral mailbox DTOs and
-prefer JMAP for future modern synchronization/search support.
+expand it into mailbox browsing. Keep the protocol-neutral mailbox DTOs and
+use the implemented JMAP path for modern synchronization/search support when
+an administrator explicitly configures it. Keep SMTP for sending and POP3
+limited to governed legacy import.