@mailwoman/resolver-wof-sqlite 7.2.0 → 7.3.0

package/postal-city-alias-schema.ts

@@ -0,0 +1,75 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`, built by
+ *   `scripts/build-postal-city-alias.ts`) — the single source of truth for the columns shared by
+ *   the BUILDER and the READER ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
+ *   contract is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
+ *   the builder is a compile error in the reader.
+ *
+ *   Provenance discipline (provenance-first): this is a SIBLING table to the PIP-derived
+ *   `postcode_locality` data, never mixed into it — one table, one provenance class. Each row is an
+ *   OBSERVED `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
+ *   with a usage count `n`; `divergent = 1` exactly when `postal_city != geo_locality` (the alias
+ *   signal — the only rows the resolver consumes).
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * One observed postal-city aggregate. The natural key is `(postcode, postal_city, geo_locality)`; the builder enforces
+ * a `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
+ */
+export interface PostalCityAliasTable {
+	/** The postcode the aggregate is scoped to (the resolver probes by this). */
+	postcode: string
+	/** What the postal system calls the place (the surface a user is likely to type). */
+	postal_city: string
+	/** The geographic locality name the postcode actually sits in (≈ the gazetteer's canonical name). */
+	geo_locality: string
+	/** Observed row count — the evidence weight behind this alias. */
+	n: number
+	/** 1 when `postal_city != geo_locality` (the alias signal); 0 when they agree. */
+	divergent: number
+	/** Provenance: the dataset this aggregate came from (e.g. `overture:US`). */
+	source: string
+	/** The pinned data release the aggregate was computed from. */
+	release: string
+}
+
+/** The postal-city-alias database schema for `new DatabaseClient<PostalCityAliasDatabase>(...)`. */
+export interface PostalCityAliasDatabase {
+	postal_city_alias: PostalCityAliasTable
+}
+
+/** The `postal_city_alias` column order — the builder's INSERT derives its column list from this. */
+export const POSTAL_CITY_ALIAS_COLUMNS = [
+	"postcode",
+	"postal_city",
+	"geo_locality",
+	"n",
+	"divergent",
+	"source",
+	"release",
+] as const
+
+/**
+ * Create the `postal_city_alias` table + its two probe indexes. Kept here (not only in the builder) so tests can stand
+ * up a fixture DB with the exact production shape. Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
+ */
+export async function createPostalCityAliasTable(db: Kysely<PostalCityAliasDatabase>): Promise<void> {
+	await db.schema
+		.createTable("postal_city_alias")
+		.addColumn("postcode", "text", (c) => c.notNull())
+		.addColumn("postal_city", "text", (c) => c.notNull())
+		.addColumn("geo_locality", "text", (c) => c.notNull())
+		.addColumn("n", "integer", (c) => c.notNull())
+		.addColumn("divergent", "integer", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.addColumn("release", "text", (c) => c.notNull())
+		.execute()
+	await db.schema.createIndex("idx_pca_postcode").on("postal_city_alias").column("postcode").execute()
+	await db.schema.createIndex("idx_pca_pair").on("postal_city_alias").columns(["postal_city", "geo_locality"]).execute()
+}

package/postal-city-candidate-schema.ts

@@ -0,0 +1,81 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the POSTAL-CITY CANDIDATE side-index (#741 / #475) — a small `(name_key,
+ *   postcode) → geo-locality` table that lives alongside the byte-range `candidate` table so the
+ *   candidate-backend resolver (the demo/CLI default) can do what the FTS coordinate-first scorer
+ *   does: resolve a user-typed POSTAL city ("Antioch", 37013) to the geographic locality the
+ *   postcode sits in ("Nashville").
+ *
+ *   Why a SIDE-INDEX, not cloned `candidate` rows: the `candidate` B-tree is keyed `(name_key,
+ *   country_id, region_id, placetype_id, …)` and ranked population-first — it has no postcode
+ *   dimension. A cloned alias row was tested (#741) and falsified: a sentinel rank is
+ *   bare-name-safe but then loses to any in-region homonym, and there is no single rank that is
+ *   both. The fix is an EXACT `(name_key, postcode)` probe that bypasses population/region ranking
+ *   entirely — consulted only when the query carries a postcode, so the common no-postcode path is
+ *   untouched.
+ */
+
+import { sql, type Kysely } from "kysely"
+
+/**
+ * One postal-city → geo-locality edge, keyed exactly by `(name_key, postcode)`. The probe returns the geographic
+ * locality directly; the denormalized name/coord avoid a join back to `candidate`.
+ */
+export interface PostalCityCandidateTable {
+	/** {@link normalizeLocalityForKey} of the postal-city name — the build/query-consistent probe key. */
+	name_key: string
+	/** The postcode the alias is scoped to (the second half of the exact key). */
+	postcode: string
+	/** WOF id of the geographic locality the postcode sits in (the resolve target). */
+	spr_id: number
+	/** The geographic locality's display name. */
+	name: string
+	latitude: number
+	longitude: number
+}
+
+/**
+ * The postal-city-candidate database schema for `new DatabaseClient<PostalCityCandidateDatabase>(...)`.
+ */
+export interface PostalCityCandidateDatabase {
+	postal_city_candidate: PostalCityCandidateTable
+}
+
+/**
+ * The table name the lookup probes (existence-gated, so an old candidate.db without it is byte-stable).
+ */
+export const POSTAL_CITY_CANDIDATE_TABLE = "postal_city_candidate"
+
+/** Column order for the builder's positional INSERT. */
+export const POSTAL_CITY_CANDIDATE_COLUMNS = [
+	"name_key",
+	"postcode",
+	"spr_id",
+	"name",
+	"latitude",
+	"longitude",
+] as const
+
+/**
+ * Create the side-index — a clustered `WITHOUT ROWID` B-tree on `(name_key, postcode)` so the resolve is a single exact
+ * probe. Idempotent (`IF NOT EXISTS`); pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB. The
+ * Kysely schema-builder is the house idiom for table creation — see `AGENTS.md` (inline-SQL → Kysely).
+ */
+export async function createPostalCityCandidateTable(db: Kysely<PostalCityCandidateDatabase>): Promise<void> {
+	await db.schema
+		.createTable(POSTAL_CITY_CANDIDATE_TABLE)
+		.ifNotExists()
+		.addColumn("name_key", "text", (c) => c.notNull())
+		.addColumn("postcode", "text", (c) => c.notNull())
+		.addColumn("spr_id", "integer", (c) => c.notNull())
+		.addColumn("name", "text", (c) => c.notNull())
+		.addColumn("latitude", "real", (c) => c.notNull())
+		.addColumn("longitude", "real", (c) => c.notNull())
+		.addPrimaryKeyConstraint("postal_city_candidate_pk", ["name_key", "postcode"])
+		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}

package/postcode-point-lookup.ts

@@ -0,0 +1,64 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   SQLite-backed postcode lookup for the postcode anchor (#240). A thin exact-match resolver over
+ *   one or more `postalcode-*.db` shards (the `spr` schema built by `build-unified-wof --placetypes
+ *   postalcode`, then centroid-backfilled by `scripts/backfill-postcode-centroids.ts`).
+ *
+ *   This is the production implementation of the `PostcodeResolver` interface consumed by
+ *   `@mailwoman/neural`'s `extractPostcodeAnchors`. It is deliberately dumb: an indexed exact-match
+ *   on the postcode string across every shard, unioned. No FTS, no ranking, no proximity — the
+ *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
+ *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` seam.
+ *
+ *   Why multiple shards instead of the multi-shard `WOFSqlitePlaceLookup`: that resolver routes a
+ *   query to ONE shard by placetype, but every postcode shard shares `placetype='postalcode'`, so a
+ *   single query could only ever hit one country's shard. The anchor needs the union across
+ *   countries to build its country posterior, so it queries each shard directly.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+/**
+ * A gazetteer hit. `lat`/`lon` of 0 means the postcode is known but has no centroid (no admin parent).
+ */
+export interface PostcodePlace {
+	country: string
+	lat: number
+	lon: number
+}
+
+const LOOKUP_SQL =
+	"SELECT country, latitude AS lat, longitude AS lon FROM spr WHERE name = ? AND placetype = 'postalcode' AND is_current != 0"
+
+export class WOFPostcodeLookup {
+	readonly #dbs: DatabaseSync[]
+	readonly #stmts: ReturnType<DatabaseSync["prepare"]>[]
+
+	/** Open each shard read-only and prepare its exact-match statement. */
+	constructor(dbPaths: readonly string[]) {
+		this.#dbs = dbPaths.map((p) => new DatabaseSync(p, { readOnly: true }))
+		this.#stmts = this.#dbs.map((db) => db.prepare(LOOKUP_SQL))
+	}
+
+	/** Exact-match the postcode across every shard and union the rows. */
+	lookup(postcode: string): PostcodePlace[] {
+		const out: PostcodePlace[] = []
+
+		for (const stmt of this.#stmts) {
+			for (const row of stmt.all(postcode)) {
+				out.push({ country: String(row.country), lat: Number(row.lat), lon: Number(row.lon) })
+			}
+		}
+
+		return out
+	}
+
+	close(): void {
+		for (const db of this.#dbs) {
+			db.close()
+		}
+	}
+}

package/reverse.ts

@@ -0,0 +1,439 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reverse geocoding (#484): `(lat, lon)` → the containing admin hierarchy. Assembly over existing
+ *   machinery, per the 2026-06-11 scoping notes:
+ *
+ *   1. **Candidate fetch** — the admin DB's `place_bbox` R*Tree (built by `fts.ts`) for places whose
+ *        bbox contains the point, smallest-area-first (so the FIRST polygon confirmation is the
+ *        deepest).
+ *   2. **PIP confirmation** — ray-cast (geo.ts, the canonical TS port of
+ *        `scripts/eval/pip-containment.py`) against the polygon sidecar DB (`wof-polygons.db`,
+ *        `polygons(id, geom)` with GeoJSON text — built by `scripts/build-wof-polygons.mjs` for the
+ *        demo map). A candidate whose polygon EXISTS but rejects the point is a bbox false positive
+ *        and is dropped entirely; a candidate with no polygon row stays eligible for the
+ *        approximate fallback.
+ *   3. **Approximate descent** — WOF carries point geometry for most localities (#292: ~99% of JP
+ *        municipalities; ~half of US localities have degenerate bboxes too), so the polygon walk
+ *        usually bottoms out at county level. We then descend tier-by-tier (county → localadmin →
+ *        locality → …) through the winner's DESCENDANTS (the `ancestors` table, reversed), taking
+ *        the PIP-confirmed child when a polygon exists and the nearest-centroid child otherwise —
+ *        the latter flagged `containment: "approximate"`, the demo's honesty convention.
+ *   4. **Hierarchy assembly** — the deepest place's ancestor chain via the SAME walk forward resolution
+ *        uses (`ancestry.ts`, #404), so consumers get a symmetric tree.
+ *
+ *   Reverse quality is country-dependent (polygon coverage: see the #292 JP finding); `containment`
+ *   says so per result rather than pretending.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { ancestorLineage, placetypeDepth } from "./ancestry.ts"
+import { PLACE_BBOX_TABLE } from "./fts.ts"
+import { geometryContains, haversineKm, type GeojsonGeometry } from "./geo.ts"
+import type { PlaceCandidate, WOFPlacetype } from "./types.ts"
+
+/**
+ * How the deepest returned place was confirmed:
+ *
+ * - `"polygon"` — the point ray-cast INSIDE the place's real (DP-simplified) admin boundary.
+ * - `"approximate"` — the place has no polygon on record; it won by nearest-centroid among the candidates whose bbox (or
+ *   parent) contains the point. The same honesty convention as the demo's approximate circles — country-dependent data
+ *   reality, surfaced instead of hidden.
+ */
+export type ContainmentKind = "polygon" | "approximate"
+
+export interface ReverseGeocodeResult {
+	/**
+	 * The containment chain, DEEPEST-FIRST (`[0]` is the winning place, then its ancestors up to country) — the same tree
+	 * shape forward resolution attaches via `includeAncestors`. Empty when no candidate's bbox contains the point (open
+	 * ocean, or outside the gazetteer's coverage).
+	 */
+	hierarchy: PlaceCandidate[]
+	/** Containment kind of the DEEPEST place in `hierarchy` (see {@link ContainmentKind}). */
+	containment: ContainmentKind
+}
+
+export interface WOFReverseGeocoderOpts {
+	/**
+	 * Path to the admin gazetteer DB (e.g. `admin-global-priority.db`) — must carry `spr`, `ancestors`, and the
+	 * package-built `place_bbox` R*Tree (`mailwoman gazetteer build fts`). Mutually exclusive with `adminDatabase`.
+	 */
+	adminDBPath?: string
+	/** Pre-opened admin DB — primarily for tests against an inline fixture. */
+	adminDatabase?: DatabaseSync
+	/**
+	 * Path to the polygon sidecar DB (`wof-polygons.db`, table `polygons(id, geom)`). OPTIONAL — without it every result
+	 * is `containment: "approximate"` (centroid-only mode). Mutually exclusive with `polygonDatabase`.
+	 */
+	polygonDBPath?: string
+	/** Pre-opened polygon DB — primarily for tests. */
+	polygonDatabase?: DatabaseSync
+}
+
+export interface ReverseGeocodeOpts {
+	/**
+	 * Restrict the hierarchy to these placetypes (both the bbox candidates and the descent tiers). Default: every admin
+	 * placetype the gazetteer carries. E.g. `["region", "county", "locality"]` to skip the neighbourhood grain.
+	 */
+	placetypes?: WOFPlacetype[]
+	/**
+	 * Cap on the bbox candidate fetch. Default 128 — comfortably covers a dense metro (the most bbox-overlapping point
+	 * we've measured is a few dozen neighbourhoods + the admin chain).
+	 */
+	maxCandidates?: number
+	/**
+	 * Approximate (nearest-centroid) steps further than this from the query point are not taken — keeps a sparse
+	 * gazetteer from "refining" to a far-away sibling. Polygon-confirmed steps ignore it (containment is exact regardless
+	 * of centroid distance). Default 25 km.
+	 */
+	maxApproximateKm?: number
+}
+
+const DEFAULT_MAX_CANDIDATES = 128
+const DEFAULT_MAX_APPROXIMATE_KM = 25
+
+/**
+ * The tier ladder for the approximate descent, coarsest-first. Each tier is attempted among the CURRENT winner's
+ * descendants; a tier with no rows is skipped (e.g. counties without localadmins jump straight to locality).
+ */
+const DESCENT_TIERS: readonly WOFPlacetype[] = [
+	"county",
+	"localadmin",
+	"locality",
+	"borough",
+	"neighbourhood",
+	"microhood",
+]
+
+/** Internal candidate row off `spr` (+ optional bbox area / centroid distance bookkeeping). */
+interface CandidateRow {
+	id: number
+	name: string
+	placetype: string
+	country: string | null
+	parent_id: number | null
+	lat: number
+	lon: number
+}
+
+function toPlaceCandidate(row: CandidateRow, distanceKm?: number): PlaceCandidate {
+	const c: PlaceCandidate = {
+		id: row.id,
+		name: row.name,
+		placetype: row.placetype as WOFPlacetype,
+		country: row.country ?? "",
+		lat: row.lat,
+		lon: row.lon,
+		parent_id: row.parent_id ?? undefined,
+		score: 0,
+	}
+
+	if (distanceKm !== undefined) {
+		c.distanceKm = distanceKm
+	}
+
+	return c
+}
+
+export class WOFReverseGeocoder implements Disposable {
+	readonly #admin: DatabaseSync
+	readonly #ownsAdmin: boolean
+	readonly #polygons: DatabaseSync | null
+	readonly #ownsPolygons: boolean
+	/**
+	 * Parsed-geometry cache. Reverse queries cluster geographically (an eval run hits the same ~15 county polygons 1400
+	 * times), so caching the JSON.parse pays for itself immediately. Bounded — cleared wholesale at the cap rather than
+	 * LRU-tracked; the polygons are DP-simplified and small, the cap exists only to keep a long-lived server process
+	 * honest.
+	 */
+	readonly #geometryCache = new Map<number, GeojsonGeometry | null>()
+	static readonly #GEOMETRY_CACHE_CAP = 4096
+
+	constructor(opts: WOFReverseGeocoderOpts) {
+		if (opts.adminDatabase && opts.adminDBPath) {
+			throw new Error("WOFReverseGeocoder: pass either `adminDatabase` or `adminDBPath`, not both")
+		}
+
+		if (!opts.adminDatabase && !opts.adminDBPath) {
+			throw new Error("WOFReverseGeocoder: one of `adminDatabase` or `adminDBPath` is required")
+		}
+
+		if (opts.polygonDatabase && opts.polygonDBPath) {
+			throw new Error("WOFReverseGeocoder: pass either `polygonDatabase` or `polygonDBPath`, not both")
+		}
+
+		this.#admin = opts.adminDatabase ?? new DatabaseSync(opts.adminDBPath!, { readOnly: true })
+		this.#ownsAdmin = !opts.adminDatabase
+		this.#polygons =
+			opts.polygonDatabase ?? (opts.polygonDBPath ? new DatabaseSync(opts.polygonDBPath, { readOnly: true }) : null)
+		this.#ownsPolygons = !opts.polygonDatabase && Boolean(opts.polygonDBPath)
+
+		// Fail loudly up front — the R*Tree is a build artifact, not part of the upstream WOF
+		// distribution, and a missing index would otherwise surface as an opaque SQL error per query.
+		const hasBbox = this.#admin
+			.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+			.get(PLACE_BBOX_TABLE)
+
+		if (!hasBbox) {
+			throw new Error(
+				`WOFReverseGeocoder: the admin DB has no \`${PLACE_BBOX_TABLE}\` R*Tree. Build it with ` +
+					"`mailwoman gazetteer build fts <path-to-wof.db>` (see resolver-wof-sqlite/README.md)."
+			)
+		}
+
+		if (this.#polygons) {
+			const hasPolygons = this.#polygons
+				.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'polygons'`)
+				.get()
+
+			if (!hasPolygons) {
+				throw new Error(
+					"WOFReverseGeocoder: the polygon DB has no `polygons` table. Expected a `wof-polygons.db` " +
+						"built by scripts/build-wof-polygons.mjs."
+				)
+			}
+		}
+	}
+
+	/**
+	 * Resolve a WGS-84 point to its containing admin hierarchy. Async for symmetry with `PlaceLookup.findPlace` (the work
+	 * is sync `node:sqlite` underneath — same convention). Thin wrapper over {@link reverseGeocodeSync}.
+	 */
+	async reverseGeocode(lat: number, lon: number, opts: ReverseGeocodeOpts = {}): Promise<ReverseGeocodeResult> {
+		return this.reverseGeocodeSync(lat, lon, opts)
+	}
+
+	/**
+	 * Synchronous core of {@link reverseGeocode} — every step underneath is already sync `node:sqlite`, so this is the
+	 * REAL implementation; the async method above exists only for call-site symmetry with `PlaceLookup.findPlace`.
+	 * Exposed directly for callers that can't await mid-call (e.g. `mailwoman/poi-executor.ts`'s `createPOIExecutor`,
+	 * whose `POIIntentOutcome` return type is synchronous by contract — see `poi-intent.ts`'s `deps.execute`).
+	 */
+	reverseGeocodeSync(lat: number, lon: number, opts: ReverseGeocodeOpts = {}): ReverseGeocodeResult {
+		if (!Number.isFinite(lat) || !Number.isFinite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180) {
+			throw new RangeError(`WOFReverseGeocoder.reverseGeocode: (${lat}, ${lon}) is not a WGS-84 coordinate`)
+		}
+		const maxApproximateKm = opts.maxApproximateKm ?? DEFAULT_MAX_APPROXIMATE_KM
+		const candidates = this.#bboxCandidates(lat, lon, opts)
+
+		// PIP walk, smallest-bbox-first: the first polygon that contains the point is the deepest
+		// polygon-confirmable place. Polygon-rejected candidates are bbox false positives — dropped.
+		let winner: CandidateRow | null = null
+		let winnerConfirmed = false
+		const pointOnly: CandidateRow[] = []
+
+		for (const c of candidates) {
+			const contains = geometryContains(this.#geometry(c.id), lon, lat)
+
+			if (contains === true) {
+				winner = c
+				winnerConfirmed = true
+				break
+			}
+
+			if (contains === null) {
+				pointOnly.push(c)
+			}
+		}
+
+		if (!winner) {
+			// No polygon confirmed anywhere — nearest centroid among the polygon-less bbox candidates.
+			let bestKm = Infinity
+
+			for (const c of pointOnly) {
+				const km = haversineKm(lat, lon, c.lat, c.lon)
+
+				if (km < bestKm) {
+					bestKm = km
+					winner = c
+				}
+			}
+
+			if (!winner) return { hierarchy: [], containment: "approximate" }
+		}
+
+		// Approximate descent into finer tiers than the winner.
+		let current = winner
+		let currentConfirmed = winnerConfirmed
+		let currentDistanceKm = currentConfirmed ? undefined : haversineKm(lat, lon, current.lat, current.lon)
+
+		for (const tier of DESCENT_TIERS) {
+			if (placetypeDepth(tier) <= placetypeDepth(current.placetype)) continue
+
+			if (opts.placetypes && !opts.placetypes.includes(tier)) continue
+			const kids = this.#descendants(current.id, tier, lat, lon, maxApproximateKm)
+			let next: CandidateRow | null = null
+			let nextConfirmed = false
+			let nextKm: number | undefined
+			let bestKm = Infinity
+
+			for (const k of kids) {
+				const contains = geometryContains(this.#geometry(k.id), lon, lat)
+
+				if (contains === true) {
+					next = k
+					nextConfirmed = true
+					nextKm = undefined
+					break
+				}
+
+				if (contains === false) continue // known not-here — polygon rejected
+				const km = haversineKm(lat, lon, k.lat, k.lon)
+
+				if (km <= maxApproximateKm && km < bestKm) {
+					bestKm = km
+					next = k
+					nextConfirmed = false
+					nextKm = km
+				}
+			}
+
+			if (next) {
+				current = next
+				currentConfirmed = nextConfirmed
+				currentDistanceKm = nextKm
+			}
+			// An empty tier is NOT terminal — counties without localadmins jump straight to locality.
+		}
+
+		// Hierarchy assembly via the shared ancestor walk. If the descent crossed an ancestry gap
+		// (the deepest place's recorded lineage misses the PIP root), merge the root's own chain so
+		// region/country are always present when a polygon confirmed them.
+		const byID = new Map<number, PlaceCandidate>()
+		byID.set(current.id, toPlaceCandidate(current, currentDistanceKm))
+
+		for (const a of ancestorLineage(this.#admin, current.id)) {
+			if (!byID.has(a.id)) {
+				byID.set(a.id, { ...a, placetype: a.placetype as WOFPlacetype, country: a.country ?? "", score: 0 })
+			}
+		}
+
+		if (!byID.has(winner.id)) {
+			byID.set(winner.id, toPlaceCandidate(winner))
+
+			for (const a of ancestorLineage(this.#admin, winner.id)) {
+				if (!byID.has(a.id)) {
+					byID.set(a.id, { ...a, placetype: a.placetype as WOFPlacetype, country: a.country ?? "", score: 0 })
+				}
+			}
+		}
+		const hierarchy = [...byID.values()]
+
+		if (opts.placetypes) {
+			const allowed = new Set<string>(opts.placetypes)
+
+			for (let i = hierarchy.length - 1; i >= 0; i--) {
+				if (!allowed.has(hierarchy[i]!.placetype)) {
+					hierarchy.splice(i, 1)
+				}
+			}
+		}
+		hierarchy.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype))
+
+		return { hierarchy, containment: currentConfirmed ? "polygon" : "approximate" }
+	}
+
+	/** Bbox candidates containing the point, smallest-area-first, via the `place_bbox` R*Tree. */
+	#bboxCandidates(lat: number, lon: number, opts: ReverseGeocodeOpts): CandidateRow[] {
+		const where: string[] = [
+			"bbox.min_lat <= ?",
+			"bbox.max_lat >= ?",
+			"bbox.min_lon <= ?",
+			"bbox.max_lon >= ?",
+			"spr.is_current != 0",
+			"spr.is_deprecated = 0",
+		]
+		const params: Array<number | string> = [lat, lat, lon, lon]
+
+		if (opts.placetypes && opts.placetypes.length > 0) {
+			where.push(`spr.placetype IN (${opts.placetypes.map(() => "?").join(", ")})`)
+			params.push(...opts.placetypes)
+		}
+		params.push(opts.maxCandidates ?? DEFAULT_MAX_CANDIDATES)
+
+		return 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[]
+	}
+
+	/**
+	 * Descendants of `parentID` at one placetype tier, pre-filtered to a centroid window around the query point (a
+	 * generous 4× the approximate cap — polygon-holding children may legitimately have far centroids, e.g. a sprawling
+	 * consolidated city; the precise cap is applied per-candidate in the caller, and only to centroid-fallback steps).
+	 */
+	#descendants(
+		parentID: number,
+		placetype: string,
+		lat: number,
+		lon: number,
+		maxApproximateKm: number
+	): CandidateRow[] {
+		const windowDeg = (maxApproximateKm * 4) / 111
+
+		return 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[]
+	}
+
+	/** Parsed GeoJSON geometry for a WOF id, or null when absent / unparseable / no polygon DB. */
+	#geometry(id: number): GeojsonGeometry | null {
+		if (!this.#polygons) return null
+		const cached = this.#geometryCache.get(id)
+
+		if (cached !== undefined) return cached
+
+		if (this.#geometryCache.size >= WOFReverseGeocoder.#GEOMETRY_CACHE_CAP) {
+			this.#geometryCache.clear()
+		}
+		const row = this.#polygons.prepare(`SELECT geom FROM polygons WHERE id = ?`).get(id) as { geom: string } | undefined
+		let geometry: GeojsonGeometry | null = null
+
+		if (row) {
+			try {
+				geometry = JSON.parse(row.geom) as GeojsonGeometry
+			} catch {
+				geometry = null // malformed row — treat as no-polygon rather than failing the query
+			}
+		}
+		this.#geometryCache.set(id, geometry)
+
+		return geometry
+	}
+
+	close(): void {
+		if (this.#ownsAdmin) {
+			this.#admin.close()
+		}
+
+		if (this.#ownsPolygons) {
+			this.#polygons?.close()
+		}
+	}
+
+	[Symbol.dispose](): void {
+		this.close()
+	}
+}