@mailwoman/resolver-wof-sqlite 7.2.0 → 7.3.0

package/street-normalize.ts

@@ -0,0 +1,302 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   THE street normalizer for the address-point tier (#476). One function, used by BOTH the shard
+ *   builder (`scripts/build-address-point-shard.ts`) and the lookup tier (`address-point.ts`) —
+ *   never two implementations (the PLACETYPE_ORDER lesson: parallel copies silently corrupt).
+ *
+ *   Normalization contract (deliberately aggressive — both sides apply the same function, so
+ *   collisions only need to be _consistent_, not linguistically perfect):
+ *
+ *   1. Lowercase, NFKD-fold diacritics, collapse whitespace, strip punctuation (periods, commas,
+ *        apostrophes).
+ *   2. Expand USPS directional abbreviations at the FIRST and LAST token position (`n` → `north`, `se` →
+ *        `southeast`) — Overture sources abbreviate inconsistently.
+ *   3. Canonicalize a trailing USPS street-type token via the codex suffix table to its canonical full
+ *        form (`st`/`str`/`street` → `street`).
+ *
+ *   Numbered streets are left as digits (`5th` stays `5th`); a SPELLED ordinal before a street suffix
+ *   folds to its digit form (`tenth street` → `10th street`, #723) so the grid-city ordinal
+ *   cross-streets the source data spells with digits become reachable.
+ */
+
+import { AbbreviationToDirectional, US_STREET_SUFFIX_LOOKUP } from "@mailwoman/codex/us"
+
+/**
+ * Spelled ordinal street names → their digit-ordinal form ("tenth" → "10th"), applied ONLY when a street-type suffix
+ * follows (#723 admin-tail) — so the ordinal cross-streets common in grid cities ("Tenth Street", "Fifth Avenue") match
+ * the shards' digit keys, WITHOUT rewriting ordinal-WORD names where the next token is not a suffix ("First National
+ * Bank Rd" stays "first national …"). Digit-source shards are unaffected (a digit token isn't in this map), so the
+ * existing keys need no rebuild; a future rebuild folds any spelled-source key the same way (the one-function
+ * discipline).
+ */
+const SPELLED_ORDINAL_TO_DIGIT = new Map<string, string>([
+	["first", "1st"],
+	["second", "2nd"],
+	["third", "3rd"],
+	["fourth", "4th"],
+	["fifth", "5th"],
+	["sixth", "6th"],
+	["seventh", "7th"],
+	["eighth", "8th"],
+	["ninth", "9th"],
+	["tenth", "10th"],
+	["eleventh", "11th"],
+	["twelfth", "12th"],
+	["thirteenth", "13th"],
+	["fourteenth", "14th"],
+	["fifteenth", "15th"],
+	["sixteenth", "16th"],
+	["seventeenth", "17th"],
+	["eighteenth", "18th"],
+	["nineteenth", "19th"],
+	["twentieth", "20th"],
+	["thirtieth", "30th"],
+	["fortieth", "40th"],
+	["fiftieth", "50th"],
+	["sixtieth", "60th"],
+	["seventieth", "70th"],
+	["eightieth", "80th"],
+	["ninetieth", "90th"],
+	["hundredth", "100th"],
+])
+
+/** Lowercase + diacritic-fold + punctuation strip + whitespace collapse. */
+function fold(input: string): string {
+	return input
+		.normalize("NFKD")
+		.replace(/[̀-ͯ]/g, "")
+		.toLowerCase()
+		.replace(/[.,'’]/g, "")
+		.replace(/\s+/g, " ")
+		.trim()
+}
+
+/**
+ * Normalize a street name for address-point keying. Same function at build time and lookup time — see module docstring
+ * for the contract.
+ */
+export function normalizeStreetForKey(street: string): string {
+	const tokens = fold(street).split(" ")
+
+	if (tokens.length === 0) return ""
+
+	// Spelled-ordinal street names → digit form when a street suffix follows ("Tenth Street" →
+	// "10th street", #723). Gated on the next token being a suffix so ordinal-WORD names are untouched.
+	for (let i = 0; i < tokens.length - 1; i++) {
+		const digit = SPELLED_ORDINAL_TO_DIGIT.get(tokens[i]!)
+
+		if (digit && US_STREET_SUFFIX_LOOKUP.has(tokens[i + 1]!)) {
+			tokens[i] = digit
+		}
+	}
+
+	// Directional expansion at the edges only ("N Main St" / "Main St N" — never interior
+	// tokens, where "W" may be an initial in a person-named street). The codex expands
+	// compounds to two words ("SE" → "SOUTH EAST"); we key on the spaceless form
+	// ("southeast"), and also merge an already-written two-token pair ("South East …").
+	const edgeDirectional = (raw: string) =>
+		AbbreviationToDirectional.get(raw.toUpperCase())?.toLowerCase().replace(" ", "")
+	const mergePair = (a?: string, b?: string) =>
+		a && b && /^(north|south)$/.test(a) && /^(east|west)$/.test(b) ? a + b : undefined
+
+	const leadPair = mergePair(tokens[0], tokens[1])
+
+	if (leadPair && tokens.length > 2) {
+		tokens.splice(0, 2, leadPair)
+	}
+	const first = edgeDirectional(tokens[0]!)
+
+	if (first && tokens.length > 1) {
+		tokens[0] = first
+	}
+
+	const tailPair = mergePair(tokens[tokens.length - 2], tokens[tokens.length - 1])
+
+	if (tailPair && tokens.length > 3) {
+		tokens.splice(tokens.length - 2, 2, tailPair)
+	}
+
+	if (tokens.length > 2) {
+		const last = edgeDirectional(tokens[tokens.length - 1]!)
+
+		if (last) {
+			tokens[tokens.length - 1] = last
+		}
+	}
+
+	// Street-type canonicalization via the codex table (lowercase keys, UPPER canonical
+	// values). The suffix is usually the last token, but sits second-to-last when a trailing
+	// directional follows ("Main St N") — check both positions, canonicalize the first hit.
+	for (const at of [tokens.length - 1, tokens.length - 2]) {
+		if (at < 1) continue // never canonicalize the only/first token ("Street Road" exists)
+		const canonical = US_STREET_SUFFIX_LOOKUP.get(tokens[at]!)
+
+		if (canonical) {
+			tokens[at] = canonical.toLowerCase()
+			break
+		}
+	}
+
+	return tokens.join(" ")
+}
+
+/**
+ * Street-name locale for the address-point key. The US path is the full USPS pipeline ({@link normalizeStreetForKey});
+ * the international paths fold + apply a SMALL, consistent per-locale type-token canonicalization. Same discipline as
+ * the US normalizer: build side and probe side call the identical function, so the key only needs to be CONSISTENT, not
+ * linguistically perfect — a folded "rue du chevaleret" keys the same on both sides whether or not we reorder the
+ * article, so no salient-token / multi-key index is built yet (deferred until probing shows the normalizer can't absorb
+ * the false-negatives).
+ */
+export type StreetLocale = "us" | "fr" | "de" | "nl"
+
+/**
+ * French street-type abbreviations → canonical full form, applied per token after {@link fold}. French address types
+ * LEAD the name ("Av. de…", "Bd …", "Pl. …") and "St"/"Ste" abbreviate Saint/Sainte inside names ("Rue St-Honoré" →
+ * "rue saint honore"). fold() has already stripped the trailing period, so the keys are point-free ("av", "bd").
+ */
+const FR_STREET_ABBREV = new Map<string, string>([
+	["av", "avenue"],
+	["ave", "avenue"],
+	["bd", "boulevard"],
+	["bld", "boulevard"],
+	["bvd", "boulevard"],
+	["boul", "boulevard"],
+	["pl", "place"],
+	["imp", "impasse"],
+	["all", "allee"],
+	["ch", "chemin"],
+	["che", "chemin"],
+	["sq", "square"],
+	["pas", "passage"],
+	["fg", "faubourg"],
+	["fbg", "faubourg"],
+	["rte", "route"],
+	["st", "saint"],
+	["ste", "sainte"],
+	["sts", "saints"],
+])
+
+/**
+ * Normalize a street name for the address-point key in a non-US locale. Same function build-side and probe-side (the
+ * one-function discipline). US delegates to {@link normalizeStreetForKey}.
+ *
+ * - **fr** — fold + expand leading type abbreviations and Saint/Sainte (token map).
+ * - **de** — fold + ß→ss + canonicalize the GLUED `-str(.)` suffix to `-strasse` ("Lindenstr." → "lindenstrasse",
+ *   "Lindenstraße" → "lindenstrasse"); an already-full "-strasse" is left intact.
+ * - **nl** — fold + canonicalize the glued `-str` suffix to `-straat` ("Kerkstr." → "kerkstraat").
+ */
+export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale): string {
+	if (locale === "us") return normalizeStreetForKey(street)
+
+	// Hyphen → space so a compound name keys the same whether the source or the query writes the
+	// hyphen ("Champs-Élysées", "St-Honoré") or a space — both sides fold identically, so this is pure
+	// robustness. It also splits a hyphenated abbreviation ("St-Honoré" → "st honore") into tokens the
+	// per-locale type/Saint map can see.
+	const tokens = fold(street).replace(/ß/g, "ss").replace(/-/g, " ").split(/\s+/).filter(Boolean)
+
+	if (tokens.length === 0) return ""
+
+	switch (locale) {
+		case "fr":
+			for (let i = 0; i < tokens.length; i++) {
+				tokens[i] = FR_STREET_ABBREV.get(tokens[i]!) ?? tokens[i]!
+			}
+			break
+		case "de":
+			for (let i = 0; i < tokens.length; i++) {
+				const t = tokens[i]!
+
+				if (t.endsWith("str") && !t.endsWith("strasse")) {
+					tokens[i] = t.replace(/str$/, "strasse")
+				}
+			}
+			break
+		case "nl":
+			for (let i = 0; i < tokens.length; i++) {
+				const t = tokens[i]!
+
+				if (t.endsWith("str") && !t.endsWith("straat")) {
+					tokens[i] = t.replace(/str$/, "straat")
+				}
+			}
+			break
+	}
+
+	return tokens.join(" ")
+}
+
+/** Normalize a locality name for address-point keying (fold only — no street semantics). */
+export function normalizeLocalityForKey(locality: string): string {
+	return fold(locality)
+}
+
+/**
+ * Strip a trailing French arrondissement designator from a FOLDED commune key ("paris 8e arrondissement" → "paris",
+ * "lyon 1er arrondissement" → "lyon", "marseille 10e arrondissement" → "marseille"). Paris, Lyon and Marseille are the
+ * only French communes subdivided into _arrondissements municipaux_; a national register (BAN) names each row per
+ * arrondissement, but a query names the base commune ("Place Bellecour, Lyon", never "…, Lyon 2e"). Applied on BOTH
+ * sides of the #1042 street-centroid key — build-side (deriving the `locality_base` column) and query-side (folding the
+ * probe commune) — so the two agree by construction (the one-function discipline). Input must already be folded
+ * (lower-case, diacritic-stripped); a no-op for every other commune. Returns the input unchanged if the strip would
+ * empty it.
+ */
+export function stripArrondissement(localityNorm: string): string {
+	const stripped = localityNorm.replace(/\s+\d+(?:er|e)\s+arrondissement$/, "").trim()
+
+	return stripped || localityNorm
+}
+
+/**
+ * Strip a locality QUALIFIER for a query-side fallback — when an OA locality's exact normalized name misses the
+ * gazetteer's canonical name, retry with the qualifier removed. OA address data carries disambiguating qualifiers the
+ * gazetteer's canonical name omits: Austrian `Kraubath/Mur` and `Hart b.Graz` → `Hart`; Swiss `Lenk im Simmental` →
+ * `Lenk`, `Roche VD` → `Roche`; Danish `Odense S`, `Hurup Thy`. A FALLBACK ONLY — the exact name is tried first, and
+ * the region-bbox disambiguation resolves any base-name ambiguity downstream. The candidate table is unchanged (this is
+ * purely query-side); feed the result back through {@link normalizeLocalityForKey}. Returns "" when nothing was stripped
+ * (no point re-probing the identical key).
+ *
+ * Measured (`scripts/eval/candidate-recall.ts --strip-fallback`, EU OA holdouts): recovers AT 74.1→88.2% (+14.1pp), DK
+ * 91.5→96.2%, CH 90.4→92.6%; +1.3pp overall (diluted by the already-100% locales). Conservative by design — only the
+ * qualifier forms above; FI/PT/SI misses are untouched.
+ */
+export function stripLocalityQualifier(locality: string): string {
+	let s = locality.trim()
+
+	if (s.includes("/")) {
+		s = s.split("/")[0]!.trim()
+	} // "Kraubath/Mur", "St.Kanzian/Klopeiner See"
+	s = s.replace(/\s+[a-zà-ÿ]\.\s*\S.*$/iu, "") // abbreviated " b.Graz" / " o.Bleiburg" / " a.d. …"
+	s = s.replace(/\s+(im|an der|ob|bei|in der|unter|vor)\s+\S.*$/iu, "") // " im Simmental", " bei Graz"
+	s = s.replace(/\s+(S|N|E|W|V|Ø|Sø|Fyn|Thy|Sjælland|Jylland|[A-ZÅÄÖ]{2})$/u, "") // " S", " VD", " Thy"
+	s = s.trim()
+
+	return s === locality.trim() ? "" : s
+}
+
+/**
+ * Fold numbered-route designators to a canonical key, applied AFTER {@link normalizeStreetForKey}. Sources disagree
+ * systematically on how they spell a route: TIGER says `State Rte 100` / `US Hwy 5` where E911/Overture say `VT ROUTE
+ * 100` / `US ROUTE 5` — the dominant street-name miss class in the #483 interpolation eval (rural addresses live on
+ * routes). `us <designator> N…` folds to `us route N…`; `state <designator> N…` and `<2-letter-prefix> <designator> N…`
+ * (the state abbreviation form) fold to `state route N…`. Only digit-leading route numbers fold — `State Street` and
+ * friends never match.
+ *
+ * Used by BOTH the segment-shard builder (`scripts/build-interpolation-shard.ts`) and the interpolation lookup — same
+ * one-function discipline as {@link normalizeStreetForKey}. The address-point tier (#476) does NOT apply it yet:
+ * adopting it there requires a shard rebuild (noted on #483).
+ *
+ * A same-numbered US and state route stay DISTINCT keys (`us route 5` vs `state route 5`); only the BARE `route N` form
+ * is ambiguous (designator unknown) and it stays unfolded — a bare-route query therefore misses rather than guessing a
+ * designator.
+ */
+export function canonicalizeRouteKey(streetNorm: string): string {
+	const match = /^(us|state|[a-z]{2}) (?:route|rte|rt|highway|hwy) (\d.*)$/.exec(streetNorm)
+
+	if (!match) return streetNorm
+
+	return `${match[1] === "us" ? "us" : "state"} route ${match[2]}`
+}

package/street-segment-schema.ts

@@ -0,0 +1,104 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the TIGER STREET-SEGMENT interpolation shards (`street-segments-<cc>-<st>.db`,
+ *   built by `scripts/build-interpolation-shard.ts` from TIGER EDGES) — the #483 Method-3 fallback
+ *   the resolver drops to when the address-point tier (Method 2) can't bracket. Single source of
+ *   truth for the columns the BUILDER writes and the READER ({@link StreetInterpolator}) probes, so
+ *   a column rename in one is a compile error in the other.
+ *
+ *   The builder reads geometry from shapefiles via DuckDB's spatial extension (raw `ST_Read` — see
+ *   AGENTS.md "Database / inline SQL") and writes here through `node:sqlite`. The hot positional
+ *   INSERT (a county's worth of edges) stays raw; its column list is derived from
+ *   {@link STREET_SEGMENT_COLUMNS} so it can't drift from the DDL.
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * One TIGER street-segment edge: a `(from_hn, to_hn)` house-number range on one `side` of a named street, with the
+ * geometry the interpolator walks. `min_hn`/`max_hn` are the sorted bounds (the probe filters on them); `parity` is
+ * `odd`/`even`/`mixed`.
+ */
+export interface StreetSegmentTable {
+	/** Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key. */
+	street_norm: string
+	/** `L` or `R` — the TIGER side the address range sits on. */
+	side: string
+	from_hn: number
+	to_hn: number
+	/** Sorted lower bound of `(from_hn, to_hn)` — the probe filters `min_hn <= n <= max_hn`. */
+	min_hn: number
+	/** Sorted upper bound of `(from_hn, to_hn)`. */
+	max_hn: number
+	/** `odd` | `even` | `mixed` — the house-number parity along the range. */
+	parity: string
+	postcode: string | null
+	/** 5-digit state+county FIPS the edge came from. */
+	county_fips: string
+	/** The street as it appeared in TIGER (kept for display / debugging). */
+	street_raw: string
+	/** GeoJSON LineString text (no SpatiaLite — read back with `JSON.parse`). */
+	geometry: string
+	/** Provenance: the dataset this edge came from (e.g. `tiger:edges`). */
+	source: string
+	/** The pinned TIGER release the edge was ingested from. */
+	release: string
+}
+
+/** The street-segment database schema for `new DatabaseClient<StreetSegmentDatabase>(...)`. */
+export interface StreetSegmentDatabase {
+	street_segment: StreetSegmentTable
+}
+
+/**
+ * The `street_segment` columns in INSERT order. The builder's positional prepared statement derives its placeholder
+ * list from this, so the positional order can't drift from the DDL / the reader.
+ */
+export const STREET_SEGMENT_COLUMNS = [
+	"street_norm",
+	"side",
+	"from_hn",
+	"to_hn",
+	"min_hn",
+	"max_hn",
+	"parity",
+	"postcode",
+	"county_fips",
+	"street_raw",
+	"geometry",
+	"source",
+	"release",
+] as const
+
+/** Create the `street_segment` table — called before the streaming bulk load. */
+export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>): Promise<void> {
+	await db.schema
+		.createTable("street_segment")
+		.addColumn("street_norm", "text", (c) => c.notNull())
+		.addColumn("side", "text", (c) => c.notNull())
+		.addColumn("from_hn", "integer", (c) => c.notNull())
+		.addColumn("to_hn", "integer", (c) => c.notNull())
+		.addColumn("min_hn", "integer", (c) => c.notNull())
+		.addColumn("max_hn", "integer", (c) => c.notNull())
+		.addColumn("parity", "text", (c) => c.notNull())
+		.addColumn("postcode", "text")
+		.addColumn("county_fips", "text", (c) => c.notNull())
+		.addColumn("street_raw", "text", (c) => c.notNull())
+		.addColumn("geometry", "text", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.addColumn("release", "text", (c) => c.notNull())
+		.execute()
+}
+
+/** Create the two probe indexes the reader relies on (postcode-scope, street-scope). */
+export async function createStreetSegmentIndexes(db: Kysely<StreetSegmentDatabase>): Promise<void> {
+	await db.schema
+		.createIndex("idx_seg_postcode")
+		.on("street_segment")
+		.columns(["postcode", "street_norm", "min_hn"])
+		.execute()
+	await db.schema.createIndex("idx_seg_street").on("street_segment").columns(["street_norm", "min_hn"]).execute()
+}

package/types.ts

@@ -0,0 +1,164 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Public surface for the WOF SQLite resolver — types only, no runtime.
+ *
+ *   These mirror the conceptual model described in `docs/plan/phases/PHASE_4_2_wof_sqlite.md`. Phase
+ *   4.3 will extend `PlaceCandidate` with the resolver-decorated fields that flow into
+ *   `AddressNode.source` / `sourceID` (e.g. an explicit `wofURI: "wof-admin:101751113"` form).
+ */
+
+/**
+ * The placetype taxonomy used by Who's On First. Ordered roughly from coarsest (country) to finest (address). See
+ * https://github.com/whosonfirst/whosonfirst-placetypes for the authoritative definitions of each.
+ *
+ * Phase 4.2 only emits the ones we actually look up; the union is open enough to extend later.
+ */
+export type WOFPlacetype =
+	| "country"
+	| "macroregion"
+	| "region"
+	| "macrocounty"
+	| "county"
+	| "localadmin"
+	| "locality"
+	| "borough"
+	| "neighbourhood"
+	| "microhood"
+	| "postalcode"
+	| "venue"
+	| "campus"
+	| "address"
+
+/**
+ * One candidate match for a place lookup.
+ *
+ * `score` is the post-boost ranking number — higher is better, but the scale is implementation- defined. Callers should
+ * treat it as ordinal, not absolute.
+ *
+ * `id` is the WOF place id. It's named generically (not `wof_id`) so the shape stays structurally compatible with
+ * `@mailwoman/resolver`'s `ResolvedPlace` — `WOFSqlitePlaceLookup` satisfies the generic `ResolverBackend` contract
+ * without an adapter shim.
+ *
+ * `distanceKm` is populated only when the query carried `near` (and the place has a centroid). Useful for downstream
+ * UIs that want to show "X km from you" alongside the result.
+ */
+export interface PlaceCandidate {
+	id: number
+	name: string
+	placetype: WOFPlacetype
+	/** ISO 3166-1 alpha-2 country code. */
+	country: string
+	lat: number
+	lon: number
+	parent_id?: number
+	score: number
+	distanceKm?: number
+	/**
+	 * True when this candidate's name OR an alias EXACTLY equals the query (the exact-match tier from
+	 * {@link RankingWeights.exactMatchTiering}). Surfaced so a downstream country re-rank (#369's postcode anchor in
+	 * `resolveTree`) can pin the country without crossing the tier — see the `exactMatch` field on `@mailwoman/core`'s
+	 * `ResolvedPlace`.
+	 */
+	exactMatch?: boolean
+	/**
+	 * Combined prominence (population term + best proximity-bias term, same additive units) — populated by the FTS
+	 * lookup; the exact-tier sort orders by THIS instead of raw population when the query carried proximity hints
+	 * (`near`/`bias`).
+	 */
+	prominence?: number
+	/**
+	 * Population from WOF's `wof:population` property. Only present when the candidate has it on record — WOF carries
+	 * population for ~15% of localities (mostly larger ones). Absent does NOT mean zero, just unknown.
+	 */
+	population?: number
+	/**
+	 * Bounding box from WOF's `spr.{min,max}_{latitude,longitude}` columns. Coarse outline for the place — a city's bbox
+	 * is the city's full extent, a postcode's is roughly the postcode polygon's envelope. Optional because not all
+	 * callers ask for it; implementations are free to omit when the underlying schema lacks the columns.
+	 */
+	bbox?: GeoBbox
+	/**
+	 * Set by the coordinate-first path when the chosen locality and the sibling postcode's containing locality are
+	 * geographically far apart — the postcode and the parsed city name disagree (a transposed / wrong-for-the-city
+	 * postcode). The candidate is still returned (the name wins for the locality), but the flag lets callers lower
+	 * confidence / surface the conflict rather than silently mislocate. A retrieval/BM25 geocoder can't raise this — it's
+	 * the falsehood-detection differentiator.
+	 */
+	mismatch?: boolean
+}
+
+/**
+ * A WGS-84 lat/lon point. Used as a proximity hint for `FindPlaceQuery.near`.
+ */
+export interface GeoPoint {
+	lat: number
+	lon: number
+}
+
+/**
+ * A WGS-84 bounding box. Used as a hard filter via `FindPlaceQuery.bbox`.
+ */
+export interface GeoBbox {
+	minLat: number
+	maxLat: number
+	minLon: number
+	maxLon: number
+}
+
+/**
+ * Query against the resolver.
+ *
+ * `text` is the only required field; everything else narrows the search. When `country` and `parentID` are both set,
+ * `parentID` wins (it's more specific).
+ *
+ * `near` and `bbox` are independent. `near` is a soft signal — candidates close to the point get a ranking boost but
+ * distant candidates aren't dropped. `bbox` is a hard filter — only candidates whose bbox intersects the query bbox are
+ * returned (uses the package-built R*Tree index when present; if the index is missing the option is silently ignored to
+ * preserve backwards compatibility).
+ *
+ * `near` may carry `maxDistanceKm` to escalate from a boost to a hard filter — candidates further than that distance
+ * from the point are dropped at the SQL level via an R*Tree pre-filter.
+ */
+export interface FindPlaceQuery {
+	text: string
+	placetype?: WOFPlacetype | WOFPlacetype[]
+	/** ISO 3166-1 alpha-2 — narrows to one country. */
+	country?: string
+	/** WOF place id — narrows to descendants of this place. */
+	parentID?: number
+	/**
+	 * Sibling postcode. When set on a `locality` query AND a `postcode_locality` table is present, triggers the
+	 * coordinate-first soft-score path: postcode→candidate localities are injected and scored `0.6·S_pc + 0.3·S_name +
+	 * 0.1·S_pop` against the FTS name-match set, recovering small localities the name-match alone misses. Ignored when no
+	 * postcode_locality shard is present.
+	 */
+	postcode?: string
+	/** Proximity hint — candidates close to this point get a ranking boost. */
+	near?: GeoPoint & { maxDistanceKm?: number }
+	/**
+	 * Ordered proximity-bias points (viewport center, user location, …), each optionally weighted (default 1.0, first
+	 * entry strongest by convention). SOFT — a re-rank signal, never a filter: with bias present, exact-tier candidates
+	 * order by combined prominence (population + the best decayed-distance term over these points) instead of population
+	 * alone, which is how an ambiguous bare postcode ("48026": Fraser MI vs Russi IT) follows the map view / the user.
+	 * Absent (and no `near`) → ranking is byte-identical to today. `near` is treated as a weight-1.0 bias point for
+	 * back-compat.
+	 */
+	bias?: Array<GeoPoint & { weight?: number }>
+	/** Bounding-box filter — only candidates whose bbox intersects this box are returned. */
+	bbox?: GeoBbox
+	/** Default 10. */
+	limit?: number
+}
+
+/**
+ * The pull-based lookup surface. Implementations resolve a `FindPlaceQuery` to a ranked list of `PlaceCandidate`s. The
+ * interface is async even though `node:sqlite` is sync — leaves room for `Worker`-backed implementations later without
+ * a public API break.
+ */
+export interface PlaceLookup {
+	findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>
+	close(): void
+}