docs: regenerate the legacy-services dependency graph after the maps fold

migration-graph.md

@@ -1,13 +1,18 @@
 # Legacy `src/services/` dependency graph
 
 Generated from the actual imports in `server/src` on **2026-07-29** (after the
-tripService migration + its quirk-fix pass — completing step 2 of the
-dependency-honest order below: the 1121-line hub folded into the DI-native
-`TripsService`, its MCP surface moved to the decorator-driven
-`trips.mcp.ts`/`share.mcp.ts`, the plugin RPC host injects it, and the bridge
-cascade landed — `todo.bridge`, `share.bridge`, `collab.bridge` and
-`vacay.bridge` deleted with their last consumers, the days/budget bridges
-pruned to their surviving exports. Earlier context: the budgetService
+mapsService migration — step 4's head in the dependency-honest order below: the
+1429-line geo core folded into the DI-native `MapsService`, its pure helpers
+into `nest/maps/maps.helpers.ts`, the 3 geo MCP tools onto the decorator
+registry (`maps.mcp.ts` — the weather/airport tools stay in the legacy
+`mapsWeather.ts` registrar), BookingImportService injects it, and a 3-export
+`maps.bridge.ts` serves `placeEnrichment` + the places registrar; earlier the
+same day, the tripService migration + its quirk-fix pass completed step 2: the
+1121-line hub folded into the DI-native `TripsService`, its MCP surface moved
+to the decorator-driven `trips.mcp.ts`/`share.mcp.ts`, the plugin RPC host
+injects it, and the bridge cascade landed — `todo.bridge`, `share.bridge`,
+`collab.bridge` and `vacay.bridge` deleted with their last consumers, the
+days/budget bridges pruned to their surviving exports. Earlier context: the budgetService
 migration (step 1) and the
 Phase 0 quick wins: `getAppUrl`/`getMcpSafeUrl` → `src/app-config` deleted the
 fake `→ notifications` edges for the identity/MCP stack and freed mapsService;
@@ -58,10 +63,19 @@ How to read it:
   and `vacay.bridge` with their last consumers; a 3-export `trips.bridge.ts` serves the
   legacy prompts registrar's getTripSummary and `budget.mcp.ts`'s getTripOwner/listMembers
   seam — injecting there would need a forwardRef'd TripsModule↔BudgetModule cycle;
-  `days.bridge.ts` shrank to getDay/listDays for the transit/transports registrars).
+  `days.bridge.ts` shrank to getDay/listDays for the transit/transports registrars),
+  maps (the 1429-line geo core folded into `MapsService`; pure helpers —
+  `buildUserAgent`, the opening-hours parsers, POI categories, Overpass endpoint
+  resolution — are plain exports in `nest/maps/maps.helpers.ts` (transitService
+  imports its UA from there — helper import, non-blocking); the module-scoped POI
+  cache / photo-fetch semaphore / frozen Overpass mirrors stay module-scoped on
+  purpose so the bridge instance and the DI singleton share them; a 3-export
+  `maps.bridge.ts` (getMapsKey/searchPlaces/getPlacePhoto) serves the legacy
+  `placeEnrichment` helper and `mcp/tools/places.ts` until the place domain
+  migrates).
 - **Domain migration targets** (the wave material): adminService, airportService, atlasService,
   authService, backupService, collectionsService,
-  journeyService, journeyShareService, mapsService, notificationService, oauthService,
+  journeyService, journeyShareService, notificationService, oauthService,
   oidcService, passkeyService, placeService, transitService,
   transitItineraryService, weatherService, wikiService.
 - **Cross-cutting Wave-2 targets:** permissions and auditLog are done (2026-07) — see the
@@ -91,13 +105,12 @@ flowchart TD
     airport["airportService (boot special case)"]:::ready
     wiki[wikiService]:::ready
     collections[collectionsService]:::ready
-    maps[mapsService]:::ready
+    place["placeService (maps edge → maps.bridge since the fold)"]:::ready
+    transit["transitService (UA → maps.helpers since the fold)"]:::ready
     oauth[oauthService]:::ready
   end
 
-  place[placeService]:::blocked
   notifSvc[notificationService]:::blocked
-  transit[transitService]:::blocked
   transitItin[transitItineraryService]:::blocked
   admin[adminService]:::blocked
   auth[authService]:::blocked
@@ -111,8 +124,6 @@ flowchart TD
   cleanup[userCleanupService]:::infra
 
   collections -.-> notifSvc
-  place --> maps
-  transit --> maps
   transitItin --> transit
   notifSvc --> notifCluster
   admin --> auth & notifSvc & cleanup
@@ -124,10 +135,13 @@ flowchart TD
   memories --> notifSvc & admin
 ```
 
-(`placeService → mapsService` is via the `placeEnrichment` helper; `notificationService
-→ notifications cluster` is a hard import — the former `mapsService/transitService/webauthnConfig/
+(The former `placeService → mapsService` edge (via the `placeEnrichment` helper) is a
+`maps.bridge` repoint since the 2026-07 maps fold, and `transitService`'s UA import is
+the pure `maps.helpers` — helpers never block — so both sit on the frontier now;
+`notificationService → notifications cluster` is a hard import — the former
+`mapsService/transitService/webauthnConfig/
 oauthService → notifications` edges were only `getAppUrl`/`getMcpSafeUrl` and died with the
-Phase 0 move to `src/app-config`, putting mapsService on the frontier. `memories/` ↔ admin/notificationService edges make the
+Phase 0 move to `src/app-config`, which had put mapsService on the frontier. `memories/` ↔ admin/notificationService edges make the
 journey/memories corner tangle with the admin corner. The former
 `auth/collections/backup → permissions` and `notifSvc/oauth → auditLog` edges are gone since the
 2026-07 Wave-2 pair: the permissions consumers repointed to `nest/permissions/permissions.bridge`,
@@ -147,7 +161,7 @@ already-migrated collab/packing/trips/reservations/vacay services.)
 |---|---|---|---|---|
 | `adminService` | apiKeyCrypto, authService, avatarUrl, llmConfig, memories/helpersService, notificationService, passwordPolicy, userCleanupService (+ `permissions.bridge`) | (none) | nest/admin/admin.service.ts, nest/packing/packing.mcp.ts (`deletePackingTemplate`, the `admin-2` residual) | scheduler.ts |
 | `airportService` | (none) | (none) | nest/airports/airports.service.ts, nest/booking-import/kitinerary-mapper.ts | db/database.ts, mcp/tools/mapsWeather.ts, mcp/tools/transports.ts |
-| `apiKeyCrypto` | (none) | adminService, airtrail/airtrailService, authService, llmConfig, mapsService, memories/helpersService, memories/immichService, memories/photoResolverService, memories/synologyService, memories/unifiedService, notifications, oidcService, unsplashService | nest/plugins/plugin-oauth.service.ts, nest/plugins/plugin-runtime.service.ts, nest/plugins/plugins.service.ts, nest/settings/settings.service.ts | db/migrations.ts |
+| `apiKeyCrypto` | (none) | adminService, airtrail/airtrailService, authService, llmConfig, memories/helpersService, memories/immichService, memories/photoResolverService, memories/synologyService, memories/unifiedService, notifications, oidcService, unsplashService | nest/maps/maps.service.ts, nest/plugins/plugin-oauth.service.ts, nest/plugins/plugin-runtime.service.ts, nest/plugins/plugins.service.ts, nest/settings/settings.service.ts | db/migrations.ts |
 | `atlasService` | (none) | authService | nest/atlas/atlas.service.ts, nest/plugins/host/plugin-host-deps.factory.ts | mcp/resources.ts, mcp/tools/atlas.ts |
 | `authService` | apiKeyCrypto, atlasService, avatarUrl, demo, distanceService, ephemeralTokens, mfaCrypto, passwordPolicy, tripMembership, userCleanupService, webauthnConfig (+ `permissions.bridge`) | adminService, oidcService, passkeyService | nest/assignments/assignments.mcp.ts, nest/auth/auth.service.ts, nest/auth/passkey-enabled.guard.ts, nest/budget/budget.mcp.ts, nest/collab/collab.mcp.ts, nest/days/day-notes.mcp.ts, nest/days/days.mcp.ts, nest/oidc/oidc.service.ts, nest/packing/packing.mcp.ts, nest/reservations/reservations.mcp.ts, nest/share/share.mcp.ts, nest/tags/tags.mcp.ts, nest/todo/todo.mcp.ts, nest/trips/trips.mcp.ts, nest/vacay/vacay.mcp.ts | mcp/index.ts, mcp/tools/atlas.ts, mcp/tools/collections.ts, mcp/tools/journey.ts, mcp/tools/notifications.ts, mcp/tools/places.ts, mcp/tools/transit.ts, mcp/tools/transports.ts |
 | `avatarUrl` | (none) | adminService, authService, inAppNotifications, journeyService | nest/budget/budget.service.ts, nest/collab/collab.service.ts, nest/files/files.service.ts, nest/packing/packing.service.ts, nest/reservations/reservations.service.ts, nest/trips/trips.service.ts | (none) |
@@ -164,7 +178,6 @@ already-migrated collab/packing/trips/reservations/vacay services.)
 | `journeyShareService` | journeyService | (none) | nest/journey/journey.service.ts | mcp/tools/journey.ts |
 | `kmlImport` | (none) | placeService | (none) | (none) |
 | `llmConfig` | apiKeyCrypto | adminService | nest/llm-parse/llm-client.factory.ts, nest/llm-parse/llm-config.resolver.ts | (none) |
-| `mapsService` | apiKeyCrypto, placePhotoCache | placeEnrichment, transitService | nest/booking-import/booking-import.service.ts, nest/maps/maps.service.ts | mcp/tools/mapsWeather.ts, mcp/tools/places.ts |
 | `mfaCrypto` | (none) | authService | (none) | (none) |
 | `notificationPreferencesService` | notifications, notifications/builtins, notifications/channelRegistry | inAppNotifications, notificationService, notifications, notifications/channelRegistry | nest/admin/admin.service.ts, nest/notifications/notifications.service.ts, nest/plugins/install/manifest.ts | (none) |
 | `notifications` | apiKeyCrypto, notificationPreferencesService (+ `audit-log.logger`) | notificationPreferencesService, notificationService, notifications/builtins | nest/auth/auth.service.ts, nest/notifications/notifications.service.ts | (none) |
@@ -173,14 +186,14 @@ already-migrated collab/packing/trips/reservations/vacay services.)
 | `oidcService` | apiKeyCrypto, authService, tripMembership | (none) | nest/oidc/oidc.service.ts | (none) |
 | `passkeyService` | authService, webauthnConfig | (none) | nest/admin/admin.service.ts, nest/auth/passkey.controller.ts | (none) |
 | `passwordPolicy` | (none) | adminService, authService | (none) | (none) |
-| `placeEnrichment` | mapsService | placeService | (none) | (none) |
+| `placeEnrichment` | (none — `maps.bridge` since the maps fold) | placeService | (none) | (none) |
 | `placeImage` | (none) | collectionsService, placeService | nest/collections/collections.controller.ts, nest/common/place-image-upload.ts, nest/places/places.controller.ts | (none) |
-| `placePhotoCache` | (none) | mapsService, placeService | nest/maps/maps.service.ts, nest/share/share.service.ts | scheduler.ts |
+| `placePhotoCache` | (none) | placeService | nest/maps/maps.service.ts, nest/share/share.service.ts | scheduler.ts |
 | `placeService` | conflictResult, kmlImport, placeEnrichment, placeImage, placePhotoCache, queryHelpers, unsplashService | (none) | nest/booking-import/booking-import.service.ts, nest/days/days.mcp.ts, nest/places/places.service.ts, nest/plugins/host/plugin-host-deps.factory.ts, nest/trips/trips.service.ts | mcp/resources.ts, mcp/tools/places.ts |
 | `queryHelpers` | (none) | placeService | nest/assignments/assignments.service.ts, nest/days/days.service.ts, nest/share/share.service.ts | (none) |
 | `timezoneService` | (none) | airtrail/airtrailMapper, transitItineraryService | nest/trips/trips.service.ts | (none) |
 | `transitItineraryService` | distanceService, timezoneService, transitService (+ type-only `reservations.bridge`) | (none) | (none) | mcp/tools/transit.ts |
-| `transitService` | mapsService | transitItineraryService | nest/transit/transit.controller.ts | mcp/tools/transit.ts |
+| `transitService` | (none — `buildUserAgent` is the pure `nest/maps/maps.helpers`) | transitItineraryService | nest/transit/transit.controller.ts | mcp/tools/transit.ts |
 | `tripAccess` | (none) | (none) | nest/booking-import/booking-import.service.ts, nest/budget/budget.service.ts, nest/collab/collab.service.ts, nest/days/day-notes.service.ts, nest/integrations/airtrail-import.controller.ts, nest/packing/packing.service.ts, nest/reservations/reservations.service.ts, nest/todo/todo.service.ts | (none) |
 | `tripMembership` | (none) | authService, oidcService | nest/plugins/host/plugin-host-deps.factory.ts, nest/trip-invite/trip-invite.service.ts | (none) |
 | `unsplashService` | apiKeyCrypto | placeService | nest/trips/trips.controller.ts, nest/trips/trips.service.ts | (none) |
@@ -215,7 +228,8 @@ already-migrated collab/packing/trips/reservations/vacay services.)
 
 | Candidate | Why now / why not | Bridge tax (legacy dependents + out-of-container) |
 |---|---|---|
-| **mapsService** ← pick | Frontier-ready since the Phase 0 `getAppUrl` → app-config move; heads the step-4 chain that unblocks the placeService Wave-4 remainder (tripService — the hub — landed 2026-07) | `placeEnrichment`, `transitService`; `mcp/tools/mapsWeather.ts`, `mcp/tools/places.ts` |
+| **transitService** ← pick | Frontier-ready since the maps fold (its only maps import is the pure `maps.helpers` UA); next in the step-4 chain, unblocks transitItineraryService | `transitItineraryService`; `mcp/tools/transit.ts` |
+| **placeService** | Frontier-ready since the maps fold (the `placeEnrichment` edge is a `maps.bridge` repoint); its legacy imports are all helpers — the fold can absorb `placeEnrichment` (exchange-rates precedent) and retire `maps.bridge` with it | `mcp/resources.ts`, `mcp/tools/places.ts` |
 | **collectionsService** | Frontier-ready — legacy deps are the placeImage helper + `permissions.bridge`, plus a call-time lazy `import()` of notificationService that a migrated service keeps (collab precedent) | `mcp/tools/collections.ts` |
 | **atlasService** | Zero deps, but its legacy dependent is `authService` (Wave-5) → bridge lives long | `authService`; `mcp/tools/atlas.ts`, `mcp/resources.ts` |
 | **oauthService** | Dependency-free since the Phase 0 addons extraction (adminService edge was only `isAddonEnabled` → `addons.bridge`) — but the coherence order keeps it after admin so the `mcp/oauthProvider.ts` merge (`mcp-2`) lands with it | `mcp/index.ts`, `mcp/oauthProvider.ts` |
@@ -223,12 +237,10 @@ already-migrated collab/packing/trips/reservations/vacay services.)
 
 **Blocked, and by what (shortest unblock path):**
 
-- `placeService` ← `mapsService` (via placeEnrichment) — mapsService itself is
-  frontier-ready since the Phase 0 app-url move deleted its notifications edge.
 - `notificationService` ← notifications cluster (its auditLog edge is now the plain
   `audit-log.logger` import — gone as a blocker since the 2026-07 Wave-2 pair).
-- `transitItineraryService` ← `transitService` (← mapsService) — its reservation edge is now
-  the `reservations.bridge` repoint (type-only).
+- `transitItineraryService` ← `transitService` (frontier-ready since the maps fold) —
+  its reservation edge is now the `reservations.bridge` repoint (type-only).
 - `adminService`/`authService` corner: `authService` ← `atlasService`
   (its permissions edge is now the `permissions.bridge` repoint); `adminService` ←
   `authService` + `notificationService`. `oauthService` is dependency-free since the
@@ -255,7 +267,10 @@ Wave-2 `permissions` + `auditLog` pair were the first frontier picks — all don
    surfaces moved to the decorator registry, the plugin host injects it, and the
    todo/share/collab/vacay bridges died with their last consumers)
 3. notifications cluster → `notificationService`
-4. `mapsService` → `transitService` → `placeService` → `transitItineraryService`
+4. `mapsService` (done 2026-07 — the geo core folded into `MapsService`, geo MCP
+   tools onto the decorator registry, BookingImportService injects it, and the
+   3-export `maps.bridge` covers placeEnrichment + the places registrar)
+   → `transitService` → `placeService` → `transitItineraryService`
 5. `atlasService` → `authService` (+ oidc/passkey) → `adminService` → `oauthService`
 6. `memories/` cluster → `journeyService` → `journeyShareService`; `collectionsService`
    (frontier-ready since the permissions fold — can also go any time)
@@ -288,3 +303,12 @@ Wave-2 `permissions` + `auditLog` pair were the first frontier picks — all don
   and `budget.mcp.ts`'s owner/member seam. `verifyTripAccess`'s `tripAccess` re-export died
   with the legacy file, leaving `services/tripAccess` with zero legacy importers — it is
   now purely Nest-consumed (Wave-2 "delete, don't migrate" is down to those repoints).
+- (2026-07-29 regeneration, post maps fold) The predicted bridge tax over-counted:
+  `transitService` needed no bridge at all — its only import was the pure `buildUserAgent`,
+  which now lives in `maps.helpers.ts` as a plain export (helpers never block), and after
+  the geo tools moved onto the decorator registry `mcp/tools/mapsWeather.ts` no longer
+  consumes the maps domain (the registrar file survives for its weather + airport tools;
+  its `searchPlaces` import turned out to be dead code and died with the prune). The
+  bridge is 3 exports for `placeEnrichment` + `mcp/tools/places.ts`, both of which the
+  placeService migration will absorb. Step 4's remaining chain — transitService →
+  placeService — is now entirely frontier-ready.