@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

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

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Unified runtime loader for the street-morphology FST — the #1315 street-context gate's signal
+ *   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
@@ -21,14 +21,14 @@
  *   `fst-deserialize-web.ts` (see the docs demo loader).
  */
 
-import { existsSync, readFileSync } from "node:fs"
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { pathExists, readLocalBuffer } from "@mailwoman/core/fs/readers"
+import { resourceDictionaryPath } from "@mailwoman/core/paths"
 
-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"
+import type { FSTMatcher } from "#fst/matcher"
+import { deserializeFST, readFSTProvenance } from "#fst/serialize"
+import type { FSTProvenance } from "#fst/types"
+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.
@@ -77,13 +77,15 @@ export interface LoadedStreetMorphologyFST {
 /**
  * Load the street-morphology matcher: sealed artifact first, per-process dictionary build as the degrade path.
  */
-export function loadStreetMorphologyFST(opts: LoadStreetMorphologyFSTOpts = {}): LoadedStreetMorphologyFST {
+export async function loadStreetMorphologyFST(
+	opts: LoadStreetMorphologyFSTOpts = {}
+): Promise<LoadedStreetMorphologyFST> {
 	const warn = opts.onWarn ?? (() => {})
 	const artifactPath = opts.artifactPath ?? defaultStreetMorphologyArtifactPath()
 
-	if (existsSync(artifactPath)) {
+	if (await pathExists(artifactPath)) {
 		try {
-			const buf = readFileSync(artifactPath)
+			const buf = await readLocalBuffer(artifactPath)
 			const matcher = deserializeFST(buf)
 			const provenance = readFSTProvenance(buf)
 
@@ -95,7 +97,7 @@ export function loadStreetMorphologyFST(opts: LoadStreetMorphologyFSTOpts = {}):
 		}
 	}
 
-	const built = buildStreetMorphologyFST({
+	const built = await buildStreetMorphologyFST({
 		dictionariesDir: opts.dictionariesDir ?? resourceDictionaryPath("libpostal"),
 	})
 

package/{street-name-lookup.ts → lib/street/name-lookup.ts}

@@ -8,7 +8,7 @@
  *   Reads a street-name index (the FR instance = 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 shard — the same reader discipline as `AddressPointSqliteLookup`.
+ *   graceful-degrade on a tableless extract — 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 /
@@ -19,24 +19,11 @@
  *   the production rebuild is a tracked BAN-sdk follow-up.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { foldStreetSurface, type StreetEvidenceScope, type StreetLocalityEvidence } from "@mailwoman/resolver"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-function hasTable(db: DatabaseSync, table: string): boolean {
-	const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(table)
-
-	return row !== undefined
-}
-
-function hasColumn(db: DatabaseSync, table: string, column: string): boolean {
-	// `table` is a caller-controlled identifier (default `street_centroid`), not user input — safe to interpolate.
-	for (const row of db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>) {
-		if (row.name === column) return true
-	}
-
-	return false
-}
+import type { WOFDatabase } from "#schema"
+import { hasColumn, hasTable } from "#sqlite-utils"
 
 export interface SQLiteStreetNameLookupOpts {
 	/**
@@ -53,22 +40,22 @@ export interface SQLiteStreetNameLookupOpts {
  * 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 {
+export class SQLiteStreetNameLookup implements StreetLocalityEvidence, Disposable {
 	readonly countries: ReadonlySet<string>
-	readonly #db: DatabaseSync
-	readonly #byName: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byNameLocality: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byNamePostcode: ReturnType<DatabaseSync["prepare"]> | undefined
+	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 = {}) {
 		this.countries = new Set([...(opts.countries ?? ["FR"])].map((c) => c.toUpperCase()))
-		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+		this.#db = new DatabaseClient<WOFDatabase>(dbPath, { readOnly: true })
 		const table = opts.table ?? "street_centroid"
 
-		// Degrade gracefully on an empty/tableless shard — a no-op miss, never a crash (#568 discipline).
+		// 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 shard (a skip-scan, but correct). The fold used to build
+			// 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`)
@@ -104,10 +91,7 @@ export class SQLiteStreetNameLookup implements StreetLocalityEvidence {
 		return this.#byName.get(norm) !== undefined
 	}
 
-	/**
-	 * Close the underlying handle.
-	 */
-	close(): void {
-		this.#db.close()
+	[Symbol.dispose](): void {
+		this.#db[Symbol.dispose]()
 	}
 }