Document active alert filtering behavior

docs/api.md

@@ -194,10 +194,14 @@ GET /conditions/current?format=json&precision=0
 GET /alerts/active
 ```
 
-Returns the latest active-alert snapshot.
+Returns the latest stored alert run filtered to alerts active at request time.
 
 Query parameters: `format`, `units`.
 
+When no latest alert run exists, `data` is null. When a latest run exists but
+no alerts are currently active, `data` remains an object and `alerts` is an
+empty array.
+
 Run `data` fields:
 
 | Field | Type | Notes |
@@ -207,6 +211,10 @@ Run `data` fields:
 | `latitude`, `longitude` | number | optional |
 | `alerts` | array | active alerts, possibly empty |
 
+Alerts are active when `messageType` is not `Cancel`, `effective` is absent or
+at or before request time, and `expires` is absent or after request time.
+`onset` is presented when available but is not used as the active boundary.
+
 Alert fields include `id`, `event`, `headline`, `severity`, `urgency`,
 `certainty`, `status`, `messageType`, `category`, `response`, `description`,
 `instruction`, `sent`, `effective`, `onset`, `expires`, `areaDescription`,

docs/internal/http-adapter.md

@@ -9,7 +9,7 @@ This document describes the internal HTTP adapter under
 The HTTP adapter turns feedapi route definitions into calls on the application
 service boundary. It owns route registration, query binding, request validation,
 forecast day-slice filtering, outlook active/location filter construction,
-response envelopes, and template names.
+alert active-time selection, response envelopes, and template names.
 
 ## Inputs and Outputs
 
@@ -35,6 +35,7 @@ The adapter may:
 - call the `Service` interface;
 - choose the presenter function for an endpoint;
 - filter forecast copies for `/today` and `/tomorrow`;
+- pass the current UTC instant to active-alert application filtering;
 - construct outlook active/location filters.
 
 The adapter must not:
@@ -61,9 +62,9 @@ declared in endpoint definitions, but `templates.base_dir` is loaded by feedapi.
 
 ## State
 
-The adapter has no durable state. `forecastNow` and `outlookNow` are
+The adapter has no durable state. `forecastNow`, `alertNow`, and `outlookNow`
-package-level state only to make time-dependent endpoint tests deterministic.
+are package-level state only to make time-dependent endpoint tests
-Do not add request caches or cross-request mutable state here.
+deterministic. Do not add request caches or cross-request mutable state here.
 
 ## Route Registry
 
@@ -131,6 +132,12 @@ Filtering behavior:
 The package variable `forecastNow` exists so endpoint tests can make day-slice
 behavior deterministic.
 
+## Alert Active Time
+
+`/alerts/active` uses the shared `format` and `units` binder. The handler calls
+the application service with `alertNow().UTC()` so active alert filtering uses
+the request-time instant while remaining deterministic in endpoint tests.
+
 ## Outlook Filters
 
 Outlook route filters are built at the HTTP boundary and passed to the

docs/internal/postgres-repository.md

@@ -79,7 +79,8 @@ successful responses with `data: null`.
 - `CurrentConditions`: aggregates recent rows from `observations` using the
   application-provided observation window.
 - `LatestAlertRun`: latest row from `alert_runs`, then child `alerts` and
-  `alert_references`.
+  `alert_references`. This is the latest stored alert snapshot; active-time
+  filtering is performed by the application service.
 - `LatestHourlyForecast`: latest `forecasts` row where `product = 'hourly'`,
   then child `forecast_periods`.
 - `LatestNarrativeForecast`: latest `forecasts` row where

docs/policy/architecture.md

@@ -100,7 +100,7 @@ Outputs are HTTP responses in JSON, XML, or text format. All public endpoint han
 
 `weatherapi` owns no durable weather state. Its runtime state is limited to process memory, loaded configuration, HTTP server state, template registry, renderer registry, and database connection pools. Durable weather data and schema creation are external concerns owned by `weatherfeeder` and Postgres.
 
-The API currently serves latest-resource views: latest observation, current conditions, latest active alerts run, latest hourly forecast, latest narrative forecast, latest forecast discussion, latest weather story run, latest individual weather story, and latest convective outlook run. Forecast `today` and `tomorrow` routes derive filtered copies from the latest run. Convective outlook active and location routes derive filtered copies from the latest run.
+The API currently serves latest-resource views: latest observation, current conditions, latest hourly forecast, latest narrative forecast, latest forecast discussion, latest weather story run, latest individual weather story, and latest convective outlook run. Active alert, forecast `today` and `tomorrow`, and convective outlook active/location routes derive filtered copies from the latest stored run.
 
 ## Configuration and CLI Boundaries