.nornir/collectors/osm-admin.md

Collector: `osm-admin` (adopted — WAVE 1)

The administrative-boundaries daemon. Extracts OSM boundary=administrative relations (Sweden's 290 kommuner + 21 län/regioner, then the Nordics, then the world) into an admin_units table (WKB borders + the per-country division ladder — see src/osm_admin.rs::country_division_name). The kommun/region cut behind the borders facet. Adopted to the daemon architecture (../collectors-daemon-design.md, §11) as a warehouse-sink (Iceberg) daemon. Implementor: src/iceberg_daemons.rs (OsmAdminDaemon), behind --features daemon. Rides the existing pure tag-filter src/osm_admin.rs::extract_admin_units + admin_batch.

Config trait (Settings ▸ Collectors ▸ osm-admin)

enabled:      bool
url:          String   // Overpass/features JSON of boundary=administrative relations (per-deployment)
admin_levels: String   // e.g. 4,7 (län + kommun) — advisory
table:        String   // Iceberg table  (default admin_units)

State machine (State trait)

Offline → Downloading(fetch %) → Indexing(filter+extract) → Online   // admin units landed
        → Failed{reason}                                             // empty-is-RED / no url / errors

The pure filter keeps only boundary=administrative features with a parseable admin_level (a non-boundary way is dropped), derives country from ISO3166-1/-2, and names each level per country. The State Facet renders sink=iceberg, phase, table, rows_written, last_run_unix, error.

Storage — Iceberg (warehouse-sink)

Units land through CollectorCtx.warehouse into admin_units. Distinct from osm-cut (which writes the packed region cut as FILES): this is the tabular borders cut — the same OSM family, a different sink.

Acquisition — the fetch seam

Fetches a JSON feature array ([{id, tags}, …] — an Overpass/features export) through CollectorCtx.fetch. The default url is empty (Overpass query wired per-deployment): an enabled daemon with no url is a loud Failed (a fact), not a silent green. Fetch + extract run off the reactor via spawn_blocking.

empty-is-RED

An enabled extract with 0 admin units ⇒ Failed{reason} (red), never silent green.

Tests (`src/iceberg_daemons.rs`)

osm_admin_daemon_reaches_online_and_sinks_units — the synthetic feature array (4 boundaries
- 1 dropped highway) drives fetch→filter→append→Online, exactly 4 units in admin_units.
shared empty-is-RED / schema / matrix-colour tests.

Follow-on (mechanical)

A live Overpass query builder from admin_levels + region bbox; the PBF-relation read (--features osm, osm.rs) as an alternative source for a whole-planet cut; the WorldAdminTrie drill-down index (world ▸ Nordics ▸ Sweden ▸ län ▸ kommun) as a second table.

Collector: osm-admin (adopted — WAVE 1)