feat(alerts): an acknowledgement is on the record, with who made it (#5463)

#5463 "Acknowledgements on record: an event and who did it", step 1 of
milestone 499 "Alerts you can trust". The live walk in #5461 found that
acknowledging changed only the alert's current state: once it resolved,
nothing said who had acknowledged it or when.

- alert_events.actor_id (migration 0040): the person behind a transition.
- Acknowledging writes a firing → acknowledged event by the acknowledger.
- A rule edit, disable or enable that resets an alert carries its actor
  (web and MCP alike).
- The history page notes "acknowledged by X" and "rule disabled by X"; MCP
  get_alert_history returns `by`.
- One usernames() helper in alerts.service, used by the active list, the
  history page and the MCP tools.
- docs/core/alerting.md: the state diagram no longer shows an acknowledged
  alert re-firing, and says what an event records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/core/alerting.md

@@ -32,18 +32,25 @@ Notifications are sent via `asyncio.create_task()` after the function returns, s
 Each `AlertRule` has one associated `AlertState` row. The state transitions are:
 
 ```
-inactive ──(breached)──► pending ──(consecutive count met)──► FIRING
-                │                                               │
-                └──(recovered)──► inactive (no notification)   │
-                                                               │
-                                          FIRING ──(recovered)──► RESOLVED ──► inactive
-                                          FIRING ──(acknowledged)──► ACKNOWLEDGED
-                                          ACKNOWLEDGED ──(recovered)──► RESOLVED ──► inactive
-                                          ACKNOWLEDGED ──(re-breached)──► FIRING
+inactive ──(breached)──► pending ──(N breaching checks in a row)──► FIRING
+    ▲                      │                                          │
+    └──(an OK check)───────┘                                          │
+                                 FIRING ──(acknowledged)──► ACKNOWLEDGED
+                                 FIRING / ACKNOWLEDGED ──(M OK checks in a row)──► RESOLVED ──► inactive
 ```
 
+N is the rule's consecutive checks, M its checks to clear. An acknowledgement
+holds for as long as the breach lasts: only a resolve clears it, and a breaching
+check never sends an acknowledged alert back to firing.
+
 `RESOLVED` is transient — the evaluator writes the event and immediately sets state back to `inactive` within the same transaction. `RESOLVED` never persists as a final state in the DB.
 
+Every transition is an `AlertEvent`, the history the Alerts → History page and
+MCP `get_alert_history` read. A transition a person made carries them in
+`actor_id`: an acknowledgement (firing → acknowledged), or a rule edit, disable
+or enable that reset the alert (→ resolved, with a note such as "rule
+disabled"). Transitions caused by readings, or by Steward itself, have none.
+
 ### State Definitions
 
 | State | Meaning |
@@ -51,7 +58,7 @@ inactive ──(breached)──► pending ──(consecutive count met)──
 | `inactive` | Threshold not breached |
 | `pending` | Threshold breached but consecutive count not yet met; no notification sent |
 | `firing` | Consecutive count met; FIRING notification sent |
-| `acknowledged` | Operator acknowledged; suppresses repeat notifications; auto-clears on recovery |
+| `acknowledged` | Someone has seen it; no further notifications; clears when the readings recover |
 | `resolved` | Transient — notification sent, immediately transitions to `inactive` |
 
 ---