Suppress superseded alerts in the /alerts/active endpoint

docs/api.md

@@ -194,7 +194,8 @@ GET /conditions/current?format=json&precision=0
 GET /alerts/active
 ```
 
-Returns the latest stored alert run filtered to alerts active at request time.
+Returns the latest stored alert run filtered to alerts active at request time,
+omitting older alerts superseded by newer alert references in the same run.
 
 Query parameters: `format`, `units`.
 
@@ -216,6 +217,9 @@ at or before request time, and the alert end boundary is absent or after request
 time. The end boundary prefers `ends`; if `ends` is absent, `expires` is used as
 a fallback for older rows or providers that do not supply an alert-period end.
 `onset` is presented when available but is not used as the active boundary.
+After active-time filtering, alerts referenced by another alert in the same run
+are omitted as superseded. References from update and cancel messages are both
+honored, even when the referencing alert is not itself returned.
 
 Alert fields include `id`, `event`, `headline`, `severity`, `urgency`,
 `certainty`, `status`, `messageType`, `category`, `response`, `description`,

docs/internal/http-adapter.md

@@ -136,7 +136,10 @@ behavior deterministic.
 the application service with `alertNow().UTC()` so active alert filtering uses
 the request-time instant while remaining deterministic in endpoint tests. The
 application service prefers alert `ends` over `expires` when deciding whether an
-alert has ended.
+alert has ended. The application service also suppresses alerts referenced by
+another alert in the same latest run. This supersession rule uses alert
+references from update and cancel messages, even when the referencing message is
+not returned by `/alerts/active`.
 
 ## Outlook Filters