@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{primary-preference.ts → lib/primary-preference.ts}

@@ -11,7 +11,7 @@
  *   Only type imports and arithmetic live here: anything with a `node:` import stays out.
  */
 
-import type { CandidateTable } from "./candidate-schema.ts"
+import type { CandidateTable } from "#candidate-schema"
 
 /**
  * The row shape the re-rank needs. `is_primary` is optional: a reader over an artifact vintage that predates the column
@@ -54,8 +54,8 @@ const SEAT_PLACETYPE = "locality"
 /**
  * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
  * worldwide) are re-ranked in-process, so the probe fetches this many (population-ordered) before the re-rank rather
- * than the caller's small `limit`, ensuring the intended primary isn't cut below the fold by a cluster of more-populous
- * foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ * than the caller's small `limit`, ensuring the intended primary isn't pushed below the fold by a cluster of
+ * more-populous foreign aliases. Bounded and small — a single contiguous B-tree scan.
  */
 export const RERANK_FETCH = 64
 
@@ -66,7 +66,7 @@ export type RankedRow<R> = R & {
 	/**
 	 * `neg_rank` plus the bounded cross-country alias penalty — the value the row is ORDERED by, and the base the emitted
 	 * `prominence` is derived from (so the resolver walk's `prominence ?? score` sort, `resolve.ts`, agrees with this
-	 * order; the raw `score`/`neg_rank` is left intact for the walk's `minWinningScore` gate).
+	 * order; the raw `score`/`neg_rank` is left intact for the walk's `minWinningScore` floor).
 	 */
 	effectiveNegRank: number
 	/**
@@ -93,6 +93,14 @@ export type RankedRow<R> = R & {
 	 * was never asked, never "not contained".
 	 */
 	containedByQualifier?: boolean
+	/**
+	 * The #1882 exemption's firing mark (#1893): this row would have taken the cross-country alias penalty and
+	 * `exemptVariantAliases` prevented it. PRESENT only when the exemption changed this row's treatment; absent on every
+	 * row it merely inspected — an in-country variant, a primary, a set with no foreign top primary. The winner-level
+	 * receipt downstream (`mechanism_fired_on.variant_alias_exemption`) counts this mark only when it survives onto the
+	 * selected candidate.
+	 */
+	variantExempted?: true
 }
 
 /**
@@ -126,7 +134,7 @@ export type RankedRow<R> = R & {
  * the fame prior overrides by design; a probe with NO placetype filter (the browser cascade's last resort, the dev
  * lookup tools) presents the full tie and this term is all that breaks it.
  *
- * BOTH GATES ARE LOAD-BEARING, and a plain "finer placetype wins" measured wrong before this shape was settled: it
+ * BOTH CONDITIONS ARE required, and a plain "finer placetype wins" measured wrong before this shape was settled: it
  * moved the top slot on 11,377 keys in `candidate.db`, of which only 722 were the seat/district duplicate. The rest
  * were contests between genuinely distinct places that merely tie — 2,885 `locality → neighbourhood` (a bare city name
  * losing to a same-named hood), 2,973 `region → county`, 2,662 `postalcode → locality` — and 7,179 of the 11,377 sat at
@@ -162,17 +170,28 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 	// query is naming THAT place, not colliding with it; the penalty exists for the coincidental-collision
 	// class ("Çançun"/`cancun`), which the detector's measured threshold keeps un-stamped. An artifact
 	// predating the role column carries no 'variant' rows, so the flag no-ops there by construction.
+	const wouldPenalize = (r: R): boolean =>
+		typeof topCountry === "number" && r.is_primary !== 1 && r.country_id !== topCountry
+
 	const isCrossCountryAlias = (r: R): boolean =>
-		typeof topCountry === "number" &&
-		r.is_primary !== 1 &&
-		r.country_id !== topCountry &&
-		!(exemptVariantAliases && r.name_role === "variant")
+		wouldPenalize(r) && !(exemptVariantAliases && r.name_role === "variant")
 
 	const annotate = (r: R): RankedRow<R> => {
 		const penalized = isCrossCountryAlias(r)
 		const effectiveNegRank = r.neg_rank + (penalized ? delta : 0)
 
-		return { ...r, effectiveNegRank, demoted: penalized && effectiveNegRank > topPrimary!.neg_rank }
+		// The firing mark (#1893): this row WOULD have taken the cross-country penalty and the exemption
+		// prevented it — conditions the winner-level receipt needs, computed where the decision is made. A
+		// variant row that was in-country, primary, or keyed under a set with no foreign primary never
+		// fired, and stays unmarked.
+		const exempted = !penalized && exemptVariantAliases && r.name_role === "variant" && wouldPenalize(r)
+
+		return {
+			...r,
+			effectiveNegRank,
+			demoted: penalized && effectiveNegRank > topPrimary!.neg_rank,
+			...(exempted ? { variantExempted: true as const } : {}),
+		}
 	}
 
 	// 1 for a populated-place row that can BE a district's seat, 0 for everything else — no code map, no

package/{proximity-rerank.ts → lib/proximity-rerank.ts}

@@ -8,12 +8,12 @@
  *   filter. Byte-identical to plain population order when no bias is passed.
  *
  *   This lives in its own platform-free module because it has to run identically in two places: the Node candidate
- *   reader and the browser byte-range twin. That is the #861 server↔demo parity contract, and it is the second thing
+ *   reader and the browser byte-range twin. That is the #861 server↔demo parity contract and the second thing
  *   here held by construction rather than by comment (`primary-preference.ts` was the first). Constants alone were not
  *   enough — the two copies agreed on every literal and still diverged on which field the population term reads and on
  *   whether the combined value is written back, which is the half that actually decides the answer.
  *
- *   Two properties are load-bearing and easy to lose when transcribing:
+ *   Two properties are required and easy to lose when transcribing:
  *
  *   1. The population base is `prominence ?? score`, NOT `score`. `prominence` carries the bounded cross-country
  *      primary preference, so reading raw score lets a coincidental foreign alias ride population back over a primary

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/{region-keys.ts → lib/region-keys.ts}

@@ -18,7 +18,7 @@
 
 import { matchSubdivision, matchSubdivisionIn } from "@mailwoman/codex/country"
 
-import { normalizeLocalityForKey } from "./street-normalize.ts"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
  * The ancestry placetypes that answer for a parsed `region` qualifier — WOF's admin band between country and locality.
@@ -120,14 +120,14 @@ export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
 /**
  * The PROBE-side expansion for a region qualifier — {@link regionKeys} plus the county-PREFIXED variant of every key.
  *
- * The verdict machinery 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 lever without a board does not get
- * built.
+ * 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)

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,15 +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 { geometryContains, haversineKm, type GeojsonGeometry } from "@mailwoman/spatial"
-
-import { ancestorLineage, placetypeDepth } from "./ancestry.ts"
-import { PLACE_BBOX_TABLE } from "./fts.ts"
-import { allRows } from "./sqlite-utils.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.
@@ -80,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`.
@@ -89,7 +90,7 @@ export interface WOFReverseGeocoderOpts {
 	/**
 	 * Pre-opened polygon DB — primarily for tests.
 	 */
-	polygonDatabase?: DatabaseSync
+	polygonDatabase?: DatabaseClient<WOFDatabase>
 }
 
 export interface ReverseGeocodeOpts {
@@ -160,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
@@ -170,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) {
@@ -186,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."
+			)
 		}
 	}
 
@@ -415,7 +407,7 @@ export class WOFReverseGeocoder implements Disposable {
 		lon: number,
 		maxApproximateKm: number
 	): CandidateRow[] {
-		const windowDeg = (maxApproximateKm * 4) / 111
+		const window = bboxAround(lat, lon, maxApproximateKm * 4)
 
 		return allRows<CandidateRow>(
 			this.#admin.prepare(
@@ -427,17 +419,17 @@ export class WOFReverseGeocoder implements Disposable {
 			),
 			parentID,
 			placetype,
-			lat - windowDeg,
-			lat + windowDeg,
-			lon - windowDeg,
-			lon + windowDeg
+			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)
 
@@ -449,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}

@@ -163,7 +163,17 @@ export interface CoincidentRolesTable {
  * 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

package/{search-fetch.ts → lib/search-fetch.ts}

@@ -12,14 +12,13 @@
  *   whole corpus, so an exact haversine over the survivors is cheap.
  */
 
-import type { DatabaseSync, SQLInputValue } from "node:sqlite"
-
 import { bboxAround } from "@mailwoman/spatial"
+import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
 
-import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "./fts.ts"
-import type { RankingWeights } from "./ranking-weights.ts"
-import { allRows } from "./sqlite-utils.ts"
-import type { FindPlaceQuery, WOFPlacetype } from "./types.ts"
+import { PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE } from "#fts/index"
+import type { RankingWeights } from "#ranking-weights"
+import { allRows } from "#sqlite-utils"
+import type { FindPlaceQuery, WOFPlacetype } from "#types"
 
 /**
  * Query length at or below which the FTS window is widened. A two- or three-character query is almost always a region
@@ -60,19 +59,21 @@ export interface RawSearchRow {
 	max_longitude: number | null
 	population: number | null // from the place_population aux table; null when missing
 	/**
-	 * From `place_importance.encyclopedic` when the shard's table carries the two-score split columns. NULL means the
-	 * place has no Wikipedia article, or the shard predates the split — absence either way, and never 0 (ROAD_TO_V9 §2).
+	 * From `place_importance.encyclopedic` when the extract's table carries the two-score split columns. NULL means the
+	 * place has no Wikipedia article, or the extract predates the split — absence either way, and never 0 (ROAD_TO_V9
+	 * §2).
 	 */
 	encyclopedic: number | null
 }
 
 /**
- * Fetch the raw candidate rows for a name match on one shard: the BM25-ordered window over `place_search` (widened for
- * short queries), plus the population-ordered companion fetch that keeps the prominent holders of a name pool-complete.
- * `schemaName` is the routed shard's bare schema name — validated at construction, so it is interpolated directly.
+ * Fetch the raw candidate rows for a name match on one extract: the BM25-ordered window over `place_search` (widened
+ * for short queries), plus the population-ordered companion fetch that keeps the prominent holders of a name
+ * pool-complete. `schemaName` is the routed extract's bare schema name — validated at construction, so it is
+ * interpolated directly.
  */
-export function fetchSearchRows(options: {
-	db: DatabaseSync
+export function fetchSearchRows<DB>(options: {
+	db: DatabaseClient<DB>
 	schemaName: string
 	query: FindPlaceQuery
 	placetypes: WOFPlacetype[] | null
@@ -112,7 +113,7 @@ export function fetchSearchRows(options: {
 	// spr table but should never win a contemporary lookup. `is_current = 0` is the only WOF
 	// value that means "not current"; both `-1` (modern) and `1` (legacy) mean current. See #91.
 	// Note: with schema-qualified FROM the bare `place_search` reference in MATCH resolves to
-	// the FROM table — required by FTS5 parser, see sharding.ts header comment.
+	// the FROM table — required by FTS5 parser, see extracts.ts header comment.
 	const where: string[] = ["place_search MATCH ?", "spr.is_current != 0", "spr.is_deprecated = 0"]
 	const params: SQLInputValue[] = [ftsQuery]
 
@@ -132,10 +133,10 @@ export function fetchSearchRows(options: {
 	}
 
 	// Bbox + near-with-radius are SQL-level filters via the R*Tree. We only emit the JOIN when
-	// the active shard has the R*Tree; missing-but-requested is silently treated as no-bbox-
-	// filter so legacy DBs / shards-without-bbox don't crash.
-	const shardHasBbox = hasBboxIndex.get(sch) === true
-	const useBboxJoin = (query.bbox || query.near?.maxDistanceKm !== undefined) && shardHasBbox
+	// the active extract has the R*Tree; missing-but-requested is silently treated as no-bbox-
+	// filter so legacy DBs / extracts-without-bbox don't crash.
+	const extractHasBbox = hasBboxIndex.get(sch) === true
+	const useBboxJoin = (query.bbox || query.near?.maxDistanceKm !== undefined) && extractHasBbox
 	let joinClause = `JOIN ${sch}.spr ON spr.id = place_search.wof_id`
 
 	if (useBboxJoin) {
@@ -146,21 +147,21 @@ export function fetchSearchRows(options: {
 		params.push(filterBox.maxLat, filterBox.minLat, filterBox.maxLon, filterBox.minLon)
 	}
 
-	// LEFT JOIN the population aux table when present. Missing-on-this-shard means the SELECT
+	// LEFT JOIN the population aux table when present. Missing-on-this-extract means the SELECT
 	// just doesn't include the population column; the post-scoring loop treats it as 0.
-	const shardHasPopulation = hasPopulationIndex.get(sch) === true
+	const extractHasPopulation = hasPopulationIndex.get(sch) === true
 
-	const populationSelect = shardHasPopulation
+	const populationSelect = extractHasPopulation
 		? `${PLACE_POPULATION_TABLE}.population AS population`
 		: `NULL AS population`
 
-	const populationJoin = shardHasPopulation
+	const populationJoin = extractHasPopulation
 		? `LEFT JOIN ${sch}.${PLACE_POPULATION_TABLE} ON ${PLACE_POPULATION_TABLE}.id = spr.id`
 		: ""
 
 	// The encyclopedic score is CARRIED, never ranked on (ROAD_TO_V9 §2, ratified 2026-08-06) — it
-	// appears in the SELECT and in no ORDER BY, here or in the companion fetch below. Gated on the
-	// split column, so a pre-split shard emits a literal NULL and builds no join at all.
+	// appears in the SELECT and in no ORDER BY, here or in the companion fetch below. Conditioned on the
+	// split column, so a pre-split extract emits a literal NULL and builds no join at all.
 	const { select: encyclopedicSelect, join: encyclopedicJoin } = encyclopedicClauses.get(sch)!
 
 	// Push the population boost into the ORDER BY when the index is available, so famous places
@@ -177,12 +178,12 @@ export function fetchSearchRows(options: {
 	// column weighted to zero — no weighting isolates name relevance in this schema. The famous-
 	// holder guarantee lives in the population-ordered companion fetch below instead, and the
 	// exact tier breaks ties by population in the post-scoring sort.
-	const orderByExpr = shardHasPopulation
+	const orderByExpr = extractHasPopulation
 		? `(bm25(place_search) - ? * MIN(1.0, COALESCE(log10(1.0 + ${PLACE_POPULATION_TABLE}.population), 0) / ?))`
 		: "bm25(place_search)"
 
 	// Schema-qualified FROM with bare-name MATCH — required syntax for FTS5 on attached schemas.
-	// See sharding.ts header for the gotcha that drove this design.
+	// See extracts.ts header for the failure mode that drove this design.
 	const stmt = db.prepare(`
 		SELECT
 			spr.id AS id,
@@ -205,7 +206,7 @@ export function fetchSearchRows(options: {
 		LIMIT ?
 	`)
 
-	if (shardHasPopulation) {
+	if (extractHasPopulation) {
 		params.push(weights.populationBoost, weights.populationScaleLog10)
 	}
 
@@ -219,7 +220,7 @@ export function fetchSearchRows(options: {
 	// vs a +4.0 boost cap), so FR Paris never even reaches post-scoring. This fetch makes the
 	// prominent holders of a name pool-complete BY CONSTRUCTION; the exact-tier sort below
 	// decides whether they win. Skipped without a population index (nothing to order by).
-	if (shardHasPopulation) {
+	if (extractHasPopulation) {
 		const popStmt = db.prepare(`
 			SELECT
 				spr.id AS id,

package/{sqlite-convention-source.ts → lib/sqlite-convention-source.ts}

@@ -8,21 +8,20 @@
  *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
  *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
  *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
- *   value in memory `feedback-no-load-bearing-trivia`).
+ *   value in memory `feedback-no-irrelevant-trivia`).
  *
  *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
  *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
  *   swallowed.
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import { tryParsingJSON } from "@mailwoman/core/json"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { tryParsingJSON } from "@mailwoman/core/objects"
+import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "#convention/index"
 
-import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "./convention.ts"
-
-export class SqliteConventionSource implements ConventionSource {
-	readonly #db: DatabaseSync
+export class SqliteConventionSource<DB> implements ConventionSource {
+	readonly #db: DatabaseClient<DB>
 	readonly #schema: string
 	/**
 	 * Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once.
@@ -31,10 +30,10 @@ export class SqliteConventionSource implements ConventionSource {
 
 	/**
 	 * @param db An open handle to a DB that has the convention asset attached (or is it).
-	 * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed shard name —
-	 *   `WOFSQLitePlaceLookup` auto-detects which shard carries the table).
+	 * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed extract name —
+	 *   `WOFSQLitePlaceLookup` auto-detects which extract carries the table).
 	 */
-	constructor(db: DatabaseSync, schema: string) {
+	constructor(db: DatabaseClient<DB>, schema: string) {
 		this.#db = db
 		this.#schema = schema
 	}

package/{sqlite-utils.ts → lib/sqlite-utils.ts}

@@ -6,12 +6,12 @@
  *   Small shared helpers for the SQLite-backed lookups.
  */
 
-import type { DatabaseSync, SQLInputValue } from "node:sqlite"
-
 import { allRows, getRow } from "@mailwoman/core/utils"
+import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
+import { hasColumn as columnExists, tableExists } from "@mailwoman/sqlite/introspection"
 
 // The row-shape assertion itself lives in `core` so the readers that cannot depend on this package reach the same
-// seam; re-exported here because this module is where this package's readers already look for it.
+// helper; re-exported here because this module is where this package's readers already look for it.
 export { allRows, getRow } from "@mailwoman/core/utils"
 
 /**
@@ -23,8 +23,8 @@ export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameter
 /**
  * Prepare a single-row query while preserving its exact parameter tuple at every call site.
  */
-export function prepareGet<Parameters extends SQLInputValue[], Row>(
-	db: DatabaseSync,
+export function prepareGet<Parameters extends SQLInputValue[], Row, DB>(
+	db: DatabaseClient<DB>,
 	sql: string
 ): PreparedGet<Parameters, Row> {
 	const statement = db.prepare(sql)
@@ -40,8 +40,8 @@ export type PreparedAll<Parameters extends SQLInputValue[], Row> = (...parameter
 /**
  * Prepare a multi-row query while preserving its exact parameter tuple at every call site.
  */
-export function prepareAll<Parameters extends SQLInputValue[], Row>(
-	db: DatabaseSync,
+export function prepareAll<Parameters extends SQLInputValue[], Row, DB>(
+	db: DatabaseClient<DB>,
 	sql: string
 ): PreparedAll<Parameters, Row> {
 	const statement = db.prepare(sql)
@@ -51,15 +51,13 @@ export function prepareAll<Parameters extends SQLInputValue[], Row>(
 
 /**
  * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
- * empty/tableless shard — an interrupted `build-*-shard.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db "…"`
- * CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode (#568). A
- * missing table makes the lookup a no-op miss.
+ * empty/tableless extract — an interrupted `build-*-extract.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db
+ * "…"` CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode
+ * (#568). A missing table makes the lookup a no-op miss.
  */
-export function hasTable(db: DatabaseSync, name: string): boolean {
+export function hasTable<DB>(db: DatabaseClient<DB>, name: string): boolean {
 	try {
-		const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(name)
-
-		return row !== undefined
+		return tableExists(db, name)
 	} catch {
 		return false
 	}
@@ -76,11 +74,9 @@ export function hasTable(db: DatabaseSync, name: string): boolean {
  * Note the interpolation: PRAGMA does not take bound parameters, so `table` is spliced. Every caller passes a
  * module-level constant; never pass user input.
  */
-export function hasColumn(db: DatabaseSync, table: string, column: string): boolean {
+export function hasColumn<DB>(db: DatabaseClient<DB>, table: string, column: string): boolean {
 	try {
-		const rows = allRows<{ name: string }>(db.prepare(`PRAGMA table_info(${table})`))
-
-		return rows.some((r) => String(r.name) === column)
+		return columnExists(db, table, column)
 	} catch {
 		return false
 	}