@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/{ranking-weights.ts → lib/ranking-weights.ts}

@@ -5,7 +5,7 @@
  *
  *   The locality-ranking weights and their shipped defaults. Its own module because every value here is
  *   a measured tuning decision with its rationale attached — the block reads as a reference table, not
- *   as part of the lookup's control flow, and the tests import it directly to pin one lever at a time.
+ *   as part of the lookup's control flow, and the tests import it directly to pin one change at a time.
  */
 
 /**
@@ -96,7 +96,7 @@ export interface RankingWeights {
 	 * Fixes unscoped "Åbo" → Turku (its official Swedish name) over a hamlet literally named Åbo; population still orders
 	 * within the sub-tier, so Paris → Paris FR is untouched.
 	 *
-	 * Default true (operator-promoted 2026-07-03 after the pre-registered gate battery: four intended exonym flips —
+	 * Default true (operator-promoted 2026-07-03 after the pre-registered eval battery: four intended exonym flips —
 	 * Berne→Bern, Bruges→Brugge, Roma→Rome, Åbo→Turku — with the namesake/abbreviation rows and the US/FI panels
 	 * byte-identical). Requires a gazetteer carrying the #940 ingest bit — on older DBs without the `official` column the
 	 * probe fails soft and behavior is identical to the flag being off.
@@ -114,7 +114,7 @@ export interface RankingWeights {
 
 /**
  * The shipped weights. Every value is a measured decision — change one and re-run the resolver eval; the per-field docs
- * on {@link RankingWeights} say what each lever moves and what motivated its current value.
+ * on {@link RankingWeights} say what each change moves and what motivated its current value.
  */
 export const DEFAULT_WEIGHTS: RankingWeights = {
 	placetypeMatchBoost: 0.5,
@@ -142,7 +142,33 @@ export const DEFAULT_WEIGHTS: RankingWeights = {
 	// consulted — keeps population as an intra-tier prominence tiebreaker, not a cross-tier promoter.
 	// Fixes the 2-letter-region-abbrev bug ("ME" → Maine, not the more-populous Missouri).
 	exactMatchTiering: true,
-	// #936 option 3 — promoted default-ON 2026-07-03 (gate battery PASS; see the RankingWeights docstring).
+	// #936 option 3 — promoted default-ON 2026-07-03 (eval battery PASS; see the RankingWeights docstring).
 	officialNameExact: true,
 	officialNameExactFloor: 100_000,
 }
+
+/**
+ * The population contribution as a 0..1 fraction: `min(1, log10(1 + population) / populationScaleLog10)`. Zero for an
+ * absent or non-positive population — and zero for a non-positive scale, so a magnitude never carries its own absence.
+ * The coordinate-first locality path consumes this fraction directly; {@link populationBoostTerm} scales it.
+ */
+export function populationScaleTerm(
+	population: number | null | undefined,
+	weights: Pick<RankingWeights, "populationScaleLog10">
+): number {
+	if (population == null || population <= 0 || weights.populationScaleLog10 <= 0) return 0
+
+	return Math.min(1, Math.log10(1 + population) / weights.populationScaleLog10)
+}
+
+/**
+ * The additive population boost: `populationBoost * populationScaleTerm(...)`, capped at `populationBoost` magnitude at
+ * `10^populationScaleLog10` people. Missing population contributes 0 — never a penalty. The one formula behind the Node
+ * weighted sum and the WASM re-rank, so the two backends cannot drift.
+ */
+export function populationBoostTerm(
+	population: number | null | undefined,
+	weights: Pick<RankingWeights, "populationBoost" | "populationScaleLog10">
+): number {
+	return weights.populationBoost * populationScaleTerm(population, weights)
+}

package/lib/region-keys.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The comparable-key expansion for a parsed REGION qualifier — one function, both consumers (the
+ *   #861 rule). The admin-coherence verdicts (`mailwoman/admin-coherence.ts`) fold a qualifier and a
+ *   winner-ancestry name through this to decide `confirmed`/`contradicted`; the candidate backend's
+ *   admin-containment re-rank (#1717 stage 2, `candidate-lookup.ts`) folds the same qualifier through
+ *   it to find the qualifier's own region-class rows in the candidate table. A check that says
+ *   `contradicted` and a re-rank that cannot find the qualifier would otherwise be two readings of
+ *   one string that silently disagree — the exact drift the shared-function rule exists to prevent.
+ *
+ *   Lives HERE rather than in `mailwoman` because the dependency points this way: `mailwoman`
+ *   depends on `@mailwoman/resolver-wof-sqlite` (which owns the fold and already depends on codex),
+ *   never the reverse.
+ */
+
+import { matchSubdivision, matchSubdivisionIn } from "@mailwoman/codex/country"
+
+import { normalizeLocalityForKey } from "#street/normalize"
+
+/**
+ * The ancestry placetypes that answer for a parsed `region` qualifier — WOF's admin band between country and locality.
+ * Deliberately the whole band: a qualifier stated at any grain ("Lancashire", a ceremonial county; "Thüringen", a Land)
+ * may confirm against whichever level the backend stored, and `contradicted` requires the entire band to miss, so
+ * widening the band only ever makes the check more conservative.
+ */
+export const REGION_CLASS_PLACETYPES: ReadonlySet<string> = new Set(["region", "macroregion", "county", "macrocounty"])
+
+/**
+ * County-style qualifier prefixes stripped to produce a comparison VARIANT. Ireland writes `Co. Westmeath` where WOF
+ * stores `Westmeath`, so the prefix defeats the fold and every Irish county qualifier read `contradicted` on the first
+ * board census (2026-08-17, five rows). The stripped form is ADDED to the key set, never substituted — `County Durham`
+ * is a real name whose stripped variant simply also matches, and a set union can only widen confirmation, so the
+ * closure is monotone: `contradicted → confirmed` is the only movement it can cause.
+ */
+const COUNTY_QUALIFIER_PREFIXES = ["county", "co.", "co"] as const
+
+/**
+ * Trailing admin-qualifier words, the suffix sibling of the prefix above: `San José Province` (CR board row) folds
+ * against stored `San José` only with the word removed. Same monotone rule — the stripped form joins the set, never
+ * replaces the original.
+ */
+const ADMIN_QUALIFIER_SUFFIXES = ["province", "prov.", "prov"] as const
+
+function withoutPrefix(value: string, prefixes: readonly string[]): string {
+	const folded = value.toLowerCase()
+
+	for (const prefix of prefixes) {
+		if (!folded.startsWith(prefix) || !/\s/u.test(value[prefix.length] ?? "")) continue
+
+		let offset = prefix.length
+
+		while (/\s/u.test(value[offset] ?? "")) {
+			offset++
+		}
+
+		return value.slice(offset)
+	}
+
+	return value
+}
+
+function withoutSuffix(value: string, suffixes: readonly string[]): string {
+	const folded = value.toLowerCase()
+
+	for (const suffix of suffixes) {
+		const offset = value.length - suffix.length
+
+		if (offset <= 0 || !folded.endsWith(suffix) || !/\s/u.test(value[offset - 1] ?? "")) continue
+
+		let end = offset
+
+		while (end > 0 && /\s/u.test(value[end - 1] ?? "")) {
+			end--
+		}
+
+		return value.slice(0, end)
+	}
+
+	return value
+}
+
+/**
+ * The comparable keys a region string expands to: its own fold (the shared candidate.db `name_key` normalizer,
+ * {@link normalizeLocalityForKey} — build side and check side agree by construction); a county-prefix-stripped variant;
+ * the codex subdivision expansions — the disjoint US+CA table always, plus the COUNTRY-SCOPED table when the caller
+ * knows a country (`WA` under AU is Western Australia; under US, Washington — the collision that keeps AU out of the
+ * unscoped table). Every expansion lands the canonical name and code folds in the set, so `IL`/`Illinois` and
+ * `WA`/`Western Australia` meet from either side.
+ */
+export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
+	const keys = new Set([normalizeLocalityForKey(value)])
+
+	for (const stripped of [
+		withoutPrefix(value, COUNTY_QUALIFIER_PREFIXES),
+		withoutSuffix(value, ADMIN_QUALIFIER_SUFFIXES),
+	]) {
+		if (stripped !== value && stripped.trim()) {
+			keys.add(normalizeLocalityForKey(stripped))
+		}
+	}
+
+	const expansions = [matchSubdivision(value), countryAlpha2 ? matchSubdivisionIn(countryAlpha2, value) : null]
+
+	for (const subdivision of expansions) {
+		if (subdivision) {
+			keys.add(normalizeLocalityForKey(subdivision.name))
+			keys.add(normalizeLocalityForKey(subdivision.code))
+		}
+	}
+
+	// The empty fold stays IN the set on purpose — the admin-coherence verdicts have always compared
+	// the empty key (two empty-folding strings intersect → `confirmed`), and this move must not shift
+	// a verdict. A consumer probing a table by key filters the empty string out itself.
+	return keys
+}
+
+/**
+ * The PROBE-side expansion for a region qualifier — {@link regionKeys} plus the county-PREFIXED variant of every key.
+ *
+ * The verdict implementation intersects two {@link regionKeys} SETS, so `Co. Donegal` meets stored `County Donegal` at
+ * the shared stripped key `donegal`. A table probe is one-sided: it matches the STORED fold verbatim, and WOF stores
+ * Irish counties under `county donegal` with no bare `donegal` key (measured on the shipped candidate.db — the
+ * qualifier probe missed every Irish county until this variant landed). Adding `county <key>` restores the
+ * two-sidedness for the one stored-form family with an evidenced case; the union is monotone (a wider qualifier set can
+ * only find more BEARERS, each of which must still genuinely contain a candidate before anything moves). The suffix
+ * sibling (`<key> province`) is deliberately absent — no stored-form case has been evidenced, and a change without a
+ * board does not get built.
+ */
+export function regionQualifierProbeKeys(value: string, countryAlpha2?: string): Set<string> {
+	const keys = regionKeys(value, countryAlpha2)
+	// Snapshot before widening: the loop adds `county <key>` members that must not themselves be revisited.
+	const bare = [...keys]
+
+	for (const key of bare) {
+		if (key && !key.startsWith("county ")) {
+			keys.add(`county ${key}`)
+		}
+	}
+
+	return keys
+}

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

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   Reverse geocoding (#484): `(lat, lon)` → the containing admin hierarchy. Assembly over existing
- *   machinery, per the 2026-06-11 scoping notes:
+ *   implementation, per the 2026-06-11 scoping notes:
  *
  *   1. **Candidate fetch** — the admin DB's `place_bbox` R*Tree (built by `fts.ts`) for places whose
  *        bbox contains the point, smallest-area-first (so the FIRST polygon confirmation is the
@@ -28,14 +28,16 @@
  *   says so per result rather than pretending.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { tryParsingJSON } from "@mailwoman/core/json"
+import { bboxAround, geometryContains, haversineKm, type ParsedGeometry } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
-
-import { ancestorLineage, placetypeDepth } from "./ancestry.ts"
-import { PLACE_BBOX_TABLE } from "./fts.ts"
-import { geometryContains, haversineKm, type GeojsonGeometry } from "./geo.ts"
-import type { PlaceCandidate, WOFPlacetype } from "./types.ts"
+import { ancestorLineage, placetypeDepth } from "#ancestry/index"
+import { PLACE_BBOX_TABLE } from "#fts/index"
+import type { WOFDatabase } from "#schema"
+import { allRows } from "#sqlite-utils"
+import type { PlaceCandidate, WOFPlacetype } from "#types"
 
 /**
  * Largest absolute latitude in WGS-84 degrees.
@@ -79,7 +81,7 @@ export interface WOFReverseGeocoderOpts {
 	/**
 	 * Pre-opened admin DB — primarily for tests against an inline fixture.
 	 */
-	adminDatabase?: DatabaseSync
+	adminDatabase?: DatabaseClient<WOFDatabase>
 	/**
 	 * Path to the polygon sidecar DB (`wof-polygons.db`, table `polygons(id, geom)`). OPTIONAL — without it every result
 	 * is `containment: "approximate"` (centroid-only mode). Mutually exclusive with `polygonDatabase`.
@@ -88,7 +90,7 @@ export interface WOFReverseGeocoderOpts {
 	/**
 	 * Pre-opened polygon DB — primarily for tests.
 	 */
-	polygonDatabase?: DatabaseSync
+	polygonDatabase?: DatabaseClient<WOFDatabase>
 }
 
 export interface ReverseGeocodeOpts {
@@ -159,9 +161,9 @@ function toPlaceCandidate(row: CandidateRow, distanceKm?: number): PlaceCandidat
 }
 
 export class WOFReverseGeocoder implements Disposable {
-	readonly #admin: DatabaseSync
+	readonly #admin: DatabaseClient<WOFDatabase>
 	readonly #ownsAdmin: boolean
-	readonly #polygons: DatabaseSync | null
+	readonly #polygons: DatabaseClient<WOFDatabase> | null
 	readonly #ownsPolygons: boolean
 	/**
 	 * Parsed-geometry cache. Reverse queries cluster geographically (an eval run hits the same ~15 county polygons 1400
@@ -169,7 +171,7 @@ export class WOFReverseGeocoder implements Disposable {
 	 * LRU-tracked; the polygons are DP-simplified and small, the cap exists only to keep a long-lived server process
 	 * honest.
 	 */
-	readonly #geometryCache = new Map<number, GeojsonGeometry | null>()
+	readonly #geometryCache = new Map<number, ParsedGeometry | null>()
 	static readonly #GEOMETRY_CACHE_CAP = 4096
 
 	constructor(opts: WOFReverseGeocoderOpts) {
@@ -185,38 +187,29 @@ export class WOFReverseGeocoder implements Disposable {
 			throw new Error("WOFReverseGeocoder: pass either `polygonDatabase` or `polygonDBPath`, not both")
 		}
 
-		this.#admin = opts.adminDatabase ?? new DatabaseSync(opts.adminDBPath!, { readOnly: true })
+		this.#admin = opts.adminDatabase ?? new DatabaseClient<WOFDatabase>(opts.adminDBPath!, { readOnly: true })
 		this.#ownsAdmin = !opts.adminDatabase
 
 		this.#polygons =
-			opts.polygonDatabase ?? (opts.polygonDBPath ? new DatabaseSync(opts.polygonDBPath, { readOnly: true }) : null)
+			opts.polygonDatabase ??
+			(opts.polygonDBPath ? new DatabaseClient<WOFDatabase>(opts.polygonDBPath, { readOnly: true }) : null)
 
 		this.#ownsPolygons = !opts.polygonDatabase && Boolean(opts.polygonDBPath)
 
 		// Fail loudly up front — the R*Tree is a build artifact, not part of the upstream WOF
 		// distribution, and a missing index would otherwise surface as an opaque SQL error per query.
-		const hasBbox = this.#admin
-			.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
-			.get(PLACE_BBOX_TABLE)
-
-		if (!hasBbox) {
+		if (!tableExists(this.#admin, PLACE_BBOX_TABLE)) {
 			throw new Error(
 				`WOFReverseGeocoder: the admin DB has no \`${PLACE_BBOX_TABLE}\` R*Tree. Build it with ` +
 					"`mailwoman gazetteer build fts <path-to-wof.db>` (see resolver-wof-sqlite/README.md)."
 			)
 		}
 
-		if (this.#polygons) {
-			const hasPolygons = this.#polygons
-				.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'polygons'`)
-				.get()
-
-			if (!hasPolygons) {
-				throw new Error(
-					"WOFReverseGeocoder: the polygon DB has no `polygons` table. Expected a `wof-polygons.db` " +
-						"built by scripts/build-wof-polygons.mjs."
-				)
-			}
+		if (this.#polygons && !tableExists(this.#polygons, "polygons")) {
+			throw new Error(
+				"WOFReverseGeocoder: the polygon DB has no `polygons` table. Expected a `wof-polygons.db` " +
+					"built by scripts/build-wof-polygons.mjs."
+			)
 		}
 	}
 
@@ -389,16 +382,17 @@ export class WOFReverseGeocoder implements Disposable {
 
 		params.push(opts.maxCandidates ?? DEFAULT_MAX_CANDIDATES)
 
-		return this.#admin
-			.prepare(
+		return allRows<CandidateRow>(
+			this.#admin.prepare(
 				`SELECT spr.id AS id, spr.name AS name, spr.placetype AS placetype, spr.country AS country,
 					spr.parent_id AS parent_id, spr.latitude AS lat, spr.longitude AS lon
 				FROM ${PLACE_BBOX_TABLE} bbox JOIN spr ON spr.id = bbox.id
 				WHERE ${where.join(" AND ")}
 				ORDER BY (bbox.max_lat - bbox.min_lat) * (bbox.max_lon - bbox.min_lon) ASC
 				LIMIT ?`
-			)
-			.all(...params) as unknown as CandidateRow[]
+			),
+			...params
+		)
 	}
 
 	/**
@@ -413,30 +407,29 @@ export class WOFReverseGeocoder implements Disposable {
 		lon: number,
 		maxApproximateKm: number
 	): CandidateRow[] {
-		const windowDeg = (maxApproximateKm * 4) / 111
+		const window = bboxAround(lat, lon, maxApproximateKm * 4)
 
-		return this.#admin
-			.prepare(
+		return allRows<CandidateRow>(
+			this.#admin.prepare(
 				`SELECT s.id AS id, s.name AS name, s.placetype AS placetype, s.country AS country,
 					s.parent_id AS parent_id, s.latitude AS lat, s.longitude AS lon
 				FROM ancestors a JOIN spr s ON s.id = a.id
 				WHERE a.ancestor_id = ? AND s.placetype = ? AND s.is_current != 0 AND s.is_deprecated = 0
 					AND s.latitude BETWEEN ? AND ? AND s.longitude BETWEEN ? AND ?`
-			)
-			.all(
-				parentID,
-				placetype,
-				lat - windowDeg,
-				lat + windowDeg,
-				lon - windowDeg,
-				lon + windowDeg
-			) as unknown as CandidateRow[]
+			),
+			parentID,
+			placetype,
+			window.minLat,
+			window.maxLat,
+			window.minLon,
+			window.maxLon
+		)
 	}
 
 	/**
 	 * Parsed GeoJSON geometry for a WOF id, or null when absent / unparseable / no polygon DB.
 	 */
-	#geometry(id: number): GeojsonGeometry | null {
+	#geometry(id: number): ParsedGeometry | null {
 		if (!this.#polygons) return null
 		const cached = this.#geometryCache.get(id)
 
@@ -448,24 +441,20 @@ export class WOFReverseGeocoder implements Disposable {
 
 		const row = this.#polygons.prepare(`SELECT geom FROM polygons WHERE id = ?`).get(id) as { geom: string } | undefined
 		// Malformed row parses to null — treat as no-polygon rather than failing the query.
-		const geometry = row ? tryParsingJSON<GeojsonGeometry>(row.geom) : null
+		const geometry = row ? tryParsingJSON<ParsedGeometry>(row.geom) : null
 
 		this.#geometryCache.set(id, geometry)
 
 		return geometry
 	}
 
-	close(): void {
+	[Symbol.dispose](): void {
 		if (this.#ownsAdmin) {
-			this.#admin.close()
+			this.#admin.destroy()
 		}
 
 		if (this.#ownsPolygons) {
-			this.#polygons?.close()
+			this.#polygons?.destroy()
 		}
 	}
-
-	[Symbol.dispose](): void {
-		this.close()
-	}
 }

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

@@ -159,11 +159,21 @@ export interface CoincidentRolesTable {
 
 /**
  * The full schema we hand to `Kysely<WOFDatabase>` / `new DatabaseClient<WOFDatabase>(...)`. Tables not listed here
- * will fail type-checked queries — by design. The reader ({@link WOFSqlitePlaceLookup}) already consumes this; the
+ * will fail type-checked queries — by design. The reader ({@link WOFSQLitePlaceLookup}) already consumes this; the
  * build/augment WRITERS adopt it so a column rename is a compile error on both sides (the drift that bit the corpus
  * TIGER adapter).
  */
+/**
+ * The provenance row every built extract carries: source fingerprints travelling WITH the database rather than in a
+ * document that can drift from it. Written by the postcode builders in `mailwoman/gazetteer-pipeline`.
+ */
+export interface ExtractMetaTable {
+	key: string
+	value: string | null
+}
+
 export interface WOFDatabase {
+	meta: ExtractMetaTable
 	place_search: PlaceSearchTable
 	spr: SprTable
 	names: NamesTable