mesh-catalog/modules/mesh-mail-reader/README.md

mesh-mail-reader — the default holder of mail-reading

Design 59, milestone 2 (mail reading); built from mesh-mail's own source, like mesh-mail-web and mesh-mail-notifier (novox/hq ADR 0459). One instance, held once for the mesh, on the machine mesh-mail runs on, under its own account (runs-as) — it hears mesh-mail's restricted stream MAIL, which the operator account never does. It reads mail; it moves, flags, deletes and sends nothing (ADR 0459 §11).

What it does, and what is still to land

• Claims mail-reading (held once for the mesh), declared in mesh-mail's own manifest beside its three mail seats, serving six verbs: entries, groups, correct, lessons, undo, status (ADR 0459 §2). Each answers only a caller the trusted setting callers names (default ["mesh-mail-web"]); any other caller is refused, naming why.
• Hears mesh-mail's added events and judges a batch of up to 10 at a time against a question put to claude_code_judge, keeping an entry per mail — never its body — in its own database (issue 1518, 1427; not yet built).
• Keeps a health of its own, mail_reader_health: unhealthy once a judgement is refused, times out or answers out of shape; healthy again once one succeeds (issue 1519; not yet built).
• Tells the operator at most once a batch when a mail matters, and corrects itself at once, keeping a reading lesson, when the operator says it judged wrong (issue 1428, 1429, 1522; not yet built).

Until each of those issues lands, its own verb answers that it is not built yet, once the caller check above has already passed or refused.

Its database

Its own postgres-database (issue 1517; not yet declared in the manifest until then): mail entries, mail groups, reading lessons, the mails heard but not yet read, and its own health state. No column holds a mail body or text taken from one.

Tools

tool	does
mail-reading.entries	every mail entry: headers, mail group, summary, mark and why, due date. Read-only
mail-reading.groups	every mail group a batch has made, largest first. Read-only
mail-reading.correct	correct one entry's mark, why or due date; kept at once as a reading lesson
mail-reading.lessons	the reading lessons kept, at most 40. Read-only
mail-reading.undo	undo one reading lesson
mail-reading.status	lessons kept, undone, and per 100 mails read this week. Read-only
mail_reader_health	how mesh-mail-reader is: unhealthy once a judgement is refused, times out or answers out of shape, naming which and since when; healthy once one succeeds. Read-only

Where it runs

Its own account (runs-as), because it hears mesh-mail's restricted stream MAIL (novox/hq ADR 0376 §2). Held once for the mesh, on the machine mesh-mail runs on; it is granted reading only, after issue 1227's split of mesh-mail's grants is delivered (ADR 0472: that split is won't-fix — mesh-mail's grants stays one list per account, and mesh-mail-reader is put on it after delivery, never asking to send).