Document SPC outlook support

docs/integrations/events.md

@@ -37,6 +37,7 @@ Canonical schemas emitted after normalization:
 | `forecast_discussion` | `weather.forecast_discussion.v1` | `WeatherForecastDiscussion` |
 | `weather_story` | `weather.weather_story.v1` | `WeatherStoryRun` |
 | `alert` | `weather.alert.v1` | `WeatherAlertRun` |
+| `outlook` | `weather.outlook.v1` | `WeatherOutlookRun` |
 
 Raw upstream schemas emitted by current sources:
 
@@ -51,6 +52,7 @@ Raw upstream schemas emitted by current sources:
 | `weather_story` | `raw.nws.weatherstories.v1` | NWS weather stories JSON |
 | `forecast` | `raw.openmeteo.hourly.forecast.v1` | Open-Meteo hourly forecast JSON |
 | `alert` | `raw.nws.alerts.v1` | NWS alerts JSON |
+| `outlook` | `raw.spc.convective_outlook.v1` | SPC convective outlook raw bundle |
 
 `standards.SchemaRawOpenWeatherHourlyForecastV1` exists in code, but no current
 registered source emits it.
@@ -218,6 +220,55 @@ Payload type: `WeatherAlertRun`.
 `references[]` entries contain optional `id`, `identifier`, `sender`, and
 `sent` fields.
 
+## `weather.outlook.v1`
+
+Payload type: `WeatherOutlookRun`.
+
+The current producer is the SPC convective outlook normalizer. It emits Day 1-3
+convective outlook polygons for categorical, tornado, hail, and wind products.
+All timestamps are UTC.
+
+| Field | Type | Required | Notes |
+|---|---|:---:|---|
+| `locationId` | string | no | Operator-configured location identifier. |
+| `locationName` | string | no | Operator-configured location label. |
+| `latitude` | number | no | Configured point latitude in decimal degrees. |
+| `longitude` | number | no | Configured point longitude in decimal degrees. |
+| `asOf` | timestamp | yes | Snapshot time. For SPC, this is the latest outlook issue time when available. |
+| `issuedAt` | timestamp | no | Latest issue time across outlook features when any feature exists. |
+| `outlooks` | array | yes | Ordered outlook polygons. |
+
+`outlooks[]` entries:
+
+| Field | Type | Required | Notes |
+|---|---|:---:|---|
+| `id` | string | yes | Deterministic weatherfeeder outlook identifier. |
+| `provider` | string | yes | Current value is `spc`. |
+| `product` | string | yes | Current value is `convective`. |
+| `day` | integer | yes | SPC outlook day, currently `1`, `2`, or `3`. |
+| `outlookType` | string | yes | `categorical`, `tornado`, `hail`, or `wind`. |
+| `label` | string | yes | SPC outlook label such as `SLGT` or `15`. |
+| `labelText` | string | no | Human label text from SPC, when present. |
+| `severityRank` | integer | no | SPC `DN` value, when present. |
+| `validFrom` | timestamp | yes | Valid period start. |
+| `validTo` | timestamp | yes | Valid period end. |
+| `issuedAt` | timestamp | yes | Feature issue time. |
+| `expiresAt` | timestamp | yes | Expiration time; currently equal to `validTo`. |
+| `forecaster` | string | no | SPC forecaster text, when present. |
+| `headline` | string | no | Matching Day 1-3 print-page product title. |
+| `summary` | string | no | Text from the print-page `...SUMMARY...` section. |
+| `discussion` | string | no | Cleaned full print-page product text. |
+| `sourceUrl` | string | no | GeoJSON product URL for this outlook feature. |
+| `imageUrl` | string | no | Reserved for provider image URLs; currently empty. |
+| `containsLocation` | boolean | yes | Whether the configured point is inside or on the boundary of the polygon. |
+| `geometry` | object | yes | Compact GeoJSON `Polygon` or `MultiPolygon` geometry. |
+
+`geometry` preserves the SPC feature geometry as compact GeoJSON using
+`[longitude, latitude]` coordinate order. `containsLocation` is computed with
+that geometry and the configured source `latitude`/`longitude`; boundary points
+count as contained. All outlook polygons are emitted, including polygons that do
+not contain the configured point.
+
 ## Compact Example
 
 ```json

docs/integrations/postgres.md

@@ -23,6 +23,7 @@ Events are mapped only for canonical weather schemas:
 - `weather.forecast_discussion.v1`
 - `weather.weather_story.v1`
 - `weather.alert.v1`
+- `weather.outlook.v1`
 
 Unsupported schemas produce no writes for this sink. Mapped events are inserted
 transactionally. Inserts use ordinary `INSERT`; duplicate primary keys fail the
@@ -56,6 +57,8 @@ Parent tables store the feed event envelope:
 | `alert_runs` | `event_id` | `as_of` |
 | `alerts` | `run_event_id`, `alert_index` | `as_of` |
 | `alert_references` | `run_event_id`, `alert_index`, `reference_index` | `as_of` |
+| `outlook_runs` | `event_id` | `as_of` |
+| `outlooks` | `run_event_id`, `outlook_index` | `as_of` |
 
 ## Table Contract
 
@@ -379,6 +382,72 @@ Indexes:
 | `sender` | `TEXT` | yes | `payload.alerts[].references[].sender` |
 | `sent` | `TIMESTAMPTZ` | yes | `payload.alerts[].references[].sent` |
 
+### `outlook_runs`
+
+Primary key: `event_id`
+
+Prune column: `as_of`
+
+Indexes:
+
+- `idx_wf_outlook_run_location_as_of` on `location_id`, `as_of`
+- `idx_wf_outlook_run_as_of` on `as_of`
+
+| Column | Type | Null | Source |
+|---|---|:---:|---|
+| `event_id` | `TEXT` | no | `event.id` |
+| `event_kind` | `TEXT` | no | `event.kind` |
+| `event_source` | `TEXT` | no | `event.source` |
+| `event_schema` | `TEXT` | no | `event.schema` |
+| `event_emitted_at` | `TIMESTAMPTZ` | no | `event.emitted_at` |
+| `event_effective_at` | `TIMESTAMPTZ` | yes | `event.effective_at` |
+| `location_id` | `TEXT` | yes | `payload.locationId` |
+| `location_name` | `TEXT` | yes | `payload.locationName` |
+| `latitude` | `DOUBLE PRECISION` | yes | `payload.latitude` |
+| `longitude` | `DOUBLE PRECISION` | yes | `payload.longitude` |
+| `as_of` | `TIMESTAMPTZ` | no | `payload.asOf` |
+| `issued_at` | `TIMESTAMPTZ` | yes | `payload.issuedAt` |
+| `outlook_count` | `INTEGER` | no | `len(payload.outlooks)` |
+
+### `outlooks`
+
+Primary key: `run_event_id`, `outlook_index`
+
+Prune column: `as_of`
+
+Foreign key: `run_event_id` references `outlook_runs(event_id)` with cascade
+delete.
+
+Indexes:
+
+- `idx_wf_outlooks_contains_valid` on `contains_location`, `valid_from`, `valid_to`
+- `idx_wf_outlooks_day_type_label` on `day`, `outlook_type`, `label`
+- `idx_wf_outlooks_valid` on `valid_from`, `valid_to`
+
+| Column | Type | Null | Source |
+|---|---|:---:|---|
+| `run_event_id` | `TEXT REFERENCES outlook_runs(event_id) ON DELETE CASCADE` | no | Parent event ID. |
+| `outlook_index` | `INTEGER` | no | `payload.outlooks[]` index. |
+| `as_of` | `TIMESTAMPTZ` | no | Parent `payload.asOf` |
+| `product` | `TEXT` | no | `payload.outlooks[].product` |
+| `day` | `INTEGER` | no | `payload.outlooks[].day` |
+| `outlook_type` | `TEXT` | no | `payload.outlooks[].outlookType` |
+| `label` | `TEXT` | no | `payload.outlooks[].label` |
+| `label_text` | `TEXT` | yes | `payload.outlooks[].labelText` |
+| `severity_rank` | `INTEGER` | yes | `payload.outlooks[].severityRank` |
+| `valid_from` | `TIMESTAMPTZ` | no | `payload.outlooks[].validFrom` |
+| `valid_to` | `TIMESTAMPTZ` | no | `payload.outlooks[].validTo` |
+| `issued_at` | `TIMESTAMPTZ` | no | `payload.outlooks[].issuedAt` |
+| `expires_at` | `TIMESTAMPTZ` | no | `payload.outlooks[].expiresAt` |
+| `forecaster` | `TEXT` | yes | `payload.outlooks[].forecaster` |
+| `headline` | `TEXT` | yes | `payload.outlooks[].headline` |
+| `summary` | `TEXT` | yes | `payload.outlooks[].summary` |
+| `discussion` | `TEXT` | yes | `payload.outlooks[].discussion` |
+| `source_url` | `TEXT` | yes | `payload.outlooks[].sourceUrl` |
+| `image_url` | `TEXT` | yes | `payload.outlooks[].imageUrl` |
+| `contains_location` | `BOOLEAN` | no | `payload.outlooks[].containsLocation` |
+| `geometry_json` | `TEXT` | no | Compact JSON from `payload.outlooks[].geometry` |
+
 ## Retention
 
 When sink param `prune` is set, every successful write transaction deletes rows
@@ -401,3 +470,5 @@ binary does not provide CLI commands for them.
 - `WeatherAlertRun`: read `alert_runs`, join `alerts` by `run_event_id` ordered
   by `alert_index`, then join `alert_references` by `run_event_id` and
   `alert_index` ordered by `reference_index`.
+- `WeatherOutlookRun`: read `outlook_runs`, then join `outlooks` by
+  `run_event_id` ordered by `outlook_index`.