@mailwoman/resolver-wof-sqlite 9.1.0 → 9.2.0

package/fst-autocomplete.ts

@@ -3,20 +3,29 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FST-based autocomplete. Prefix walk + BFS expansion to collect ranked place suggestions. O(depth
- *   × branching) — the FST IS the autocomplete index.
+ *   FST-based autocomplete — mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm
+ *   (#1728 phase 2). The #587 behavior — prefix walk + BFS expansion, partial-last-token completion,
+ *   per-branch capping, dedupe — lives in ancestrie's `autocomplete`; this module contributes only
+ *   the storage adapter ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to
+ *   mailwoman's suggestion shape (name, placetype, referential/encyclopedic, WOF ids).
  *
- *   Two query shapes are handled (the FST is a trie over normalized WORD tokens):
- *
- *   - COMPLETE tokens ("new york") — `walk` lands on a state; collect its accepting entries + BFS a
- *       couple tokens past it for nearby completions. This is the CLI's "complete a place word"
- *       path.
- *   - A PARTIAL last token ("new yor", "chic") — `walk` fails (there is no "yor" edge, only "york"). So
- *       walk the complete prefix, then complete the partial token by prefix-filtering the
- *       continuation edges (`token.startsWith(partial)`). This is what a char-level typeahead
- *       needs; without it "new yor" returns nothing useful. (#587)
+ *   THE BYTES DO NOT MIGRATE. The shipped artifacts are `FST\0` v1–v5 (`fst-serialize.ts`), not
+ *   ancestrie's `ANCT`: ancestrie entries are id-keyed with one record per id, while an FST place row
+ *   is per-(surface, place) — `crossCountryBranches` is a property of the SURFACE, so the same wofID
+ *   legitimately carries different values under different aliases and cannot be represented id-keyed.
+ *   The matcher, both deserializers, and the serializer therefore stay here; what migrated is the
+ *   ALGORITHM, which is the half that drifts (the #861 share-the-function rule).
  */
 
+import type {
+	AncestrieContinuation,
+	AncestrieMatch,
+	AncestrieReaderLike,
+	AncestrieRecord,
+	AncestrieSuggestion,
+} from "@mailwoman/ancestrie"
+import { autocomplete as ancestrieAutocomplete } from "@mailwoman/ancestrie"
+
 import type { FSTMatcher } from "./fst-matcher.ts"
 import { normalizeTokens } from "./fst-matcher.ts"
 import type { PlaceEntry } from "./fst-types.ts"
@@ -59,19 +68,15 @@ export interface AutocompleteOpts {
 	dedupeByName?: boolean
 }
 
-interface BfsItem {
-	stateID: number
-	depth: number
-	tokens: string[]
-}
-
 /**
  * Max accepting entries collected per BFS branch — keeps one dense branch from starving the search.
  */
 const PER_BRANCH = 4
 
 /**
- * The top-`k` entries by REFERENTIAL likelihood (descending). Avoids sorting/allocating when `entries` is small.
+ * The top-`k` entries by REFERENTIAL likelihood (descending). Avoids sorting/allocating when `entries` is small — and
+ * that shortcut is part of the observable contract: at or under `k` the INSERTION order is served, which decides
+ * suggestion order among referential ties.
  */
 function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
 	if (entries.length <= k) return [...entries]
@@ -80,125 +85,92 @@ function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry
 }
 
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
+ * {@link FSTMatcher} presented through ancestrie's storage seam. Records carry the {@link PlaceEntry} itself as the
+ * payload, so the entry that WINS the algorithm's shallowest-depth rule is the entry whose fields the suggestion
+ * reports — a side lookup keyed on id could pick a different surface's row (`crossCountryBranches` differs per
+ * surface).
  */
-export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteOpts = {}): AutocompleteResult {
-	const maxSuggestions = opts.maxSuggestions ?? 10
-	const maxExpansionDepth = opts.maxExpansionDepth ?? 2
-	const normalizedTokens = normalizeTokens(query)
-
-	if (!normalizedTokens.length) {
-		return { query, normalizedTokens: [], depth: 0, suggestions: [] }
-	}
-
-	const seen = new Map<number, AutocompleteSuggestion>()
-	const queue: BfsItem[] = []
-	let depth: number
-
-	const match = fst.walk(normalizedTokens)
-
-	if (match) {
-		// COMPLETE-token prefix landed on a state. Seed at the match state (accepting + continuations).
-		depth = match.depth
-
-		for (const entry of fst.accepting(match.stateID)) {
-			addSuggestion(seen, entry, match.depth, [])
-		}
-
-		for (const cont of fst.continuations(match.stateID)) {
-			queue.push({ stateID: cont.targetState, depth: 1, tokens: [cont.token] })
-		}
-	} else {
-		// PARTIAL last token — walk the complete prefix, complete the partial by prefix-filtering edges.
-		const complete = normalizedTokens.slice(0, -1)
-		const partial = normalizedTokens.at(-1)!
-		const prefixState = !complete.length ? 0 : (fst.walk(complete)?.stateID ?? undefined)
-
-		if (prefixState === undefined) {
-			return { query, normalizedTokens, depth: 0, suggestions: [] }
-		}
-
-		depth = complete.length
+class FSTReader implements AncestrieReaderLike<PlaceEntry> {
+	readonly #fst: FSTMatcher
 
-		for (const cont of fst.continuations(prefixState)) {
-			if (!cont.token.startsWith(partial)) continue
+	/**
+	 * Parent chains of the entries this reader has served, id-keyed. A place's chain is identical across its surfaces (it
+	 * is place-row data), so last-write-wins is safe. The algorithm asks {@link FSTReader.ancestorsOf} only for ids it
+	 * just received from {@link FSTReader.entriesAt}, so serving from this memo answers every real call without an
+	 * artifact-wide id index.
+	 */
+	readonly #chains = new Map<number, number[]>()
 
-			// This edge completes the typed partial token — its target is a real match at depth+1.
-			for (const entry of topByReferential(fst.accepting(cont.targetState), PER_BRANCH)) {
-				addSuggestion(seen, entry, complete.length + 1, [cont.token])
-			}
+	constructor(fst: FSTMatcher) {
+		this.#fst = fst
+	}
 
-			// BFS a little past it too (multi-token completions: "new yor" → "New York Mills").
-			queue.push({ stateID: cont.targetState, depth: 1, tokens: [cont.token] })
-		}
+	walk(tokens: readonly string[]): AncestrieMatch | null {
+		return this.#fst.walk([...tokens])
 	}
 
-	// BFS expansion (shared by both paths) — find nearby completions up to maxExpansionDepth. Each
-	// branch contributes only its top PER_BRANCH places: a state like "new london" has dozens of
-	// accepting entries and would otherwise blow the budget before the BFS ever reaches "new york"
-	// (the "new" state has 311 continuations). Per-branch capping keeps the search broad. (#587)
-	while (queue.length && seen.size < maxSuggestions * 4) {
-		const item = queue.shift()!
+	continuations(stateID: number): AncestrieContinuation[] {
+		// Insertion order, verbatim — BFS visit order under the suggestion budget depends on it.
+		return this.#fst.continuations(stateID).map((c) => ({
+			token: c.token,
+			targetState: c.targetState,
+			entryCount: c.acceptingCount,
+		}))
+	}
 
-		if (item.depth > maxExpansionDepth) continue
+	entriesAt(stateID: number, limit?: number): AncestrieRecord<PlaceEntry>[] {
+		const places = this.#fst.accepting(stateID)
+		const selected = limit === undefined ? places : topByReferential(places, limit)
 
-		for (const entry of topByReferential(fst.accepting(item.stateID), PER_BRANCH)) {
-			addSuggestion(seen, entry, depth + item.depth, item.tokens)
-		}
+		return selected.map((entry) => {
+			this.#chains.set(entry.wofID, entry.parentChain)
 
-		if (item.depth < maxExpansionDepth) {
-			for (const cont of fst.continuations(item.stateID)) {
-				queue.push({ stateID: cont.targetState, depth: item.depth + 1, tokens: [...item.tokens, cont.token] })
+			return {
+				id: entry.wofID,
+				rank: entry.referential,
+				parentIDs: entry.parentChain,
+				payload: entry,
 			}
-		}
+		})
 	}
 
-	let suggestions = [...seen.values()].toSorted((a, b) => b.referential - a.referential)
-
-	if (opts.dedupeByName) {
-		suggestions = dedupeByName(suggestions)
+	ancestorsOf(id: number): number[] {
+		return this.#chains.get(id) ?? []
 	}
-
-	return { query, normalizedTokens, depth, suggestions: suggestions.slice(0, maxSuggestions) }
-}
-
-function addSuggestion(
-	seen: Map<number, AutocompleteSuggestion>,
-	entry: PlaceEntry,
-	matchDepth: number,
-	completionTokens: string[]
-): void {
-	const existing = seen.get(entry.wofID)
-
-	if (existing && existing.matchDepth <= matchDepth) return
-
-	seen.set(entry.wofID, {
-		name: entry.name,
-		placetype: entry.placetype,
-		referential: entry.referential,
-		...(entry.encyclopedic === undefined ? {} : { encyclopedic: entry.encyclopedic }),
-		wofID: entry.wofID,
-		parentChain: entry.parentChain,
-		matchDepth,
-		completionTokens: [...completionTokens],
-	})
 }
 
 /**
- * Keep one suggestion per name — the highest-referential. Input is already referential-sorted, so the first occurrence
- * per name wins; order is preserved.
+ * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
  */
-function dedupeByName(suggestions: AutocompleteSuggestion[]): AutocompleteSuggestion[] {
-	const seenNames = new Set<string>()
-	const out: AutocompleteSuggestion[] = []
+export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteOpts = {}): AutocompleteResult {
+	const normalizedTokens = normalizeTokens(query)
 
-	for (const s of suggestions) {
-		const key = s.name.toLowerCase()
+	const result = ancestrieAutocomplete<PlaceEntry>(new FSTReader(fst), normalizedTokens, {
+		...(opts.maxSuggestions === undefined ? {} : { maxSuggestions: opts.maxSuggestions }),
+		...(opts.maxExpansionDepth === undefined ? {} : { maxExpansionDepth: opts.maxExpansionDepth }),
+		perBranchLimit: PER_BRANCH,
+		// The dedupe key is the DISPLAY name, not the token path: two surfaces of one name must still collapse. (#587)
+		...(opts.dedupeByName ? { dedupe: (s: AncestrieSuggestion<PlaceEntry>) => s.payload!.name.toLowerCase() } : {}),
+	})
 
-		if (seenNames.has(key)) continue
-		seenNames.add(key)
-		out.push(s)
+	return {
+		query,
+		normalizedTokens,
+		depth: result.depth,
+		suggestions: result.suggestions.map((s) => {
+			// Every record this adapter serves carries its entry; the assertion documents the invariant.
+			const entry = s.payload!
+
+			return {
+				name: entry.name,
+				placetype: entry.placetype,
+				referential: entry.referential,
+				...(entry.encyclopedic === undefined ? {} : { encyclopedic: entry.encyclopedic }),
+				wofID: s.id,
+				parentChain: s.parentIDs,
+				matchDepth: s.matchDepth,
+				completionTokens: s.completionTokens,
+			}
+		}),
 	}
-
-	return out
 }

package/fst-builder.ts

@@ -18,6 +18,7 @@ import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
 import type { BuildFSTOpts, BuildFSTResult, FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
 import { loadImportanceSplit } from "./place-importance-schema.ts"
+import { allRows, getRow } from "./sqlite-utils.ts"
 
 const DEFAULT_PLACETYPES: PlacetypeID[] = [
 	"country",
@@ -78,7 +79,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		   AND placetype IN (${placeholders(placetypes)})`
 	)
 
-	const sprRows = sprStmt.all(...countries, ...placetypes) as unknown as SprRow[]
+	const sprRows = allRows<SprRow>(sprStmt, ...countries, ...placetypes)
 	progress("spr", `Loaded ${sprRows.length} places`)
 
 	// Phase 2: Build a lookup for parent chain resolution.
@@ -103,8 +104,8 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		for (let i = 0; i < orphanIDs.length; i += ANCESTOR_CHUNK) {
 			const chunk = orphanIDs.slice(i, i + ANCESTOR_CHUNK)
 
-			const rows = db
-				.prepare(
+			const rows = allRows<{ id: number; ancestor_id: number }>(
+				db.prepare(
 					`SELECT DISTINCT id, ancestor_id FROM ancestors
 					 WHERE id IN (${chunk.map(() => "?").join(",")}) AND ancestor_placetype IN ('country', 'region', 'county')
 					 ORDER BY id, CASE ancestor_placetype
@@ -112,8 +113,9 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 					   WHEN 'region' THEN 2
 					   WHEN 'country' THEN 3
 					 END`
-				)
-				.all(...chunk) as unknown as Array<{ id: number; ancestor_id: number }>
+				),
+				...chunk
+			)
 
 			for (const row of rows) {
 				let chain = ancestorsByID.get(row.id)
@@ -150,7 +152,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 			let parentRow = sprByID.get(current)
 
 			if (!parentRow) {
-				const fetched = parentStmt.get(current) as unknown as SprRow | undefined
+				const fetched = getRow<SprRow>(parentStmt, current)
 
 				if (!fetched) break
 				parentRow = fetched
@@ -186,13 +188,13 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 
 	// Phase 4: Load names for matching places.
 	progress("names", "Loading name variants")
-	const placeIds = sprRows.map((r) => r.id)
+	const placeIDs = sprRows.map((r) => r.id)
 	const namesByPlace = new Map<number, string[]>()
 
 	const allLanguages = languages.includes("*")
 
-	for (let i = 0; i < placeIds.length; i += 500) {
-		const chunk = placeIds.slice(i, i + 500)
+	for (let i = 0; i < placeIDs.length; i += 500) {
+		const chunk = placeIDs.slice(i, i + 500)
 		const idPlaceholders = chunk.map(() => "?").join(",")
 
 		const nameStmt = allLanguages
@@ -201,9 +203,9 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 					`SELECT id, name, language, privateuse FROM names WHERE id IN (${idPlaceholders}) AND language IN (${languages.map(() => "?").join(",")})`
 				)
 
-		const nameRows = (allLanguages
-			? nameStmt.all(...chunk)
-			: nameStmt.all(...chunk, ...languages)) as unknown as NameRow[]
+		const nameRows = allLanguages
+			? allRows<NameRow>(nameStmt, ...chunk)
+			: allRows<NameRow>(nameStmt, ...chunk, ...languages)
 
 		for (const row of nameRows) {
 			const existing = namesByPlace.get(row.id) ?? []

package/fst-freshness.ts

@@ -15,7 +15,7 @@
  *   `FSTProvenance` already recorded `sourceDB` — the source's PATH, which is exactly the field that
  *   cannot change when the bytes behind it do. So the stamp gains the source's IDENTITY (md5 + byte
  *   size) and this module compares it. The shape deliberately mirrors
- *   `scripts/weights-overlay-linker.ts`'s `pairIndexStaleReason`: one function returning a reason
+ *   `@mailwoman/resolver-wof-sqlite/weights-overlay-linker`'s `pairIndexStaleReason`: one function returning a reason
  *   string or `undefined`, so a fact added to the stamp cannot be checked by some callers and not
  *   others — which is how three of the four base linkers ended up unable to notice a PIX1 schema bump.
  *
@@ -162,7 +162,7 @@ export function peekFSTStampFields(path: string): FSTStampFields | undefined {
  *
  * The async `md5File` in `@mailwoman/core/utils` is the one to reach for anywhere else. This exists because the FST
  * builder and its whole call chain are synchronous by design (`buildFSTFromWOF` → `buildLocaleFSTs`), and making them
- * async to stamp a checksum would cascade through the Pastel commands and the tests for one hash. It reads in
+ * async to stamp a checksum would cascade through command callers and tests for one hash. It reads in
  * {@link MD5_CHUNK_BYTES} chunks rather than `readFileSync` — the source is a multi-gigabyte database.
  */
 export function md5FileSync(path: string): string {

package/fts-query.ts

@@ -67,7 +67,7 @@ export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }):
 		// fusing "Thiron-Gardais" into the unmatchable single term `ThironGardais` while the FTS
 		// doc holds two terms (#945 — the entire hyphenated-name class missed at the raw lookup;
 		// masked for years because pre-splice tokenizers never emitted hyphen-preserved values).
-		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter(Boolean)
+		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter((part) => part.length > 0)
 
 		if (!parts.length) continue
 

package/fts.ts

@@ -5,7 +5,7 @@
  *
  *   FTS5 index lifecycle for the WOF SQLite distribution.
  *
- *   Shared by `WOFSqlitePlaceLookup` (lazy build via `buildFTS: true`) and the operator-side
+ *   Shared by `WOFSQLitePlaceLookup` (lazy build via `buildFTS: true`) and the operator-side
  *   `mailwoman gazetteer build fts` CLI (ahead-of-time build to avoid first-open latency in production).
  *
  *   Upstream WOF SQLite distributions do NOT ship FTS5. The index lives in a `place_search` virtual
@@ -17,7 +17,7 @@
 import type { DatabaseSync } from "node:sqlite"
 
 /**
- * Name of the FTS5 virtual table this module owns. Centralized so `WOFSqlitePlaceLookup` and the CLI can't drift apart.
+ * Name of the FTS5 virtual table this module owns. Centralized so `WOFSQLitePlaceLookup` and the CLI can't drift apart.
  */
 export const PLACE_SEARCH_TABLE = "place_search"
 
@@ -73,7 +73,7 @@ const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
 
 /**
  * Does any alias in an `alt_names` bag exactly equal the (already-normalized) query? The single shared implementation
- * of the exact-tier alias check for every consumer of the bag — the Node resolver's `#exactMatchIds` fallback, the WASM
+ * of the exact-tier alias check for every consumer of the bag — the Node resolver's `#exactMatchIDs` fallback, the WASM
  * resolver, and the demo's httpvfs resolver — so the bag format and its parsers can't drift.
  *
  * Two formats exist in the wild:
@@ -326,7 +326,7 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 }
 
 /**
- * Returns true iff the `place_search` table exists in the connected DB. Used by `WOFSqlitePlaceLookup` for its "FTS
+ * Returns true iff the `place_search` table exists in the connected DB. Used by `WOFSQLitePlaceLookup` for its "FTS
  * missing — pass buildFTS:true or run the CLI" guard.
  */
 export function placeSearchFTSExists(db: DatabaseSync): boolean {

package/geonames-postal.ts

@@ -54,7 +54,7 @@ const GEONAMES_POSTAL_COLUMNS = 11
 export const GEONAMES_POSTAL_ID_BASE = 9_500_000_000_000
 
 /**
- * The #920 name law: reduce a postal code to the sanitized-query token shape — strip every non-letter/number — so the
+ * The #920 name law: reduce a postcode to the sanitized-query token shape — strip every non-letter/number — so the
  * stored name matches what `sanitizeFTSQuery` produces from the parsed postcode token. `"110 00"` → `"11000"`,
  * `"11-041"` → `"11041"`, `"AD500"` → `"AD500"`.
  */
@@ -132,7 +132,7 @@ export interface GeonamesPostalIngestResult {
 }
 
 /**
- * Fold GeoNames postal codes for `countries` into an open unified/postcode ingest DB: one `spr` row per distinct
+ * Fold GeoNames postcodes for `countries` into an open unified/postcode ingest DB: one `spr` row per distinct
  * normalized postcode (placetype `postalcode`, medoid centroid, degenerate bbox), the normalized form as `name`, and
  * the display form as an extra `names` row when it differs. The caller owns the FTS rebuild (rows ride the standard
  * freeze phase).

package/index.ts

@@ -19,7 +19,24 @@ export type {
 	WOFDatabase,
 } from "./schema.ts"
 
-export { WOFSqlitePlaceLookup, type RankingWeights, type WOFSqlitePlaceLookupOpts } from "./lookup.ts"
+export { WOFSQLitePlaceLookup, type RankingWeights, type WOFSQLitePlaceLookupOpts } from "./lookup.ts"
+
+export {
+	CANDIDATE_ANCESTOR_COLUMNS,
+	CANDIDATE_ANCESTOR_TABLE,
+	CANDIDATE_INTERVAL_TABLE,
+	createCandidateAncestorTable,
+	createCandidateIntervalTable,
+	intervalContains,
+	MAX_ANCESTOR_DEPTH,
+} from "./candidate-ancestors-schema.ts"
+
+export type {
+	CandidateAncestorsDatabase,
+	CandidateAncestorTable,
+	CandidateIntervalTable,
+	IntervalLabel,
+} from "./candidate-ancestors-schema.ts"
 
 export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "./candidate-fts.ts"
 
@@ -100,19 +117,6 @@ export {
 	type BuildPlaceSearchFTSResult,
 } from "./fts.ts"
 
-export {
-	bboxAround,
-	geometryContains,
-	haversineKm,
-	pointInPolygonRings,
-	pointInRing,
-	type Bbox,
-	type GeojsonGeometry,
-	type GeojsonMultiPolygon,
-	type GeojsonPolygon,
-	type GeojsonPosition,
-} from "./geo.ts"
-
 export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth, type AncestorPlaceRow } from "./ancestry.ts"
 
 export {

package/interpolation.ts

@@ -30,11 +30,10 @@ import { DatabaseSync } from "node:sqlite"
 
 import { parseJSONStrict } from "@mailwoman/core/objects"
 import type { InterpolationLookup } from "@mailwoman/resolver"
-import { clampFraction, pointAlong } from "@mailwoman/spatial"
+import { clampFraction, haversineKm, pointAlong } from "@mailwoman/spatial"
 
-import { haversineKm } from "./geo.ts"
-import { hasTable } from "./sqlite-utils.ts"
-import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.ts"
+import { hasTable, prepareAll, type PreparedAll } from "./sqlite-utils.ts"
+import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } from "./street-normalize.ts"
 
 /**
  * How an interpolated answer was computed (#483 Method 2):
@@ -92,8 +91,27 @@ export interface InterpolationQuery {
 	 * ZIP scope — strongly preferred; without it common street names abstain (see module doc).
 	 */
 	postcode?: string
+	/**
+	 * The resolved locality's coordinate — the tie-breaker when no postcode was given and the parity-preferred covering
+	 * ranges still span several postcodes. See {@link NEAR_MAX_KM} for the acceptance geometry.
+	 */
+	near?: { lat: number; lon: number }
 }
 
+/**
+ * Acceptance geometry for the `near` tie-break: the winning postcode group's closest segment must sit within this many
+ * kilometres of `near`, AND the runner-up group must be at least {@link NEAR_DOMINANCE} times farther. Both measured on
+ * the two live failures: Brooklyn's `st pauls place` 11226 segment is ~2 km from the Brooklyn centroid with Great
+ * Neck's 11021 at ~24 km (12×); Fraser's `east 13 mile road` 48026 is ~2 km with Mecosta's namesake ~190 km away. A
+ * near-tie between groups is genuine ambiguity and stays an abstention.
+ */
+const NEAR_MAX_KM = 25
+
+/**
+ * See {@link NEAR_MAX_KM}.
+ */
+const NEAR_DOMINANCE = 2
+
 interface SegmentRow {
 	from_hn: number
 	to_hn: number
@@ -106,11 +124,55 @@ interface SegmentRow {
 	release: string
 }
 
+/**
+ * The postcode group nearest `near`, under the {@link NEAR_MAX_KM} dominance geometry — or null when no group qualifies
+ * (out of range, or the runner-up is too close to call). A group's distance is its closest segment's first polyline
+ * vertex; a segment whose geometry fails to parse prices as unreachable rather than aborting the tie-break.
+ */
+function nearestPostcodeGroup(pool: readonly SegmentRow[], near: { lat: number; lon: number }): SegmentRow[] | null {
+	const groups = new Map<string, { rows: SegmentRow[]; km: number }>()
+
+	for (const row of pool) {
+		const key = row.postcode ?? ""
+		let km = Number.POSITIVE_INFINITY
+
+		try {
+			const [firstVertex] = parseJSONStrict<[number, number][]>(row.geometry)
+
+			if (firstVertex) {
+				km = haversineKm(near.lat, near.lon, firstVertex[1], firstVertex[0])
+			}
+		} catch {
+			// Unparseable geometry: this row cannot be sited, so it cannot win the tie-break.
+		}
+
+		const group = groups.get(key)
+
+		if (group) {
+			group.rows.push(row)
+			group.km = Math.min(group.km, km)
+		} else {
+			groups.set(key, { rows: [row], km })
+		}
+	}
+
+	const ranked = [...groups.values()].toSorted((a, b) => a.km - b.km)
+	const [winner, runnerUp] = ranked
+
+	if (!winner || winner.km > NEAR_MAX_KM) return null
+
+	if (runnerUp && runnerUp.km < winner.km * NEAR_DOMINANCE) return null
+
+	return winner.rows
+}
+
 export class StreetInterpolator implements InterpolationLookup {
 	readonly #db: DatabaseSync
 	readonly #ownsDB: boolean
-	readonly #byPostcode: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byStreet: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #byPostcode:
+		| PreparedAll<[postcode: string, street: RouteKey, minNumber: number, maxNumber: number], SegmentRow>
+		| undefined
+	readonly #byStreet: PreparedAll<[street: RouteKey, minNumber: number, maxNumber: number], SegmentRow> | undefined
 	readonly #radiusCalibration: number | undefined
 
 	constructor(opts: { dbPath?: string; database?: DatabaseSync }) {
@@ -129,12 +191,14 @@ export class StreetInterpolator implements InterpolationLookup {
 		if (hasTable(this.#db, "street_segment")) {
 			const columns = `from_hn, to_hn, min_hn, max_hn, parity, postcode, geometry, source, release`
 
-			this.#byPostcode = this.#db.prepare(
+			this.#byPostcode = prepareAll(
+				this.#db,
 				`SELECT ${columns} FROM street_segment
 				 WHERE postcode = ? AND street_norm = ? AND min_hn <= ? AND max_hn >= ?`
 			)
 
-			this.#byStreet = this.#db.prepare(
+			this.#byStreet = prepareAll(
+				this.#db,
 				`SELECT ${columns} FROM street_segment
 				 WHERE street_norm = ? AND min_hn <= ? AND max_hn >= ?`
 			)
@@ -169,29 +233,41 @@ export class StreetInterpolator implements InterpolationLookup {
 
 	find(query: InterpolationQuery): InterpolatedHit | null {
 		if (!this.#byPostcode || !this.#byStreet) return null
-		const streetNorm = canonicalizeRouteKey(normalizeStreetForKey(query.street))
 		const numberRaw = query.number.trim()
 
 		// Strictly-numeric house numbers only — this tier estimates, it doesn't guess at
 		// hyphenated/alphanumeric schemes the ranges don't model.
-		if (!streetNorm || !/^\d+$/.test(numberRaw)) return null
+		if (!/^\d+$/.test(numberRaw)) return null
 		const n = Number(numberRaw)
 
-		let rows: SegmentRow[]
+		// Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
+		// collapse and the saint↔st register swap. A variant advances the ladder when it produces no
+		// ANSWER, not merely no rows — a wrong-register key can cover the number in far-away towns and
+		// then fail the ambiguity gate ("saint pauls place" reaches Nassau's rows; the Brooklyn answer
+		// lives under "st pauls place"), and stopping at rows would eclipse the right variant.
+		for (const variant of streetKeyVariants(query.street)) {
+			const streetNorm = canonicalizeRouteKey(variant)
 
-		if (query.postcode) {
 			// A given ZIP that scopes to nothing is a MISS, not a statewide guess: the retry was
 			// measured (2026-06-11 VT eval) at +2.3pp coverage for a poisoned tail (p99 1.0 → 20.8
 			// km, max 204 km — a unique name statewide can live in a far-away town).
-			rows = this.#byPostcode.all(query.postcode.trim(), streetNorm, n, n) as unknown as SegmentRow[]
-		} else {
-			// No scope given: a name matching ranges across several ZIPs is ambiguous — abstain.
-			rows = this.#byStreet.all(streetNorm, n, n) as unknown as SegmentRow[]
-			const postcodes = new Set(rows.map((r) => r.postcode ?? ""))
+			const rows = query.postcode
+				? this.#byPostcode(query.postcode.trim(), streetNorm, n, n)
+				: this.#byStreet(streetNorm, n, n)
+
+			const hit = this.#answerFromRows(rows, n, query)
 
-			if (postcodes.size > 1) return null
+			if (hit) return hit
 		}
 
+		return null
+	}
+
+	/**
+	 * Resolve one key variant's covering rows to an answer, or null when they cannot honestly give one — the
+	 * parity/ambiguity/tightest-range pipeline the module doc describes.
+	 */
+	#answerFromRows(rows: SegmentRow[], n: number, query: InterpolationQuery): InterpolatedHit | null {
 		if (!rows.length) return null
 
 		// Parity preference: exact side first, then 'mixed' (matches either), then the
@@ -200,9 +276,27 @@ export class StreetInterpolator implements InterpolationLookup {
 		const exact = rows.filter((r) => r.parity === (wantOdd ? "odd" : "even"))
 		const mixed = rows.filter((r) => r.parity === "mixed")
 		const preferred = exact.length ? exact : mixed
-		const pool = preferred.length ? preferred : rows
+		let pool = preferred.length ? preferred : rows
 		const parityMatched = preferred.length > 0
 
+		// No scope given: the covering ranges must agree on ONE postcode or the lookup abstains — a
+		// name spanning towns is ambiguity, not an answer. Counted over the PARITY pool, not all
+		// rows: a section-line boundary road carries a different ZIP per side ("east 13 mile road"
+		// is Fraser 48026 odd / Roseville 48066 even), and the opposite side can never hold the
+		// number it would otherwise veto. When several postcodes survive parity, the caller's
+		// resolved-locality coordinate breaks the tie by segment proximity under the dominance
+		// geometry of {@link NEAR_MAX_KM} — a near-tie stays an abstention.
+		if (!query.postcode) {
+			const postcodes = new Set(pool.map((r) => r.postcode ?? ""))
+
+			if (postcodes.size > 1) {
+				const scoped = query.near ? nearestPostcodeGroup(pool, query.near) : null
+
+				if (!scoped) return null
+				pool = scoped
+			}
+		}
+
 		// Tightest range wins — the most specific claim about where this number lives.
 		let best = pool[0]!