feat(map): cache and search reference stations

services/map-gateway/README.md

@@ -13,6 +13,10 @@
 - защищает proxy allowlist-ом upstream hosts, HTTPS-only правилом, лимитами размера и token-free cache key;
 - ведёт лёгкий persistent cache index и health/stats без автоматического удаления уже записанных tiles.
 - отдаёт Engine отдельный provider-neutral generation геозон из проверенного профиля: текущий backend — версионированный snapshot Дептранса, будущий API-адаптер обязан материализовать тот же envelope и не меняет L2-потребителя.
+- отдаёт Foundry provider-neutral справочный snapshot транспортных станций:
+  seed Москвы из проверенного legacy MMAP donor плюс bounded spatial
+  cache OSM для новых viewport. L1/L2 и пользовательские Data Product в этом
+  контуре не участвуют.
 
 ## API
 
@@ -20,8 +24,44 @@
 GET /healthz
 GET /api/map/ion/assets/:assetId/endpoint
 GET|HEAD /api/map/cache?url=<encoded-upstream-url>
+GET /api/map/reference-sources/v1/profiles/transport-stations.v1/current
+GET /api/map/reference-sources/v1/profiles/transport-stations.v1/current?bbox=west,south,east,north
+GET /api/map/reference-sources/v1/profiles/transport-stations.v1/search?q=<exact-name>&limit=12
 ```
 
+Reference-station route возвращает `nodedc.map-reference.snapshot/v1` и только
+два онтологических типа: `map.station` и `map.terminal`. Категории v1 —
+`metro`, `railway_station`, `railway_terminal`. Проекция allowlist-ит имена,
+operator/network, `uic_ref`, wheelchair и геометрию; raw OSM tags, upstream
+endpoint и provider credentials в snapshot отсутствуют.
+
+Seed проверяется на старте и покрывает Москву без сетевого запроса. Для bbox за
+пределами покрытия Gateway делит область на фиксированные spatial cells,
+выполняет не более двух OSM-запросов одновременно, разносит старты запросов
+минимум на 750 мс, дедуплицирует одинаковые
+inflight cells и атомарно пишет нормализованный cell snapshot в
+`${MAP_CACHE_DIR}/reference-features`. Warm viewport читается из этого
+persistent cache. `name:ru` имеет приоритет перед общим `name`. Неудачный
+upstream не повреждает уже сохранённые cells; `complete=false` сообщает
+вызывающей стороне о частичном результате. `/healthz` возвращает только
+безопасный код последней ошибки, её время, counters и глубину очереди — без
+upstream endpoint или payload.
+
+Поиск вне уже загруженного viewport вызывается только явным Enter пользователя.
+Gateway сначала ищет в seed и persistent search index, затем при miss выполняет
+точный OSM name lookup. Upstream selector использует глобально индексированные
+`name`/`name:ru`, а найденные элементы повторно проходят fail-closed проверку
+`railway=station|halt`. Это не autocomplete и не глобальный regex scan.
+Нормализованный результат атомарно пополняет persistent search index; после
+перелёта обычный bbox-контур загружает полную spatial cell. Одинаковые запросы
+дедуплицируются и кэшируются, а `/healthz` отдельно показывает безопасные
+search counters.
+
+Граница seed округляется наружу до границ этих spatial cells. Поэтому viewport
+внутри московского покрытия всегда отвечает синхронно из packaged snapshot и
+не ожидает OSM только из-за того, что содержащая его ячейка выходит за крайнюю
+координату одной из seed-точек.
+
 Внутренний route `GET|HEAD /internal/zone-sources/v1/profiles/moscow-pmd-slow-zones/current` доступен сервисам в private `engine` network и намеренно не публикуется через Caddy. На старте Gateway проверяет manifest, SHA-256 обоих исходных JSON, геометрию, замкнутость колец, уникальность identity, расписание и его связи с зонами; повреждённый или неполный generation останавливает запуск. Сейчас profile упакован в image как immutable MMap snapshot. Для будущего Дептранс API меняется producer профиля (`depttrans-api-snapshot-v1`), но endpoint, stable source IDs и `nodedc.zone-source-generation/v2` остаются прежними.
 
 Внутренний admin route `GET|PUT /api/map/admin/cesium-ion` не является Browser API: он доступен только из Foundry по HMAC. Ключ подписи создаётся и хранится root-owned deploy runner в `/volume1/docker/nodedc-platform/secrets/map-gateway-admin-secret`, а оба сервиса получают только read-only file mount. Он не является `.env`-значением, настройкой Foundry или Cesium credential. Перед записью `PUT` проверяет candidate token через Cesium asset endpoints `1` (terrain), `2` (imagery) и `96188` (3D Buildings). Не прошедшее проверку значение не заменяет рабочее. Успешный token записывается атомарно в `${MAP_CACHE_DIR}/secrets/cesium-ion-token` с mode `0600`; ответ содержит только факт конфигурации, safe verification state и audit metadata — никогда само значение.
@@ -90,6 +130,8 @@ MAP_GATEWAY_LEGACY_CACHE_HOSTS=ecn.t0.tiles.virtualearth.net,ecn.t1.tiles.virtua
 MAP_GATEWAY_OFFLINE_PROVIDER_ALLOWLIST=
 MAP_CACHE_DIR=/var/lib/nodedc-map-cache
 MAP_CACHE_MODE=readwrite
+MAP_REFERENCE_STATION_FETCH_ENABLED=true
+MAP_REFERENCE_STATION_CELL_DEGREES=0.5
 ```
 # Cache topology