@mailwoman/resolver-wof-sqlite 10.7.0 → 10.8.0

package/lib/address/point/interpolation.ts

@@ -30,7 +30,7 @@
  */
 
 import type { InterpolationLookup } from "@mailwoman/core/resolver"
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
 import type { AddressPointDatabase } from "#address/point/schema"
@@ -185,7 +185,7 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 
 	if (below && above) {
 		const t = (n - below.n) / (above.n - below.n)
-		const spanM = haversineKm(below.lat, below.lon, above.lat, above.lon) * 1000
+		const spanM = haversine(below.lat, below.lon, above.lat, above.lon) * 1000
 
 		return {
 			lat: below.lat + (above.lat - below.lat) * t,
@@ -212,8 +212,8 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 
 	const lat = far.lat + (near.lat - far.lat) * t
 	const lon = far.lon + (near.lon - far.lon) * t
-	const pairM = haversineKm(near.lat, near.lon, far.lat, far.lon) * 1000
-	const overshootM = haversineKm(lat, lon, near.lat, near.lon) * 1000
+	const pairM = haversine(near.lat, near.lon, far.lat, far.lon) * 1000
+	const overshootM = haversine(lat, lon, near.lat, near.lon) * 1000
 
 	return {
 		lat,

package/lib/address/point/spine-schema.ts

@@ -0,0 +1,59 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The shared rooftop schema with an H3 spine column and the layer-interface tables.
+ *
+ *   The OpenStreetMap and G-NAF rooftop builders write this shape. Readers of existing address points
+ *   project only the columns of `address_point` in `#address/point/schema`, so the H3 spine and the
+ *   layer-interface tables leave their query path unchanged.
+ */
+
+import { createLayerCoverageTable, createLayerManifestTable, type layerschemadatabase } from "@mailwoman/core/layers"
+import type { Kysely } from "kysely"
+
+import { ADDRESS_POINT_COLUMNS, type AddressPointTable, createAddressPointTable } from "#address/point/schema"
+
+/**
+ * Jitter-stable address/POI join cell.
+ * Matches @mailwoman/address-id.
+ */
+export const ADDRESS_POINT_H3_RESOLUTION = 9
+
+export interface SpineAddressPointTable extends AddressPointTable {
+	/**
+	 * 48-bit shortened H3 cell stored as a safe SQLite integer.
+	 */
+	h3_cell: number
+}
+
+export interface SpineAddressPointDatabase extends layerschemadatabase {
+	address_point: SpineAddressPointTable
+}
+
+/**
+ * Positional insert order: the shared address-point fields followed by the H3 spine.
+ */
+export const SPINE_ADDRESS_POINT_COLUMNS = [...ADDRESS_POINT_COLUMNS, "h3_cell"] as const
+
+/**
+ * Create the legacy-compatible domain table plus the H3 spine and the layer-interface tables.
+ */
+export async function createSpineAddressPointTables(db: Kysely<SpineAddressPointDatabase>): Promise<void> {
+	await createAddressPointTable(db)
+
+	await db.schema
+		.alterTable("address_point")
+		.addColumn("h3_cell", "integer", (column) => column.notNull())
+		.execute()
+
+	await createLayerManifestTable(db)
+	await createLayerCoverageTable(db)
+}
+
+/**
+ * Build after the bulk load so the spine index is not updated on every streaming insert.
+ */
+export async function createSpineAddressPointIndexes(db: Kysely<SpineAddressPointDatabase>): Promise<void> {
+	await db.schema.createIndex("idx_ap_h3").on("address_point").column("h3_cell").execute()
+}

package/lib/ancestry/backfill.ts

@@ -6,7 +6,8 @@
  *   Repair the truncated ancestry left by the `parent_id` closure. Must run after `populateAncestors` and before the build freezes.
  */
 
-import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst"
+import { readWOFFeature } from "@mailwoman/gazetteer/whosonfirst"
+import { hierarchyAncestorsInAnyBranch } from "@mailwoman/gazetteer/whosonfirst/hierarchy"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
 import { Globerator } from "spliterator/node/fs"
@@ -61,14 +62,6 @@ export async function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promis
 	return roots
 }
 
-// The `aid === id` check filters out a place's own `locality_id`.
-// For a neighborhood, that id identifies a real ancestor.
-function placetypeFromKey(key: string): string | null {
-	if (!key.endsWith("_id")) return null
-
-	return key.slice(0, -3)
-}
-
 /**
  * Insert missing ancestor rows for places whose ancestry chain ended before reaching a country.
  *
@@ -141,22 +134,7 @@ export async function backfillAncestorsFromHierarchy(
 			continue
 		}
 
-		const seen = new Map<number, string>()
-
-		for (const branch of hierarchy) {
-			for (const [key, val] of Object.entries(branch)) {
-				const pt = placetypeFromKey(key)
-
-				if (!pt) continue
-				const aid = Number(val)
-
-				if (!Number.isFinite(aid) || aid <= 0 || aid === id) continue
-
-				if (!seen.has(aid)) {
-					seen.set(aid, pt)
-				}
-			}
-		}
+		const seen = hierarchyAncestorsInAnyBranch(id, hierarchy)
 
 		let present = alreadyPresent.get(id)
 

package/lib/build/candidate.ts

@@ -5,6 +5,7 @@
  */
 
 import { COUNTRY_POPULATION } from "@mailwoman/codex/country"
+import { bareAdminName } from "@mailwoman/codex/country/bare-admin-names"
 import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { removePath } from "@mailwoman/core/fs/writers"
 import { stringifyJSON } from "@mailwoman/core/json"
@@ -14,6 +15,7 @@ import type { PathBuilderLike } from "path-ts"
 import { POPULATION_CORRECTIONS } from "#build/population-corrections"
 import { explodeAliasBags } from "#candidate/alias-bags"
 import { buildAncestorsSidecar } from "#candidate/ancestors/sidecar"
+import { stageBareAdminNames } from "#candidate/bare-admin-names"
 import { stageCountryDisplayNames } from "#candidate/country-display-names"
 import { foldExtract } from "#candidate/extract-fold"
 import { createCandidateFTS } from "#candidate/fts"
@@ -205,6 +207,8 @@ export interface BuildCandidateResult {
  * Builds the candidate lookup database from a WOF admin database and replaces any existing output.
  * The builder adds an FTS5 trigram index for fuzzy lookup.
  */
+// repo-health-ignore export-name-affix -- writes candidate.db, and the gazetteer
+// pipeline's buildCandidate runs a whole build around it
 export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult> {
 	const progress = opts.onProgress ?? (() => {})
 
@@ -226,7 +230,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		const c = (code || "??").toUpperCase()
 		let id = ccodes.get(c)
 
-		if (id === undefined) {
+		if (typeof id !== "number") {
 			id = ccodes.size
 			ccodes.set(c, id)
 		}
@@ -238,7 +242,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		const p = pt || ""
 		let id = ptcodes.get(p)
 
-		if (id === undefined) {
+		if (typeof id !== "number") {
 			id = ptcodes.size
 			ptcodes.set(p, id)
 		}
@@ -306,7 +310,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		const ptid = ptID(r.placetype as string | null)
 		const rid = regionOf.get(sid) ?? 0
 
-		const wofPop = r.pop === null || r.pop === undefined ? null : Number(r.pop)
+		const wofPop = r.pop === null || !r.pop ? null : Number(r.pop)
 
 		const pop =
 			POPULATION_CORRECTIONS[sid]?.population ??
@@ -406,6 +410,16 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		}).toLocaleString()} country surfaces`
 	)
 
+	progress(
+		"bare-admin-names",
+		`${stageBareAdminNames({
+			attrs,
+			iso2ByID: new Map([...ccodes].map(([code, id]) => [id, code])),
+			stageRow,
+			tx: kdb,
+		}).toLocaleString()} bare admin names`
+	)
+
 	if (opts.currencyBackfill) {
 		const nBackfill = await resurrectCurrencyHoles({
 			src,
@@ -429,14 +443,17 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 
 	progress("aliases", "exploding alias bags")
 
-	const { nAlias, keyCounts, regionOfficialRefused } = explodeAliasBags(src, kdb, attrs, stageRow, {
+	const iso2ByCountryID = new Map([...ccodes].map(([code, id]) => [id, code]))
+
+	const { nAlias, nBare, keyCounts, regionOfficialRefused } = explodeAliasBags(src, kdb, attrs, stageRow, {
 		regionPlacetypeID: ptID("region"),
 		ccID,
+		bareName: (countryID, alias) => bareAdminName(iso2ByCountryID.get(countryID) ?? "", alias),
 	})
 
 	progress(
 		"aliases",
-		`${nAlias.toLocaleString()} aliases` +
+		`${nAlias.toLocaleString()} aliases; ${nBare.toLocaleString()} bare admin aliases` +
 			(regionOfficialRefused
 				? `; ${regionOfficialRefused.toLocaleString()} region aliases refused as another region's official name`
 				: "")

package/lib/candidate/alias-bags.ts

@@ -61,9 +61,20 @@ export function explodeAliasBags(
 	out: DatabaseClient<CandidateDatabase>,
 	attrs: Map<number, PlaceAttrs>,
 	stageRow: StageRow,
-	opts: { regionPlacetypeID?: number; ccID?: (code: string | null) => number } = {}
-): { nAlias: number; keyCounts: Map<number, number>; regionOfficialRefused: number } {
+	opts: {
+		regionPlacetypeID?: number
+		ccID?: (code: string | null) => number
+		/**
+		 * The bare form of an alias in its place's country, staged as one more alias: `渋谷` for the alias `渋谷区`.
+		 *
+		 * A Japanese place's primary name is romanized, so its suffixed name reaches
+		 * the candidate only as an alias.
+		 */
+		bareName?: (countryID: number, alias: string) => string | null
+	} = {}
+): { nAlias: number; nBare: number; keyCounts: Map<number, number>; regionOfficialRefused: number } {
 	let nAlias = 0
+	let nBare = 0
 	let regionOfficialRefused = 0
 	const keyCounts = new Map<number, number>()
 
@@ -87,24 +98,31 @@ export function explodeAliasBags(
 		// includes surrounding whitespace and the last one is empty.
 		// `normalizeLocalityForKey` folds both away.
 		for (const piece of alt.split(ALIAS_SEPARATOR)) {
-			const k = normalizeLocalityForKey(piece)
+			const bare = opts.bareName?.(a.cid, piece.trim())
+			const keys = [normalizeLocalityForKey(piece), bare ? normalizeLocalityForKey(bare) : ""]
 
-			if (!k || seen.has(k)) continue
-			seen.add(k)
+			for (const [position, k] of keys.entries()) {
+				if (!k || seen.has(k)) continue
+				seen.add(k)
 
-			if (isRegion) {
-				const holder = official.get(`${a.cid}\0${k}`)
+				if (isRegion) {
+					const holder = official.get(`${a.cid}\0${k}`)
 
-				if (typeof holder === "number" && holder !== id) {
-					regionOfficialRefused++
+					if (typeof holder === "number" && holder !== id) {
+						regionOfficialRefused++
 
-					continue
+						continue
+					}
 				}
-			}
 
-			stageRow(k, a, id, 0)
+				stageRow(k, a, id, 0)
 
-			nAlias++
+				if (position) {
+					nBare++
+				} else {
+					nAlias++
+				}
+			}
 		}
 
 		keyCounts.set(id, seen.size)
@@ -112,5 +130,5 @@ export function explodeAliasBags(
 
 	out.exec("COMMIT")
 
-	return { nAlias, keyCounts, regionOfficialRefused }
+	return { nAlias, nBare, keyCounts, regionOfficialRefused }
 }

package/lib/candidate/bare-admin-names.ts

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file A candidate build pass that keys each admin place under its bare name as well as its full one.
+ */
+
+import { bareAdminName } from "@mailwoman/codex/country/bare-admin-names"
+
+import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import { normalizeLocalityForKey } from "#street/normalize"
+
+/**
+ * Stages an alias row under the bare form of every place name a country writes with an admin-unit suffix.
+ *
+ * A bare `渋谷` otherwise reaches only the places whose full name is `渋谷`, a Hyogo
+ * and a Chiba locality with no recorded population, and never Tokyo's `渋谷区`.
+ * The alias row includes the ward's own population, so the candidate ordering
+ * ranks it above the unmeasured exact matches.
+ *
+ * @returns The number of alias rows staged.
+ */
+export function stageBareAdminNames(ctx: {
+	attrs: Map<number, PlaceAttrs>
+	iso2ByID: Map<number, string>
+	stageRow: StageRow
+	tx: { exec(sql: string): void }
+}): number {
+	let staged = 0
+
+	ctx.tx.exec("BEGIN")
+
+	for (const [sid, a] of ctx.attrs) {
+		const iso2 = ctx.iso2ByID.get(a.cid)
+
+		if (!iso2) continue
+
+		const bare = bareAdminName(iso2, a.name)
+
+		if (!bare) continue
+
+		const key = normalizeLocalityForKey(bare)
+
+		if (!key || key === a.pkey) continue
+
+		ctx.stageRow(key, a, sid, 0)
+
+		staged++
+	}
+
+	ctx.tx.exec("COMMIT")
+
+	return staged
+}

package/lib/candidate/importance.ts

@@ -29,7 +29,7 @@
  *   population assigned it.
  */
 
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { PathBuilderLike } from "path-ts"
 
@@ -144,7 +144,7 @@ export class ImportanceIndex {
 		let bestKm = Infinity
 
 		for (const place of group) {
-			const km = haversineKm(lat, lon, place.lat, place.lon)
+			const km = haversine(lat, lon, place.lat, place.lon)
 
 			if (km < bestKm) {
 				bestKm = km

package/lib/candidate/lookup.ts

@@ -10,7 +10,7 @@ import { type Ancestor, type GazetteerArtifactCoverage, referentialFromPopulatio
 import { allRows } from "@mailwoman/core/utils"
 import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators"
 import { partitionByContainment } from "@mailwoman/resolver"
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup"
 
@@ -67,6 +67,18 @@ type CandidateRow = Pick<
 	// Optional because older artifacts may not include `importance`.
 	Partial<Pick<CandidateTable, "importance">>
 
+/**
+ * What a containment re-rank needs beside the rows: the keys to inject contained
+ * misses from and the shape filters the initial probe applied.
+ */
+interface ContainmentOptions {
+	nameKey: NameKey
+	strippedKey: NameKey
+	shapeFilters: string[]
+	shapeParams: Array<string | number>
+	limit: number
+}
+
 const FUZZY_FETCH = 40
 
 const WORD_FUZZY_MIN = 0.85
@@ -177,7 +189,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 			const bandIDs = [...REGION_CLASS_PLACETYPES, "country"]
 				.map((placetype) => this.#placetypeToID.get(placetype))
-				.filter((id): id is number => id !== undefined)
+				.filter((id) => typeof id === "number")
 
 			if (bandIDs.length) {
 				this.#qualifierProbe = this.database.prepare(
@@ -219,7 +231,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 		const cached = this.#intervalCache.get(sprID)
 
-		if (cached !== undefined) return cached
+		if (cached) return cached
 
 		const row = this.#intervalProbe.get(sprID) as { pre: number; post: number } | undefined
 		const label = row ? { pre: Number(row.pre), post: Number(row.post) } : null
@@ -260,23 +272,30 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 	}
 
 	/**
-	 * Apply admin-containment re-rank: stamp containment, inject contained misses,
-	 * then partition contained-first.
+	 * Apply admin-containment re-rank for a parsed region qualifier: resolve the
+	 * qualifier's region rows, then {@linkcode #applyContainment}.
 	 */
 	#applyAdminContainment(
 		rows: Array<RankedRow<CandidateRow>>,
 		qualifier: string,
 		country: string | null,
-		opts: {
-			nameKey: NameKey
-			strippedKey: NameKey
-			shapeFilters: string[]
-			shapeParams: Array<string | number>
-			limit: number
-		}
+		opts: ContainmentOptions
 	): Array<RankedRow<CandidateRow>> {
-		const qualifierIDs = this.#qualifierRegionIDs(qualifier, country)
+		return this.#applyContainment(rows, this.#qualifierRegionIDs(qualifier, country), opts)
+	}
 
+	/**
+	 * Stamp containment in the qualifier rows, inject contained misses, then partition contained-first.
+	 *
+	 * The qualifier rows are a parsed region's rows or one resolved parent place (#2804).
+	 * The injection reads the same name key under the shape filters and under the sub-locality placetypes,
+	 * so a dependent locality the locality band excludes re-enters the list when its parent contains it.
+	 */
+	#applyContainment(
+		rows: Array<RankedRow<CandidateRow>>,
+		qualifierIDs: ReadonlySet<number>,
+		opts: ContainmentOptions
+	): Array<RankedRow<CandidateRow>> {
 		if (!qualifierIDs.size) {
 			for (const row of rows) {
 				row.containedByQualifier = false
@@ -326,7 +345,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		// Also inject contained neighborhood-band namesakes (primary-keyed only).
 		const bandIDs = ["neighbourhood", "macrohood", "microhood"]
 			.map((placetype) => this.#placetypeToID.get(placetype))
-			.filter((id): id is number => id !== undefined)
+			.filter((id) => typeof id === "number")
 
 		if (bandIDs.length) {
 			const bandSQL =
@@ -375,7 +394,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 	#postcodeAnchor(postcode: string, country?: string): { lat: number; lon: number } | null {
 		const placetypeID = this.#placetypeToID.get("postalcode")
 
-		if (placetypeID === undefined) return null
+		if (typeof placetypeID !== "number") return null
 
 		const conds = ["name_key = ?", "placetype_id = ?"]
 		const params: Array<string | number> = [postcode.replaceAll(/\s+/g, ""), placetypeID]
@@ -383,7 +402,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		if (country) {
 			const countryID = this.#countryToID.get(country.toUpperCase())
 
-			if (countryID === undefined) return null // Unknown country in this artifact.
+			if (typeof countryID !== "number") return null // Unknown country in this artifact.
 			conds.push("country_id = ?")
 			params.push(countryID)
 		}
@@ -457,7 +476,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		if (query.country) {
 			const cid = this.#countryToID.get(query.country.toUpperCase())
 
-			if (cid === undefined) return [] // Unknown country in this artifact.
+			if (typeof cid !== "number") return [] // Unknown country in this artifact.
 			filters.push("country_id = ?")
 			filterParams.push(cid)
 		}
@@ -468,7 +487,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 			const ids = expandPlacetypeFilter(want as readonly string[])
 				.map((t) => this.#placetypeToID.get(t))
-				.filter((v): v is number => v !== undefined)
+				.filter((v) => typeof v === "number")
 
 			if (!ids.length) return []
 			shapeFilters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`)
@@ -599,7 +618,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 				const outsideThreshold: RankedRow<CandidateRow>[] = []
 
 				for (const row of rows) {
-					const distanceKm = haversineKm(anchor.lat, anchor.lon, Number(row.latitude), Number(row.longitude))
+					const distanceKm = haversine(anchor.lat, anchor.lon, Number(row.latitude), Number(row.longitude))
 
 					if (distanceKm <= POSTCODE_CONTAINMENT_THRESHOLD_KM) {
 						insideThreshold.push({ row, distanceKm })
@@ -617,14 +636,23 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		}
 
 		// Admin-containment re-rank runs last.
+		const containmentOptions: ContainmentOptions = {
+			nameKey,
+			strippedKey: normalizeLocalityForKey(stripLocalityQualifier(text)),
+			shapeFilters,
+			shapeParams,
+			limit,
+		}
+
 		if (query.regionQualifier?.trim() && this.#qualifierProbe && this.#wantsLocality(query.placetype)) {
-			rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country ?? null, {
-				nameKey,
-				strippedKey: normalizeLocalityForKey(stripLocalityQualifier(text)),
-				shapeFilters,
-				shapeParams,
-				limit,
-			})
+			rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country ?? null, containmentOptions)
+		} else if (
+			typeof query.parentQualifierID === "number" &&
+			this.#ancestorsProbe &&
+			this.#wantsLocality(query.placetype)
+		) {
+			// A resolved parent qualifies by id, so no name probe runs (#2804).
+			rows = this.#applyContainment(rows, new Set([query.parentQualifierID]), containmentOptions)
 		}
 
 		const candidates = rows.map((row): PlaceCandidate => {

package/lib/candidate/own-name.ts

@@ -114,11 +114,7 @@ export function romanizeNameKey(key: string): string | null {
 		out += CYRILLIC_TO_LATIN[ch] ?? ch
 	}
 
-	out = out
-		.normalize("NFD")
-		.replaceAll(/[̀-ͯ]/g, "")
-		.replaceAll(/\s+/g, " ")
-		.trim()
+	out = out.normalize("NFD").replaceAll(/[̀-ͯ]/g, "").replaceAll(/\s+/g, " ").trim()
 
 	return /^[a-z0-9 ]*$/.test(out) ? out : null
 }

package/lib/candidate/scoring.ts

@@ -5,7 +5,7 @@
  */
 
 import { compareReferential, referentialFromPopulation } from "@mailwoman/core/resolver"
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 import { exactMatchIDs, officialNameIDs } from "#exact-match"
@@ -47,7 +47,7 @@ export function candidateFromSearchRow(
 		score += weights.countryMatchBoost
 	}
 
-	if (query.parentID !== undefined) {
+	if (query.parentID) {
 		score += row.parent_id === query.parentID ? weights.directChildBoost : weights.descendantBoost
 	}
 
@@ -74,7 +74,7 @@ export function candidateFromSearchRow(
 		let scoreTerm = 0
 
 		for (const h of hints) {
-			const d = haversineKm(h.lat, h.lon, row.lat, row.lon)
+			const d = haversine(h.lat, h.lon, row.lat, row.lon)
 			const decay = h.weight / (1 + d / weights.proximityScaleKm)
 			const prom = decay * weights.biasBoost
 
@@ -184,7 +184,7 @@ export function rankCandidates<DB>(
 							.map((c) => c.id as number),
 						query.text
 					)
-				: undefined
+				: null
 
 			const kind = (c: PlaceCandidate): number => {
 				if (!exactIDs.has(c.id as number)) return 0

package/lib/capitals.ts

@@ -15,7 +15,7 @@
  *   radius a centroid-drift allowance rather than a catchment.
  */
 
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 
 import { normalizeLocalityForKey } from "#street/normalize"
 
@@ -129,7 +129,7 @@ export class CapitalIndex {
 			if (
 				point.level > best &&
 				point.keys.has(key) &&
-				haversineKm(latitude, longitude, point.latitude, point.longitude) <= CAPITAL_MATCH_RADIUS_KM
+				haversine(latitude, longitude, point.latitude, point.longitude) <= CAPITAL_MATCH_RADIUS_KM
 			) {
 				best = point.level
 			}

package/lib/coincident-roles.ts

@@ -38,7 +38,7 @@
 
 import type { CoincidentLocality } from "@mailwoman/core/resolver"
 import { allRows } from "@mailwoman/core/utils"
-import { haversineKm } from "@mailwoman/spatial"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
 
@@ -190,8 +190,8 @@ export function buildCoincidentRoles(
 
 	try {
 		for (const c of candidates) {
-			const dist = haversineKm(c.rlat, c.rlon, c.llat, c.llon)
-			const diag = haversineKm(c.min_latitude, c.min_longitude, c.max_latitude, c.max_longitude)
+			const dist = haversine(c.rlat, c.rlon, c.llat, c.llon)
+			const diag = haversine(c.min_latitude, c.min_longitude, c.max_latitude, c.max_longitude)
 			const tolerance = Math.max(toleranceFraction * diag, minToleranceKm)
 
 			if (dist > tolerance) continue

package/lib/currency-backfill.ts

@@ -7,8 +7,8 @@
  */
 
 import { pathExists } from "@mailwoman/core/fs/readers/stat"
-import { isStrictlyFiner } from "@mailwoman/core/resources/whosonfirst"
-import { haversineKm } from "@mailwoman/spatial"
+import { isStrictlyFiner } from "@mailwoman/gazetteer/whosonfirst"
+import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { type PathBuilderLike, resolvePath } from "path-ts"
 import { TSVSpliterator } from "spliterator"
@@ -208,7 +208,7 @@ export async function resurrectCurrencyHoles(ctx: {
 			// A live row blocks unless it is strictly finer than the dead one.
 			// An unranked placetype also blocks because the failure mode is inventing a place.
 			const liveNear = liveStmt.all(cc, name).some((row) => {
-				if (haversineKm(dLat, dLon, Number(row.latitude), Number(row.longitude)) > CURRENCY_BACKFILL_RADIUS_KM) {
+				if (haversine(dLat, dLon, Number(row.latitude), Number(row.longitude)) > CURRENCY_BACKFILL_RADIUS_KM) {
 					return false
 				}
 
@@ -222,7 +222,7 @@ export async function resurrectCurrencyHoles(ctx: {
 			}
 
 			const near = (attestors.get(pkey) ?? []).filter(
-				(g) => haversineKm(dLat, dLon, g.lat, g.lon) <= CURRENCY_BACKFILL_RADIUS_KM
+				(g) => haversine(dLat, dLon, g.lat, g.lon) <= CURRENCY_BACKFILL_RADIUS_KM
 			)
 
 			if (!near.length) {

package/lib/fst/autocomplete.ts

@@ -135,7 +135,7 @@ class FSTReader implements AncestrieReaderLike<PlaceEntry> {
 
 	entriesAt(stateID: number, limit?: number): AncestrieRecord<PlaceEntry>[] {
 		const places = this.#fst.accepting(stateID)
-		const selected = limit === undefined ? places : topByReferential(places, limit)
+		const selected = typeof limit !== "number" ? places : topByReferential(places, limit)
 
 		return selected.map((entry) => {
 			this.#chains.set(entry.wofID, entry.parentChain)