@mailwoman/resolver-wof-sqlite 10.7.0 → 11.0.0

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(",")})`)
@@ -534,16 +553,19 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 				}
 			}
 
-			// Typo-tolerant fallback for true name misses only, skipping postcodes and respecting the fuzzy-country scope.
+			// Typo-tolerant fallback for true name misses only, skipping postcodes.
+			// With no stated country, locale hint or parent to search within,
+			// a correction keeps its first letter.
+			// `Aucklnad` reaches Auckland, and `Anal Island` stays away from `Capual Island` in the Philippines.
 			const fuzzyCountryID =
 				!query.country && query.fuzzyCountry ? this.#countryToID.get(query.fuzzyCountry.toUpperCase()) : undefined
 
-			const fuzzyScopedOut = !query.country && !!query.fuzzyCountry && typeof fuzzyCountryID !== "number"
+			const hasCountryEvidence = !!query.country || regionID !== null || typeof fuzzyCountryID === "number"
 
 			if (
 				!rows.length &&
 				!wantsPostcode &&
-				!fuzzyScopedOut &&
+				!(query.fuzzyCountry && !query.country && typeof fuzzyCountryID !== "number") &&
 				this.#ftsProbe &&
 				this.#nameKeyExistsProbe &&
 				!this.#nameKeyExistsProbe.get(nameKey)
@@ -555,7 +577,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 					const ranked = hits
 						.map((h) => ({ nk: String(h.name_key), s: wordFuzzySimilarity(nameKey, String(h.name_key)) }))
-						.filter((h) => h.s >= WORD_FUZZY_MIN)
+						.filter((h) => h.s >= WORD_FUZZY_MIN && (hasCountryEvidence || h.nk[0] === nameKey[0]))
 						// 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.s - a.s)
 
@@ -599,7 +621,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 +639,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 => {
@@ -656,6 +687,8 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 				variantAliasExempted: row.variantExempted ? true : null,
 
+				matchedAlias: row.is_primary === 0 ? true : null,
+
 				population: hasPopulation ? row.population : null,
 				referential: hasPopulation ? referentialFromPopulation(row.population) : null,
 				encyclopedic: null,

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/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)