TREK/server/docs/nest-migration-history.md

# NestJS migration: history (historical)

**Historisch / historical record.** This is the module guide as it stood while
the Express API was being strangled into Nest, kept for the reasoning behind
decisions that still shape the code (why a registry is module state, why a
bridge was folded the way it was, how each legacy service moved). It is not a
guide for new code: `src/services/`, every `*.bridge.ts`, `DatabaseService`
and the routing gate it describes are gone. The current blueprint is
`src/nest/README.md`; the rules are in `server/CLAUDE.md`.

Paths below are relative to `server/src/nest/` unless they say otherwise, and
many name files that no longer exist.

---


This folder holds the co-hosted NestJS app that incrementally strangles the legacy
Express API (see the "Brownfield Rewrite" board). Until a prefix is migrated, the
top-level dispatcher in `src/index.ts` routes it to the legacy app; migrated
prefixes go to Nest. **Weather (`weather/`) is the reference implementation** — copy
its shape when migrating a new domain.

## Module layout (per domain)

```
shared/src/<domain>/<domain>.schema.ts(.spec.ts)   # Zod contract — single source of truth
server/src/nest/<domain>/<domain>.service.ts        # business logic (ported 1:1 from the Express service)
server/src/nest/<domain>/<domain>.controller.ts     # same routes/verbs/params/status codes as Express
server/src/nest/<domain>/<domain>.module.ts         # registered in app.module.ts
```

Register the module in `app.module.ts` and it is live. There is no routing gate to
flip any more: **every request goes through Nest**. The `strangler.ts` matcher and
its `DEFAULT_NEST_PREFIXES` / `NEST_PREFIXES` escape hatch are gone — Express only
remains as the platform underneath `@nestjs/platform-express`.

## Migrated so far

- **Phase 1 (leaf):** weather, airports, config (public), system-notices, maps,
  categories, tags, notifications, atlas.
- **Phase 2 (trip sub-domains):** vacay (addon), packing, todo.
- **DI-native services (legacy `src/services/*` deleted):** tags, categories,
  todo, packing, day-notes, trip-invite, assignments, share, settings, files,
  collab, vacay, reservations, day, permissions, audit, budget, trip, maps,
  transit, place, transit-itinerary, collections, atlas, auth, oidc, passkey,
  notifications, admin, webauthn-config, user-cleanup, oauth, wiki, mailer,
  notification transports, notification preferences, memories (immich, synology,
  unified, photo-resolver, thumbnails, trek-photo cache), journey, journeyShare
  — see the migration recipe below.
- **Foundation (BE-Phase 1, complete):** the eight stateless helpers moved to
  `common/`; every trip-access check routes through a repository
  (`services/tripAccess.ts` and the dead `middleware/tripAccess.ts` are gone;
  `DatabaseService`, the facade BE-Phase 1 originally routed this through, was
  itself retired by the later ORM migration — see the root/server `CLAUDE.md`);
  `queryHelpers` and `tripMembership` are providers; every cron is a domain
  `*.job.ts` provider on `scheduling/CronRegistrarService` (`src/scheduler.ts`
  is deleted).
- **Plugin RPC surface (BE-7, complete):** all 113 wire methods are
  `@PluginMethod` / `@PluginOpenMethod` handlers on `@PluginController()` providers
  in their own domains (`<domain>/<domain>.rpc.ts`; the three that belong to no
  domain live in `plugins/host/rpc/`), and all 18 host-to-plugin hook contracts are
  `@PluginHook` declarations on `PluginHooks`. `PluginRpcHost` no longer holds a
  handler: it builds the granted subset of the dispatch map from the registry,
  dispatches, audits and maps errors. `PluginHostDepsFactory` — the 26-argument
  wiring sheet named throughout the log below — is now
  `PluginRpcHostFactory` and injects two things. See
  `src/nest-rpc/rpc-kit/README.md` (the kit, `rpc-params`, `rpc-errors` and
  `PluginGuards` moved to `src/nest-rpc/`, a kernel layer beside `src/nest-mcp/`,
  so a domain's `*.rpc.ts` no longer depends on the plugins domain).
- **Plugin module split (complete):** `PluginsModule` was 21 controllers, 24 domain
  imports and 10 providers in one class, so `AdminModule` importing it for one
  cascade-disable call inherited the whole graph. It is now `PluginsRuntimeModule`
  (supervisor, capability router, hook contracts — the half with the domain imports),
  `PluginContributionsModule` (the 14 read-only hook controllers, in
  `plugins/contributions/`), `PluginOAuthModule` (`plugins/oauth/`) and a composition
  root holding the install and delivery controllers. `AdminModule` imports the runtime
  alone. Note the invariant the boot-time coverage check now depends on: importing
  `PluginsRuntimeModule` must pull in EVERY domain that owns part of the wire surface,
  which is why `WeatherModule` sits in its import list.
- **Guards (BE-Phase 2, done):** the JWT verify lives in `auth/`, and
  `middleware/auth.ts`, `validate.ts`, `idempotency.ts` and `mfaPolicy.ts` are
  deleted; the three addon guards are one `AddonGuard` + `@RequireAddon`; the
  demo-mode block is one condition. `TripAccessGuard` and `TripOwnerGuard` cover
  the trip-scoped and owner-only routes.

  **Authentication is default-deny.** `GlobalAuthGuard` is an `APP_GUARD`: a route
  is authenticated unless it carries `@Public(reason)` or `@OptionalAuth(reason)`,
  or declares its own `@UseGuards` chain. A controller that declares a chain keeps
  it — global guards run before route guards, so an addon-gated controller has to
  stay in charge of answering 404 before anything answers 401, or the response
  leaks which addons are installed. The global guard still *resolves* the user in
  that case, without refusing, because `MfaPolicyGuard` runs behind it and reads
  `req.user`.

  Adding a `@Public()` route is not a local decision: `validateRouteGuards` runs in
  `buildApp()` and refuses to boot unless the route is also in
  `PUBLIC_ROUTE_ALLOW_LIST` in `common/validate-route-guards.ts`. That list is the
  whole anonymous surface of the server, in one reviewable place. Stale entries
  fail too.

**`src/services/` is gone.** It was the legacy layer this whole migration existed
to empty, and the last of it — `airtrail/`, 1305 lines of plain functions over the
better-sqlite3 singleton — folded into `integrations/`. An ESLint
`no-restricted-imports` rule now refuses any import of a `services/` path, because
the directory disappearing is not what keeps it gone: it grew one reasonable file
at a time. Backup made the same trip earlier: `services/backupService.ts` is
`nest/backup/backup.impl.ts`, imported only by its own domain. It is still a
module of free functions, but it no longer closes or reopens the core DB handle
itself: `BackupService` hands it the injected database backup port
(`DATABASE_BACKUP`, `SqliteDatabaseBackup`), which snapshots and swaps the file
through `DatabaseLifecycle`, the provider that owns the connection. The demo
reset goes through the same port. Another engine plugs in there, with a logical
dump in place of `VACUUM INTO` and the file swap.

Note that the trip-access and `canEdit` methods on the domain services are **not**
dead weight waiting for a guard: their callers are overwhelmingly the `*.mcp.ts`
tools, which never pass through an HTTP guard. In the five domains piloted for
`TripAccessGuard`, 40 of the 46 callers are MCP; only 6 sit in controllers.

## Cross-cutting Foundation pieces

- `common/idempotency.interceptor.ts` — global `APP_INTERCEPTOR` replaying the
  client's `X-Idempotency-Key` on mutations. It replaced the `applyIdempotency`
  middleware, which is deleted; this is the only implementation.
- `common/` — the stateless helpers (`avatarUrl`, `conflictResult`, `demo`,
  `passwordPolicy`, `timezoneService`, `cookie`, `rowShape`, `geo`, `crypto/`).
  Free functions, not providers: the numbered migrations in `db/migrations/`
  (e.g. the plaintext-secret encryption steps) and `demo/demo-seed.ts` import
  them from outside the container and could not inject one. `geo.ts` holds the two haversines; there
  were three implementations of the metre variant, differing by one clamp, and
  the clamped form is the one kept — `asin` of a value a hair over 1 is NaN, and
  a NaN distance silently fails every comparison it feeds instead of throwing.
  `maps.helpers.ts` re-exports `haversineMetres` rather than defining it, because
  callers and a test import it from there.
- `auth/jwt-verify.ts` — `extractToken` + `verifyJwtAndLoadUser`, the canonical
  session check behind the four guards, the MCP bearer path and the file-download
  query token. Free functions for the same reason.
  `JWT_SECRET` stays a live binding from `src/config` and must NOT move to
  `app-config`: the admin panel rotates it at runtime, and a `registerAs` token
  would freeze the boot value.
- `query-helpers/` — the batch loaders that keep list endpoints off N+1 queries.
- `trip-membership/` — `joinTripAsMember`. Its own module rather than folded into
  auth or trip-invite, because both call it (as do oidc and the plugin host) and
  either home would put `AuthModule` and `TripInviteModule` in a cycle.
- `addons/addon.guard.ts` + `@RequireAddon(addonId, label)` — the addon route
  gate. Declare `AddonGuard` **before** `JwtAuthGuard`: a disabled addon has to
  answer 404 to anonymous callers, so the addon check must beat the 401.
- `common/demo-write.ts` — `isDemoWriteBlocked`, the demo-mode upload block. A
  function and not a guard on purpose; see the gotcha below.
- `storage/` — the storage abstraction and its admin surface. `storage.types.ts`
  defines the driver contract (opaque keys, no rename/append — S3 constraints
  baked in) plus the `ServedCategory` seam: `STORAGE_CATEGORIES` (shared, 8,
  configurable) + the legacy `photos` directory that is served and backed up
  but not configurable. `drivers/` (local, s3, mirror) all pass one contract
  suite (`tests/unit/nest/storage/storage-driver.contract.ts`).
  `storage-registry.service.ts` merges built-ins ← env (`place-photos-local`)
  ← `app_settings` rows, validates semantics (references, no mirror nesting),
  falls back to last-good/defaults at boot but NEVER on admin writes
  (`preview()` runs the real build first), seeds once from
  `data/storage-config.json`, and hot-swaps on `reload()`.
  `storage.service.ts` is the facade every byte-path uses.
  `storage-admin.{controller,service}.ts` (+ `storage-secrets.ts`,
  `storage-probe.ts`) carry `api/admin/storage`: masked GET of the effective
  world, full-document PUT (unmask → preview → encrypt → one transaction →
  reload → audit), and per-target test probes with ephemeral drivers. Secrets
  live `enc:v1:`-encrypted inside the `storage.backends` JSON (the implicit
  key covers installs without an explicit `ENCRYPTION_KEY`). The client
  presents mirrors as replicas-on-primary; the wire keeps explicit mirror
  backends. `storage-jobs.service.ts` runs backfill and category-migration
  jobs (one at a time, TTL'd statuses).
- `memories/photo-provider.ts` + `providers/` — the PhotoProvider seam (#584).
  Dispatch to a photo backend was a `switch (photo.provider)` in three places
  (`photo-resolver.service.ts` twice, `journey-public.controller.ts` once, where
  anything that was not Immich got handed to Synology). It is
  `PhotoProviderRegistry.get(id)` now, over adapters registered under the
  `PHOTO_PROVIDERS` multi-provider token in `memories.module.ts` — adding a
  backend is one registration.
  - Adapters, not `implements` on the services: ImmichService and
    SynologyService are also the album/browse surfaces, with their own argument
    orders and return shapes. The mapping lives in the adapter.
  - `PhotoAssetRef` exists because the two services took the same three values
    in different orders — `(userId, assetId, ownerId)` against
    `(userId, targetUserId, photoId)`. A transposition compiled cleanly and
    served another user's photo.
  - `local` is deliberately NOT a provider. It is storage on this disk, it has
    no row in `photo_providers`, and its "asset info" comes from the DB row
    rather than from a backend. Both dispatch sites branch on it explicitly.
  - The rename `memories/` → `media/` was considered and dropped: it is 275
    files of import churn, and `scripts/coverage-thresholds.mjs` buckets on one
    path segment, so merging `photos/` into it would collapse two ratchet
    entries into one and drop the stricter of the two.
- `realtime/` — the /ws transport, as a Nest gateway.
  - `realtime.gateway.ts` owns the connection lifecycle and the handshake, with
    `TripsRepository`/`UsersRepository`/`AppSettingsRepository` and
    `EphemeralTokenService` injected instead of imported (Plan 4 converted it
    off the deleted `DatabaseService`). It replaced `setupWebSocket(server)`,
    which index.ts kicked off with a dynamic import after listen().
  - `ws-state.ts` holds the socket registry, and that is **module state on
    purpose**. The no-Nest test harnesses build `new RealtimeService()`
    outside the container and 115 test files `vi.mock` the `src/websocket`
    stub; rooms on a provider instance would leave their broadcasts going to
    an empty map, with no error and no log. Same reasoning as the geo
    throttle cursor.
  - `trek-ws.adapter.ts` exists because the stock `WsAdapter` dispatches on
    `{ event, data }` and every deployed client sends `{ type, tripId }`. It
    also builds the ws server itself rather than delegating: the base's port-0
    branch uses `noServer: true` and performs the upgrade from its own registry,
    which never consults `verifyClient`, so delegating would silently drop the
    origin check. The per-socket `error` listener is attached FIRST, because an
    unhandled one kills the process (#1576), and the flood guard counts every
    inbound frame before parsing, because malformed frames are the ones worth
    limiting.
  - The socket id stays a **monotonic integer**. The client echoes it as
    `X-Socket-Id` and `broadcast` excludes the originator with
    `Number(excludeSid)`; a uuid is `NaN`, `NaN === NaN` is false, and every
    client would receive its own writes back. It shows up as drag-and-drop that
    jumps, not as an error.
  - `RealtimeGatewayModule` is imported by AppModule alone. RealtimeModule is
    @Global, so a gateway there follows into every hand-assembled TestingModule,
    and Nest's SocketModule then loads an adapter none of them set: it reaches
    for `@nestjs/platform-socket.io` and calls `process.exit(1)` when it is
    absent.
  - `buildApp()` creates the http server and binds the adapter to it BEFORE
    `app.init()`, and callers take it from `getHttpServer()`. Nest binds gateways
    during init, so an adapter registered later binds nothing, and one given the
    app instead of the server binds to Nest's internal server, which this process
    never listens on. Either way the boot is green and no browser can connect.
  - `src/websocket.ts` survives as a re-export. 115 test files `vi.mock` that
    path to assert on broadcasts; repointing them all would be a large diff that
    proves nothing.

- `geo/` — the ONE Nominatim client (#576). There used to be two: atlas
  throttled to the published 1.1s and cached its answers, maps did neither, so
  five interactive routes fired straight at the service while the atlas loops
  politely waited and OSM saw a single instance ignoring its rate limit. Both
  domains now go through `nominatimFetch`.
  - The throttle cursor and the cache are **module state, not provider state**,
    for the permissions-cache reason: the no-Nest test harnesses build their
    collaborators with `new`, outside the container, and a second copy of the
    cursor is the very bug the fold removes. `GeoModule` is registered straight in AppModule and neither
    `MapsModule` nor `AtlasModule` imports it — an import would claim an
    injection edge that does not exist.
  - `GeocodingService` owns exactly one thing: the cache-cleanup timer's
    lifecycle, via `OnModuleInit`/`OnModuleDestroy`. Atlas used to start that
    interval as an import-time side effect, documented as a parity exception. It
    is not one any more.
  - Two lanes over one cursor. Interactive calls (`/api/maps/search`,
    `/autocomplete`, `/details`, `/reverse`, `/resolve-url`) take the next slot;
    background calls (the atlas enrichment loops, which walk every uncached
    place) yield to anything queued on a request path.
  - The cache key carries the **query shape**, not coordinates alone. Atlas asks
    at zoom 3 and zoom 8, maps at zoom 18; a coordinate-only key answered a
    street lookup with a country.
  - `AbortSignal.timeout` is built **after** the throttle wait. Built up front,
    the 1.1s spent queueing would eat nearly half of the identity lookup's 2.5s
    budget before the socket opens.
  - `setGeoThrottleInterval(ms)` is a test seam, and `tests/setup.ts` zeroes it.
    Nineteen maps cases drive these paths back to back with real timers; at the
    real interval they slept nineteen seconds and covered nothing extra. A
    function rather than a `NODE_ENV` check, for the reason app-config exists.

### Reaching the container from outside it

Two shapes, and the choice is settled:

**Prefer handing the dependency in.** `bootstrap.ts` hands the `/mcp` handler
its registry via `setMcpRegistry(app.get(...))` after `buildApp()` — the
outside code names the capability it needs, structurally, never the provider
class, so no module cycle can close through it. (The retired `src/scheduler.ts`
was the fullest example — a structural `SchedulerDeps` interface filled by
`index.ts` — until every cron became an in-container `*.job.ts` provider and
the seam disappeared entirely, which is the real endgame for this shape.)

**`<domain>.bridge.ts` is a retired shape** — zero bridge files remain since
the MCP/OAuth mount moved behind the container (2026-08-11). It served code
that ran before `app.init()` and so could not inject; its cost was real: a
bridge rebuilt its services with `new`, so adding one constructor parameter to
a service meant hand-editing every bridge that constructed it — five of them in
one PR, at the worst. If a pre-init consumer ever reappears, prefer the
`bootstrap.ts` pattern instead: resolve the container singleton with
`app.get(...)` before init (the `httpConfig.KEY` / discovery-metadata
precedent) rather than minting a second instance.

**Express middleware with DI has two honest mounts** (first used by the mount
migration): `consumer.apply(...).forRoutes('<concrete path>')` in a module's
`configure()` — an Express prefix mount, exactly the legacy `app.use('/path')`
semantics, which is how `OauthModule` mounts the MCP SDK's authorize/register
routers and `PlatformModule` the consent-COOP override — and, for middleware
that must see the ORIGINAL `req.url` (a wildcard `forRoutes()` is a pattern
mount that strips the matched prefix), a pathless `app.use` in `bootstrap.ts`
over a container-resolved factory provider (`MCP_METADATA_MIDDLEWARE`).
`nest/mcp-transport/` (the /mcp controller + service over injected services)
and `nest/mcp-shared/` (`McpToolGuardsService` for the `*.mcp.ts` classes) are
the module shapes that replaced the last bridges.

**A bridge imported from INSIDE the container hides an edge from the module
graph**, which is a different problem from serving a genuine outside consumer.
Nine `*.mcp.ts` files did that with `addons.bridge` for one boolean each, and
not by preference: a decorator's options object is built while the class is
being defined, so the `when:` closure had no `this` to reach an injected service
through. `src/nest-mcp/` hands the gate its declaring instance now, and
`addons/addon-gate.ts` turns that into `addonGate(ADDON_IDS.X)` over an injected
`AddonsService`. `reservations.mcp.ts` (assignments) and `atlas.mcp.ts` /
`journey.mcp.ts` (auth) went the same way.

No in-container bridge uses are left. The last four folded 2026-08-11, and
their folds are the playbook for any edge that reappears — plain injection
would have closed a real cycle in every case, so each cut the knot with a
finer-grained module instead:

- `budget.mcp.ts` / `packing.mcp.ts` / `costs.rpc.ts` → `trips.bridge`:
  everything that owns the hydrated trip reads (TripsService,
  TripReadModelService, TripMembersService) lives in modules importing the
  budget/packing domains, so the consumers moved instead — the id-level
  membership reads went to the dependency-free `TripMembershipModule`
  (`getOwnerId` / `listMemberUserIds` / `listAccessibleTripIds`) and the two
  cross-domain prompts moved above the read model onto
  `trips/trip-prompts.mcp.ts`. `trips.bridge` (102 lines, ~25 hand-built
  services) is deleted.
- `places.mcp.ts` → `assignments.bridge`: the cycle `DaysModule →
  PlacesModule → AssignmentsModule → DaysModule` is real, but only
  AssignmentsMcp needs DaysService — the service itself does not, so it moved
  to a leaf `AssignmentsDomainModule` (the journey-domain split) that
  PlacesModule imports. `assignments.bridge` is deleted.
- `reservations.controller.ts` → `airtrail.bridge`: the pull genuinely needs
  ReservationsService, so `AirtrailModule` keeps it — but the write-back push
  only needs the hydrated reservation READ. That read became
  `ReservationsReadService` (leaf, the trek_photos pattern), the link
  lifecycle + push became `AirtrailLinkService` in `AirtrailCoreModule`, and
  the controller injects it. `airtrail.bridge` is deleted, and
  `notifications.instance.ts` — whose last consumer it was — died with it.

Two more were on this list and folded 2026-08-11:

- `auth/user-cleanup.service.ts` → `budget.bridge` died when `BudgetModule`
  dropped its `AuthModule` import (BudgetMcp's demo guard reads
  `RuntimeEnvService` + the users table via `isDemoUserId`, not
  `AuthService`), which let `AuthModule` import `BudgetModule` and
  `UserCleanupService` inject `BudgetService`. `budget.bridge` is deleted.
- `backup/backup.impl.ts` → `permissions.bridge`: the restore path is free
  functions, not a provider, so there is nothing for an injected service to
  hang off — but the thing it needs is the cache, not the service. The cache
  moved to `permissions/permissions-cache.ts` (the `oauth.pending-codes.ts`
  precedent) and `backup.impl` imports the plain `invalidatePermissionsCache`
  from there.

`files.bridge` used to be on the list and is gone, resolved 2026-08-10 exactly
as predicted: `MulterModule.registerAsync` over an `AllowedFileTypesService`
leaf, and `files.controller.ts` / `journey.controller.ts` build their multer
options from that. `systemNotices/conditions.ts` similarly stopped importing
`addons.bridge`: the enablement check is threaded in through
`ConditionContext.addonEnabled` by the DI-native `SystemNoticesService`.

`days`, `packing`, `photos` and `reservations` had no production consumer left
and are deleted. Each still built a service outside the container at module load
for nobody, and three domain docblocks were still sending readers to them. The
cases that exercised them kept their assertions and point at the service.
`journey.bridge` died 2026-08-11 with `src/mcp/resources.ts`, when the last
four legacy resources became `@Resource`/`@ResourceTemplate` methods on
`journey.mcp.ts`.

Five bridges remain, all pinned by the one pre-`app.init()` MCP/OAuth mount
(`addons`, `audit`, `auth`, `oauth`, `permissions` — shrunk to the exports that
seam consumes) and all dying together if that mount ever moves behind the
container. When one loses its last outside-container consumer, delete it in
the same change rather than leaving it as a courtesy: an unused bridge reads
as a supported entry point.

The nine fire-and-forget notification senders inject too. They were lazy
`import('../notifications/notifications.bridge').then(({ send }) => …)` calls
working around a cycle that no longer exists, and the laziness hid the edge
while handing each send a NotificationsService built outside the container.

That sweep needed a method, because `tests/` sits outside `tsconfig`'s `include`:
a missed constructor argument does not fail to compile, it arrives as
`undefined`. Adding `tests` to a throwaway `tsconfig` and diffing the errors
before and after named all **46** hand-wired `new` sites exactly; a grep would
have been a guess. Worth repeating for any change that widens a service
constructor — and worth knowing that such a config reports **288 pre-existing
errors** in the suites, almost all deliberate partial constructions in the
harnesses (`new AuthService(db, permissions, atlas)` where the class takes six).
That is why `tests/` is not in the build's `include`, and cleaning it up is its
own piece of work.

`notifications.instance.ts` held the out-of-container `NotificationsService`
for the cycle-dodge bridges and died 2026-08-11 with the last of them
(`airtrail.bridge`) — every production consumer injects the container
singleton now. The module-scoped channel registry it leaned on stays (the
no-Nest test harnesses still construct instances; CHOVR-015 pins the
sharing).
- `app-config/` — the `@nestjs/config` binding (`AppConfigModule`, global). Never
  read `process.env` in a module (ESLint enforces this): inject a boot-stable
  namespace via its `registerAs` token (`@Inject(storageConfig.KEY) … ConfigType<…>`)
  or read runtime-toggled values live through `RuntimeEnvService` / `readEnv()`
  from `src/app-config`. Every variable has exactly one owner, a token or
  `readEnv()`, and `config-ownership.test.ts` fails on a variable read through
  both. A provider that reads a data path takes `DataPathsService`
  (`AdminService`, `StorageRegistryService`, and through it the storage
  jobs); plain helper modules call `resolveDataPaths()` (see
  `src/app-config/README.md` for which and why). The classification and
  invariants live in `src/app-config/README.md`.

## Parity gotchas worth remembering

- A POST that answers with `res.json` in Express stays **200**; add `@HttpCode(200)`
  (Nest defaults POST to 201). Creates that Express sends as 201 need nothing.
- Static sub-routes that collide with a `:id` param (e.g. `/in-app/all` vs
  `/in-app/:id`, `/reorder` vs `/:id`) must be declared **before** the param route.
- Reproduce bespoke admin/error wording exactly — e.g. notifications' `test-smtp`
  returns `{ error: 'Admin only' }`, not the AdminGuard's `Admin access required`.
- Trip-scoped routes verify trip access (404) and the relevant permission (403)
  per handler and forward `X-Socket-Id` to the WebSocket broadcast.
- **Never gate a multipart upload with a guard.** Guards run before the parser,
  so throwing from one leaves the request body unread and Node resets the
  connection — the client sees `ECONNRESET`, not your 403. Check inside the
  handler, after the interceptor has drained the upload. `PROFILE-015` is the
  regression test.
- **`@Global()` only applies to modules that are in the graph.** An e2e
  `TestingModule` built around one domain module does not get `AppConfigModule`
  for free just because it is global: a provider injecting `RuntimeEnvService`
  fails to resolve and takes every suite importing that module down with it.
  Import it explicitly, the way `PermissionsModule` is handled.
- **A module-scoped registry that outside code writes into must stay a module,
  not a provider.** The notification channel registry is the live example:
  `PluginRuntimeService` pushes its channel getter in at `onModuleInit`, and
  `notifications.instance.ts` builds its own `NotificationsService` for the
  surviving cycle-dodge bridges. As a provider that instance would get a second,
  empty registry and every plugin channel would go quiet — with no error
  anywhere. `CHOVR-015` is the regression test. Same reasoning as
  `oauth/oauth.pending-codes.ts`.
- **Self-registration by side-effect import is a trap.** The built-in channels
  used to register because `notificationPreferencesService` happened to `import
  './notifications/builtins'`. Dropping that one line would have silenced email,
  webhook and ntfy without a failure. They are built from injected transports and
  registered in `NotificationsService`'s constructor now, so every path that can
  dispatch has them.
- **The coverage gate reads `src/nest/**` and nothing else.** Moving code in from
  `src/mcp/` or `src/services/` does not just relocate it — it starts being
  measured. PR #1844 landed `airports.mcp.ts` at 0% branches because
  `search_airports`/`get_airport` had never had a test in either world, and the
  aggregate fell to 79.86% with every suite green. Before pushing anything that
  moves files into this tree, run `npm run test:coverage`, not just `npm test`.
- A guard with a constructor dependency has to be a registered provider
  everywhere it is used. The three auth guards are dependency-free on purpose —
  38 directories apply them and 21 do not import `AuthModule`, so giving them a
  dependency is its own migration, not a side effect of another change.

## Parity is law

A migrated route must be **byte-identical** for the client: same URL, method,
query/body, HTTP status, `Set-Cookie`, and JSON body — including bespoke error
strings. Where the legacy route returns a hand-written error (e.g. weather's
`{ error: 'Latitude and longitude are required' }`), reproduce that exact body in
the controller rather than relying on the generic `ZodValidationPipe` envelope.

## TripAccessGuard and TripOwnerGuard, and where they do not fit

`permissions/trip-access.guard.ts` resolves `:tripId` once per request, answers 404
"Trip not found" for anything the user cannot reach (never 403 — that would confirm the
id exists), and hands the row to the handler through `@Trip()`. `@RequirePermission`
carries the same action string the domain services pass to `checkPermission`.

Two limits are worth knowing before rolling it onto another controller, because both
were found the expensive way:

- **A guard runs before the body pipe.** Any route whose DTO validation is expected to
  answer 400 *ahead of* the trip 404 cannot use it. `places` is exactly that case — its
  e2e suite documents the pipe-first ordering as a deliberate parity shift — so its
  create/update/import routes keep their in-handler `requireTrip`, and that is not an
  oversight. Its five body-free routes (list, get, unrate, image, delete) do carry
  the guard; the split runs along "does this handler take a DTO-typed body", not
  along the domain.
- **A guard also runs before interceptors.** On a multipart upload route, a 404 sent
  while the client is still streaming destroys the socket, so the caller sees
  ECONNRESET instead of the 404. The three upload routes (files, collab note files,
  places) keep their own check for that reason; their controllers apply the guard per
  handler instead of on the class.

`permissions/trip-owner.guard.ts` is the stricter sibling: `@RequireTripOwner(message)`
demands that the caller *owns* the trip, not merely that they may edit it. Handing a
trip over and creating or deleting guests are the two things a collaborator must never
do however generous the trip's permission settings are.

It deliberately does **not** inject `PermissionsService`. `checkPermission` returns true
for every admin, and the trip actions are admin-lowerable, so routing ownership through
it would quietly hand any admin the ability to transfer other people's trips. The check
is the literal one the routes did by hand: `trip.user_id === user.id`. The message
travels in the metadata because the two call sites answer with different strings and
both are asserted.

The services keep `verifyTripAccess`/`canEdit` regardless: most of their callers are
`*.mcp.ts` tools, which never pass through an HTTP guard.

## Coverage is gated per domain, as a ratchet

`server/vitest.config.ts` carries one threshold entry per `src/nest/<domain>/`, set at
that domain's measured coverage minus one point. The single repo-wide 80% it replaced
let a well-covered domain subsidise a thin one — `booking-import` sits at 50% and
`integrations` at 20%, and the aggregate still cleared the bar, so either could have
lost another ten points with the build staying green.

Regenerate the block with `node scripts/coverage-thresholds.mjs` after a run that
RAISED coverage. Raise an entry when you improve a domain; never lower one to make a
build pass. The script reads `coverage/coverage-summary.json` rather than the text
reporter on purpose: the text reporter prints one row per DIRECTORY, so a domain with
subdirectories reads several points higher there than it actually is.

## How to write the tests

Every module ships two kinds of tests. The coverage gate (`vitest.config.ts`)
requires ≥80% over `src/nest/**` — note that it is an **average across the whole
tree**, not a per-file floor, so a large untested module can hide behind the
well-covered small ones.

1. **Service / controller unit spec** — `tests/unit/nest/<domain>.controller.test.ts`.
   Instantiate the controller with a mocked service; assert status codes, the exact
   `{ error }` bodies, and that inputs are forwarded correctly (defaults, coercion).
   See `weather.controller.test.ts`.

   Parity against the behaviour being replaced belongs here too — assert the exact
   status codes and bodies the old path produced. There is no separate
   `tests/parity/` directory; it was removed along with the routing toggle.

2. **e2e** — `tests/e2e/<domain>.e2e.test.ts`. Boot the Nest module against a temp
   in-memory SQLite db via the shared harness (`tests/e2e/harness.ts`:
   `createTempDb`/`seedUser`/`sessionCookie`), exercising the **real** `JwtAuthGuard`
   end-to-end (401 without cookie, 200 with a signed session). Mock external I/O
   (HTTP/etc.). See `weather.e2e.test.ts`.

## Definition of Done (per module)

Contract in `@trek/shared` → service ported 1:1 → controller with identical routes →
validation/error parity → unit + e2e tests, with the old behaviour asserted in the
unit test → module registered in `app.module.ts` → **then** decommission the legacy
service (separate step) → frontend points at the typed contract (Frontend Track).

## Migrating a legacy `src/services/*` service into its Nest module (recipe)

**Historical record.** `src/services/` finished emptying in 2026-08 (see above);
the numbered steps below describe how each fold was actually done at the time,
including its `DatabaseService` construction — a deliberate changelog, not a
recipe to follow for new code. `DatabaseService` itself is gone (ORM migration
Plan 4): a service now takes the repositories it needs plus `UnitOfWork` for
transactions, per the root and server `CLAUDE.md`'s DB sections.

Pilot: **tags** (`services/tagService.ts` → `nest/tags/tags.service.ts` +
`nest/tags/tags.bridge.ts`); categories followed the same shape (and piloted the
first `@Resource` in `categories.mcp.ts`); todo followed too (and piloted the
first `@ResourceTemplate` plus the `when` addon gate in `todo.mcp.ts`, and the
first in-container consumer wiring: `TripsService` injects `TodoService` via
`exports: [TodoService]` instead of using the bridge); packing followed (the
largest port so far: a 17-tool + 2-resource `packing.mcp.ts` with inline admin
gates, and the first `PluginHostDepsFactory` swap done as part of a service
migration — no bridge entry for the plugin host); day-notes followed (the first
migration needing **no bridge at all**: after its three tools + resource moved
to `day-notes.mcp.ts` and the plugin host injection, nothing outside the
container consumed it); trip-invite followed (the smallest port: no MCP
surface, no plugin-host import and no bridge — the SQL folded straight into
`trip-invite.service.ts`); assignments followed (a 7-tool `assignments.mcp.ts`,
the plugin-host swap, and a bridge kept only for the two legacy registrars —
places and reservations — that borrow its existence checks; the batch loaders
stay in `services/queryHelpers.ts`, shared with the unmigrated place
service); share followed (never imported by the plugin host, and its three MCP
tools stay in the legacy trips registrar — their `trips:share` scope gate has
no declarative `access: { group, mode }` equivalent — so the port is the SQL
fold plus a 3-export `share.bridge.ts` for `mcp/tools/trips.ts`); settings
followed (no MCP surface, no bridge, and the first migration that converted an
in-container plain-function consumer into a provider instead of bridging it:
`llm-parse/llm-config.resolver.ts` became the injectable `LlmConfigResolver`,
injected by `LlmParseService` and `PluginHostDepsFactory`); files followed (no
MCP surface and no addon gate; the load-time constants + pure helpers consumed
by three controllers' module-scope multer configs moved to
`files.constants.ts`, and `files.bridge.ts` survives with a single export —
the request-time `getAllowedExtensions` app_settings read those configs need
outside DI — while every function consumer, including the plugin host and
`TripsService`, injects `FilesService`); collab followed (a 12-tool +
3-resource `collab.mcp.ts` that piloted **composite `when` gates** — the collab
addon AND the per-sub-feature `getCollabFeatures()` flags (notes/polls/chat)
that the legacy registrar and resources checked at registration time — plus
the plugin-host swap and a 3-export `collab.bridge.ts` for the two remaining
legacy consumers, `tripService`'s trip summary and `mcp/tools/trips.ts`);
vacay followed (the largest MCP port yet — a 26-tool + 3-resource
`vacay.mcp.ts`, including the first fixed-URI `@Resource` behind a `when`
addon gate — plus the plugin-host swap and a 1-export `vacay.bridge.ts` for
`tripService`'s trip-window entry shift; the DTO ratchet for its 13
grandfathered body contracts landed as a sibling commit); reservations
followed (the residue fold: the wrapper `ReservationsService` was already
DI-native at the edge, so the 626-line legacy module folded into it — a 5-tool
+ 1-resource `reservations.mcp.ts`, the plugin host's last plain-function
reservation import (`notifyBookingChange`) swapped for the injected service,
`TripsService` and `BookingImportService` converted from function imports to
injection, and a 9-export + 3-type `reservations.bridge.ts` for the legacy
`tripService`, the airtrail import/sync pair and the still-legacy transports
registrar (the transit registrar has since migrated to `transit.mcp.ts`); the
DTO ratchet for its 4 grandfathered body contracts
landed as a sibling commit, which also loosened the shared positions schema to
the real wire contract — `day_plan_position` optional, pinned by RESV-006);
day followed (the 592-line legacy `dayService` folded into the existing
wrapper `DaysService` — including the accommodation SQL that
`nest/reservations/accommodations.service.ts` now reaches via an injected
`DaysService` — with the hand-rolled `BEGIN`/`COMMIT` blocks in
reorder/insert converted to `db.transaction()`; a 7-tool + 2-resource
`days.mcp.ts`, the plugin host's 11-symbol import swapped for the injected
service, `TripsService` + the assignments/reservations MCP controllers
converted to injection, and a 6-export `days.bridge.ts` for the legacy
`tripService` and the still-legacy transports registrar (transit has since
migrated); the DTO
ratchet for its 4 day + 2 accommodation grandfathered body contracts landed
as a sibling commit);
permissions followed (the first Wave-2 **cross-cutting** migration and the
first greenfield module in the series — no prior wrapper, controller, MCP
surface or DTO of its own: a new `nest/permissions/` whose
`PermissionsService` is injected by 16 domain services, the airtrail-import
controller and `PluginHostDepsFactory` (its 16th constructor dep) in one move,
plus a 5-function `permissions.bridge.ts` for `mcp/tools/_shared.ts` — one
repoint covering every `hasTripPermission` call site — and the four legacy
consumers adminService/authService/backupService/collectionsService; the
permissions **cache stays module-scoped** in `permissions.service.ts` on
purpose, so the bridge instance and the container singleton share one cache
and backup-restore's bridge-side `invalidatePermissionsCache()` flushes what
request handlers serve; the domain e2e suites swapped their path mocks for a
`vi.spyOn(app.get(PermissionsService), 'checkPermission')` instance spy);
auditLog followed (the other Wave-2 half, split into five files: the
injectable `AuditService` (`writeAudit` over `DatabaseService`), the pure
`client-ip.ts` (files.constants precedent — the four getClientIp-only
controllers stay plain imports), the deliberately side-effectful plain
`audit-log.logger.ts` — frozen-at-import `LOG_LEVEL` and the import-time
`data/logs` mkdir are a documented parity exception to the no-side-effects
rule because `index.ts` lazy-requires it pre-container and tests/setup.ts
sets the level pre-import — plus `audit.module.ts` and a full-surface
`audit.bridge.ts` for `mcp/index.ts`, `mcp/oauthProvider.ts` and the legacy
airtrail/immich/oauth services, while log*-only consumers (index.ts's lazy
require strings, scheduler, globalMiddleware, notifications) point at the
logger directly; 8 controllers + `PluginRuntimeService` inject `AuditService`,
and the domain e2e suites dropped the audit mock entirely — writeAudit runs
for real against an `audit_log` table in their temp DBs).
The exchangeRateService fold followed (the pure-infra FX helper — Frankfurter
fetch + module-scoped 6h cache, no SQL, no controller, no MCP registrar of its
own — folded into `nest/budget/` as a dep-free `ExchangeRatesService`, injected
by `BudgetService` and `PluginHostDepsFactory` (its 17th constructor dep); the
rate **cache stays module-scoped** like the permissions cache, so any
out-of-container instance and the container singleton share one cached
upstream feed).
budgetService followed (the 755-line Wave-4 money core folded into the wrapper
`BudgetService`: items/members/payers CRUD, the FX freeze + rebase paths and
the settlement maths with `splitEqualShares` gone private; the freeze-then-write
composites kept their wrapper names while the raw settlement writes became
`insertSettlement`/`applySettlementUpdate` so the MCP paths keep skipping the
freeze; the 11-tool `mcp/tools/budget.ts` registrar + 3 `resources.ts` budget
resources moved to `budget.mcp.ts`; TripsService, ReservationsService (+ its
MCP class) and BookingImportService inject `BudgetService`; a 4-export
`budget.bridge.ts` served the legacy tripService/userCleanupService and the
trips/transports registrars (deleted 2026-08-11: BudgetMcp's demo guard moved
off AuthService onto `isDemoUserId`, BudgetModule dropped AuthModule, and
`UserCleanupService` injects `BudgetService` now);
`exchange-rates.bridge.ts` was deleted with its
last consumers, and the controller adopted `budget.dto.ts` — all nine
allow-list entries removed).
tripService followed (the 1121-line Wave-4 hub — the biggest fold — moved into
the wrapper `TripsService`: TRIP_SELECT + list/create/get, the
`generateDays` two-phase renumber engine, the updateTrip date-shift
transaction, the member/guest lifecycle (#973/#1362), the ICS export with its
module-scoped tz-validity cache, `copyTripById` and `getTripSummary`; its six
bridge imports became injected services (CollabService + VacayService joined
the constructor); the 10-tool trips registrar + 3 `resources.ts` trip
resources + the trip-summary prompt moved to `trips.mcp.ts` — the first
`@Prompt` use, with the fire-once static-token deprecation notice now riding
the `registry.attach` ctx — and the 3 share-link tools it carried moved to
`share.mcp.ts` on the `canShareTrips` predicate (delete_trip and the
canReadTrips reads are predicates too — the broadened legacy gates have no
declarative equivalent); FeedsService and the plugin host inject
`TripsService` (its 20th constructor dep); a 4-export `trips.bridge.ts`
serves budget.mcp.ts / packing.mcp.ts / costs.rpc.ts (verified-permanent
2026-08-11: the trip read-model/members modules import the budget and packing
domains, so injecting any backing service there closes a real cycle; the
prompts registrar it also served is long migrated);
`todo.bridge.ts`, `share.bridge.ts`, `collab.bridge.ts` and `vacay.bridge.ts`
were deleted with their last consumers and the unused days/budget bridge
exports pruned; the controller adopted `trips.dto.ts` — all seven allow-list
entries removed).
mapsService followed (the 1429-line geo core — Google Places, Nominatim,
Overpass mirror racing, Wikimedia photos, Maps-URL resolution — folded into the
wrapper `MapsService`; the pure parser/UA/POI-category helpers moved to
`maps.helpers.ts` as plain exports (files.constants/client-ip precedent —
the DI-native TransitService's User-Agent imports from there, not a bridge), the module-scoped
POI cache / photo-fetch semaphore / frozen Overpass mirrors stayed module-scoped
on purpose (permissions-cache precedent: any out-of-container instance and the
DI singleton share them); the 3 geo tools left the mixed `mcp/tools/mapsWeather.ts`
registrar for the decorator-driven `maps.mcp.ts` (the registrar file survives —
its weather + airport tools await their own migrations); BookingImportService
injects `MapsService` for its Nominatim geocoding, and a 3-export
`maps.bridge.ts` served the legacy placeEnrichment helper and the places
registrar — both absorbed by the 2026-07 place fold, which deleted the bridge).
transitService followed (the first fully SQL-free domain fold — the 333-line
Transitous/MOTIS proxy became a dep-free `TransitService` (no
`DatabaseService`; the ExchangeRatesService precedent), its response cache,
frozen-at-import `TRANSIT_API_BASE` and lazy User-Agent memo staying
module-scoped on purpose; the pure `deriveTransitStats` + mode whitelist +
itinerary types moved to `transit.helpers.ts` (maps.helpers precedent) so the
downstream legacy `transitItineraryService` needed no bridge (since relocated
into the domain as `transit-itinerary.helpers.ts`); the whole 3-tool
`mcp/tools/transit.ts` registrar moved to `transit.mcp.ts` — the two geo
search tools on `access: { group: 'geo', mode: 'read' }` and
`create_transit_journey` on `reservations:write`, with its days/reservations
bridge imports becoming injected `DaysService`/`ReservationsService` (+
`DatabaseService` for `canAccessTrip`) — leaving **zero bridge files** and the
transports registrar as `days.bridge.ts`'s last consumer).
placeService followed (the step-4 tail: the 1029-line place core — the
CRUD + ratings SQL, the GPX/KML/KMZ importers and the Google/Naver list
importers — folded into the wrapper `PlacesService`, with the pure pieces
(frozen XML parsers, the KMZ unpacker, the dedup predicates, the Google
hex-id parsers, `reclaimPhotoCache`) moving to `places.helpers.ts` on the
maps.helpers precedent; the 10-tool `mcp/tools/places.ts` registrar + the
`trek://trips/{tripId}/places` resource moved to `places.mcp.ts` —
`search_place` came along because its gate is `places:read`, not the geo
group, and now injects `MapsService`; TripsService, DaysMcp,
BookingImportService and the plugin host (its 21st constructor dep) inject
`PlacesService`, leaving **zero bridge files** for the domain; the two
`assignments.bridge` imports stay in `places.mcp.ts` on purpose —
AssignmentsModule imports DaysModule and DaysModule now imports
PlacesModule, so injecting would close a
DaysModule → PlacesModule → AssignmentsModule → DaysModule cycle
(reservations.mcp.ts uses the same seam for the same reason). The sibling
`placeEnrichment` fold went further than the recipe's minimum: the 168-line
helper's DB/websocket/Maps half became `PlacesService` methods over the
injected `DatabaseService`/`RealtimeService`/`MapsService` and its pure
match selector joined `places.helpers.ts`, which retired **`maps.bridge.ts`**
with its last consumer. The DTO ratchet for its 7 grandfathered body
contracts landed as a third commit, which also loosened
`placeBulkUpdateRequestSchema.ids` (`.min(1)` dropped) so the endpoint's
empty-list short-circuit stays reachable, and retired three bespoke 400
strings — 'Place name is required', 'ids must be an array of numbers' and
'URL is required' — in favour of the pipe envelope, accepting that a
malformed body now 400s ahead of the trip-access 404 (the todo/trips trade).
transitItineraryService followed (the first pure-helpers relocation with no
service fold at all — the 287-line module is 100% pure, so the recipe's SQL /
bridge / DTO / plugin-host steps were all no-ops: the Zod itinerary schemas +
endpoint/metadata builders moved byte-identical to
`transit-itinerary.helpers.ts`, next to `transit.helpers.ts`; the schemas
**must** stay module-level plain exports because `transit.mcp.ts` consumes
them inside `@Tool({ inputSchema })` decorators, which evaluate at module load
before any container exists; the sole consumer — the in-container
`transit.mcp.ts` — was a one-import repoint, closing step 4 of the
dependency-honest order; the legacy module had no direct suite, so a new
21-case `TRANSIT-ITIN-*` characterization suite now pins all 12 superRefine
error strings, the `??` time fallbacks, the coordinate tolerances and the
reservation endpoint/metadata builder).
collectionsService followed (the biggest single fold yet — 1024 lines / 28
exports into `CollectionsService` over DatabaseService + PermissionsService +
RealtimeService, with the `deleteOldCollectionCover` path re-anchored one
directory deeper and the `sendInvite` lazy notificationService `import()`
kept, collab precedent; the 25-tool legacy registrar `mcp/tools/collections.ts`
moved to `collections.mcp.ts` — at relocation time deliberately with NO
`when:` addon gate, since the legacy registrar registered unconditionally
while REST/plugin-host gate on the addon; the trailing `fix(server)` quirk
commit then gated all 25 tools (the addon ships disabled by default, so the
ungated surface was live on fresh installs) alongside wrapping every
multi-statement write in `db.transaction()`, making the bulk ops
all-or-nothing, and forwarding `X-Socket-Id` on the from-trip saves — each
pinned by a new 23-case `tools-collections` characterization suite plus the
`COLLECTIONS-SVC-090…092` band (the legacy registrar had no tool-level tests
at all);
the plugin host swapped its 7 collections imports for the injected service —
its 22nd constructor dep — and NO bridge was needed anywhere; the dead
`buildDedupSet` module helper was dropped in the move, the only line that
didn't relocate verbatim).
atlasService followed (1612 lines split two ways, places precedent: the DB
half — stats aggregation, visited countries/regions with the #1490
tombstone/cascade logic, bucket-list CRUD — folded into `AtlasService` over
DatabaseService alone, while the ~750-line pure-geo half — the bundled
admin0/admin1 stores and their #1576 OOM-shaped streaming builders, the
point-in-polygon indexes, Nominatim geocoding with its shared ≥1.1s throttle,
the 50k geocode cache with its import-time unref'd cleanup interval, and the
`geocodingInFlight` dedup set — moved to the plain module `atlas-geo.ts` so
those caches stay process-global across the container instance, the bridge
instance and test helpers; `assetPath` re-anchored one directory deeper, the
only non-verbatim line. The 10-tool legacy registrar `mcp/tools/atlas.ts`
plus all four atlas resources in `mcp/resources.ts` (`trek://bucket-list`,
`trek://visited-countries`, `trek://atlas/stats`, `trek://atlas/regions`)
moved to `atlas.mcp.ts` — here the `when:` atlas-addon gate IS parity, since
the legacy registrar and resources both gated on the addon while the REST
controller deliberately does not; the mark_region_visited /
get_country_atlas_places no-uppercase divergence from REST relocated
untouched. The plugin host swapped its 9 atlas imports for the injected
service — its 23rd constructor dep — and a minimal 2-export `atlas.bridge.ts`
existed solely for the legacy `authService.getTravelStats` edge
(`getCountryFromCoords` re-exported straight from atlas-geo,
`getHiddenCountries` over the bridge instance); it died with the auth fold, as
predicted. resources.test.ts retired with its last two cases — every resource
it covered now lives in the domain suites. The trailing `fix(server)` quirk
commit then wrapped the four multi-statement mark/unmark writes in
`db.transaction()` (the region cascade nests as a savepoint), made the
trip-less `countryPlaces` early return honour `manually_marked`, fixed the
`|| null` bindings that dropped `lat: 0`/`lng: 0`/`notes: ''` on bucket
update, user-scoped the mutating bucket SQL, and uppercased the MCP
region/country-places codes to match REST — each pinned by
`ATLAS-SVC-031…036` plus two MCP casing cases; see migration-graph.md's
"Quirks fixed after the atlas fold".)
authService followed (1497 lines, the biggest fold and the head of the
auth → admin → oauth chain: the pure crypto half — backup-code
hash/match/generate, `stripUserForClient`, key masking, the import-time
`DUMMY_PASSWORD_HASH` timing equaliser and the `avatarDir` mkdir (both
documented parity exceptions) — moved to the plain module `auth.helpers.ts`,
while the DB half — toggles/app-config, register/login with the CWE-208
dummy-hash path, MFA setup/enable/disable/verify, the password-reset
throttle+token flows with their two `db.transaction()` revocation blocks,
API keys/settings, travel stats, MCP/ws/resource tokens, `isDemoUser` and
the two token verifiers — folded into `AuthService` over DatabaseService +
injected PermissionsService (ex `permissions.bridge`) and AtlasService (ex
`atlas.bridge`, which died on schedule). The `mfaSetupPending` and
per-email reset-throttle maps stay module-scoped (with the unref'd cleanup
interval) so the bridge instance and the container singleton share them; the
otplib `window: 1` mutation runs at module top; `require('../../../package.json')`
and `avatarDir` re-anchored one directory deeper — the only non-verbatim
lines besides the two injection swaps. No MCP registrar existed and the
plugin host never imported authService, so neither surface changed; the 15
in-container `*.mcp.ts` demo guards now inject AuthService (their modules
import AuthModule) — except `atlas.mcp.ts`, which keeps a bridge import
because AuthService injects AtlasService and the reverse module edge would
close a cycle (places.mcp precedent). The 8-export `auth.bridge.ts` serves
`mcp/index.ts` token verification, the three legacy tool registrars'
`isDemoUser`, and the un-migrated adminService.
Tests moved with IDs preserved: authService.test.ts → auth.helpers.test.ts,
authServiceDb.test.ts → auth.service.test.ts (+ AUTH-BR-001…007 bridge
delegation); auth.e2e converted DI-native — the 30-method whole-module mock
died, login now runs real bcrypt and real audit rows; oidc.e2e switched its
dead path-mock for a `vi.spyOn(app.get(AuthService), …)` instance stub.)
oidcService followed (the frontier cash-in the auth fold predicted: a pure
fold of the 508-line module into the existing wrapper `OidcService` over
DatabaseService + injected AuthService — the `resolveAuthToggles`
`auth.bridge` import became the injection, the first repoint-consumer of that
bridge to migrate. No MCP registrar, no plugin-host import, and **no bridge
at all**: nothing outside the container consumes the domain (day-notes/
trip-invite class), so the `pendingStates`/`authCodes` maps, their two sweep
`setInterval`s, the single-slot discovery cache and the JWKS cache became
**instance state** — the module-scope precedent (permissions/atlas-geo/auth
maps) applies only where a bridge instance must share state, and none exists
here; the sweepers start in the constructor and are cleared in
`onModuleDestroy`, the one wire-invisible deviation. The `uuid`/`bcryptjs`
lazy requires, the `invite_exhausted` reference-sentinel transaction (reshaped
one line for `DatabaseService.transaction`) and every SQL string relocated
verbatim; controller and its unit suite needed zero edits. Tests moved with
IDs preserved: oidcService.test.ts → oidc.service.test.ts (OIDC-SVC-001…045,
superseding the 18-case delegation-shim suite; 046–048 carry its wrapper
cases); oidc.e2e swapped its whole-module path mock for
`vi.spyOn(app.get(OidcService), …)` instance spies; the integration suite
spies the four HTTP methods on the container instance while driving the real
state maps on that same instance.)
passkeyService followed (the last frontier member of the auth stack: the
364-line WebAuthn module folded into a new `nest/auth/passkey.service.ts`
`PasskeyService` over DatabaseService + injected AuthService — its three
`auth.bridge` imports resolved to `this.auth.generateToken` plus plain
`stripUserForClient`/`avatarUrl` helper imports, and `resolveWebauthnConfig`
stayed a plain `services/webauthnConfig` import at the time (it has since
become the injected `WebauthnConfigService`, which also feeds auth.service's
`passkey_configured`). No MCP registrar, no plugin-host
import, and **no bridge at all** — both consumers were already in-container:
`PasskeyController` swapped its `import *` shim for the injection, and
`AdminService` swapped its `adminResetPasskeys` function import for the
injected service (`AuthModule` now exports PasskeyService and `AdminModule`
imports AuthModule — the todo→TripsService in-container precedent). No
module-level mutable state existed to preserve: the challenge store is
DB-backed (`webauthn_challenges`, single-use `DELETE … RETURNING` claim,
5-min TTL), so the fold is a plain stateless injectable — every SQL string,
error string and the counter/login-bookkeeping transaction relocated
verbatim. Tests: the legacy module had **no service-level suite**, so
PASSKEY-SVC-001…030 were written fresh with the fold (characterization over a
real `:memory:` DB, `@simplewebauthn/server` mocked at the ceremony-verdict
boundary — the repo's first such mock); auth-guard.test.ts's PasskeyController
block swapped its path mock for a constructor stub.)
notificationService followed (the notifications fan-in, step 3 of the
dependency-honest order: the `send()` dispatcher **and** the
`inAppNotifications.ts` store folded together into the existing
`NotificationsService` over DatabaseService + RealtimeService — the wrapper's
in-app delegation became the real SQL, while the prefs matrix, the smtp/
webhook/ntfy transports, the channel registry and `inAppNotificationActions`
stay plain-module imports (graph-classified infra helpers, complete with
their registry⇄prefs cycle). A one-export `notifications.bridge.ts` (`send`)
covered the outside-container consumers — scheduler's two cron `require`s,
legacy adminService and memories/{unified,synology} (that bridge died
2026-08-10 with the scheduler migration; `notifications.instance.ts` carries
the surviving cycle-dodge bridges) — **and** the six
deliberately-lazy fire-and-forget `import().then(({ send }) => …)` sends in
migrated Nest services (collab/collections/packing/reservations/trips/vacay,
path-only repoints; kept lazy so a send can never block or cycle a domain
module). In-container static consumers inject instead: `AdminController`'s
dev test send (AdminModule → NotificationsModule) and the plugin host
(`NotificationsService` = `PluginHostDepsFactory`'s 24th dep). The 5-tool
legacy registrar + the `notifications-in-app` resource moved 1:1 to
`notifications.mcp.ts` (no `when:` — the domain is core, not addon-gated).
Tests moved with IDs preserved: notificationService.test.ts →
notifications.service.test.ts (NSVC-001…019/NTFY-SVCB-*/NSVC-PLUG-001…007,
plus the NSVC-020 bridge pin), inAppNotificationPrefs.test.ts →
notifications.inapp-prefs.test.ts (INOTIF-*); ~18 suites repointed their
path mocks/warm-ups to the bridge; admin.controller.test and the plugin-host
suite converted theirs to constructor stubs; the module e2e went DI-native
(real notifications DDL, prefs/transports still path-mocked).)
adminService followed (the last Wave-5 god file and the first fold where recipe
steps 2-4 were all no-ops or near-no-ops: **no `src/mcp/tools/admin.ts` has ever
existed** — the "11 MCP consumers" figure carried in `migrate.md` /
`migration-graph.md` predated the Phase-0 addons extraction, so no registrar
moved, `mcp/tools.ts` / `mcp/resources.ts` / `mcp-test-controllers.ts` were
untouched — and `plugin-host-deps.factory.ts` never imported the domain either
(its addon reads already went through the DI-native `AddonsService`). The
851-line module folded into the wrapper `AdminService` over `DatabaseService`
plus injected Settings/Addons/Passkey/Packing/Auth/Permissions/Notifications
services: the `auth.bridge` (`resolveAuthToggles`), `notifications.bridge`
(`send`) and `permissions.bridge` (`getAllPermissions`/`savePermissions`)
imports all became injections, while `PERMISSION_ACTIONS` stayed a plain const
import and the `mcp/sessionManager` deep import kept its anti-cycle comment.
The pure + module-scoped half moved to `admin.helpers.ts` — `compareVersions`,
`utcSuffix` (since moved to `db/types`, shared with `auth.helpers`), `BCRYPT_COST`, the import-time `isDocker` probe (a documented
parity exception, auth.helpers precedent) and the 5-minute version cache, which
stays module-scoped so the bridge instance and the container singleton share it.
Ahead of the fold the 11 packing-template functions relocated to
`PackingService`, which already owned all three template tables
(`saveAsTemplate` writes every one of them) — that also resolved the `admin-2`
residual without a bridge, since `packing.mcp.ts` already injects the service;
`AdminModule` gained PackingModule and PermissionsModule, both cycle-free.
A 1-export `admin.bridge.ts` (`checkAndNotifyVersion`) served the only
out-of-container consumer, `scheduler.ts`'s daily cron (both died 2026-08-10
with the scheduler migration — `VersionCheckJob` injects `AdminService`).
Four lines are
non-verbatim, all path re-anchoring one directory deeper for `nest/admin/`
(`rotateJwtSecret`'s data dir, the `package.json` version require, the
websocket/demo-reset lazy requires) — both resolved paths verified against the
emitted `dist/` layout. Tests moved with IDs preserved (adminService.test.ts →
`nest/admin.service.test.ts`, ADMIN-SVC-001…069 incl. the pre-existing 029/030
gap and duplicated 069, + ADMIN-BR-001 pinning the bridge and the shared version
cache; versionNotification.test.ts → `nest/admin.version-notification.test.ts`,
VNOTIF-001…007; the template cases rode along to `packing.service.test.ts`), and
the module e2e went DI-native — its 3-method whole-module mock died, 6 cases
became 15 over real SQL. A sibling DTO ratchet cleared all twenty
`AdminController` allow-list entries — the largest single block — trading the
three `'enabled must be a boolean'` checks plus `'permissions object required'`
and `'Object body required'` for the pipe envelope; the schemas are
deliberately permissive wherever the service owns a bespoke 400 of its own.)
Repeat these steps per
service (next up: **backupService** / **airtrail** —
per the dependency-honest order in
`migration-graph.md`). This is a
**pure relocation** — byte-identical
SQL, statuses, bodies, and error strings. The plugin RPC host is **no longer a
bridge consumer**: since Option A of `src/nest/plugins/DI-MIGRATION.md` it
injects domain services via `PluginHostDepsFactory`, so a migrated domain adds
`exports: [XService]` + a `PluginsModule` import instead of a bridge entry.
Only the pre-`app.init()` MCP/OAuth mount still needs bridges — the module-
cycle seams are folded, nothing on the websocket path imports one, and the
crons all inject now (`*.job.ts` providers on `scheduling/CronRegistrarService`).

1. **Move the SQL** into `<domain>.service.ts` as methods over an injected
   `DatabaseService` (`this.db.all<T>/get<T>/run/prepare`; multi-statement writes go
   through `await this.uow.transactional(...)` instead — see the root `CLAUDE.md`;
   strict constructor injection, no `@Optional()`). Preserve every quirk: falsy-coercion
   defaults (`x || fallback`, never `??`), post-insert/post-update re-selects (no
   RETURNING), `COALESCE` semantics. If a controller already wraps the legacy
   functions, do not change the service's method surface. The module needs no
   `imports: [DatabaseModule]` — it's `@Global`.
2. **Add `<domain>.bridge.ts`** next to the service **only if non-Nest consumers
   exist** (legacy MCP tool registrars, websocket — the plugin RPC host and the
   crons now inject instead, see above). It builds a module-level instance over
   the shared connection Proxy — `new XService(new DatabaseService(db))`,
   reinitialize-proof, same pattern as `nest/todo/todo.bridge.ts` — and exports
   the legacy function names 1:1.
   Container code injects the service; only outside-container code imports the
   bridge. When porting an MCP registrar, note the `access: { group, mode }`
   markers are typed against the scope-derived `ScopeGroup` union and
   boot-validated by `trekMcpValidateAccess` (`src/mcp/nest-mcp-policy.ts`) —
   an unknown group, or `mode: 'write'` on a read-only group (`geo`,
   `weather`), fails app boot. **`mode` is typed the same way**: it is the mode
   half of `Scope` (`read | write | delete | share`), fed into
   `src/nest-mcp/types.ts` through `McpAccessModeRegistry` exactly like the
   group registry. A scope that is neither read nor write — `journey:share` is the
   one today — gets a real marker, *not* a `(ctx) => canX(ctx.scopes)`
   predicate: predicates bypass the policy entirely and are invisible to the
   boot gate, so a scope typo in one would ship as a silent full-access tool.
   Reach for a predicate only when the gate genuinely is not a scope. *(Design decision, settled with the tags pilot:
   MCP tools stay outside the container and use the bridge. The alternative — handing the Nest app to the
   MCP layer via `app.get(XService)` — was rejected: it would thread the container
   through `mcpHandler` + every tool registrar and force a Nest bootstrap into the
   container-less `tests/helpers/mcp-harness.ts` used by ~25 MCP suites.)*
3. **Repoint non-Nest consumers** — import-path-only diffs from
   `services/<x>Service` to `nest/<domain>/<domain>.bridge`; call sites unchanged.
4. **Delete the legacy service** once `grep -rn "services/<x>Service" src tests`
   only hits the tests you're rewriting.
5. **Tests:**
   - Move `tests/unit/services/<x>Service.test.ts` →
     `tests/unit/nest/<domain>.service.test.ts`, preserving case IDs. Construct the
     service directly — `new XService(new DatabaseService(testDb))` — no
     TestingModule, no `overrideProvider` (repo convention). Add one delegation
     case per bridge export: the bridge sits under `src/nest/**`, inside the ≥80%
     coverage gate, and these cases pin it deterministically.
   - Convert the module e2e to the DI-native pattern (exemplar
     `tests/e2e/trips.e2e.test.ts`): temp-db DDL for the domain's tables,
     `imports: [DatabaseModule, <Domain>Module]`, real SQL assertions. Keep only
     the `vi.mock('../../src/db/database', …)` — the auth guard still reads users
     through the singleton, and `DatabaseModule`'s factory picks up the same
     mocked db. Drop the legacy-service mock entirely.
   - Suites that mocked the legacy module mock the bridge path instead — same
     factory shape, path-only change. (For the plugin host suite,
     `plugin-host-deps.factory.test.ts`, the domain becomes a constructor stub
     instead of a path mock.)
6. **Verify** (from `server/`): `npm run typecheck`, `test:unit`,
   `test:integration`, `test:e2e`, `lint:check`, `test:coverage`.