@mailwoman/resolver-wof-sqlite 10.0.0 → 10.1.0

package/README.md

@@ -40,7 +40,7 @@ Databases are `ATTACH`ed by a schema name **derived from the filename**, and que
 - 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 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.
+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.
 
 ```
 WOFSQLitePlaceLookup: …/postcode-ca-overture.db carries "spr" but no "place_search" table, so it
@@ -81,7 +81,7 @@ Cross-database `UNION` queries are not supported in one `findPlace` call — BM2
 comparable across separately-indexed corpora. Issue two `findPlace` calls and merge in your
 caller if you need that.
 
-## Getting the WOF SQLite distribution
+## Get the WOF SQLite distribution
 
 The Geocode Earth team mirrors WOF SQLite distributions at <https://data.geocode.earth/wof/dist/sqlite/>. The two relevant distributions for v1:
 
@@ -137,7 +137,7 @@ Builds a trimmed WOF SQLite distribution sized for browser-side deployments (Pat
 # Defaults: --top 1000 localities, --countries US, drops geojson after building aux tables
 # The slim wof-hot.db distribution is RETIRED (2026-06-20): the demo byte-range-resolves
 # against the global candidate table. `buildSlimWOFDatabase` remains importable from
-# `@mailwoman/resolver-wof-sqlite/build-slim` for test fixtures. Historical invocation:
+# `@mailwoman/resolver-wof-sqlite/build/slim` for test fixtures. Historical invocation:
 # mailwoman-wof-build-slim \
   --in /path/to/whosonfirst-data-admin-us-latest.db \
   --in /path/to/whosonfirst-data-postalcode-us-latest.db \
@@ -175,7 +175,7 @@ const { created, indexedRows, durationMs } = buildPlaceSearchFts(db, {
 })
 ```
 
-## Ranking
+## Rank places
 
 The resolver scores candidates by:
 
@@ -237,11 +237,11 @@ 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.
-- **Trailing `*`** (`"627*"`, `"Pari*"`) becomes FTS5 **prefix syntax**: `627*` matches every
+- **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.
-- **Multiple tokens** join with implicit AND: `"Pari* TX"` matches places whose name contains
-  both a `Pari*`-prefixed word AND the word `TX`.
+- **Multiple tokens** join with an implicit `AND`: `"Pari* TX"` matches places whose name contains
+  both a `Pari*`-prefixed word and the word `TX`.
 
 Example: `findPlace({ text: "902*", placetype: "postalcode" })` returns 90201, 90210, 90211, …
 matching the Los Angeles ZIP corridor.
@@ -256,7 +256,7 @@ This package itself is AGPL-3.0; the WOF data it indexes is CC-BY 4.0. The two l
 
 ## 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 `/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.
+`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).
 

package/lib/address/point/interpolation.ts

@@ -3,34 +3,30 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   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 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.
+ *   Address-point interpolation, the second method of the resolution ladder. When the exact
+ *   address-point tier misses a house number, bracket the number with real neighbor points on the
+ *   same street and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces the tiger range tier's uniform-spacing assumption. Tiger range interpolation
+ *   (`StreetInterpolator`) is 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-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).
+ *   The matching key is `street_key`, the shared normalizer plus the route fold
+ *   (`canonicalizeRouteKey`), identical at build time (`mailwoman situs address-points`) and query
+ *   time by construction. Scope is postcode-first like the segment tier. A query without a postcode
+ *   goes straight to the fallback. The fallback has its own statewide-ambiguity abstention.
  *
- *   Bracketing contract:
+ *   Neighbor candidates never include the queried number itself, so production never overrides an
+ *   on-file number and grading against the same extract is non-circular.
  *
- *   - 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 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
- *       that side, capped at one pair-span beyond the nearest point (`t ≤ 2` — beyond that the line
- *       carries no evidence and the query falls through); `uncertaintyM` = the pair distance plus
- *       the extrapolated overshoot, explicitly larger than the both-sided radius.
- *   - No bracket (no neighbors, a single known number, or past the extrapolation cap): fall through to
- *       the TIGER fallback when configured, else null.
+ *       below and above. `uncertaintyM` is half the distance between them.
+ *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers
+ *       on that side, capped at one pair-span beyond the nearest point (`t ≤ 2`, past which the line
+ *       provides no evidence and the query falls through). `uncertaintyM` is the pair distance plus
+ *       the extrapolated overshoot, larger than the both-sided radius.
+ *   - No bracket, meaning no neighbors, a single known number, or past the extrapolation cap: fall
+ *       through to the tiger fallback when configured, else null.
  *
- *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
+ *   Standalone like the segment tier, wired through the ordered `spatialTiers` list.
  */
 
 import type { InterpolationLookup } from "@mailwoman/core/resolver"
@@ -42,8 +38,10 @@ import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "#i
 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.
+ * 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 provides no evidence about the query number.
  */
 const MAX_EXTRAPOLATION_T = 2
 
@@ -71,29 +69,31 @@ export class AddressPointInterpolator<
 > 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.
+	 * 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 checks.
 	 */
-	readonly #resources = new DisposableStack()
+	readonly #resources: DisposableStack
 	readonly #fallback: StreetInterpolator | undefined
 	readonly #byPostcode: PreparedAll<[postcode: string, street: RouteKey, number: number], PointRow> | undefined
 
 	constructor(opts: { dbPath?: string; database?: DatabaseClient<DB>; fallback?: StreetInterpolator }) {
+		using resources = new DisposableStack()
+
 		if (opts.database) {
 			this.#db = opts.database
 		} else if (opts.dbPath) {
-			this.#db = this.#resources.use(new DatabaseClient<DB>(opts.dbPath, { readOnly: true }))
+			this.#db = 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 extract (#568): with no `address_point` table this tier
-		// is skipped, deferring to the segment fallback rather than crashing at construction.
+		// Degrade gracefully on an extract without an `address_point` table.
+		// The tier is skipped and defers 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
-			// queried number itself is excluded HERE (see module doc: non-circular by construction).
 			this.#byPostcode = prepareAll(
 				this.#db,
 				`SELECT CAST(number AS INTEGER) AS n, lat, lon, source, release
@@ -103,6 +103,8 @@ export class AddressPointInterpolator<
 					AND CAST(number AS INTEGER) != ?`
 			)
 		}
+
+		this.#resources = resources.move()
 	}
 
 	find(query: InterpolationQuery): InterpolatedHit | null {
@@ -111,10 +113,9 @@ export class AddressPointInterpolator<
 		if (!/^\d+$/.test(numberRaw)) return null
 		const n = Number(numberRaw)
 
-		// 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.
+		// Key-variant ladder (see `streetKeyVariants`), the same probe order as the exact-point reader.
 		let rows: PointRow[] = []
 
 		for (const variant of streetKeyVariants(query.street)) {
@@ -165,7 +166,8 @@ function anchorsByNumber(rows: readonly PointRow[]): NumberAnchor[] {
 function interpolateFromNeighbors(rows: readonly PointRow[], n: number): InterpolatedHit | null {
 	const anchors = anchorsByNumber(rows)
 
-	// Nearest known number below and above the query (the rows never contain n itself).
+	// Nearest known number below and above the query.
+	// The rows never contain n itself.
 	let below: NumberAnchor | undefined
 	let above: NumberAnchor | undefined
 
@@ -196,7 +198,7 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 	}
 
 	// Single-sided: extrapolate along the two nearest known numbers on the populated side.
-	// `near` is the anchor closest to n, `far` the next one out; t > 1 by construction.
+	// `t > 1` by construction because n lies outside the span.
 	const side = below ? anchors.slice(-2) : anchors.slice(0, 2)
 
 	if (side.length < 2) return null

package/lib/address/point/schema.ts

@@ -2,18 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   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.
- *
- *   The builder's hot INSERT (tens of millions of rows per state) stays a POSITIONAL prepared
- *   statement for throughput — but its column list is derived from {@link ADDRESS_POINT_COLUMNS}
- *   here, and its table comes from {@link createAddressPointTable}, so the positional order can't
- *   silently drift from what the reader expects. (Same convention as the candidate build: typed
- *   schema guards the contract; positional inserts keep the speed.)
  */
 
 import type { Kysely } from "kysely"
@@ -21,9 +9,8 @@ import type { Kysely } from "kysely"
 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
- * lookup; `street_key` is the #483 route-fold key for interpolation. Coordinates are non-null (the builder drops
- * non-finite coords). `unit`/`postcode`/`locality_norm` are nullable (not every source carries all three).
+ * One rooftop address point; `(street_norm, number)` within a `postcode`
+ * or `locality_norm` scope is the lookup.
  */
 export interface AddressPointTable {
 	/**
@@ -31,12 +18,12 @@ export interface AddressPointTable {
 	 */
 	street_norm: StreetKey
 	/**
-	 * `canonicalizeRouteKey(street_norm)` — the route-fold key (#483 Method 2). Its own brand, so it cannot be
-	 * interchanged with the plain `street_norm` above.
+	 * `canonicalizeRouteKey(street_norm)` — the route-fold key, branded
+	 * so it cannot be interchanged with `street_norm`.
 	 */
 	street_key: RouteKey
 	/**
-	 * House number, normalized lower-case (kept TEXT — "123-A", "12 1/2" must survive).
+	 * House number, normalized lower-case (kept text — "123-A", "12 1/2" must survive).
 	 */
 	number: string
 	unit: string | null
@@ -45,9 +32,7 @@ export interface AddressPointTable {
 	 * Shared {@link normalizeLocalityForKey} of the locality — the fallback scope.
 	 */
 	locality_norm: NameKey | null
-	/**
-	 * The street as it appeared in the source (kept for display / debugging).
-	 */
+
 	street_raw: string
 	lat: number
 	lon: number
@@ -55,18 +40,16 @@ export interface AddressPointTable {
 	 * Provenance: the dataset this point came from (e.g. `overture:us`, `openaddresses`).
 	 */
 	source: string
-	/**
-	 * 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.
+	 * The source register's stable administrative key for the point's commune or municipality —
+	 * BAN's `code_insee`; the coverage basis is computed per this key.
 	 */
 	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.
+	 * The register's own certification flag for the point
+	 * (BAN `certification_commune`: 1 certified, 0 not), never inferred from a share.
 	 */
 	certified: number | null
 }
@@ -79,17 +62,13 @@ 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 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.
+ * The subset of a Kysely handle the DDL touches, narrowed to `schema`
+ * because Kysely is invariant in its schema parameter.
  */
 export type AddressPointSchemaHandle = Pick<Kysely<AddressPointDatabase>, "schema">
 
 /**
- * The `address_point` columns in INSERT order. The builder's positional prepared statement derives its placeholder list
- * from this, so the positional order can't drift from the DDL / the reader.
+ * The `address_point` columns in insert order, from which the builder derives its positional placeholders.
  */
 export const ADDRESS_POINT_COLUMNS = [
 	"street_norm",
@@ -114,7 +93,7 @@ export async function createAddressPointTable(db: AddressPointSchemaHandle): Pro
 	await db.schema
 		.createTable("address_point")
 		.addColumn("street_norm", "text", (c) => c.notNull())
-		// `street_key` = canonicalizeRouteKey(street_norm): the route-fold key (#483 Method 2).
+
 		.addColumn("street_key", "text", (c) => c.notNull())
 		.addColumn("number", "text", (c) => c.notNull())
 		.addColumn("unit", "text")
@@ -147,9 +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 (#247): OSM points often carry no postcode/locality, so the
-	// reader scopes a `(street_norm, number)` probe by the resolved locality's bbox (lat/lon BETWEEN). The
-	// postcode/locality indexes lead with their scope column and can't serve this; US situs never probes by
-	// bbox so it simply carries one extra (cheap) index on a future rebuild.
+	// Street-first index for the bbox scope: OSM points often 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

@@ -0,0 +1,315 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file SQLite implementation of core's `AddressPointLookup`.
+ */
+
+import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
+
+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 reads, typed from the shared {@link AddressPointTable}
+ * so a writer-side rename fails to compile here.
+ */
+type AddressPointRow = Pick<AddressPointTable, "lat" | "lon" | "source" | "release" | "locality_norm" | "postcode">
+
+/**
+ * The column list every prepared SELECT uses.
+ * It must match the fields of `AddressPointRow`.
+ */
+const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode"
+
+/**
+ * Finds an address point by exact normalized `(street, number)` within a postcode,
+ * a locality, or a bounding box.
+ *
+ * Query normalization uses the extract's `streetLocale`, which must match the
+ * locale the extract was built with.
+ * Street matching is exact after normalization.
+ *
+ * Scopes are tried from most to least selective: postcode, locality, locality suffix, then bounding box.
+ * When several rows match, any one of them can answer, because unit siblings share the building coordinate.
+ */
+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
+	/**
+	 * This query matches the locality key by its suffix, for a `zh` query that gives the 鄉鎮市區 without its 縣市.
+	 *
+	 * The (street, number) index narrows the rows first, so the `LIKE` scans only 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 the extract was built with.
+	 * A mismatch makes every key miss.
+	 * It defaults to `"us"`.
+	 * @param opts.localityKeys Whether the extract's `locality_norm` holds full place names.
+	 * With `"abbreviated"`, a row's locality can select a row but never rejects one.
+	 * The US situs extract uses NAD city fields.
+	 * Some counties abbreviate them (`addi` for Addison).
+	 * Other counties replace them with the parent town.
+	 * It defaults to `"abbreviated"` for `"us"` and `"full"` for every other locale.
+	 */
+	constructor(
+		dbPath: PathBuilderLike,
+		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")
+
+		// An extract without an `address_point` table, such as an interrupted build, makes every lookup miss.
+		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 keys locality as 縣市 + 鄉鎮市區.
+		// The parser tags 縣市 as `region` and 鄉鎮市區 as `subregion`.
+		// The Taiwanese register has no postcode, so this pair becomes the locality key.
+		// A query with only the 鄉鎮市區 matches the stored key by its suffix.
+		const scoped =
+			this.#locale === "zh" && !query.locality && query.subregion
+				? query.region
+					? { ...query, locality: `${query.region}${query.subregion}` }
+					: { ...query, localityTail: normalizeLocalityForKeyLocale(query.subregion, "zh") }
+				: query
+
+		// `streetKeyVariants` yields the literal key first.
+		// Each variant runs the full number fallback sequence.
+		// The first variant with a match wins.
+		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 } : {}),
+		}
+	}
+
+	/**
+	 * Tries one normalized street key with the exact number, then fallback number forms.
+	 * Each fallback runs only after the previous forms missed.
+	 */
+	#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)
+
+		// 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]
+
+			if (low) {
+				row = this.#probe(streetNorm, low, query)
+			}
+		}
+
+		// BAN stores a letter suffix as "3 a", while G-NAF and most OA sources store "3a".
+		// For a number of digits plus one letter, the lookup retries the other spacing
+		// and then the bare number.
+		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)
+			}
+		}
+
+		// The Taiwanese register stores `14之12` and `30附40` as numbers `14` and `30`.
+		// It stores the rest in `unit`.
+		// A query number that still includes the sub-number falls back to the base number.
+		// That result is approximate.
+		if (!row && this.#locale === "zh") {
+			const base = /^(\d+)(?:[之附]\d+)+$/u.exec(number)?.[1]
+
+			if (base) {
+				row = this.#probe(streetNorm, base, query)
+			}
+		}
+
+		return row
+	}
+
+	/**
+	 * Probes one (street, number) key by postcode, then locality, then locality suffix, then bounding box.
+	 * Each scope runs only when the previous ones 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
+
+			// One postcode can cover several places with the same street and number,
+			// so a row whose locality agrees with the query is tried first.
+			// The postcode-only row answers only if `#scopeContradicts` accepts it.
+			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) {
+			row = this.#byLocality!(this.#localityKey(query.locality), streetNorm, number)
+		}
+
+		if (!row && query.localityTail && this.#byLocalityTail) {
+			// A Han key contains no `%` or `_`, so the pattern matches a literal suffix.
+			row = this.#byLocalityTail(streetNorm, number, `%${query.localityTail}`)
+		}
+
+		// The bounding box serves extracts whose points have no postcode or locality, such as OSM.
+		if (!row && query.bbox) {
+			const b = query.bbox
+			const candidate = this.#byBbox!(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon)
+
+			// A row with its own scope that the scoped probes missed is a different address in the same box.
+			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
+		}
+
+		return row
+	}
+
+	/**
+	 * Folds the query's locality the way the extract's builder folded `locality_norm`.
+	 *
+	 * FR extracts key arrondissements at the base city, so "Paris 13e Arrondissement"
+	 * and "Paris" produce the same key.
+	 */
+	#localityKey(locality: string): NameKey {
+		if (this.#locale === "fr") return stripArrondissement(normalizeLocalityForKey(locality))
+
+		return normalizeLocalityForKeyLocale(locality, this.#locale)
+	}
+
+	/**
+	 * Returns whether the row's own postcode or locality differs from the query's.
+	 *
+	 * 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.
+	 */
+	#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]()
+	}
+}

package/lib/{address/index.ts → address.ts}

@@ -4,6 +4,6 @@
  * @author Teffen Ellis, et al.
  */
 
-export * from "#address/point/index"
+export * from "#address/point"
 export * from "#address/point/interpolation"
 export * from "#address/point/schema"