@mailwoman/resolver-wof-sqlite 9.1.0 → 9.2.0

package/street-normalize.ts

@@ -23,6 +23,37 @@
  */
 
 import { AbbreviationToDirectional, US_STREET_SUFFIX_LOOKUP } from "@mailwoman/codex/us"
+import type { Tagged } from "type-fest"
+
+/**
+ * A place name folded by {@link normalizeLocalityForKey} — the value stored in, and required to probe, every
+ * `name_key`-style column: the candidate gazetteer, the postal-city side-index, the street-centroid shard, an ancestor
+ * chain's `parent_name_key`, and the address-point locality scope.
+ *
+ * The brand is here because the fold is applied at BUILD time and is therefore mandatory at QUERY time, while a
+ * near-miss approximation of it (`toLowerCase()`, `trim()`) is still a `string`: it binds to the parameter, returns
+ * fewer rows, and the shortfall reads as a coverage gap in the data rather than a defect in the probe. Requiring the
+ * brand at the seam turns that silent under-match into a compile error. Mint one only by calling the fold.
+ */
+export type NameKey = Tagged<string, "NameKey">
+
+/**
+ * A street name folded by {@link normalizeStreetForKey} / {@link normalizeStreetForKeyLocale} — the value stored in a
+ * `street_norm` address-point column and required to probe it.
+ *
+ * Distinct from {@link RouteKey}: the route fold is a FURTHER canonicalization applied to some columns and not others,
+ * so the two are not interchangeable even though both are folded streets.
+ */
+export type StreetKey = Tagged<string, "StreetKey">
+
+/**
+ * A street key that has additionally passed {@link canonicalizeRouteKey} — the numbered-route canonical form.
+ *
+ * A separate brand from {@link StreetKey} because it identifies a DIFFERENT set of columns, and the two folds disagree
+ * exactly on the rows that motivate the route fold: binding a plain street key to a route-folded column silently misses
+ * every row whose source spelled the route differently, which is the miss class the fold exists to close.
+ */
+export type RouteKey = Tagged<string, "RouteKey">
 
 /**
  * Token count a street must exceed before its trailing pair is merged. At or below it the pair IS the whole street
@@ -86,10 +117,10 @@ function fold(input: string): string {
  * Normalize a street name for address-point keying. Same function at build time and lookup time — see module docstring
  * for the contract.
  */
-export function normalizeStreetForKey(street: string): string {
+export function normalizeStreetForKey(street: string): StreetKey {
 	const tokens = fold(street).split(" ")
 
-	if (!tokens.length) return ""
+	if (!tokens.length) return "" as StreetKey
 
 	// Spelled-ordinal street names → digit form when a street suffix follows ("Tenth Street" →
 	// "10th street", #723). Gated on the next token being a suffix so ordinal-WORD names are untouched.
@@ -151,7 +182,7 @@ export function normalizeStreetForKey(street: string): string {
 		}
 	}
 
-	return tokens.join(" ")
+	return tokens.join(" ") as StreetKey
 }
 
 /**
@@ -162,7 +193,7 @@ export function normalizeStreetForKey(street: string): string {
  * article, so no salient-token / multi-key index is built yet (deferred until probing shows the normalizer can't absorb
  * the false-negatives).
  */
-export type StreetLocale = "us" | "en" | "fr" | "de" | "nl"
+export type StreetLocale = "us" | "en" | "fr" | "de" | "nl" | "pl" | "vn" | "id"
 
 /**
  * French street-type abbreviations → canonical full form, applied per token after {@link fold}. French address types
@@ -191,6 +222,25 @@ const FR_STREET_ABBREV = new Map<string, string>([
 	["sts", "saints"],
 ])
 
+/**
+ * Polish leading street-type tokens, STRIPPED rather than expanded. Measured on the 5.56M-row PL OSM shard
+ * (2026-08-19): OSM Poland tags `addr:street` BARE — `ulica%` covers 22 rows and `ul.%` eight, so an EXPANSION rule
+ * makes a typed query ("ul. Świętokrzyska" → "ulica swietokrzyska") miss the 3,846 bare "swietokrzyska" rows. Stripping
+ * the leading type on BOTH sides keys typed and bare surfaces identically. The full words are stripped too: the
+ * aleja/plac/osiedle populations (48,597 / 26,815 / 39,552 rows) spell the word out, and "Plac Zamkowy" must key the
+ * same as a query's "plac zamkowy" or bare "Zamkowy". Never stripped when it is the only token.
+ */
+const PL_LEADING_TYPE = new Set(["ul", "ulica", "al", "aleja", "aleje", "pl", "plac", "os", "osiedle"])
+
+/**
+ * Indonesian street-type abbreviations → canonical full form, leading position ("Jl. Thamrin", "Gg. Waru").
+ */
+const ID_STREET_ABBREV = new Map<string, string>([
+	["jl", "jalan"],
+	["jln", "jalan"],
+	["gg", "gang"],
+])
+
 /**
  * Normalize a street name for the address-point key in a non-US locale. Same function build-side and probe-side (the
  * one-function discipline). US delegates to {@link normalizeStreetForKey}.
@@ -200,17 +250,32 @@ const FR_STREET_ABBREV = new Map<string, string>([
  * - **de** — fold + ß→ss + canonicalize the GLUED `-str(.)` suffix to `-strasse` ("Lindenstr." → "lindenstrasse",
  *   "Lindenstraße" → "lindenstrasse"); an already-full "-strasse" is left intact.
  * - **nl** — fold + canonicalize the glued `-str` suffix to `-straat` ("Kerkstr." → "kerkstraat").
+ * - **pl** — fold + ł→l (Ł does not NFKD-decompose, so the generic fold keeps it and an undiacritized query would miss;
+ *   every other Polish diacritic is a combining form the fold already strips) + STRIP the leading type token — see
+ *   {@link PL_LEADING_TYPE} for the measured reason expansion was wrong for this source.
+ * - **vn** — fold + đ→d AND ð→d (both non-decomposing, and OSM mixes the two codepoints inside single values — see the
+ *   branch comment). Deliberately NO type-abbreviation map yet: the common abbreviation is the single letter "Đ." for
+ *   Đường, and expanding a bare folded "d" token would rewrite initials — measure the miss rate on the built shard
+ *   before adding anything.
+ * - **id** — fold + expand leading type abbreviations (jl/jln→jalan, gg→gang); Indonesian street surfaces are otherwise
+ *   ASCII-clean.
  */
-export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale): string {
+export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale): StreetKey {
 	if (locale === "us" || locale === "en") return normalizeStreetForKey(street)
 
 	// Hyphen → space so a compound name keys the same whether the source or the query writes the
 	// hyphen ("Champs-Élysées", "St-Honoré") or a space — both sides fold identically, so this is pure
 	// robustness. It also splits a hyphenated abbreviation ("St-Honoré" → "st honore") into tokens the
-	// per-locale type/Saint map can see.
-	const tokens = fold(street).replaceAll("ß", "ss").replaceAll("-", " ").split(/\s+/).filter(Boolean)
+	// per-locale type/Saint map can see. Letter maps for non-decomposing letters (ß, ł, đ) live in the
+	// per-locale branches, NEVER here: widening the shared pipeline would silently change keys under
+	// every already-built shard of the other locales.
+	const tokens = fold(street)
+		.replaceAll("ß", "ss")
+		.replaceAll("-", " ")
+		.split(/\s+/)
+		.filter((value) => value.length > 0)
 
-	if (!tokens.length) return ""
+	if (!tokens.length) return "" as StreetKey
 
 	switch (locale) {
 		case "fr":
@@ -236,16 +301,69 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 				}
 			}
 			break
+		case "pl":
+			for (let i = 0; i < tokens.length; i++) {
+				tokens[i] = tokens[i]!.replaceAll("ł", "l")
+			}
+
+			if (tokens.length > 1 && PL_LEADING_TYPE.has(tokens[0]!)) {
+				tokens.shift()
+			}
+			break
+		case "id":
+			for (let i = 0; i < tokens.length; i++) {
+				tokens[i] = ID_STREET_ABBREV.get(tokens[i]!) ?? tokens[i]!
+			}
+			break
+		case "vn":
+			// đ (U+0111, d-with-stroke) AND ð (U+00F0, eth): OSM Vietnamese data mixes the two visually
+			// identical codepoints inside single values — the 2026-08-19 shard measured `Đường Trần Hưng
+			// Đạo` carrying d-with-stroke at the front and ETH in `Đạo`, splitting the country's most
+			// common street into two keys with the MAJORITY variant (630 vs 421 rows) unreachable by a
+			// correctly-typed query. No abbreviation map — see the locale table.
+			for (let i = 0; i < tokens.length; i++) {
+				tokens[i] = tokens[i]!.replaceAll("đ", "d").replaceAll("ð", "d")
+			}
+			break
 	}
 
-	return tokens.join(" ")
+	return tokens.join(" ") as StreetKey
 }
 
 /**
  * Normalize a locality name for address-point keying (fold only — no street semantics).
  */
-export function normalizeLocalityForKey(locality: string): string {
-	return fold(locality)
+export function normalizeLocalityForKey(locality: string): NameKey {
+	return fold(locality) as NameKey
+}
+
+/**
+ * Leading French street-type token. French types LEAD the name ("avenue du Parc", "boul Saint-Laurent") while English
+ * types TRAIL ("Fifth Avenue", "Grosvenor Place"), so a leading type-token is the discriminating signal — "1 Avenue NE"
+ * starts with a digit and never matches. The separator lookahead is explicit rather than `\b` because a word boundary
+ * after an accented final letter ("carré") is not one to an ASCII-word `\b`.
+ */
+const FRENCH_LEAD_TYPE =
+	/^(?:rue|ruelle|av|ave|avenue|boul|bd|boulevard|ch|che|chemin|all[ée]e|imp|impasse|mont[ée]e|c[ôo]te|pl|place|prom|promenade|rang|rte|route|autoroute|carr[eé]|croissant|terrasse|sentier)(?=[\s.-]|$)/i
+
+/**
+ * Surface-driven street-locale ROUTER for bilingual shards — the Québec finishing move on the CA rooftop shard.
+ *
+ * A country registers ONE street locale, but Canada's street surfaces are two languages: under the `en` rules a French
+ * surface passes through mostly unchanged (both sides fold identically, so those rows stay reachable), and what breaks
+ * is abbreviation variance — the `en` rules cannot fold "boul"/"Ste-" to the full French word, so an abbreviated query
+ * misses a full-word row and vice versa. Routing on the SURFACE (not the province) also carries bilingual NB and the
+ * French street names outside Québec for free.
+ *
+ * ONE function, called by the shard BUILDER and the query PROBE alike — the #861 discipline: routing is part of the
+ * fold contract, and two transcriptions of this predicate would diverge exactly where it matters. Only an `en` base
+ * re-routes: a `fr`/`de`/`nl` shard already speaks its own rules, and the US pipeline stays untouched.
+ *
+ * Measured basis (CA shard, 2026-08-19): 183,963 distinct surfaces, 43,762 French-lead; 29,682 fold differently under
+ * fr-vs-en (888,265 rows), and the non-French half of those are English surfaces this router keeps on `en` unchanged.
+ */
+export function streetLocaleForSurface(street: string, base: StreetLocale): StreetLocale {
+	return base === "en" && FRENCH_LEAD_TYPE.test(street.trimStart()) ? "fr" : base
 }
 
 /**
@@ -254,12 +372,13 @@ export function normalizeLocalityForKey(locality: string): string {
  * only French communes subdivided into _arrondissements municipaux_; a national register (BAN) names each row per
  * arrondissement, but a query names the base commune ("Place Bellecour, Lyon", never "…, Lyon 2e"). Applied on BOTH
  * sides of the #1042 street-centroid key — build-side (deriving the `locality_base` column) and query-side (folding the
- * probe commune) — so the two agree by construction (the one-function discipline). Input must already be folded
- * (lower-case, diacritic-stripped); a no-op for every other commune. Returns the input unchanged if the strip would
- * empty it.
+ * probe commune) — so the two agree by construction (the one-function discipline). The {@link NameKey} parameter is the
+ * enforcement of "must already be folded": stripping an arrondissement off an unfolded surface yields a key neither
+ * side stores. A no-op for every other commune, and the strip leaves a fold fixed point, so the result is still a
+ * {@link NameKey}. Returns the input unchanged if the strip would empty it.
  */
-export function stripArrondissement(localityNorm: string): string {
-	const stripped = localityNorm.replace(/\s+\d+(?:er|e)\s+arrondissement$/, "").trim()
+export function stripArrondissement(localityNorm: NameKey): NameKey {
+	const stripped = localityNorm.replace(/\s+\d+(?:er|e)\s+arrondissement$/, "").trim() as NameKey
 
 	return stripped || localityNorm
 }
@@ -284,10 +403,43 @@ export function stripLocalityQualifier(locality: string): string {
 		s = s.split("/")[0]!.trim()
 	}
 
-	// "Kraubath/Mur", "St.Kanzian/Klopeiner See"
-	s = s.replace(/\s+[a-zà-ÿ]\.\s*\S.*$/iu, "") // abbreviated " b.Graz" / " o.Bleiburg" / " a.d. …"
-	s = s.replace(/\s+(im|an der|ob|bei|in der|unter|vor)\s+\S.*$/iu, "") // " im Simmental", " bei Graz"
-	s = s.replace(/\s+(S|N|E|W|V|Ø|Sø|Fyn|Thy|Sjælland|Jylland|[A-ZÅÄÖ]{2})$/u, "") // " S", " VD", " Thy"
+	const words = [...s.matchAll(/\S+/gu)].map((match) => ({ value: match[0], index: match.index }))
+	let qualifierStart: number | undefined
+
+	for (let index = 1; index < words.length; index++) {
+		const word = words[index]!
+		const first = word.value[0] ?? ""
+		const abbreviated = /[a-zà-ÿ]/iu.test(first) && word.value[1] === "." && word.value.length > 2
+		const oneWordQualifier = ["im", "ob", "bei", "unter", "vor"].includes(word.value.toLowerCase())
+
+		const twoWordQualifier =
+			["an", "in"].includes(word.value.toLowerCase()) && words[index + 1]?.value.toLowerCase() === "der"
+
+		const hasQualifierValue = oneWordQualifier ? index + 1 < words.length : index + 2 < words.length
+
+		if (abbreviated || ((oneWordQualifier || twoWordQualifier) && hasQualifierValue)) {
+			qualifierStart = word.index
+
+			break
+		}
+	}
+
+	const suffix = words.at(-1)
+
+	if (
+		qualifierStart === undefined &&
+		suffix &&
+		words.length > 1 &&
+		(["S", "N", "E", "W", "V", "Ø", "Sø", "Fyn", "Thy", "Sjælland", "Jylland"].includes(suffix.value) ||
+			/^[A-ZÅÄÖ]{2}$/u.test(suffix.value))
+	) {
+		qualifierStart = suffix.index
+	}
+
+	if (qualifierStart !== undefined) {
+		s = s.slice(0, qualifierStart).trimEnd()
+	}
+
 	s = s.trim()
 
 	return s === locality.trim() ? "" : s
@@ -309,10 +461,87 @@ export function stripLocalityQualifier(locality: string): string {
  * is ambiguous (designator unknown) and it stays unfolded — a bare-route query therefore misses rather than guessing a
  * designator.
  */
-export function canonicalizeRouteKey(streetNorm: string): string {
+export function canonicalizeRouteKey(streetNorm: StreetKey): RouteKey {
 	const match = /^(us|state|[a-z]{2}) (?:route|rte|rt|highway|hwy) (\d.*)$/.exec(streetNorm)
 
-	if (!match) return streetNorm
+	// A street naming no route is already its own route key. {@link StreetKey} and {@link RouteKey} are
+	// SIBLING brands rather than nested ones — precisely so neither column accepts the other's key — so
+	// re-minting here is an explicit hop through the unbranded string.
+	if (!match) return streetNorm as string as RouteKey
+
+	return `${match[1] === "us" ? "us" : "state"} route ${match[2]}` as RouteKey
+}
+
+/**
+ * The canonical street-type words (lowercase) — the VALUE side of the codex suffix table. Membership means "this
+ * normalized token is a fully-spelled street type" ("place", "street", "road" …), which is how the doubled-type
+ * collapse below recognizes its shape without any parse-tree knowledge.
+ */
+const CANONICAL_TYPE_WORDS: ReadonlySet<string> = new Set(
+	[...US_STREET_SUFFIX_LOOKUP.values()].map((v) => v.toLowerCase())
+)
+
+/**
+ * Ordered lookup-key variants for a US/EN street span — the primary normalized key first, then the null-only recovery
+ * forms a reader may probe when the primary misses. Two register mismatches motivate them, both measured on live
+ * queries (2026-08-14):
+ *
+ * - **Doubled type** — a user types the type twice ("Saint Pauls PL St"), and the normalizer canonicalizes only the LAST
+ *   type token, leaving `saint pauls pl street`, which matches nothing anywhere. The signature is visible in the key
+ *   itself: a canonical type word in last position DIRECTLY after an uncanonicalized type abbreviation. The variant
+ *   drops the trailing word and canonicalizes what remains (`saint pauls place`). A street genuinely named with two
+ *   types keys identically on both sides and is caught by the primary probe first.
+ * - **Saint↔St register split** — the artifacts preserve each SOURCE's spelling (NYC situs keys `st pauls place`, Nassau
+ *   keys `saint pauls place`), and a query arrives in whichever register the user typed. A leading `saint` or `st`
+ *   token is swapped for its sibling; leading position only — a leading `st` is always the hagionym in US street names,
+ *   and interior tokens ("Mount Saint Helens Dr") are out of scope until measured.
+ *
+ * Deduplicated and ordered most-literal-first, so probing the list in order preserves the primary key's precedence.
+ */
+export function streetKeyVariants(street: string, locale: StreetLocale = "us"): StreetKey[] {
+	const primary = locale === "us" ? normalizeStreetForKey(street) : normalizeStreetForKeyLocale(street, locale)
+	const variants: StreetKey[] = primary ? [primary] : []
+
+	if (!primary || (locale !== "us" && locale !== "en")) return variants
+
+	const tokens = primary.split(" ")
+	const last = tokens.at(-1)
+	const secondLast = tokens.at(-2)
+
+	if (
+		tokens.length > 2 &&
+		last &&
+		secondLast &&
+		CANONICAL_TYPE_WORDS.has(last) &&
+		!CANONICAL_TYPE_WORDS.has(secondLast) &&
+		US_STREET_SUFFIX_LOOKUP.has(secondLast)
+	) {
+		const collapsed = normalizeStreetForKey(tokens.slice(0, -1).join(" "))
+
+		if (collapsed && !variants.includes(collapsed)) {
+			variants.push(collapsed)
+		}
+	}
+
+	// Snapshot before the swap pass — it appends while reading, and iterating the live array would
+	// re-visit its own additions.
+	const preSwap = variants.slice()
+
+	for (const variant of preSwap) {
+		const [head, ...rest] = variant.split(" ")
+		const swapped = head === "saint" ? "st" : head === "st" ? "saint" : null
+
+		if (swapped && rest.length) {
+			// Substituting a leading hagionym token in an already-normalized key leaves a fold fixed point —
+			// the suffix pass never rewrites position 0 — so the swap yields a {@link StreetKey} without
+			// re-folding.
+			const candidate = [swapped, ...rest].join(" ") as StreetKey
+
+			if (!variants.includes(candidate)) {
+				variants.push(candidate)
+			}
+		}
+	}
 
-	return `${match[1] === "us" ? "us" : "state"} route ${match[2]}`
+	return variants
 }

package/street-segment-schema.ts

@@ -17,6 +17,8 @@
 
 import type { Kysely } from "kysely"
 
+import type { RouteKey } from "./street-normalize.ts"
+
 /**
  * One TIGER street-segment edge: a `(from_hn, to_hn)` house-number range on one `side` of a named street, with the
  * geometry the interpolator walks. `min_hn`/`max_hn` are the sorted bounds (the probe filters on them); `parity` is
@@ -24,9 +26,12 @@ import type { Kysely } from "kysely"
  */
 export interface StreetSegmentTable {
 	/**
-	 * Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key.
+	 * `canonicalizeRouteKey(normalizeStreetForKey(street))` — the build/query-consistent probe key. The column NAME says
+	 * `street_norm`, but the value carries the route fold on top of the street fold, which is why the brand is
+	 * {@link RouteKey}: builder and probe both apply both folds, and a plain street key bound here misses every
+	 * numbered-route row.
 	 */
-	street_norm: string
+	street_norm: RouteKey
 	/**
 	 * `L` or `R` — the TIGER side the address range sits on.
 	 */

package/types.ts

@@ -39,7 +39,7 @@ export type WOFPlacetype =
  * treat it as ordinal, not absolute.
  *
  * `id` is the WOF place id. It's named generically (not `wof_id`) so the shape stays structurally compatible with
- * `@mailwoman/resolver`'s `ResolvedPlace` — `WOFSqlitePlaceLookup` satisfies the generic `ResolverBackend` contract
+ * `@mailwoman/resolver`'s `ResolvedPlace` — `WOFSQLitePlaceLookup` satisfies the generic `ResolverBackend` contract
  * without an adapter shim.
  *
  * `distanceKm` is populated only when the query carried `near` (and the place has a centroid). Useful for downstream
@@ -122,6 +122,14 @@ export interface PlaceCandidate {
 	 * the falsehood-detection differentiator.
 	 */
 	mismatch?: boolean
+	/**
+	 * Admin-containment stamp (#1717 stage 2) — TRI-STATE, mirroring `ResolvedPlace.containedByQualifier` in
+	 * `@mailwoman/core`: `true` = the ancestors sidecar vouches this candidate sits under the query's
+	 * {@link FindPlaceQuery.regionQualifier}; `false` = evaluated and not vouched for; absent = never evaluated (no
+	 * qualifier on the query, or an artifact without the sidecar). Absence is load-bearing — the resolver walk reads it
+	 * as `unavailable`, never as "not contained".
+	 */
+	containedByQualifier?: boolean
 }
 
 /**
@@ -163,6 +171,24 @@ export interface FindPlaceQuery {
 	 * ISO 3166-1 alpha-2 — narrows to one country.
 	 */
 	country?: string
+	/**
+	 * ISO 3166-1 alpha-2 — narrows the TYPO-FUZZY tier only (#1585). Exact and qualifier-strip probes stay worldwide (a
+	 * locale hint is a prior, never a hard filter on exact matches), but a typo CORRECTION into a different country's
+	 * namespace is nearly always a scrape, so the corrected-key probes honor this scope and a scoped-empty ABSTAINS
+	 * rather than falling through to a world-fuzzy candidate. Ignored when `country` is set (already narrower).
+	 */
+	fuzzyCountry?: string
+	/**
+	 * Restrict name matching to PRIMARY-keyed rows (#1632) — set by probes whose surface is a RE-READING (a token cut out
+	 * of a longer classified span), which never named an alias. See the ResolverBackend contract in
+	 * `@mailwoman/core/resolver`.
+	 */
+	primaryOnly?: boolean
+	/**
+	 * Alias-row NAME ROLES the probe refuses to answer through (#1730) — the bare-toponym side races pass `abbr`/`gloss`.
+	 * Role-NULL alias rows (the exonym tier) stay open; backends/artifacts without a role column ignore it.
+	 */
+	excludeNameRoles?: readonly string[]
 	/**
 	 * WOF place id — narrows to descendants of this place.
 	 */
@@ -181,6 +207,14 @@ export interface FindPlaceQuery {
 	 * → the population-first order is untouched (byte-identical).
 	 */
 	postcodeContainmentCoherence?: boolean
+	/**
+	 * The tree's parsed REGION qualifier (#1717 stage 2) — set by the resolver on locality lookups when
+	 * `ResolveOpts.adminContainmentRerank` is on. See the `ResolverBackend` contract in `@mailwoman/core/resolver`: a
+	 * capable backend stamps `containedByQualifier`, ranks contained candidates first, and may ADD contained same-key
+	 * candidates a country scope hid — additive only, never a filter. Ignored on an artifact without the ancestors
+	 * sidecar (candidates then carry no stamp).
+	 */
+	regionQualifier?: string
 	/**
 	 * Proximity hint — candidates close to this point get a ranking boost.
 	 */

package/unified-schema.ts

@@ -7,7 +7,7 @@
  *   (`scripts/build-unified-wof.ts`). This is the CANONICAL gazetteer — we never use the
  *   off-the-shelf geocode.earth prebuilt dumps (they assign different WOF ids to the same place;
  *   see the `feedback-custom-wof-db-only` memory). The table/column names match the resolver's
- *   expectations (`lookup.ts`) so `WOFSqlitePlaceLookup` works unchanged, INCLUDING the `ancestors`
+ *   expectations (`lookup.ts`) so `WOFSQLitePlaceLookup` works unchanged, INCLUDING the `ancestors`
  *   table (which lookup.ts's parent-constraint subquery needs) — see `populateAncestors`. The
  *   `place_search` FTS5 + `place_bbox` R*Tree are built separately by `build-fts` (fts.ts).
  */

package/uprn-lookup.ts

@@ -0,0 +1,210 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node reader for `uprn.db` — the OS Open UPRN layer (`uprn-schema.ts`). Two probes:
+ *
+ *   - **`coordinateOf(uprn)`**: rowid B-tree hit on the `uprn` integer PK.
+ *   - **`nearestUPRN(lat, lon, radiusM)`**: bounded nearest-point search over the res-9 `h3_cell`
+ *     index — ring-by-ring `gridDisk` expansion with chunked `IN` probes and haversine ranking.
+ *     Rings stop as soon as geometry proves no unprobed cell could beat the best hit — a distance
+ *     bound, not POILookup's row-count accumulation, so the early exit can never strand a nearer
+ *     point in an unprobed ring.
+ *
+ *   ## `null` is a claim, scoped by coverage
+ *
+ *   OS designates Open UPRN complete for GB (every UPRN in AddressBase Premium with geometry), and
+ *   the builder writes `layer_coverage` with basis `designated` for every cell the product touches.
+ *   So a `null` from either probe inside a covered cell is evidence of absence — "no such published
+ *   GB UPRN" / "no UPRN within the radius". Outside coverage (Northern Ireland, the Isle of Man, the
+ *   Channel Islands, open water) it is UNKNOWN, per the meaning-of-zero rule — callers building
+ *   negative evidence must consult `readLayerCoverage`, not this reader alone.
+ *
+ *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing is
+ *   `@mailwoman/spatial`'s `shortCellToInt` via `uprnFullCell` — never reimplemented here.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { gridDisk } from "h3-js"
+
+import { allRows } from "./sqlite-utils.ts"
+import { uprnFullCell } from "./uprn-schema.ts"
+
+/**
+ * Conservative FLOOR on how much CENTRE distance one unit of res-9 GRID distance buys, metres. Adjacent centres sit √3
+ * × edge apart (avg edge 174.4 m → ≈302 m); the worst bearing across a ring costs a further ×0.866, and H3's projection
+ * distortion shrinks edges by well under the slack this leaves (the true worst is ≈217 m per grid step). Dividing a
+ * radius by this over-counts rings and can never miss a cell; multiplying a grid distance by it under-states reach and
+ * can never end the ring walk early.
+ */
+const RES9_CENTER_SPACING_FLOOR_M = 150
+
+/**
+ * Conservative CEILING on a res-9 cell's centre-to-vertex distance, metres (avg edge 174.4 m; distortion stays well
+ * under this). A point within `radiusM` of the query sits in a cell whose CENTRE is within `radiusM` + this.
+ */
+const RES9_CELL_RADIUS_CEILING_M = 300
+
+/**
+ * Hard ceiling on `radiusM`. Keeps the probe bounded (10 km → ~72 rings ≈ 15.8k cells ≈ 18 `IN` chunks); a caller who
+ * wants a wider search than "which property is this coordinate" has outgrown this reader and should say so loudly.
+ */
+export const UPRN_MAX_NEAREST_RADIUS_M = 10_000
+
+/**
+ * `IN`-list chunk size for the cell probe — far under SQLite's 32,766 bound-variable ceiling.
+ */
+const CELL_PROBE_CHUNK = 900
+
+export interface UPRNCoordinate {
+	latitude: number
+	longitude: number
+}
+
+export interface UPRNNearestHit {
+	uprn: number
+	latitude: number
+	longitude: number
+	/**
+	 * Haversine distance from the query point, metres.
+	 */
+	distanceM: number
+}
+
+export interface UPRNLookupOpts {
+	/**
+	 * Path to a `uprn.db` built by `mailwoman`'s gazetteer pipeline. Opened read-only.
+	 */
+	databasePath?: string
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
+	database?: DatabaseSync
+}
+
+interface UPRNRow {
+	uprn: number
+	lat: number
+	lon: number
+}
+
+/**
+ * Node reader over `uprn.db`. `implements Disposable` so callers can `using lookup = new UPRNLookup(...)` — the same
+ * precedent as {@link POILookup}.
+ */
+export class UPRNLookup implements Disposable {
+	#db: DatabaseSync
+	#ownsDB: boolean
+
+	/**
+	 * `uprn` → its point (rowid-alias PK hit).
+	 */
+	readonly #coordinateProbe: ReturnType<DatabaseSync["prepare"]>
+
+	constructor(opts: UPRNLookupOpts) {
+		if (opts.database) {
+			this.#db = opts.database
+			this.#ownsDB = false
+		} else if (opts.databasePath) {
+			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
+			this.#ownsDB = true
+		} else {
+			throw new Error("UPRNLookup needs `databasePath` or `database`")
+		}
+
+		this.#coordinateProbe = this.#db.prepare("SELECT lat, lon FROM uprn WHERE uprn = ?")
+	}
+
+	/**
+	 * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such UPRN (see the module docstring for
+	 * what that `null` claims).
+	 */
+	coordinateOf(uprn: number): UPRNCoordinate | null {
+		const row = this.#coordinateProbe.get(uprn) as { lat: number; lon: number } | undefined
+
+		return row ? { latitude: row.lat, longitude: row.lon } : null
+	}
+
+	/**
+	 * The single nearest UPRN within `radiusM` metres of the query point, or `null` when no UPRN lies inside the radius.
+	 *
+	 * Bounded two ways: `radiusM` is capped at {@link UPRN_MAX_NEAREST_RADIUS_M}, and rings expand outward only until no
+	 * unprobed cell could beat the best hit found so far (or the radius, when nothing has been found). The stop rule is
+	 * geometric — a cell at grid distance `g` holds no point nearer than `g` × spacing floor − cell radius, using the
+	 * same conservative constants the reach math uses — so unlike POILookup's row-count accumulation there is no
+	 * early-exit ambiguity: a break can never strand a nearer point in an unprobed ring. This is what keeps a
+	 * capped-radius call over dense ground at milliseconds instead of a full-disk fetch (measured 6.4 s → 13 ms for a 10
+	 * km radius over central London, 41.6M-row layer; an empty-sea miss at the cap runs the full expansion, 74 ms).
+	 *
+	 * @throws {RangeError} When `radiusM` is not a positive finite number, or exceeds the cap.
+	 */
+	nearestUPRN(latitude: number, longitude: number, radiusM: number): UPRNNearestHit | null {
+		if (!Number.isFinite(radiusM) || radiusM <= 0) {
+			throw new RangeError(`nearestUPRN: radiusM must be a positive finite number, received ${radiusM}`)
+		}
+
+		if (radiusM > UPRN_MAX_NEAREST_RADIUS_M) {
+			throw new RangeError(`nearestUPRN: radiusM ${radiusM} exceeds the ${UPRN_MAX_NEAREST_RADIUS_M} m cap`)
+		}
+
+		const origin = uprnFullCell(latitude, longitude)
+		const seenCells = new Set<string>()
+		let best: UPRNNearestHit | null = null
+
+		// `ring` is H3 grid distance; the loop terminates because the break bound is at most radiusM, which the
+		// RangeError above caps.
+		for (let ring = 0; ; ring++) {
+			// A cell at grid distance `ring` holds no point nearer than this. Once it exceeds what could still
+			// win — the best hit so far, or the radius itself — further rings cannot improve the answer.
+			const closestPossibleM = ring * RES9_CENTER_SPACING_FLOOR_M - RES9_CELL_RADIUS_CEILING_M
+
+			if (closestPossibleM > Math.min(radiusM, best?.distanceM ?? radiusM)) break
+
+			// gridDisk(origin, ring) returns the WHOLE disk out to `ring`; diffing against what's already been
+			// probed derives just this ring's new cells (the POILookup pattern).
+			const diskCells = gridDisk(origin, ring) as string[]
+			const newCells: number[] = []
+
+			for (const cell of diskCells) {
+				if (!seenCells.has(cell)) {
+					seenCells.add(cell)
+					newCells.push(shortCellToInt(cell as H3Cell))
+				}
+			}
+
+			for (let i = 0; i < newCells.length; i += CELL_PROBE_CHUNK) {
+				const chunk = newCells.slice(i, i + CELL_PROBE_CHUNK)
+				const placeholders = chunk.map(() => "?").join(", ")
+
+				// Prepared fresh per chunk arity — a cold, per-call path, same posture as POILookup's batched hydration.
+				const rows = allRows<UPRNRow>(
+					this.#db.prepare(`SELECT uprn, lat, lon FROM uprn WHERE h3_cell IN (${placeholders})`),
+					...chunk
+				)
+
+				for (const row of rows) {
+					const distanceM = haversineKm(latitude, longitude, row.lat, row.lon) * 1000
+
+					if (distanceM <= radiusM && (best === null || distanceM < best.distanceM)) {
+						best = { uprn: row.uprn, latitude: row.lat, longitude: row.lon, distanceM }
+					}
+				}
+			}
+		}
+
+		return best
+	}
+
+	close(): void {
+		if (this.#ownsDB) {
+			this.#db.close()
+		}
+	}
+
+	[Symbol.dispose](): void {
+		this.close()
+	}
+}