@mailwoman/resolver-wof-sqlite 10.8.0 → 11.0.0

package/lib/address/point.ts

@@ -7,6 +7,7 @@
 
 import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { indexExists } from "@mailwoman/sqlite/introspection"
 import type { PathBuilderLike } from "path-ts"
 
 import type { AddressPointDatabase, AddressPointTable } from "#address/point/schema"
@@ -35,6 +36,27 @@ type AddressPointRow = Pick<AddressPointTable, "lat" | "lon" | "source" | "relea
  */
 const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode"
 
+/**
+ * The widest span of numbers a written range covers on one building or block.
+ */
+const WIDEST_HOUSE_NUMBER_RANGE = 200
+
+/**
+ * Returns whether two hyphenated numbers read as one number rather than a range of houses.
+ *
+ * `8-9 Upper St` is a range, and joining it would answer the different house at number 89.
+ * `19-4074` and Queens's `123-45` cannot be ranges, because a range climbs by a short step.
+ */
+function isJoinedHyphenNumber(number: string): boolean {
+	const parts = /^(\d+)-(\d+)$/.exec(number)
+
+	if (!parts) return false
+
+	const span = Number(parts[2]) - Number(parts[1])
+
+	return span < 0 || span > WIDEST_HOUSE_NUMBER_RANGE
+}
+
 /**
  * Finds an address point by exact normalized `(street, number)` within a postcode,
  * a locality, or a bounding box.
@@ -73,6 +95,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	readonly #byLocalityTail:
 		| PreparedGet<[street: StreetKey, number: string, tailPattern: string], AddressPointRow>
 		| undefined
+	readonly #hasStreetIndex: boolean = false
 	readonly #byBbox:
 		| PreparedGet<
 				[street: StreetKey, number: string, minLat: number, maxLat: number, minLon: number, maxLon: number],
@@ -140,6 +163,8 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
 			)
 
+			this.#hasStreetIndex = indexExists(this.#db, "idx_ap_street")
+
 			this.#byBbox = prepareGet(
 				this.#db,
 				`SELECT ${SELECT_COLS} FROM address_point
@@ -220,6 +245,23 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	) {
 		let row = this.#probe(streetNorm, number, query)
 
+		// A hyphenated number can be one number written two ways: Hawaii's `19-4074`
+		// is stored as `194074` by some sources.
+		// This runs ahead of the range fallback, because that fallback reads it as house number 19.
+		if (!row && isJoinedHyphenNumber(number)) {
+			row = this.#probe(streetNorm, number.replace("-", ""), query)
+		}
+
+		// A grid number leads with a compass letter.
+		// One writer's `N3971` is another source's `n 3971`.
+		if (!row) {
+			const grid = /^([nesw])(?:\s+)?(\d+)$/.exec(number)
+
+			if (grid) {
+				row = this.#probe(streetNorm, number.includes(" ") ? `${grid[1]}${grid[2]}` : `${grid[1]} ${grid[2]}`, query)
+			}
+		}
+
 		// The registers store one number per point, so a range such as "385-387" falls back to its low end.
 		if (!row) {
 			const low = /^(\d+[a-z]?)-\d+[a-z]?$/.exec(number)?.[1]
@@ -307,7 +349,8 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		}
 
 		// The bounding box serves extracts whose points have no postcode or locality, such as OSM.
-		if (!row && query.bbox) {
+		// A database without the street index skips this search, because each miss would scan the whole table.
+		if (!row && query.bbox && this.#hasStreetIndex) {
 			const b = query.bbox
 			const candidate = this.#byBbox!(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon)
 

package/lib/build/slim.ts

@@ -54,7 +54,6 @@ export type SlimBuildPhase =
 	| "postcode"
 	| "names"
 	| "place_population"
-	| "coincident_roles"
 	| "place_abbr"
 	| "fts"
 	| "vacuum"
@@ -314,24 +313,6 @@ async function copyFromSource(
 				.onConflict((oc) => oc.doNothing())
 				.execute()
 		}
-
-		// `ancestors` is intentionally not copied, so the derived `coincident_roles`
-		// table is copied and filtered to surviving spr ids.
-		const relationSchema = out
-			.prepare(`SELECT sql FROM src.sqlite_master WHERE type = 'table' AND name = 'coincident_roles'`)
-			.get() as { sql?: string } | undefined
-
-		if (relationSchema?.sql) {
-			progress("coincident_roles", `${inputPath}: copying dual-role relation`)
-			out.exec(relationSchema.sql.replace(/CREATE TABLE/i, "CREATE TABLE IF NOT EXISTS"))
-
-			out.exec(
-				`INSERT OR IGNORE INTO coincident_roles SELECT * FROM src.coincident_roles
-					WHERE admin_id IN (SELECT id FROM spr) AND locality_id IN (SELECT id FROM spr)`
-			)
-
-			out.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON coincident_roles (admin_id)`)
-		}
 	} finally {
 		out.exec(`DETACH DATABASE src;`)
 	}

package/lib/candidate/lookup.ts

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

package/lib/index.ts

@@ -8,7 +8,6 @@ export type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "
 
 export type {
 	AncestorsTable,
-	CoincidentRolesTable,
 	ConcordancesTable,
 	GeojsonTable,
 	NamesTable,

package/lib/landmark/rows.ts

@@ -0,0 +1,91 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The landmark table's read, shared by the native lookup and the range-read lookup a Worker uses. It holds no database
+ *   client, so a Worker bundle can import it.
+ */
+
+import type { LandmarkHit, LandmarkKind } from "@mailwoman/core/resolver"
+
+import { normalizeLocalityForKey } from "#street/normalize"
+
+/**
+ * One way of writing one place.
+ */
+export interface LandmarkNameTable {
+	name_key: string
+	qid: string
+	/**
+	 * The place's own display name.
+	 */
+	name: string
+	kind: LandmarkKind
+	country: string | null
+	latitude: number
+	longitude: number
+	sitelinks: number
+	/**
+	 * The upper-case spelling of a code alias such as `DTW`, or `null` for an ordinary name.
+	 *
+	 * A code answers only when written in that case, so `Lax` and `Sea` stay words.
+	 */
+	code: string | null
+	/**
+	 * 1 when this is the place's own name in English or its country's language, 0 for a translation or alias.
+	 */
+	is_primary: number
+	/**
+	 * The importance Photon's index holds for an OpenStreetMap place, or `null` for a Wikidata place.
+	 */
+	importance: number | null
+	/**
+	 * The place's short H3 cell, the spatial key an OpenStreetMap layer's manifest names,
+	 * or `null` for a Wikidata place.
+	 */
+	h3_cell: number | null
+}
+
+/**
+ * The read of every row under one name key, best first.
+ */
+export const LANDMARK_BY_NAME_SQL =
+	"SELECT * FROM landmark_name WHERE name_key = ? ORDER BY is_primary DESC, sitelinks DESC, importance DESC, qid"
+
+/**
+ * Returns the key a written name is stored and read under.
+ *
+ * Canonical Unicode form, a typographic apostrophe and a sentence's closing period do not change
+ * which place a name means, so `St George’s.` and `St George's` read one row.
+ */
+export function landmarkNameKey(written: string): string {
+	return normalizeLocalityForKey(written.normalize("NFC").replaceAll("’", "'").trim().replace(/\.+$/u, ""))
+}
+
+/**
+ * Turns the rows under a name's key into hits for that name as it was written.
+ *
+ * A code written in its own case is an identifier, so it ranks ahead of every word spelled the same.
+ * A code row reads only in that case.
+ */
+export function landmarkHitsFromRows(rows: readonly LandmarkNameTable[], name: string): LandmarkHit[] {
+	const written = name.trim()
+	const isCode = (row: LandmarkNameTable) => row.code === written
+
+	return rows
+		.filter((row) => !row.code || isCode(row))
+		.toSorted((a, b) => Number(isCode(b)) - Number(isCode(a)))
+		.map((row) => ({
+			code: isCode(row),
+			qid: row.qid,
+			name: row.name,
+			kind: row.kind,
+			country: row.country,
+			lat: row.latitude,
+			lon: row.longitude,
+			sitelinks: row.sitelinks,
+			primary: row.is_primary === 1,
+			importance: row.importance ?? null,
+		}))
+}

package/lib/landmark.ts

@@ -0,0 +1,94 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The landmark layer: Wikidata places keyed by every name and alias they are written with, ranked by the number of
+ *   Wikipedia language editions that describe them. The source is CC0, so the database may ship.
+ */
+
+import type { LandmarkHit, LandmarkLookup } from "@mailwoman/core/resolver"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { sql, type Kysely } from "kysely"
+import type { PathBuilderLike } from "path-ts"
+
+import { LANDMARK_BY_NAME_SQL, landmarkHitsFromRows, landmarkNameKey, type LandmarkNameTable } from "#landmark/rows"
+import { prepareAll, type PreparedAll } from "#sqlite-utils"
+
+export interface LandmarkDatabase {
+	landmark_name: LandmarkNameTable
+}
+
+/**
+ * The column order the build's positional insert writes.
+ */
+export const LANDMARK_NAME_COLUMNS = [
+	"name_key",
+	"qid",
+	"name",
+	"kind",
+	"country",
+	"latitude",
+	"longitude",
+	"sitelinks",
+	"code",
+	"is_primary",
+	"importance",
+	"h3_cell",
+] as const satisfies ReadonlyArray<keyof LandmarkNameTable>
+
+/**
+ * Creates the table.
+ *
+ * Rows cluster by name, because every read is a probe of one name.
+ */
+export async function createLandmarkTables(db: Kysely<LandmarkDatabase>): Promise<void> {
+	await db.schema
+		.createTable("landmark_name")
+		.addColumn("name_key", "text", (c) => c.notNull())
+		.addColumn("qid", "text", (c) => c.notNull())
+		.addColumn("name", "text", (c) => c.notNull())
+		.addColumn("kind", "text", (c) => c.notNull())
+		.addColumn("country", "text")
+		.addColumn("latitude", "real", (c) => c.notNull())
+		.addColumn("longitude", "real", (c) => c.notNull())
+		.addColumn("sitelinks", "integer", (c) => c.notNull())
+		.addColumn("code", "text")
+		.addColumn("is_primary", "integer", (c) => c.notNull())
+		.addColumn("importance", "real")
+		.addColumn("h3_cell", "integer")
+		.addPrimaryKeyConstraint("landmark_name_pk", ["name_key", "qid"])
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * Returns whether an alias is an identifier code rather than a word:
+ * two to five upper-case letters or digits.
+ */
+export function isLandmarkCode(alias: string): boolean {
+	return /^[\p{Lu}\d]{2,5}$/u.test(alias)
+}
+
+/**
+ * Reads a sealed landmark database.
+ */
+export class LandmarkSqliteLookup implements LandmarkLookup, Disposable {
+	readonly #db: DatabaseClient<LandmarkDatabase>
+
+	readonly #byName: PreparedAll<[nameKey: string], LandmarkNameTable>
+
+	constructor(path: PathBuilderLike) {
+		this.#db = new DatabaseClient<LandmarkDatabase>(path, { readOnly: true })
+
+		this.#byName = prepareAll(this.#db, LANDMARK_BY_NAME_SQL)
+	}
+
+	find(name: string): LandmarkHit[] {
+		return landmarkHitsFromRows(this.#byName(landmarkNameKey(name)), name)
+	}
+
+	[Symbol.dispose](): void {
+		this.#db[Symbol.dispose]()
+	}
+}

package/lib/lookup.ts

@@ -7,7 +7,7 @@
  */
 
 import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
-import type { Ancestor, CoincidentLocality } from "@mailwoman/core/resolver"
+import type { Ancestor } from "@mailwoman/core/resolver"
 import { allRows } from "@mailwoman/core/utils"
 import { haversine } from "@mailwoman/spatial/geometries/point/distance"
 import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
@@ -16,7 +16,6 @@ import type { PathBuilderLike } from "path-ts"
 
 import { ancestorLineage } from "#ancestry"
 import { candidateFromSearchRow, rankCandidates } from "#candidate/scoring"
-import { loadCoincidentLocalities } from "#coincident-roles"
 import {
 	ADDRESS_CONVENTION_TABLE,
 	resolveConvention,
@@ -155,10 +154,6 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 	 * Strategy names already warned about, so an unknown name surfaces once.
 	 */
 	readonly #warnedUnknownStrategies = new Set<string>()
-	/**
-	 * Lazily-built `admin_id → coincident localities` map, null until first use.
-	 */
-	#coincidentRolesCache: Map<number, CoincidentLocality[]> | null = null
 	/**
 	 * Per-id memoized ancestor lineages, queried once per chain.
 	 */
@@ -355,21 +350,6 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 		return found
 	}
 
-	/**
-	 * Dual-role localities coincident with an admin id, or `[]` when the relation table is absent.
-	 */
-	coincidentLocalitiesFor(adminID: number | string): CoincidentLocality[] {
-		const id = typeof adminID === "number" ? adminID : Number(adminID)
-
-		if (!Number.isFinite(id)) return []
-
-		if (!this.#coincidentRolesCache) {
-			this.#coincidentRolesCache = loadCoincidentLocalities(this.database)
-		}
-
-		return this.#coincidentRolesCache.get(id) ?? []
-	}
-
 	/**
 	 * The ancestor lineage of a place, ordered nearest-first with self excluded,
 	 * or `[]` when it has no recorded ancestry.

package/lib/primary-preference.ts

@@ -11,14 +11,15 @@ import type { CandidateTable } from "#candidate/schema"
  *
  * `is_primary` is optional, so an older artifact without the column skips the re-rank without an error.
  */
-export type PrimaryPreferenceRow = Pick<CandidateTable, "neg_rank" | "country_id"> &
+export type PrimaryPreferenceRow = Pick<CandidateTable, "neg_rank"> &
 	Partial<Pick<CandidateTable, "is_primary" | "placetype_id" | "population" | "name_role">>
 
 /**
- * The log10-population penalty applied to an alias row when the top primary-name
- * row for the same key is in another country.
+ * The log10-population penalty applied to an alias row when another row holds
+ * the same key as its primary name.
  *
- * An alias at least 10 times as populous still wins, so alternate names such as "LA" keep working.
+ * An alias at least 10 times as populous still wins, so alternate names such as "LA"
+ * and misspellings of a large city such as "Dehli" keep working.
  */
 export const PRIMARY_PREFERENCE_LOG10 = 1
 
@@ -37,7 +38,7 @@ export const RERANK_FETCH = 64
  */
 export type RankedRow<R> = R & {
 	/**
-	 * `neg_rank` plus any cross-country alias penalty.
+	 * `neg_rank` plus any alias penalty.
 	 *
 	 * Rows are ordered by this value.
 	 * The emitted `prominence` derives from it.
@@ -47,12 +48,11 @@ export type RankedRow<R> = R & {
 	effectiveNegRank: number
 
 	/**
-	 * True when this row is a cross-country alias that the penalty moved behind
-	 * the top primary for the same key.
+	 * True when this row is an alias that the penalty moved behind the top primary for the same key.
 	 *
 	 * A demoted row loses `exactMatch`, so the resolver's country pin cannot promote
-	 * a coincidental foreign exonym back over the primary.
-	 * A dominant alias and a same-country alias are never demoted.
+	 * a coincidental exonym back over the primary.
+	 * A dominant alias is never demoted.
 	 */
 	demoted: boolean
 
@@ -82,7 +82,7 @@ export type RankedRow<R> = R & {
 /**
  * Re-ranks population-ordered candidate rows.
  *
- * A cross-country alias must beat the top primary by `delta` in log10 population.
+ * An alias must beat the top primary by `delta` in log10 population, in any country.
  * The function returns the top `limit` rows.
  *
  * When `placetypes` is given, an exact tie prefers a populated `locality`.
@@ -103,20 +103,13 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 		}
 	}
 
-	const topCountry = topPrimary?.country_id
-
-	const wouldPenalize = (r: R): boolean =>
-		typeof topCountry === "number" && r.is_primary !== 1 && r.country_id !== topCountry
-
-	const isCrossCountryAlias = (r: R): boolean =>
-		wouldPenalize(r) && !(exemptVariantAliases && r.name_role === "variant")
+	const isAliasOfPrimary = (r: R): boolean => topPrimary != null && r.is_primary !== 1
 
 	const annotate = (r: R): RankedRow<R> => {
-		const penalized = isCrossCountryAlias(r)
+		const exempted = exemptVariantAliases && r.name_role === "variant" && isAliasOfPrimary(r)
+		const penalized = isAliasOfPrimary(r) && !exempted
 		const effectiveNegRank = r.neg_rank + (penalized ? delta : 0)
 
-		const exempted = !penalized && exemptVariantAliases && r.name_role === "variant" && wouldPenalize(r)
-
 		return {
 			...r,
 			effectiveNegRank,

package/lib/schema.ts

@@ -170,23 +170,6 @@ export interface ConcordancesTable {
 	lastmodified: number
 }
 
-/**
- * `coincident_roles`.
- *
- * The dual-role relation, where a place is both an admin region and a locality (Berlin the city-state).
- *
- * One row per (admin, locality) pair the resolver can complete a hierarchy with.
- * Surfaced by {@link MailwomanLookupLike.coincidentRolesFor}.
- */
-export interface CoincidentRolesTable {
-	admin_id: number
-	locality_id: number
-	relationship_type: string
-	admin_placetype: string
-	distance_km: number
-	locality_population: number
-}
-
 /**
  * The full schema we hand to `Kysely<WOFDatabase>` / `new DatabaseClient<WOFDatabase>(...)`.
  *
@@ -205,5 +188,4 @@ export interface WOFDatabase {
 	place_population: PlacePopulationTable
 	place_abbr: PlaceAbbrTable
 	concordances: ConcordancesTable
-	coincident_roles: CoincidentRolesTable
 }

package/lib/street/normalize.ts

@@ -536,5 +536,96 @@ export function streetKeyVariants(street: string, locale: StreetLocale = "us"):
 		}
 	}
 
+	for (const candidate of routeKeyVariants(primary)) {
+		if (!variants.includes(candidate)) {
+			variants.push(candidate)
+		}
+	}
+
 	return variants
 }
+
+/**
+ * The route designators a numbered road is written with, by the system the query's prefix selects.
+ *
+ * The forms are the ones US address sources store, measured over the state extracts:
+ * `state road 10`, `state highway 42`, `highway 79`, `united states highway 31`, `interstate 35`.
+ */
+const ROUTE_DESIGNATORS: Readonly<Record<"us" | "state" | "interstate", readonly string[]>> = {
+	us: ["united states highway", "us highway", "us route", "highway", "route"],
+	state: ["state road", "state highway", "state route", "highway", "route"],
+	interstate: ["interstate"],
+}
+
+/**
+ * The spellings of a county road, as US address sources store them.
+ *
+ * Wisconsin leads with `cth`, Texas with `county road`, and Florida with `cr`,
+ * and a county road may take letters, as `cth cw` does.
+ */
+const COUNTY_ROAD_DESIGNATORS: readonly string[] = ["county road", "county highway", "county", "cth", "co road", "cr"]
+
+/**
+ * Reads a county road's designator from a query, such as `county rd cw`,
+ * `cty hwy 5`, `co rd 12`, `cr 40` or `cth a`.
+ *
+ * A bare `co 5` stays a Colorado state route.
+ */
+const COUNTY_ROAD_QUERY =
+	/^(?:(?:county|cty|co) (?:road|rd|highway|hwy|trunk|trunk highway) (\d+[a-z]?|[a-z]{1,3})|(?:county|cty|cth|cr) (\d+[a-z]?|[a-z]{1,2}))$/
+
+const COMPASS_WORDS: readonly string[] = ["north", "south", "east", "west"]
+
+/**
+ * A query's route number and system: `in 245` and `state route 245` read as state routes,
+ * `us 93` as a US route, and `i 68` as an interstate.
+ *
+ * A two-letter prefix is any state's code, because the shape is the same in every state.
+ */
+function parseRouteQuery(key: string): { system: keyof typeof ROUTE_DESIGNATORS; route: string } | null {
+	const match =
+		/^(us|i|interstate|[a-z]{2}|state|sr)(?: (?:road|rd|route|rte|rt|highway|hwy))? (\d+[a-z]?)$/.exec(key) ??
+		/^(highway|hwy|route|rte)() ?(\d+[a-z]?)$/.exec(key)
+
+	if (!match) return null
+
+	const route = match.at(-1)!
+	const prefix = match[1]!
+
+	if (prefix === "us") return { system: "us", route }
+
+	if (prefix === "i" || prefix === "interstate") return { system: "interstate", route }
+
+	return { system: "state", route }
+}
+
+/**
+ * Lists the stored spellings of a numbered route, with and without the compass word a source may add.
+ *
+ * `IN-245` is stored as `north state road 245` in Indiana, so a query gives no hint of the spelling.
+ * The caller's postcode, locality or box still scopes each probe.
+ */
+export function routeKeyVariants(key: StreetKey): StreetKey[] {
+	const written = key.replaceAll("-", " ")
+	const countyRoad = COUNTY_ROAD_QUERY.exec(written)
+
+	if (countyRoad) {
+		const route = countyRoad[1] ?? countyRoad[2]!
+
+		return COUNTY_ROAD_DESIGNATORS.map((designator) => `${designator} ${route}` as StreetKey)
+	}
+
+	const parsed = parseRouteQuery(written)
+
+	if (!parsed) return []
+
+	return ROUTE_DESIGNATORS[parsed.system].flatMap((designator) => {
+		const base = `${designator} ${parsed.route}`
+
+		return [
+			base,
+			...COMPASS_WORDS.map((compass) => `${compass} ${base}`),
+			...COMPASS_WORDS.map((compass) => `${base} ${compass}`),
+		] as StreetKey[]
+	})
+}

package/lib/types.ts

@@ -109,10 +109,15 @@ export interface PlaceCandidate {
 	regionScopeMiss: boolean | null
 
 	/**
-	 * Set when the variant exemption spared the candidate from the cross-country
-	 * alias penalty, by the candidate-table backend only.
+	 * Set when the variant exemption spared the candidate from the alias penalty,
+	 * by the candidate-table backend only.
 	 */
 	variantAliasExempted: true | null
+
+	/**
+	 * Set when the input matched an alias of this place, by the candidate-table backend only.
+	 */
+	matchedAlias?: true | null
 }
 
 /**

package/out/address/point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../lib/address/point.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAEnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,oBAAoB,EAAqB,MAAM,uBAAuB,CAAA;AAEpF,OAAO,EASN,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAA;AAc1B;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB,CAAC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CAC3F,YAAW,kBAAkB,EAAE,UAAU;;IAiCzC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YACC,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE;QACL,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAA;QACrC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;KAC7B,EA6CN;IAED,IAAI,CAAC,KAAK,EAAE;QACX,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAC/E,GAAG,eAAe,GAAG,IAAI,CAsCzB;IA4LD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../lib/address/point.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAGnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,oBAAoB,EAAqB,MAAM,uBAAuB,CAAA;AAEpF,OAAO,EASN,KAAK,YAAY,EACjB,MAAM,mBAAmB,CAAA;AAmC1B;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB,CAAC,EAAE,SAAS,oBAAoB,GAAG,oBAAoB,CAC3F,YAAW,kBAAkB,EAAE,UAAU;;IAkCzC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YACC,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE;QACL,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAA;QACrC,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;KAC7B,EA+CN;IAED,IAAI,CAAC,KAAK,EAAE;QACX,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAC/E,GAAG,eAAe,GAAG,IAAI,CAsCzB;IA8MD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}