feat: place text-search with durable cache insert + unified type classification

[timwangmusic]

Description

Adds free-text place search with durable cache insertion, closing the gap where the legacy Nearby Search never returns certain places at all (verified live: Konjoe Burger, a food-hall stall at State Street Market, is absent from the cache even immediately after a fresh cold search — downtown Los Altos has only 7 cached eateries within 2 km).

Consumed by OfferBee's best-card page: when a user can't find a place in the nearby list, they explicitly search, pick the right result, and that place is inserted into the geo cache — immediately answering "which card should I use here" and making the place durably visible in category results for everyone.

Solution

1. Expanded type→category reverse map, one rule everywhere (9b6d167)
GetPlaceCategory grows from an 18-type switch to a 43-entry placeTypeToCategory table (meal_delivery→Eatery, convenience_store and the *_store family→Shopping, tourist_attraction/stadium/movie_theater→Visit, drugstore/beauty_salon→Wellness, …). ReclassifyForCategory (the category read filter) now keys on the same map as the cleanup migration — one rule for "does this place belong in this category".

The change is monotone: the map is a strict superset of the searched types (pinned by TestGetPlaceTypesSubsetOfCategoryMap), so strictly more cached places become visible on category reads, never fewer. No data migration needed. GetPlaceTypes — the searched subset that shapes outbound Google queries — is byte-identical, so no new ?type= values can reach the legacy API (the #446/#447 incident vector stays closed; TestGetPlaceCategoryKeysAreGoogleTypes structurally guards the map against non-legacy values, and fast_food_restaurant/food_court remain deliberately refused).

2. Text search + candidate stash + confirm-insert (2a2ecdb, a23d808)

• POST /v1/place-search: legacy Text Search with query+location+radius only — never a type filter (that's the incident vector) — parsed WITHOUT the zero-ratings filter that hides exactly the new/obscure places this feature targets. Every candidate is stashed server-side (30-min TTL).
• POST /v1/place-search/confirm: takes only {placeId}, resolves it against the stash (fabricated data can never reach the cache), derives the category server-side from Google's primary type — unmapped types are refused with 422 and nothing is written — enriches via one best-effort Place Details call (hours/URL/photo), never clobbers a previously-cached record's real hours or photo, writes through the audited SetPlacesAddGeoLocations, and read-back-verifies.
• Anti-pollution is structural: the confirm response's category and the Redis bucket are two reads of the same map with the same key — a mismatch is unrepresentable.

3. Docs (d6b71da, a272365, 2a61462)
README API docs incl. a Visibility note (bucket membership is immediate; category-read visibility in a cold cell takes until the second read, because the freshness-marker path replaces rather than unions cached members — pre-existing behavior, follow-up filed; never stamp MapsLastSearchTime to force it). The reclassify-buckets runbook now carries the complete production residue audit: 27 records = 5 newly removable (shoe_store×2, furniture_store, hardware_store, stadium) + 1 legitimized (night_club — Cain's Ballroom) + 21 residue. Dry-run counts WILL change vs the old 145/0/12/4/3 baseline because the map changed — expected, not a red flag. Do not apply=true without reviewing the new dry-run output.

Deploy ordering (matters)

OfferBee's reward-table change (already merged on their side as C1) must deploy before this does. The expanded map means category reads immediately start emitting re-tagged locationType values (meal_delivery, convenience_store, …); without the reward-table entries those fall back to base rate. Order: OfferBee C1 → this PR → dry-run the cleanup per the updated runbook → OfferBee's UI PR.

New endpoints share the existing global 100 req/hr/IP rate limiter with the category search (single Convex egress IP) — the client gates search behind an explicit tap, but 429s on nearby reads are the metric to watch after deploy. Confirm costs 1 Text Search + 1 Place Details billed call per user action.

Testing

• Integration testing on Heroku staging — not done; needs a deploy + the smoke steps in the README Visibility note (verify via ZSCORE, expect up to two category reads in a cold cell)
• Added new unit tests

~60 new tests across 6 files (map/reclassify pins incl. a monotonicity property test and mutation-verified guards, text-search parser rules, insert-flow truth table on miniredis incl. nothing-written-on-422, handler auth/validation incl. an end-to-end 422 with a real unmapped type, hermetic wire-shape marshal tests). go build -v . clean, go test -v ./... 6/6 packages, go vet clean, suite also green under -shuffle=on.

Checks

• Have you removed commented code?
• Have you used gofmt to format your code? (gofmt -l empty)