@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

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

@@ -2,26 +2,13 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   SQLite implementation of core's `StreetCentroidLookup` (#1042): the street-level tier BELOW the
- *   exact address-point tier and ABOVE admin-centroid resolution. Given a street name (no house
- *   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 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).
- *
- *   Scope order is most-selective first: `postcode`, then the base commune. Each scope WEIGHTED-
- *   aggregates (by `point_count`) across the matched rows in SQL, so a commune-scope probe returns the
- *   street's grand centroid over every postcode/arrondissement it spans — one row, one hit. Matching is
- *   exact-after-normalization only (no fuzzy street matching in this tier).
+ * @file SQLite implementation of core's `StreetCentroidLookup`.
  */
 
 import type { StreetCentroidHit, StreetCentroidLookup } from "@mailwoman/core/resolver"
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
 
 import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
 import type { StreetCentroidDatabase } from "#street/centroid/schema"
@@ -36,7 +23,8 @@ import {
 } from "#street/normalize"
 
 /**
- * The weighted-centroid + extent + provenance an aggregate probe projects. `lat` is null when nothing matched.
+ * The weighted centroid, extent and provenance an aggregate probe returns;
+ * `lat` is null when no row matched.
  */
 interface AggRow {
 	lat: number | null
@@ -50,7 +38,8 @@ interface AggRow {
 }
 
 /**
- * Weighted-centroid aggregate over a WHERE-filtered set. `SUM(coord*n)/SUM(n)` reconstructs the grand centroid.
+ * The aggregate columns that weight each row's centroid by `point_count` to
+ * reconstruct the combined centroid.
  */
 const AGG_SELECT =
 	"SUM(lat * point_count) / SUM(point_count) AS lat, " +
@@ -59,12 +48,16 @@ const AGG_SELECT =
 	"MAX(source) AS source, MAX(release) AS release"
 
 /**
- * Half the bbox diagonal, in METERS — an honest coarse radius for a street centroid.
+ * Half the bounding-box diagonal in meters, used as a coarse uncertainty radius for a street centroid.
  */
 function extentRadiusM(minLat: number, maxLat: number, minLon: number, maxLon: number): number {
 	return Math.round(haversineKm(minLat, minLon, maxLat, maxLon) * 500)
 }
 
+/**
+ * Finds a street's centroid and extent-based uncertainty by street name,
+ * scoped by postcode and then by base commune.
+ */
 export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 	readonly #db: DatabaseClient<StreetCentroidDatabase>
 	readonly #locale: StreetLocale
@@ -72,16 +65,14 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey], AggRow> | undefined
 
 	/**
-	 * @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).
+	 * The extract defaults to the `fr` street-normalization locale.
+	 * A mismatch with the extract's locale makes every key miss.
 	 */
-	constructor(dbPath: string, opts: { streetLocale?: StreetLocale } = {}) {
+	constructor(dbPath: PathBuilderLike, opts: { streetLocale?: StreetLocale } = {}) {
 		this.#db = new DatabaseClient<StreetCentroidDatabase>(dbPath, { readOnly: true })
 		this.#locale = opts.streetLocale ?? "fr"
 
-		// 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).
+		// An extract without a `street_centroid` table makes every lookup miss.
 		if (hasTable(this.#db, "street_centroid")) {
 			this.#byPostcode = prepareGet(
 				this.#db,
@@ -101,7 +92,7 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 
 		if (!streetNorm) return null
 
-		let row: AggRow | undefined
+		let row: AggRow | null = null
 
 		if (query.postcode?.trim()) {
 			row = this.#byPostcode(query.postcode.trim(), streetNorm)

package/lib/street/morphology/fst/builder.ts

@@ -5,13 +5,14 @@
  *
  *   Build a street-morphology FST from libpostal's street_types dictionaries. The morphology FST maps
  *   street-typing affixes (Street/Avenue/rue/Calle/Straße/...) to a single synthetic placetype
- *   `"street_affix"` — distinct from the admin FST in source data, intent, and binary artifact.
+ *   `"street_affix"`. Its source data and purpose differ from the admin FST.
+ *   It also produces a separate binary artifact.
  *
  *   The morphology FST closes the inference-time vacuum identified by the v0.6.1 postmortem: street
  *   tokens have no admin-FST anchor, so synth-street training pushed the model toward over-emitting
  *   `dependent_locality` on subcomponents. With the morphology FST, the neural decoder gets
  *   positive evidence for street-typing affixes and the adjacent name tokens, plus negative
- *   evidence away from `dependent_locality` on the same neighbours.
+ *   evidence away from `dependent_locality` on the same neighbors.
  *
  *   Design rationale + the four-layer street-supplement architecture lives in
  *   `docs/articles/concepts/street-supplement-architecture.md`.
@@ -23,8 +24,9 @@
  *   `fst-street-morphology.bin`.
  */
 
-import { isDirectory, readLocalTextFile, statPath } from "@mailwoman/core/fs/readers"
-import { join } from "path-ts"
+import { readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { isDirectory, isFile } from "@mailwoman/core/fs/readers/stat"
+import { PathBuilder, type PathBuilderLike } from "path-ts"
 import { TextSpliterator } from "spliterator"
 import { Globerator } from "spliterator/node/fs"
 
@@ -33,9 +35,11 @@ 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
- * allocation. Reusing the same base across rebuilds keeps IDs stable for any consumer that caches them. See
- * [[project-schema-storage-decision]] for the reserved range policy.
+ * Reserved synthetic wofID base for street-morphology entries. 32-bit unsigned,
+ * well above any realistic WOF allocation.
+ *
+ * The same base across rebuilds keeps IDs stable for consumers that cache them.
+ * See [[project-schema-storage-decision]] for the reserved range policy.
  */
 const STREET_AFFIX_WOFID_BASE = 1_900_000_000
 
@@ -45,19 +49,27 @@ export interface BuildStreetMorphologyFSTOpts {
 	/**
 	 * Path to the `core/data/libpostal/dictionaries` directory containing per-locale subfolders.
 	 */
-	dictionariesDir: string
+	dictionariesDir: PathBuilderLike
 	/**
-	 * Optional locale filter — only ingest these locale subfolders. Defaults to all that have a `street_types.txt`.
+	 * Optional locale filter — only ingest these locale subfolders.
+	 *
+	 * @defaultValue all that have a `street_types.txt`.
 	 */
 	locales?: string[]
 	/**
-	 * Minimum length (in characters, post-normalization) of variant surface forms to insert into the trie. Defaults to 3.
+	 * Minimum length (in characters, post-normalization) of variant surface forms to insert into the trie.
+	 *
+	 * Rationale: libpostal's street_types dictionaries contain 1-2 character abbreviations
+	 * (`a`, `b`, `av`, `bd`, `br`, ...) that collide with non-affix tokens at parse time,
+	 * including US state abbreviations (`or`, `CA`, `ND`, `NY`).
+	 * Single-letter unit designators and other short tokens also collide.
+	 *
+	 * Empirically these collisions push the morphology prior to mis-tag state
+	 * abbreviations as `street_suffix`.
+	 *
+	 * A minimum length of 3 retains useful forms (`ave`, `blvd`, `rue`, `str`) while filtering out the noise.
 	 *
-	 * Rationale: libpostal's street_types dictionaries contain 1-2 character abbreviations (`a`, `b`, `av`, `bd`, `br`,
-	 * ...) that collide with non-affix tokens at parse time — notably US state abbreviations (`OR`, `CA`, `ND`, `NY`),
-	 * single-letter unit designators, and arbitrary short tokens. Empirically these collisions push the morphology prior
-	 * to mis-tag state abbreviations as `street_suffix`. A minimum length of 3 retains useful forms (`ave`, `blvd`,
-	 * `rue`, `str`) while filtering out the noise.
+	 * @defaultValue `3`
 	 */
 	minVariantLength?: number
 	/**
@@ -76,20 +88,19 @@ export interface BuildStreetMorphologyFSTResult {
 }
 
 /**
- * Parse one `street_types.txt` line into `{ canonical, variants }`. Canonical is the first token (pre-`|`); variants
- * are all whitespace-stripped non-empty tokens including the canonical.
+ * Parse one `street_types.txt` line into `{ canonical, variants }`.
+ *
+ * Canonical is the first token (pre-`|`); variants are all whitespace-stripped
+ * non-empty tokens including the canonical.
  *
  * Lines with no `|` are treated as a single-form entry where canonical == variant.
  */
 function parseLine(line: string): { canonical: string; variants: string[] } | null {
 	const trimmed = line.trim()
 
-	if (!trimmed.length || trimmed.startsWith("#")) return null
+	if (!trimmed || trimmed.startsWith("#")) return null
 
-	const parts = trimmed
-		.split("|")
-		.map((s) => s.trim())
-		.filter((s) => s.length > 0)
+	const parts = TextSpliterator.from(trimmed, { delimiter: "|" }).toArray()
 
 	if (!parts.length) return null
 
@@ -101,6 +112,7 @@ export async function buildStreetMorphologyFST(
 ): Promise<BuildStreetMorphologyFSTResult> {
 	const progress = opts.onProgress ?? (() => {})
 	const minVariantLength = opts.minVariantLength ?? 3
+	const dictionariesDir = PathBuilder.from(opts.dictionariesDir)
 
 	// Discover locales — either provided explicitly, or all directories containing street_types.txt.
 	let locales: string[]
@@ -110,7 +122,7 @@ export async function buildStreetMorphologyFST(
 		locales = opts.locales
 	} else {
 		const entries = await Globerator.from("*", {
-			cwd: opts.dictionariesDir,
+			cwd: dictionariesDir,
 			absolute: false,
 			onlyFiles: false,
 		}).toArray()
@@ -118,7 +130,7 @@ export async function buildStreetMorphologyFST(
 		const localeProbes: Array<[string, boolean]> = []
 
 		for (const entry of entries) {
-			const localePath = join(opts.dictionariesDir, entry)
+			const localePath = dictionariesDir(entry)
 
 			if (!(await isDirectory(localePath))) {
 				localeProbes.push([entry, false])
@@ -126,13 +138,7 @@ export async function buildStreetMorphologyFST(
 				continue
 			}
 
-			try {
-				await statPath(join(localePath, STREET_TYPES_FILENAME))
-
-				localeProbes.push([entry, true])
-			} catch {
-				localeProbes.push([entry, false])
-			}
+			localeProbes.push([entry, await isFile(localePath(STREET_TYPES_FILENAME))])
 		}
 
 		locales = localeProbes.filter(([, hasFile]) => hasFile).map(([entry]) => entry)
@@ -140,12 +146,12 @@ export async function buildStreetMorphologyFST(
 
 	progress("discover", `Found ${locales.length} locales with ${STREET_TYPES_FILENAME}`)
 
-	// Collect canonical → set-of-variants across all locales. Same canonical form may appear in
-	// multiple locales (e.g. "avenue" in en/fr); we union the variant sets.
+	// Collect canonical → set-of-variants across all locales.
+	// Same canonical form may appear in multiple locales (e.g. "avenue" in en/fr); we union the variant sets.
 	const canonicalToVariants = new Map<string, Set<string>>()
 
 	for (const locale of locales) {
-		const filePath = join(opts.dictionariesDir, locale, STREET_TYPES_FILENAME)
+		const filePath = dictionariesDir(locale, STREET_TYPES_FILENAME)
 		const content = await readLocalTextFile(filePath)
 
 		for (const line of TextSpliterator.from(content)) {
@@ -164,7 +170,8 @@ export async function buildStreetMorphologyFST(
 
 	progress("collect", `Collected ${canonicalToVariants.size} canonical affixes`)
 
-	// Assign stable synthetic wofIDs. Sort canonicals for determinism.
+	// Assign stable synthetic wofIDs.
+	// Sort canonicals for determinism.
 	const sortedCanonicals = [...canonicalToVariants.keys()].toSorted()
 	const canonicalToWOFID = new Map<string, number>()
 
@@ -172,8 +179,9 @@ export async function buildStreetMorphologyFST(
 		canonicalToWOFID.set(sortedCanonicals[i]!, STREET_AFFIX_WOFID_BASE + i)
 	}
 
-	// Build the trie. Each variant is inserted as a token sequence pointing to its canonical's
-	// PlaceEntry — so all variants of "avenue" (av/ave/aven/...) lead to the same terminal entry.
+	// Build the trie.
+	// Each variant is inserted as a token sequence pointing to its canonical's PlaceEntry —
+	// so all variants of "avenue" (av/ave/aven/...) lead to the same terminal entry.
 	const nodes: FSTNode[] = [{ edges: new Map(), places: [] }]
 
 	function insertName(tokens: string[], entry: PlaceEntry): void {
@@ -212,13 +220,16 @@ export async function buildStreetMorphologyFST(
 			placetype: "street_affix",
 			name: canonical,
 			parentChain: [],
-			// Fixed referential score: street affixes are structurally unambiguous (Avenue is almost
-			// never anything but street-typing). The morphology prior caps bias separately; this value
-			// just feeds the cap formula `referential * cap`. No encyclopedic field — a street affix is
-			// not a place and has no article; absence here is the correct statement.
+			// Fixed referential score: street affixes are structurally unambiguous
+			// (Avenue is almost never anything but street-typing).
+			// The morphology prior caps bias separately.
+			// This value just feeds the cap formula `referential * cap`.
+			// No encyclopedic score — a street affix is not a place and has no article.
 			referential: 1,
+			encyclopedic: null,
 			lat: 0,
 			lon: 0,
+			crossCountryBranches: null,
 		}
 
 		for (const variant of variants) {
@@ -251,7 +262,14 @@ export async function buildStreetMorphologyFST(
 		edgeCount,
 		nameInsertions: insertCount,
 		importanceMatches: 0, // No importance scoring for morphology — fixed at 1.0.
-		sourceDB: opts.dictionariesDir,
+		encyclopedicMatches: null,
+		importanceSource: null,
+		sourceDB: dictionariesDir.toString(),
+		sourceDBMD5: null,
+		sourceDBBytes: null,
+		modelCardVersion: null,
+		exclusionPolicy: null,
+		excludedInsertions: null,
 	}
 
 	return {

package/lib/street/morphology/fst/loader.ts

@@ -3,57 +3,64 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Unified runtime loader for the street-morphology FST — the #1315 street-context check's signal
- *   source, previously rebuilt from the libpostal dictionaries per process at three duplicate call
- *   sites (runtime pipeline / parity eval / neural harness). The sealed artifact
- *   (`fst-street-morphology.bin`, built by `mailwoman gazetteer build street-morphology`) replaces
- *   those per-process builds; this loader is the ONE resolution ladder every node call site shares:
+ *   Runtime loader for the street-morphology FST. The sealed artifact
+ *   (`fst-street-morphology.bin`, built by `mailwoman gazetteer build street-morphology`) is the one
+ *   resolution ladder every node call site shares.
  *
- *   1. An explicit `artifactPath` (e.g. the weights-package sibling surfaced by
- *      `NeuralAddressClassifier.streetMorphologyPath`). When given, it is the only artifact probed.
- *   2. Otherwise the staged sealed artifact at `$MAILWOMAN_DATA_ROOT/wof/fst-street-morphology.bin`.
- *   3. Build-from-dictionaries fallback: `buildStreetMorphologyFST` over core's bundled libpostal
- *      `street_types.txt` files — the pre-artifact behavior, kept so a missing artifact degrades to
- *      a per-process build rather than a crash.
+ *   1. An explicit `artifactPath`, e.g. the weights-package sibling surfaced by
+ *      `NeuralAddressClassifier.streetMorphologyPath`. When given, it is the only artifact probed.
+ *   2. Otherwise the staged sealed artifact at `$MAILWOMAN_DATA_ROOT/db/wof/fst-street-morphology.bin`.
+ *   3. A build-from-dictionaries fallback: `buildStreetMorphologyFST` over core's bundled libpostal
+ *      `street_types.txt` files, kept so a missing artifact degrades to a per-process build instead
+ *      of a crash.
  *
  *   A present-but-unreadable artifact reports through `onWarn` and falls through to the build rung.
- *   Browsers can't take the fallback (no fs) — they deserialize the same artifact via
- *   `fst-deserialize-web.ts` (see the docs demo loader).
+ *   Browsers cannot take the fallback because they have no filesystem API. They deserialize the same
+ *   artifact through `fst-deserialize-web.ts` (see the docs demo loader).
  */
 
-import { dataRootPath } from "@mailwoman/core/data-root"
-import { pathExists, readLocalBuffer } from "@mailwoman/core/fs/readers"
+import { readLocalBuffer } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { resourceDictionaryPath } from "@mailwoman/core/paths"
+import type { PathBuilder, PathBuilderLike } from "path-ts"
 
 import type { FSTMatcher } from "#fst/matcher"
 import { deserializeFST, readFSTProvenance } from "#fst/serialize"
 import type { FSTProvenance } from "#fst/types"
+import { wofDatabasePath } from "#paths"
 import { buildStreetMorphologyFST } from "#street/morphology/fst/builder"
 
 /**
- * The sealed artifact's canonical filename — identical in the data-root staging dir and as a weights-package sibling.
+ * The sealed artifact's canonical filename, identical in the data-root staging dir
+ * and as a weights-package sibling.
  */
 export const STREET_MORPHOLOGY_ARTIFACT_FILENAME = "fst-street-morphology.bin"
 
 /**
- * The staged artifact's default location: `$MAILWOMAN_DATA_ROOT/wof/fst-street-morphology.bin`.
+ * The staged artifact's default location: `$MAILWOMAN_DATA_ROOT/db/wof/fst-street-morphology.bin`.
  */
-export function defaultStreetMorphologyArtifactPath(): string {
-	return String(dataRootPath("wof", STREET_MORPHOLOGY_ARTIFACT_FILENAME))
+export function defaultStreetMorphologyArtifactPath(): PathBuilder {
+	return wofDatabasePath(STREET_MORPHOLOGY_ARTIFACT_FILENAME)
 }
 
 export interface LoadStreetMorphologyFSTOpts {
 	/**
-	 * Explicit artifact path (e.g. a weights-package sibling). When given it is the ONLY artifact probed — missing or
-	 * unreadable degrades straight to the dictionary build, never a throw.
+	 * Explicit artifact path (e.g. A weights-package sibling).
+	 *
+	 * When given, it is the only artifact probed.
+	 * A missing or unreadable artifact degrades straight to the dictionary build, never a throw.
 	 */
-	artifactPath?: string
+	artifactPath?: PathBuilderLike
 	/**
-	 * Dictionaries dir for the build fallback. Defaults to core's bundled libpostal dictionaries.
+	 * Dictionaries dir for the build fallback.
+	 *
+	 * @defaultValue core's bundled libpostal dictionaries.
 	 */
-	dictionariesDir?: string
+	dictionariesDir?: PathBuilderLike
 	/**
-	 * Unreadable-artifact diagnostics. Defaults to silent (the caller owns its warn channel).
+	 * Unreadable-artifact diagnostics.
+	 *
+	 * @defaultValue silent (the caller owns its warn channel).
 	 */
 	onWarn?: (message: string) => void
 }
@@ -67,15 +74,16 @@ export interface LoadedStreetMorphologyFST {
 	/**
 	 * The artifact path when `source === "artifact"`.
 	 */
-	path?: string
+	path: PathBuilderLike | null
 	/**
-	 * Build provenance — read from the artifact trailer, or carried fresh off the fallback build.
+	 * Build provenance, read from the artifact trailer or copied from the fallback build.
 	 */
-	provenance?: FSTProvenance
+	provenance: FSTProvenance | null
 }
 
 /**
- * Load the street-morphology matcher: sealed artifact first, per-process dictionary build as the degrade path.
+ * Load the street-morphology matcher: sealed artifact first, per-process
+ * dictionary build as the degrade path.
  */
 export async function loadStreetMorphologyFST(
 	opts: LoadStreetMorphologyFSTOpts = {}
@@ -89,7 +97,7 @@ export async function loadStreetMorphologyFST(
 			const matcher = deserializeFST(buf)
 			const provenance = readFSTProvenance(buf)
 
-			return { matcher, source: "artifact", path: artifactPath, ...(provenance ? { provenance } : {}) }
+			return { matcher, source: "artifact", path: artifactPath, provenance }
 		} catch (error) {
 			warn(
 				`street-morphology artifact at ${artifactPath} unreadable (${(error as Error).message}) — falling back to the dictionary build`
@@ -98,8 +106,8 @@ export async function loadStreetMorphologyFST(
 	}
 
 	const built = await buildStreetMorphologyFST({
-		dictionariesDir: opts.dictionariesDir ?? resourceDictionaryPath("libpostal"),
+		dictionariesDir: (opts.dictionariesDir ?? resourceDictionaryPath("libpostal")).toString(),
 	})
 
-	return { matcher: built.matcher, source: "built", provenance: built.provenance }
+	return { matcher: built.matcher, source: "built", path: null, provenance: built.provenance }
 }

package/lib/street/name-lookup.ts

@@ -3,68 +3,79 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   #727 stage-2 phase 4c — the SQLite backend for {@link StreetLocalityEvidence}.
+ *   The SQLite backend for {@link StreetLocalityEvidence}.
  *
- *   Reads a street-name index (the FR instance = BAN `street-centroids-fr.db`, a `street_centroid`
+ *   Reads a street-name index (the FR instance is BAN `street-centroids-fr.db`, a `street_centroid`
  *   table of `street_norm × locality_base × postcode` rows) and answers "does this street surface
- *   exist as a name" for the k-best rerank. Sync-by-interface, `readOnly`, prepared statements,
- *   graceful-degrade on a tableless extract — the same reader discipline as `AddressPointSqliteLookup`.
+ *   exist as a name" for the k-best rerank. It is sync-by-interface and read-only, uses prepared
+ *   statements. It also degrades gracefully on a tableless extract, following the same reader discipline as
+ *   `AddressPointSqliteLookup`.
  *
- *   THE FOLD CONTRACT: the surface is folded with {@link foldStreetSurface} (the shared function),
- *   and the DB's `street_norm` column MUST have been built with that SAME fold or every hyphenated /
- *   apostrophe'd street silently misses. The current `street-centroids-fr.db` predates the contract
- *   fold (it folded without hyphen/apostrophe normalization); it must be REBUILT with
- *   `foldStreetSurface` + a `street_norm` index before this backend is wired in production. Until
- *   then this class is correct-by-construction against a fixture built with the contract fold, and
- *   the production rebuild is a tracked BAN-sdk follow-up.
+ *   The fold interface: the surface is folded with {@link foldStreetSurface} (the shared function),
+ *   so the DB's `street_norm` column must have been built with that same fold or every hyphenated
+ *   or apostrophe'd street silently misses. The column also needs a `street_norm` index before this
+ *   backend is wired in production.
  */
 
 import { foldStreetSurface, type StreetEvidenceScope, type StreetLocalityEvidence } from "@mailwoman/resolver"
-import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { SQLiteLookup } from "@mailwoman/sqlite/lookup"
+import type { PathBuilderLike } from "path-ts"
 
 import type { WOFDatabase } from "#schema"
 import { hasColumn, hasTable } from "#sqlite-utils"
 
 export interface SQLiteStreetNameLookupOpts {
 	/**
-	 * ISO-2 (upper-case) countries this index answers for. Default `["FR"]` (the BAN street-centroids instance).
+	 * ISO-2 (upper-case) countries this index answers for.
+	 *
+	 * @defaultValue `["FR"]` (the BAN street-centroids instance).
 	 */
 	countries?: Iterable<string>
 	/**
-	 * Table name. Default `street_centroid`.
+	 * Table name.
+	 *
+	 * @defaultValue `street_centroid`
 	 */
 	table?: string
 }
 
 /**
- * A {@link StreetLocalityEvidence} backed by a street-name SQLite index. Positive evidence only: any doubt (missing
- * table, read miss) returns `false`, so the rerank fails open to the model's ranking.
+ * A {@link StreetLocalityEvidence} backed by a street-name SQLite index.
+ *
+ * Positive evidence only: any doubt (missing table, read miss) returns `false`,
+ * so the rerank fails open to the model's ranking.
  */
-export class SQLiteStreetNameLookup implements StreetLocalityEvidence, Disposable {
+export class SQLiteStreetNameLookup extends SQLiteLookup<WOFDatabase> implements StreetLocalityEvidence {
 	readonly countries: ReadonlySet<string>
-	readonly #db: DatabaseClient<WOFDatabase>
 	readonly #byName: ReturnType<DatabaseClient["prepare"]> | undefined
 	readonly #byNameLocality: ReturnType<DatabaseClient["prepare"]> | undefined
 	readonly #byNamePostcode: ReturnType<DatabaseClient["prepare"]> | undefined
 
-	constructor(dbPath: string, opts: SQLiteStreetNameLookupOpts = {}) {
+	constructor(dbPath: PathBuilderLike, opts: SQLiteStreetNameLookupOpts = {}) {
+		super({ databasePath: dbPath })
 		this.countries = new Set([...(opts.countries ?? ["FR"])].map((c) => c.toUpperCase()))
-		this.#db = new DatabaseClient<WOFDatabase>(dbPath, { readOnly: true })
 		const table = opts.table ?? "street_centroid"
 
-		// Degrade gracefully on an empty/tableless extract — a no-op miss, never a crash (#568 discipline).
-		if (hasTable(this.#db, table)) {
-			// Prefer the #727 phase-4c `name_key` column (foldStreetSurface, indexed by `idx_sc_name` for a direct seek);
-			// fall back to `street_norm` on a pre-rebuild extract (a skip-scan, but correct). The fold used to build
-			// `name_key` MUST match `foldStreetSurface` here (the fold-parity contract).
-			const keyCol = hasColumn(this.#db, table, "name_key") ? "name_key" : "street_norm"
-			this.#byName = this.#db.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? LIMIT 1`)
+		// Degrade gracefully on an empty or tableless extract.
+		// A no-op miss, never a crash.
+		if (hasTable(this.database, table)) {
+			// Prefer the `name_key` column (built with `foldStreetSurface`
+			// and indexed by `idx_sc_name` for a direct seek).
+			// On a pre-rebuild extract, `street_norm` is a correct fallback.
+			// It uses a skip-scan.
+			// The fold that built `name_key` must match `foldStreetSurface` here.
+			// This is the fold-parity interface.
+			const keyCol = hasColumn(this.database, table, "name_key") ? "name_key" : "street_norm"
+			this.#byName = this.database.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? LIMIT 1`)
 
-			this.#byNameLocality = this.#db.prepare(
+			this.#byNameLocality = this.database.prepare(
 				`SELECT 1 FROM ${table} WHERE ${keyCol} = ? AND locality_base = ? LIMIT 1`
 			)
 
-			this.#byNamePostcode = this.#db.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? AND postcode = ? LIMIT 1`)
+			this.#byNamePostcode = this.database.prepare(
+				`SELECT 1 FROM ${table} WHERE ${keyCol} = ? AND postcode = ? LIMIT 1`
+			)
 		}
 	}
 
@@ -74,24 +85,17 @@ export class SQLiteStreetNameLookup implements StreetLocalityEvidence, Disposabl
 
 		if (!norm) return false
 
-		// Scoped lookups tighten precision when the hypothesis carries a locality/postcode; a scoped MISS falls back to the
-		// unscoped probe (index incompleteness in the scope column is not evidence of absence — positive-evidence rule).
-		if (
-			scope?.locality &&
-			this.#byNameLocality &&
-			this.#byNameLocality.get(norm, foldStreetSurface(scope.locality)) !== undefined
-		) {
+		// Scoped lookups tighten precision when the hypothesis includes a locality/postcode.
+		// A scoped miss falls back to the unscoped probe.
+		// The scope column may be incomplete, so a miss there does not establish absence.
+		if (scope?.locality && this.#byNameLocality && this.#byNameLocality.get(norm, foldStreetSurface(scope.locality))) {
 			return true
 		}
 
-		if (scope?.postcode && this.#byNamePostcode && this.#byNamePostcode.get(norm, scope.postcode) !== undefined) {
+		if (scope?.postcode && this.#byNamePostcode && this.#byNamePostcode.get(norm, scope.postcode)) {
 			return true
 		}
 
 		return this.#byName.get(norm) !== undefined
 	}
-
-	[Symbol.dispose](): void {
-		this.#db[Symbol.dispose]()
-	}
 }