refactor: separate map feature queries and source records

docs/CODE-BOUNDARIES.md

@@ -589,9 +589,9 @@ installation footprints, and annotation geometry (administrative boundaries,
 neighborhoods, streets, building/grounds outlines and monument candidates).
 Nominatim forward/reverse lookup does not replace those queries. Layer source
 interfaces select traffic, camera and installation ingestion separately;
-annotation `boundaries.query` still uses Overpass QL and OSM-shaped elements.
-Replacing that service with a different query language requires operation-level
-feature/geometry adapters, not just changing its URL. Rendering and geometry
+annotation and camera-framing consumers use the feature operations documented
+below. The Overpass adapter translates those operations and normalizes records;
+an alternate backend implements that source interface. Rendering and geometry
 selection remain consumers of those results.
 
 `./sources/nominatim` exports the lower-level JSONv2 client and normalizers for
@@ -606,3 +606,39 @@ Runtime formatting discovers tracked and new non-ignored `.js`, `.mjs` and `.cjs
 files under the configured owned roots. Tests retain explicit adoption. Git and
 Prettier exclusions keep local/generated data out; resolved paths are validated
 before any writes. New runtime modules do not need another scope-list entry.
+
+## Map-feature sources
+
+Application request services expose `features`. Callers may supply another source
+with the same operations; the default is `createOverpassFeatureSource` from
+`sources/map-features`. Legacy boundary-query configuration remains supported.
+Search and annotation code request candidates and rank them without constructing
+query-language strings or decoding backend tags and relation members.
+
+| Operation                                                             | Result used by the caller                               |
+| --------------------------------------------------------------------- | ------------------------------------------------------- |
+| `getAdministrativeAreas(point, options)`                              | Named administrative candidates and geometry references |
+| `getAreaGeometry(id, options)`                                        | Geometry for one selected administrative reference      |
+| `getNeighborhoodAreas(point, options)`                                | Neighborhood polygon candidates                         |
+| `getStreetAreas(point, options)` / `getStreetLines(point, options)`   | Named areas and road lines for street annotations       |
+| `getFootprints(point, options)` / `getEnclosingAreas(point, options)` | Building and surrounding-ground candidates              |
+| `getMonuments(point, options)`                                        | Named point candidates                                  |
+| `getFocusFootprints(point, options)`                                  | Building/landmark candidates for camera framing         |
+
+Points use `{lat, lon}`. Options carry `signal`. A successful array, including an
+empty array, is definitive; `null` means a transient failure;
+`{rateLimited: true, retryAfterMs}` retains a provider's retry delay. Candidates
+carry `id`, `names` (`primary`, `english`, `official`, `alternate`, `short`),
+`coordinates` (objects with `lat` and `lon`), `building` and optional `heightM`,
+`center` and `point`. Administrative candidates use `category: 'administrative'`
+and a numeric `level`. Provenance may retain compatibility metadata, but ranking
+does not use backend tags. The Overpass implementation retains its existing
+operation-specific query radii and deadlines.
+
+Traffic's source response decodes to `{roads}`. Each road supplies longitude/latitude
+`coordinates`, a road-class `type` and `oneway` (`-1`, `0` or `1`). Scene construction
+still owns thinning, terrain sampling and Cartesian waypoints. Installation
+sources supply `{records, droppedCount, status, saturated}`; viewport filtering,
+exact-bound retry and rendering stay in the layer. Legacy cache saturation is
+decoded in the source. Source and geometry modules remain independent of Cesium,
+DOM and platform middleware.

docs/CURRENT-STATE.md

@@ -1,5 +1,6 @@
 # God's Eye View Current State
 
+Search framing and annotations request semantic map features from an explicit source. The Overpass adapter owns bounded queries, member/tag decoding and request deadlines; callers retain candidate ranking, outline caching, deferred retries and scene placement. Empty, transient and throttled outcomes remain distinct. Traffic sources return road records and installation sources return mapped records with freshness/saturation metadata, so their layers no longer decode upstream elements. ALPR already normalizes its records in the source. Default providers, footprints, road directions, exact-viewport retries and source attribution are unchanged.
 Transit snapshot and selected-history reads use an explicit source interface. The standalone source selects the existing routes; rendering, playback and selection retain their existing owners. A portable request service owns registered-feed admission, bounded decoding, cache/revalidation, backoff and history; development and preview use the same thin adapter. Compatibility exports and source attribution are preserved.
 
 Place search accepts an explicit Nominatim provider with independently configured search and reverse endpoints. The default offline/Google/Photon/local-fallback order is unchanged when no provider is selected. Provider adapters share normalized coordinates, viewport framing and reverse labels; roads and boundary geometry remain separate services. Portable capped-response and Overpass lexical helpers are exported independently of the Node server.