@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/street/normalize.ts

@@ -2,73 +2,31 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   THE street normalizer for the address-point tier (#476). One function, used by BOTH the extract
- *   builder (`scripts/build-address-point-extract.ts`) and the lookup tier (`address-point.ts`) —
- *   never two implementations (the PLACETYPE_ORDER lesson: parallel copies silently corrupt).
- *
- *   Normalization contract (deliberately aggressive — both sides apply the same function, so
- *   collisions only need to be _consistent_, not linguistically perfect):
- *
- *   1. Lowercase, NFKD-fold diacritics, collapse whitespace, strip punctuation (periods, commas,
- *        apostrophes).
- *   2. Expand USPS directional abbreviations at the FIRST and LAST token position (`n` → `north`, `se` →
- *        `southeast`) — Overture sources abbreviate inconsistently.
- *   3. Canonicalize a trailing USPS street-type token via the codex suffix table to its canonical full
- *        form (`st`/`str`/`street` → `street`).
- *
- *   Numbered streets are left as digits (`5th` stays `5th`); a SPELLED ordinal before a street suffix
- *   folds to its digit form (`tenth street` → `10th street`, #723) so the grid-city ordinal
- *   cross-streets the source data spells with digits become reachable.
  */
 
 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 extract, 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 boundary turns that silent under-match into a compile error. Mint one only by calling the fold.
+ * A place name folded by {@link normalizeLocalityForKey}, minted 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.
+ * A street name folded by {@link normalizeStreetForKey} or {@link normalizeStreetForKeyLocale},
+ * the form an address-point `street_norm` column stores.
+ * Do not substitute {@link RouteKey} for this type.
  */
 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.
+ * A street key that has also passed {@link canonicalizeRouteKey}; binding a plain
+ * {@link StreetKey} to a route-folded column silently misses rows whose route spelling differs.
  */
 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
- * name, and merging would leave nothing to match on.
- */
 const MIN_TOKENS_FOR_TAIL_MERGE = 3
 
-/**
- * Spelled ordinal street names → their digit-ordinal form ("tenth" → "10th"), applied ONLY when a street-type suffix
- * follows (#723 admin-tail) — so the ordinal cross-streets common in grid cities ("Tenth Street", "Fifth Avenue") match
- * the extracts' digit keys, WITHOUT rewriting ordinal-WORD names where the next token is not a suffix ("First National
- * Bank Rd" stays "first national …"). Digit-source extracts are unaffected (a digit token isn't in this map), so the
- * existing keys need no rebuild; a future rebuild folds any spelled-source key the same way (the one-function
- * discipline).
- */
 const SPELLED_ORDINAL_TO_DIGIT = new Map<string, string>([
 	["first", "1st"],
 	["second", "2nd"],
@@ -100,9 +58,6 @@ const SPELLED_ORDINAL_TO_DIGIT = new Map<string, string>([
 	["hundredth", "100th"],
 ])
 
-/**
- * Lowercase + diacritic-fold + punctuation strip + whitespace collapse.
- */
 function fold(input: string): string {
 	return input
 		.normalize("NFKD")
@@ -114,16 +69,15 @@ 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.
+ * Normalizes a US or English street name into an address-point key, folding directionals,
+ * spelled ordinals and the USPS street-type suffix.
+ * The extract builder and the probe must both call it.
  */
 export function normalizeStreetForKey(street: string): StreetKey {
 	const tokens = fold(street).split(" ")
 
 	if (!tokens.length) return "" as StreetKey
 
-	// Spelled-ordinal street names → digit form when a street suffix follows ("Tenth Street" →
-	// "10th street", #723). Conditioned on the next token being a suffix so ordinal-WORD names are untouched.
 	for (let i = 0; i < tokens.length - 1; i++) {
 		const digit = SPELLED_ORDINAL_TO_DIGIT.get(tokens[i]!)
 
@@ -132,10 +86,6 @@ export function normalizeStreetForKey(street: string): StreetKey {
 		}
 	}
 
-	// Directional expansion at the edges only ("N Main St" / "Main St N" — never interior
-	// tokens, where "W" may be an initial in a person-named street). The codex expands
-	// compounds to two words ("SE" → "SOUTH EAST"); we key on the spaceless form
-	// ("southeast"), and also merge an already-written two-token pair ("South East …").
 	const edgeDirectional = (raw: string) =>
 		AbbreviationToDirectional.get(raw.toUpperCase())?.toLowerCase().replace(" ", "")
 
@@ -168,11 +118,8 @@ export function normalizeStreetForKey(street: string): StreetKey {
 		}
 	}
 
-	// Street-type canonicalization via the codex table (lowercase keys, UPPER canonical
-	// values). The suffix is usually the last token, but sits second-to-last when a trailing
-	// directional follows ("Main St N") — check both positions, canonicalize the first hit.
 	for (const at of [tokens.length - 1, tokens.length - 2]) {
-		if (at < 1) continue // never canonicalize the only/first token ("Street Road" exists)
+		if (at < 1) continue
 		const canonical = US_STREET_SUFFIX_LOOKUP.get(tokens[at]!)
 
 		if (canonical) {
@@ -186,31 +133,18 @@ export function normalizeStreetForKey(street: string): StreetKey {
 }
 
 /**
- * Street-name locale for the address-point key. The US path is the full USPS pipeline ({@link normalizeStreetForKey});
- * the international paths fold + apply a SMALL, consistent per-locale type-token canonicalization. Same discipline as
- * the US normalizer: build side and probe side call the identical function, so the key only needs to be CONSISTENT, not
- * linguistically perfect — a folded "rue du chevaleret" keys the same on both sides whether or not we reorder the
- * article, so no salient-token / multi-key index is built yet (deferred until probing shows the normalizer can't absorb
- * the false-negatives).
+ * Names the rule set {@link normalizeStreetForKeyLocale} uses to fold a street
+ * name into an address-point key.
  */
-export type StreetLocale = "us" | "en" | "fr" | "de" | "nl" | "pl" | "vn" | "id" | "zh"
+export type StreetLocale = "us" | "en" | "es" | "fr" | "de" | "it" | "nl" | "pl" | "vn" | "id" | "zh"
 
-/**
- * The Han fold shared by every `zh` key: NFKC so a full-width digit or letter keys as its ASCII form (the Taiwanese
- * civil-affairs registers write `１２２`, a person types `122`), 臺 → 台 (the register writes 臺北市, the common hand writes
- * 台北市), and no whitespace at all, because a Han surface carries none and a stray space would split one key into two.
- * Kanji numerals stay as written: the register spells a road section `一段`, and so does a query.
- */
 function foldHan(input: string): string {
 	return input.normalize("NFKC").replaceAll("臺", "台").replaceAll(/\s+/g, "").toLowerCase()
 }
 
 /**
- * Country → street-locale registry surface for the acquisition SDKs (BAN, OSM). Each SDK keeps its own map — membership
- * is a per-register decision — and this factory owns the lookup discipline: throw for an unsupported country rather
- * than silently folding with the wrong rules, because a extract built with the wrong normalizer keys every street
- * incorrectly and looks fine until a probe misses. `label` is the SDK's own registration instructions, appended to the
- * error verbatim.
+ * Creates a country-to-street-locale lookup for an acquisition SDK, throwing
+ * rather than falling back so a misregistered locale cannot key every street wrongly.
  */
 export function createStreetLocaleRegistry(
 	registry: ReadonlyMap<string, StreetLocale>,
@@ -230,11 +164,6 @@ export function createStreetLocaleRegistry(
 	}
 }
 
-/**
- * French street-type abbreviations → canonical full form, applied per token after {@link fold}. French address types
- * LEAD the name ("Av. de…", "Bd …", "Pl. …") and "St"/"Ste" abbreviate Saint/Sainte inside names ("Rue St-Honoré" →
- * "rue saint honore"). fold() has already stripped the trailing period, so the keys are point-free ("av", "bd").
- */
 const FR_STREET_ABBREV = new Map<string, string>([
 	["av", "avenue"],
 	["ave", "avenue"],
@@ -257,19 +186,45 @@ const FR_STREET_ABBREV = new Map<string, string>([
 	["sts", "saints"],
 ])
 
+const PL_LEADING_TYPE = new Set(["ul", "ulica", "al", "aleja", "aleje", "pl", "plac", "os", "osiedle"])
+
 /**
- * Polish leading street-type tokens, STRIPPED rather than expanded. Measured on the 5.56M-row PL OSM extract
- * (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.
+ * Italian street types in the abbreviated spellings a person types, mapped to the spelling ANNCSU publishes.
  */
-const PL_LEADING_TYPE = new Set(["ul", "ulica", "al", "aleja", "aleje", "pl", "plac", "os", "osiedle"])
+const IT_STREET_TYPE_ABBREV = new Map<string, string>([
+	["v", "via"],
+	["vle", "viale"],
+	["vl", "viale"],
+	["vic", "vicolo"],
+	["vlo", "vicolo"],
+	["str", "strada"],
+	["pza", "piazza"],
+	["pzza", "piazza"],
+	["p", "piazza"],
+	["ple", "piazzale"],
+	["cso", "corso"],
+	["c", "corso"],
+	["lgo", "largo"],
+	["loc", "localita"],
+	["fraz", "frazione"],
+	["cda", "contrada"],
+	["lungarno", "lungarno"],
+])
 
 /**
- * Indonesian street-type abbreviations → canonical full form, leading position ("Jl. Thamrin", "Gg. Waru").
+ * Spanish street-type abbreviations whose expansion is the same token in every language
+ * the register writes after `fold`; `c/`, `av`, and `pl` are deliberately absent
+ * because they expand differently by region.
  */
+const ES_STREET_TYPE_ABBREV = new Map<string, string>([
+	["ctra", "carretera"],
+	["crta", "carretera"],
+	["rbla", "rambla"],
+	["gta", "glorieta"],
+	["cjon", "callejon"],
+	["rda", "ronda"],
+])
+
 const ID_STREET_ABBREV = new Map<string, string>([
 	["jl", "jalan"],
 	["jln", "jalan"],
@@ -277,42 +232,19 @@ const ID_STREET_ABBREV = new Map<string, string>([
 ])
 
 /**
- * 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}.
- *
- * - **en** — the shared English address-key pipeline (directionals + suffix aliases), currently identical to US.
- * - **fr** — fold + expand leading type abbreviations and Saint/Sainte (token map).
- * - **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 extract
- *   before adding anything.
- * - **id** — fold + expand leading type abbreviations (jl/jln→jalan, gg→gang); Indonesian street surfaces are otherwise
- *   ASCII-clean.
+ * Normalizes a street name into an address-point key under the given locale, delegating `us`
+ * and `en` to {@link normalizeStreetForKey}; the extract builder and the probe must both call it.
  */
 export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale): StreetKey {
 	if (locale === "us" || locale === "en") return normalizeStreetForKey(street)
 
-	// A Han street name has no tokens, no type abbreviation and no diacritics; the Latin pipeline below would only
-	// split it on whitespace it never carries. `zh` keys are the Han fold and nothing else.
 	if (locale === "zh") return foldHan(street) as StreetKey
 
-	// 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. 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 extract of the other locales.
 	const tokens = fold(street)
 		.replaceAll("ß", "ss")
 		.replaceAll("-", " ")
 		.split(/\s+/)
-		.filter((value) => value.length > 0)
+		.filter((value) => value.length)
 
 	if (!tokens.length) return "" as StreetKey
 
@@ -331,6 +263,20 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 				}
 			}
 			break
+		case "it":
+			// The leading type is expanded and kept, unlike `pl`, because dropping it
+			// merges distinct streets that share a name.
+			if (tokens.length > 1) {
+				tokens[0] = IT_STREET_TYPE_ABBREV.get(tokens[0]!) ?? tokens[0]!
+			}
+			break
+		case "es":
+			// Keep the leading type, as `it` does and more strongly, because `Calle Mayor`
+			// and `Plaza Mayor` often share a municipio.
+			if (tokens.length > 1) {
+				tokens[0] = ES_STREET_TYPE_ABBREV.get(tokens[0]!) ?? tokens[0]!
+			}
+			break
 		case "nl":
 			for (let i = 0; i < tokens.length; i++) {
 				const t = tokens[i]!
@@ -355,11 +301,6 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 			}
 			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 extract 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")
 			}
@@ -370,30 +311,27 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 }
 
 /**
- * Normalize a locality name for address-point keying (fold only — no street semantics).
+ * Normalize a locality name for address-point keying, fold only with no street semantics.
  */
 export function normalizeLocalityForKey(locality: string): NameKey {
 	return fold(locality) as NameKey
 }
 
 /**
- * The locality key under a street locale: the Han fold for `zh`, {@link normalizeLocalityForKey} for every other.
- * Separate from the shared fold on purpose — the candidate gazetteer's `name_key` column is the shared fold, and a Han
- * rule inside it would re-key every 臺 name under an extract built without the rule.
+ * Folds a locality name into a {@link NameKey} with the Han fold for `zh`
+ * and {@link normalizeLocalityForKey} otherwise.
+ *
+ * The Han rule stays out of the shared fold so existing columns are not re-keyed.
  */
 export function normalizeLocalityForKeyLocale(locality: string, locale: StreetLocale): NameKey {
 	return locale === "zh" ? (foldHan(locality) as NameKey) : normalizeLocalityForKey(locality)
 }
 
 /**
- * The house-number key under a street locale. Every Latin register stores a lower-cased, trimmed number and the reader
- * probes the same; `zh` additionally folds width and drops the trailing 號 the Taiwanese registers write on the number
- * itself (`１２２號`), which a parse also carries on the `house_number` span (`122號`). Both sides key `122`.
+ * Folds a house number into an address-point key, additionally width-folding
+ * and dropping the trailing 號 for `zh`.
  */
 export function normalizeHouseNumberForKey(number: string, locale: StreetLocale): string {
-	// The sub-number is written two ways — `30之19號` and `30號之19` — and an attached number a third (`30附40號`,
-	// `55之23附1號`); the register stores the base `30` with the rest in `unit`. Every form keys with the 號 dropped and
-	// the base number first, which the reader's sub-number rung then falls from.
 	if (locale === "zh") {
 		return foldHan(number)
 			.replace(/^(\d+)號([之附]\d+)$/u, "$1$2")
@@ -403,45 +341,21 @@ export function normalizeHouseNumberForKey(number: string, locale: StreetLocale)
 	return number.trim().toLowerCase()
 }
 
-/**
- * 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 extracts — the Québec finishing move on the CA rooftop extract.
- *
- * 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 extract 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` extract already speaks its own rules, and the US pipeline stays untouched.
- *
- * Measured basis (CA extract, 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.
+ * Routes an `en` street surface leading with a French type word to the `fr` locale
+ * and returns any other base unchanged, routing on the surface rather than the province
+ * so bilingual Canadian extracts fold consistently.
  */
 export function streetLocaleForSurface(street: string, base: StreetLocale): StreetLocale {
 	return base === "en" && FRENCH_LEAD_TYPE.test(street.trimStart()) ? "fr" : base
 }
 
 /**
- * Strip a trailing French arrondissement designator from a FOLDED commune key ("paris 8e arrondissement" → "paris",
- * "lyon 1er arrondissement" → "lyon", "marseille 10e arrondissement" → "marseille"). Paris, Lyon and Marseille are the
- * 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). 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.
+ * Strips a trailing French arrondissement designator from a folded commune key,
+ * returning the input unchanged when the strip would leave no text.
  */
 export function stripArrondissement(localityNorm: NameKey): NameKey {
 	const stripped = localityNorm.replace(/\s+\d+(?:er|e)\s+arrondissement$/, "").trim() as NameKey
@@ -450,17 +364,10 @@ export function stripArrondissement(localityNorm: NameKey): NameKey {
 }
 
 /**
- * Strip a locality QUALIFIER for a query-side fallback — when an OA locality's exact normalized name misses the
- * gazetteer's canonical name, retry with the qualifier removed. OA address data carries disambiguating qualifiers the
- * gazetteer's canonical name omits: Austrian `Kraubath/Mur` and `Hart b.Graz` → `Hart`; Swiss `Lenk im Simmental` →
- * `Lenk`, `Roche VD` → `Roche`; Danish `Odense S`, `Hurup Thy`. A FALLBACK ONLY — the exact name is tried first, and
- * the region-bbox disambiguation resolves any base-name ambiguity downstream. The candidate table is unchanged (this is
- * purely query-side); feed the result back through {@link normalizeLocalityForKey}. Returns "" when nothing was stripped
- * (no point re-probing the identical key).
+ * Strips a disambiguating qualifier from a locality name for a query-side retry,
+ * returning an empty string when no text was stripped.
  *
- * Measured (`scripts/eval/candidate-recall.ts --strip-fallback`, EU OA holdouts): recovers AT 74.1→88.2% (+14.1pp), DK
- * 91.5→96.2%, CH 90.4→92.6%; +1.3pp overall (diluted by the already-100% locales). Conservative by design — only the
- * qualifier forms above; FI/PT/SI misses are untouched.
+ * The result must be refolded with {@link normalizeLocalityForKey} before probing.
  */
 export function stripLocalityQualifier(locality: string): string {
 	let s = locality.trim()
@@ -470,7 +377,7 @@ export function stripLocalityQualifier(locality: string): string {
 	}
 
 	const words = [...s.matchAll(/\S+/gu)].map((match) => ({ value: match[0], index: match.index }))
-	let qualifierStart: number | undefined
+	let qualifierStart: number | null = null
 
 	for (let index = 1; index < words.length; index++) {
 		const word = words[index]!
@@ -493,7 +400,7 @@ export function stripLocalityQualifier(locality: string): string {
 	const suffix = words.at(-1)
 
 	if (
-		qualifierStart === undefined &&
+		qualifierStart === null &&
 		suffix &&
 		words.length > 1 &&
 		(["S", "N", "E", "W", "V", "Ø", "Sø", "Fyn", "Thy", "Sjælland", "Jylland"].includes(suffix.value) ||
@@ -502,7 +409,7 @@ export function stripLocalityQualifier(locality: string): string {
 		qualifierStart = suffix.index
 	}
 
-	if (qualifierStart !== undefined) {
+	if (qualifierStart !== null) {
 		s = s.slice(0, qualifierStart).trimEnd()
 	}
 
@@ -512,57 +419,24 @@ export function stripLocalityQualifier(locality: string): string {
 }
 
 /**
- * Fold numbered-route designators to a canonical key, applied AFTER {@link normalizeStreetForKey}. Sources disagree
- * systematically on how they spell a route: TIGER says `State Rte 100` / `US Hwy 5` where E911/Overture say `VT ROUTE
- * 100` / `US ROUTE 5` — the dominant street-name miss class in the #483 interpolation eval (rural addresses live on
- * routes). `us <designator> N…` folds to `us route N…`; `state <designator> N…` and `<2-letter-prefix> <designator> N…`
- * (the state abbreviation form) fold to `state route N…`. Only digit-leading route numbers fold — `State Street` and
- * friends never match.
- *
- * Used by BOTH the segment-extract builder (`scripts/build-interpolation-extract.ts`) and the interpolation lookup —
- * same one-function discipline as {@link normalizeStreetForKey}. The address-point tier (#476) does NOT apply it yet:
- * adopting it there requires a extract rebuild (noted on #483).
- *
- * A same-numbered US and state route stay DISTINCT keys (`us route 5` vs `state route 5`); only the BARE `route N` form
- * is ambiguous (designator unknown) and it stays unfolded — a bare-route query therefore misses rather than guessing a
- * designator.
+ * Folds a numbered-route designator in a street key to `us route N` or `state route N`;
+ * only digit-leading numbers after a `us`, `state`, or two-letter prefix fold.
  */
 export function canonicalizeRouteKey(streetNorm: StreetKey): RouteKey {
 	const match = /^(us|state|[a-z]{2}) (?:route|rte|rt|highway|hwy) (\d.*)$/.exec(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.
+ * Lists the lookup keys to probe for a street span, most literal first, adding doubled-type
+ * and Saint/St-swap recovery forms for `us` and `en`.
  */
 export function streetKeyVariants(street: string, locale: StreetLocale = "us"): StreetKey[] {
 	const primary = locale === "us" ? normalizeStreetForKey(street) : normalizeStreetForKeyLocale(street, locale)
@@ -589,8 +463,6 @@ export function streetKeyVariants(street: string, locale: StreetLocale = "us"):
 		}
 	}
 
-	// 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) {
@@ -598,9 +470,6 @@ export function streetKeyVariants(street: string, locale: StreetLocale = "us"):
 		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)) {