@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

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}

@@ -5,7 +5,7 @@
  *
  *   FTS5 index lifecycle for the WOF SQLite distribution.
  *
- *   Shared by `WOFSqlitePlaceLookup` (lazy build via `buildFTS: true`) and the operator-side
+ *   Shared by `WOFSQLitePlaceLookup` (lazy build via `buildFTS: true`) and the operator-side
  *   `mailwoman gazetteer build fts` CLI (ahead-of-time build to avoid first-open latency in production).
  *
  *   Upstream WOF SQLite distributions do NOT ship FTS5. The index lives in a `place_search` virtual
@@ -14,10 +14,11 @@
  *   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.
+ * Name of the FTS5 virtual table this module owns. Centralized so `WOFSQLitePlaceLookup` and the CLI can't drift apart.
  */
 export const PLACE_SEARCH_TABLE = "place_search"
 
@@ -71,19 +72,29 @@ 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
+ * of the exact-tier alias check for every consumer of the bag — the Node resolver's `#exactMatchIDs` fallback, the WASM
  * resolver, and the demo's httpvfs resolver — so the bag format and its parsers can't drift.
  *
  * Two formats exist in the wild:
  *
  * - **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 ?? (() => {})
 
@@ -326,31 +339,23 @@ 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
+ * 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
@@ -67,7 +67,7 @@ export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }):
 		// fusing "Thiron-Gardais" into the unmatchable single term `ThironGardais` while the FTS
 		// doc holds two terms (#945 — the entire hyphenated-name class missed at the raw lookup;
 		// masked for years because pre-splice tokenizers never emitted hyphen-preserved values).
-		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter(Boolean)
+		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter((part) => part.length > 0)
 
 		if (!parts.length) continue
 

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

package/lib/geonames/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#geonames/aliases"
+export * from "#geonames/postal"

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

@@ -3,15 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   #920 — fold GeoNames POSTAL codes into a WOF/unified postcode shard as first-class
+ *   #920 — fold GeoNames POSTAL codes into a WOF/unified postcode extract as first-class
  *   `postalcode` places, for the countries whose WOF postalcode repos don't exist (the
  *   namesake-tail locales: FI/CZ/SK/SI/DK/NO/HR/PL and any future gap).
  *
  *   Why: the night-31 taxonomy measured the cross-locale resolve tail as NAMESAKE COLLISION
- *   (FI 300/1k … PL 75/1k offender rows), and the controlled experiment showed postcode-shard
+ *   (FI 300/1k … PL 75/1k offender rows), and the controlled experiment showed postcode-extract
  *   coverage alone collapses it (FI 300→1, CZ 131→4): a resolvable postcode node feeds the
  *   resolver's coordinate-first sibling-postcode candidate injection, which binds the locality
- *   pick to its postcode neighborhood. The machinery already ships; it was coverage-starved.
+ *   pick to its postcode neighborhood. The implementation already ships; it was coverage-starved.
  *
  *   Two hard-won laws from the experiment are enforced HERE, in code, not in a runbook:
  *
@@ -30,16 +30,17 @@
  *   --geonames-postal-countries`, any standalone fold, and the `mailwoman gazetteer` commands
  *   share ONE implementation. GeoNames postal dump = `download.geonames.org/export/zip/<CC>.zip`
  *   → `<CC>.txt` (TSV: country, postcode, place, admin1, code1, admin2, code2, admin3, code3,
- *   lat, lon, accuracy). License CC BY 4.0 — attribution rides the shard's `meta` provenance and
+ *   lat, lon, accuracy). License CC BY 4.0 — attribution rides the extract's `meta` provenance and
  *   the model card like the existing GeoNames alias fold.
  */
 
-import { existsSync } from "node:fs"
-import type { DatabaseSync } from "node:sqlite"
-
-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 type { WOFDatabase } from "#schema"
+
 /**
  * Column count of a GeoNames postal-code TSV row. Short rows are truncated or blank and are skipped. See the
  * allCountries.zip readme for the field list.
@@ -54,7 +55,7 @@ const GEONAMES_POSTAL_COLUMNS = 11
 export const GEONAMES_POSTAL_ID_BASE = 9_500_000_000_000
 
 /**
- * The #920 name law: reduce a postal code to the sanitized-query token shape — strip every non-letter/number — so the
+ * The #920 name law: reduce a postcode to the sanitized-query token shape — strip every non-letter/number — so the
  * stored name matches what `sanitizeFTSQuery` produces from the parsed postcode token. `"110 00"` → `"11000"`,
  * `"11-041"` → `"11041"`, `"AD500"` → `"AD500"`.
  */
@@ -77,7 +78,7 @@ export type PostcodePoint = readonly [number, number]
  *
  * Distance is squared-Euclidean in DEGREES, not haversine. At the scale a postcode spans, the ranking the two produce
  * is the same, and this one carries no trig into a per-group inner loop. Ties go to the earliest member, which makes
- * the result a pure function of the input order — the property a rebuilt shard's ids depend on.
+ * the result a pure function of the input order — the property a rebuilt extract's ids depend on.
  *
  * Exported (rather than inlined at each ingest) because it is the second half of the #920 pair: every postcode source
  * that groups member points — GeoNames postal, OSM `addr:postcode` — owes the same law, and a second hand-rolled copy
@@ -132,15 +133,15 @@ export interface GeonamesPostalIngestResult {
 }
 
 /**
- * Fold GeoNames postal codes for `countries` into an open unified/postcode ingest DB: one `spr` row per distinct
+ * Fold GeoNames postcodes for `countries` into an open unified/postcode ingest DB: one `spr` row per distinct
  * normalized postcode (placetype `postalcode`, medoid centroid, degenerate bbox), the normalized form as `name`, and
  * the display form as an extra `names` row when it differs. The caller owns the FTS rebuild (rows ride the standard
  * freeze phase).
  */
 export async function ingestGeonamesPostal(
-	db: DatabaseSync,
+	db: DatabaseClient<WOFDatabase>,
 	countries: readonly string[],
-	postalDir: string
+	postalDir: PathBuilderLike
 ): Promise<GeonamesPostalIngestResult> {
 	const sprInsert = db.prepare(
 		`INSERT OR REPLACE INTO spr (id, parent_id, name, placetype, country, latitude, longitude, min_latitude, min_longitude, max_latitude, max_longitude, is_current, is_deprecated, is_ceased, is_superseded, is_superseding, lastmodified) VALUES (?, -1, ?, 'postalcode', ?, ?, ?, ?, ?, ?, ?, 1, 0, 0, 0, 0, 0)`
@@ -159,7 +160,7 @@ export async function ingestGeonamesPostal(
 		const cc = country.toUpperCase()
 		const file = join(postalDir, `${cc}.txt`)
 
-		if (!existsSync(file)) {
+		if (!(await pathExists(file))) {
 			missing.push(cc)
 
 			console.error(
@@ -173,7 +174,7 @@ export async function ingestGeonamesPostal(
 		const members = new Map<string, { display: string; pts: Array<[number, number]> }>()
 
 		// Streamed: a national dump is a caller-supplied size — GB's is 177 MB, and only the caller
-		// knows which country is next. `header: false` is load-bearing; the GeoNames postal dump is
+		// knows which country is next. `header: false` is required; the GeoNames postal dump is
 		// headerless, so row 1 would be consumed as column names and its postcode lost.
 		for await (const cols of TSVSpliterator.fromAsync(file, { header: false })) {
 			if (cols.length < GEONAMES_POSTAL_COLUMNS) continue