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>

steward/alerts/service.py

@@ -203,18 +203,24 @@ async def breach_started(db, rule_ids) -> dict[str, datetime]:
     )).all())
 
 
+async def usernames(db, ids) -> dict[str, str]:
+    """{user id: username} for the given ids (None and repeats ignored)."""
+    from steward.models.users import User
+    ids = {i for i in ids if i}
+    if not ids:
+        return {}
+    return dict((await db.execute(select(User.id, User.username).where(User.id.in_(ids)))).all())
+
+
 async def active_rows(db, now: datetime) -> list[dict]:
     """The alerts page's active list, firing first, then no data, then
     acknowledged, then pending; within each the longest-running first. Each
     row: its state, rule, label, sentence, the link to what it watches, when
     the breach began, and who acknowledged it."""
-    from steward.models.users import User
     alerts = await active_alerts(db)
     started = await breach_started(db, {rule.id for state, rule in alerts
                                         if state.state.value in _BREACHING})
-    ackers = {s.acknowledged_by for s, _ in alerts if s.acknowledged_by}
-    names = dict((await db.execute(
-        select(User.id, User.username).where(User.id.in_(ackers)))).all()) if ackers else {}
+    names = await usernames(db, (s.acknowledged_by for s, _ in alerts))
     rows = []
     for state, rule in alerts:
         label = alert_label(state)
@@ -430,11 +436,12 @@ async def rule_fields(db, *, name: str, source_module: str, resource_name: str,
 WATCHED_FIELDS = ("source_module", "resource_name", "metric_name", "operator", "threshold")
 
 
-async def apply_rule_change(db, rule: AlertRule, fields: dict, *, enabled: bool | None = None) -> None:
+async def apply_rule_change(db, rule: AlertRule, fields: dict, *, enabled: bool | None = None,
+                            actor_id: str | None = None) -> None:
     """Apply validated fields (and optionally enabled) to a rule, in the
     caller's transaction. A change to what it watches, or disabling or
     re-enabling it, puts its alert back to inactive and starts its silence
-    watch over (core.alerts.reset_rule_state)."""
+    watch over (core.alerts.reset_rule_state); the event says who did it."""
     from steward.core.alerts import reset_rule_state
     changed = [k for k in WATCHED_FIELDS if k in fields and getattr(rule, k) != fields[k]]
     for k, v in fields.items():
@@ -444,11 +451,11 @@ async def apply_rule_change(db, rule: AlertRule, fields: dict, *, enabled: bool
     if enabled is not None:
         rule.enabled = bool(enabled)
     if disabling:
-        await reset_rule_state(db, rule, "rule disabled")
+        await reset_rule_state(db, rule, "rule disabled", actor_id)
     elif enabling:
-        await reset_rule_state(db, rule, "rule enabled")
+        await reset_rule_state(db, rule, "rule enabled", actor_id)
     elif changed:
-        await reset_rule_state(db, rule, "rule changed: " + ", ".join(changed))
+        await reset_rule_state(db, rule, "rule changed: " + ", ".join(changed), actor_id)
 
 
 async def add_rule(db, fields: dict, *, created_by: str, enabled: bool = True,
@@ -462,11 +469,14 @@ async def add_rule(db, fields: dict, *, created_by: str, enabled: bool = True,
     return rule
 
 
-async def acknowledge(db, rule_id: str, user_id: str) -> AlertState:
-    """Acknowledge a firing alert, in the caller's transaction.
+async def acknowledge(db, rule_id: str, user_id: str | None) -> AlertState:
+    """Acknowledge a firing alert, in the caller's transaction, and record it
+    in the alert's history as a firing → acknowledged event by `user_id`, so
+    who saw it outlives the alert (#5463).
 
     LookupError when the rule has no state; ValueError when it is not firing.
     """
+    from steward.core.alerts import _add_event
     state = (await db.execute(
         select(AlertState).where(AlertState.rule_id == rule_id))).scalar_one_or_none()
     if state is None:
@@ -479,6 +489,8 @@ async def acknowledge(db, rule_id: str, user_id: str) -> AlertState:
     state.acknowledged_by = user_id
     state.acknowledged_at = now
     state.last_transition_at = now
+    _add_event(db, rule_id, AlertStateEnum.firing.value, AlertStateEnum.acknowledged.value,
+               None, now, actor_id=user_id)
     return state