@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.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,14 +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 { 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
@@ -67,26 +67,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 +112,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 +131,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/{address-point.ts → lib/address/point.ts}

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  *
  *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
- *   postcode (preferred), locality, or — for shards whose points carry no scope tag (OSM, #247) —
+ *   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 shard's `streetLocale` so build-side and probe-side
+ *   (`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
@@ -15,12 +15,11 @@
  *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import type { AddressPointHit, AddressPointLookup } from "@mailwoman/resolver"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { AddressPointTable } from "./address-point-schema.ts"
-import { hasTable, prepareGet, type PreparedGet } from "./sqlite-utils.ts"
+import type { AddressPointDatabase, AddressPointTable } from "#address/point-schema"
+import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
 import {
 	normalizeLocalityForKey,
 	type NameKey,
@@ -29,11 +28,11 @@ import {
 	streetLocaleForSurface,
 	stripArrondissement,
 	type StreetLocale,
-} from "./street-normalize.ts"
+} from "#street/normalize"
 
 /**
  * The columns this lookup projects — a typed slice of the SHARED {@link AddressPointTable}, so a column rename in
- * `build-address-point-shard.ts` (the writer) is a compile error here (the reader).
+ * `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">
 
@@ -43,10 +42,16 @@ type AddressPointRow = Pick<AddressPointTable, "lat" | "lon" | "source" | "relea
  */
 const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode"
 
-export class AddressPointSqliteLookup implements AddressPointLookup {
-	readonly #db: DatabaseSync
+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
 	readonly #byBbox:
 		| PreparedGet<
@@ -56,15 +61,22 @@ export class AddressPointSqliteLookup implements AddressPointLookup {
 		| undefined
 
 	/**
-	 * @param dbPath Shard path.
-	 * @param opts.streetLocale The street-normalization locale this shard was BUILT with — must match, or every key
+	 * @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 } = {}) {
-		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+	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 shard (interrupted build, stray 0-byte file): with no
+		// 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(
@@ -73,6 +85,12 @@ export class AddressPointSqliteLookup implements AddressPointLookup {
 				 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
@@ -187,32 +205,76 @@ export class AddressPointSqliteLookup implements AddressPointLookup {
 		let row: AddressPointRow | undefined
 
 		if (query.postcode) {
-			row = this.#byPostcode!(query.postcode.trim(), streetNorm, number)
+			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 shards key arrondissement communes at the base city (both-sides fold, see the BAN
+			// 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" shards and every non-arrondissement commune.
-			const localityKey =
-				this.#locale === "fr"
-					? stripArrondissement(normalizeLocalityForKey(query.locality))
-					: normalizeLocalityForKey(query.locality)
-
-			row = this.#byLocality!(localityKey, streetNorm, number)
+			// "Paris" both hit. No-op for "us" extracts and every non-arrondissement commune.
+			row = this.#byLocality!(this.#localityKey(query.locality), streetNorm, number)
 		}
 
 		// 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
-			row = this.#byBbox!(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon)
+			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
 	}
 
-	close(): void {
-		this.#db.close()
+	/**
+	 * 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 {
+		return this.#locale === "fr"
+			? stripArrondissement(normalizeLocalityForKey(locality))
+			: normalizeLocalityForKey(locality)
+	}
+
+	/**
+	 * 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]()
 	}
 }

package/{ancestry-backfill.ts → lib/ancestry/backfill.ts}

@@ -45,14 +45,12 @@
  *   nothing.
  */
 
-import { readdirSync } from "node:fs"
-import type { DatabaseSync } from "node:sqlite"
-
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import { readDirectoryEntries } from "@mailwoman/core/fs/readers"
 import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst"
-import { join } from "path-ts"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { join, resolvePath, type PathBuilderLike } from "path-ts"
 
-import type { WOFDatabase } from "./schema.ts"
+import type { WOFDatabase } from "#schema"
 
 /**
  * Genuinely top-level placetypes — they never have (or need) an ancestor, so skip them.
@@ -76,23 +74,21 @@ export interface AncestryBackfillResult {
 }
 
 /**
- * Discover the `data` directories under a WOF repos root that hold sharded geojson, e.g.
+ * Discover the `data` directories under a WOF repos root that hold attached geojson, e.g.
  * `<root>/whosonfirst-data/whosonfirst-data-admin-us/data`. Resolves an id to its geojson via these roots. Accepts both
  * the nested lab layout (a `whosonfirst-data` group dir holding the admin repos) and a flat layout (admin repos
  * directly under the root); searches at most two directory levels deep.
  */
-export function discoverAdminDataRoots(reposRoot: string): string[] {
+export async function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promise<string[]> {
 	const roots: string[] = []
 
-	const visit = (dir: string, depth: number): void => {
+	const visit = async (dir: string, depth: number): Promise<void> => {
 		if (depth > 2) return
 
 		let names: string[]
 
 		try {
-			names = readdirSync(dir, { withFileTypes: true })
-				.filter((e) => e.isDirectory())
-				.map((e) => e.name)
+			names = (await readDirectoryEntries(dir)).filter((e) => e.isDirectory()).map((e) => e.name)
 		} catch {
 			return
 		}
@@ -103,12 +99,12 @@ export function discoverAdminDataRoots(reposRoot: string): string[] {
 			if (name === "data") {
 				roots.push(child)
 			} else if (name.startsWith("whosonfirst-data")) {
-				visit(child, depth + 1)
+				await visit(child, depth + 1)
 			}
 		}
 	}
 
-	visit(reposRoot, 0)
+	await visit(resolvePath(reposRoot), 0)
 
 	return roots
 }
@@ -136,18 +132,17 @@ function placetypeFromKey(key: string): string | null {
  * skipped rows would have `noGeojson`-skipped anyway. Omit `maxID` (default) for the legacy WOF-only DBs.
  */
 export async function backfillAncestorsFromHierarchy(
-	db: DatabaseSync,
+	db: DatabaseClient<WOFDatabase>,
 	geojsonRoots: readonly string[],
 	opts: { maxID?: number } = {}
 ): Promise<AncestryBackfillResult> {
 	const maxID = opts.maxID ?? Number.MAX_SAFE_INTEGER
-	const kdb = new DatabaseClient<WOFDatabase>({ database: db })
 
 	// "No country-tier ancestor" is the dead-end signal at any depth — see the module docstring. The
 	// earlier "<= 1 ancestor row" test only caught the dead end's origin, never the children that
 	// inherit it (a child of a repaired -4 place has two rows: itself and that parent) (#1445).
 	// The id bound is stated first so SQLite prunes by the PK index before the NOT EXISTS runs at all.
-	const candidateBase = kdb
+	const candidateBase = db
 		.selectFrom("spr")
 		.where("id", "<", maxID)
 		.where((eb) =>
@@ -172,7 +167,7 @@ export async function backfillAncestorsFromHierarchy(
 	// (measured 2026-08-04).
 	const alreadyPresent = new Map<number, Set<number>>()
 
-	for (const row of await kdb
+	for (const row of await db
 		.selectFrom("ancestors")
 		.select(["id", "ancestor_id"])
 		.where("id", "in", candidateBase.select("spr.id"))
@@ -198,7 +193,7 @@ export async function backfillAncestorsFromHierarchy(
 
 	for (const { id, placetype } of candidates) {
 		if (placetype && TOP_PLACETYPES.has(placetype)) continue
-		const gj = readWOFFeature(id, geojsonRoots)
+		const gj = await readWOFFeature(id, geojsonRoots)
 		const hierarchy = gj?.properties?.["wof:hierarchy"]
 
 		if (!hierarchy || !hierarchy.length) {

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

@@ -15,9 +15,9 @@
  *   geocoding always does).
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { allRows } from "./sqlite-utils.ts"
+import { allRows } from "#sqlite-utils"
 
 /**
  * WOF placetype → containment depth, coarsest = 1. Higher = finer. Placetypes we never resolve (continent, empire, …)
@@ -61,7 +61,7 @@ export interface AncestorPlaceRow {
  * The ancestor lineage of `id` — self excluded, nearest-first. Returns `[]` when the place has no recorded ancestry.
  * NOT memoized here; `WOFSQLitePlaceLookup` keeps its own per-id cache.
  */
-export function ancestorLineage(db: DatabaseSync, id: number, schemaName = "main"): AncestorPlaceRow[] {
+export function ancestorLineage<DB>(db: DatabaseClient<DB>, id: number, schemaName = "main"): AncestorPlaceRow[] {
 	const rows = allRows<AncestorPlaceRow>(
 		db.prepare(
 			`SELECT a.ancestor_id AS id, a.ancestor_placetype AS placetype, s.name AS name,
@@ -76,3 +76,5 @@ export function ancestorLineage(db: DatabaseSync, id: number, schemaName = "main
 
 	return rows
 }
+
+export * from "#ancestry/backfill"