Antispam: plugin docs, the learning acceptance test, and a bootstrap that refuses bad corpora

docs/plugins.md described an SDK that no longer exists. It now covers
messages.raw/sample, actions.move_to_special, the envelope's account_id /
mailbox_special_use / account_state, the message.changed transition payload, the
message.actions.menu slot, Slot.title and .wm-menu-item — with the reasons, not
just the signatures. M3's acceptance is that a plugin can be written from this
file alone, and it had drifted.

Acceptance 4 (§C.8): a test that teaches 20 spam + 20 ham to a real engine and
checks the classifier generalises to held-out mail, keeps ham under the banner
threshold, and does not leak between users. It skips when no engine is reachable.
It does NOT assert the literal move_threshold — a synthetic fixture cannot reach
12.0 once the SMTP-time symbols are zeroed, which is the whole point of the
tuning. Recorded as OQ-8 rather than quietly asserting something weaker.

Bayes ignores training until min_learns, stock 200. For a personal mailbox that
means every correction appears to be ignored for months, so it is now 20.

The bootstrap would have made this filter worse. Accounts do not sync their
provider's spam folder by default, so the real corpus here is 3 junk beside 1,294
aged inbox — teaching both as found trains "everything is ham". It now refuses
below 10 spam samples (leaving the account unmarked so a later run can do it
properly) and otherwise caps ham at 3x the spam count.

Run against the live account, it correctly declined:
  "only 3 spam samples (need 10); enable spam-folder sync to build a corpus"

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018SqJYt7jD7oUEkoY68sBZo

docs/plugins.md

@@ -98,18 +98,55 @@ s = sdk("myplugin")
 | `s.blob` | blob store (`store`/`load`/`exists`/`remove`), keyed by user |
 | `s.outbox` | draft/send helpers (`upsert_draft`, `create_outbox`) |
 | `await s.http_get(url)` | HTTPS GET through the SSRF guard (blocks private IPs) |
-| `s.messages` | read a message: `envelope(user_id, id)`, `header(user_id, id, name)` |
-| `s.actions` | act on a message: `set_flags(...)`, `trash(user_id, id)` |
+| `s.messages` | read a message: `envelope`, `header`, `raw`, `sample` |
+| `s.actions` | act on a message: `set_flags`, `trash`, `move_to_special` |
 
 Plus, for routers: `CurrentUserId` (auth dependency → the user's uuid) and
 `require_csrf` (guard mutating routes).
 
-`s.messages.envelope(user_id, message_id)` returns
-`{message_id, subject, from_email, from_name, to: [{email,name}], flags}` or `None`.
-`s.messages.header(user_id, message_id, "List-Unsubscribe")` returns a raw header.
-`s.actions.set_flags(user_id, id, add=["\\Seen"], remove=[])` — user-settable flags
-only (`\Seen`, `\Flagged` [= "Pin"], `\Answered`). `s.actions.trash(user_id, id)`
-moves the message's thread to Trash (same as the UI Delete).
+### Reading a message
+
+`s.messages.envelope(user_id, message_id)` → `None`, or:
+
+```python
+{message_id, subject, from_email, from_name, to: [{email, name}], flags,
+ account_id,             # which account it arrived on
+ mailbox_special_use,    # "inbox" | "junk" | "sent" | … | None
+ account_state}          # "backfilling" | "live" | …
+```
+
+The last three matter more than they look. `message.new` fires for imported
+history as well as new arrivals, and for every folder — so a plugin that should
+only react to genuinely new inbox mail has to check `account_state == "live"`
+and `mailbox_special_use == "inbox"` itself. Acting on a backfill means acting on
+years of someone's archive, inline, in the sync loop.
+
+`s.messages.header(user_id, id, "List-Unsubscribe")` returns one raw header.
+
+`s.messages.raw(user_id, id)` returns the whole stored RFC822 as bytes, or `None`
+when the message isn't the user's or its blob is unreadable. For engines that
+need headers *and* body — spam scoring, signature checks.
+
+`s.messages.sample(user_id, account_id=…, special_use="junk", limit=500,
+older_than_days=30)` returns message **ids** from one folder, newest first. For
+building a corpus out of mail the user already has. Ids only, so the caller pulls
+bodies one at a time rather than materialising 500 messages at once.
+
+### Acting on a message
+
+`s.actions.set_flags(user_id, id, add=["\\Seen"], remove=[])` — user-settable
+flags only (`\Seen`, `\Flagged` [= "Pin"], `\Answered`).
+
+`s.actions.trash(user_id, id)` moves the message's whole **thread** to Trash
+(same as the UI Delete).
+
+`s.actions.move_to_special(user_id, id, "junk")` moves **one message** into the
+account's folder with that special-use, on the same path as the UI's move:
+optimistic DB update, then the IMAP move, then `message.changed`. Per-message on
+purpose — filing one spam reply must not drag a legitimate conversation with it.
+Returns `False` (never raises) when the message isn't the user's, the account has
+no such folder, or it is already there; treat that as "could not act", because
+mail must still arrive for an account whose server has no Junk folder.
 
 ---
 
@@ -133,6 +170,16 @@ Keyed by `(plugin, user_id, key)` — users can't see each other's values.
 
 Subscribe to §8.3 events (`message.new`, `flags.changed`, `thread.updated`, …).
 Handlers are `async def h(payload: dict) -> None`; every payload carries `user_id`.
+
+`message.changed` describes a **move**, not just a destination:
+
+```python
+{user_id, message_id, thread_id, mailbox_id,
+ previous_mailbox_id, special_use, previous_special_use}
+```
+
+Read the pair, not `special_use` alone — "now in Junk" and "moved out of Junk"
+are different facts, and only the transition distinguishes them.
 They fire wherever the event is published — `message.new` originates in the **worker**.
 
 ```python
@@ -276,8 +323,19 @@ async def bundle(filename: str) -> FileResponse:
 ```
 
 **Slots** (inject into the mail UI): `thread.toolbar`, `message.actions`,
-`message.banner`, `sidebar.section`, `settings.page`. `message.*` slots receive
-`props = { messageId }`.
+`message.actions.menu`, `message.banner`, `sidebar.section`, `settings.page`.
+`message.*` slots receive `props = { messageId }`.
+
+- `message.actions` sits on the message header — a persistent control.
+- `message.actions.menu` sits *inside* the Actions dropdown, beside Reply and
+  Delete — for a verb the user reaches for occasionally. The host closes the menu
+  after any click inside, so the bundle only has to act.
+- `settings.page` becomes its own section in Settings. Give the slot a `title`
+  and that is its nav label; without one it falls back to the plugin name:
+
+  ```python
+  Slot(name="settings.page", bundle=f"{_UI}/settings.js", title="Antispam filtering")
+  ```
 
 **Pages** (`app.page`): a full content-area view at `/p/<route>` with a nav entry.
 
@@ -299,7 +357,11 @@ ui_manifest = UiManifest(
 Style bundles with these theme-aware classes (they adapt to light/dark) instead of
 inline styles: `wm-root`, `wm-h2`, `wm-muted`, `wm-faint`, `wm-card`, `wm-row`,
 `wm-input`, `wm-select`, `wm-btn` / `wm-btn-primary` / `wm-btn-danger` / `wm-btn-ghost`,
-`wm-chip`, `wm-table`, `wm-list`.
+`wm-chip`, `wm-table`, `wm-list`, `wm-menu-item`.
+
+`wm-menu-item` is for the `message.actions.menu` slot: it applies the exact
+utilities the core Actions dropdown uses, so a plugin verb is indistinguishable
+from Reply or Delete rather than approximately similar.
 
 ---