@mailwoman/resolver-wof-sqlite 8.0.0 → 8.2.0

package/reverse.ts

@@ -35,6 +35,16 @@ import { PLACE_BBOX_TABLE } from "./fts.ts"
 import { geometryContains, haversineKm, type GeojsonGeometry } from "./geo.ts"
 import type { PlaceCandidate, WOFPlacetype } from "./types.ts"
 
+/**
+ * Largest absolute latitude in WGS-84 degrees.
+ */
+const MAX_ABS_LATITUDE = 90
+
+/**
+ * Largest absolute longitude in WGS-84 degrees.
+ */
+const MAX_ABS_LONGITUDE = 180
+
 /**
  * How the deepest returned place was confirmed:
  *
@@ -52,7 +62,9 @@ export interface ReverseGeocodeResult {
 	 * ocean, or outside the gazetteer's coverage).
 	 */
 	hierarchy: PlaceCandidate[]
-	/** Containment kind of the DEEPEST place in `hierarchy` (see {@link ContainmentKind}). */
+	/**
+	 * Containment kind of the DEEPEST place in `hierarchy` (see {@link ContainmentKind}).
+	 */
 	containment: ContainmentKind
 }
 
@@ -62,14 +74,18 @@ export interface WOFReverseGeocoderOpts {
 	 * package-built `place_bbox` R*Tree (`mailwoman gazetteer build fts`). Mutually exclusive with `adminDatabase`.
 	 */
 	adminDBPath?: string
-	/** Pre-opened admin DB — primarily for tests against an inline fixture. */
+	/**
+	 * Pre-opened admin DB — primarily for tests against an inline fixture.
+	 */
 	adminDatabase?: DatabaseSync
 	/**
 	 * Path to the polygon sidecar DB (`wof-polygons.db`, table `polygons(id, geom)`). OPTIONAL — without it every result
 	 * is `containment: "approximate"` (centroid-only mode). Mutually exclusive with `polygonDatabase`.
 	 */
 	polygonDBPath?: string
-	/** Pre-opened polygon DB — primarily for tests. */
+	/**
+	 * Pre-opened polygon DB — primarily for tests.
+	 */
 	polygonDatabase?: DatabaseSync
 }
 
@@ -108,7 +124,9 @@ const DESCENT_TIERS: readonly WOFPlacetype[] = [
 	"microhood",
 ]
 
-/** Internal candidate row off `spr` (+ optional bbox area / centroid distance bookkeeping). */
+/**
+ * Internal candidate row off `spr` (+ optional bbox area / centroid distance bookkeeping).
+ */
 interface CandidateRow {
 	id: number
 	name: string
@@ -167,8 +185,10 @@ export class WOFReverseGeocoder implements Disposable {
 
 		this.#admin = opts.adminDatabase ?? new DatabaseSync(opts.adminDBPath!, { readOnly: true })
 		this.#ownsAdmin = !opts.adminDatabase
+
 		this.#polygons =
 			opts.polygonDatabase ?? (opts.polygonDBPath ? new DatabaseSync(opts.polygonDBPath, { readOnly: true }) : null)
+
 		this.#ownsPolygons = !opts.polygonDatabase && Boolean(opts.polygonDBPath)
 
 		// Fail loudly up front — the R*Tree is a build artifact, not part of the upstream WOF
@@ -213,9 +233,15 @@ export class WOFReverseGeocoder implements Disposable {
 	 * whose `POIIntentOutcome` return type is synchronous by contract — see `poi-intent.ts`'s `deps.execute`).
 	 */
 	reverseGeocodeSync(lat: number, lon: number, opts: ReverseGeocodeOpts = {}): ReverseGeocodeResult {
-		if (!Number.isFinite(lat) || !Number.isFinite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180) {
+		if (
+			!Number.isFinite(lat) ||
+			!Number.isFinite(lon) ||
+			Math.abs(lat) > MAX_ABS_LATITUDE ||
+			Math.abs(lon) > MAX_ABS_LONGITUDE
+		) {
 			throw new RangeError(`WOFReverseGeocoder.reverseGeocode: (${lat}, ${lon}) is not a WGS-84 coordinate`)
 		}
+
 		const maxApproximateKm = opts.maxApproximateKm ?? DEFAULT_MAX_APPROXIMATE_KM
 		const candidates = this.#bboxCandidates(lat, lon, opts)
 
@@ -231,6 +257,7 @@ export class WOFReverseGeocoder implements Disposable {
 			if (contains === true) {
 				winner = c
 				winnerConfirmed = true
+
 				break
 			}
 
@@ -277,6 +304,7 @@ export class WOFReverseGeocoder implements Disposable {
 					next = k
 					nextConfirmed = true
 					nextKm = undefined
+
 					break
 				}
 
@@ -302,8 +330,7 @@ export class WOFReverseGeocoder implements Disposable {
 		// Hierarchy assembly via the shared ancestor walk. If the descent crossed an ancestry gap
 		// (the deepest place's recorded lineage misses the PIP root), merge the root's own chain so
 		// region/country are always present when a polygon confirmed them.
-		const byID = new Map<number, PlaceCandidate>()
-		byID.set(current.id, toPlaceCandidate(current, currentDistanceKm))
+		const byID = new Map<number, PlaceCandidate>([[current.id, toPlaceCandidate(current, currentDistanceKm)]])
 
 		for (const a of ancestorLineage(this.#admin, current.id)) {
 			if (!byID.has(a.id)) {
@@ -320,6 +347,7 @@ export class WOFReverseGeocoder implements Disposable {
 				}
 			}
 		}
+
 		const hierarchy = [...byID.values()]
 
 		if (opts.placetypes) {
@@ -331,12 +359,15 @@ export class WOFReverseGeocoder implements Disposable {
 				}
 			}
 		}
+
 		hierarchy.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype))
 
 		return { hierarchy, containment: currentConfirmed ? "polygon" : "approximate" }
 	}
 
-	/** Bbox candidates containing the point, smallest-area-first, via the `place_bbox` R*Tree. */
+	/**
+	 * Bbox candidates containing the point, smallest-area-first, via the `place_bbox` R*Tree.
+	 */
 	#bboxCandidates(lat: number, lon: number, opts: ReverseGeocodeOpts): CandidateRow[] {
 		const where: string[] = [
 			"bbox.min_lat <= ?",
@@ -346,12 +377,14 @@ export class WOFReverseGeocoder implements Disposable {
 			"spr.is_current != 0",
 			"spr.is_deprecated = 0",
 		]
+
 		const params: Array<number | string> = [lat, lat, lon, lon]
 
-		if (opts.placetypes && opts.placetypes.length > 0) {
+		if (opts.placetypes && opts.placetypes.length) {
 			where.push(`spr.placetype IN (${opts.placetypes.map(() => "?").join(", ")})`)
 			params.push(...opts.placetypes)
 		}
+
 		params.push(opts.maxCandidates ?? DEFAULT_MAX_CANDIDATES)
 
 		return this.#admin
@@ -398,7 +431,9 @@ export class WOFReverseGeocoder implements Disposable {
 			) as unknown as CandidateRow[]
 	}
 
-	/** Parsed GeoJSON geometry for a WOF id, or null when absent / unparseable / no polygon DB. */
+	/**
+	 * Parsed GeoJSON geometry for a WOF id, or null when absent / unparseable / no polygon DB.
+	 */
 	#geometry(id: number): GeojsonGeometry | null {
 		if (!this.#polygons) return null
 		const cached = this.#geometryCache.get(id)
@@ -408,6 +443,7 @@ export class WOFReverseGeocoder implements Disposable {
 		if (this.#geometryCache.size >= WOFReverseGeocoder.#GEOMETRY_CACHE_CAP) {
 			this.#geometryCache.clear()
 		}
+
 		const row = this.#polygons.prepare(`SELECT geom FROM polygons WHERE id = ?`).get(id) as { geom: string } | undefined
 		let geometry: GeojsonGeometry | null = null
 
@@ -418,6 +454,7 @@ export class WOFReverseGeocoder implements Disposable {
 				geometry = null // malformed row — treat as no-polygon rather than failing the query
 			}
 		}
+
 		this.#geometryCache.set(id, geometry)
 
 		return geometry

package/sharding.ts

@@ -47,7 +47,7 @@ export function deriveSchemaName(path: string): string {
 		.replace(/^whosonfirst-data-/u, "")
 		.replace(/-latest\.db$/u, "")
 		.replace(/\.db$/u, "")
-		.replace(/[^a-zA-Z0-9_]/g, "_")
+		.replaceAll(/[^a-zA-Z0-9_]/g, "_")
 
 	if (!stem) {
 		throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`)
@@ -86,7 +86,9 @@ export interface ResolvedShard {
 	placetypes: readonly string[]
 }
 
-/** SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`. */
+/**
+ * SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`.
+ */
 const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
 
 /**
@@ -99,7 +101,7 @@ const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
 export function resolveShards(input: string | ReadonlyArray<string | ShardConfig>): ResolvedShard[] {
 	const list = typeof input === "string" ? [input] : input
 
-	if (list.length === 0) throw new Error("resolveShards: at least one shard is required")
+	if (!list.length) throw new Error("resolveShards: at least one shard is required")
 
 	const seen = new Set<string>()
 	const out: ResolvedShard[] = []
@@ -116,6 +118,7 @@ export function resolveShards(input: string | ReadonlyArray<string | ShardConfig
 					`{ path, schemaName } to override.`
 			)
 		}
+
 		// The first shard is always main per SQLite semantics — its derived name is informational
 		// only. Subsequent shards must have unique non-main names.
 		const schemaName = i === 0 ? "main" : derived
@@ -126,7 +129,9 @@ export function resolveShards(input: string | ReadonlyArray<string | ShardConfig
 					`(either with "main" or another shard). Pass an explicit { path, schemaName }.`
 			)
 		}
+
 		seen.add(schemaName)
+
 		out.push({
 			path: cfg.path,
 			schemaName,
@@ -179,7 +184,7 @@ export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: strin
 		}
 	}
 
-	return matches.length > 0 ? matches : [shards[0]!]
+	return matches.length ? matches : [shards[0]!]
 }
 
 export function pickShardForPlacetype(
@@ -194,7 +199,9 @@ export function pickShardForPlacetype(
 		 * order remains the tiebreak when no shard claims the country (or none was probed).
 		 */
 		country?: string
-		/** Per-schema probed country sets (see `WOFSqlitePlaceLookup`'s construction probe). */
+		/**
+		 * Per-schema probed country sets (see `WOFSqlitePlaceLookup`'s construction probe).
+		 */
 		countriesBySchema?: ReadonlyMap<string, ReadonlySet<string>>
 	}
 ): ResolvedShard {
@@ -223,7 +230,7 @@ export function pickShardForPlacetype(
 		}
 	}
 
-	if (matches.length === 0) return shards[0]!
+	if (!matches.length) return shards[0]!
 
 	if (opts?.country && opts.countriesBySchema) {
 		for (const s of matches) {

package/sqlite-convention-source.ts

@@ -22,7 +22,9 @@ import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from
 export class SqliteConventionSource implements ConventionSource {
 	readonly #db: DatabaseSync
 	readonly #schema: string
-	/** Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once. */
+	/**
+	 * Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once.
+	 */
 	readonly #cache = new Map<number, Convention | null>()
 
 	/**
@@ -54,6 +56,7 @@ export class SqliteConventionSource implements ConventionSource {
 			// WORLD_DEFAULT). The build script validates structure, so this is purely defensive.
 			value = null
 		}
+
 		this.#cache.set(wofID, value)
 
 		return value ?? undefined

package/street-centroid-schema.ts

@@ -29,27 +29,45 @@ import type { Kysely } from "kysely"
  * bbox diagonal into an honest `uncertainty_m`).
  */
 export interface StreetCentroidTable {
-	/** Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key. */
+	/**
+	 * Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key.
+	 */
 	street_norm: string
-	/** The 5-digit postcode of this group, or null when the source row carried none. */
+	/**
+	 * The 5-digit postcode of this group, or null when the source row carried none.
+	 */
 	postcode: string | null
-	/** Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope. */
+	/**
+	 * Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope.
+	 */
 	locality_base: string
-	/** Weighted-mean centroid latitude of the street's member points. */
+	/**
+	 * Weighted-mean centroid latitude of the street's member points.
+	 */
 	lat: number
-	/** Weighted-mean centroid longitude of the street's member points. */
+	/**
+	 * Weighted-mean centroid longitude of the street's member points.
+	 */
 	lon: number
 	min_lat: number
 	max_lat: number
 	min_lon: number
 	max_lon: number
-	/** Member address-point count — the weight for a cross-group centroid aggregate. */
+	/**
+	 * Member address-point count — the weight for a cross-group centroid aggregate.
+	 */
 	point_count: number
-	/** A representative street name as it appeared in the source (display / debugging). */
+	/**
+	 * A representative street name as it appeared in the source (display / debugging).
+	 */
 	street_raw: string
-	/** Provenance: the register this street was derived from (e.g. `ban:fr`). */
+	/**
+	 * Provenance: the register this street was derived from (e.g. `ban:fr`).
+	 */
 	source: string
-	/** The pinned data release the underlying points came from. */
+	/**
+	 * The pinned data release the underlying points came from.
+	 */
 	release: string
 	/**
 	 * #727 phase-4c: `foldStreetSurface(street_raw)` — the contract-fold street-NAME existence key for
@@ -61,7 +79,9 @@ export interface StreetCentroidTable {
 	name_key: string
 }
 
-/** The street-centroid database schema for `new DatabaseClient<StreetCentroidDatabase>(...)`. */
+/**
+ * The street-centroid database schema for `new DatabaseClient<StreetCentroidDatabase>(...)`.
+ */
 export interface StreetCentroidDatabase {
 	street_centroid: StreetCentroidTable
 }
@@ -87,7 +107,9 @@ export const STREET_CENTROID_COLUMNS = [
 	"name_key",
 ] as const
 
-/** Create the `street_centroid` table — called before the streaming bulk load. */
+/**
+ * Create the `street_centroid` table — called before the streaming bulk load.
+ */
 export async function createStreetCentroidTable(db: Kysely<StreetCentroidDatabase>): Promise<void> {
 	await db.schema
 		.createTable("street_centroid")
@@ -115,10 +137,12 @@ export async function createStreetCentroidTable(db: Kysely<StreetCentroidDatabas
  */
 export async function createStreetCentroidIndexes(db: Kysely<StreetCentroidDatabase>): Promise<void> {
 	await db.schema.createIndex("idx_sc_postcode").on("street_centroid").columns(["postcode", "street_norm"]).execute()
+
 	await db.schema
 		.createIndex("idx_sc_locality")
 		.on("street_centroid")
 		.columns(["locality_base", "street_norm"])
 		.execute()
+
 	await db.schema.createIndex("idx_sc_name").on("street_centroid").columns(["name_key"]).execute()
 }

package/street-centroid.ts

@@ -31,7 +31,9 @@ import {
 	stripArrondissement,
 } from "./street-normalize.ts"
 
-/** The weighted-centroid + extent + provenance an aggregate probe projects. `lat` is null when nothing matched. */
+/**
+ * The weighted-centroid + extent + provenance an aggregate probe projects. `lat` is null when nothing matched.
+ */
 interface AggRow {
 	lat: number | null
 	lon: number | null
@@ -43,14 +45,18 @@ interface AggRow {
 	release: string | null
 }
 
-/** Weighted-centroid aggregate over a WHERE-filtered set. `SUM(coord*n)/SUM(n)` reconstructs the grand centroid. */
+/**
+ * Weighted-centroid aggregate over a WHERE-filtered set. `SUM(coord*n)/SUM(n)` reconstructs the grand centroid.
+ */
 const AGG_SELECT =
 	"SUM(lat * point_count) / SUM(point_count) AS lat, " +
 	"SUM(lon * point_count) / SUM(point_count) AS lon, " +
 	"MIN(min_lat) AS min_lat, MAX(max_lat) AS max_lat, MIN(min_lon) AS min_lon, MAX(max_lon) AS max_lon, " +
 	"MAX(source) AS source, MAX(release) AS release"
 
-/** Half the bbox diagonal, in METERS — an honest coarse radius for a street centroid. */
+/**
+ * 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
@@ -84,6 +90,7 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 			this.#byPostcode = this.#db.prepare(
 				`SELECT ${AGG_SELECT} FROM street_centroid WHERE postcode = ? AND street_norm = ?`
 			)
+
 			this.#byLocality = this.#db.prepare(
 				`SELECT ${AGG_SELECT} FROM street_centroid WHERE locality_base = ? AND street_norm = ?`
 			)

package/street-morphology-fst-builder.ts

@@ -40,7 +40,9 @@ const STREET_AFFIX_WOFID_BASE = 1_900_000_000
 const STREET_TYPES_FILENAME = "street_types.txt"
 
 export interface BuildStreetMorphologyFSTOpts {
-	/** Path to the `core/data/libpostal/dictionaries` directory containing per-locale subfolders. */
+	/**
+	 * Path to the `core/data/libpostal/dictionaries` directory containing per-locale subfolders.
+	 */
 	dictionariesDir: string
 	/**
 	 * Optional locale filter — only ingest these locale subfolders. Defaults to all that have a `street_types.txt`.
@@ -56,7 +58,9 @@ export interface BuildStreetMorphologyFSTOpts {
 	 * `rue`, `str`) while filtering out the noise.
 	 */
 	minVariantLength?: number
-	/** Optional progress callback. */
+	/**
+	 * Optional progress callback.
+	 */
 	onProgress?: (phase: string, detail?: string) => void
 }
 
@@ -78,13 +82,14 @@ export interface BuildStreetMorphologyFSTResult {
 function parseLine(line: string): { canonical: string; variants: string[] } | null {
 	const trimmed = line.trim()
 
-	if (trimmed.length === 0 || trimmed.startsWith("#")) return null
+	if (!trimmed.length || trimmed.startsWith("#")) return null
+
 	const parts = trimmed
 		.split("|")
 		.map((s) => s.trim())
 		.filter((s) => s.length > 0)
 
-	if (parts.length === 0) return null
+	if (!parts.length) return null
 
 	return { canonical: parts[0]!, variants: parts }
 }
@@ -96,7 +101,8 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 	// Discover locales — either provided explicitly, or all directories containing street_types.txt.
 	let locales: string[]
 
-	if (opts.locales && opts.locales.length > 0) {
+	// oxlint-disable-next-line unicorn/prefer-ternary -- the else branch is a multi-line directory scan
+	if (opts.locales && opts.locales.length) {
 		locales = opts.locales
 	} else {
 		locales = readdirSync(opts.dictionariesDir).filter((entry) => {
@@ -113,6 +119,7 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 			}
 		})
 	}
+
 	progress("discover", `Found ${locales.length} locales with ${STREET_TYPES_FILENAME}`)
 
 	// Collect canonical → set-of-variants across all locales. Same canonical form may appear in
@@ -132,13 +139,15 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 			for (const variant of parsed.variants) {
 				existing.add(variant)
 			}
+
 			canonicalToVariants.set(parsed.canonical, existing)
 		}
 	}
+
 	progress("collect", `Collected ${canonicalToVariants.size} canonical affixes`)
 
 	// Assign stable synthetic wofIDs. Sort canonicals for determinism.
-	const sortedCanonicals = [...canonicalToVariants.keys()].sort()
+	const sortedCanonicals = [...canonicalToVariants.keys()].toSorted()
 	const canonicalToWOFID = new Map<string, number>()
 
 	for (let i = 0; i < sortedCanonicals.length; i++) {
@@ -150,7 +159,7 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 	const nodes: FSTNode[] = [{ edges: new Map(), places: [] }]
 
 	function insertName(tokens: string[], entry: PlaceEntry): void {
-		if (tokens.length === 0) return
+		if (!tokens.length) return
 		let stateID = 0
 
 		for (const t of tokens) {
@@ -162,8 +171,10 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 				nodes.push({ edges: new Map(), places: [] })
 				node.edges.set(t, next)
 			}
+
 			stateID = next
 		}
+
 		const existing = nodes[stateID]!.places
 
 		if (!existing.some((p) => p.wofID === entry.wofID && p.placetype === entry.placetype)) {
@@ -177,6 +188,7 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 	for (const canonical of sortedCanonicals) {
 		const variants = canonicalToVariants.get(canonical)!
 		const wofID = canonicalToWOFID.get(canonical)!
+
 		const entry: PlaceEntry = {
 			wofID,
 			placetype: "street_affix",
@@ -185,7 +197,7 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 			// Fixed importance: 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 `importance * cap`.
-			importance: 1.0,
+			importance: 1,
 			lat: 0,
 			lon: 0,
 		}
@@ -193,21 +205,25 @@ export function buildStreetMorphologyFST(opts: BuildStreetMorphologyFSTOpts): Bu
 		for (const variant of variants) {
 			const tokens = normalizeTokens(variant)
 
-			if (tokens.length === 0) continue
+			if (!tokens.length) continue
 			// Filter out collision-prone short surface forms — see `minVariantLength` docstring.
 			// We measure against the joined token form (no spaces) since FST keys are token sequences.
 			const joined = tokens.join("")
 
 			if (joined.length < minVariantLength) continue
 			insertName(tokens, entry)
+
 			insertCount++
+
 			variantCount++
 		}
 	}
+
 	progress("trie", `Built trie: ${nodes.length} states, ${insertCount} variant insertions`)
 
 	const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0)
 	const matcher = FSTMatcher.fromNodes(nodes)
+
 	const provenance: FSTProvenance = {
 		builtAt: new Date().toISOString(),
 		countries: locales, // Reuse `countries` slot for locale provenance — semantics differ from admin FST.

package/street-morphology-fst-loader.ts

@@ -0,0 +1,103 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Unified runtime loader for the street-morphology FST — the #1315 street-context gate'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:
+ *
+ *   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.
+ *
+ *   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).
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+
+import { dataRootPath, resourceDictionaryPath } from "@mailwoman/core/utils"
+
+import type { FSTMatcher } from "./fst-matcher.ts"
+import { deserializeFST, readFSTProvenance } from "./fst-serialize.ts"
+import type { FSTProvenance } from "./fst-types.ts"
+import { buildStreetMorphologyFST } from "./street-morphology-fst-builder.ts"
+
+/**
+ * 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`.
+ */
+export function defaultStreetMorphologyArtifactPath(): string {
+	return String(dataRootPath("wof", 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.
+	 */
+	artifactPath?: string
+	/**
+	 * Dictionaries dir for the build fallback. Defaults to core's bundled libpostal dictionaries.
+	 */
+	dictionariesDir?: string
+	/**
+	 * Unreadable-artifact diagnostics. Defaults to silent (the caller owns its warn channel).
+	 */
+	onWarn?: (message: string) => void
+}
+
+export interface LoadedStreetMorphologyFST {
+	matcher: FSTMatcher
+	/**
+	 * Which rung produced the matcher: a sealed-artifact deserialize, or the per-process dictionary build.
+	 */
+	source: "artifact" | "built"
+	/**
+	 * The artifact path when `source === "artifact"`.
+	 */
+	path?: string
+	/**
+	 * Build provenance — read from the artifact trailer, or carried fresh off the fallback build.
+	 */
+	provenance?: FSTProvenance
+}
+
+/**
+ * Load the street-morphology matcher: sealed artifact first, per-process dictionary build as the degrade path.
+ */
+export function loadStreetMorphologyFST(opts: LoadStreetMorphologyFSTOpts = {}): LoadedStreetMorphologyFST {
+	const warn = opts.onWarn ?? (() => {})
+	const artifactPath = opts.artifactPath ?? defaultStreetMorphologyArtifactPath()
+
+	if (existsSync(artifactPath)) {
+		try {
+			const buf = readFileSync(artifactPath)
+			const matcher = deserializeFST(buf)
+			const provenance = readFSTProvenance(buf)
+
+			return { matcher, source: "artifact", path: artifactPath, ...(provenance ? { provenance } : {}) }
+		} catch (error) {
+			warn(
+				`street-morphology artifact at ${artifactPath} unreadable (${(error as Error).message}) — falling back to the dictionary build`
+			)
+		}
+	}
+
+	const built = buildStreetMorphologyFST({
+		dictionariesDir: opts.dictionariesDir ?? resourceDictionaryPath("libpostal"),
+	})
+
+	return { matcher: built.matcher, source: "built", provenance: built.provenance }
+}