@mailwoman/resolver-wof-sqlite 9.2.0 → 9.4.0

package/README.md

@@ -17,7 +17,7 @@ Requires Node 22+ for built-in `node:sqlite`.
 ```ts
 import { WOFSQLitePlaceLookup } from "@mailwoman/resolver-wof-sqlite"
 
-const lookup = new WOFSQLitePlaceLookup({
+using lookup = new WOFSQLitePlaceLookup({
 	databasePath: "/path/to/whosonfirst-data-admin-us-latest.db",
 	buildFTS: true, // build the FTS5 index on first open (one-time cost)
 })
@@ -31,18 +31,16 @@ const candidates = await lookup.findPlace({
 for (const c of candidates) {
 	console.log(c.id, c.name, c.country, c.lat, c.lon, "score:", c.score)
 }
-
-lookup.close()
 ```
 
-## A shard that cannot answer says so on construction
+## A database that cannot answer says so on construction
 
-Shards 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 quietly, and both now throw when you build the lookup:
+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 shard carries `spr` but no `place_search`. It routes, then dies mid-`SELECT`.
+- The database carries `spr` but no `place_search`. It routes, then dies mid-`SELECT`.
 
-The predicate is the **table, not the filename**: a shard carrying `spr` is claiming to be a place shard, and every lookup path here reaches the FTS index. A relation-table shard like `postcode-locality-<cc>.db` carries no `spr`, never makes that claim, and is exempt — which is what keeps the documented default shard list working.
+The predicate is the **table, not 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.
 
 ```
 WOFSQLitePlaceLookup: …/postcode-ca-overture.db carries "spr" but no "place_search" table, so it
@@ -54,21 +52,21 @@ locality, region, county, country, venue), so it would never have been queried e
 
 The second sentence appears only when the name routes nowhere. It is the half that turns zero hits into a diagnosis.
 
-## Multi-shard (admin + postcode in one connection)
+## Multiple databases (admin + postcode in one connection)
 
-Pass an array of paths to open multiple WOF shards on a single connection — each is opened as a
+Pass an array of paths to open multiple WOF databases on a single connection — each is opened as a
 separate SQLite schema via `ATTACH DATABASE`. Schema names auto-derive from filenames
 (`whosonfirst-data-admin-us-latest.db` → `admin_us`, `whosonfirst-data-postalcode-us-latest.db` →
 `postalcode_us`). Queries route by `placetype` — a `postalcode` query goes to the
-`postalcode_us` shard automatically, everything else hits main.
+`postalcode_us` database automatically, everything else hits main.
 
 ```ts
 const lookup = new WOFSQLitePlaceLookup({
 	databasePath: ["/data/wof/whosonfirst-data-admin-us-latest.db", "/data/wof/whosonfirst-data-postalcode-us-latest.db"],
 })
 
-await lookup.findPlace({ text: "Springfield", placetype: "locality" }) // → admin shard
-await lookup.findPlace({ text: "62701", placetype: "postalcode" }) // → postcode shard
+await lookup.findPlace({ text: "Springfield", placetype: "locality" }) // → admin extract
+await lookup.findPlace({ text: "62701", placetype: "postalcode" }) // → postcode extract
 ```
 
 Override schema names or routing explicitly when needed:
@@ -79,13 +77,13 @@ new WOFSQLitePlaceLookup({
 })
 ```
 
-Cross-shard `UNION` queries are not supported in one `findPlace` call — BM25 scores aren't
+Cross-database `UNION` queries are not supported in one `findPlace` call — BM25 scores aren't
 comparable across separately-indexed corpora. Issue two `findPlace` calls and merge in your
 caller if you need that.
 
 ## Getting the WOF SQLite distribution
 
-The Geocode Earth team mirrors WOF SQLite distributions at <https://data.geocode.earth/wof/dist/sqlite/>. The two relevant shards for v1:
+The Geocode Earth team mirrors WOF SQLite distributions at <https://data.geocode.earth/wof/dist/sqlite/>. The two relevant distributions for v1:
 
 | Distribution                                   | Size (bz2) | Use                                                               |
 | ---------------------------------------------- | ---------- | ----------------------------------------------------------------- |
@@ -102,7 +100,7 @@ bunzip2 whosonfirst-data-admin-us-latest.db.bz2
 
 Upstream WOF SQLite distributions ship a `places` table but **not** an FTS5 index. The resolver needs FTS5 to do fast prefix + token-bag matching. Two options:
 
-1. **`buildFTS: true` on construction** — builds the index lazily on first open. Cost is one-time but expensive (~minutes on the full US admin shard). Use for prototyping.
+1. **`buildFTS: true` on construction** — builds the index lazily on first open. Cost is one-time but expensive (~minutes on the full US admin database). Use for prototyping.
 2. **Pre-build the index with `mailwoman gazetteer build fts`** — ship the DB with the index included so first-open is fast. Recommended for production.
 
 ### `mailwoman gazetteer build fts`
@@ -170,12 +168,11 @@ You can also build the index programmatically via the package's `./fts` subpath:
 import { DatabaseSync } from "node:sqlite"
 import { buildPlaceSearchFts } from "@mailwoman/resolver-wof-sqlite/fts"
 
-const db = new DatabaseSync("/path/to/wof.db")
+using db = new DatabaseSync("/path/to/wof.db")
 const { created, indexedRows, durationMs } = buildPlaceSearchFts(db, {
 	drop: false,
 	onProgress: (phase, detail) => console.log(phase, detail),
 })
-db.close()
 ```
 
 ## Ranking
@@ -261,11 +258,11 @@ This package itself is AGPL-3.0; the WOF data it indexes is CC-BY 4.0. The two l
 
 `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 `/mnt/playpen/mailwoman-data/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 shard).
+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 / many-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 fine (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; 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/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#address/point"
+export * from "#address/point-interpolation"
+export * from "#address/point-schema"

package/{address-point-interpolation.ts → lib/address/point-interpolation.ts}

@@ -6,13 +6,13 @@
  *   Address-point interpolation — "Method 2" of the resolution ladder (#483, Phase 1 of
  *   `docs/articles/plan/2026-06-11-resolution-ladder.md`): when the exact address-point tier (#476)
  *   misses a house number, bracket the number with REAL neighbor points on the same street from the
- *   same #476 shard and interpolate linearly in house-number space between them. Real occupancy
- *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's gate
+ *   same #476 extract and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's check
  *   miss; TIGER range interpolation (`StreetInterpolator`) demotes to the fallback for streets too
  *   sparse to bracket.
  *
  *   Matching key is `street_key` — THE shared normalizer plus the route fold
- *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-shard.ts`) and
+ *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-extract.ts`) and
  *   query time, by construction. Scope is postcode-first like the segment tier; a query without a
  *   postcode goes straight to the fallback (which carries its own statewide-ambiguity abstention).
  *
@@ -20,7 +20,7 @@
  *
  *   - Neighbor candidates NEVER include the queried number itself (any unit/duplicate row of it) — in
  *       production the exact tier would already have answered an on-file number, and in the eval
- *       this is what makes grading against the same shard non-circular by construction.
+ *       this is what makes grading against the same extract non-circular by construction.
  *   - Both-sided bracket (`bracket: "both"`): linear interpolation between the nearest known number
  *       below and above; `uncertaintyM` = half the distance between them.
  *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers on
@@ -33,15 +33,14 @@
  *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
-import type { InterpolationLookup } from "@mailwoman/resolver"
+import type { InterpolationLookup } from "@mailwoman/core/resolver"
 import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "./interpolation.ts"
-import { hasTable, prepareAll, type PreparedAll } from "./sqlite-utils.ts"
-import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } from "./street-normalize.ts"
-
+import type { AddressPointDatabase } from "#address/point-schema"
+import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "#interpolation"
+import { hasTable, prepareAll, type PreparedAll } from "#sqlite-utils"
+import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } from "#street/normalize"
 /**
  * Extrapolation cap for a single-sided bracket: at most one pair-span beyond the nearest known point (`t = 2`). Past
  * it, the two-point line carries no evidence about the query number.
@@ -67,26 +66,30 @@ interface NumberAnchor {
 	release: string
 }
 
-export class AddressPointInterpolator implements InterpolationLookup {
-	readonly #db: DatabaseSync
-	readonly #ownsDB: boolean
+export class AddressPointInterpolator<
+	DB extends AddressPointDatabase = AddressPointDatabase,
+> implements InterpolationLookup {
+	readonly #db: DatabaseClient<DB>
+	/**
+	 * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
+	 * ownership is membership rather than a flag a later branch has to check.
+	 */
+	readonly #resources = new DisposableStack()
 	readonly #fallback: StreetInterpolator | undefined
 	readonly #byPostcode: PreparedAll<[postcode: string, street: RouteKey, number: number], PointRow> | undefined
 
-	constructor(opts: { dbPath?: string; database?: DatabaseSync; fallback?: StreetInterpolator }) {
+	constructor(opts: { dbPath?: string; database?: DatabaseClient<DB>; fallback?: StreetInterpolator }) {
 		if (opts.database) {
 			this.#db = opts.database
-			this.#ownsDB = false
 		} else if (opts.dbPath) {
-			this.#db = new DatabaseSync(opts.dbPath, { readOnly: true })
-			this.#ownsDB = true
+			this.#db = this.#resources.use(new DatabaseClient<DB>(opts.dbPath, { readOnly: true }))
 		} else {
 			throw new Error("AddressPointInterpolator: one of dbPath or database is required")
 		}
 
 		this.#fallback = opts.fallback
 
-		// Degrade gracefully on an empty/tableless shard (#568): with no `address_point` table this tier
+		// Degrade gracefully on an empty/tableless extract (#568): with no `address_point` table this tier
 		// is skipped, deferring to the segment fallback rather than crashing at construction.
 		if (hasTable(this.#db, "address_point")) {
 			// Strictly-numeric neighbor numbers on the route-folded street key within the ZIP. The
@@ -108,7 +111,7 @@ export class AddressPointInterpolator implements InterpolationLookup {
 		if (!/^\d+$/.test(numberRaw)) return null
 		const n = Number(numberRaw)
 
-		// No own table (empty shard) or no postcode → defer to the segment fallback rather than query.
+		// No own table (empty extract) or no postcode → defer to the segment fallback rather than query.
 		if (!this.#byPostcode || !query.postcode) return this.#fallback?.find(query) ?? null
 
 		// Key-variant ladder (see `streetKeyVariants`) — same probe order as the exact-point reader.
@@ -127,10 +130,8 @@ export class AddressPointInterpolator implements InterpolationLookup {
 		return hit ?? this.#fallback?.find(query) ?? null
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
 	}
 }
 

package/{address-point-schema.ts → lib/address/point-schema.ts}

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the SITUS / rooftop ADDRESS-POINT shards (`address-points-<cc>-<slug>.db`, built
- *   by `scripts/build-address-point-shard.ts` — the #476/#567 national rooftop tier behind the
+ *   Typed schema for the SITUS / rooftop ADDRESS-POINT extracts (`address-points-<cc>-<slug>.db`, built
+ *   by `scripts/build-address-point-extract.ts` — the #476/#567 national rooftop tier behind the
  *   demo's "type any US address, get the building"). Single source of truth for the columns shared
  *   by the BUILDER and the READER ({@link AddressPointSqliteLookup}), so a column rename in one is a
  *   compile error in the other.
@@ -18,7 +18,7 @@
 
 import type { Kysely } from "kysely"
 
-import type { NameKey, RouteKey, StreetKey } from "./street-normalize.ts"
+import type { NameKey, RouteKey, StreetKey } from "#street/normalize"
 
 /**
  * One rooftop address point. `(street_norm, number)` within a `postcode` (preferred) or `locality_norm` scope is the
@@ -59,6 +59,16 @@ export interface AddressPointTable {
 	 * The pinned data release the point was ingested from.
 	 */
 	release: string
+	/**
+	 * The source register's stable administrative key for the point's commune or municipality — BAN's `code_insee`. A
+	 * display name (`locality_norm`) is not a key; the coverage basis is computed per THIS.
+	 */
+	admin_code: string | null
+	/**
+	 * The register's own certification flag for the point (BAN `certification_commune`: 1 certified by the commune, 0
+	 * not), or null for a source that states none. A basis is never inferred from a share of these.
+	 */
+	certified: number | null
 }
 
 /**
@@ -71,7 +81,7 @@ export interface AddressPointDatabase {
 /**
  * The slice of a Kysely handle the `address_point` DDL touches — the parameter type its builders take.
  *
- * Kysely is invariant in its schema parameter (the incompatibility is in `transaction()`), so a shard that EXTENDS
+ * Kysely is invariant in its schema parameter (the incompatibility is in `transaction()`), so a extract that EXTENDS
  * `AddressPointTable` — OSM adds `h3_cell` — cannot pass its own handle to a `Kysely<AddressPointDatabase>` parameter.
  * Naming only `schema` lets it, and the DDL below needs nothing else.
  */
@@ -93,6 +103,8 @@ export const ADDRESS_POINT_COLUMNS = [
 	"lon",
 	"source",
 	"release",
+	"admin_code",
+	"certified",
 ] as const
 
 /**
@@ -113,6 +125,8 @@ export async function createAddressPointTable(db: AddressPointSchemaHandle): Pro
 		.addColumn("lon", "real", (c) => c.notNull())
 		.addColumn("source", "text", (c) => c.notNull())
 		.addColumn("release", "text", (c) => c.notNull())
+		.addColumn("admin_code", "text")
+		.addColumn("certified", "integer")
 		.execute()
 }
 

package/lib/address/point.ts

@@ -0,0 +1,328 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
+ *   postcode (preferred), locality, or — for extracts whose points carry no scope tag (OSM, #247) —
+ *   the resolved locality's BBOX. Query-side normalization is THE shared normalizer
+ *   (`street-normalize.ts`), selected per the extract's `streetLocale` so build-side and probe-side
+ *   stay identical by construction (US delegates to the USPS pipeline; FR/DE/NL use the locale rules).
+ *
+ *   Matching is exact-after-normalization only — no fuzzy street matching in this tier (measure how
+ *   far exact gets first; fuzz is a later, separate decision). Scope order is most-selective first:
+ *   postcode, then locality, then the bbox fall-through (only when a bbox is supplied AND the prior
+ *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
+ */
+
+import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import type { AddressPointDatabase, AddressPointTable } from "#address/point-schema"
+import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
+import {
+	normalizeHouseNumberForKey,
+	normalizeLocalityForKey,
+	normalizeLocalityForKeyLocale,
+	type NameKey,
+	type StreetKey,
+	streetKeyVariants,
+	streetLocaleForSurface,
+	stripArrondissement,
+	type StreetLocale,
+} from "#street/normalize"
+
+/**
+ * The columns this lookup projects — a typed slice of the SHARED {@link AddressPointTable}, so a column rename in
+ * `build-address-point-extract.ts` (the writer) is a compile error here (the reader).
+ */
+type AddressPointRow = Pick<AddressPointTable, "lat" | "lon" | "source" | "release" | "locality_norm" | "postcode">
+
+/**
+ * The 4 columns the reader SELECTs, in the schema's order — referenced by the prepared SELECTs so the projected
+ * `AddressPointRow` stays in lockstep with the shared schema.
+ */
+const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode"
+
+export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressPointDatabase>
+	implements AddressPointLookup, Disposable
+{
+	readonly #db: DatabaseClient<DB>
+	readonly #locale: StreetLocale
+	readonly #localityKeys: "full" | "abbreviated"
+	readonly #byPostcode: PreparedGet<[postcode: string, street: StreetKey, number: string], AddressPointRow> | undefined
+	readonly #byPostcodeLocality:
+		| PreparedGet<[postcode: string, locality: NameKey, street: StreetKey, number: string], AddressPointRow>
+		| undefined
+	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey, number: string], AddressPointRow> | undefined
+	/**
+	 * The scope key matched by its TAIL — a `zh` query that names the 鄉鎮市區 without its 縣市. Narrowed by the (street,
+	 * number) index first, so the LIKE walks the handful of rows that share the pair.
+	 */
+	readonly #byLocalityTail:
+		| PreparedGet<[street: StreetKey, number: string, tailPattern: string], AddressPointRow>
+		| undefined
+	readonly #byBbox:
+		| PreparedGet<
+				[street: StreetKey, number: string, minLat: number, maxLat: number, minLon: number, maxLon: number],
+				AddressPointRow
+		  >
+		| undefined
+
+	/**
+	 * @param dbPath Extract path.
+	 * @param opts.streetLocale The street-normalization locale this extract was BUILT with — must match, or every key
+	 *   misses. Defaults to `"us"` (the situs tier), so existing callers are unchanged.
+	 * @param opts.localityKeys Whether the extract's `locality_norm` is a FULL place name a query can be held to. The BAN
+	 *   and OSM extracts write the commune or `addr:city` in full; the US situs extract writes the NAD city field, which
+	 *   several counties abbreviate (`addi` for Addison on 5,174 Texas rows, 327,264 Texas rows at four characters or
+	 *   fewer) or give as the parent town (`easton` for North Easton). A key like that can steer WHICH row answers but
+	 *   cannot refuse one, so it never contradicts. Defaults from the street locale: `"us"` is abbreviated, the rest
+	 *   full.
+	 */
+	constructor(dbPath: string, opts: { streetLocale?: StreetLocale; localityKeys?: "full" | "abbreviated" } = {}) {
+		this.#db = new DatabaseClient<DB>(dbPath, { readOnly: true })
+		this.#locale = opts.streetLocale ?? "us"
+		this.#localityKeys = opts.localityKeys ?? (this.#locale === "us" ? "abbreviated" : "full")
+
+		// Degrade gracefully on an empty/tableless extract (interrupted build, stray 0-byte file): with no
+		// `address_point` table this lookup is a no-op miss, not a crash that loses the whole state (#568).
+		if (hasTable(this.#db, "address_point")) {
+			this.#byPostcode = prepareGet(
+				this.#db,
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND street_norm = ? AND number = ? LIMIT 1`
+			)
+
+			this.#byPostcodeLocality = prepareGet(
+				this.#db,
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
+			)
+
+			this.#byLocality = prepareGet(
+				this.#db,
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
+			)
+
+			this.#byBbox = prepareGet(
+				this.#db,
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND lat BETWEEN ? AND ? AND lon BETWEEN ? AND ? LIMIT 1`
+			)
+
+			this.#byLocalityTail = prepareGet(
+				this.#db,
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND locality_norm LIKE ? LIMIT 1`
+			)
+		}
+	}
+
+	find(query: {
+		street: string
+		number: string
+		postcode?: string
+		locality?: string
+		region?: string
+		subregion?: string
+		bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+	}): AddressPointHit | null {
+		if (!this.#byPostcode || !this.#byLocality || !this.#byBbox) return null
+		const number = normalizeHouseNumberForKey(query.number, this.#locale)
+
+		if (!number) return null
+
+		// A `zh` extract scopes a point by 縣市 + 鄉鎮市區, the pair the parse tags `region` + `subregion`; the Taiwanese
+		// register carries no postcode and the parse no `locality`. The pair becomes the locality key here, on the
+		// reader that was built with the same fold, and a Latin extract never sees the two fields. A line that names
+		// only the 鄉鎮市區 (`中和區中興街281號`, 14.7% of the TW board) matches the stored pair by its tail instead.
+		const scoped =
+			this.#locale === "zh" && !query.locality && query.subregion
+				? query.region
+					? { ...query, locality: `${query.region}${query.subregion}` }
+					: { ...query, localityTail: normalizeLocalityForKeyLocale(query.subregion, "zh") }
+				: query
+
+		// Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
+		// collapse and the saint↔st register swap — each variant runs the FULL number ladder below, and
+		// the first variant to answer wins, so an attested literal key is never second-guessed.
+		let row: AddressPointRow | undefined
+
+		for (const streetNorm of streetKeyVariants(query.street, streetLocaleForSurface(query.street, this.#locale))) {
+			row = this.#findForKey(streetNorm, number, scoped)
+
+			if (row) break
+		}
+
+		if (!row) return null
+
+		return {
+			lat: row.lat,
+			lon: row.lon,
+			source: row.source,
+			release: row.release,
+			...(row.locality_norm ? { localityNorm: row.locality_norm } : {}),
+			...(row.postcode ? { postcode: row.postcode } : {}),
+		}
+	}
+
+	/**
+	 * The full number ladder for ONE normalized street key: exact, then the range low-end, then letter-suffix spacing
+	 * with the base-number fall — see each rung's note in place.
+	 */
+	#findForKey(
+		streetNorm: StreetKey,
+		number: string,
+		query: {
+			street: string
+			number: string
+			postcode?: string
+			locality?: string
+			localityTail?: NameKey
+			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+		}
+	) {
+		let row = this.#probe(streetNorm, number, query)
+
+		// Range-surface fallback: every register this reader serves stores ONE number per point
+		// (G-NAF `NUMBER_FIRST`, BAN, OA, OSM `addr:housenumber`), but the attested surface is often
+		// a range — "385-387 Esplanade" keys `385`. Null-only: an exact range key that matched above
+		// (some OSM points DO carry "385-387" verbatim) is never second-guessed.
+		if (!row) {
+			const low = /^(\d+[a-z]?)-\d+[a-z]?$/.exec(number)?.[1]
+
+			if (low) {
+				row = this.#probe(streetNorm, low, query)
+			}
+		}
+
+		// Letter-suffix spacing fallback: the registers disagree on the joint — BAN stores "3 a"
+		// (space-separated), G-NAF and most OA sources store "3a" — and the parsed surface can arrive
+		// either way. On a miss, retry the OTHER spacing; on a double miss, the BASE number (the
+		// register attests no 3A but does attest 3 — the adjacent-parcel approximation, priced the
+		// same as the range fallback's low end). Null-only throughout, and only for the
+		// digits+single-letter shape (never touches "12 1/2" or unit-bearing forms).
+		if (!row) {
+			const joined = /^(\d+)\s+([a-z])$/.exec(number)
+			const spaced = /^(\d+)([a-z])$/.exec(number)
+
+			if (joined) {
+				row = this.#probe(streetNorm, `${joined[1]}${joined[2]}`, query) ?? this.#probe(streetNorm, joined[1]!, query)
+			} else if (spaced) {
+				row = this.#probe(streetNorm, `${spaced[1]} ${spaced[2]}`, query) ?? this.#probe(streetNorm, spaced[1]!, query)
+			}
+		}
+
+		// Sub-number fallback for the Taiwanese register: `14之12` is building 12 off number 14, `30附40` an attached
+		// number, stored as number `14` / `30` with the rest in `unit`. A query that kept the pair on the number span
+		// falls to the base number — the same adjacent-parcel approximation the letter-suffix rung makes, priced the
+		// same: on the 2,000-row served read the rows answered this way sit a median 256 m and at most 1.0 km from the
+		// building.
+		if (!row && this.#locale === "zh") {
+			const base = /^(\d+)(?:[之附]\d+)+$/u.exec(number)?.[1]
+
+			if (base) {
+				row = this.#probe(streetNorm, base, query)
+			}
+		}
+
+		return row
+	}
+
+	/**
+	 * The scope ladder for one (street, number) key: postcode, then locality, then the bbox fall-through — each rung only
+	 * when the prior missed.
+	 */
+	#probe(
+		streetNorm: StreetKey,
+		number: string,
+		query: {
+			postcode?: string
+			locality?: string
+			localityTail?: NameKey
+			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+		}
+	): AddressPointRow | undefined {
+		let row: AddressPointRow | undefined
+
+		if (query.postcode) {
+			const postcode = query.postcode.trim()
+			const localityKey = query.locality ? this.#localityKey(query.locality) : undefined
+
+			// A postcode can span several places — DE 04509 covers Schönwölkau and Werlitzsch, both with a Teichstraße 3 —
+			// so when the query names a locality the row whose own locality agrees is asked for FIRST. Only when no such
+			// row exists does the postcode-only row answer, and then only if its locality does not name a different place
+			// (see `#scopeContradicts` for what "different" tolerates): a query naming a third village under the postcode
+			// falls through to the locality rung rather than answering the wrong rooftop.
+			const agreeing = localityKey ? this.#byPostcodeLocality!(postcode, localityKey, streetNorm, number) : undefined
+			const candidate = agreeing ?? this.#byPostcode!(postcode, streetNorm, number)
+
+			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
+		}
+
+		if (!row && query.locality) {
+			// FR extracts key arrondissement communes at the base city (both-sides fold, see the BAN
+			// builder + stripArrondissement) — fold the probe too so "Paris 13e Arrondissement" and
+			// "Paris" both hit. No-op for "us" extracts and every non-arrondissement commune.
+			row = this.#byLocality!(this.#localityKey(query.locality), streetNorm, number)
+		}
+
+		if (!row && query.localityTail && this.#byLocalityTail) {
+			// A Han key carries no `%` or `_`, so the tail is a literal suffix pattern.
+			row = this.#byLocalityTail(streetNorm, number, `%${query.localityTail}`)
+		}
+
+		// Bbox fall-through (#247): the point carries no postcode/locality of its own, but its coordinate falls
+		// inside the resolved locality's box. Only reached when the scoped probes missed AND a bbox was supplied.
+		if (!row && query.bbox) {
+			const b = query.bbox
+			const candidate = this.#byBbox!(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon)
+
+			// A register row that carries its own scope and was NOT found by the scoped rungs is a different address that
+			// happens to share the street and number inside the box: `10 rue de la République, 75008 Paris` reached
+			// Servon's `10 rue de la République` (postcode 77170) 26 km away this way, at rooftop tier and 1 m uncertainty.
+			// The rung exists for points with no scope of their own; a point whose scope disagrees with the query is a miss.
+			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
+		}
+
+		return row
+	}
+
+	/**
+	 * The query's locality folded the way the extract's builder folded its `locality_norm`. FR extracts key
+	 * arrondissement communes at the base city (both-sides fold, see the BAN builder + stripArrondissement), so "Paris
+	 * 13e Arrondissement" and "Paris" both hit; a no-op for every other locale.
+	 */
+	#localityKey(locality: string): NameKey {
+		if (this.#locale === "fr") return stripArrondissement(normalizeLocalityForKey(locality))
+
+		return normalizeLocalityForKeyLocale(locality, this.#locale)
+	}
+
+	/**
+	 * Whether a row's OWN postcode or locality names a different place than the query did. Absent scope on the row is not
+	 * a contradiction — it is the case the bbox rung was built for — and a rung that matched ON a field cannot contradict
+	 * it, so at the postcode rung only the locality can disagree and at the bbox rung either can.
+	 *
+	 * The locality is consulted only on an extract whose keys are full names (the constructor's `localityKeys`). Under
+	 * exact comparison against the US extract's abbreviated keys, the postcode rung refused `4900 Airport Pkwy, Addison
+	 * TX 75001`'s own rooftop row (`addi`) and `678 Depot St, North Easton, MA 02356`'s (`easton`), and both `pass` board
+	 * rows fell to interpolation 144–198 m away — invisible to a 1 km grade (#2155). `servon` against `paris` and
+	 * `werlitzsch` against `krensitz`, on the BAN and OSM extracts, are different places and still refuse.
+	 */
+	#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)
+		}
+
+		return false
+	}
+
+	[Symbol.dispose](): void {
+		this.#db[Symbol.dispose]()
+	}
+}