@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.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 \
@@ -166,6 +166,7 @@ You can also build the index programmatically via the package's `./fts` subpath:
 
 ```ts
 import { DatabaseSync } from "node:sqlite"
+
 import { buildPlaceSearchFts } from "@mailwoman/resolver-wof-sqlite/fts"
 
 using db = new DatabaseSync("/path/to/wof.db")
@@ -175,7 +176,7 @@ const { created, indexedRows, durationMs } = buildPlaceSearchFts(db, {
 })
 ```
 
-## Ranking
+## Rank places
 
 The resolver scores candidates by:
 
@@ -237,11 +238,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 +257,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,18 +103,21 @@ export class AddressPointInterpolator<
 					AND CAST(number AS INTEGER) != ?`
 			)
 		}
+
+		this.#resources = resources.move()
 	}
 
+	readonly radiusCalibration = null
+
 	find(query: InterpolationQuery): InterpolatedHit | null {
 		const numberRaw = query.number.trim()
 
 		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,9 +168,10 @@ 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).
-	let below: NumberAnchor | undefined
-	let above: NumberAnchor | undefined
+	// Nearest known number below and above the query.
+	// The rows never contain n itself.
+	let below: NumberAnchor | null = null
+	let above: NumberAnchor | null = null
 
 	for (const anchor of anchors) {
 		if (anchor.n < n) {
@@ -188,6 +192,7 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 			lon: below.lon + (above.lon - below.lon) * t,
 			interpolated: true,
 			method: "address_point",
+			parityMatched: null,
 			bracket: "both",
 			uncertaintyM: Math.round(spanM / 2),
 			source: below.source,
@@ -196,7 +201,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
@@ -215,6 +220,7 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 		lon,
 		interpolated: true,
 		method: "address_point",
+		parityMatched: null,
 		bracket: "single",
 		// Explicitly larger than the both-sided radius: the whole pair span plus the overshoot.
 		uncertaintyM: Math.round(pairM + overshootM),

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()
 }