Decide mark-read granularity and trigger

[Hohnik]

Part of #12

Question

#11 says the user can "mark a conversation or message as read" but doesn't decide the mechanism: does opening a conversation's thread view auto-mark all its messages read, is it an explicit per-message or per-conversation action, and does "marking a conversation read" mean marking every message in it read individually or also tracking read state at the conversation level?

Decide the model and record the answer as an update to #11's acceptance criteria.

[Hohnik]

Answer

Read state is the server's, not MailChat's. Message.is_read is a cache of the IMAP \Seen flag. Every local change is pushed immediately with UID STORE; every poll pulls flags back and overwrites the cache. There is no pending/dirty state anywhere — the server is simply authoritative, and a local write that doesn't reach it doesn't happen.

Granularity

Per-message, mirroring the per-message \Seen the server owns. Conversation gets no read column — conversation-level unread is derived (EXISTS/COUNT over its messages), so there is one source of truth that cannot drift from the messages or from the server. A conversation-level read cursor (the classic chat-app model) was rejected: the server's truth is per-message, so a cursor would have nowhere to land the pulled flags and couldn't represent "read message 3 but not message 5".

"Mark this conversation read" therefore means marking each of its messages read — batched into one UID STORE per (account, imap_folder) group, so it's one or two IMAP calls rather than N. Since conversations aren't account-scoped (#10), one such action may touch two different IMAP servers.

Trigger

Opening a conversation auto-marks its unread inbound messages read — chat semantics, since you can't open half a conversation — plus explicit per-message and per-conversation overrides in both directions, as an escape hatch for "I glanced at it, keep it flagged". Marking unread pushes -FLAGS (\Seen), forced by the same authority rule: a local-only unread would just be reverted by the next poll.

The auto-mark fires from an hx-trigger="load" POST emitted by the page shell, not the polled thread fragment:

• Rendering the thread never touches IMAP, so the messages appear instantly and the IMAP round trip lives in its own request that can actually report failure.
• Because the trigger is in the shell rather than the fragment, it fires once per page load. A message arriving into a conversation you already have open renders bold and stays unread until you reload or mark it — a thread left open in a background tab never silently consumes unread state.

Failure handling

The local write commits only if the STORE succeeded. On failure nothing is persisted and the htmx swap returns the unchanged unread state with an inline notice, so the UI never shows a read state the server doesn't hold. Consequence: while IMAP is unreachable, marking read is impossible — acceptable, since sync is down in that state anyway.

Schema and IMAP changes

Message gains is_read (bool), imap_uid (int), imap_folder (str), imap_uidvalidity (int).

The pull fetches (UID FLAGS RFC822) and stays readonly=True. That is load-bearing rather than incidental: a writable SELECT makes FETCH RFC822 set \Seen server-side, which would mark every message read as a side effect of syncing it. Only the mark-read path opens the folder writable, and it compares the SELECT response's UIDVALIDITY against the stored one, skipping and logging on mismatch rather than flipping a flag on an unrelated message in a real mailbox.

normalize() no longer leaves a known message_id untouched: for messages inside the fetch window it refreshes is_read from the pulled flag and rewrites imap_uid/imap_uidvalidity, so a UID left stale by a UIDVALIDITY change heals on the next poll.

Outbound messages

is_read mirrors the server faithfully on every row, but unread display filters to direction = 'inbound'. Some servers store sent mail without \Seen, and under faithful mirroring that would badge a conversation unread because of a message you wrote. Filtering at display avoids that without making the pull path write to mail the user never asked it to touch.

The conversation list shows an unread count badge (COUNT over inbound-unread messages), not just a boolean — at this scale it costs the same as an EXISTS and tells you how much is waiting.

Accepted limitations

• The flag refresh only reaches the newest messages each poll fetches per folder (currently 10), so a message read in another client after it falls out of that window stays unread in MailChat indefinitely — and the count badge with it.
• A poll landing between the local write and the STORE can briefly revert a badge; it self-heals on the next cycle.

Recorded in

• Reply within a conversation #11 — trigger, shell-vs-fragment placement, overrides, batching, UIDVALIDITY guard, rollback-on-failure, and mark-read tests.
• Group messages into person+subject conversations #10 — the four new Message columns, the (UID FLAGS RFC822) + readonly=True fetch change, the flag refresh in normalize(), the inbound-only unread count badge, and the corresponding tests.

Worth flagging for whoever implements these: this is the heaviest of the map's five decisions. It adds a write path to IMAP that nothing else in the MVP needs, and both #10 and #11 get materially larger as a result.

[Hohnik]

Refinement: use BODY.PEEK[], not RFC822

The resolution above relies on readonly=True alone to stop the pull setting \Seen. That works, but it makes a load-bearing safety property depend on a SELECT argument that a future change could flip for an unrelated reason.

Scope of the hazard, stated precisely: the \Seen side effect is per-message and only fires for a FETCH of a non-PEEK body item (RFC822, RFC822.TEXT, BODY[...]). FLAGS, UID, ENVELOPE and RFC822.HEADER never trigger it — RFC822.HEADER is defined as equivalent to BODY.PEEK[HEADER]. So a writable SELECT would not mark the whole mailbox read at once; it would mark exactly the messages fetched, i.e. the newest 10 per folder. The damage is that this window refreshes every 60 seconds, so every new message would be marked read within a poll interval of arriving, before the user ever opened it — and because the server is authoritative here, sync would be steadily erasing MailChat's own unread state.

BODY.PEEK[] returns the same raw bytes without ever setting \Seen, whatever mode the folder was selected in. Adopting both:

• Fetch is (UID FLAGS BODY.PEEK[]), SELECT stays readonly=True.
• The FETCH response item comes back keyed BODY[] rather than RFC822; the bytes are identical, so parse() is unaffected.
• Group messages into person+subject conversations #10's test asserts both halves, since either alone would satisfy a weaker assertion while still leaving the side effect reachable.

#10 amended accordingly.