@mailwoman/resolver-wof-sqlite 9.4.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 → point/interpolation.ts}

@@ -3,47 +3,45 @@
  * @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"
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { AddressPointDatabase } from "#address/point-schema"
+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.
+ * 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

@@ -0,0 +1,132 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { Kysely } from "kysely"
+
+import type { NameKey, RouteKey, StreetKey } from "#street/normalize"
+
+/**
+ * One rooftop address point; `(street_norm, number)` within a `postcode`
+ * or `locality_norm` scope is the lookup.
+ */
+export interface AddressPointTable {
+	/**
+	 * Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key.
+	 */
+	street_norm: StreetKey
+	/**
+	 * `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).
+	 */
+	number: string
+	unit: string | null
+	postcode: string | null
+	/**
+	 * Shared {@link normalizeLocalityForKey} of the locality — the fallback scope.
+	 */
+	locality_norm: NameKey | null
+
+	street_raw: string
+	lat: number
+	lon: number
+	/**
+	 * Provenance: the dataset this point came from (e.g. `overture:us`, `openaddresses`).
+	 */
+	source: string
+
+	release: string
+	/**
+	 * 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, 0 not), never inferred from a share.
+	 */
+	certified: number | null
+}
+
+/**
+ * The address-point database schema for `new DatabaseClient<AddressPointDatabase>(...)`.
+ */
+export interface AddressPointDatabase {
+	address_point: AddressPointTable
+}
+
+/**
+ * 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, from which the builder derives its positional placeholders.
+ */
+export const ADDRESS_POINT_COLUMNS = [
+	"street_norm",
+	"street_key",
+	"number",
+	"unit",
+	"postcode",
+	"locality_norm",
+	"street_raw",
+	"lat",
+	"lon",
+	"source",
+	"release",
+	"admin_code",
+	"certified",
+] as const
+
+/**
+ * Create the `address_point` table — called before the streaming bulk load.
+ */
+export async function createAddressPointTable(db: AddressPointSchemaHandle): Promise<void> {
+	await db.schema
+		.createTable("address_point")
+		.addColumn("street_norm", "text", (c) => c.notNull())
+
+		.addColumn("street_key", "text", (c) => c.notNull())
+		.addColumn("number", "text", (c) => c.notNull())
+		.addColumn("unit", "text")
+		.addColumn("postcode", "text")
+		.addColumn("locality_norm", "text")
+		.addColumn("street_raw", "text", (c) => c.notNull())
+		.addColumn("lat", "real", (c) => c.notNull())
+		.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()
+}
+
+/**
+ * Create the three probe indexes the reader relies on (postcode-scope, locality-scope, route-key).
+ */
+export async function createAddressPointIndexes(db: AddressPointSchemaHandle): Promise<void> {
+	await db.schema
+		.createIndex("idx_ap_postcode")
+		.on("address_point")
+		.columns(["postcode", "street_norm", "number"])
+		.execute()
+
+	await db.schema
+		.createIndex("idx_ap_locality")
+		.on("address_point")
+		.columns(["locality_norm", "street_norm", "number"])
+		.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,
+	// 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

@@ -2,23 +2,14 @@
  * @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.
+ * @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 type { AddressPointDatabase, AddressPointTable } from "#address/point/schema"
 import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
 import {
 	normalizeHouseNumberForKey,
@@ -33,17 +24,28 @@ import {
 } 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).
+ * 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 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.
+ * 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
 {
@@ -56,8 +58,9 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		| 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.
+	 * 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>
@@ -71,22 +74,25 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 
 	/**
 	 * @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.
+	 * @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: string, opts: { streetLocale?: StreetLocale; localityKeys?: "full" | "abbreviated" } = {}) {
+	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")
 
-		// 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).
+		// 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,
@@ -134,10 +140,10 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 
 		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.
+		// 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
@@ -145,9 +151,9 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 					: { ...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.
+		// `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))) {
@@ -169,8 +175,8 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	}
 
 	/**
-	 * 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.
+	 * 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,
@@ -186,10 +192,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	) {
 		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.
+		// 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]
 
@@ -198,12 +201,9 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			}
 		}
 
-		// 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).
+		// 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)
@@ -215,11 +215,10 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			}
 		}
 
-		// 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.
+		// 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]
 
@@ -232,8 +231,8 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	}
 
 	/**
-	 * The scope ladder for one (street, number) key: postcode, then locality, then the bbox fall-through — each rung only
-	 * when the prior missed.
+	 * 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,
@@ -251,11 +250,9 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			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.
+			// 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)
 
@@ -263,27 +260,20 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		}
 
 		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.
+			// A Han key contains no `%` or `_`, so the pattern matches a literal suffix.
 			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.
+		// 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 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.
+			// 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
 		}
 
@@ -291,9 +281,10 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	}
 
 	/**
-	 * 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.
+	 * 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))
@@ -302,15 +293,11 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	}
 
 	/**
-	 * 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.
+	 * Returns whether the row's own postcode or locality differs from the query's.
 	 *
-	 * 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.
+	 * 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

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

@@ -5,5 +5,5 @@
  */
 
 export * from "#address/point"
-export * from "#address/point-interpolation"
-export * from "#address/point-schema"
+export * from "#address/point/interpolation"
+export * from "#address/point/schema"