@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{candidate-lookup.ts → lib/candidate-lookup.ts}

@@ -23,8 +23,6 @@
  *   `bbox` field on {@link FindPlaceQuery}).
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators"
 import {
 	expandPlacetypeFilter,
@@ -33,6 +31,8 @@ import {
 	type GazetteerArtifactCoverage,
 } from "@mailwoman/resolver"
 import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
 
 import {
 	CANDIDATE_ANCESTOR_TABLE,
@@ -40,31 +40,31 @@ import {
 	intervalContains,
 	type CandidateAncestorTable,
 	type IntervalLabel,
-} from "./candidate-ancestors-schema.ts"
-import { CANDIDATE_FTS_TABLE } from "./candidate-fts.ts"
-import type { CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "./candidate-schema.ts"
-import { readGazetteerCoverageManifest } from "./coverage-manifest-schema.ts"
-import { referentialFromPopulation } from "./place-importance-schema.ts"
-import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "./postal-city-candidate-schema.ts"
-import { rankByPrimaryPreference, type RankedRow, RERANK_FETCH } from "./primary-preference.ts"
-import { applyProximityRerank } from "./proximity-rerank.ts"
-import { REGION_CLASS_PLACETYPES, regionQualifierProbeKeys } from "./region-keys.ts"
-import { allRows, hasColumn, hasTable } from "./sqlite-utils.ts"
-import { type NameKey, normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.ts"
-import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
-
-export { rankByPrimaryPreference } from "./primary-preference.ts"
-export type { RankedRow } from "./primary-preference.ts"
+} from "#candidate-ancestors-schema"
+import { CANDIDATE_FTS_TABLE } from "#candidate-fts"
+import type { CandidateDatabase, CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "#candidate-schema"
+import { readGazetteerCoverageManifest } from "#coverage-manifest-schema"
+import { referentialFromPopulation } from "#place-importance-schema"
+import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "#postal/city-candidate-schema"
+import { rankByPrimaryPreference, type RankedRow, RERANK_FETCH } from "#primary-preference"
+import { applyProximityRerank } from "#proximity-rerank"
+import { REGION_CLASS_PLACETYPES, regionQualifierProbeKeys } from "#region-keys"
+import { allRows, hasColumn, hasTable } from "#sqlite-utils"
+import { type NameKey, normalizeLocalityForKey, stripLocalityQualifier } from "#street/normalize"
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "#types"
+
+export { rankByPrimaryPreference } from "#primary-preference"
+export type { RankedRow } from "#primary-preference"
 
 export interface WOFCandidateTableLookupOpts {
 	/**
 	 * Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only.
 	 */
-	databasePath?: string
+	databasePath?: PathBuilderLike
 	/**
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
-	database?: DatabaseSync
+	database?: DatabaseClient<CandidateDatabase>
 	/**
 	 * #1882 opt-in: exempt `name_role = 'variant'` aliases — the holder's own primary name in another orthography,
 	 * stamped by the build's own-name detector — from the cross-country primary-preference penalty. No-ops on an artifact
@@ -126,12 +126,12 @@ function wordFuzzySimilarity(a: string, b: string): number {
 }
 
 /**
- * Postcode-containment re-rank gate radius (km) — the SAME value the resolver's country pass measures at
- * (`POSTCODE_COUNTRY_COHERENCE_GATE_KM`, resolver/postcode-country-coherence.ts): a locality within this distance of
- * the postcode's own centroid counts as "containing" it. One number, two passes — a divergence here would make the two
- * mechanisms disagree about what is proximal.
+ * Postcode-containment re-rank check radius (km) — the SAME value the resolver's country pass measures at
+ * (`POSTCODE_COUNTRY_COHERENCE_THRESHOLD_KM`, resolver/postcode-country-coherence.ts): a locality within this distance
+ * of the postcode's own centroid counts as "containing" it. One number, two passes — a divergence here would make the
+ * two mechanisms disagree about what is proximal.
  */
-const POSTCODE_CONTAINMENT_GATE_KM = 25
+const POSTCODE_CONTAINMENT_THRESHOLD_KM = 25
 
 /**
  * Unpadded character-trigrams of `s`, OR'd into an FTS5 trigram MATCH query (each quoted so FTS treats it as a literal
@@ -156,9 +156,13 @@ function ftsTrigramQuery(s: string): string {
  * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSQLitePlaceLookup} in `createWOFResolver(backend)`
  * — same `findPlace` contract, population-first ranking.
  */
-export class WOFCandidateTableLookup implements PlaceLookup {
-	#db: DatabaseSync
-	#ownsDB: boolean
+export class WOFCandidateTableLookup implements PlaceLookup, Disposable {
+	#db: DatabaseClient<CandidateDatabase>
+	/**
+	 * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
+	 * ownership is membership rather than a flag a later branch has to check.
+	 */
+	readonly #resources = new DisposableStack()
 	readonly #countryToID = new Map<string, number>()
 	readonly #idToCountry = new Map<number, string>()
 	readonly #placetypeToID = new Map<string, number>()
@@ -167,29 +171,29 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	 * Prepared `(name_key, postcode)` probe for the #741 postal-city side-index — `undefined` when the
 	 * `postal_city_candidate` table isn't present, so a candidate.db built without it is byte-stable.
 	 */
-	readonly #postalCityProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #postalCityProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 	/**
 	 * Prepared FTS5-trigram MATCH probe for the typo-tolerant fallback — `undefined` when the `candidate_fts` index isn't
 	 * present, so a candidate.db built without it is byte-stable (the fuzzy path is skipped, exactly like today).
 	 */
-	readonly #ftsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #ftsProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 	/**
-	 * Prepared UNFILTERED existence probe (`name_key` present anywhere, ignoring country/placetype/bbox). Gates the fuzzy
-	 * fallback: fuzzy is a TYPO corrector, so it engages only when the name doesn't exist in the gazetteer at all. A name
-	 * that DOES exist but missed under the active filter is a filter miss (e.g. a placer misroute "Vienna, Austria"→IT),
-	 * not a spelling miss — fuzzing it would scrape an unrelated same-country place and defeat the cascade's
-	 * country-agnostic retry. Prepared only alongside `#ftsProbe`.
+	 * Prepared UNFILTERED existence probe (`name_key` present anywhere, ignoring country/placetype/bbox). Checks the
+	 * fuzzy fallback: fuzzy is a TYPO corrector, so it engages only when the name doesn't exist in the gazetteer at all.
+	 * A name that DOES exist but missed under the active filter is a filter miss (e.g. a placer misroute "Vienna,
+	 * Austria"→IT), not a spelling miss — fuzzing it would scrape an unrelated same-country place and defeat the
+	 * cascade's country-agnostic retry. Prepared only alongside `#ftsProbe`.
 	 */
-	readonly #nameKeyExistsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #nameKeyExistsProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 	/**
 	 * Facts this candidate DB declares about itself — the coverage manifest (`country_coverage` + `country_bbox`) the
 	 * gazetteer build emits, read once at open. `undefined` when the artifact predates the manifest, so every consumer
-	 * (the hard-country coverage gate, guard-B plausibility) falls back to its code constants byte-identically.
+	 * (the hard-country coverage check, guard-B plausibility) falls back to its code constants byte-identically.
 	 */
 	readonly artifactCoverage: GazetteerArtifactCoverage | undefined
 	/**
 	 * `", importance"` when this artifact carries the #28 fame column, `""` when it does not — spliced into the probe's
-	 * SELECT list. Existence-gated exactly like `#ftsProbe` and `#postalCityProbe` above, and for the same reason: a
+	 * SELECT list. Existence-restricted exactly like `#ftsProbe` and `#postalCityProbe` above, and for the same reason: a
 	 * candidate.db built before the column is a valid artifact, and naming a column it lacks would turn a stale gazetteer
 	 * into `no such column` on the first keystroke rather than into "no fame signal", which is what it is.
 	 */
@@ -208,22 +212,22 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	/**
 	 * Prepared chain probe over the `candidate_ancestor` sidecar — `undefined` when the artifact predates it.
 	 */
-	readonly #ancestorsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #ancestorsProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 	readonly #ancestorsCache = new Map<number, Ancestor[]>()
 	/**
 	 * Prepared interval-label probe over `candidate_interval` — `undefined` when the artifact predates the sidecar, which
-	 * is what makes the admin-containment re-rank (#1717 stage 2) capability-gated: without it,
+	 * is what makes the admin-containment re-rank (#1717 stage 2) capability-restricted: without it,
 	 * `FindPlaceQuery.regionQualifier` is ignored, no candidate carries a `containedByQualifier` stamp, and the resolver
-	 * walk reports the lever `unavailable` instead of silently dead.
+	 * walk reports the change `unavailable` instead of silently dead.
 	 */
-	readonly #intervalProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #intervalProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 	readonly #intervalCache = new Map<number, IntervalLabel | null>()
 	/**
 	 * Prepared qualifier probe: the region-band rows (plus `country` — the region SLOT can hold a mislabeled country
 	 * name, "Moscow, Russia" parses region="Russia") for one folded qualifier key. `undefined` when the artifact lacks
 	 * the sidecar or the placetype dictionary lacks the band entirely.
 	 */
-	readonly #qualifierProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #qualifierProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 	/**
 	 * The ancestor lineage of a resolved place — nearest-first (locality-tier → county → region → … → country), the same
 	 * order the FTS backend's `ancestorLineage` serves, read from the `candidate_ancestor` sidecar in one clustered
@@ -240,10 +244,8 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	constructor(opts: WOFCandidateTableLookupOpts) {
 		if (opts.database) {
 			this.#db = opts.database
-			this.#ownsDB = false
 		} else if (opts.databasePath) {
-			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
-			this.#ownsDB = true
+			this.#db = this.#resources.use(new DatabaseClient<CandidateDatabase>(opts.databasePath, { readOnly: true }))
 		} else {
 			throw new Error("WOFCandidateTableLookup needs `databasePath` or `database`")
 		}
@@ -285,7 +287,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		this.#variantAliasExemption = opts.variantAliasExemption === true
 		this.#roleSelect = this.#hasNameRole ? ", name_role" : ""
 
-		// Ancestors sidecar (#1717): existence-gated like the probes above, and the CAPABILITY gates with
+		// Ancestors sidecar (#1717): existence-restricted like the probes above, and the CAPABILITY checks with
 		// it — see the `ancestors` property doc for why an older artifact must read as "no ancestors()"
 		// rather than as a method that answers [] everywhere.
 		if (hasTable(this.#db, CANDIDATE_ANCESTOR_TABLE)) {
@@ -297,7 +299,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			this.ancestors = (id) => this.#ancestorLineage(id)
 		}
 
-		// Admin-containment re-rank (#1717 stage 2): gated on the interval half of the sidecar (built in
+		// Admin-containment re-rank (#1717 stage 2): conditioned on the interval half of the sidecar (built in
 		// the same pass as the closure rows; probed separately so a hand-degraded artifact degrades
 		// truthfully) AND on the placetype dictionary carrying the qualifier band at all.
 		if (this.#ancestorsProbe && hasTable(this.#db, CANDIDATE_INTERVAL_TABLE)) {
@@ -314,7 +316,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			}
 		}
 
-		// Coverage manifest (survey candidate #2): the artifact's own coverage facts, existence-gated like
+		// Coverage manifest (survey candidate #2): the artifact's own coverage facts, existence-restricted like
 		// the probes above — a candidate.db built before the manifest reads `undefined` and consumers keep
 		// their code-constant fallbacks byte-identically.
 		this.artifactCoverage = readGazetteerCoverageManifest(this.#db)
@@ -396,7 +398,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	 * Is `sprID` contained by ANY of the qualifier's rows? Interval first — {@link intervalContains}, O(1), reflexive —
 	 * then the closure rows where intervals abstain: the interval forest encodes only the CANONICAL parent per place, so
 	 * a `false` there means "not contained along the canonical hierarchy", and the chain probe (one clustered read of
-	 * ≤{@link MAX_ANCESTOR_DEPTH} rows) is the complete record that settles it.
+	 * ≤{@link MAX_ANCESTOR_DEPTH} rows) is the complete record that determines the result.
 	 */
 	#containedByQualifier(sprID: number, qualifierIDs: ReadonlySet<number>, qualifierLabels: IntervalLabel[]): boolean {
 		if (qualifierIDs.has(sprID)) return true
@@ -491,7 +493,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// cannot reach a neighbourhood-tier namesake, so a CONTAINED one is structurally invisible no matter
 		// how the list reorders — the Astoria class: Queens' Astoria is a WOF neighbourhood, and the walk
 		// answered the Oregon locality under `qualifier="NY"` because nothing in the pool sat under NY. The
-		// widening is injection-only and triple-gated: the band is explicit (neighbourhood/macrohood/microhood
+		// widening is injection-only and triple-conditioned: the band is explicit (neighbourhood/macrohood/microhood
 		// — never region or country tiers), admission still requires the sidecar's containment proof, and only
 		// primary-keyed rows enter (an alias-keyed neighbourhood is the #1626 scrape class). Recall can only
 		// widen, and only toward rows the qualifier vouches for. `opts.shapeFilters`' bbox clause is
@@ -601,7 +603,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 		// #741: postcode-keyed postal-city alias. An exact `(name_key, postcode)` hit resolves a
 		// user-typed POSTAL city ("Antioch", 37013) to the geographic locality the postcode sits in
-		// ("Nashville"), bypassing the population/region ranking that can't see the postcode. Gated on
+		// ("Nashville"), bypassing the population/region ranking that can't see the postcode. Conditioned on
 		// the side-index being present, a postcode in the query, and a locality-tier request — so the
 		// common (no-postcode / non-locality) path is untouched. A hit short-circuits: the postcode is
 		// an exact, high-confidence disambiguator, so we return the single geographic locality.
@@ -632,7 +634,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// SHAPE subset (placetype/bbox/primary — everything but the country scope) is kept separately
 		// because the admin-containment injection probe (#1717 stage 2) runs under the shape conds
 		// WITHOUT the country: bypassing a locale-inferred country scope for a qualifier-vouched
-		// candidate is the lever's whole point, and it is the one filter injection may cross.
+		// candidate is the change's whole point and the one filter injection may cross.
 		const filters: string[] = []
 		const filterParams: Array<string | number> = []
 		const shapeFilters: string[] = []
@@ -667,7 +669,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		}
 
 		// The re-reading guard (#1632, the #1626 rationale generalized to the caller): a probe whose surface
-		// is a token cut out of a longer classified span never NAMED an alias, so alias-keyed rows must not
+		// is a token taken out of a longer classified span never NAMED an alias, so alias-keyed rows must not
 		// answer it — 'Savile Row''s token 'Row' resolved Rhu, Scotland (585 km) through the village's
 		// historical-name alias key. Whole-input bare probes never set this, keeping the exonym recall the
 		// #1546 note protects (Москва's alias rows answer 'Moscow').
@@ -763,7 +765,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// the same on either backend. The country/placetype/bbox/region filters still apply via `probe`.
 			// Skipped when the index is absent (byte-stable for an older candidate.db).
 			//
-			// Gate: only when the name doesn't exist in the gazetteer AT ALL (unfiltered). A name that exists
+			// Condition: only when the name doesn't exist in the gazetteer AT ALL (unfiltered). A name that exists
 			// but missed under the active country/placetype/bbox filter is a FILTER miss, not a spelling miss
 			// — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
 			// pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
@@ -821,7 +823,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 		let rows = cascade(regionParentID)
 		// #1731: whether the rows the caller receives came from the UNSCOPED fallback below — the backend's
-		// interior gate the resolver-side trace (#1721) cannot otherwise see. Stamped onto every returned
+		// interior check the resolver-side trace (#1721) cannot otherwise see. Stamped onto every returned
 		// place, because the re-admission path is exactly where a wrong-instance namesake enters.
 		let regionScopeMiss = false
 
@@ -838,8 +840,8 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// holds 75001, not the one that holds a 75001-free namesake). The resolver sends this flag on locality
 		// lookups when `ResolveOpts.postcodeContainmentCoherence` is on. Strictly beneath the #741 postal-city
 		// short-circuit above — an exact (name, postcode) hit IS the answer and outranks any re-rank — and after
-		// the region-scope fallback, so it sees the final row set. Rows within the gate sort by distance first;
-		// the out-gate tail keeps its original population-first order. No in-gate row, or no postcode row in
+		// the region-scope fallback, so it sees the final row set. Rows within the radius sort by distance first;
+		// the out-of-radius tail keeps its original population-first order. No in-radius row, or no postcode row in
 		// the candidate table → unchanged (byte-identical to the flag-off path).
 		if (
 			query.postcode &&
@@ -850,32 +852,32 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			const anchor = this.#postcodeAnchor(query.postcode, query.country)
 
 			if (anchor) {
-				const inGate: Array<{ row: RankedRow<CandidateRow>; distanceKm: number }> = []
-				const outGate: RankedRow<CandidateRow>[] = []
+				const insideThreshold: Array<{ row: RankedRow<CandidateRow>; distanceKm: number }> = []
+				const outsideThreshold: RankedRow<CandidateRow>[] = []
 
 				for (const row of rows) {
 					const distanceKm = haversineKm(anchor.lat, anchor.lon, Number(row.latitude), Number(row.longitude))
 
-					if (distanceKm <= POSTCODE_CONTAINMENT_GATE_KM) {
-						inGate.push({ row, distanceKm })
+					if (distanceKm <= POSTCODE_CONTAINMENT_THRESHOLD_KM) {
+						insideThreshold.push({ row, distanceKm })
 					} else {
-						outGate.push(row)
+						outsideThreshold.push(row)
 					}
 				}
 
-				if (inGate.length) {
+				if (insideThreshold.length) {
 					// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
-					inGate.sort((a, b) => a.distanceKm - b.distanceKm)
-					rows = [...inGate.map(({ row }) => row), ...outGate]
+					insideThreshold.sort((a, b) => a.distanceKm - b.distanceKm)
+					rows = [...insideThreshold.map(({ row }) => row), ...outsideThreshold]
 				}
 			}
 		}
 
 		// Admin-containment re-rank (#1717 stage 2): LAST, on the final row set — the qualifier is the
 		// address's outermost explicit statement, so its partition outranks the postcode-proximity order
-		// above (contained rows keep that order among themselves). Capability-gated on the sidecar
+		// above (contained rows keep that order among themselves). Capability-conditioned on the sidecar
 		// (`#qualifierProbe`); when the artifact predates it, `regionQualifier` is ignored, no stamp is
-		// written, and the resolver walk reports the lever `unavailable`.
+		// written, and the resolver walk reports the change `unavailable`.
 		if (query.regionQualifier?.trim() && this.#qualifierProbe && this.#wantsLocality(query.placetype)) {
 			rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country, {
 				nameKey,
@@ -893,13 +895,13 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				id: Number(row.spr_id),
 				name: String(row.name ?? ""),
 				placetype: (this.#idToPlacetype.get(Number(row.placetype_id)) ?? "") as WOFPlacetype,
-				// Surfaced so the cascade can country-gate a postcode by the resolved locality (an ambiguous
+				// Surfaced so the cascade can country-restrict a postcode by the resolved locality (an ambiguous
 				// international postcode like 10115 = Berlin DE AND New York US must not out-resolve the city).
 				country: this.#idToCountry.get(Number(row.country_id)) ?? "",
 				lat: Number(row.latitude),
 				lon: Number(row.longitude),
 				// `score` stays the RAW population rank (`-neg_rank`) — it feeds the resolver walk's absolute
-				// `minWinningScore` gate (`resolve.ts`), which must see real prominence, never a penalized value.
+				// `minWinningScore` floor (`resolve.ts`), which must see real prominence, never a penalized value.
 				score: -Number(row.neg_rank),
 				// `prominence` carries the bounded cross-country primary preference (the effective, penalty-adjusted
 				// rank). The walk ORDERS candidates by `prominence ?? score` (`resolve.ts`), so this is what makes the
@@ -921,6 +923,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				// asked (a `regionQualifier` query over a sidecar-bearing artifact); its absence is what
 				// the resolver walk reports as `unavailable` (meaning-of-zero).
 				...(row.containedByQualifier === undefined ? {} : { containedByQualifier: row.containedByQualifier }),
+				// #1893 — the exemption's firing mark, carried only when the ranker actually spared this row
+				// the cross-country penalty (see RankedRow.variantExempted).
+				...(row.variantExempted ? { variantAliasExempted: true as const } : {}),
 				// The two-score split's carry (ROAD_TO_V9 §2). `referential` names the prominence this
 				// backend has always ordered by — `neg_rank` IS `-log10(population + 1)`, so the score and
 				// the sort key are two readings of the same number.
@@ -965,9 +970,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		return candidates
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
 	}
 }

package/{candidate-schema.ts → lib/candidate-schema.ts}

@@ -17,14 +17,14 @@
 
 import { sql, type Kysely } from "kysely"
 
-import type { CandidateAncestorsDatabase } from "./candidate-ancestors-schema.ts"
-import type { CapitalTable } from "./capital-schema.ts"
-import type { NameKey } from "./street-normalize.ts"
+import type { CandidateAncestorsDatabase } from "#candidate-ancestors-schema"
+import type { CapitalTable } from "#capital-schema"
+import type { NameKey } from "#street/normalize"
 
 /**
  * One candidate row. `name_key` + the four small int keys + `neg_rank` + `spr_id` form the clustered primary key; the
  * rest is denormalized so a resolve is one probe (no join to `spr`). Coordinates + bbox + name are nullable at the SQL
- * level (a postcode shard row may lack a bbox).
+ * level (a postcode extract row may lack a bbox).
  */
 export interface CandidateTable {
 	/**
@@ -99,7 +99,7 @@ export interface CandidateTable {
 	 *   core.
 	 *
 	 * NULL = no role detected. The column is WRITE-ONLY in this build generation: no ranking consumer reads it — a rank
-	 * penalty is its own future, D-rule-gated step with the `gloss_key` board as tripwire.
+	 * penalty is its own future, D-rule-conditional step with the `gloss_key` board as regression check.
 	 */
 	name_role: string | null
 }

package/{candidate-scoring.ts → lib/candidate-scoring.ts}

@@ -7,15 +7,15 @@
  *   ordered — the weighted-sum score and the exact-match tiering that ranks over it.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import { haversineKm } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { exactMatchIDs, officialNameIDs } from "./exact-match.ts"
-import { compareReferential, referentialFromPopulation } from "./place-importance-schema.ts"
-import type { RankingWeights } from "./ranking-weights.ts"
-import type { RawSearchRow } from "./search-fetch.ts"
-import type { FindPlaceQuery, PlaceCandidate, WOFPlacetype } from "./types.ts"
+import { exactMatchIDs, officialNameIDs } from "#exact-match"
+import { foldQueryText } from "#fts/index"
+import { compareReferential, referentialFromPopulation } from "#place-importance-schema"
+import { populationBoostTerm, type RankingWeights } from "#ranking-weights"
+import type { RawSearchRow } from "#search-fetch"
+import type { FindPlaceQuery, PlaceCandidate, WOFPlacetype } from "#types"
 
 /**
  * Score one raw FTS row into a `PlaceCandidate`: the weighted sum over the negated BM25 baseline, the placetype /
@@ -95,14 +95,8 @@ export function candidateFromSearchRow(
 
 	// Population boost: capped at `populationBoost` magnitude at `10^populationScaleLog10`
 	// people. Missing population → no contribution. Never penalizes.
-	let popTerm = 0
-
-	if (row.population !== null && row.population > 0 && weights.populationScaleLog10 > 0) {
-		const popLog = Math.log10(1 + row.population)
-		const popFraction = Math.min(1, popLog / weights.populationScaleLog10)
-		popTerm = weights.populationBoost * popFraction
-		score += popTerm
-	}
+	const popTerm = populationBoostTerm(row.population, weights)
+	score += popTerm
 
 	// Combined prominence for the exact-tier sort when proximity hints are present: population
 	// and nearness in the SAME additive units, so the map view / the user's location can win a
@@ -154,13 +148,13 @@ export function candidateFromSearchRow(
 }
 
 /**
- * Order `candidates` IN PLACE — the exact-match tier first when the shard can answer the name probes, otherwise plain
+ * Order `candidates` IN PLACE — the exact-match tier first when the extract can answer the name probes, otherwise plain
  * weighted-score order. Every candidate is stamped with its `exactMatch` flag on the way through.
  */
-export function rankCandidates(
+export function rankCandidates<DB>(
 	candidates: PlaceCandidate[],
 	options: {
-		db: DatabaseSync
+		db: DatabaseClient<DB>
 		schemaName: string
 		query: FindPlaceQuery
 		weights: RankingWeights
@@ -204,12 +198,11 @@ export function rankCandidates(
 			// widen recall, not to tie primaries. ME→Maine is untouched: 'ME' name-exact-matches
 			// nothing, so the alias sub-tier still decides there. Population orders within each
 			// sub-tier as before.
-			const norm = (v: string): string => v.toLowerCase().trim().replaceAll(/\s+/g, " ")
-			const needle = norm(query.text)
+			const needle = foldQueryText(query.text)
 
 			// #936 option 3: an OFFICIAL name (preferred form in an official language of the place's
 			// country, `names.official = 1`) counts as the place's own name for the sub-tier — "Åbo" is
-			// Turku's name, not merely its alias. Floor-gated on the holder's population (see the
+			// Turku's name, not merely its alias. Floor-conditioned on the holder's population (see the
 			// RankingWeights docstring for the measured 100k boundary). officialIDs ⊆ exactIDs by
 			// construction (official rows are names rows), so only the sub-tier KIND changes.
 			const officialIDs = weights.officialNameExact
@@ -226,7 +219,7 @@ export function rankCandidates(
 			const kind = (c: PlaceCandidate): number => {
 				if (!exactIDs.has(c.id as number)) return 0
 
-				if (norm(String(c.name ?? "")) === needle) return 2
+				if (foldQueryText(String(c.name ?? "")) === needle) return 2
 
 				return officialIDs?.has(c.id as number) ? 2 : 1
 			}

package/{capital-schema.ts → lib/capital-schema.ts}

@@ -14,13 +14,12 @@
  *   keeps the coordinate radius from promoting a capital's same-name neighbours (`capitals.ts`).
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
-import { tryParsingJSON } from "@mailwoman/core/objects"
+import { tryParsingJSON } from "@mailwoman/core/json"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { Kysely } from "kysely"
 
-import type { CapitalPoint } from "./capitals.ts"
-import { hasTable } from "./sqlite-utils.ts"
+import type { CapitalPoint } from "#capitals"
+import { hasTable } from "#sqlite-utils"
 
 /**
  * The table name the builder writes and the reader probes — one word, singular, matching the artifact's other reference
@@ -63,7 +62,7 @@ export async function createCapitalTable<DB extends { capital: CapitalTable }>(d
  * back to its next source rather than treating an old artifact as "no capitals" (the meaning-of-zero rule: a missing
  * table is UNMEASURED, an empty one is a finding).
  */
-export function readCapitalPoints(db: DatabaseSync): CapitalPoint[] | null {
+export function readCapitalPoints<DB>(db: DatabaseClient<DB>): CapitalPoint[] | null {
 	if (!hasTable(db, CAPITAL_TABLE)) return null
 
 	const points: CapitalPoint[] = []

package/{capitals.ts → lib/capitals.ts}

@@ -12,7 +12,7 @@
  *   Matching is an IDENTITY test with three conjuncts: same country, within
  *   {@link CAPITAL_MATCH_RADIUS_KM} of the reference point, and the candidate's own folded name a
  *   member of the reference entry's folded name set (name + romanization + the source's alternate
- *   names, so exonym rows — "Vienna" for Wien — still match). All three are load-bearing. The
+ *   names, so exonym rows — "Vienna" for Wien — still match). All three are required. The
  *   iteration-1 board run matched on country + coordinate alone, and the 25 km radius promoted
  *   capital-ADJACENT namesakes instead of capitals: North Salt Lake beside the Utah seat, a Gujarat
  *   Indiranagar beside Gandhinagar, Via delle Parti beside Perugia. The name set is what makes the
@@ -21,7 +21,7 @@
 
 import { haversineKm } from "@mailwoman/spatial"
 
-import { normalizeLocalityForKey } from "./street-normalize.ts"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
  * Capital status of one candidate: national capital, admin-1 seat, or neither. Numeric so the resolver's promotion can

package/{coincident-roles.ts → lib/coincident-roles.ts}

@@ -38,12 +38,13 @@
  *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import type { CoincidentLocality } from "@mailwoman/resolver"
 import { haversineKm } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import { allRows } from "./sqlite-utils.ts"
+import type { WOFDatabase } from "#schema"
+import { allRows } from "#sqlite-utils"
 
 /**
  * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
@@ -105,16 +106,12 @@ interface CandidateRow {
 	pop: number
 }
 
-function tableExists(db: DatabaseSync, name: string): boolean {
-	return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?").get(name)
-}
-
 /**
  * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
  * touches `spr`/`names`/`ancestors`. Idempotent.
  */
 export function buildCoincidentRoles(
-	db: DatabaseSync,
+	db: DatabaseClient<WOFDatabase>,
 	opts: BuildCoincidentRolesOpts = {}
 ): BuildCoincidentRolesResult {
 	const start = Date.now()
@@ -215,7 +212,7 @@ export function buildCoincidentRoles(
 /**
  * True iff the relation table exists. Used by the resolver to decide whether completion can run.
  */
-export function coincidentRolesExists(db: DatabaseSync): boolean {
+export function coincidentRolesExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, COINCIDENT_ROLES_TABLE)
 }
 
@@ -224,7 +221,7 @@ export function coincidentRolesExists(db: DatabaseSync): boolean {
  * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
  * map when the table is absent.
  */
-export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRole[]> {
+export function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, CoincidentRole[]> {
 	const map = new Map<number, CoincidentRole[]>()
 
 	if (!coincidentRolesExists(db)) return map
@@ -269,7 +266,7 @@ export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRol
  * {@link loadCoincidentRoles}, carrying the canonical name and coordinates each coincident locality resolves to.
  * Returns an empty map when the relation table is absent.
  */
-export function loadCoincidentLocalities(db: DatabaseSync): Map<number, CoincidentLocality[]> {
+export function loadCoincidentLocalities<DB>(db: DatabaseClient<DB>): Map<number, CoincidentLocality[]> {
 	const map = new Map<number, CoincidentLocality[]>()
 
 	if (coincidentRolesExists(db)) {

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

@@ -21,7 +21,7 @@
  *   source).
  */
 
-import type { FindPlaceQuery, PlaceCandidate } from "./types.ts"
+import type { FindPlaceQuery, PlaceCandidate } from "#types"
 
 /**
  * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
@@ -76,13 +76,13 @@ export const WORLD_DEFAULT: ResolvedConvention = {
 export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
 
 /**
- * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the shard
+ * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the extract
  * auto-detect all agree.
  */
 export const ADDRESS_CONVENTION_TABLE = "address_convention"
 
 /**
- * A named resolution primitive. Returns `null` to abstain (gate unmet / no data) → the dispatcher tries the next
+ * A named resolution primitive. Returns `null` to abstain (condition unmet / no data) → the dispatcher tries the next
  * strategy; returns an array (possibly empty) to claim the result.
  */
 export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>

package/{convention-schema.ts → lib/convention/schema.ts}

@@ -11,7 +11,7 @@
 
 import type { Kysely } from "kysely"
 
-import { ADDRESS_CONVENTION_TABLE } from "./convention.ts"
+import { ADDRESS_CONVENTION_TABLE } from "#convention/index"
 
 /**
  * One convention profile, keyed by the WOF admin polygon it attaches to.
@@ -49,7 +49,7 @@ export type ConventionSchemaHandle = Pick<Kysely<ConventionDatabase>, "schema">
 
 /**
  * Create `address_convention`. The table name comes from {@link ADDRESS_CONVENTION_TABLE} so the build script, the
- * runtime source, and the shard auto-detect cannot drift apart.
+ * runtime source, and the extract auto-detect cannot drift apart.
  */
 export async function createAddressConventionTable(db: ConventionSchemaHandle): Promise<void> {
 	await db.schema