feat(tomtom_flow): TomTom Orbis vector flow-tile telemetry adapter + CENTRAL_TRAFFIC_FLOW (v0.9.3)

Third CENTRAL_TRAFFIC-family member, first telemetry traffic source. Polls a
configured tile coverage set (Idaho metros, z=10), fetches Orbis vector flow
tiles, decodes per-segment relative_speed + road geometry, emits one telemetry
Event per road segment per poll to the new CENTRAL_TRAFFIC_FLOW stream. Renders
as colored polylines (green free-flow -> red jam) on the /telemetry map.

Production code; supervisor + gui + ARCHIVE restart (NEW event-bearing stream
central.traffic_flow.> -> archive must resubscribe). Ships disabled; needs a
"tomtom" api key in config.api_keys before enable.

- Subject central.traffic_flow.{z}.{x}.{y} (token traffic_flow, non-overlapping
  with central.traffic.>). category="flow.tomtom_flow" -> GUI event_type "flow".
- Severity from relative_speed: >=0.75=1, 0.5-0.75=2, 0.25-0.5=3, <0.25=4.
- Cadence 300s; 7-day retention (high-volume telemetry). Dedup minute-bucketed,
  inherited from the v0.9.1 SourceAdapter mixin.
- Shared tomtom_flow_parse module (decode + slippy-tile georeference) reused by
  the v0.9.4 on-demand passthrough endpoint.
- Generic framework change (Option A, ~3 lines, inert for the other 14
  adapters): Geo.geometry optional field + archive _build_geom_sql prefers it,
  so segments persist their real LineString to the PostGIS geom column.
- Idaho-only (Orbis tier confirmed live). Cameras + Navi passthrough are follow-ups.
- deps: mapbox-vector-tile (vector PBF decode); itsdangerous promoted to an
  explicit dependency (gui/csrf.py + gui/wizard.py imported it as an undeclared
  transitive that uv re-lock would otherwise prune).

Full suite: 780 passed, 1 skipped (central and unprivileged zvx, 3x each).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/CONSUMER-INTEGRATION.md

@@ -132,6 +132,7 @@ Central's archive.
 | `CENTRAL_DISASTER` | `central.disaster.>` | 7 | 1 GiB | ✓ | ✓ |
 | `CENTRAL_HYDRO` | `central.hydro.>` | 7 | 1 GiB | ✓ | ✓ |
 | `CENTRAL_TRAFFIC` | `central.traffic.>` | 7 | 1 GiB | ✓ | ✓ |
+| `CENTRAL_TRAFFIC_FLOW` | `central.traffic_flow.>` | 7 | 1 GiB | ✓ | ✓ |
 | `CENTRAL_META` | `central.meta.>` | 1 | 1 GiB | — | ✓ |
 
 Retention and storage caps are migration-seeded defaults visible in `config.streams`;
@@ -1517,6 +1518,40 @@ road name, description, county, severity). Verified for Idaho only.
 - **Removal semantics:** none in v1. Events age out of the upstream feed; the
   14-day dedup sweep expires stale ids.
 
+### tomtom_flow — TomTom Orbis vector flow tiles (per-segment speed, telemetry)
+
+Per-road-segment traffic speed from TomTom Orbis **vector** flow tiles, polled for
+a configured tile coverage set (Idaho metros at z=10). Each segment is one
+telemetry Event carrying a LineString/MultiLineString geometry (drawn as a
+colored polyline on the `/telemetry` map) — green free-flowing, red jammed.
+
+- **Stream:** `CENTRAL_TRAFFIC_FLOW` (telemetry; `/telemetry` tab).
+- **Subject pattern:** `central.traffic_flow.{z}.{x}.{y}` — tile-routable (segments
+  carry no state). Distinct token from `central.traffic.>` (no overlap).
+- **GUI event_type:** `flow` (from `category = "flow.tomtom_flow"`).
+- **Cadence default:** 300s (5 min). **Retention:** 7 days (high-volume telemetry).
+- **Dedup key shape:** `{z}/{x}/{y}:{segment_index}:{minute}` — minute-bucketed so
+  an adapter poll and an on-demand passthrough fetch of the same tile in the same
+  minute don't double-store (TomTom advertises a 60s tile TTL).
+- **Event.data fields:**
+
+  | key | type | nullable | description |
+  |---|---|---|---|
+  | `relative_speed` | float | yes | 0-1 ratio of current to free-flow speed (drives severity + color) |
+  | `road_category` | str | yes | `motorway` / `trunk` / `primary` / `secondary` |
+  | `tile_z` / `tile_x` / `tile_y` | int | no | Source slippy tile |
+  | `segment_index` | int | no | Index within the tile's "Traffic flow" layer |
+  | `tier` | str | no | `orbis` |
+  | `fetched_at` | str (ISO 8601 UTC) | no | Poll timestamp |
+
+  Geometry (the road polyline) is on `geo.geometry`, persisted to the PostGIS
+  `geom` column and returned by the map as GeoJSON.
+- **Severity:** from `relative_speed` — `>=0.75`=1 (free), `0.5-0.75`=2, `0.25-0.5`=3,
+  `<0.25`=4 (jam).
+- **Decipherable as-is:** yes — speed ratio + road class + geometry are self-contained.
+- **Removal semantics:** none; time-series telemetry, one snapshot per poll, swept
+  by the 7-day retention.
+
 ### wzdx — FHWA Work Zone Data Exchange (state-DOT work zones)
 
 Active road work zones discovered from the federal WZDx Feed Registry and each

docs/PRODUCER-INTEGRATION.md

@@ -362,7 +362,7 @@ central.<domain>.<subtype>[.<dimensions>...]
 ```
 
 - `<domain>` is one of `wx`, `fire`, `quake`, `space`, `disaster`, `hydro`,
-  `traffic`, `meta` (the current set — see [§8](#8-the-streamentry-registry) for adding
+  `traffic`, `traffic_flow`, `meta` (the current set — see [§8](#8-the-streamentry-registry) for adding
   one). Operators MUST be able to subscribe to all of one domain with
   `central.<domain>.>`.
 - `<subtype>` is adapter-driven and identifies the event category within the
@@ -551,6 +551,7 @@ STREAMS: list[StreamEntry] = [
     StreamEntry("CENTRAL_DISASTER", "central.disaster.>"),
     StreamEntry("CENTRAL_HYDRO",    "central.hydro.>"),
     StreamEntry("CENTRAL_TRAFFIC",  "central.traffic.>"),
+    StreamEntry("CENTRAL_TRAFFIC_FLOW", "central.traffic_flow.>"),
     StreamEntry("CENTRAL_META",     "central.meta.>", event_bearing=False),
 ]
 ```