@mailwoman/resolver-wof-sqlite 9.0.0 → 9.2.0

package/fst-serialize.ts

@@ -18,9 +18,19 @@
  *
  *   EDGE TABLE [edgeCount × 8 bytes] stringIdx u32 index into string table targetState u32
  *
- *   PLACE TABLE [placeCount × 56 bytes] wofID u32 placetypeIdx u8 index into PLACETYPE_ORDER chainLen
- *   u8 0..8 _pad u16 nameIdx u32 index into string table importance f32 Wikipedia importance [0,1]
- *   (V2); was population u32 (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0)
+ *   PLACE TABLE [placeCount × 60 bytes at V5, 56 below] wofID u32 placetypeIdx u8 index into
+ *   PLACETYPE_ORDER chainLen u8 0..8 crossCountryBranches u8 (header flags bit0 gates the read)
+ *   placeFlags u8 (V5; bit0 = encyclopedic present) nameIdx u32 index into string table referential f32
+ *   population-anchored likelihood [0,1] — was the conflated `importance` (V2–V4), was population u32
+ *   (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0) encyclopedic f32 (V5 only;
+ *   read only when placeFlags bit0 is set)
+ *
+ *   THE V5 BUMP IS THE TWO-SCORE SPLIT (ROAD_TO_V9 §2 R1). Through V4 one float carried whichever score
+ *   the source database held, and nothing in the bytes said which — so a reader could not tell a
+ *   population proxy from a Wikipedia score. V5 names the ranking score `referential` and gives the
+ *   encyclopedic signal its own slot plus a PER-PLACE presence bit, because most places have no
+ *   Wikipedia article and a 0 there would be a fact nobody recorded. `fst-freshness.ts` reports every
+ *   V4-and-below artifact as format-stale for exactly this reason: its single float is unattributable.
  */
 
 import { tryParsingJSON } from "@mailwoman/core/objects"
@@ -50,6 +60,34 @@ const NARROW_STATE_ENTRY_SIZE = 12
  */
 const VERSION_WITH_METADATA = 3
 
+/**
+ * Format version that split the single `importance` float into `referential` + `encyclopedic`, growing the place entry
+ * from 56 to 60 bytes and claiming the previously-reserved `pp+7` byte as {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
+ */
+const VERSION_TWO_SCORE_SPLIT = 5
+
+/**
+ * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const SPLIT_PLACE_ENTRY_SIZE = 60
+
+/**
+ * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const LEGACY_PLACE_ENTRY_SIZE = 56
+
+/**
+ * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
+ */
+const ENCYCLOPEDIC_OFFSET = 56
+
+/**
+ * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-PLACE rather than per-file
+ * because absence is the common case — roughly 89% of the 2026-08-05 gazetteer has no Wikipedia article — and a
+ * file-level flag would force every one of those rows to claim a 0 it never had.
+ */
+const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
+
 /**
  * File magic. A reader rejects anything not starting with these four bytes before parsing further.
  */
@@ -58,7 +96,7 @@ const MAGIC = Buffer.from("FST\0", "ascii")
 /**
  * Format version this serializer emits. See {@link VERSION_WIDE_STATE_COUNTERS} for what each bump changed.
  */
-const VERSION = 4
+const VERSION = 5
 
 /**
  * The format version this tree WRITES, published so a freshness guard can call an older artifact format-stale without
@@ -83,9 +121,9 @@ const STATE_ENTRY_SIZE = 16
 const EDGE_ENTRY_SIZE = 8
 
 /**
- * Place-table entry: the place id, its placetype, coordinates, and importance.
+ * Place-table entry at the version this tree WRITES: the place id, its placetype, coordinates, and both scores.
  */
-const PLACE_ENTRY_SIZE = 56
+const PLACE_ENTRY_SIZE = SPLIT_PLACE_ENTRY_SIZE
 
 /**
  * Longest ancestry chain stored per place. Deeper hierarchies are truncated at the leaf end, since the specific end of
@@ -246,11 +284,14 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 			buf.writeUInt32LE(place.wofID, pp)
 			buf.writeUInt8(placetypeToIdx.get(place.placetype) ?? 0, pp + 4)
 			buf.writeUInt8(chainLen, pp + 5)
-			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 reserved.
+			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 = v5 placeFlags.
 			buf.writeUInt8(hasAmbiguity ? Math.min(place.crossCountryBranches ?? 0, 255) : 0, pp + 6)
-			buf.writeUInt8(0, pp + 7)
+			// An absent encyclopedic score writes flag 0 AND a 0.0 float. The float is unread in that
+			// state, so absence can never surface as a score — the meaning-of-zero rule, in bytes.
+			const hasEncyclopedic = place.encyclopedic !== undefined
+			buf.writeUInt8(hasEncyclopedic ? PLACE_FLAG_HAS_ENCYCLOPEDIC : 0, pp + 7)
 			buf.writeUInt32LE(intern(place.name), pp + 8)
-			buf.writeFloatLE(place.importance, pp + 12)
+			buf.writeFloatLE(place.referential, pp + 12)
 			buf.writeFloatLE(place.lat, pp + 16)
 			buf.writeFloatLE(place.lon, pp + 20)
 
@@ -258,6 +299,8 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 				buf.writeUInt32LE(ci < chainLen ? validChain[ci]! : 0, pp + 24 + ci * 4)
 			}
 
+			buf.writeFloatLE(hasEncyclopedic ? place.encyclopedic! : 0, pp + ENCYCLOPEDIC_OFFSET)
+
 			placeIdx++
 		}
 	}
@@ -280,6 +323,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	if (version < 1 || version > VERSION) throw new Error(`FST version ${version} unsupported (expected 1..${VERSION})`)
 	const isV2 = version >= 2
+	const isSplit = version >= VERSION_TWO_SCORE_SPLIT
 	// flags bit0 (survey #4): place rows carry surface-ambiguity data in the former _pad byte.
 	const hasAmbiguity = (buf.readUInt16LE(6) & 1) === 1
 
@@ -312,6 +356,8 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	// --- State table ---
 	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
+	// v5 grew the place entry by the encyclopedic float; v4-and-below files are read at the old stride.
+	const placeEntrySize = version >= VERSION_TWO_SCORE_SPLIT ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
 	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
@@ -341,7 +387,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 		const places: PlaceEntry[] = new Array(placeCountForState)
 
 		for (let pi = 0; pi < placeCountForState; pi++) {
-			const pp = placeTableStart + (placeStart + pi) * PLACE_ENTRY_SIZE
+			const pp = placeTableStart + (placeStart + pi) * placeEntrySize
 			const chainLen = buf.readUInt8(pp + 5)
 			const parentChain: number[] = []
 
@@ -349,20 +395,30 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 				parentChain.push(buf.readUInt32LE(pp + 24 + ci * 4))
 			}
 
-			const rawImportance = isV2
+			// v1 stored a raw population u32 here; v2–v4 the conflated `importance` float; v5 the
+			// referential score. A v1 file's population is mapped through the SAME curve
+			// `referentialFromPopulation` uses, so its value is genuinely referential — the only
+			// generation of this format for which that can be said without reading the source database.
+			const referential = isV2
 				? buf.readFloatLE(pp + 12)
 				: Math.min(1, Math.log2(1 + buf.readUInt32LE(pp + 12) / 1000) / 14)
 
+			// Per-place presence bit (v5+). A v4-and-below file has no encyclopedic channel at all, so
+			// the field stays undefined rather than reading the reserved byte as a flag.
+			const hasEncyclopedic =
+				isSplit && (buf.readUInt8(pp + 7) & PLACE_FLAG_HAS_ENCYCLOPEDIC) === PLACE_FLAG_HAS_ENCYCLOPEDIC
+
 			places[pi] = {
 				wofID: buf.readUInt32LE(pp),
 				placetype: PLACETYPE_ORDER[buf.readUInt8(pp + 4)] ?? "locality",
 				name: strings[buf.readUInt32LE(pp + 8)]!,
-				importance: rawImportance,
+				referential,
 				lat: buf.readFloatLE(pp + 16),
 				lon: buf.readFloatLE(pp + 20),
 				parentChain,
 				// Header flags bit0 gates the read (survey #4): pre-ambiguity artifacts expose undefined.
 				...(hasAmbiguity ? { crossCountryBranches: buf.readUInt8(pp + 6) } : {}),
+				...(hasEncyclopedic ? { encyclopedic: buf.readFloatLE(pp + ENCYCLOPEDIC_OFFSET) } : {}),
 			}
 		}
 

package/fst-types.ts

@@ -13,7 +13,25 @@ export interface PlaceEntry {
 	placetype: PlacetypeID
 	name: string
 	parentChain: number[]
-	importance: number
+	/**
+	 * REFERENTIAL likelihood in [0, 1] — population-anchored (`referentialFromPopulation`), and the ONLY score the
+	 * decoder bias is allowed to read (ROAD_TO_V9 §2, ratified 2026-08-06).
+	 *
+	 * This field was called `importance` through format v4, where it carried whichever score the source database happened
+	 * to hold: the population proxy on a database with no `place_importance` table (which is every shipped
+	 * `fst-per-locale` binary), the Wikipedia score where the concordance join landed otherwise. The rename is the point
+	 * — a v4 artifact's value is a CONFLATION that cannot be told apart after the fact, which is why `fst-freshness.ts`
+	 * reports anything below {@link FST_FORMAT_VERSION} as format-stale rather than reading it as referential.
+	 */
+	referential: number
+	/**
+	 * Encyclopedic (Wikipedia) importance in [0, 1], fan-out-guarded per #1497. Carried for consumers that want to
+	 * DISPLAY salience; never read by the decoder or by any ranking.
+	 *
+	 * `undefined` = this place has no encyclopedic signal, or the artifact predates format 5. NEVER conflate either with
+	 * 0 — the meaning-of-zero rule; roughly 89% of the 2026-08-05 gazetteer's rows have no Wikipedia article at all.
+	 */
+	encyclopedic?: number
 	lat: number
 	lon: number
 	/**
@@ -64,7 +82,23 @@ export interface FSTProvenance {
 	placeCount: number
 	edgeCount: number
 	nameInsertions: number
+	/**
+	 * How many places carried a non-zero REFERENTIAL score at build time. Named `importanceMatches` for stamp
+	 * compatibility with every artifact written before the two-score split — renaming the JSON key would make every
+	 * existing stamp unreadable, and the number means the same thing it always did on a population-built artifact.
+	 */
 	importanceMatches: number
+	/**
+	 * How many places carried an ENCYCLOPEDIC score at build time. `undefined` on a pre-split build — which is not the
+	 * same as 0 (a v5 build against a population-only database), so the freshness report says the two in different
+	 * words.
+	 */
+	encyclopedicMatches?: number
+	/**
+	 * How the builder obtained its two scores — an {@link ImportanceSplitSource}. Recorded so an artifact states, in its
+	 * own provenance, whether its encyclopedic channel is real, reconstructed from a legacy conflated column, or absent.
+	 */
+	importanceSource?: string
 	sourceDB?: string
 	/**
 	 * MD5 of the source database's bytes at build time — the artifact's link to the gazetteer it is a projection of.

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:
@@ -123,6 +123,18 @@ export const PLACE_BBOX_TABLE = "place_bbox"
  */
 export const PLACE_POPULATION_TABLE = "place_population"
 
+/**
+ * Name of the auxiliary table holding the two salience scores per place — `referential` (population-anchored, the
+ * ranking backbone) and `encyclopedic` (the Wikipedia join, NULL when there is no article). Built by `mailwoman
+ * gazetteer importance`; schema and derivations in `place-importance-schema.ts`.
+ *
+ * The lookup reads ONLY `encyclopedic` from it, and only to CARRY the value onto the result — referential is derived
+ * from the population already joined, and no ORDER BY anywhere touches this table (ROAD_TO_V9 §2). Sparse and
+ * schema-versioned: a pre-split gazetteer has this table with a single conflated `importance` column instead, which the
+ * lookup's column probe deliberately refuses to read.
+ */
+export const PLACE_IMPORTANCE_TABLE = "place_importance"
+
 /**
  * Counters for a single `buildPlaceSearchFTS` run. Exposed so callers (CLI, lazy-build) can render progress to the
  * user.
@@ -314,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,9 +19,34 @@ 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"
+
+export {
+	ImportanceIndex,
+	IMPORTANCE_JOIN_GATE_KM,
+	type ImportanceIndexStats,
+	loadImportanceIndex,
+} from "./candidate-importance.ts"
+
 export { WOFCandidateTableLookup, type WOFCandidateTableLookupOpts } from "./candidate-lookup.ts"
 
 export {
@@ -92,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]!