feat(okw): network map endpoint — local facilities ∪ Maps of Making

[touchthesun]

What

Backend for the dashboard geographic map (review note #1). The map's whole point is showing the network — but local data is only 79 facilities. Maps of Making (MoM) has ~3,200 geolocated spaces, already integrated with matching via SPARQL, so this unions the two into one source-agnostic point set and serves it to the map.

Approach

Built on the existing mom_bridge SPARQL work rather than reinventing it. The union is server-side (keeps SPARQL off the browser, cacheable, source-agnostic), MoM loads by default, and the map degrades gracefully when MoM is unreachable.

Changes

• mom_bridge: fetch_all_mom_spaces() (all spaces with geo — a non-process-filtered variant of the existing query) + MoMSpacesCache, a 24h TTL cache that:
  • degrades gracefully — keeps serving stale data if a refresh fails, and only reports mom_available: false when nothing was ever fetched;
  • serializes concurrent refreshes (no thundering herd on a cold cache);
  • exposes refresh() / invalidate() as the cache-refresh hooks other events can trigger (plus force_refresh on the endpoint / --refresh on the CLI).
• OKWService.get_map_points(): source-labeled union {id, name, lat, lon, source} of local facilities (via the Location.coordinates() accessor from feat(okw): typed coordinate accessor + structured lat/lon in API #226) + MoM spaces. Local facilities without coordinates are counted (dropped_no_coords), not plotted.
• GET /api/okw/map (include_mom, force_refresh) — registered before /{id} so map isn't captured as a facility id. Returns points + counts + mom_available.
• CLI: ohm okw map (--no-mom, --refresh), HTTP with direct-service fallback — parity.
• Docs: OKW model doc gains a network-map section + CLI/endpoint table rows.
• Tests: fetch parsing (incl. malformed-row skipping), cache (TTL / refresh / invalidate / stale-on-failure / never-fetched), union + source labels + dropped count (unit); endpoint local-only path (TestClient integration, no network).

Verification

make ready — all gates green (563 passed, parity 4/4, docs ✓). MoM endpoint confirmed reachable during design (3,193 spaces with geo).

Scope

This is the read/display slice of the documented "External network integration" epic. Admin enable/disable config for networks stays deferred to that epic. The frontend map (react-leaflet + clustering) consuming /api/okw/map lands next on frontend-dev.

🤖 Generated with Claude Code