@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/lib/search-fetch.ts

@@ -0,0 +1,257 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The FTS5 candidate fetch behind the fuzzy name match: the schema-qualified `place_search`
+ *   MATCH, its population-ordered companion fetch, and the raw row shape both of them return.
+ *
+ *   Bbox and near-with-radius narrow at the SQL level through SQLite's built-in `rtree`, whose index name and schema
+ *   live in `fts.ts` beside the FTS5 build. That is why this package pulls neither SpatiaLite nor turf: the R*Tree does
+ *   the narrowing, and the passes downstream of it operate on ≤ a few hundred candidates per query rather than the
+ *   whole corpus, so an exact haversine over the survivors is cheap.
+ */
+
+import { bboxAround } from "@mailwoman/spatial"
+import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
+
+import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "#fts/index"
+import type { RankingWeights } from "#ranking-weights"
+import { allRows } from "#sqlite-utils"
+import type { FindPlaceQuery, WOFPlacetype } from "#types"
+
+/**
+ * Query length at or below which the FTS window is widened. A two- or three-character query is almost always a region
+ * abbreviation, where the exact match can otherwise fall outside the window behind higher-bm25 partial hits — "NY"
+ * losing to "New York".
+ */
+const SHORT_QUERY_MAX_LENGTH = 3
+
+/**
+ * Over-fetch floor for SHORT (≤3-char) queries — region abbreviations like "NY"/"VT". An exact-abbrev holder's BM25 is
+ * poor (long multilingual alt-name document), so the normal `limit * 4` window can drop it before `exactMatchTiering`
+ * promotes it. 200 comfortably covers every same-abbrev region across the 12-country gazetteer (a 2-letter token
+ * matches a few dozen regions at most) while staying a cheap region-placetype fetch. See the `#fuzzyNameMatch`
+ * over-fetch comment.
+ */
+const SHORT_QUERY_OVERFETCH = 200
+
+/**
+ * How many rows the population-ordered companion fetch (#905) adds to the candidate pool. Small on purpose: its only
+ * job is to guarantee the FAMOUS holders of a name enter the pool at all — for "Paris"-class floods the bm25 window is
+ * saturated by thousands of tiny same-name rows and no boost inside the bm25-based ORDER BY can rescue a candidate
+ * whose bm25 is length-poisoned by ~15 points (see the fetch-site comment).
+ */
+const POPULATION_FETCH_LIMIT = 15
+
+export interface RawSearchRow {
+	id: number
+	name: string
+	placetype: string
+	country: string | null
+	parent_id: number | null
+	rank: number // BM25 (lower = better in SQLite); we negate to get higher-is-better
+	lat: number | null
+	lon: number | null
+	min_latitude: number | null
+	max_latitude: number | null
+	min_longitude: number | null
+	max_longitude: number | null
+	population: number | null // from the place_population aux table; null when missing
+	/**
+	 * From `place_importance.encyclopedic` when the extract's table carries the two-score split columns. NULL means the
+	 * place has no Wikipedia article, or the extract predates the split — absence either way, and never 0 (ROAD_TO_V9
+	 * §2).
+	 */
+	encyclopedic: number | null
+}
+
+/**
+ * Fetch the raw candidate rows for a name match on one extract: the BM25-ordered window over `place_search` (widened
+ * for short queries), plus the population-ordered companion fetch that keeps the prominent holders of a name
+ * pool-complete. `schemaName` is the routed extract's bare schema name — validated at construction, so it is
+ * interpolated directly.
+ */
+export function fetchSearchRows<DB>(options: {
+	db: DatabaseClient<DB>
+	schemaName: string
+	query: FindPlaceQuery
+	placetypes: WOFPlacetype[] | null
+	ftsQuery: string
+	limit: number
+	hasBboxIndex: ReadonlyMap<string, boolean>
+	hasPopulationIndex: ReadonlyMap<string, boolean>
+	encyclopedicClauses: ReadonlyMap<string, { select: string; join: string }>
+	weights: RankingWeights
+}): RawSearchRow[] {
+	const {
+		db,
+		schemaName: sch,
+		query,
+		placetypes,
+		ftsQuery,
+		limit,
+		hasBboxIndex,
+		hasPopulationIndex,
+		encyclopedicClauses,
+		weights,
+	} = options
+
+	// Over-fetch so post-scoring + exact-match tiering have room to re-rank. SHORT queries (a 2–3-char
+	// region abbreviation like "NY"/"VT") are the danger case the `exactMatchTiering` docstring flags:
+	// the exact-abbrev holder's BM25 is poor (its long multilingual alt-name document tanks the score),
+	// so under the normal `limit * 4` window it drops OUT of the candidate pool BEFORE tiering can
+	// promote it — "NY" then resolves to a token-matching foreign region (Highland, GB) instead of New
+	// York. Widen the window for short queries so the exact match is always present to be tiered.
+	// (Cross-country abbrev collisions — "VT" is BOTH Vermont and Viterbo — still need a country/
+	// postcode signal to disambiguate; this only rescues the window-drop class, not genuine ambiguity.
+	// With a `country` hint every abbrev resolves; bare + no-context lifts 7→10/15 US states.)
+	const ftsLimit =
+		query.text.trim().length <= SHORT_QUERY_MAX_LENGTH ? Math.max(limit * 4, SHORT_QUERY_OVERFETCH) : limit * 4
+
+	// Filter out historical / superseded / deprecated places by default — they live in the same
+	// spr table but should never win a contemporary lookup. `is_current = 0` is the only WOF
+	// value that means "not current"; both `-1` (modern) and `1` (legacy) mean current. See #91.
+	// Note: with schema-qualified FROM the bare `place_search` reference in MATCH resolves to
+	// the FROM table — required by FTS5 parser, see extracts.ts header comment.
+	const where: string[] = ["place_search MATCH ?", "spr.is_current != 0", "spr.is_deprecated = 0"]
+	const params: SQLInputValue[] = [ftsQuery]
+
+	if (placetypes && placetypes.length) {
+		where.push(`spr.placetype IN (${placetypes.map(() => "?").join(", ")})`)
+		params.push(...placetypes)
+	}
+
+	if (query.country) {
+		where.push("spr.country = ?")
+		params.push(query.country)
+	}
+
+	if (query.parentID !== undefined) {
+		where.push(`(spr.parent_id = ? OR spr.id IN (SELECT id FROM ${sch}.ancestors WHERE ancestor_id = ?))`)
+		params.push(query.parentID, query.parentID)
+	}
+
+	// Bbox + near-with-radius are SQL-level filters via the R*Tree. We only emit the JOIN when
+	// the active extract has the R*Tree; missing-but-requested is silently treated as no-bbox-
+	// filter so legacy DBs / extracts-without-bbox don't crash.
+	const extractHasBbox = hasBboxIndex.get(sch) === true
+	const useBboxJoin = (query.bbox || query.near?.maxDistanceKm !== undefined) && extractHasBbox
+	let joinClause = `JOIN ${sch}.spr ON spr.id = place_search.wof_id`
+
+	if (useBboxJoin) {
+		joinClause += ` JOIN ${sch}.${PLACE_BBOX_TABLE} bbox ON bbox.id = spr.id`
+		// AABB intersection — both bbox sides must overlap. R*Tree handles this in O(log n).
+		const filterBox = query.bbox || bboxAround(query.near!.lat, query.near!.lon, query.near!.maxDistanceKm!)
+		where.push("bbox.min_lat <= ? AND bbox.max_lat >= ?", "bbox.min_lon <= ? AND bbox.max_lon >= ?")
+		params.push(filterBox.maxLat, filterBox.minLat, filterBox.maxLon, filterBox.minLon)
+	}
+
+	// LEFT JOIN the population aux table when present. Missing-on-this-extract means the SELECT
+	// just doesn't include the population column; the post-scoring loop treats it as 0.
+	const extractHasPopulation = hasPopulationIndex.get(sch) === true
+
+	const populationSelect = extractHasPopulation
+		? `${PLACE_POPULATION_TABLE}.population AS population`
+		: `NULL AS population`
+
+	const populationJoin = extractHasPopulation
+		? `LEFT JOIN ${sch}.${PLACE_POPULATION_TABLE} ON ${PLACE_POPULATION_TABLE}.id = spr.id`
+		: ""
+
+	// The encyclopedic score is CARRIED, never ranked on (ROAD_TO_V9 §2, ratified 2026-08-06) — it
+	// appears in the SELECT and in no ORDER BY, here or in the companion fetch below. Conditioned on the
+	// split column, so a pre-split extract emits a literal NULL and builds no join at all.
+	const { select: encyclopedicSelect, join: encyclopedicJoin } = encyclopedicClauses.get(sch)!
+
+	// Push the population boost into the ORDER BY when the index is available, so famous places
+	// (whose long alt-name lists hurt BM25) actually make it into the over-fetch window. The TS
+	// post-scoring will still compute the same boost for the final score; this just ensures the
+	// candidate set is right.
+	//
+	// Formula: rank_adjusted = bm25 - populationBoost * min(1.0, log10(1 + pop) / scaleLog10)
+	// Lower rank_adjusted = better (matches SQLite's bm25 convention of "more negative = better").
+	//
+	// #905 — do NOT reach for bm25 column weights here. Measured falsification (2026-07-02): FTS5's
+	// bm25 length normalization is polluted by the row's TOTAL document size, so identical 1-token
+	// `name` docs read −16.0 (empty alt_names) vs −0.43 (2.7 KB alt_names) EVEN with the alt_names
+	// column weighted to zero — no weighting isolates name relevance in this schema. The famous-
+	// holder guarantee lives in the population-ordered companion fetch below instead, and the
+	// exact tier breaks ties by population in the post-scoring sort.
+	const orderByExpr = extractHasPopulation
+		? `(bm25(place_search) - ? * MIN(1.0, COALESCE(log10(1.0 + ${PLACE_POPULATION_TABLE}.population), 0) / ?))`
+		: "bm25(place_search)"
+
+	// Schema-qualified FROM with bare-name MATCH — required syntax for FTS5 on attached schemas.
+	// See extracts.ts header for the failure mode that drove this design.
+	const stmt = db.prepare(`
+		SELECT
+			spr.id AS id,
+			spr.name,
+			spr.placetype,
+			spr.country,
+			spr.parent_id,
+			bm25(place_search) AS rank,
+			spr.latitude AS lat,
+			spr.longitude AS lon,
+			spr.min_latitude, spr.max_latitude, spr.min_longitude, spr.max_longitude,
+			${populationSelect},
+			${encyclopedicSelect}
+		FROM ${sch}.place_search
+		${joinClause}
+		${populationJoin}
+		${encyclopedicJoin}
+		WHERE ${where.join(" AND ")}
+		ORDER BY ${orderByExpr} ASC
+		LIMIT ?
+	`)
+
+	if (extractHasPopulation) {
+		params.push(weights.populationBoost, weights.populationScaleLog10)
+	}
+
+	params.push(ftsLimit)
+
+	const rawRows = allRows<RawSearchRow>(stmt, ...params)
+
+	// #905 companion fetch: the same MATCH, ordered by population alone. For name floods
+	// ("Paris" matches thousands of gap-fill villages) the bm25-based window above cannot admit
+	// the famous holder — its bm25 is length-poisoned by the row's alias bulk (measured ~15 pts,
+	// vs a +4.0 boost cap), so FR Paris never even reaches post-scoring. This fetch makes the
+	// prominent holders of a name pool-complete BY CONSTRUCTION; the exact-tier sort below
+	// decides whether they win. Skipped without a population index (nothing to order by).
+	if (extractHasPopulation) {
+		const popStmt = db.prepare(`
+			SELECT
+				spr.id AS id,
+				spr.name,
+				spr.placetype,
+				spr.country,
+				spr.parent_id,
+				bm25(place_search) AS rank,
+				spr.latitude AS lat,
+				spr.longitude AS lon,
+				spr.min_latitude, spr.max_latitude, spr.min_longitude, spr.max_longitude,
+				${populationSelect},
+				${encyclopedicSelect}
+			FROM ${sch}.place_search
+			${joinClause}
+			${populationJoin}
+			${encyclopedicJoin}
+			WHERE ${where.join(" AND ")}
+			ORDER BY COALESCE(${PLACE_POPULATION_TABLE}.population, 0) DESC
+			LIMIT ?
+		`)
+
+		const popParams = params.slice(0, -3) // drop the two boost params + ftsLimit
+		const seen = new Set(rawRows.map((r) => r.id))
+
+		for (const row of allRows<RawSearchRow>(popStmt, ...popParams, POPULATION_FETCH_LIMIT)) {
+			if (!seen.has(row.id)) {
+				rawRows.push(row)
+			}
+		}
+	}
+
+	return rawRows
+}

package/{sqlite-convention-source.ts → lib/sqlite-convention-source.ts}

@@ -8,21 +8,20 @@
  *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
  *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
  *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
- *   value in memory `feedback-no-load-bearing-trivia`).
+ *   value in memory `feedback-no-irrelevant-trivia`).
  *
  *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
  *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
  *   swallowed.
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import { tryParsingJSON } from "@mailwoman/core/json"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
+import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "#convention/index"
 
-import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "./convention.ts"
-
-export class SqliteConventionSource implements ConventionSource {
-	readonly #db: DatabaseSync
+export class SqliteConventionSource<DB> implements ConventionSource {
+	readonly #db: DatabaseClient<DB>
 	readonly #schema: string
 	/**
 	 * Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once.
@@ -31,10 +30,10 @@ export class SqliteConventionSource implements ConventionSource {
 
 	/**
 	 * @param db An open handle to a DB that has the convention asset attached (or is it).
-	 * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed shard name —
-	 *   `WOFSqlitePlaceLookup` auto-detects which shard carries the table).
+	 * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed extract name —
+	 *   `WOFSQLitePlaceLookup` auto-detects which extract carries the table).
 	 */
-	constructor(db: DatabaseSync, schema: string) {
+	constructor(db: DatabaseClient<DB>, schema: string) {
 		this.#db = db
 		this.#schema = schema
 	}

package/lib/sqlite-utils.ts

@@ -0,0 +1,83 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Small shared helpers for the SQLite-backed lookups.
+ */
+
+import { allRows, getRow } from "@mailwoman/core/utils"
+import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
+import { hasColumn as columnExists, tableExists } from "@mailwoman/sqlite/introspection"
+
+// The row-shape assertion itself lives in `core` so the readers that cannot depend on this package reach the same
+// helper; re-exported here because this module is where this package's readers already look for it.
+export { allRows, getRow } from "@mailwoman/core/utils"
+
+/**
+ * A prepared single-row query whose parameter tuple remains visible to TypeScript. `StatementSync` accepts only the
+ * broad `SQLInputValue[]`, which otherwise erases tagged key types before they reach SQLite.
+ */
+export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | undefined
+
+/**
+ * Prepare a single-row query while preserving its exact parameter tuple at every call site.
+ */
+export function prepareGet<Parameters extends SQLInputValue[], Row, DB>(
+	db: DatabaseClient<DB>,
+	sql: string
+): PreparedGet<Parameters, Row> {
+	const statement = db.prepare(sql)
+
+	return (...parameters) => getRow<Row>(statement, ...parameters)
+}
+
+/**
+ * Multi-row counterpart to {@link PreparedGet}.
+ */
+export type PreparedAll<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row[]
+
+/**
+ * Prepare a multi-row query while preserving its exact parameter tuple at every call site.
+ */
+export function prepareAll<Parameters extends SQLInputValue[], Row, DB>(
+	db: DatabaseClient<DB>,
+	sql: string
+): PreparedAll<Parameters, Row> {
+	const statement = db.prepare(sql)
+
+	return (...parameters) => allRows<Row>(statement, ...parameters)
+}
+
+/**
+ * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
+ * empty/tableless extract — an interrupted `build-*-extract.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db
+ * "…"` CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode
+ * (#568). A missing table makes the lookup a no-op miss.
+ */
+export function hasTable<DB>(db: DatabaseClient<DB>, name: string): boolean {
+	try {
+		return tableExists(db, name)
+	} catch {
+		return false
+	}
+}
+
+/**
+ * True when `table` exists in the open database AND carries `column`.
+ *
+ * The column-level sibling of {@link hasTable}, and it exists for the same reason one layer down: an artifact built
+ * before a column was added is still a VALID artifact, and a reader that unconditionally names the new column in its
+ * `SELECT` turns "this gazetteer is a build behind" into `no such column` at the first keystroke. Probe once at
+ * construction and shape the query — `table_info` is a PRAGMA, so it must not sit on a per-query path.
+ *
+ * Note the interpolation: PRAGMA does not take bound parameters, so `table` is spliced. Every caller passes a
+ * module-level constant; never pass user input.
+ */
+export function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean {
+	try {
+		return columnExists(db, table, column)
+	} catch {
+		return false
+	}
+}

package/{street-centroid-schema.ts → lib/street/centroid-schema.ts}

@@ -3,10 +3,10 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the DERIVED STREET-CENTROID shard (`street-centroids-<cc>.db`, built by
- *   `ban/scripts/build-street-centroid-shard.ts` — the #1042 street-level tier behind "street-only
- *   FR queries deserve a street-level answer"). The shard is a `GROUP BY street` roll-up of the
- *   sealed rooftop address-point shard: one row per (street, postcode, commune) carrying the street's
+ *   Typed schema for the DERIVED STREET-CENTROID extract (`street-centroids-<cc>.db`, built by
+ *   `ban/scripts/build-street-centroid-extract.ts` — the #1042 street-level tier behind "street-only
+ *   FR queries deserve a street-level answer"). The extract is a `GROUP BY street` roll-up of the
+ *   sealed rooftop address-point extract: one row per (street, postcode, commune) carrying the street's
  *   CENTROID + bounding-box EXTENT + member-point count. No new data source — a derived artifact.
  *
  *   Single source of truth for the columns shared by the BUILDER (a positional prepared INSERT for
@@ -22,6 +22,8 @@
 
 import type { Kysely } from "kysely"
 
+import type { NameKey, StreetKey } from "#street/normalize"
+
 /**
  * One street roll-up. `(street_norm, postcode, locality_base)` is unique. `lat`/`lon` are the UNWEIGHTED mean of the
  * group's member address points (each source row = one point), so a cross-group weighted mean (`SUM(lat*point_count) /
@@ -32,7 +34,7 @@ export interface StreetCentroidTable {
 	/**
 	 * Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key.
 	 */
-	street_norm: string
+	street_norm: StreetKey
 	/**
 	 * The 5-digit postcode of this group, or null when the source row carried none.
 	 */
@@ -40,7 +42,7 @@ export interface StreetCentroidTable {
 	/**
 	 * Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope.
 	 */
-	locality_base: string
+	locality_base: NameKey
 	/**
 	 * Weighted-mean centroid latitude of the street's member points.
 	 */
@@ -75,6 +77,10 @@ export interface StreetCentroidTable {
 	 * name-evidence rerank folds the model's street surface with the SAME `foldStreetSurface` used to build this column
 	 * (the fold-parity contract), so it must not drift from `street_norm`'s richer normalizer. Indexed (`idx_sc_name`)
 	 * for a direct seek.
+	 *
+	 * Deliberately UNBRANDED despite the `name_key` column name: `foldStreetSurface` is a different fold from the
+	 * {@link NameKey} one every other `name_key` column carries, and giving it that brand would invite exactly the
+	 * cross-fold probe the brands exist to stop.
 	 */
 	name_key: string
 }

package/{street-centroid.ts → lib/street/centroid.ts}

@@ -8,7 +8,7 @@
  *   number) plus a postcode/commune scope, it returns the street's CENTROID + an honest extent-derived
  *   uncertainty from the derived `street-centroids-<cc>.db` roll-up.
  *
- *   Query-side normalization is THE shared normalizer (`street-normalize.ts`), selected per the shard's
+ *   Query-side normalization is THE shared normalizer (`street-normalize.ts`), selected per the extract's
  *   `streetLocale`, so build-side and probe-side keys agree by construction. The commune scope folds
  *   through `normalizeLocalityForKey` + `stripArrondissement` (BAN names Paris/Lyon/Marseille per
  *   arrondissement; a query names the base commune).
@@ -19,17 +19,21 @@
  *   exact-after-normalization only (no fuzzy street matching in this tier).
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import type { StreetCentroidHit, StreetCentroidLookup } from "@mailwoman/resolver"
+import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { hasTable } from "./sqlite-utils.ts"
+import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
+import type { StreetCentroidDatabase } from "#street/centroid-schema"
 import {
 	normalizeLocalityForKey,
 	normalizeStreetForKeyLocale,
+	type NameKey,
+	type StreetKey,
+	streetLocaleForSurface,
 	type StreetLocale,
 	stripArrondissement,
-} from "./street-normalize.ts"
+} from "#street/normalize"
 
 /**
  * The weighted-centroid + extent + provenance an aggregate probe projects. `lat` is null when nothing matched.
@@ -58,40 +62,34 @@ const AGG_SELECT =
  * Half the bbox diagonal, in METERS — an honest coarse radius for a street centroid.
  */
 function extentRadiusM(minLat: number, maxLat: number, minLon: number, maxLon: number): number {
-	const R = 6_371_000
-	const toRad = (d: number): number => (d * Math.PI) / 180
-	const dLat = toRad(maxLat - minLat)
-	const dLon = toRad(maxLon - minLon)
-	const midLat = toRad((minLat + maxLat) / 2)
-	const a = Math.sin(dLat / 2) ** 2 + Math.cos(midLat) ** 2 * Math.sin(dLon / 2) ** 2
-	const diag = 2 * R * Math.asin(Math.min(1, Math.sqrt(a)))
-
-	return Math.round(diag / 2)
+	return Math.round(haversineKm(minLat, minLon, maxLat, maxLon) * 500)
 }
 
 export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
-	readonly #db: DatabaseSync
+	readonly #db: DatabaseClient<StreetCentroidDatabase>
 	readonly #locale: StreetLocale
-	readonly #byPostcode: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byLocality: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #byPostcode: PreparedGet<[postcode: string, street: StreetKey], AggRow> | undefined
+	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey], AggRow> | 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 `"fr"` (BAN is the French national register; the tier is FR-only today).
 	 */
 	constructor(dbPath: string, opts: { streetLocale?: StreetLocale } = {}) {
-		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+		this.#db = new DatabaseClient<StreetCentroidDatabase>(dbPath, { readOnly: true })
 		this.#locale = opts.streetLocale ?? "fr"
 
-		// 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
 		// `street_centroid` table this lookup is a no-op miss, not a crash (mirrors the address-point reader).
 		if (hasTable(this.#db, "street_centroid")) {
-			this.#byPostcode = this.#db.prepare(
+			this.#byPostcode = prepareGet(
+				this.#db,
 				`SELECT ${AGG_SELECT} FROM street_centroid WHERE postcode = ? AND street_norm = ?`
 			)
 
-			this.#byLocality = this.#db.prepare(
+			this.#byLocality = prepareGet(
+				this.#db,
 				`SELECT ${AGG_SELECT} FROM street_centroid WHERE locality_base = ? AND street_norm = ?`
 			)
 		}
@@ -99,19 +97,19 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 
 	find(query: { street: string; postcode?: string; locality?: string }): StreetCentroidHit | null {
 		if (!this.#byPostcode || !this.#byLocality) return null
-		const streetNorm = normalizeStreetForKeyLocale(query.street, this.#locale)
+		const streetNorm = normalizeStreetForKeyLocale(query.street, streetLocaleForSurface(query.street, this.#locale))
 
 		if (!streetNorm) return null
 
 		let row: AggRow | undefined
 
 		if (query.postcode?.trim()) {
-			row = this.#byPostcode.get(query.postcode.trim(), streetNorm) as AggRow | undefined
+			row = this.#byPostcode(query.postcode.trim(), streetNorm)
 		}
 
 		if ((!row || row.lat == null) && query.locality?.trim()) {
 			const base = stripArrondissement(normalizeLocalityForKey(query.locality))
-			row = this.#byLocality.get(base, streetNorm) as AggRow | undefined
+			row = this.#byLocality(base, streetNorm)
 		}
 
 		if (!row || row.lat == null || row.lon == null) return null
@@ -125,7 +123,7 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 		}
 	}
 
-	close(): void {
-		this.#db.close()
+	[Symbol.dispose](): void {
+		this.#db[Symbol.dispose]()
 	}
 }

package/lib/street/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#street/centroid"
+export * from "#street/centroid-schema"
+export * from "#street/morphology-fst-builder"
+export * from "#street/morphology-fst-loader"
+export * from "#street/name-lookup"
+export * from "#street/normalize"
+export * from "#street/segment-schema"

package/{street-morphology-fst-builder.ts → lib/street/morphology-fst-builder.ts}

@@ -23,14 +23,13 @@
  *   `fst-street-morphology.bin`.
  */
 
-import { readdirSync, readFileSync, statSync } from "node:fs"
-import { join } from "node:path"
-
+import { isDirectory, readDirectory, readLocalTextFile, statPath } from "@mailwoman/core/fs/readers"
+import { join } from "path-ts"
 import { TextSpliterator } from "spliterator"
 
-import type { FSTNode } from "./fst-matcher.ts"
-import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
-import type { FSTProvenance, PlaceEntry } from "./fst-types.ts"
+import type { FSTNode } from "#fst/matcher"
+import { FSTMatcher, normalizeTokens } from "#fst/matcher"
+import type { FSTProvenance, PlaceEntry } from "#fst/types"
 
 /**
  * Reserved synthetic wofID base for street-morphology entries. 32-bit unsigned, well above any realistic WOF
@@ -96,7 +95,9 @@ function parseLine(line: string): { canonical: string; variants: string[] } | nu
 	return { canonical: parts[0]!, variants: parts }
 }
 
-export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): BuildStreetMorphologyFSTResult {
+export async function buildStreetMorphologyFST(
+	opts: BuildStreetMorphologyFSTOpts
+): Promise<BuildStreetMorphologyFSTResult> {
 	const progress = opts.onProgress ?? (() => {})
 	const minVariantLength = opts.minVariantLength ?? 3
 
@@ -107,19 +108,28 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 	if (opts.locales && opts.locales.length) {
 		locales = opts.locales
 	} else {
-		locales = readdirSync(opts.dictionariesDir).filter((entry) => {
+		const entries = await readDirectory(opts.dictionariesDir)
+		const localeProbes: Array<[string, boolean]> = []
+
+		for (const entry of entries) {
 			const localePath = join(opts.dictionariesDir, entry)
 
-			if (!statSync(localePath).isDirectory()) return false
+			if (!(await isDirectory(localePath))) {
+				localeProbes.push([entry, false])
+
+				continue
+			}
 
 			try {
-				statSync(join(localePath, STREET_TYPES_FILENAME))
+				await statPath(join(localePath, STREET_TYPES_FILENAME))
 
-				return true
+				localeProbes.push([entry, true])
 			} catch {
-				return false
+				localeProbes.push([entry, false])
 			}
-		})
+		}
+
+		locales = localeProbes.filter(([, hasFile]) => hasFile).map(([entry]) => entry)
 	}
 
 	progress("discover", `Found ${locales.length} locales with ${STREET_TYPES_FILENAME}`)
@@ -130,7 +140,7 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 
 	for (const locale of locales) {
 		const filePath = join(opts.dictionariesDir, locale, STREET_TYPES_FILENAME)
-		const content = readFileSync(filePath, "utf8")
+		const content = await readLocalTextFile(filePath)
 
 		for (const line of TextSpliterator.from(content)) {
 			const parsed = parseLine(line)