@mailwoman/resolver-wof-sqlite 9.0.0 → 9.2.0

package/primary-preference.ts

@@ -0,0 +1,207 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Bounded cross-country PRIMARY-NAME preference over a population-ordered candidate row set — the
+ *   `is_primary` ranking signal, PURE and platform-free so the Node candidate lookup
+ *   (`candidate-lookup.ts`) and the browser twin (`docs/src/shared/httpvfs-resolver.ts`) rank with the
+ *   SAME function rather than two copies that drift (the #861 server↔demo parity contract).
+ *
+ *   Only type imports and arithmetic live here: anything with a `node:` import stays out.
+ */
+
+import type { CandidateTable } from "./candidate-schema.ts"
+
+/**
+ * The row shape the re-rank needs. `is_primary` is optional: a reader over an artifact vintage that predates the column
+ * omits it from the SELECT, no row reads as primary, and the re-rank no-ops by construction — the exact degradation the
+ * browser reader's vintage guard relies on.
+ */
+export type PrimaryPreferenceRow = Pick<CandidateTable, "neg_rank" | "country_id"> &
+	Partial<Pick<CandidateTable, "is_primary" | "placetype_id" | "population" | "name_role">>
+
+/**
+ * Bounded PRIMARY-NAME preference across a CROSS-COUNTRY name collision (the `is_primary` ranking signal).
+ *
+ * The raw candidate order is population-first (`neg_rank ASC`) and treats an ALIAS row (a place's alt-name / exonym,
+ * `is_primary=0`) and a PRIMARY-name row (`is_primary=1`) on equal footing. So a foreign place whose transliterated
+ * exonym coincidentally normalizes to a query — Changchun CN stores the Turkish exonym "Çançun" (`name_key="cancun"`),
+ * 4.19 M pop — outranks the PRIMARY-name place the query actually means (Cancún MX, 0.89 M pop). This penalty makes a
+ * same-key alias have to clear a population MARGIN over a foreign primary before it wins.
+ *
+ * It is deliberately NOT a dominant sort key (no `ORDER BY is_primary DESC`, which would make every primary outrank
+ * every alias and break the alt-names users depend on — "NYC"→New York, "LA"→Los Angeles, "Frisco"→San Francisco). Two
+ * bounds keep it a soft prior:
+ *
+ * 1. **Cross-country only.** The penalty applies to an alias ONLY when the top-population primary sharing the key is in a
+ *    DIFFERENT country. A SAME-country nickname contest (San Francisco's alias "Frisco" vs the primary Frisco, TX —
+ *    both US) is left on pure population, so the legitimate alias still wins.
+ * 2. **Population-bounded.** The penalty is {@link PRIMARY_PREFERENCE_LOG10} in log10-population units — an alias must be
+ *    at least 10x more populous than the foreign primary to still win. So a genuinely dominant alias keeps winning
+ *    ("Los Angeles" over La, Ghana — gap 1.6; "Las Vegas" over Vegas, Cuba — gap 2.4) while a near-tie coincidental
+ *    collision defers to the primary (Cancún over Changchun — gap 0.7).
+ */
+export const PRIMARY_PREFERENCE_LOG10 = 1
+
+/**
+ * The placetype the seat preference promotes: the populated-place tier a district duplicate shares its name and its
+ * population with. Named rather than inlined because narrowing the term to this ONE tier is what keeps it off the
+ * region/county and locality/neighbourhood contests — see `rankByPrimaryPreference` for the measurement.
+ */
+const SEAT_PLACETYPE = "locality"
+
+/**
+ * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
+ * worldwide) are re-ranked in-process, so the probe fetches this many (population-ordered) before the re-rank rather
+ * than the caller's small `limit`, ensuring the intended primary isn't cut below the fold by a cluster of more-populous
+ * foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ */
+export const RERANK_FETCH = 64
+
+/**
+ * A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag.
+ */
+export type RankedRow<R> = R & {
+	/**
+	 * `neg_rank` plus the bounded cross-country alias penalty — the value the row is ORDERED by, and the base the emitted
+	 * `prominence` is derived from (so the resolver walk's `prominence ?? score` sort, `resolve.ts`, agrees with this
+	 * order; the raw `score`/`neg_rank` is left intact for the walk's `minWinningScore` gate).
+	 */
+	effectiveNegRank: number
+	/**
+	 * True when this row is a cross-country alias that LOST the bounded population contest to the same-key primary — a
+	 * coincidental foreign exonym (Changchun's "Çançun" for "Cancun"). Such a row is dropped out of the exact-match tier
+	 * (`exactMatch=false`) so the resolver walk's country pin — the model's `anchorPosterior`, which "never crosses the
+	 * exact/partial boundary" (`resolve.ts`) — can't ride a spurious posterior (CN 0.86 for "Cancun") back over the
+	 * primary. Only the LOSING foreign alias is demoted; a dominant alias (Los Angeles over La, Ghana) keeps its exact
+	 * tier, and a same-country nickname (San Francisco's "Frisco") is never touched.
+	 */
+	demoted: boolean
+	/**
+	 * True when this row came from the TYPO-CORRECTOR tier — the FTS5-trigram fallback that fires only after the exact
+	 * and qualifier-strip probes both missed. Such a row answers a query the gazetteer does not contain, so it is a fuzzy
+	 * match by construction and must not claim `exactMatch` (#17). Recall is unaffected: the row is still returned, still
+	 * ranked, still resolvable — it just stops asserting a match quality it does not have, which is what the FTS backend
+	 * has always done and what every `exactMatch`-filtering consumer assumed.
+	 */
+	fuzzy?: boolean
+	/**
+	 * The admin-containment verdict (#1717 stage 2), stamped by `candidate-lookup.ts` when the query carried a
+	 * `regionQualifier` and the artifact carries the ancestors sidecar — the `fuzzy` precedent: a lookup-tier annotation
+	 * declared on the shared row shape. Tri-state like `ResolvedPlace.containedByQualifier`: absent means the question
+	 * was never asked, never "not contained".
+	 */
+	containedByQualifier?: boolean
+}
+
+/**
+ * Bounded cross-country primary-name preference (see {@link PRIMARY_PREFERENCE_LOG10}). Pure + total-ordered so
+ * `candidate-lookup.test.ts` can exercise it on synthetic rows. `rows` arrive population-ordered (`neg_rank ASC`); an
+ * alias (`is_primary=0`) is pushed back by `delta` in log10-population units ONLY when the top-population primary
+ * sharing the key is in a different country, and is `demoted` out of the exact tier when that penalty leaves it BEHIND
+ * the primary. Returns the top `limit` after the re-rank, each annotated.
+ *
+ * `placetypes` (the artifact's own `placetype_codes` map) enables the LAST tiebreak, the SEAT preference: when
+ * `effectiveNegRank` and raw `neg_rank` both tie — two same-key rows population cannot separate at all — a
+ * {@link SEAT_PLACETYPE} row carrying a real population outranks every other placetype. Omit the map and every row
+ * scores 0, the term cancels, and the order is exactly the population-then-scan-order it was before.
+ *
+ * The tie it exists for is a DUPLICATE, not a contest. A district and its identically-named seat town are stored as two
+ * rows carrying the SAME population, so `neg_rank` is equal to the bit and `referential` follows it
+ * (`referentialFromPopulation` is a pure function of population). Turkey's `Of` is the measured case — locality
+ * 8114738869649 and its parent county 8837168432019 both hold population 44212 — and 358 locality/parent-county pairs
+ * across 15 countries share the shape in `admin-global-priority.db` (TR 162, CA 77, US 47, HR 24, DO 14). Without the
+ * term their order is whatever the scan hands the sorter.
+ *
+ * WHERE THE TERM DECIDES, AND WHERE IT CANNOT (#1729). It binds inside `findPlace`, so it orders every row set that
+ * actually CONTAINS the tie — but the resolver walk's probes all carry a placetype filter, and
+ * `PLACETYPE_FILTER_GROUPS` (core/resolver) never mixes `locality` with `county`: the `Of`-shape locality/county pair
+ * is PARTITIONED before this ranker runs, the locality probe fetches one row, and the walk's own `locality` request
+ * selects the seat by construction — the same winner, decided upstream. The tie that reaches an end-to-end answer
+ * through this term is the IN-GROUP residue: a locality/localadmin (or borough) duplicate whose `importance` values
+ * also tie. Downstream the resolver re-sorts by importance (`resolver/toponym-prior.ts`) but is stable on equal keys,
+ * so the order stamped here is the order that answers — inverting this term moves bare `Pu-cheng-hsien` 1,100 km
+ * (locality Pucheng over the 浦城县 localadmin, identical population and importance). Where importance separates the pair,
+ * the fame prior overrides by design; a probe with NO placetype filter (the browser cascade's last resort, the dev
+ * lookup tools) presents the full tie and this term is all that breaks it.
+ *
+ * BOTH GATES ARE LOAD-BEARING, and a plain "finer placetype wins" measured wrong before this shape was settled: it
+ * moved the top slot on 11,377 keys in `candidate.db`, of which only 722 were the seat/district duplicate. The rest
+ * were contests between genuinely distinct places that merely tie — 2,885 `locality → neighbourhood` (a bare city name
+ * losing to a same-named hood), 2,973 `region → county`, 2,662 `postalcode → locality` — and 7,179 of the 11,377 sat at
+ * population 0, where a tie means NO EVIDENCE rather than equal evidence. Requiring a real population keeps the term
+ * off every no-evidence tie; promoting the populated-place tier specifically, rather than whatever is finer, keeps it
+ * off the admin-tier and hood contests. It can never reach a pair population separates: it does not override a
+ * population gap, it replaces an undetermined order with a stated one.
+ */
+export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
+	rows: readonly R[],
+	limit: number,
+	delta = PRIMARY_PREFERENCE_LOG10,
+	placetypes?: ReadonlyMap<number, string>,
+	exemptVariantAliases = false
+): Array<RankedRow<R>> {
+	// The primary the alias actually competes with for the top slot: highest population (min neg_rank). Undefined
+	// when the set has no primary → nothing to prefer, penalty is 0, order stays population-first (today's behavior).
+	let topPrimary: R | undefined
+
+	for (const r of rows) {
+		if (r.is_primary === 1 && (topPrimary == null || r.neg_rank < topPrimary.neg_rank)) {
+			topPrimary = r
+		}
+	}
+
+	const topCountry = topPrimary?.country_id
+
+	// A cross-country alias (different country than the top primary) is penalized; it is DEMOTED when even after — i.e.
+	// the penalty leaves its effective rank behind the primary's raw rank (it lost the bounded population contest).
+	//
+	// #1882 exemption (opt-in): a `name_role = 'variant'` alias is the holder's OWN primary name in another
+	// orthography (`Брэст` → `brest`, `George Town` → `georgetown` — the build's own-name detector), so the
+	// query is naming THAT place, not colliding with it; the penalty exists for the coincidental-collision
+	// class ("Çançun"/`cancun`), which the detector's measured threshold keeps un-stamped. An artifact
+	// predating the role column carries no 'variant' rows, so the flag no-ops there by construction.
+	const isCrossCountryAlias = (r: R): boolean =>
+		typeof topCountry === "number" &&
+		r.is_primary !== 1 &&
+		r.country_id !== topCountry &&
+		!(exemptVariantAliases && r.name_role === "variant")
+
+	const annotate = (r: R): RankedRow<R> => {
+		const penalized = isCrossCountryAlias(r)
+		const effectiveNegRank = r.neg_rank + (penalized ? delta : 0)
+
+		return { ...r, effectiveNegRank, demoted: penalized && effectiveNegRank > topPrimary!.neg_rank }
+	}
+
+	// 1 for a populated-place row that can BE a district's seat, 0 for everything else — no code map, no
+	// placetype on the row, an id the map does not carry, a placetype that is not the seat tier, or no
+	// recorded population. Every row scoring 0 cancels the term, leaving exactly the
+	// population-then-scan-order the sort had before it existed.
+	const seatPreference = (r: R): number =>
+		placetypes != null &&
+		typeof r.placetype_id === "number" &&
+		typeof r.population === "number" &&
+		r.population > 0 &&
+		placetypes.get(r.placetype_id) === SEAT_PLACETYPE
+			? 1
+			: 0
+
+	return (
+		rows
+			.map((r, i) => ({ row: annotate(r), i }))
+			// Effective rank ASC; ties keep population order, then the seat preference DESC, then original
+			// index (stable).
+			// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+			.sort(
+				(a, b) =>
+					a.row.effectiveNegRank - b.row.effectiveNegRank ||
+					a.row.neg_rank - b.row.neg_rank ||
+					seatPreference(b.row) - seatPreference(a.row) ||
+					a.i - b.i
+			)
+			.slice(0, limit)
+			.map((x) => x.row)
+	)
+}

package/proximity-rerank.ts

@@ -0,0 +1,120 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The proximity re-rank (#938): with bias hints — the demo's map viewport, a user location — re-order exact-match
+ *   candidates by population and nearness on one additive scale, so an in-view namesake wins a tie without a hard
+ *   filter. Byte-identical to plain population order when no bias is passed.
+ *
+ *   This lives in its own platform-free module because it has to run identically in two places: the Node candidate
+ *   reader and the browser byte-range twin. That is the #861 server↔demo parity contract, and it is the second thing
+ *   here held by construction rather than by comment (`primary-preference.ts` was the first). Constants alone were not
+ *   enough — the two copies agreed on every literal and still diverged on which field the population term reads and on
+ *   whether the combined value is written back, which is the half that actually decides the answer.
+ *
+ *   Two properties are load-bearing and easy to lose when transcribing:
+ *
+ *   1. The population base is `prominence ?? score`, NOT `score`. `prominence` carries the bounded cross-country
+ *      primary preference, so reading raw score lets a coincidental foreign alias ride population back over a primary
+ *      whenever a viewport hint happens to be present.
+ *   2. The combined value is PERSISTED into `prominence`. The resolver walk re-sorts by `prominence ?? score`, so a
+ *      caller that only returns the array in bias order has its ordering silently discarded downstream.
+ */
+
+import { haversineKm } from "@mailwoman/spatial"
+
+/**
+ * Full magnitude of the nearness term at distance 0, before decay.
+ */
+export const BIAS_BOOST = 4
+
+/**
+ * Full magnitude of the population term, reached at {@link POP_SCALE_LOG10} and capped there.
+ */
+export const POP_BOOST = 4
+
+/**
+ * `log10(population + 1)` at which the population term saturates — 6 means a population of one million earns the whole
+ * {@link POP_BOOST}, and larger populations earn no more.
+ */
+export const POP_SCALE_LOG10 = 6
+
+/**
+ * Distance at which the nearness term halves.
+ *
+ * SHARPER than the FTS reader's 100 km on purpose: the candidate backend's score is log-population ALONE, with no bm25
+ * document term, so the population signal is weaker relative to the bias and a gentle 100 km decay let a 230 km-distant
+ * alias-exact township ("Paris Township", OH) edge out a global city ("Paris", FR) from a nearby view. At ~30 km the
+ * boost reaches only candidates the user is actually looking at: an in-view namesake still wins (Dublin, OH from an
+ * Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
+ */
+export const PROX_SCALE_KM = 30
+
+/**
+ * One bias hint — a coordinate the user is looking at or standing on, optionally weighted.
+ */
+export interface ProximityBias {
+	lat: number
+	lon: number
+	weight?: number
+}
+
+/**
+ * The candidate fields the re-rank reads and writes. Structural rather than a concrete candidate type, so the Node
+ * reader's `PlaceCandidate` and the browser twin's row shape both satisfy it without an adapter.
+ */
+export interface ProximityRerankable {
+	lat: number
+	lon: number
+	score: number
+	prominence?: number
+}
+
+/**
+ * Population plus nearness on one additive scale. Exported for tests and for a caller that wants the value without the
+ * sort; ordinary callers want {@link applyProximityRerank}.
+ */
+export function combinedProminence(candidate: ProximityRerankable, bias: readonly ProximityBias[]): number {
+	const popBase = candidate.prominence ?? candidate.score
+	const popTerm = POP_BOOST * Math.min(1, Math.max(0, popBase) / POP_SCALE_LOG10)
+	let proxTerm = 0
+
+	// A candidate at the null island has no coordinate, not a coordinate at 0,0 — it earns no nearness term rather
+	// than an enormous one.
+	if (!(candidate.lat === 0 && candidate.lon === 0)) {
+		for (const b of bias) {
+			const d = haversineKm(b.lat, b.lon, candidate.lat, candidate.lon)
+			const term = (BIAS_BOOST * (b.weight ?? 1)) / (1 + d / PROX_SCALE_KM)
+
+			if (term > proxTerm) {
+				proxTerm = term
+			}
+		}
+	}
+
+	return popTerm + proxTerm
+}
+
+/**
+ * Re-order `candidates` in place by {@link combinedProminence}, persisting each combined value into `prominence` so the
+ * resolver walk's own `prominence ?? score` sort carries the bias order rather than undoing it. Stable within equal
+ * prominence, preserving the population order the index already gave. A caller with no bias hints must not call this —
+ * the no-bias path is plain population order by construction.
+ */
+export function applyProximityRerank<T extends ProximityRerankable>(
+	candidates: T[],
+	bias: readonly ProximityBias[]
+): T[] {
+	candidates
+		.map((c, i) => {
+			c.prominence = combinedProminence(c, bias)
+
+			return { c, i, p: c.prominence }
+		})
+		// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+		.sort((a, b) => b.p - a.p || a.i - b.i)
+		.forEach((x, j) => (candidates[j] = x.c))
+
+	return candidates
+}

package/region-keys.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The comparable-key expansion for a parsed REGION qualifier — one function, both consumers (the
+ *   #861 rule). The admin-coherence verdicts (`mailwoman/admin-coherence.ts`) fold a qualifier and a
+ *   winner-ancestry name through this to decide `confirmed`/`contradicted`; the candidate backend's
+ *   admin-containment re-rank (#1717 stage 2, `candidate-lookup.ts`) folds the same qualifier through
+ *   it to find the qualifier's own region-class rows in the candidate table. A check that says
+ *   `contradicted` and a re-rank that cannot find the qualifier would otherwise be two readings of
+ *   one string that silently disagree — the exact drift the shared-function rule exists to prevent.
+ *
+ *   Lives HERE rather than in `mailwoman` because the dependency points this way: `mailwoman`
+ *   depends on `@mailwoman/resolver-wof-sqlite` (which owns the fold and already depends on codex),
+ *   never the reverse.
+ */
+
+import { matchSubdivision, matchSubdivisionIn } from "@mailwoman/codex/country"
+
+import { normalizeLocalityForKey } from "./street-normalize.ts"
+
+/**
+ * The ancestry placetypes that answer for a parsed `region` qualifier — WOF's admin band between country and locality.
+ * Deliberately the whole band: a qualifier stated at any grain ("Lancashire", a ceremonial county; "Thüringen", a Land)
+ * may confirm against whichever level the backend stored, and `contradicted` requires the entire band to miss, so
+ * widening the band only ever makes the check more conservative.
+ */
+export const REGION_CLASS_PLACETYPES: ReadonlySet<string> = new Set(["region", "macroregion", "county", "macrocounty"])
+
+/**
+ * County-style qualifier prefixes stripped to produce a comparison VARIANT. Ireland writes `Co. Westmeath` where WOF
+ * stores `Westmeath`, so the prefix defeats the fold and every Irish county qualifier read `contradicted` on the first
+ * board census (2026-08-17, five rows). The stripped form is ADDED to the key set, never substituted — `County Durham`
+ * is a real name whose stripped variant simply also matches, and a set union can only widen confirmation, so the
+ * closure is monotone: `contradicted → confirmed` is the only movement it can cause.
+ */
+const COUNTY_QUALIFIER_PREFIXES = ["county", "co.", "co"] as const
+
+/**
+ * Trailing admin-qualifier words, the suffix sibling of the prefix above: `San José Province` (CR board row) folds
+ * against stored `San José` only with the word removed. Same monotone rule — the stripped form joins the set, never
+ * replaces the original.
+ */
+const ADMIN_QUALIFIER_SUFFIXES = ["province", "prov.", "prov"] as const
+
+function withoutPrefix(value: string, prefixes: readonly string[]): string {
+	const folded = value.toLowerCase()
+
+	for (const prefix of prefixes) {
+		if (!folded.startsWith(prefix) || !/\s/u.test(value[prefix.length] ?? "")) continue
+
+		let offset = prefix.length
+
+		while (/\s/u.test(value[offset] ?? "")) {
+			offset++
+		}
+
+		return value.slice(offset)
+	}
+
+	return value
+}
+
+function withoutSuffix(value: string, suffixes: readonly string[]): string {
+	const folded = value.toLowerCase()
+
+	for (const suffix of suffixes) {
+		const offset = value.length - suffix.length
+
+		if (offset <= 0 || !folded.endsWith(suffix) || !/\s/u.test(value[offset - 1] ?? "")) continue
+
+		let end = offset
+
+		while (end > 0 && /\s/u.test(value[end - 1] ?? "")) {
+			end--
+		}
+
+		return value.slice(0, end)
+	}
+
+	return value
+}
+
+/**
+ * The comparable keys a region string expands to: its own fold (the shared candidate.db `name_key` normalizer,
+ * {@link normalizeLocalityForKey} — build side and check side agree by construction); a county-prefix-stripped variant;
+ * the codex subdivision expansions — the disjoint US+CA table always, plus the COUNTRY-SCOPED table when the caller
+ * knows a country (`WA` under AU is Western Australia; under US, Washington — the collision that keeps AU out of the
+ * unscoped table). Every expansion lands the canonical name and code folds in the set, so `IL`/`Illinois` and
+ * `WA`/`Western Australia` meet from either side.
+ */
+export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
+	const keys = new Set([normalizeLocalityForKey(value)])
+
+	for (const stripped of [
+		withoutPrefix(value, COUNTY_QUALIFIER_PREFIXES),
+		withoutSuffix(value, ADMIN_QUALIFIER_SUFFIXES),
+	]) {
+		if (stripped !== value && stripped.trim()) {
+			keys.add(normalizeLocalityForKey(stripped))
+		}
+	}
+
+	const expansions = [matchSubdivision(value), countryAlpha2 ? matchSubdivisionIn(countryAlpha2, value) : null]
+
+	for (const subdivision of expansions) {
+		if (subdivision) {
+			keys.add(normalizeLocalityForKey(subdivision.name))
+			keys.add(normalizeLocalityForKey(subdivision.code))
+		}
+	}
+
+	// The empty fold stays IN the set on purpose — the admin-coherence verdicts have always compared
+	// the empty key (two empty-folding strings intersect → `confirmed`), and this move must not shift
+	// a verdict. A consumer probing a table by key filters the empty string out itself.
+	return keys
+}
+
+/**
+ * The PROBE-side expansion for a region qualifier — {@link regionKeys} plus the county-PREFIXED variant of every key.
+ *
+ * The verdict machinery intersects two {@link regionKeys} SETS, so `Co. Donegal` meets stored `County Donegal` at the
+ * shared stripped key `donegal`. A table probe is one-sided: it matches the STORED fold verbatim, and WOF stores Irish
+ * counties under `county donegal` with no bare `donegal` key (measured on the shipped candidate.db — the qualifier
+ * probe missed every Irish county until this variant landed). Adding `county <key>` restores the two-sidedness for the
+ * one stored-form family with an evidenced case; the union is monotone (a wider qualifier set can only find more
+ * BEARERS, each of which must still genuinely contain a candidate before anything moves). The suffix sibling (`<key>
+ * province`) is deliberately absent — no stored-form case has been evidenced, and a lever without a board does not get
+ * built.
+ */
+export function regionQualifierProbeKeys(value: string, countryAlpha2?: string): Set<string> {
+	const keys = regionKeys(value, countryAlpha2)
+	// Snapshot before widening: the loop adds `county <key>` members that must not themselves be revisited.
+	const bare = [...keys]
+
+	for (const key of bare) {
+		if (key && !key.startsWith("county ")) {
+			keys.add(`county ${key}`)
+		}
+	}
+
+	return keys
+}

package/reverse.ts

@@ -31,10 +31,11 @@
 import { DatabaseSync } from "node:sqlite"
 
 import { tryParsingJSON } from "@mailwoman/core/objects"
+import { geometryContains, haversineKm, type GeojsonGeometry } from "@mailwoman/spatial"
 
 import { ancestorLineage, placetypeDepth } from "./ancestry.ts"
 import { PLACE_BBOX_TABLE } from "./fts.ts"
-import { geometryContains, haversineKm, type GeojsonGeometry } from "./geo.ts"
+import { allRows } from "./sqlite-utils.ts"
 import type { PlaceCandidate, WOFPlacetype } from "./types.ts"
 
 /**
@@ -389,16 +390,17 @@ export class WOFReverseGeocoder implements Disposable {
 
 		params.push(opts.maxCandidates ?? DEFAULT_MAX_CANDIDATES)
 
-		return this.#admin
-			.prepare(
+		return allRows<CandidateRow>(
+			this.#admin.prepare(
 				`SELECT spr.id AS id, spr.name AS name, spr.placetype AS placetype, spr.country AS country,
 					spr.parent_id AS parent_id, spr.latitude AS lat, spr.longitude AS lon
 				FROM ${PLACE_BBOX_TABLE} bbox JOIN spr ON spr.id = bbox.id
 				WHERE ${where.join(" AND ")}
 				ORDER BY (bbox.max_lat - bbox.min_lat) * (bbox.max_lon - bbox.min_lon) ASC
 				LIMIT ?`
-			)
-			.all(...params) as unknown as CandidateRow[]
+			),
+			...params
+		)
 	}
 
 	/**
@@ -415,22 +417,21 @@ export class WOFReverseGeocoder implements Disposable {
 	): CandidateRow[] {
 		const windowDeg = (maxApproximateKm * 4) / 111
 
-		return this.#admin
-			.prepare(
+		return allRows<CandidateRow>(
+			this.#admin.prepare(
 				`SELECT s.id AS id, s.name AS name, s.placetype AS placetype, s.country AS country,
 					s.parent_id AS parent_id, s.latitude AS lat, s.longitude AS lon
 				FROM ancestors a JOIN spr s ON s.id = a.id
 				WHERE a.ancestor_id = ? AND s.placetype = ? AND s.is_current != 0 AND s.is_deprecated = 0
 					AND s.latitude BETWEEN ? AND ? AND s.longitude BETWEEN ? AND ?`
-			)
-			.all(
-				parentID,
-				placetype,
-				lat - windowDeg,
-				lat + windowDeg,
-				lon - windowDeg,
-				lon + windowDeg
-			) as unknown as CandidateRow[]
+			),
+			parentID,
+			placetype,
+			lat - windowDeg,
+			lat + windowDeg,
+			lon - windowDeg,
+			lon + windowDeg
+		)
 	}
 
 	/**

package/schema.ts

@@ -159,7 +159,7 @@ export interface CoincidentRolesTable {
 
 /**
  * The full schema we hand to `Kysely<WOFDatabase>` / `new DatabaseClient<WOFDatabase>(...)`. Tables not listed here
- * will fail type-checked queries — by design. The reader ({@link WOFSqlitePlaceLookup}) already consumes this; the
+ * will fail type-checked queries — by design. The reader ({@link WOFSQLitePlaceLookup}) already consumes this; the
  * build/augment WRITERS adopt it so a column rename is a compile error on both sides (the drift that bit the corpus
  * TIGER adapter).
  */