@mailwoman/resolver-wof-sqlite 10.3.0 → 10.5.0

package/README.md

@@ -33,14 +33,14 @@ for (const c of candidates) {
 }
 ```
 
-## A database that cannot answer says so on construction
+## A database that cannot answer throws on construction
 
 Databases are `ATTACH`ed by a schema name **derived from the filename**, and queries route to them by matching that name against the requested placetype — `postalcode_us` serves `postalcode`. Two ways that used to fail without logging, and both now throw when you build the lookup:
 
-- The name does not route. `postcode-ca-overture.db` derives `postcode_ca_overture`, and the router tests `startsWith("postalcode_")` — **"postcode" is not "postalcode"**. It held 843,739 Canadian codes and answered every query with zero hits, which is indistinguishable from "this country has no places".
-- The database carries `spr` but no `place_search`. It routes, then dies mid-`SELECT`.
+- The name does not route. `postcode-ca-overture.db` derives `postcode_ca_overture`, and the router tests `startsWith("postalcode_")` — **"postcode" is not "postalcode"**. It held 843,739 Canadian codes and answered every query with zero hits. A caller could not tell that result from "this country has no places".
+- The database has `spr` but no `place_search`. It routes, then dies mid-`SELECT`.
 
-The predicate is the **table rather than the filename**: a database carrying `spr` is claiming to be a place database, and every lookup path here reaches the FTS index. A relation-table database like `postcode-locality-<cc>.db` carries no `spr`, never makes that claim, and is exempt — which is what keeps the documented default database list working.
+The predicate is the **table rather than the filename**: a database with an `spr` table is claiming to be a place database, and every lookup path here reaches the FTS index. A relation-table database like `postcode-locality-<cc>.db` has no `spr`, never makes that claim, and is exempt. That exemption keeps the documented default database list working.
 
 ```
 WOFSQLitePlaceLookup: …/postcode-ca-overture.db carries "spr" but no "place_search" table, so it
@@ -118,8 +118,8 @@ The CLI:
 - Populates it from `spr` + `names` (alternate-name concatenation included).
 - Builds the `place_bbox` R*Tree virtual table from `spr.min\_*`/`spr.max\_\*` columns for the
   proximity + bbox query support.
-- Reports progress to stderr per phase (`checking` → `creating` → `populating` → `creating-bbox`
-  → `populating-bbox` → `done`).
+- Reports progress to stderr per phase, in the order `checking`, `creating`, `populating`, `creating-bbox`,
+  `populating-bbox` and `done`.
 - Exits 0 with a no-op message if both indexes already exist.
 
 ```bash
@@ -131,7 +131,7 @@ mailwoman gazetteer build fts /path/to/wof.db --drop
 
 ### Slim builds (retired CLI — module only)
 
-Builds a trimmed WOF SQLite distribution sized for browser-side deployments (Path B of the demo plan). The full admin-US distribution is ~4 GB; a slim US bundle with the top-1k localities by population plus all postcodes lands at **~35 MB** — small enough to ship as a static asset.
+Builds a trimmed WOF SQLite distribution sized for browser-side deployments (Path B of the demo plan). The full admin-US distribution is ~4 GB. A slim US bundle with the top-1k localities by population plus all postcodes lands at **~35 MB**, small enough to ship as a static asset.
 
 ```bash
 # Defaults: --top 1000 localities, --countries US, drops geojson after building aux tables
@@ -158,7 +158,7 @@ What survives in the slim DB:
 - All `names` rows for the selected place IDs
 - Fresh `place_search` (FTS5), `place_bbox` (R\*Tree), `place_population` aux tables
 
-What gets dropped: the `geojson` table, which is build-time only — `lookup.ts` never reads it at query time, and it accounts for ~95% of the on-disk size. The `place_population` aux table consumes `wof:population` from geojson before we drop it.
+What gets dropped: the `geojson` table. That table is build-time only. `lookup.ts` never reads it at query time, and it accounts for ~95% of the on-disk size. The `place_population` aux table consumes `wof:population` from geojson before we drop it.
 
 `WOFSQLitePlaceLookup` opens the slim DB without any code change. Out-of-set queries (a locality not in the top-K) correctly return zero hits.
 
@@ -186,7 +186,7 @@ The resolver scores candidates by:
 4. - `countryMatchBoost` when the country filter matches.
 5. - `directChildBoost` / `descendantBoost` when `parentId` is set.
 6. - `proximityBoost / (1 + distanceKm / proximityScaleKm)` when `near: {lat, lon}` is set — decays
-     smoothly with distance from the user's position. At distance 0 the boost is full magnitude; at
+     smoothly with distance from the user's position. At distance 0 the boost is full magnitude, and at
      `proximityScaleKm` (default 100 km) it's half.
 7. − `lengthPenaltyWeight` × excess-length penalty (favors short matches over long matches on short
    queries).
@@ -237,7 +237,7 @@ Defaults are in `lookup.ts::DEFAULT_WEIGHTS`.
 are all stripped safely before going to FTS5. Per-token rules:
 
 - **Bare tokens** (`"Paris"`, `"62701"`) become FTS5 **phrase matches**: `"Paris"` matches places
-  named exactly "Paris", `"62701"` matches the postcode 62701 exactly.
+  whose name is exactly "Paris", `"62701"` matches the postcode 62701 exactly.
 - **A trailing `*`** (`"627*"`, `"Pari*"`) becomes FTS5 **prefix syntax**: `627*` matches every
   postcode starting with 627, `Pari*` matches Paris / Parishville / etc. The caller explicitly
   signals "prefix"; bare tokens stay phrase-matched for safety.
@@ -249,21 +249,21 @@ matching the Los Angeles ZIP corridor.
 
 ## Attribution (CC-BY 4.0)
 
-Who's On First data is licensed [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Downstream applications shipping resolved results from this package **must** carry an attribution notice — for example:
+Who's On First data is licensed [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). Downstream applications shipping resolved results from this package **must** display an attribution notice — for example:
 
 > Place data via [Who's On First](https://whosonfirst.org/) © Mapzen + contributors, CC-BY 4.0.
 
-This package itself is AGPL-3.0; the WOF data it indexes is CC-BY 4.0. The two licenses are separate — your application must comply with both.
+This package itself is AGPL-3.0, and the WOF data it indexes is CC-BY 4.0. The two licenses are separate — your application must comply with both.
 
 ## Integration tests
 
-`resolver-wof-sqlite/integration.test.ts` exercises the resolver against a real WOF SQLite distribution. The suite is **skipped** when no DB is present — set `MAILWOMAN_WOF_DB` to override the lookup path, otherwise it defaults to `$MAILWOMAN_DATA_ROOT/db/wof/whosonfirst-data-admin-us-latest.db` (the canonical lab location). CI runs against the fixture-only suites; operators with real WOF data locally get an extra layer of validation.
+`resolver-wof-sqlite/integration.test.ts` exercises the resolver against a real WOF SQLite distribution. The suite is **skipped** when no DB is present — set `MAILWOMAN_WOF_DB` to override the lookup path, otherwise it defaults to `$MAILWOMAN_DATA_ROOT/db/wof/whosonfirst-data-admin-us-latest.db` (the canonical lab location). CI runs against the fixture-only suites. Operators with real WOF data locally get an extra layer of validation.
 
 Coverage includes: placetype filtering, country filtering, the empty-result case, FTS5 special-character sanitization, Japanese alt-name resolution, parent-constrained lookup, and a performance budget (`findPlace` < 250 ms against the 142 k-row US admin database).
 
 ## Concurrency model
 
-This package opens a single `node:sqlite` connection per `WOFSQLitePlaceLookup` instance. SQLite is single-writer / multiple-reader; the Kysely wrapper around the connection serializes all queries through a mutex. For high-concurrency HTTP servers, instantiate one resolver per request handler or per pool slot — sharing a single instance across concurrent requests is safe (queries queue) but won't parallelize across cores.
+This package opens a single `node:sqlite` connection per `WOFSQLitePlaceLookup` instance. SQLite is single-writer / multiple-reader, and the Kysely wrapper around the connection serializes all queries through a mutex. For high-concurrency HTTP servers, instantiate one resolver per request handler or per pool slot — sharing a single instance across concurrent requests is safe (queries queue) but won't parallelize across cores.
 
 ## License
 

package/lib/address/point/schema.ts

@@ -126,7 +126,7 @@ export async function createAddressPointIndexes(db: AddressPointSchemaHandle): P
 		.execute()
 
 	await db.schema.createIndex("idx_ap_streetkey").on("address_point").columns(["postcode", "street_key"]).execute()
-	// Street-first index for the bbox scope: OSM points often have no postcode or locality,
+	// Street-first index for the bbox scope: some OSM points have no postcode or locality,
 	// so the reader scopes a `(street_norm, number)` probe by the resolved locality's bbox.
 	await db.schema.createIndex("idx_ap_street").on("address_point").columns(["street_norm", "number"]).execute()
 }

package/lib/address/point.ts

@@ -52,10 +52,18 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	readonly #db: DatabaseClient<DB>
 	readonly #locale: StreetLocale
 	readonly #localityKeys: "full" | "abbreviated"
+	readonly #localityLevel: "place" | "finest"
 	readonly #byPostcode: PreparedGet<[postcode: string, street: StreetKey, number: string], AddressPointRow> | undefined
 	readonly #byPostcodeLocality:
 		| PreparedGet<[postcode: string, locality: NameKey, street: StreetKey, number: string], AddressPointRow>
 		| undefined
+	/**
+	 * This query counts the distinct stored localities that hold one (postcode, street, number) key.
+	 * Unit siblings share a locality, so they count once.
+	 */
+	readonly #postcodeKeyPlaces:
+		| PreparedGet<[postcode: string, street: StreetKey, number: string], { places: number }>
+		| undefined
 	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey, number: string], AddressPointRow> | undefined
 	/**
 	 * This query matches the locality key by its suffix, for a `zh` query that gives the 鄉鎮市區 without its 縣市.
@@ -82,16 +90,29 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	 * Some counties abbreviate them (`addi` for Addison).
 	 * Other counties replace them with the parent town.
 	 *
+	 * @param opts.localityLevel The kind of place the extract stores in `locality_norm`.
+	 * With `"place"`, `locality_norm` holds the place an address line gives, such as a BAN commune.
+	 * With `"finest"`, `locality_norm` holds the finest place the source recorded.
+	 * That place can be a part of the place the line gives.
+	 * The OSM builder stores `addr:suburb` before `addr:city`, so
+	 * `Teschener Weg 5, 14163 Berlin` is stored under `zehlendorf`.
+	 *
 	 * @defaultValue `"us"`
 	 * @defaultValue `"abbreviated"` for `"us"` and `"full"` for every other locale.
+	 * @defaultValue `"place"`
 	 */
 	constructor(
 		dbPath: PathBuilderLike,
-		opts: { streetLocale?: StreetLocale; localityKeys?: "full" | "abbreviated" } = {}
+		opts: {
+			streetLocale?: StreetLocale
+			localityKeys?: "full" | "abbreviated"
+			localityLevel?: "place" | "finest"
+		} = {}
 	) {
 		this.#db = new DatabaseClient<DB>(dbPath, { readOnly: true })
 		this.#locale = opts.streetLocale ?? "us"
 		this.#localityKeys = opts.localityKeys ?? (this.#locale === "us" ? "abbreviated" : "full")
+		this.#localityLevel = opts.localityLevel ?? "place"
 
 		// An extract without an `address_point` table, such as an interrupted build, makes every lookup miss.
 		if (hasTable(this.#db, "address_point")) {
@@ -107,6 +128,12 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 				 WHERE postcode = ? AND locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
 			)
 
+			this.#postcodeKeyPlaces = prepareGet(
+				this.#db,
+				`SELECT COUNT(DISTINCT locality_norm) AS places FROM address_point
+				 WHERE postcode = ? AND street_norm = ? AND number = ?`
+			)
+
 			this.#byLocality = prepareGet(
 				this.#db,
 				`SELECT ${SELECT_COLS} FROM address_point
@@ -246,6 +273,8 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		}
 	): AddressPointRow | null {
 		let row: AddressPointRow | null = null
+		// A postcode row stored under a different locality waits until the probe for the query's own locality misses.
+		let heldBack: AddressPointRow | null = null
 
 		if (query.postcode) {
 			const postcode = query.postcode.trim()
@@ -257,7 +286,11 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			const agreeing = localityKey ? this.#byPostcodeLocality!(postcode, localityKey, streetNorm, number) : null
 			const candidate = agreeing ?? this.#byPostcode!(postcode, streetNorm, number)
 
-			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : null
+			if (candidate && !this.#scopeContradicts(candidate, query)) {
+				row = candidate
+			} else if (candidate && this.#isSublocalityRow(candidate, postcode, streetNorm, number, query.bbox)) {
+				heldBack = candidate
+			}
 		}
 
 		if (!row && query.locality) {
@@ -269,6 +302,10 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			row = this.#byLocalityTail(streetNorm, number, `%${query.localityTail}`)
 		}
 
+		if (!row && heldBack) {
+			row = heldBack
+		}
+
 		// The bounding box serves extracts whose points have no postcode or locality, such as OSM.
 		if (!row && query.bbox) {
 			const b = query.bbox
@@ -299,17 +336,58 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	 * A row field that is empty never contradicts.
 	 * The locality is compared only when the extract's `localityKeys` is `"full"`,
 	 * because abbreviated keys would reject correct rows.
+	 *
+	 * Two locality keys agree when they are equal or when one is the leading words of the other.
+	 * A German disambiguated name such as `Lauta b Hoyerswerda` or `Freiberg Sachs` begins with the place
+	 * name that OSM's `addr:city` records, and a word boundary keeps `lauta` apart from `lautabach`.
 	 */
 	#scopeContradicts(row: AddressPointRow, query: { postcode?: string; locality?: string }): boolean {
 		if (query.postcode && row.postcode && row.postcode.trim() !== query.postcode.trim()) return true
 
 		if (this.#localityKeys === "full" && query.locality && row.locality_norm) {
-			return row.locality_norm !== this.#localityKey(query.locality)
+			const queryKey = this.#localityKey(query.locality)
+
+			const [shorter, longer] =
+				row.locality_norm.length <= queryKey.length ? [row.locality_norm, queryKey] : [queryKey, row.locality_norm]
+
+			return shorter !== longer && !longer.startsWith(`${shorter} `)
 		}
 
 		return false
 	}
 
+	/**
+	 * Returns whether a postcode row stored under a different locality lies in a part of the queried place.
+	 *
+	 * Only an extract whose `localityLevel` is `"finest"` can store a part of a place.
+	 * In a `"place"` extract, a different stored locality is a different place.
+	 *
+	 * In a `"finest"` extract, the row is accepted as part of the queried place when two conditions hold.
+	 *
+	 * No other stored locality holds the same (postcode, street, number) key.
+	 * When the caller supplies the box around the query's resolved locality, the row lies inside it.
+	 *
+	 * The caller probes the query's own locality before it uses this row.
+	 * A postcode key that two places share therefore still answers the place the query gives.
+	 */
+	#isSublocalityRow(
+		row: AddressPointRow,
+		postcode: string,
+		streetNorm: StreetKey,
+		number: string,
+		bbox: { minLat: number; maxLat: number; minLon: number; maxLon: number } | null
+	): boolean {
+		if (this.#localityLevel !== "finest") return false
+
+		if (row.postcode && row.postcode.trim() !== postcode) return false
+
+		if ((this.#postcodeKeyPlaces?.(postcode, streetNorm, number)?.places ?? 0) !== 1) return false
+
+		if (!bbox) return true
+
+		return row.lat >= bbox.minLat && row.lat <= bbox.maxLat && row.lon >= bbox.minLon && row.lon <= bbox.maxLon
+	}
+
 	[Symbol.dispose](): void {
 		this.#db[Symbol.dispose]()
 	}

package/lib/candidate/ancestors/sidecar.ts

@@ -132,13 +132,13 @@ export async function buildAncestorsSidecar(ctx: {
 	const postOf = new Map<number, number>()
 
 	for (const kids of childrenOf.values()) {
-		// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass just built
+		// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass built
 		kids.sort((a, b) => a - b)
 	}
 
 	const roots = [...forest].filter((id) => !canonicalParentOf.has(id))
 
-	// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass just built
+	// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass built
 	roots.sort((a, b) => a - b)
 
 	let counter = 0
@@ -174,7 +174,7 @@ export async function buildAncestorsSidecar(ctx: {
 	const insInterval = out.prepare(`INSERT INTO ${CANDIDATE_INTERVAL_TABLE} VALUES (?, ?, ?)`)
 	const labeled = [...preOf.keys()]
 
-	// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass just built
+	// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass built
 	labeled.sort((a, b) => a - b)
 
 	out.exec("BEGIN")

package/lib/candidate/importance.ts

@@ -63,7 +63,7 @@ interface ScoredPlace {
 /**
  * What {@link loadImportanceIndex} measured while reading the source.
  *
- * Reported by the builder so a run reports how much of the gazetteer it actually scored,
+ * Reported by the builder so a run reports how much of the gazetteer it scored,
  * rather than leaving the caller to infer it from a column full of nulls.
  */
 export interface ImportanceIndexStats {
@@ -108,7 +108,7 @@ export class ImportanceIndex {
 	 * The key matched a scored group, but the nearest member was outside the radius,
 	 * so it is a different place wearing the same name.
 	 *
-	 * This is the number worth watching across rebuilds.
+	 * Compare this number across rebuilds.
 	 * A jump means the score source and the admin source have drifted apart
 	 * and the join is being asked to guess.
 	 * It does not mean the radius is too tight.

package/lib/candidate/own-name.ts

@@ -31,7 +31,7 @@ export const VARIANT_SIMILARITY_MIN = 0.85
  * BGN/pcgn-flavored Cyrillic romanization, folded to the name-key alphabet.
  *
  * Digraph outputs (zh, kh, ts, ch, sh, shch, yu, ya) match the dominant transliteration
- * conventions the gazetteer's Latin aliases actually use.
+ * conventions the gazetteer's Latin aliases use.
  * The `w`/`v` and `kh`/`h` style variance between systems is what the edit-similarity threshold absorbs.
  */
 const CYRILLIC_TO_LATIN: Record<string, string> = {

package/lib/coincident-roles.ts

@@ -5,7 +5,7 @@
  *
  *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
  *
- *   Many places occupy multiple admin tiers under one name: German city-states (Berlin, Hamburg,
+ *   Some places occupy multiple admin tiers under one name: German city-states (Berlin, Hamburg,
  *   Bremen), Italian provinces whose names match their capital (Milano, Varese), Spanish
  *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals (Utrecht,
  *   Groningen), and Shanghai. When an address surfaces only the admin role because the parser

package/lib/currency-backfill.ts

@@ -24,8 +24,8 @@ const CURRENCY_BACKFILL_RADIUS_KM = 10
 const CURRENCY_BACKFILL_POP_FLOOR = 1000
 
 /**
- * Restore a deprecated locality only when no nearby live namesake exists and GeoNames
- * attests the same folded name above {@link CURRENCY_BACKFILL_POP_FLOOR}.
+ * Restore a deprecated locality only when no live namesake exists within CURRENCY_BACKFILL_RADIUS_KM
+ * and GeoNames attests the same folded name above {@link CURRENCY_BACKFILL_POP_FLOOR}.
  */
 export interface CurrencyBackfillResults {
 	judged: number

package/lib/extracts.ts

@@ -55,7 +55,7 @@ export function deriveSchemaName(path: PathBuilderLike): string {
 /**
  * Per-extract configuration.
  *
- * The simple form is just a path string.
+ * The simple form is a path string.
  * The schema name is derived from it.
  *
  * The object form lets callers override the derived schema name (useful when a filename

package/lib/fst/autocomplete.ts

@@ -109,9 +109,9 @@ class FSTReader implements AncestrieReaderLike<PlaceEntry> {
 	 * 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.
+	 * The algorithm asks {@link FSTReader.ancestorsOf} only for ids it received in the
+	 * same call 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[]>()
 

package/lib/fst/deserialize-web.ts

@@ -127,7 +127,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 			// v1 stored a raw population u32 here. v2-v4 stored the conflated `importance`
 			// float. v5 stored the referential score.
-			// The Node deserializer explains why a v1 value is genuinely referential.
+			// The Node deserializer explains why a v1 value is the referential score.
 			const referential = isV2
 				? view.getFloat32(pp + 12, true)
 				: Math.min(1, Math.log2(1 + view.getUint32(pp + 12, true) / 1000) / 14)

package/lib/fst/format.ts

@@ -59,7 +59,7 @@ export const NARROW_STATE_ENTRY_SIZE = 12
 
 /**
  * First format version carrying the trailing metadata block.
- * Older files simply have none.
+ * Older files have none.
  */
 export const VERSION_WITH_METADATA = 3
 

package/lib/geonames/postal.ts

@@ -122,8 +122,8 @@ function collapseDuplicatePoints(points: readonly PostcodePoint[]): PostcodePoin
  * and a multi-member group is one of its members.
  * The bound applies only while the members are distinct, so duplicate points are collapsed first.
  *
- * Separate counts for N rows at one coordinate would weight that value by how many settlements
- * inherited it. {@link MedoidSupport.distinctPoints} reports how many points the answer rested on.
+ * Separate counts for N rows at one coordinate would weight that value by the count of settlements that
+ * inherited it. {@link MedoidSupport.distinctPoints} reports the count of points the answer rested on.
  *
  * Distance is squared-Euclidean in degrees rather than haversine.
  * At the scale a postcode spans, both methods produce the same ranking.
@@ -194,7 +194,7 @@ export interface GeonamesPostalIngestResult {
 	/**
 	 * Per-country count of inserted codes the dump listed on several rows that all refer to one point.
 	 *
-	 * The coordinate rests on a single value no matter how many settlements sit under the code.
+	 * The coordinate rests on a single value regardless of the count of settlements under the code.
 	 * Reported because the point is still the best the source offers.
 	 *
 	 * A consumer weighing postal coverage needs to know how much of it is this.

package/lib/interpolation.ts

@@ -68,7 +68,7 @@ export interface InterpolationQuery {
 
 /**
  * Acceptance geometry for the `near` tie-break: the winning group must be within this
- * many kilometers and the runner-up at least {@link NEAR_DOMINANCE} times farther.
+ * number of kilometers and the runner-up at least {@link NEAR_DOMINANCE} times farther.
  */
 const NEAR_MAX_KM = 25
 
@@ -223,7 +223,7 @@ export class StreetInterpolator<
 	}
 
 	/**
-	 * Resolve one key variant's covering rows to an answer, or null when they cannot give one honestly.
+	 * Resolve one key variant's covering rows to an answer, or null when the rows do not support one.
 	 */
 	#answerFromRows(rows: SegmentRow[], n: number, query: InterpolationQuery): InterpolatedHit | null {
 		if (!rows.length) return null

package/lib/lookup.ts

@@ -569,7 +569,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 
 	/**
 	 * Coordinate-first locality resolution: union the postcode's containing
-	 * and nearby localities with the FTS name candidates and soft-score them,
+	 * and closest neighboring localities with the FTS name candidates and soft-score them,
 	 * returning null when the postcode is not in the table.
 	 */
 	async #findLocalityCoordFirst(

package/lib/nsul/lookup.ts

@@ -24,6 +24,7 @@
  *   unknown, per the meaning-of-zero rule.
  */
 
+import type { UkCountryCode } from "@mailwoman/codex/gb/country"
 import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup"
 
 import { compactPostcode, type NSULDatabase } from "#nsul/schema"
@@ -64,6 +65,22 @@ export interface NSULAssignedPoint {
  */
 export type NSULLookupOpts = SQLiteLookupOptions<NSULDatabase>
 
+/**
+ * The UPRNs of one unit postcode that lie in one constituent country.
+ */
+export interface NSULPostcodeCountry {
+	/**
+	 * The ISO 3166-2:GB constituent country (`ENG`, `SCT`, `WLS`).
+	 */
+	country: UkCountryCode
+	uprns: number
+}
+
+interface CountryRow {
+	ctry: UkCountryCode
+	uprns: number
+}
+
 interface PostcodeRow {
 	pcds: string
 	pcds_compact: string
@@ -84,6 +101,7 @@ interface PointRow {
 export class NSULLookup extends SQLiteLookup<NSULDatabase> {
 	readonly #postcodeProbe: (uprn: number) => PostcodeRow | null
 	readonly #pointsProbe: (pcdsCompact: string) => PointRow[]
+	readonly #countriesProbe: (pcdsCompact: string) => CountryRow[]
 
 	constructor(opts: NSULLookupOpts) {
 		super(opts)
@@ -97,6 +115,21 @@ export class NSULLookup extends SQLiteLookup<NSULDatabase> {
 			this.database,
 			"SELECT uprn, lat, lon, h3_cell FROM uprn_postcode WHERE pcds_compact = ? ORDER BY uprn"
 		)
+
+		this.#countriesProbe = prepareAll<[string], CountryRow, NSULDatabase>(
+			this.database,
+			"SELECT ctry, count(*) AS uprns FROM uprn_postcode WHERE pcds_compact = ? GROUP BY ctry ORDER BY uprns DESC, ctry"
+		)
+	}
+
+	/**
+	 * The constituent countries one unit postcode's UPRNs lie in, with the UPRN count in each, most first.
+	 *
+	 * A postcode on the England–Wales or England–Scotland border can return two entries.
+	 * An empty array means the register assigns no UPRN to the postcode.
+	 */
+	countriesForPostcode(postcode: string): NSULPostcodeCountry[] {
+		return this.#countriesProbe(compactPostcode(postcode)).map((row) => ({ country: row.ctry, uprns: row.uprns }))
 	}
 
 	/**

package/lib/nsul/schema.ts

@@ -38,6 +38,11 @@ export interface UPRNPostcodeTable {
 	 * `spr.name` contains and `uprnsForPostcode` probes.
 	 */
 	pcds_compact: string
+	/**
+	 * The ISO 3166-2:GB constituent country the UPRN lies in (`ENG`, `SCT`, `WLS`),
+	 * read from NSUL's `CTRY25CD` column.
+	 */
+	ctry: string
 	/**
 	 * WGS84 latitude, copied from `uprn.db` for the same UPRN.
 	 */
@@ -78,6 +83,7 @@ export async function createUPRNPostcodeTable(db: Kysely<NSULDatabase>): Promise
 		.addColumn("uprn", "integer", (c) => c.primaryKey())
 		.addColumn("pcds", "text", (c) => c.notNull())
 		.addColumn("pcds_compact", "text", (c) => c.notNull())
+		.addColumn("ctry", "text", (c) => c.notNull())
 		.addColumn("lat", "real", (c) => c.notNull())
 		.addColumn("lon", "real", (c) => c.notNull())
 		.addColumn("h3_cell", "integer", (c) => c.notNull())

package/lib/paths.ts

@@ -85,7 +85,7 @@ export const nsulDatabasePath: PathBuilder = databaseRootPath(dataRootPath())("n
  * It defaults to `$MAILWOMAN_DATA_ROOT`, and callers may pass `--data-root`.
  * Returns a fresh array each call.
  *
- * Callers usually filter with `existsSync`, so missing files are skipped.
+ * A caller can filter with `existsSync`, so missing files are skipped.
  *
  * This runtime list is intentionally smaller than `DEFAULT_POSTCODE_DATABASES`
  * (`mailwoman/gazetteer-pipeline/index.ts`), because these databases are attached live at boot.

package/lib/place-importance-schema.ts

@@ -21,7 +21,7 @@ export interface PlaceImportanceTable {
 	 * It is never NULL.
 	 * A place without a population row scores `0`.
 	 *
-	 * That score represents no population evidence, so it earns no boost or penalty.
+	 * That score represents no population evidence, so it receives no boost or penalty.
 	 */
 	referential: number
 

package/lib/poi/lookup.ts

@@ -81,7 +81,7 @@ export interface POISearchQuery {
 	 */
 	center?: { latitude: number; longitude: number }
 	/**
-	 * Ring budget: how many res-9 k-rings to expand before giving up.
+	 * Ring budget: the count of res-9 k-rings to expand before giving up.
 	 *
 	 * Counts ring 0, so k reaches `maxRings - 1`.
 	 *
@@ -251,7 +251,7 @@ export class POILookup<DB extends POIDatabase = POIDatabase> extends SQLiteLooku
 		// `ring` starts at 0 (the origin cell itself), so this loop's k reaches `maxRings - 1`.
 		for (let ring = 0; ring < maxRings; ring++) {
 			// gridDisk(origin, ring) returns the whole disk out to `ring`, so diffing against
-			// the already-probed set derives just this ring's new cells.
+			// the already-probed set derives only this ring's new cells.
 			const diskCells = gridDisk(origin, ring) as string[]
 			const newCells = diskCells.filter((cell) => !seenCells.has(cell))
 

package/lib/polygon-schema.ts

@@ -14,7 +14,7 @@
 import type { Kysely } from "kysely"
 
 /**
- * One admin polygon, keyed by WOF id.
+ * Each row holds one admin polygon, keyed by WOF id.
  */
 export interface PolygonsTable {
 	id: number

package/lib/postal/city/alias/lookup.ts

@@ -7,7 +7,7 @@
  *   `postal_city → geo_locality` aliases per postcode (`build-postal-city-alias.ts`). Consumed by
  *   {@link WOFSQLitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
  *   ("Antioch", postcode 37013) becomes a name-match alias for the geographic locality the postcode
- *   actually sits in ("Nashville"), so the right place tiers to the top instead of a place with the same name
+ *   sits in ("Nashville"), so the right place tiers to the top instead of a place with the same name
  *   town in another state. Opt-in — the lookup is only constructed when a path is supplied.
  *   absent it the resolver is byte-identical.
  *

package/lib/postal/city/alias/schema.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   Typed schema for the postal-city alias table (`postal-city-alias-<cc>.db`, built by
- *   `scripts/build-postal-city-alias.ts`) — the single source of truth for the columns shared by
+ *   `scripts/build-postal-city-alias.ts`) — the one declaration of the columns shared by
  *   the builder and the reader ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
  *   interface is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
  *   the builder is a compile error in the reader.
@@ -34,7 +34,7 @@ export interface PostalCityAliasTable {
 	 */
 	postal_city: string
 	/**
-	 * The geographic locality name the postcode actually sits in (≈ the gazetteer's canonical name).
+	 * The geographic locality name the postcode sits in (≈ the gazetteer's canonical name).
 	 */
 	geo_locality: string
 	/**

package/lib/proximity-rerank.ts

@@ -88,7 +88,7 @@ export function combinedProminence(candidate: ProximityRerankable, bias: readonl
 	const popTerm = POP_BOOST * Math.min(1, Math.max(0, popBase) / POP_SCALE_LOG10)
 	let proxTerm = 0
 
-	// A candidate at the null island has no coordinate, so it warrants no nearness term.
+	// A candidate at 0,0 (Null Island) has no coordinate, so it receives no nearness term.
 	// A 0,0 pair interpreted as a real coordinate would receive an enormous score.
 	if (!(candidate.lat === 0 && candidate.lon === 0)) {
 		for (const b of bias) {

package/lib/search-fetch.ts

@@ -30,7 +30,7 @@ const SHORT_QUERY_MAX_LENGTH = 3
 /**
  * Over-fetch floor for short (≤3-character) queries.
  *
- * These queries are usually region abbreviations such as "NY" or "VT".
+ * The target case is a region abbreviation such as "NY" or "VT".
  *
  * An exact-abbrev holder's BM25 is poor (long multilingual alt-name document),
  * so the normal `limit * 4` window can drop it before `exactMatchTiering` promotes
@@ -41,7 +41,7 @@ const SHORT_QUERY_MAX_LENGTH = 3
 const SHORT_QUERY_OVERFETCH = 200
 
 /**
- * How many rows the population-ordered companion fetch adds to the candidate pool.
+ * The count of rows the population-ordered companion fetch adds to the candidate pool.
  *
  * Small on purpose.
  * Its only job is to guarantee the famous holders of a name enter the pool at all.
@@ -184,10 +184,10 @@ export function fetchSearchRows<DB>(options: {
 	// and builds no join at all.
 	const { select: encyclopedicSelect, join: encyclopedicJoin } = encyclopedicClauses.get(sch)!
 
-	// Push the population boost into the order BY when the index is available, so famous places
-	// (whose long alt-name lists hurt BM25) actually make it into the over-fetch window.
+	// Push the population boost into the order BY when the index is available, so famous
+	// places (whose long alt-name lists hurt BM25) make it into the over-fetch window.
 	// The TS post-scoring will still compute the same boost for the final score.
-	// This just ensures the candidate set is right.
+	// This ordering only decides which rows enter the candidate set.
 	//
 	// Formula: rank_adjusted = bm25 - populationBoost * min(1.0, log10(1 + pop) / scaleLog10)
 	// Lower rank_adjusted = better (matches SQLite's bm25 convention of "more negative = better").