@mailwoman/resolver-wof-sqlite 7.2.0 → 7.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/resolver-wof-sqlite",
-  "version": "7.2.0",
+  "version": "7.2.1",
   "description": "Who's On First SQLite resolver — FTS5-backed PlaceLookup that resolves text queries to WOF place IDs + coordinates. Optional dependency for callers who want geocoding.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -13,145 +13,231 @@
     "out/**/*.js.map",
     "out/**/*.d.ts",
     "out/**/*.d.ts.map",
-    "README.md"
+    "README.md",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     },
     "./fts": {
-      "node": "./fts.ts",
-      "default": "./out/fts.js",
-      "types": "./out/fts.d.ts"
+      "types": "./out/fts.d.ts",
+      "default": "./out/fts.js"
     },
     "./build-slim": {
-      "node": "./build-slim.ts",
-      "default": "./out/build-slim.js",
-      "types": "./out/build-slim.d.ts"
+      "types": "./out/build-slim.d.ts",
+      "default": "./out/build-slim.js"
     },
     "./fst-builder": {
-      "node": "./fst-builder.ts",
-      "default": "./out/fst-builder.js",
-      "types": "./out/fst-builder.d.ts"
+      "types": "./out/fst-builder.d.ts",
+      "default": "./out/fst-builder.js"
     },
     "./street-morphology-fst-builder": {
-      "node": "./street-morphology-fst-builder.ts",
-      "default": "./out/street-morphology-fst-builder.js",
-      "types": "./out/street-morphology-fst-builder.d.ts"
+      "types": "./out/street-morphology-fst-builder.d.ts",
+      "default": "./out/street-morphology-fst-builder.js"
     },
     "./fst-matcher": {
-      "node": "./fst-matcher.ts",
-      "default": "./out/fst-matcher.js",
-      "types": "./out/fst-matcher.d.ts"
+      "types": "./out/fst-matcher.d.ts",
+      "default": "./out/fst-matcher.js"
     },
     "./fst-serialize": {
-      "node": "./fst-serialize.ts",
-      "default": "./out/fst-serialize.js",
-      "types": "./out/fst-serialize.d.ts"
+      "types": "./out/fst-serialize.d.ts",
+      "default": "./out/fst-serialize.js"
     },
     "./fst-autocomplete": {
-      "node": "./fst-autocomplete.ts",
-      "default": "./out/fst-autocomplete.js",
-      "types": "./out/fst-autocomplete.d.ts"
+      "types": "./out/fst-autocomplete.d.ts",
+      "default": "./out/fst-autocomplete.js"
     },
     "./fst-types": {
-      "node": "./fst-types.ts",
-      "default": "./out/fst-types.js",
-      "types": "./out/fst-types.d.ts"
+      "types": "./out/fst-types.d.ts",
+      "default": "./out/fst-types.js"
     },
     "./fst-deserialize-web": {
-      "node": "./fst-deserialize-web.ts",
-      "default": "./out/fst-deserialize-web.js",
-      "types": "./out/fst-deserialize-web.d.ts"
+      "types": "./out/fst-deserialize-web.d.ts",
+      "default": "./out/fst-deserialize-web.js"
     },
     "./unified-schema": {
-      "node": "./unified-schema.ts",
-      "default": "./out/unified-schema.js",
-      "types": "./out/unified-schema.d.ts"
+      "types": "./out/unified-schema.d.ts",
+      "default": "./out/unified-schema.js"
     },
     "./ancestry-backfill": {
-      "node": "./ancestry-backfill.ts",
-      "default": "./out/ancestry-backfill.js",
-      "types": "./out/ancestry-backfill.d.ts"
+      "types": "./out/ancestry-backfill.d.ts",
+      "default": "./out/ancestry-backfill.js"
     },
     "./coincident-roles": {
-      "node": "./coincident-roles.ts",
-      "default": "./out/coincident-roles.js",
-      "types": "./out/coincident-roles.d.ts"
+      "types": "./out/coincident-roles.d.ts",
+      "default": "./out/coincident-roles.js"
     },
     "./geonames-aliases": {
-      "node": "./geonames-aliases.ts",
-      "default": "./out/geonames-aliases.js",
-      "types": "./out/geonames-aliases.d.ts"
+      "types": "./out/geonames-aliases.d.ts",
+      "default": "./out/geonames-aliases.js"
     },
     "./geonames-postal": {
-      "node": "./geonames-postal.ts",
-      "default": "./out/geonames-postal.js",
-      "types": "./out/geonames-postal.d.ts"
+      "types": "./out/geonames-postal.d.ts",
+      "default": "./out/geonames-postal.js"
     },
     "./geo": {
-      "node": "./geo.ts",
-      "default": "./out/geo.js",
-      "types": "./out/geo.d.ts"
+      "types": "./out/geo.d.ts",
+      "default": "./out/geo.js"
     },
     "./street-normalize": {
-      "node": "./street-normalize.ts",
-      "default": "./out/street-normalize.js",
-      "types": "./out/street-normalize.d.ts"
+      "types": "./out/street-normalize.d.ts",
+      "default": "./out/street-normalize.js"
     },
     "./build-candidate": {
-      "node": "./build-candidate.ts",
-      "default": "./out/build-candidate.js",
-      "types": "./out/build-candidate.d.ts"
+      "types": "./out/build-candidate.d.ts",
+      "default": "./out/build-candidate.js"
     },
     "./candidate-schema": {
-      "node": "./candidate-schema.ts",
-      "default": "./out/candidate-schema.js",
-      "types": "./out/candidate-schema.d.ts"
+      "types": "./out/candidate-schema.d.ts",
+      "default": "./out/candidate-schema.js"
     },
     "./postal-city-alias-schema": {
-      "node": "./postal-city-alias-schema.ts",
-      "default": "./out/postal-city-alias-schema.js",
-      "types": "./out/postal-city-alias-schema.d.ts"
+      "types": "./out/postal-city-alias-schema.d.ts",
+      "default": "./out/postal-city-alias-schema.js"
     },
     "./address-point-schema": {
-      "node": "./address-point-schema.ts",
-      "default": "./out/address-point-schema.js",
-      "types": "./out/address-point-schema.d.ts"
+      "types": "./out/address-point-schema.d.ts",
+      "default": "./out/address-point-schema.js"
     },
     "./street-centroid-schema": {
-      "node": "./street-centroid-schema.ts",
-      "default": "./out/street-centroid-schema.js",
-      "types": "./out/street-centroid-schema.d.ts"
+      "types": "./out/street-centroid-schema.d.ts",
+      "default": "./out/street-centroid-schema.js"
     },
     "./street-segment-schema": {
-      "node": "./street-segment-schema.ts",
-      "default": "./out/street-segment-schema.js",
-      "types": "./out/street-segment-schema.d.ts"
+      "types": "./out/street-segment-schema.d.ts",
+      "default": "./out/street-segment-schema.js"
     },
     "./poi-schema": {
-      "node": "./poi-schema.ts",
-      "default": "./out/poi-schema.js",
-      "types": "./out/poi-schema.d.ts"
+      "types": "./out/poi-schema.d.ts",
+      "default": "./out/poi-schema.js"
     },
     "./poi-lookup": {
-      "node": "./poi-lookup.ts",
-      "default": "./out/poi-lookup.js",
-      "types": "./out/poi-lookup.d.ts"
+      "types": "./out/poi-lookup.d.ts",
+      "default": "./out/poi-lookup.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      },
+      "./fts": {
+        "types": "./out/fts.d.ts",
+        "default": "./out/fts.js"
+      },
+      "./build-slim": {
+        "types": "./out/build-slim.d.ts",
+        "default": "./out/build-slim.js"
+      },
+      "./fst-builder": {
+        "types": "./out/fst-builder.d.ts",
+        "default": "./out/fst-builder.js"
+      },
+      "./street-morphology-fst-builder": {
+        "types": "./out/street-morphology-fst-builder.d.ts",
+        "default": "./out/street-morphology-fst-builder.js"
+      },
+      "./fst-matcher": {
+        "types": "./out/fst-matcher.d.ts",
+        "default": "./out/fst-matcher.js"
+      },
+      "./fst-serialize": {
+        "types": "./out/fst-serialize.d.ts",
+        "default": "./out/fst-serialize.js"
+      },
+      "./fst-autocomplete": {
+        "types": "./out/fst-autocomplete.d.ts",
+        "default": "./out/fst-autocomplete.js"
+      },
+      "./fst-types": {
+        "types": "./out/fst-types.d.ts",
+        "default": "./out/fst-types.js"
+      },
+      "./fst-deserialize-web": {
+        "types": "./out/fst-deserialize-web.d.ts",
+        "default": "./out/fst-deserialize-web.js"
+      },
+      "./unified-schema": {
+        "types": "./out/unified-schema.d.ts",
+        "default": "./out/unified-schema.js"
+      },
+      "./ancestry-backfill": {
+        "types": "./out/ancestry-backfill.d.ts",
+        "default": "./out/ancestry-backfill.js"
+      },
+      "./coincident-roles": {
+        "types": "./out/coincident-roles.d.ts",
+        "default": "./out/coincident-roles.js"
+      },
+      "./geonames-aliases": {
+        "types": "./out/geonames-aliases.d.ts",
+        "default": "./out/geonames-aliases.js"
+      },
+      "./geonames-postal": {
+        "types": "./out/geonames-postal.d.ts",
+        "default": "./out/geonames-postal.js"
+      },
+      "./geo": {
+        "types": "./out/geo.d.ts",
+        "default": "./out/geo.js"
+      },
+      "./street-normalize": {
+        "types": "./out/street-normalize.d.ts",
+        "default": "./out/street-normalize.js"
+      },
+      "./build-candidate": {
+        "types": "./out/build-candidate.d.ts",
+        "default": "./out/build-candidate.js"
+      },
+      "./candidate-schema": {
+        "types": "./out/candidate-schema.d.ts",
+        "default": "./out/candidate-schema.js"
+      },
+      "./postal-city-alias-schema": {
+        "types": "./out/postal-city-alias-schema.d.ts",
+        "default": "./out/postal-city-alias-schema.js"
+      },
+      "./address-point-schema": {
+        "types": "./out/address-point-schema.d.ts",
+        "default": "./out/address-point-schema.js"
+      },
+      "./street-centroid-schema": {
+        "types": "./out/street-centroid-schema.d.ts",
+        "default": "./out/street-centroid-schema.js"
+      },
+      "./street-segment-schema": {
+        "types": "./out/street-segment-schema.d.ts",
+        "default": "./out/street-segment-schema.js"
+      },
+      "./poi-schema": {
+        "types": "./out/poi-schema.d.ts",
+        "default": "./out/poi-schema.js"
+      },
+      "./poi-lookup": {
+        "types": "./out/poi-lookup.d.ts",
+        "default": "./out/poi-lookup.js"
+      }
+    }
   },
   "dependencies": {
-    "@mailwoman/codex": "7.2.0",
-    "@mailwoman/core": "7.2.0",
-    "@mailwoman/resolver": "7.2.0",
-    "@mailwoman/spatial": "7.2.0",
+    "@mailwoman/codex": "7.2.1",
+    "@mailwoman/core": "7.2.1",
+    "@mailwoman/resolver": "7.2.1",
+    "@mailwoman/spatial": "7.2.1",
     "h3-js": "^4.5.0",
     "kysely": "^0.29.3"
   }

package/poi-lookup.ts

@@ -0,0 +1,319 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node reader for `poi.db` (spec §3.4) — the res-9 k-ring reader over the clustered `poi`
+ *   `WITHOUT ROWID` B-tree Task 1's schema (`poi-schema.ts`) builds. Three search modes share one
+ *   artifact:
+ *
+ *   - **Category**: `latLngToCell(center, 9)` → `gridDisk` ring-by-ring expansion, probing each
+ *     cell's clustered `(h3_cell, category_id, neg_rank, …)` range. Rings accumulate until `limit`
+ *     rows are on hand after a completed ring, or `maxRings` is exhausted; the pool is sorted by
+ *     haversine distance from `center` after every ring.
+ *   - **Brand**: the same k-ring walk, but probing on `brand_wikidata` instead — category
+ *     unconstrained, so a chain's rows surface regardless of how they were categorized.
+ *   - **Name**: FTS5 `MATCH` against the `poi_search` virtual table, hydrated back to full rows by
+ *     `name_key`. No center required; if one is given, hits are still distance-sorted.
+ *
+ *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing that turns a raw H3
+ *   cell into the integer `poi.h3_cell` stores is `@mailwoman/spatial`'s `shortenH3Cell` — that math
+ *   is NEVER reimplemented here (see AGENTS.md on `@mailwoman/spatial` being the one true home for
+ *   it).
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { haversineKm, shortenH3Cell, type H3Cell } from "@mailwoman/spatial"
+import { gridDisk, latLngToCell } from "h3-js"
+
+import type { POICategoryCodeTable, POITable } from "./poi-schema.ts"
+
+/** Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4). */
+export const POI_H3_RESOLUTION = 9
+
+/** Ring budget default: 12 res-9 k-rings ≈ ~4 km. */
+const DEFAULT_MAX_RINGS = 12
+
+/** Row-count default when a query doesn't specify `limit`. */
+const DEFAULT_LIMIT = 20
+
+export interface POISearchQuery {
+	/** Poi-taxonomy category id (string side of the dictionary). Ignored when `brandWikidata` is also set — brand wins. */
+	categoryID?: string
+	/** Wikidata QID for brand-exact search. */
+	brandWikidata?: string
+	/** Free-text name (FTS5). */
+	name?: string
+	/** Search center. Required for category/brand queries (k-ring expansion). */
+	center?: { latitude: number; longitude: number }
+	/**
+	 * Ring budget: how many res-9 k-rings to expand before giving up (default 12 ≈ ~4 km). Counts ring 0, so k reaches
+	 * `maxRings - 1`.
+	 */
+	maxRings?: number
+	limit?: number
+}
+
+export interface POISearchHit {
+	name: string | null
+	categoryID: string | null
+	brandWikidata: string | null
+	latitude: number
+	longitude: number
+	country: string
+	confidence: number
+	distanceM?: number
+}
+
+export interface POILookupOpts {
+	/** Path to a `poi.db` built by the (future) POI builder. Opened read-only. */
+	databasePath?: string
+	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	database?: DatabaseSync
+}
+
+/** The `poi` columns every search mode hydrates — a typed projection of the SHARED {@link POITable}. */
+type POIRow = Pick<
+	POITable,
+	"name" | "category_id" | "brand_wikidata" | "latitude" | "longitude" | "country" | "confidence" | "name_key"
+>
+
+/**
+ * Node reader over `poi.db`. `implements Disposable` so callers can `using lookup = new POILookup(...)` (or call
+ * `[Symbol.dispose]()` explicitly), the same precedent as {@link WOFCandidateTableLookup} /
+ * {@link WOFSqlitePlaceLookup}.
+ */
+export class POILookup implements Disposable {
+	#db: DatabaseSync
+	#ownsDB: boolean
+	readonly #categoryToID = new Map<string, number>()
+	readonly #idToCategory = new Map<number, string>()
+
+	/** `(h3_cell, category_id)` → the cell's category-clustered range, most-confident-first. */
+	readonly #categoryCellProbe: ReturnType<DatabaseSync["prepare"]>
+	/** `(h3_cell, brand_wikidata)` → the cell's brand-matched rows (category unconstrained). */
+	readonly #brandCellProbe: ReturnType<DatabaseSync["prepare"]>
+	/** FTS5 `MATCH` over `poi_search`, returning candidate `name_key`s to hydrate. */
+	readonly #nameFTSProbe: ReturnType<DatabaseSync["prepare"]>
+
+	constructor(opts: POILookupOpts) {
+		if (opts.database) {
+			this.#db = opts.database
+			this.#ownsDB = false
+		} else if (opts.databasePath) {
+			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
+			this.#ownsDB = true
+		} else {
+			throw new Error("POILookup needs `databasePath` or `database`")
+		}
+
+		// The category dictionary is tiny (poi-taxonomy's category count) — load it once at
+		// construction so `search` never round-trips to it.
+		for (const r of this.#db
+			.prepare("SELECT id, category FROM poi_category_codes")
+			.all() as unknown as POICategoryCodeTable[]) {
+			this.#categoryToID.set(String(r.category), Number(r.id))
+			this.#idToCategory.set(Number(r.id), String(r.category))
+		}
+
+		const columns = "name, category_id, brand_wikidata, latitude, longitude, country, confidence, name_key"
+
+		this.#categoryCellProbe = this.#db.prepare(
+			`SELECT ${columns} FROM poi WHERE h3_cell = ? AND category_id = ? ORDER BY neg_rank ASC LIMIT ?`
+		)
+		this.#brandCellProbe = this.#db.prepare(
+			`SELECT ${columns} FROM poi WHERE h3_cell = ? AND brand_wikidata = ? ORDER BY neg_rank ASC LIMIT ?`
+		)
+		this.#nameFTSProbe = this.#db.prepare(
+			"SELECT name_key FROM poi_search WHERE poi_search MATCH ? ORDER BY bm25(poi_search) LIMIT ?"
+		)
+	}
+
+	search(query: POISearchQuery): POISearchHit[] {
+		const limit = Math.max(1, query.limit ?? DEFAULT_LIMIT)
+
+		if (query.name) {
+			return this.#searchByName(query.name, limit, query.center)
+		}
+
+		if (query.categoryID || query.brandWikidata) {
+			if (!query.center) {
+				throw new Error("POILookup.search: category/brand search requires a `center`")
+			}
+
+			return this.#searchKRing(query, limit)
+		}
+
+		return []
+	}
+
+	/** Category or brand path: k-ring expansion from `query.center`'s res-9 cell, probing each new ring's cells. */
+	#searchKRing(query: POISearchQuery, limit: number): POISearchHit[] {
+		const center = query.center!
+		const maxRings = query.maxRings ?? DEFAULT_MAX_RINGS
+		let categoryId: number | undefined
+
+		// brandWikidata wins over categoryID when both are set — see POISearchQuery.categoryID.
+		if (!query.brandWikidata) {
+			categoryId = this.#categoryToID.get(query.categoryID!)
+
+			// An unknown category (not in the dictionary) can't have rows — a clean miss, not a throw.
+			if (categoryId === undefined) return []
+		}
+
+		const origin = latLngToCell(center.latitude, center.longitude, POI_H3_RESOLUTION) as H3Cell
+		const seenCells = new Set<string>()
+		let rows: POIRow[] = []
+
+		// `ring` starts at 0 (the origin cell itself), so this loop's k reaches `maxRings - 1`.
+		for (let ring = 0; ring < maxRings; ring++) {
+			// gridDisk(origin, ring) returns the WHOLE disk out to `ring`; diffing against what's
+			// already been probed derives just this ring's new cells.
+			const diskCells = gridDisk(origin, ring) as string[]
+			const newCells = diskCells.filter((cell) => !seenCells.has(cell))
+
+			for (const cell of newCells) {
+				seenCells.add(cell)
+				const shortCell = h3CellToInt(cell as H3Cell)
+
+				const hits = query.brandWikidata
+					? (this.#brandCellProbe.all(shortCell, query.brandWikidata, limit) as unknown as POIRow[])
+					: (this.#categoryCellProbe.all(shortCell, categoryId!, limit) as unknown as POIRow[])
+
+				rows.push(...hits)
+			}
+
+			rows = sortByDistance(rows, center)
+
+			if (rows.length >= limit) break
+		}
+
+		return rows.slice(0, limit).map((row) => toHit(row, this.#idToCategory, center))
+	}
+
+	/**
+	 * Name path: FTS5 MATCH → hydrate by name_key. No center required; distance-sorts if one is given anyway.
+	 *
+	 * Hydration is ONE batched `WHERE name_key IN (...)` query over the FTS hits' unique `name_key`s, not a per-hit probe
+	 * — with up to `limit` FTS hits, a per-hit probe was up to `limit` full table scans before `createPOINameKeyIndex`
+	 * (poi-schema.ts) + this batching.
+	 */
+	#searchByName(name: string, limit: number, center?: { latitude: number; longitude: number }): POISearchHit[] {
+		const matchQuery = sanitizePOINameQuery(name)
+
+		if (!matchQuery) return []
+
+		const ftsHits = this.#nameFTSProbe.all(matchQuery, limit) as unknown as Array<{ name_key: string | null }>
+		const uniqueKeys: string[] = []
+		const seenKeys = new Set<string>()
+
+		for (const hit of ftsHits) {
+			if (!hit.name_key || seenKeys.has(hit.name_key)) continue
+			seenKeys.add(hit.name_key)
+			uniqueKeys.push(hit.name_key)
+		}
+
+		if (uniqueKeys.length === 0) return []
+
+		const hydrated = this.#hydrateByNameKeys(uniqueKeys)
+		const rowsByKey = new Map<string, POIRow[]>()
+
+		for (const row of hydrated) {
+			if (row.name_key === null) continue
+			const bucket = rowsByKey.get(row.name_key)
+
+			if (bucket) {
+				bucket.push(row)
+			} else {
+				rowsByKey.set(row.name_key, [row])
+			}
+		}
+
+		let rows: POIRow[] = []
+
+		for (const key of uniqueKeys) {
+			rows.push(...(rowsByKey.get(key) ?? []))
+		}
+
+		if (center) {
+			rows = sortByDistance(rows, center)
+		}
+
+		return rows.slice(0, limit).map((row) => toHit(row, this.#idToCategory, center))
+	}
+
+	/**
+	 * Batched hydration for the FTS name path: `WHERE name_key IN (?, ?, …)`, one query for the whole batch instead of
+	 * one probe per FTS hit. This is a cold path (name search only) with variable arity per call, so the statement is
+	 * prepared fresh each time rather than cached.
+	 */
+	#hydrateByNameKeys(nameKeys: string[]): POIRow[] {
+		const columns = "name, category_id, brand_wikidata, latitude, longitude, country, confidence, name_key"
+		const placeholders = nameKeys.map(() => "?").join(", ")
+		const stmt = this.#db.prepare(`SELECT ${columns} FROM poi WHERE name_key IN (${placeholders})`)
+
+		return stmt.all(...nameKeys) as unknown as POIRow[]
+	}
+
+	close(): void {
+		if (this.#ownsDB) {
+			this.#db.close()
+		}
+	}
+
+	[Symbol.dispose](): void {
+		this.close()
+	}
+}
+
+/** `poi.h3_cell` is the SHORTENED (48-bit) cell — never the full h3-js cell string. */
+function h3CellToInt(cell: H3Cell): number {
+	return Number(BigInt(`0x${shortenH3Cell(cell)}`))
+}
+
+function sortByDistance(rows: POIRow[], center: { latitude: number; longitude: number }): POIRow[] {
+	return [...rows].sort(
+		(a, b) =>
+			haversineKm(center.latitude, center.longitude, a.latitude, a.longitude) -
+			haversineKm(center.latitude, center.longitude, b.latitude, b.longitude)
+	)
+}
+
+function toHit(
+	row: POIRow,
+	idToCategory: ReadonlyMap<number, string>,
+	center?: { latitude: number; longitude: number }
+): POISearchHit {
+	return {
+		name: row.name,
+		categoryID: row.category_id !== 0 ? (idToCategory.get(row.category_id) ?? null) : null,
+		brandWikidata: row.brand_wikidata,
+		latitude: row.latitude,
+		longitude: row.longitude,
+		country: row.country,
+		confidence: row.confidence,
+		...(center
+			? { distanceM: haversineKm(center.latitude, center.longitude, row.latitude, row.longitude) * 1000 }
+			: {}),
+	}
+}
+
+/**
+ * Sanitize free text into an FTS5-safe MATCH query: strip the characters FTS5 would otherwise read as syntax (`"`
+ * phrase delimiters, `*` prefix wildcards, `:` column-filter separators), then phrase-quote each whitespace-separated
+ * token (AND-joined).
+ *
+ * `resolver-wof-sqlite` already has this discipline — `lookup.ts`'s `sanitizeFTSQuery` — but that function is
+ * module-private there (not re-exported from `fts.ts` or the package's `index.ts`), so this replicates the same
+ * discipline locally rather than reaching across the module boundary for a private helper.
+ */
+function sanitizePOINameQuery(text: string): string {
+	return text
+		.replace(/["*:]/g, "")
+		.trim()
+		.split(/\s+/u)
+		.filter(Boolean)
+		.map((token) => `"${token.replace(/"/g, '""')}"`)
+		.join(" ")
+}