@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/lib/candidate/own-name.ts

@@ -0,0 +1,146 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The OWN-NAME VARIANT predicate (#1882): is an alias surface the holder's own primary name in
+ *   another orthography — a romanization (`Брэст` → `brest`), a spacing/diacritic variant
+ *   (`George Town` → `georgetown`), an abbreviation expansion (`St. George's` → `Saint George's`)
+ *   — rather than a different name that merely shares the folded key?
+ *
+ *   The comparator is `levenshteinSimilarity`, NOT Jaro-Winkler: JW's common-prefix bonus scores
+ *   the required NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
+ *   (`saint george s` vs `st georges` expanded, 0.914), so no JW threshold separates them.
+ *   Measured on the #1882 census contests, edit similarity separates every case with margin:
+ *
+ *   - IN: `brest`/`brest` 1.0 · `george town`/`georgetown` 0.909 · `saint george s`/`saint georges`
+ *       0.929 · `adamovka`/`adamowka` 0.875
+ *   - OUT: `lievin`/`levin` 0.833 (Liévin FR vs Levin NZ — different places with near-identical
+ *       names; the panel's `41 Weraroa Road, Levin` row needs this side) · `chanchun`/`cancun` 0.75 ·
+ *       `augsburg`/`augusta` 0.375 · `west bay`/`west end` 0.625 · `derry`/`londonderry` 0.455
+ *       (Derry/Londonderry is a DUAL NAME, not a variant — its own follow-up on #1882)
+ *
+ *   An unhandled script (Arabic, Hebrew, CJK — the romanizer covers Cyrillic only) answers NULL,
+ *   never "different name": absence of a verdict must not stamp anything (the meaning-of-zero rule).
+ *   The #1882 census counted 396 demoted Arabic/Hebrew-primary aliases left unclassified by this.
+ */
+
+import { levenshteinSimilarity } from "@mailwoman/match/comparators"
+
+/**
+ * Edit-similarity floor for the variant verdict. The measured band: nearest admitted pair 0.875
+ * (`adamovka`/`adamowka`), nearest refused pair 0.833 (`lievin`/`levin`).
+ */
+export const VARIANT_SIMILARITY_MIN = 0.85
+
+/**
+ * BGN/PCGN-flavored Cyrillic romanization, folded to the name-key alphabet. Digraph outputs (zh, kh, ts, ch, sh, shch,
+ * yu, ya) match the dominant transliteration conventions the gazetteer's Latin aliases actually use; the `w`/`v` and
+ * `kh`/`h` style variance between systems is what the edit-similarity threshold absorbs.
+ */
+const CYRILLIC_TO_LATIN: Record<string, string> = {
+	а: "a",
+	б: "b",
+	в: "v",
+	г: "g",
+	д: "d",
+	е: "e",
+	ё: "e",
+	ж: "zh",
+	з: "z",
+	и: "i",
+	і: "i",
+	й: "i",
+	к: "k",
+	л: "l",
+	м: "m",
+	н: "n",
+	о: "o",
+	п: "p",
+	р: "r",
+	с: "s",
+	т: "t",
+	у: "u",
+	ў: "u",
+	ф: "f",
+	х: "kh",
+	ц: "ts",
+	ч: "ch",
+	ш: "sh",
+	щ: "shch",
+	ъ: "",
+	ы: "y",
+	ь: "",
+	э: "e",
+	ю: "yu",
+	я: "ya",
+	ґ: "g",
+	є: "e",
+	ї: "i",
+}
+
+/**
+ * Leading-word abbreviations expanded BEFORE comparison, so `st georges` meets `saint george s` inside the edit
+ * threshold. Whole-word only — `st` inside `stanley` never expands.
+ */
+const NAME_ABBREVIATIONS: ReadonlyArray<[RegExp, string]> = [
+	[/\bst\b/g, "saint"],
+	[/\bste\b/g, "sainte"],
+	[/\bmt\b/g, "mount"],
+	[/\bft\b/g, "fort"],
+]
+
+/**
+ * Expand the whole-word abbreviations above.
+ */
+export function expandNameAbbreviations(key: string): string {
+	let out = key
+
+	for (const [pattern, replacement] of NAME_ABBREVIATIONS) {
+		out = out.replaceAll(pattern, replacement)
+	}
+
+	return out
+}
+
+/**
+ * Romanize a folded name key to the a–z0–9/space alphabet. `null` when characters outside the covered scripts remain —
+ * an unhandled script is NO VERDICT, not a mismatch.
+ */
+export function romanizeNameKey(key: string): string | null {
+	let out = ""
+
+	for (const ch of key.toLowerCase()) {
+		out += CYRILLIC_TO_LATIN[ch] ?? ch
+	}
+
+	out = out
+		.normalize("NFD")
+		.replaceAll(/[̀-ͯ]/g, "")
+		.replaceAll(/\s+/g, " ")
+		.trim()
+
+	return /^[a-z0-9 ]*$/.test(out) ? out : null
+}
+
+/**
+ * Edit similarity between a holder's primary name key and one of its alias keys, both romanized and
+ * abbreviation-expanded. `null` when either side's script is uncovered.
+ */
+export function ownNameSimilarity(primaryKey: string, aliasKey: string): number | null {
+	const primary = romanizeNameKey(primaryKey)
+	const alias = romanizeNameKey(aliasKey)
+
+	if (primary == null || alias == null || !primary || !alias) return null
+
+	return levenshteinSimilarity(expandNameAbbreviations(primary), expandNameAbbreviations(alias))
+}
+
+/**
+ * The stamp predicate: the alias surface is the holder's own name in another orthography.
+ */
+export function isOwnNameVariant(primaryKey: string, aliasKey: string): boolean {
+	const similarity = ownNameSimilarity(primaryKey, aliasKey)
+
+	return similarity != null && similarity >= VARIANT_SIMILARITY_MIN
+}

package/lib/candidate/place-attrs.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The per-place record every candidate-staging pass writes its rows from.
+ *
+ *   Pass 1 reduces each current `spr` row to one {@link PlaceAttrs}; every later pass (alias bags,
+ *   region abbreviations, country display names, the currency backfill, the extract folds) discovers
+ *   ADDITIONAL name keys for a place already in that map and stages a row against the same record.
+ *   That is what keeps each candidate row denormalized without re-reading the source, and it is why
+ *   a pass needs exactly four things to stage: the key it found, the place, the id the row hangs on,
+ *   and whether the key is the place's canonical name.
+ */
+
+export interface PlaceAttrs {
+	cid: number
+	rid: number
+	ptid: number
+	name: string
+	lat: number
+	lon: number
+	mnLat: number
+	mnLon: number
+	mxLat: number
+	mxLon: number
+	pop: number
+	neg: number
+	pkey: string
+	/**
+	 * The place's toponym-fame score, or null when the score source has no measurement for it (#28). A property of the
+	 * PLACE, so it rides {@link StageRow} onto the alias and abbrev rows too — that is how a bare `Moscow` reaches
+	 * Москва's score through the alias row that carries the key.
+	 */
+	imp: number | null
+}
+
+/**
+ * Stage one candidate row: a normalized name key, the place it belongs to, the source id the row hangs on, and whether
+ * the key is that place's canonical name (`is_primary`).
+ *
+ * `sid` is passed separately rather than read off the place because a extract fold and the alias pass stage rows for
+ * ids the admin `attrs` map never held.
+ */
+export type StageRow = (k: string, a: PlaceAttrs, sid: number, isPrimary: number) => void

package/lib/candidate-ancestors-schema.ts

@@ -0,0 +1,195 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the candidate gazetteer's ANCESTORS sidecar (`candidate_ancestor` +
+ *   `candidate_interval`) — the containment lineage the candidate table itself cannot answer, built
+ *   into the same `candidate.db` by `build-candidate.ts` and read by
+ *   {@link WOFCandidateTableLookup.ancestors}.
+ *
+ *   ENCODING: closure-lite rows, denormalized — one row per (place, ancestor) edge carrying the
+ *   parent's placetype, display name and folded key — rather than a fixed-slot id chain on the
+ *   candidate row. Decided by the two consumers:
+ *
+ *   1. The admin-coherence check needs the WINNER's chain as (placetype, name) pairs in one probe.
+ *      A fixed-slot `[id;8]` chain answers with ids, and every id then needs a name lookup the
+ *      artifact has no per-id table for — up to 8 indirections where the closure row has zero.
+ *   2. The account layer needs EVERY candidate under a `name_key` enumerable WITH its chain from
+ *      one artifact probe ("present-but-outranked, discriminated by containment"). That is the
+ *      candidate probe (contiguous) followed by one `spr_id`-clustered closure probe per candidate
+ *      — each a handful of adjacent pages.
+ *
+ *   Denormalizing the parent onto the edge is the same discipline as the candidate table itself:
+ *   this artifact is read over HTTP byte ranges, where a join to a dimension table scatters page
+ *   fetches, and a `WITHOUT ROWID` B-tree clustered on `(spr_id, depth)` keeps a whole chain in
+ *   1-2 pages. The repeated parent strings are the price of the zero-join read, paid at build time.
+ *
+ *   `depth` is 1 for the NEAREST ancestor (deepest containment tier), increasing outward to the
+ *   country — the same nearest-first order `ancestry.ts` serves for the FTS backend, so the two
+ *   backends' `ancestors()` agree by construction. The order within a place is deterministic:
+ *   containment depth descending (`placetypeDepth`), then ancestor id ascending, capped at
+ *   {@link MAX_ANCESTOR_DEPTH}. `parent_name_key` is the SHARED {@link normalizeLocalityForKey}
+ *   fold — the same fold `candidate.name_key` is built with, so a chain entry and a candidate key
+ *   compare under one normalizer.
+ *
+ *   `candidate_interval` carries pre/post-order labels over the CANONICAL-PARENT FOREST, assigned
+ *   at build time: `a` contains `d` ⟺ `a.pre <= d.pre AND d.post <= a.post` — O(1) in either
+ *   direction with no chain scan and no knowledge of either side's tier — and the descendants of
+ *   `a` are the contiguous range `pre BETWEEN a.pre AND a.post`. Interval labels are classically
+ *   avoided for their relabel-on-update cost; this database is a sealed read-only artifact rebuilt
+ *   whole, which is exactly the regime where that cost is void.
+ *
+ *   THE DAG CAVEAT, and the recorded choice: WOF places can carry more than one parent (multiple
+ *   hierarchies, ambiguous boundaries). `candidate_ancestor` keeps EVERY parent — the closure rows
+ *   are the complete containment record. A single interval pair can only encode a tree, so the
+ *   interval forest links each place to ONE canonical parent: its depth-1 edge — the finest
+ *   containment tier, lowest ancestor id — the same MIN-stability convention the candidate table's
+ *   `region_id` stamp uses. A containment question about a NON-canonical hierarchy must consult the
+ *   closure rows; the interval answer for it is `false`, which is why interval verdicts are
+ *   "contained along the canonical hierarchy", never "not contained at all".
+ *
+ *   ABSENCE SEMANTICS (meaning-of-zero): a place with no `candidate_interval` row has no recorded
+ *   ancestry in the source (extract-fed postcodes and localities, isolated places, cycle-skipped
+ *   rows). Absence is UNVERIFIABLE, never a containment verdict.
+ */
+
+import { sql, type Kysely } from "kysely"
+
+// Type-only and circular on purpose (candidate-schema extends CandidateAncestorsDatabase): Kysely's
+// DB parameter is invariant, so the DDL functions must take the FULL database type their caller
+// holds. Erased at runtime.
+import type { CandidateDatabase } from "#candidate-schema"
+import type { NameKey } from "#street/normalize"
+
+/**
+ * The deepest chain the sidecar stores per place. WOF containment within the resolvable placetypes (country …
+ * microhood) never legitimately exceeds this; anything past it is source noise the build drops (and counts) rather than
+ * stores.
+ */
+export const MAX_ANCESTOR_DEPTH = 8
+
+/**
+ * The closure-row table's name — probed with `hasTable` by the reader, so an artifact predating the sidecar degrades to
+ * "no ancestors capability" rather than `no such table`.
+ */
+export const CANDIDATE_ANCESTOR_TABLE = "candidate_ancestor"
+
+/**
+ * The interval-label table's name — the closure table's seal-time sibling; existence-restricted the same way.
+ */
+export const CANDIDATE_INTERVAL_TABLE = "candidate_interval"
+
+/**
+ * One (place, ancestor) edge, denormalized so a chain read is a single clustered probe (no join).
+ */
+export interface CandidateAncestorTable {
+	/**
+	 * WOF id of the place whose chain this row belongs to — the same `spr_id` the candidate table resolves to.
+	 */
+	spr_id: number
+	/**
+	 * 1 = nearest ancestor, increasing outward to the country. Deterministic within a place (containment depth
+	 * descending, then ancestor id ascending), so `(spr_id, depth)` is a stable primary key across rebuilds.
+	 */
+	depth: number
+	/**
+	 * WOF id of the ancestor.
+	 */
+	parent_spr_id: number
+	/**
+	 * Small int from the shared `placetype_codes` dictionary (the same one the candidate table uses).
+	 */
+	parent_placetype_id: number
+	/**
+	 * The ancestor's canonical display name — what {@link Ancestor.name} serves, matching the FTS backend's register.
+	 */
+	parent_name: string
+	/**
+	 * The SHARED {@link normalizeLocalityForKey} fold of `parent_name` — comparable against `candidate.name_key` and
+	 * against a query-side fold under one normalizer, by construction.
+	 */
+	parent_name_key: NameKey
+}
+
+/**
+ * Pre/post-order labels over the canonical-parent forest — one row per place WITH recorded ancestry (see the module
+ * docstring for absence semantics). `pre < post` always; labels are unique across the artifact.
+ */
+export interface CandidateIntervalTable {
+	spr_id: number
+	pre: number
+	post: number
+}
+
+/**
+ * The sidecar tables, for a `Kysely` view over the candidate DB. `CandidateDatabase` (candidate-schema.ts) extends
+ * this, so the builder's one typed client sees both families.
+ */
+export interface CandidateAncestorsDatabase {
+	candidate_ancestor: CandidateAncestorTable
+	candidate_interval: CandidateIntervalTable
+}
+
+/**
+ * The `candidate_ancestor` columns in clustered-key order — the first two ARE the primary key, and the builder's
+ * positional `INSERT` binds by this order. Keep in sync with {@link CandidateAncestorTable}.
+ */
+export const CANDIDATE_ANCESTOR_COLUMNS = [
+	"spr_id",
+	"depth",
+	"parent_spr_id",
+	"parent_placetype_id",
+	"parent_name",
+	"parent_name_key",
+] as const
+
+/**
+ * Create the clustered closure table. The builder inserts in `(spr_id, depth)` order so the B-tree leaves are
+ * contiguous per place — the byte-range read discipline.
+ */
+export async function createCandidateAncestorTable(db: Kysely<CandidateDatabase>): Promise<void> {
+	await db.schema
+		.createTable(CANDIDATE_ANCESTOR_TABLE)
+		.addColumn("spr_id", "integer", (c) => c.notNull())
+		.addColumn("depth", "integer", (c) => c.notNull())
+		.addColumn("parent_spr_id", "integer", (c) => c.notNull())
+		.addColumn("parent_placetype_id", "integer", (c) => c.notNull())
+		.addColumn("parent_name", "text", (c) => c.notNull())
+		.addColumn("parent_name_key", "text", (c) => c.notNull())
+		.addPrimaryKeyConstraint("candidate_ancestor_pk", ["spr_id", "depth"])
+		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * Create the interval-label table. Small rows probed by primary key — the `WITHOUT ROWID` win case.
+ */
+export async function createCandidateIntervalTable(db: Kysely<CandidateDatabase>): Promise<void> {
+	await db.schema
+		.createTable(CANDIDATE_INTERVAL_TABLE)
+		.addColumn("spr_id", "integer", (c) => c.primaryKey())
+		.addColumn("pre", "integer", (c) => c.notNull())
+		.addColumn("post", "integer", (c) => c.notNull())
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * One place's interval label — the shape both sides of a containment comparison read.
+ */
+export interface IntervalLabel {
+	pre: number
+	post: number
+}
+
+/**
+ * Does `outer` contain `inner` along the canonical hierarchy? Reflexive: a place contains itself (containment
+ * degenerates to identity, the same reading the admin-coherence check gives a self-match). The shared FUNCTION for
+ * every consumer of the labels — a re-derived comparison risks disagreeing at exactly the strict/inclusive boundary
+ * this line settles.
+ */
+export function intervalContains(outer: IntervalLabel, inner: IntervalLabel): boolean {
+	return outer.pre <= inner.pre && inner.post <= outer.post
+}

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

@@ -9,8 +9,10 @@
  *   raw `name`), so a diacritic-stripped query (`munchen`) trigram-matches the stored `munchen`
  *   rather than missing a raw `München`. The trigram tokenizer makes MATCH a substring/fuzzy
  *   operation; the reader ({@link WOFCandidateTableLookup}) OR's the query's trigrams to fetch a
- *   loose set, then re-ranks by the SAME `trigramJaccard` the admin/FTS backend uses, so a typo
- *   resolves identically on either.
+ *   loose set, then re-ranks it with a WORD-level similarity. The trigram index is the candidate
+ *   GENERATOR, not the scorer — trigram Jaccard scores a true transposition correction BELOW a wrong
+ *   answer, because shared generic suffixes count as evidence and transpositions count against it.
+ *   The receipts are on `candidate-lookup.ts`'s `FUZZY_FETCH` and `WORD_FUZZY_MIN`.
  *
  *   This is what unifies the two gazetteers: the candidate B-tree stays the common,
  *   byte-range-optimal fast path (the browser's contiguous probe), and FTS5 is consulted ONLY on an
@@ -23,10 +25,10 @@
  *   fallback only needs to recover the name_key, then re-probes the B-tree for its rows).
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 /**
- * Name of the FTS5 trigram virtual table this module owns. The reader gates its fuzzy fallback on it.
+ * Name of the FTS5 trigram virtual table this module owns. The reader conditions its fuzzy fallback on it.
  */
 export const CANDIDATE_FTS_TABLE = "candidate_fts"
 
@@ -34,7 +36,7 @@ export const CANDIDATE_FTS_TABLE = "candidate_fts"
  * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. Call after the candidate
  * B-tree is populated (build pipeline) or against an existing candidate DB (migration).
  */
-export function createCandidateFTS(db: DatabaseSync): void {
+export function createCandidateFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(`DROP TABLE IF EXISTS ${CANDIDATE_FTS_TABLE}`)
 	db.exec(`CREATE VIRTUAL TABLE ${CANDIDATE_FTS_TABLE} USING fts5(name_key, tokenize='trigram')`)
 

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

@@ -27,7 +27,7 @@
  *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
  *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
  *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_GATE_KM}. Two artifacts describing the same settlement put its centroid in
+ *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
  *   almost the same place; two same-named towns in one country do not.
  *
  *   ## What lands in the column
@@ -41,10 +41,11 @@
  *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { haversineKm } from "./geo.ts"
-import { normalizeLocalityForKey } from "./street-normalize.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
  * How far apart two artifacts may put the same place's centroid and still be read as the same place.
@@ -54,18 +55,18 @@ import { normalizeLocalityForKey } from "./street-normalize.ts"
  * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
  * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
  *
- * What sets the gate is where that mode ENDS, and the per-kilometre density says so plainly. It falls from 1,076
- * places/km over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of
- * 760–780 places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns
- * wearing one name in one country, and it does not decay with distance because there is no reason it should. 10 km is
- * the floor between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the
- * gate to 25 km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
+ * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
+ * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
+ * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
+ * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
+ * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
  *
  * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The gate is the definition of
- * "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
+ * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
  */
-export const IMPORTANCE_JOIN_GATE_KM = 10
+export const IMPORTANCE_JOIN_RADIUS_KM = 10
 
 /**
  * One scored place from the source: where it is, and what it scored.
@@ -110,17 +111,17 @@ export class ImportanceIndex {
 	readonly #groups: Map<string, ScoredPlace[]>
 	readonly stats: ImportanceIndexStats
 	/**
-	 * Places {@link find} matched inside the gate.
+	 * Places {@link find} matched inside the radius.
 	 */
 	matched = 0
 	/**
-	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the gate, so
-	 * it is a different place wearing the same name.
+	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+	 * so it is a different place wearing the same name.
 	 *
 	 * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-	 * apart and the join is being asked to guess; it does not mean the gate is too tight.
+	 * apart and the join is being asked to guess; it does not mean the radius is too tight.
 	 */
-	gated = 0
+	refused = 0
 
 	constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats) {
 		this.#groups = groups
@@ -129,7 +130,7 @@ export class ImportanceIndex {
 
 	/**
 	 * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-	 * null when there is no such place within {@link IMPORTANCE_JOIN_GATE_KM}.
+	 * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
 	 *
 	 * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
 	 * column already carries that fallback where it has one, and inventing a second one would make an absence
@@ -156,8 +157,8 @@ export class ImportanceIndex {
 			}
 		}
 
-		if (!best || bestKm > IMPORTANCE_JOIN_GATE_KM) {
-			this.gated++
+		if (!best || bestKm > IMPORTANCE_JOIN_RADIUS_KM) {
+			this.refused++
 
 			return null
 		}
@@ -181,47 +182,43 @@ export class ImportanceIndex {
  * 25 s.
  */
 export function loadImportanceIndex(databasePath: string): ImportanceIndex {
-	const db = new DatabaseSync(databasePath, { readOnly: true })
-
-	try {
-		const groups = new Map<string, ScoredPlace[]>()
-		let places = 0
-		let unkeyable = 0
-
-		for (const row of db
-			.prepare(
-				`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
-					s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
-				 FROM place_importance i JOIN spr s ON s.id = i.id
-				 WHERE s.is_current != 0 AND s.is_deprecated = 0`
-			)
-			.iterate()) {
-			const importance = Number(row.importance)
-
-			if (!Number.isFinite(importance)) continue
-			const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
-
-			if (!nameKey) {
-				unkeyable++
-
-				continue
-			}
+	using db = new DatabaseClient<CandidateDatabase>(databasePath, { readOnly: true })
 
-			const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
-			let group = groups.get(key)
+	const groups = new Map<string, ScoredPlace[]>()
+	let places = 0
+	let unkeyable = 0
 
-			if (!group) {
-				group = []
-				groups.set(key, group)
-			}
+	for (const row of db
+		.prepare(
+			`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
+				s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
+			 FROM place_importance i JOIN spr s ON s.id = i.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`
+		)
+		.iterate()) {
+		const importance = Number(row.importance)
+
+		if (!Number.isFinite(importance)) continue
+		const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
+
+		if (!nameKey) {
+			unkeyable++
 
-			group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+			continue
+		}
+
+		const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
+		let group = groups.get(key)
 
-			places++
+		if (!group) {
+			group = []
+			groups.set(key, group)
 		}
 
-		return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
-	} finally {
-		db.close()
+		group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+
+		places++
 	}
+
+	return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
 }