@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{fst-freshness.ts → lib/fst/freshness.ts}

@@ -29,13 +29,14 @@
  *   and continue.
  */
 
-import { createHash } from "node:crypto"
-import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs"
+import { pathExists, readFileRange, readLocalTextFile, statPath } from "@mailwoman/core/fs/readers"
+import { writeLocalTextFile } from "@mailwoman/core/fs/writers"
+import { md5File } from "@mailwoman/core/hash"
+import { tryParsingJSON } from "@mailwoman/core/json"
+import { basename, resolvePath, type PathBuilderLike } from "path-ts"
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
-
-import { FST_FORMAT_VERSION } from "./fst-serialize.ts"
-import type { FSTProvenance } from "./fst-types.ts"
+import { FST_FORMAT_VERSION } from "#fst/serialize"
+import type { FSTProvenance } from "#fst/types"
 
 /**
  * Fixed header size in bytes — mirrors `fst-serialize.ts`'s `HEADER_SIZE`. Duplicated rather than exported across
@@ -65,12 +66,6 @@ export const MIN_STAMPED_FORMAT_VERSION = 3
  */
 const MD5_HEX_LENGTH = 32
 
-/**
- * Bytes per read in {@link md5FileSync}. 8 MiB measured at 7.3 s for the 5.27 GB admin DB on the lab playpen — the same
- * throughput as `md5sum(1)`, so the sidecar below is what makes the check cheap, not the chunk size.
- */
-const MD5_CHUNK_BYTES = 8 * 1024 * 1024
-
 /**
  * What an FST was built from, recorded so a later reader can tell whether that thing still exists.
  *
@@ -121,69 +116,37 @@ export interface FSTExpectation {
  * Returns `undefined` for a file that is absent, too small, or not an FST at all — none of which is this function's
  * business to diagnose.
  */
-export function peekFSTStampFields(path: string): FSTStampFields | undefined {
-	if (!existsSync(path)) return undefined
-	const size = statSync(path).size
+export async function peekFSTStampFields(path: string): Promise<FSTStampFields | undefined> {
+	if (!(await pathExists(path))) return undefined
+	const size = (await statPath(path)).size
 
 	if (size < HEADER_SIZE) return undefined
-	const fd = openSync(path, "r")
+	const header = await readFileRange(path, 0, HEADER_SIZE)
 
-	try {
-		const header = Buffer.alloc(HEADER_SIZE)
-		readSync(fd, header, 0, HEADER_SIZE, 0)
+	if (header.readUInt32LE(0) !== MAGIC) return undefined
+	const formatVersion = header.readUInt16LE(4)
 
-		if (header.readUInt32LE(0) !== MAGIC) return undefined
-		const formatVersion = header.readUInt16LE(4)
+	if (formatVersion < MIN_STAMPED_FORMAT_VERSION) return { formatVersion, provenance: undefined }
+	const trailerStart = header.readUInt32LE(PROVENANCE_OFFSET_FIELD)
 
-		if (formatVersion < MIN_STAMPED_FORMAT_VERSION) return { formatVersion, provenance: undefined }
-		const trailerStart = header.readUInt32LE(PROVENANCE_OFFSET_FIELD)
+	// 0 = "this build wrote no trailer" (the serializer's own encoding); anything past EOF is a
+	// truncated file. Both read as "no stamp", which is what the caller does with them anyway.
+	if (trailerStart === 0 || trailerStart + 4 > size) return { formatVersion, provenance: undefined }
 
-		// 0 = "this build wrote no trailer" (the serializer's own encoding); anything past EOF is a
-		// truncated file. Both read as "no stamp", which is what the caller does with them anyway.
-		if (trailerStart === 0 || trailerStart + 4 > size) return { formatVersion, provenance: undefined }
+	const jsonLength = (await readFileRange(path, trailerStart, 4)).readUInt32LE(0)
 
-		const lengthBytes = Buffer.alloc(4)
-		readSync(fd, lengthBytes, 0, 4, trailerStart)
-		const jsonLength = lengthBytes.readUInt32LE(0)
+	if (jsonLength === 0 || trailerStart + 4 + jsonLength > size) return { formatVersion, provenance: undefined }
 
-		if (jsonLength === 0 || trailerStart + 4 + jsonLength > size) return { formatVersion, provenance: undefined }
+	const json = await readFileRange(path, trailerStart + 4, jsonLength)
 
-		const json = Buffer.alloc(jsonLength)
-		readSync(fd, json, 0, jsonLength, trailerStart + 4)
-
-		return { formatVersion, provenance: tryParsingJSON<FSTProvenance>(json.toString("utf8")) ?? undefined }
-	} finally {
-		closeSync(fd)
-	}
+	return { formatVersion, provenance: tryParsingJSON<FSTProvenance>(json.toString("utf8")) ?? undefined }
 }
 
 /**
- * Streaming MD5 of a file, SYNCHRONOUS.
- *
- * The async `md5File` in `@mailwoman/core/utils` is the one to reach for anywhere else. This exists because the FST
- * builder and its whole call chain are synchronous by design (`buildFSTFromWOF` → `buildLocaleFSTs`), and making them
- * async to stamp a checksum would cascade through command callers and tests for one hash. It reads in
- * {@link MD5_CHUNK_BYTES} chunks rather than `readFileSync` — the source is a multi-gigabyte database.
+ * Re-exported from `@mailwoman/core/hash`. This package's own test imports it from here, and the sidecar convention
+ * below is what it is for.
  */
-export function md5FileSync(path: string): string {
-	const hash = createHash("md5")
-	const fd = openSync(path, "r")
-
-	try {
-		const chunk = Buffer.alloc(MD5_CHUNK_BYTES)
-
-		for (;;) {
-			const read = readSync(fd, chunk, 0, MD5_CHUNK_BYTES, null)
-
-			if (read <= 0) break
-			hash.update(chunk.subarray(0, read))
-		}
-	} finally {
-		closeSync(fd)
-	}
-
-	return hash.digest("hex")
-}
+export { md5File } from "@mailwoman/core/hash"
 
 /**
  * The source identity an FST build should stamp, or a check should compare against.
@@ -197,8 +160,12 @@ export function md5FileSync(path: string): string {
  * write and the caller still gets its answer, because refusing to check freshness on a read-only tree would be the
  * wrong trade.
  */
-export function readWOFSourceIdentity(path: string, { refreshSidecar = true } = {}): FSTSourceIdentity {
-	const stats = statSync(path)
+export async function readWOFSourceIdentity(
+	source: PathBuilderLike,
+	{ refreshSidecar = true } = {}
+): Promise<FSTSourceIdentity> {
+	const path = resolvePath(source)
+	const stats = await statPath(path)
 	const memoKey = `${path}\0${stats.mtimeMs}\0${stats.size}`
 	const hit = sourceIdentityMemo.get(memoKey)
 
@@ -206,11 +173,11 @@ export function readWOFSourceIdentity(path: string, { refreshSidecar = true } =
 	const sidecarPath = `${path}.md5`
 	let md5: string | undefined
 
-	if (existsSync(sidecarPath)) {
-		const sidecarStats = statSync(sidecarPath)
+	if (await pathExists(sidecarPath)) {
+		const sidecarStats = await statPath(sidecarPath)
 
 		if (sidecarStats.mtimeMs >= stats.mtimeMs) {
-			const [hash] = readFileSync(sidecarPath, "utf8").trim().split(/\s+/)
+			const [hash] = (await readLocalTextFile(sidecarPath)).trim().split(/\s+/)
 
 			if (hash && hash.length === MD5_HEX_LENGTH) {
 				md5 = hash
@@ -219,11 +186,11 @@ export function readWOFSourceIdentity(path: string, { refreshSidecar = true } =
 	}
 
 	if (!md5) {
-		md5 = md5FileSync(path)
+		md5 = await md5File(path)
 
 		if (refreshSidecar) {
 			try {
-				writeFileSync(sidecarPath, `${md5}  ${path.split("/").pop()}\n`)
+				await writeLocalTextFile(`${md5}  ${basename(path)}\n`, sidecarPath)
 			} catch {
 				// Read-only data root — the digest is still correct, it just isn't cached.
 			}
@@ -293,7 +260,7 @@ export function fstStaleReason(fields: FSTStampFields | undefined, expected: FST
  * Returns `undefined` when the artifact is current OR when it is absent — an absent artifact is a different problem
  * with a different message, and every existing caller already reports it in place.
  */
-export function fstFreshnessWarning({
+export async function fstFreshnessWarning({
 	fstPath,
 	sourceDBPath,
 	formatVersion,
@@ -305,11 +272,11 @@ export function fstFreshnessWarning({
 	formatVersion?: number
 	exclusionPolicy?: string
 	rebuildCommand: string
-}): string | undefined {
-	if (!existsSync(fstPath) || !existsSync(sourceDBPath)) return undefined
+}): Promise<string | undefined> {
+	if (!(await pathExists(fstPath)) || !(await pathExists(sourceDBPath))) return undefined
 
-	const reason = fstStaleReason(peekFSTStampFields(fstPath), {
-		source: readWOFSourceIdentity(sourceDBPath),
+	const reason = fstStaleReason(await peekFSTStampFields(fstPath), {
+		source: await readWOFSourceIdentity(sourceDBPath),
 		...(formatVersion === undefined ? {} : { formatVersion }),
 		...(exclusionPolicy === undefined ? {} : { exclusionPolicy }),
 	})

package/lib/fst/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#fst/autocomplete"
+export * from "#fst/builder"
+export * from "#fst/deserialize-web"
+export * from "#fst/format"
+export * from "#fst/freshness"
+export * from "#fst/matcher"
+export * from "#fst/serialize"
+export * from "#fst/types"

package/{fst-matcher.ts → lib/fst/matcher.ts}

@@ -8,7 +8,7 @@
  *   arrays at accepting states.
  */
 
-import type { FSTContinuation, FSTMatchResult, FSTQueryResult, PlaceEntry } from "./fst-types.ts"
+import type { FSTContinuation, FSTMatchResult, FSTQueryResult, PlaceEntry } from "#fst/types"
 
 interface FSTNode {
 	edges: Map<string, number>

package/{fst-serialize.ts → lib/fst/serialize.ts}

@@ -19,7 +19,7 @@
  *   EDGE TABLE [edgeCount × 8 bytes] stringIdx u32 index into string table targetState u32
  *
  *   PLACE TABLE [placeCount × 60 bytes at V5, 56 below] wofID u32 placetypeIdx u8 index into
- *   PLACETYPE_ORDER chainLen u8 0..8 crossCountryBranches u8 (header flags bit0 gates the read)
+ *   PLACETYPE_ORDER chainLen u8 0..8 crossCountryBranches u8 (header flags bit0 enables the read)
  *   placeFlags u8 (V5; bit0 = encyclopedic present) nameIdx u32 index into string table referential f32
  *   population-anchored likelihood [0,1] — was the conflated `importance` (V2–V4), was population u32
  *   (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0) encyclopedic f32 (V5 only;
@@ -33,97 +33,34 @@
  *   V4-and-below artifact as format-stale for exactly this reason: its single float is unattributable.
  */
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
-
-import type { FSTNode } from "./fst-matcher.ts"
-import { FSTMatcher } from "./fst-matcher.ts"
-import type { FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
-
-/**
- * Format version that widened the per-state edge and place counters from 16 to 32 bits, growing the state entry from 12
- * to 16 bytes. Readers branch on it to stay backward-compatible with v2/v3 files.
- */
-const VERSION_WIDE_STATE_COUNTERS = 4
-
-/**
- * State-table entry size in bytes at or above {@link VERSION_WIDE_STATE_COUNTERS}.
- */
-const WIDE_STATE_ENTRY_SIZE = 16
-
-/**
- * State-table entry size in bytes below {@link VERSION_WIDE_STATE_COUNTERS}.
- */
-const NARROW_STATE_ENTRY_SIZE = 12
-
-/**
- * First format version carrying the trailing metadata block; older files simply have none.
- */
-const VERSION_WITH_METADATA = 3
+import { tryParsingJSON } from "@mailwoman/core/json"
+
+import {
+	EDGE_ENTRY_SIZE,
+	ENCYCLOPEDIC_OFFSET,
+	FST_FORMAT_VERSION,
+	FST_MAGIC_BYTES,
+	HEADER_SIZE,
+	LEGACY_PLACE_ENTRY_SIZE,
+	NARROW_STATE_ENTRY_SIZE,
+	PLACE_FLAG_HAS_ENCYCLOPEDIC,
+	PLACETYPE_ORDER,
+	SPLIT_PLACE_ENTRY_SIZE,
+	VERSION_TWO_SCORE_SPLIT,
+	VERSION_WIDE_STATE_COUNTERS,
+	VERSION_WITH_METADATA,
+	WIDE_STATE_ENTRY_SIZE,
+} from "#fst/format"
+import type { FSTNode } from "#fst/matcher"
+import { FSTMatcher } from "#fst/matcher"
+import type { FSTProvenance, PlaceEntry } from "#fst/types"
+
+export { FST_FORMAT_VERSION } from "#fst/format"
 
 /**
- * Format version that split the single `importance` float into `referential` + `encyclopedic`, growing the place entry
- * from 56 to 60 bytes and claiming the previously-reserved `pp+7` byte as {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
+ * File magic as a Buffer, for the Node-side prefix comparison.
  */
-const VERSION_TWO_SCORE_SPLIT = 5
-
-/**
- * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
- */
-const SPLIT_PLACE_ENTRY_SIZE = 60
-
-/**
- * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
- */
-const LEGACY_PLACE_ENTRY_SIZE = 56
-
-/**
- * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
- */
-const ENCYCLOPEDIC_OFFSET = 56
-
-/**
- * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-PLACE rather than per-file
- * because absence is the common case — roughly 89% of the 2026-08-05 gazetteer has no Wikipedia article — and a
- * file-level flag would force every one of those rows to claim a 0 it never had.
- */
-const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
-
-/**
- * File magic. A reader rejects anything not starting with these four bytes before parsing further.
- */
-const MAGIC = Buffer.from("FST\0", "ascii")
-
-/**
- * Format version this serializer emits. See {@link VERSION_WIDE_STATE_COUNTERS} for what each bump changed.
- */
-const VERSION = 5
-
-/**
- * The format version this tree WRITES, published so a freshness guard can call an older artifact format-stale without
- * re-typing the number. Mirrors `REQUIRED_PAIR_INDEX_SCHEMA`'s role for PIX1: one constant, so a version bump cannot be
- * noticed by some checkers and not others. See `fst-freshness.ts`.
- */
-export const FST_FORMAT_VERSION = VERSION
-
-/**
- * Fixed header size in bytes: magic, version, and the section offsets that follow it.
- */
-const HEADER_SIZE = 32
-
-/**
- * State-table entry: edge offset, place offset, and the two 32-bit counters (v4 widths).
- */
-const STATE_ENTRY_SIZE = 16
-
-/**
- * Edge-table entry: the transition label and the target state index.
- */
-const EDGE_ENTRY_SIZE = 8
-
-/**
- * Place-table entry at the version this tree WRITES: the place id, its placetype, coordinates, and both scores.
- */
-const PLACE_ENTRY_SIZE = SPLIT_PLACE_ENTRY_SIZE
+const MAGIC = Buffer.from(FST_MAGIC_BYTES)
 
 /**
  * Longest ancestry chain stored per place. Deeper hierarchies are truncated at the leaf end, since the specific end of
@@ -131,24 +68,6 @@ const PLACE_ENTRY_SIZE = SPLIT_PLACE_ENTRY_SIZE
  */
 const MAX_CHAIN_LEN = 8
 
-/**
- * Placetypes in hierarchy order, largest first. The index into this array is what gets written into a place entry, so
- * REORDERING IT BREAKS EVERY EXISTING FILE — append instead, and bump the version.
- */
-const PLACETYPE_ORDER: readonly PlacetypeID[] = [
-	"country",
-	"region",
-	"county",
-	"locality",
-	"localadmin",
-	"borough",
-	"neighbourhood",
-	"postalcode",
-	"campus",
-	"dependency",
-	"street_affix",
-]
-
 const placetypeToIdx = new Map<string, number>()
 
 for (let i = 0; i < PLACETYPE_ORDER.length; i++) {
@@ -198,9 +117,9 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 
 	// --- Allocate ---
 	const stringTableSize = (strings.length + 1) * 4 + stringBytes
-	const stateTableSize = nodes.length * STATE_ENTRY_SIZE
+	const stateTableSize = nodes.length * WIDE_STATE_ENTRY_SIZE
 	const edgeTableSize = totalEdges * EDGE_ENTRY_SIZE
-	const placeTableSize = totalPlaces * PLACE_ENTRY_SIZE
+	const placeTableSize = totalPlaces * SPLIT_PLACE_ENTRY_SIZE
 	const provenanceJson = provenance ? Buffer.from(JSON.stringify(provenance), "utf8") : null
 	const provenanceSize = provenanceJson ? 4 + provenanceJson.length : 0
 	const binarySize = HEADER_SIZE + stringTableSize + stateTableSize + edgeTableSize + placeTableSize
@@ -215,7 +134,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	const hasAmbiguity = nodes.some((n) => n.places.some((p) => p.crossCountryBranches !== undefined))
 	MAGIC.copy(buf, pos)
 	pos += 4
-	buf.writeUInt16LE(VERSION, pos)
+	buf.writeUInt16LE(FST_FORMAT_VERSION, pos)
 	pos += 2
 	buf.writeUInt16LE(hasAmbiguity ? 1 : 0, pos)
 	pos += 2
@@ -261,7 +180,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 
 	for (let si = 0; si < nodes.length; si++) {
 		const node = nodes[si]!
-		const sp = stateTableStart + si * STATE_ENTRY_SIZE
+		const sp = stateTableStart + si * WIDE_STATE_ENTRY_SIZE
 
 		buf.writeUInt32LE(edgeIdx, sp)
 		buf.writeUInt32LE(placeIdx, sp + 4)
@@ -277,14 +196,14 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 		}
 
 		for (const place of node.places) {
-			const pp = placeTableStart + placeIdx * PLACE_ENTRY_SIZE
+			const pp = placeTableStart + placeIdx * SPLIT_PLACE_ENTRY_SIZE
 			// Filter out WOF sentinel parent IDs (negative values like -1, -4).
 			const validChain = place.parentChain.filter((id) => id > 0)
 			const chainLen = Math.min(validChain.length, MAX_CHAIN_LEN)
 			buf.writeUInt32LE(place.wofID, pp)
 			buf.writeUInt8(placetypeToIdx.get(place.placetype) ?? 0, pp + 4)
 			buf.writeUInt8(chainLen, pp + 5)
-			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 = v5 placeFlags.
+			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 enables the read), byte 1 = v5 placeFlags.
 			buf.writeUInt8(hasAmbiguity ? Math.min(place.crossCountryBranches ?? 0, 255) : 0, pp + 6)
 			// An absent encyclopedic score writes flag 0 AND a 0.0 float. The float is unread in that
 			// state, so absence can never surface as a score — the meaning-of-zero rule, in bytes.
@@ -321,7 +240,10 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 	if (!buf.subarray(0, 4).equals(MAGIC)) throw new Error("FST magic mismatch")
 	const version = buf.readUInt16LE(4)
 
-	if (version < 1 || version > VERSION) throw new Error(`FST version ${version} unsupported (expected 1..${VERSION})`)
+	if (version < 1 || version > FST_FORMAT_VERSION) {
+		throw new Error(`FST version ${version} unsupported (expected 1..${FST_FORMAT_VERSION})`)
+	}
+
 	const isV2 = version >= 2
 	const isSplit = version >= VERSION_TWO_SCORE_SPLIT
 	// flags bit0 (survey #4): place rows carry surface-ambiguity data in the former _pad byte.
@@ -416,7 +338,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 				lat: buf.readFloatLE(pp + 16),
 				lon: buf.readFloatLE(pp + 20),
 				parentChain,
-				// Header flags bit0 gates the read (survey #4): pre-ambiguity artifacts expose undefined.
+				// Header flags bit0 enables the read (survey #4): pre-ambiguity artifacts expose undefined.
 				...(hasAmbiguity ? { crossCountryBranches: buf.readUInt8(pp + 6) } : {}),
 				...(hasEncyclopedic ? { encyclopedic: buf.readFloatLE(pp + ENCYCLOPEDIC_OFFSET) } : {}),
 			}

package/{fst-types.ts → lib/fst/types.ts}

@@ -8,6 +8,8 @@
  *   prefix of every place name in the gazetteer.
  */
 
+import type { PathBuilderLike } from "path-ts"
+
 export interface PlaceEntry {
 	wofID: number
 	placetype: PlacetypeID
@@ -129,7 +131,7 @@ export interface FSTProvenance {
 }
 
 export interface BuildFSTOpts {
-	dbPath: string
+	dbPath: PathBuilderLike
 	/**
 	 * Pre-computed identity of `dbPath` to stamp into provenance. Omit and the builder reads it via
 	 * `readWOFSourceIdentity` (sidecar-cached). Supply it when the digest is already in hand, or when the caller is
@@ -164,7 +166,7 @@ export interface BuildFSTOpts {
 	 * accessible under several surfaces records each surface's own count. Serialized into the place row's former `_pad`
 	 * byte with presence signaled by header flags bit0, so VERSION stays put and pre-ambiguity artifacts read as "no
 	 * data" (never "0 branches" — the meaning-of-zero rule). No decoder consumes it yet; consumers (FST-prior tempering,
-	 * the Option-A evidence channel) arrive behind their own measured gates.
+	 * the Option-A evidence channel) arrive behind their own measured checks.
 	 */
 	surfaceCountryCounts?: ReadonlyMap<string, number>
 	onProgress?: (phase: string, detail?: string) => void

package/{fts.ts → lib/fts/index.ts}

@@ -14,7 +14,8 @@
  *   bag.
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
 /**
  * Name of the FTS5 virtual table this module owns. Centralized so `WOFSQLitePlaceLookup` and the CLI can't drift apart.
@@ -71,6 +72,16 @@ export const ALIAS_SEPARATOR = "\uE000"
  */
 const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
 
+/**
+ * The query/name fold every exact-tier comparison uses: lowercase, trim, collapse internal whitespace. The `alt_names`
+ * bag is compared alias-by-alias against a query folded THIS way, so the fold lives beside the bag parser — every
+ * consumer (the Node resolver's exact tier, the WASM resolver, the name-exact sub-tier sort) folds through this one
+ * function.
+ */
+export function foldQueryText(input: string): string {
+	return input.toLowerCase().trim().replaceAll(/\s+/g, " ")
+}
+
 /**
  * Does any alias in an `alt_names` bag exactly equal the (already-normalized) query? The single shared implementation
  * of the exact-tier alias check for every consumer of the bag — the Node resolver's `#exactMatchIDs` fallback, the WASM
@@ -80,10 +91,10 @@ const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
  *
  * - **Separated bags** (built since #523): aliases joined with {@link ALIAS_SEPARATOR}, plus a trailing separator so even
  *   a single-alias bag self-identifies as separator-formatted. Split + per-alias equality — a true exact-alias check,
- *   matching the semantics of the full `names` table (`names.name = ? COLLATE NOCASE`), so it runs UNGATED: an alias
- *   match is an exact match whether or not another candidate matched on its canonical name.
+ *   matching the semantics of the full `names` table (`names.name = ? COLLATE NOCASE`), so it runs unrestricted: an
+ *   alias match is an exact match whether or not another candidate matched on its canonical name.
  * - **Legacy bags** (pre-#523 artifacts, e.g. an already-deployed slim DB): aliases space-joined, boundaries lost. Falls
- *   back to the historical padded-containment check, gated on `anyStrictExact` — ungated containment would
+ *   back to the historical padded-containment check, conditioned on `anyStrictExact` — unrestricted containment would
  *   false-promote interior fragments ("York" inside the alias "New York City") and cross-boundary fragments ("York New"
  *   across "…York" + "New…"). Delete this branch once every shipped artifact carries the separator.
  *
@@ -95,15 +106,14 @@ const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
  */
 export function aliasBagExactMatch(altNames: string | null, normalizedQuery: string, anyStrictExact: boolean): boolean {
 	if (altNames === null || altNames === "" || !normalizedQuery) return false
-	const norm = (s: string): string => s.toLowerCase().trim().replaceAll(/\s+/g, " ")
 
 	if (altNames.includes(ALIAS_SEPARATOR)) {
-		return altNames.split(ALIAS_SEPARATOR).some((alias) => norm(alias) === normalizedQuery)
+		return altNames.split(ALIAS_SEPARATOR).some((alias) => foldQueryText(alias) === normalizedQuery)
 	}
 
 	if (anyStrictExact) return false
 
-	return ` ${norm(altNames)} `.includes(` ${normalizedQuery} `)
+	return ` ${foldQueryText(altNames)} `.includes(` ${normalizedQuery} `)
 }
 
 /**
@@ -189,7 +199,10 @@ export interface BuildPlaceSearchFTSOpts {
  * Returns a `BuildPlaceSearchFTSResult` summary. Idempotent when `drop: false` — re-running against an already-indexed
  * DB skips whichever indexes already exist.
  */
-export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSOpts = {}): BuildPlaceSearchFTSResult {
+export function buildPlaceSearchFTS<DB>(
+	db: DatabaseClient<DB>,
+	opts: BuildPlaceSearchFTSOpts = {}
+): BuildPlaceSearchFTSResult {
 	const start = Date.now()
 	const onProgress = opts.onProgress ?? (() => {})
 
@@ -329,28 +342,20 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
  * Returns true iff the `place_search` table exists in the connected DB. Used by `WOFSQLitePlaceLookup` for its "FTS
  * missing — pass buildFTS:true or run the CLI" guard.
  */
-export function placeSearchFTSExists(db: DatabaseSync): boolean {
+export function placeSearchFTSExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, PLACE_SEARCH_TABLE)
 }
 
 /**
  * Returns true iff the `place_bbox` R*Tree table exists. Used for opt-in proximity lookup checks.
  */
-export function placeBboxExists(db: DatabaseSync): boolean {
+export function placeBboxExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, PLACE_BBOX_TABLE)
 }
 
 /**
  * Returns true iff the `place_population` table exists. Used for opt-in population-ranking checks.
  */
-export function placePopulationExists(db: DatabaseSync): boolean {
+export function placePopulationExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, PLACE_POPULATION_TABLE)
 }
-
-function tableExists(db: DatabaseSync, name: string): boolean {
-	const row = db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`).get(name) as
-		| { name: string }
-		| undefined
-
-	return Boolean(row)
-}

package/{fts-query.ts → lib/fts/query.ts}

@@ -8,7 +8,7 @@
  *   an unescaped quote or a bare `*` is a syntax error, not an empty result.
  */
 
-import type { FindPlaceQuery, WOFPlacetype } from "./types.ts"
+import type { FindPlaceQuery, WOFPlacetype } from "#types"
 
 export function normalizePlacetypes(p: FindPlaceQuery["placetype"]): WOFPlacetype[] | null {
 	if (!p) return null

package/{geonames-aliases.ts → lib/geonames/aliases.ts}

@@ -24,14 +24,14 @@
  *   (TSV).
  */
 
-import { existsSync } from "node:fs"
-import type { DatabaseSync } from "node:sqlite"
-
 import { isOfficialLanguage } from "@mailwoman/codex/country"
-import { join } from "path-ts"
+import { pathExists } from "@mailwoman/core/fs/readers"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { join, type PathBuilderLike } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
-import { GEONAMES_POSTAL_ID_BASE } from "./geonames-postal.ts"
+import { GEONAMES_POSTAL_ID_BASE } from "#geonames/postal"
+import type { WOFDatabase } from "#schema"
 
 /**
  * Synthetic id base for GeoNames-sourced rows (#743/#193) — above Overture's 8e12 so the three sources (WOF real ids,
@@ -62,11 +62,11 @@ const FOLD_OWNED_TABLES = ["spr", "names", "place_population", "ancestors"] as c
  * country. Gaborone/BW at id 9000000121151 became Aichegg/AT and kept all 26 of its names; Kinshasa's 16,000,000
  * population landed on a Lithuanian hamlet.
  *
- * The upper bound is NOT the end of the id space. Each later shard owns a range above this one — GeoNames-postal @
+ * The upper bound is NOT the end of the id space. Each later extract owns a range above this one — GeoNames-postal @
  * 9.5e12, NL-PC6 @ 9.6e12, Code-Point @ 9.7e12, NI @ 9.8e12 — and a purge that ran past {@link GEONAMES_POSTAL_ID_BASE}
  * would delete them.
  */
-export function purgeGeonamesAliasRange(db: DatabaseSync): Record<string, number> {
+export function purgeGeonamesAliasRange<DB>(db: DatabaseClient<DB>): Record<string, number> {
 	const removed: Record<string, number> = {}
 
 	for (const table of FOLD_OWNED_TABLES) {
@@ -125,7 +125,7 @@ async function parseAlternateNamesV2(
 	// spelling across rows — Malabo carries "Santa Isabel" as (es, unflagged) AND as (no-language,
 	// isHistoric=1, to=1973). Officialness must see the flags from EVERY row for the spelling, or the
 	// colonial-era name sails through on the language-tagged row (the #936 review's Malabo finding).
-	// Do NOT gate on isPreferredName instead — it's sparse annotation, not a signal (Turku's sv "Åbo"
+	// Do NOT condition on isPreferredName instead — it's sparse annotation, not a signal (Turku's sv "Åbo"
 	// is unflagged; FI has 1,746 flags across the whole dump).
 	//
 	// Both passes STREAM the file rather than sharing one materialized array: NO's V2 dump is 33 MB,
@@ -190,9 +190,9 @@ async function parseAlternateNamesV2(
  * the candidate build's alias pass.
  */
 export async function ingestGeonamesAliases(
-	db: DatabaseSync,
+	db: DatabaseClient<WOFDatabase>,
 	countries: string[],
-	geonamesDir: string,
+	geonamesDir: PathBuilderLike,
 	onProgress?: (event: GeonamesIngestProgress) => void,
 	opts?: {
 		/**
@@ -211,7 +211,7 @@ export async function ingestGeonamesAliases(
 		 * at 7 new name-exact collisions globally). The main dump's bare `alternatenames` list still decides WHICH rows
 		 * exist; V2 only decorates them. Missing file = the pre-#936 untagged behavior, not an error.
 		 */
-		alternateDir?: string
+		alternateDir?: PathBuilderLike
 	}
 ): Promise<number> {
 	// Latin-only, no bracket/paren noise GeoNames packs into `alternatenames` ("(( Karis Landskommun ))",
@@ -265,7 +265,7 @@ export async function ingestGeonamesAliases(
 	for (const cc of countries) {
 		const file = join(geonamesDir, `${cc}.txt`)
 
-		if (!existsSync(file)) {
+		if (!(await pathExists(file))) {
 			report({ country: cc, places: 0, skipped: true }, file)
 
 			continue
@@ -275,7 +275,7 @@ export async function ingestGeonamesAliases(
 		// #267: add A-class admin + ancestry only for the gap countries this country is in (never the EU set).
 		const addAdmin = opts?.adminForCountries?.has(cc) ?? false
 		const v2File = opts?.alternateDir ? join(opts.alternateDir, `${cc}.txt`) : undefined
-		const readV2 = Boolean(v2File && existsSync(v2File))
+		const readV2 = Boolean(v2File && (await pathExists(v2File)))
 
 		// Survey pass. The dump is STREAMED — NO's is 71 MB and only the caller knows which country
 		// comes next — so what a later pass needs has to be collected here rather than re-scanned off a