feat(places): record which search result was picked, on this instance only

The corpus behind "is our own index good enough to replace Nominatim".
When somebody searches and then picks a result, the client posts the query,
the rank and the pick. Nothing else: no user, no trip, no session, and
coordinates only to three decimals.

Deliberately decoupled from the search endpoint. Correlating a response
with a later pick would mean handing out a ticket on POST /api/maps/search
and threading it through all fifteen call sites; the client already holds
everything the row needs at the moment of the pick.

Evaluation happens offline afterwards: export the corpus, run it against a
candidate index, count how often the pick came back in the top five. That
is why collection can start before such an index exists, which is the whole
point, because the corpus needs weeks of real use and the index needs a
server, and those two waits should not be serial.

Off unless an admin switches it on, and it reads === 'true' rather than
!== 'false'. The three older places switches fail open because a migration
backfilled a row for installs already using them; nothing uses this one, so
an instance that upgrades and never visits the admin panel logs nothing.

Reading is admin only, retention is 180 days, and the switch state is on the
unauthenticated app-config endpoint on purpose: whether an instance records
what its users search for is something a visitor may know before logging in.

client/src/api/client.ts

@@ -647,6 +647,8 @@ export const adminApi = {
   updateBagTracking: (enabled: boolean) => apiClient.put('/admin/bag-tracking', { enabled }).then(r => r.data),
   getPlacesPhotos: () => apiClient.get('/admin/places-photos').then(r => r.data),
   updatePlacesPhotos: (enabled: boolean) => apiClient.put('/admin/places-photos', { enabled }).then(r => r.data),
+  getPlaceShadow: () => apiClient.get('/admin/place-shadow').then(r => r.data),
+  updatePlaceShadow: (enabled: boolean) => apiClient.put('/admin/place-shadow', { enabled }).then(r => r.data),
   getPlacesAutocomplete: () => apiClient.get('/admin/places-autocomplete').then(r => r.data),
   updatePlacesAutocomplete: (enabled: boolean) => apiClient.put('/admin/places-autocomplete', { enabled }).then(r => r.data),
   getPlacesDetails: () => apiClient.get('/admin/places-details').then(r => r.data),

client/src/api/placeShadow.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { server } from '../../tests/helpers/msw/server'
+import { useAuthStore } from '../store/authStore'
+import { recordPlacePick } from './placeShadow'
+import type { PlaceShadowPickRequest } from '@trek/shared'
+
+/**
+ * The point of this module is that it never gets in the way: it must not fire
+ * when the instance has the log switched off, must not throw when the request
+ * fails, and must not send coordinates finer than the ranking needs.
+ */
+
+const PICK: PlaceShadowPickRequest = {
+  query: '  losteria rostock  ',
+  lang: 'de',
+  biasLat: 54.088712,
+  biasLng: 12.140493,
+  source: 'search:nominatim',
+  liveRank: 0,
+  liveCount: 8,
+  pickedName: "L'Osteria",
+  pickedLat: 54.0891234,
+  pickedLng: 12.1372987,
+  pickedPlaceId: 'osm:node/1',
+}
+
+/** Resolves with the body the module posted, or null if it never posted. */
+function capture(status = 200) {
+  let seen: unknown = null
+  let resolve: (v: unknown) => void = () => {}
+  const posted = new Promise<unknown>(r => { resolve = r })
+  server.use(
+    http.post('/api/place-shadow/pick', async ({ request }) => {
+      seen = await request.json()
+      resolve(seen)
+      return status === 200
+        ? HttpResponse.json({ recorded: true })
+        : HttpResponse.json({ error: 'nope' }, { status })
+    }),
+  )
+  return { posted, seen: () => seen }
+}
+
+beforeEach(() => {
+  useAuthStore.setState({ placeShadowEnabled: true })
+})
+
+describe('recordPlacePick', () => {
+  it('sends nothing at all when the instance has the log switched off', async () => {
+    useAuthStore.setState({ placeShadowEnabled: false })
+    const cap = capture()
+    recordPlacePick(PICK)
+    await new Promise(r => setTimeout(r, 20))
+    expect(cap.seen()).toBeNull()
+  })
+
+  it('trims the query and rounds every coordinate to three decimals', async () => {
+    const cap = capture()
+    recordPlacePick(PICK)
+    expect(await cap.posted).toMatchObject({
+      query: 'losteria rostock',
+      pickedLat: 54.089,
+      pickedLng: 12.137,
+      biasLat: 54.089,
+      biasLng: 12.14,
+    })
+  })
+
+  it('leaves an absent bias absent rather than sending a zero', async () => {
+    const cap = capture()
+    recordPlacePick({ ...PICK, biasLat: undefined, biasLng: undefined })
+    const body = (await cap.posted) as Record<string, unknown>
+    expect(body.biasLat).toBeUndefined()
+    expect(body.biasLng).toBeUndefined()
+  })
+
+  it('drops a pick with no query, no name or an impossible rank before sending', async () => {
+    const cap = capture()
+    recordPlacePick({ ...PICK, query: '   ' })
+    recordPlacePick({ ...PICK, pickedName: '' })
+    recordPlacePick({ ...PICK, liveRank: 8, liveCount: 8 })
+    recordPlacePick({ ...PICK, pickedLat: Number.NaN })
+    await new Promise(r => setTimeout(r, 20))
+    expect(cap.seen()).toBeNull()
+  })
+
+  it('swallows a server error instead of surfacing it to the pick that triggered it', async () => {
+    const cap = capture(500)
+    const onUnhandled = vi.fn()
+    process.on('unhandledRejection', onUnhandled)
+    expect(() => recordPlacePick(PICK)).not.toThrow()
+    await cap.posted
+    await new Promise(r => setTimeout(r, 20))
+    process.off('unhandledRejection', onUnhandled)
+    expect(onUnhandled).not.toHaveBeenCalled()
+  })
+})

client/src/api/placeShadow.ts

@@ -0,0 +1,42 @@
+import type { PlaceShadowPickRequest } from '@trek/shared'
+import { apiClient } from './client'
+import { useAuthStore } from '../store/authStore'
+
+/**
+ * Records which search result the user picked, for the local shadow corpus.
+ *
+ * Fire and forget in the strongest sense: it never throws, never blocks the
+ * pick it is describing, and does nothing at all unless the instance switched
+ * the log on. Adding a place must not get slower or more fragile because
+ * somebody is collecting a measurement.
+ *
+ * The store flag is checked first so a switched-off instance makes no request
+ * at all; the server checks it again, because a client is not a permission.
+ */
+
+/** About 100 m. Enough to reproduce a ranking, too coarse to place someone. */
+function coarse(value: number): number {
+  return Math.round(value * 1000) / 1000
+}
+
+export function recordPlacePick(pick: PlaceShadowPickRequest): void {
+  if (!useAuthStore.getState().placeShadowEnabled) return
+  if (!Number.isFinite(pick.pickedLat) || !Number.isFinite(pick.pickedLng)) return
+  if (pick.liveRank >= pick.liveCount) return
+
+  const body: PlaceShadowPickRequest = {
+    ...pick,
+    query: pick.query.trim().slice(0, 200),
+    pickedName: pick.pickedName.slice(0, 300),
+    pickedLat: coarse(pick.pickedLat),
+    pickedLng: coarse(pick.pickedLng),
+    biasLat: pick.biasLat === undefined ? undefined : coarse(pick.biasLat),
+    biasLng: pick.biasLng === undefined ? undefined : coarse(pick.biasLng),
+  }
+  // The contract requires both; an unnamed result is not worth a row anyway.
+  if (!body.query || !body.pickedName) return
+
+  void apiClient.post('/place-shadow/pick', body).catch(() => {
+    // Deliberately silent. The user was adding a place, not running a study.
+  })
+}