@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/candidate/ancestors/sidecar.ts

@@ -7,7 +7,7 @@
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { placetypeDepth } from "#ancestry/index"
+import { placetypeDepth } from "#ancestry"
 import {
 	CANDIDATE_ANCESTOR_COLUMNS,
 	CANDIDATE_ANCESTOR_TABLE,
@@ -21,14 +21,9 @@ import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 
 /**
- * Pass 3b — the ancestors sidecar: closure rows + interval labels (candidate-ancestors-schema.ts owns the encoding
- * decision and the DAG/absence semantics). Reads the same source `ancestors` table the region stamp reads,
- * denormalizing each edge with the parent's name/key from `attrs`, streamed `ORDER BY id` so the clustered `(spr_id,
- * depth)` insert is sorted — the contiguous-leaves discipline of the candidate table itself.
- *
- * Excluded by policy: self rows, and placetypes outside the containment ladder (continent, empire, …: `placetypeDepth` 0)
- * — they discriminate nothing a consumer of this sidecar checks. An edge to a parent with no current `spr` row has no
- * name to denormalize; it is dropped and counted rather than stored blind.
+ * Build the ancestors sidecar (closure rows plus interval labels) from the source
+ * `ancestors` table, excluding self rows and placetypes outside the containment ladder.
+ * an edge to a parent with no current `spr` row is dropped and counted.
  */
 export async function buildAncestorsSidecar(ctx: {
 	src: DatabaseClient<WOFDatabase>
@@ -47,9 +42,8 @@ export async function buildAncestorsSidecar(ctx: {
 		`INSERT INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
 	)
 
-	// The canonical-parent forest the interval labels are computed over. One parent per place — the
-	// depth-1 edge (finest containment tier, lowest ancestor id; the `regionOf` MIN-stability
-	// convention). ALL parents stay in the closure rows; only the interval tree canonicalizes.
+	// One parent per place (the finest containment tier, lowest ancestor id) canonicalizes the interval tree.
+	// All parents stay in the closure rows.
 	const canonicalParentOf = new Map<number, number>()
 	const childrenOf = new Map<number, number[]>()
 	const forest = new Set<number>()
@@ -58,15 +52,15 @@ export async function buildAncestorsSidecar(ctx: {
 	let ancestorPlaces = 0
 	let droppedParents = 0
 
-	// Per-child edge buffer; the stream below is grouped by child id, so each flush owns one place.
+	// The stream is grouped by child id, so each flush owns one place.
 	let childID = -1
 	let edges: Array<{ aid: number; apt: string }> = []
 
 	const flush = (): void => {
 		if (childID < 0 || !edges.length) return
 
-		// Deterministic nearest-first: containment depth descending, then ancestor id ascending —
-		// the FTS backend's `ancestorLineage` ordering, made stable across rebuilds.
+		// Deterministic nearest-first: containment depth descending, then ancestor id ascending,
+		// matching the FTS backend's `ancestorLineage` ordering across rebuilds.
 		edges.sort((a, b) => placetypeDepth(b.apt) - placetypeDepth(a.apt) || a.aid - b.aid)
 
 		if (edges.length > MAX_ANCESTOR_DEPTH) {
@@ -132,8 +126,8 @@ export async function buildAncestorsSidecar(ctx: {
 	flush()
 	out.exec("COMMIT")
 
-	// Interval labels: pre/post-order DFS over the canonical-parent forest. Root order and child
-	// order are id-ascending so the labels are stable across rebuilds of the same source.
+	// Interval labels are a pre/post-order DFS over the canonical-parent forest, with root
+	// and child order id-ascending so labels stay stable across rebuilds.
 	const preOf = new Map<number, number>()
 	const postOf = new Map<number, number>()
 
@@ -160,8 +154,8 @@ export async function buildAncestorsSidecar(ctx: {
 			if (kids && top.next < kids.length) {
 				const kid = kids[top.next++]!
 
-				// Each child holds exactly one canonical parent, so a labeled node here means the
-				// grouping upstream broke — skip rather than corrupt the numbering.
+				// Each child holds exactly one canonical parent, so a labeled node means upstream grouping broke.
+				// Skip rather than corrupt the numbering.
 				if (preOf.has(kid)) continue
 
 				preOf.set(kid, counter++)
@@ -173,9 +167,8 @@ export async function buildAncestorsSidecar(ctx: {
 		}
 	}
 
-	// A canonical-parent CYCLE (corrupt source ancestry) leaves its members unreachable from any
-	// root: they simply receive no label, and containment against them reads unverifiable — the
-	// absence semantics the schema module states. Counted so a jump is visible across rebuilds.
+	// A canonical-parent cycle leaves its members unreachable from any root,
+	// so they receive no label and containment against them reads unverifiable.
 	const cycleSkipped = forest.size - preOf.size
 
 	const insInterval = out.prepare(`INSERT INTO ${CANDIDATE_INTERVAL_TABLE} VALUES (?, ?, ?)`)

package/lib/candidate/country-display-names.ts

@@ -2,7 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 1b of the candidate build — fold ICU's country display names onto the country rows.
  */
 
 import { enumerateCountryDisplayNames } from "@mailwoman/codex/country"
@@ -11,22 +10,13 @@ import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).
+ * Stages each country name that `Intl.DisplayNames` renders in the codex display-name
+ * locales as a non-primary key on that country's candidate row.
  *
- * A bare `格鲁吉亚` (Georgia the country) resolved to NOTHING while `佐治亚州` (Georgia the US state) resolved correctly, and
- * the model gave both the same wrong `locality` tag — so the tag was never the variable. Measured 2026-08-15: 140 of
- * 237 country rows are synthetic and carry a canonical English name and nothing else; WOF holds no Chinese country
- * names at all; and the GeoNames alias fold filters through a Latin-script regex, so neither existing source could ever
- * supply them.
+ * The row's display name is unchanged, so a query such as `格鲁吉亚` resolves to the existing Georgia row.
+ * When several country rows share an ISO code, the most populous one receives the keys.
  *
- * `Intl.DisplayNames` already knows every one — ~280 regions, ~5,244 surfaces, from the same ICU the runtime uses for
- * every other locale-sensitive operation. No download, no vendored corpus, no snapshot to drift.
- *
- * `is_primary = 0`: these are NAMES THE WORLD USES, not the country's canonical name. The display `name` stays whatever
- * the gazetteer already had, so resolving `格鲁吉亚` answers with the Georgia country row rather than renaming it.
- *
- * Returns the row count so the caller can report it — a zero means ICU supplied nothing, which is a different fact from
- * the pass not having run.
+ * @returns The number of rows staged.
  */
 export function stageCountryDisplayNames(ctx: {
 	attrs: Map<number, PlaceAttrs>
@@ -35,8 +25,6 @@ export function stageCountryDisplayNames(ctx: {
 	stageRow: StageRow
 	tx: { exec(sql: string): void }
 }): number {
-	// One country row per ISO2. Where a code has several (historic rows surviving the is_current filter), the most
-	// populous wins — the same tiebreak the ranking uses everywhere else.
 	const countryByISO2 = new Map<string, { sid: number; a: PlaceAttrs }>()
 
 	for (const [sid, a] of ctx.attrs) {
@@ -48,7 +36,7 @@ export function stageCountryDisplayNames(ctx: {
 
 		const held = countryByISO2.get(iso2)
 
-		if (!held || a.pop > held.a.pop) {
+		if (!held || (a.pop ?? 0) > (held.a.pop ?? 0)) {
 			countryByISO2.set(iso2, { sid, a })
 		}
 	}
@@ -64,8 +52,6 @@ export function stageCountryDisplayNames(ctx: {
 
 		const k = normalizeLocalityForKey(name)
 
-		// The country's own key is already staged as its primary; INSERT OR IGNORE at materialization dedupes the
-		// rest, so this only skips the obvious self-alias.
 		if (!k || k === target.a.pkey) continue
 
 		ctx.stageRow(k, target.a, target.sid, 0)

package/lib/candidate/extract-fold.ts

@@ -2,11 +2,11 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
  */
 
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
+import type { PathBuilderLike } from "path-ts"
 
 import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate/ancestors/schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
@@ -14,15 +14,6 @@ import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
-/**
- * The extract's own region-tier ancestry, when it carries any: extract id → the admin region's id. A locality extract
- * derived from a national register (the Taiwanese 鄉鎮市區 from the civil-affairs address points) knows which 縣市 each row
- * belongs to, and writes that as an `ancestors` row against the admin region's WOF id. Without it a folded row has no
- * region scope, so a `parentID`-scoped probe misses it and the cascade widens to whatever namesake carries the key.
- *
- * Only a region the admin build staged (`attrs`) counts: an id the admin does not know cannot be denormalized into a
- * closure row, and a scope nothing can match would be a silent zero rather than an absence.
- */
 function extractRegionAncestry(pc: DatabaseClient<WOFDatabase>, attrs: Map<number, PlaceAttrs>): Map<number, number> {
 	const regionOf = new Map<number, number>()
 
@@ -46,28 +37,21 @@ function extractRegionAncestry(pc: DatabaseClient<WOFDatabase>, attrs: Map<numbe
 }
 
 /**
- * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
- * hanging off that same extract's `names` table.
+ * Stages one postcode or locality extract's located `spr` rows and their `names`
+ * aliases into the candidate table.
  *
- * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
- * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
- * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
- * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
+ * When `attrs` is given and the extract's `ancestors` table places a row in a known region,
+ * the row also gets that region's scope and the region's ancestor chain.
+ * The stored ancestors then agree with the row's scope.
  */
 export function foldExtract(ctx: {
-	/**
-	 * The staging connection. The extract itself is opened read-only here and closed before returning.
-	 */
 	out: DatabaseClient<CandidateDatabase>
-	extractPath: string
+	extractPath: PathBuilderLike
 	extractPlacetype: "postalcode" | "locality"
 	ccID: (code: string | null) => number
 	ptID: (pt: string | null) => number
 	stageRow: StageRow
-	/**
-	 * The admin places pass 1 staged — what an extract's region ancestry is resolved against. Absent, no extract row
-	 * takes a region scope (the postcode extracts, which carry none).
-	 */
+
 	attrs?: Map<number, PlaceAttrs>
 	progress: (phase: string, message: string) => void
 }): { primaries: number; aliases: number; scoped: number; ancestorRows: number } {
@@ -77,8 +61,7 @@ export function foldExtract(ctx: {
 
 	using pc = new DatabaseClient<WOFDatabase>(extractPath, { readOnly: true })
 	const pcPtid = ptID(extractPlacetype)
-	// Per-extract, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
-	// below has nothing to join against unless this primary loop records what it staged.
+
 	const pcAttrs = new Map<number, PlaceAttrs>()
 	const regionOf = ctx.attrs ? extractRegionAncestry(pc, ctx.attrs) : new Map<number, number>()
 
@@ -86,10 +69,6 @@ export function foldExtract(ctx: {
 		`INSERT OR IGNORE INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
 	)
 
-	// The region's own closure rows, as the sidecar pass wrote them. A scoped row inherits the whole chain above its
-	// region — macroregion, country — not the region alone: the widened-scope refusal reads a pick's stamped ancestors
-	// against the parent the walk resolved, and a 縣市 that resolves to its macroregion record (`桃園市`, which WOF names
-	// only at that tier) would otherwise contradict a lineage that stops at the region.
 	const regionChain = out.prepare(
 		`SELECT depth, parent_spr_id, parent_placetype_id, parent_name, parent_name_key FROM ${CANDIDATE_ANCESTOR_TABLE} WHERE spr_id = ? ORDER BY depth`
 	)
@@ -118,9 +97,6 @@ export function foldExtract(ctx: {
 		const id = Number(r.id)
 		const rid = regionOf.get(id) ?? 0
 
-		// region_id from the extract's own ancestry when it names one, else 0 (a postcode is unique by
-		// name+country — no same-name disambiguation); neg_rank 0 (no population). bbox = the row's own
-		// min/max (falls back to the centroid point).
 		const a: PlaceAttrs = {
 			cid: ccID(r.country as string | null),
 			rid,
@@ -135,9 +111,7 @@ export function foldExtract(ctx: {
 			pop: 0,
 			neg: 0,
 			pkey: key,
-			// A postcode has no toponym fame — nobody writes an encyclopedia article about SW1A 2AA — and
-			// the score source carries no `postalcode` rows to join against anyway. NULL is the truthful
-			// value: unmeasured, so the ranking key leaves postcode rows exactly where they were.
+
 			imp: null,
 		}
 
@@ -172,20 +146,6 @@ export function foldExtract(ctx: {
 
 	out.exec("COMMIT")
 
-	// Fold postcode aliases into the staged candidate names.
-	//
-	// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
-	// the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
-	// downstream of `names` picked them up EXCEPT this build: `fts.ts` unions `spr.name` with every
-	// `names` row into `place_search.alt_names`, so the FTS backend resolved "Brooklyn" → 11201
-	// while the candidate backend — whose every row IS an exact-tier row — had no key for it at
-	// all. Pass 2 does the equivalent fold for admin places, but reads the ADMIN `place_search`,
-	// and `attrs` holds admin ids only, so a postcode extract could never reach it.
-	//
-	// Same discipline as pass 2: `is_primary = 0` (so `rankByPrimaryPreference` treats it as an
-	// alias, not a canonical postcode name), the row stays denormalized onto the POSTCODE's own
-	// spr_id/coords/bbox, and the display `name` stays the postcode — resolving "brooklyn" answers
-	// with place 11201, it does not rename the place to its delivery city.
 	const hasNames = tableExists(pc, "names")
 
 	if (hasNames) {
@@ -198,8 +158,6 @@ export function foldExtract(ctx: {
 
 			const k = normalizeLocalityForKey(String(r.name ?? ""))
 
-			// The postcode's own key is already staged as the primary; `INSERT OR IGNORE` at
-			// materialization dedupes repeats, so this only skips the obvious self-alias.
 			if (!k || k === a.pkey) continue
 
 			stageRow(k, a, Number(r.id), 0)
@@ -209,9 +167,6 @@ export function foldExtract(ctx: {
 
 		out.exec("COMMIT")
 	} else {
-		// Never a silent zero: real extracts come from `createUnifiedSchema`, which always creates
-		// `names`. A extract without it has no alias surface to lose, but say so rather than reporting
-		// "0 aliases" from a table that was never read.
 		progress("postcode-aliases", `${extractPath} has no \`names\` table — no delivery-city aliases to fold`)
 	}
 

package/lib/candidate/fts.ts

@@ -3,38 +3,20 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FTS5-TRIGRAM fuzzy index over the candidate gazetteer's `name_key` — the typo-tolerant fallback
- *   the exact `name_key` B-tree probe structurally can't do (a misspelling breaks the normalized
- *   key, so the contiguous-probe lookup returns nothing). It indexes the NORMALIZED key (not the
- *   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 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
- *   exact+strip miss — so its scattered postings cost is rare/amortized, and one DB serves both the
- *   browser and the server.
- *
- *   Raw SQL on purpose: Kysely can't express `CREATE VIRTUAL TABLE … USING fts5` (the repo's
- *   FTS5-stays-raw rule). Indexing DISTINCT `name_key` keeps the index to unique normalized forms
- *   (a name_key fans out to many candidate rows — placetypes, regions, aliases — but the fuzzy
- *   fallback only needs to recover the name_key, then re-probes the B-tree for its rows).
+ *   FTS5-trigram fuzzy index over the candidate gazetteer's normalized `name_key`; raw SQL on purpose, since Kysely cannot express `create virtual table … using fts5`.
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 /**
- * Name of the FTS5 trigram virtual table this module owns. The reader conditions its fuzzy fallback on it.
+ * Name of the FTS5 trigram virtual table this module owns, on which the reader
+ * conditions its fuzzy fallback.
  */
 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).
+ * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. call
+ * after the candidate B-tree is populated or against an existing candidate DB.
  */
 export function createCandidateFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(`DROP TABLE IF EXISTS ${CANDIDATE_FTS_TABLE}`)

package/lib/candidate/importance.ts

@@ -3,46 +3,35 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The score side of the candidate build (#28) — load a WOF admin database's `place_importance` into
- *   a lookup the candidate builder can probe per place, so every candidate row can carry the
+ *   The score side of the candidate build: load a WOF admin database's `place_importance` into a
+ *   lookup the candidate builder probes per place, so every candidate row can include the
  *   toponym-fame prior a bare city name is decided on.
  *
- *   ## Why this joins on the NAME and not on the id
+ *   The join key is `(name_key, country, placetype)`, the same {@link normalizeLocalityForKey} the
+ *   candidate build uses for its probe key, so the two sides fold identically. An id join is wrong
+ *   here, because the score source (`admin-global-priority-importance.db`) and the candidate build's
+ *   admin source are different snapshots whose ids disagree. An id join silently drops rows and
+ *   leaves the ranking inert on the queries the prior exists for.
  *
- *   The obvious join is `candidate.spr_id = place_importance.id`, and it is wrong here. The score
- *   source (`admin-global-priority-importance.db`) and the candidate build's admin source are
- *   DIFFERENT SNAPSHOTS, and they disagree about ids for exactly the rows that matter: Whitby,
- *   Ontario is `8143502164401` in the shipped `candidate.db` and `8000001156384` in the score source
- *   — the Overture-sourced rows were re-keyed between the two. An id join silently drops every one of
- *   them, which means it drops precisely the FOREIGN HOMONYMS the fame prior exists to demote, and it
- *   drops them invisibly: the build succeeds, the column is populated, and the ranking is inert on
- *   the queries it was built for.
+ *   The key by itself is not enough. `(warwick, US, locality)` covers eleven different places.
+ *   The group's maximum would give every Warwick in America the fame of Warwick, Rhode Island.
+ *   The join picks the nearest centroid when it falls within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+ *   Two artifacts describing the same settlement put its centroid
+ *   in almost the same place. Two towns with the same name in one country do not.
  *
- *   So the join key is `(name_key, country, placetype)` — the same {@link normalizeLocalityForKey} the
- *   candidate build uses for its probe key, so the two sides fold identically by construction.
+ *   `place_importance.importance` lands in the column verbatim, the pre-split conflation that is
+ *   encyclopedia-derived where the concordance matched and a population-derived proxy everywhere
+ *   else. See {@link CandidateTable.importance} for why the split `encyclopedic` channel is not what
+ *   is written here.
  *
- *   ## Why the key alone is not enough
- *
- *   `(warwick, US, locality)` names ELEVEN different places. Taking the group's max would give every
- *   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_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
- *
- *   `place_importance.importance` VERBATIM — the pre-split conflation (encyclopedia-derived where
- *   the concordance matched, a population-derived proxy everywhere else). See
- *   {@link CandidateTable.importance} for why the split `encyclopedic` channel is deliberately NOT
- *   what is written here, with the measurement that settled it.
- *
- *   A place with no match gets NULL. NULL is UNMEASURED, never zero — the consumer
- *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
+ *   A place with no match gets NULL. NULL means the place's fame is unmeasured.
+ *   The consumer (`resolver/toponym-prior.ts`) leaves an unmeasured candidate at the position
+ *   population assigned it.
  */
 
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
 
 import type { CandidateDatabase } from "#candidate/schema"
 import { normalizeLocalityForKey } from "#street/normalize"
@@ -50,26 +39,20 @@ 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.
  *
- * MEASURED, not guessed (2026-08-10, `admin-global-priority.db` × `admin-global-priority-importance.db`; 4,476,245
- * current locality-tier places against 676,790 scored ones, 1,020,099 of which matched a scored group by `(name_key,
- * 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.
+ * Measured from two admin snapshots.
+ * The nearest-centroid distances separate into a mode where the two snapshots agree
+ * and a background rate of two different towns wearing one name in one country.
  *
- * 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 background rate does not decay with distance.
+ * Ten kilometers separates the two populations.
  *
- * 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 radius is the definition
- * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * That distance matches the join's purpose.
+ * A radius above the floor starts handing one town's fame to another.
  */
 export const IMPORTANCE_JOIN_RADIUS_KM = 10
 
 /**
- * One scored place from the source: where it is, and what it scored.
+ * One scored place from the source, with its coordinates and importance score.
  */
 interface ScoredPlace {
 	lat: number
@@ -78,8 +61,10 @@ interface ScoredPlace {
 }
 
 /**
- * What {@link loadImportanceIndex} measured while reading the source. Reported by the builder so a run says how much of
- * the gazetteer it actually scored, rather than leaving the caller to infer it from a column full of nulls.
+ * What {@link loadImportanceIndex} measured while reading the source.
+ *
+ * Reported by the builder so a run reports how much of the gazetteer it actually scored,
+ * rather than leaving the caller to infer it from a column full of nulls.
  */
 export interface ImportanceIndexStats {
 	/**
@@ -91,14 +76,17 @@ export interface ImportanceIndexStats {
 	 */
 	keys: number
 	/**
-	 * Places whose name folded to the empty key and could never be joined (non-Latin punctuation-only names, blanks).
+	 * Places whose name folded to the empty key and could never be joined
+	 * (non-Latin punctuation-only names, blanks).
 	 */
 	unkeyable: number
 }
 
 /**
- * `(name_key, country, placetype)` → the scored places under it. The separator is U+0000, which no WOF name carries and
- * no fold can produce, so the three fields can't smear into one another.
+ * `(name_key, country, placetype)` → the scored places under it.
+ *
+ * The separator is U+0000, a character no WOF name contains and no fold can produce,
+ * so the three fields cannot smear into one another.
  */
 function groupKey(nameKey: string, country: string | null, placetype: string | null): string {
 	return `${nameKey}\u0000${(country ?? "").toUpperCase()}\u0000${placetype ?? ""}`
@@ -115,11 +103,15 @@ export class ImportanceIndex {
 	 */
 	matched = 0
 	/**
-	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+	 * Places {@link find} refused.
+	 *
+	 * The key matched a scored group, but the nearest member 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 radius is too tight.
+	 * 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 radius is too tight.
 	 */
 	refused = 0
 
@@ -129,12 +121,15 @@ 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_RADIUS_KM}.
+	 * 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_RADIUS_KM}.
+	 *
+	 * Null is unmeasured.
+	 * Keep the value null.
+	 * Do not substitute zero or a population-derived value here.
 	 *
-	 * 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
-	 * indistinguishable from a measurement.
+	 * The source column already contains a population-derived fallback where one exists.
+	 * A second fallback would make an absence indistinguishable from a measurement.
 	 */
 	find(name: string, country: string | null, placetype: string | null, lat: number, lon: number): number | null {
 		const nameKey = normalizeLocalityForKey(name)
@@ -145,7 +140,7 @@ export class ImportanceIndex {
 
 		if (!group) return null
 
-		let best: ScoredPlace | undefined
+		let best: ScoredPlace | null = null
 		let bestKm = Infinity
 
 		for (const place of group) {
@@ -170,18 +165,20 @@ export class ImportanceIndex {
 }
 
 /**
- * Read `place_importance` (joined to `spr` for the name/country/placetype/centroid) out of a WOF admin database into an
- * {@link ImportanceIndex}.
+ * Read `place_importance` from a WOF admin database and join it to `spr`.
+ *
+ * The join retrieves each place's name, country, placetype, plus its centroid.
+ * These fields populate an {@link ImportanceIndex}.
+ *
+ * Only current, non-deprecated places are indexed.
+ * A superseded row's score belongs to a place the gazetteer no longer contains.
  *
- * Only CURRENT, non-deprecated places are indexed — a superseded row's score belongs to a place the gazetteer no longer
- * carries, and letting it win the nearest-centroid contest would hand a live place a dead one's fame.
+ * If that row won the nearest-centroid contest, a live place would inherit the superseded place's fame.
  *
- * The whole table is held in memory on purpose. The 2026-08-10 source holds 676,790 scored places in 544,823 groups,
- * and the build probes it once for every one of its ~4.8 M places; the alternative is a prepared statement per place
- * against a 3.7 GB database. Measured end to end, loading the index plus probing all 4.48 M locality-tier places takes
- * 25 s.
+ * The whole table is held in memory on purpose, because the build probes it once for every place
+ * and the alternative is a prepared statement per place against a multi-gigabyte database.
  */
-export function loadImportanceIndex(databasePath: string): ImportanceIndex {
+export function loadImportanceIndex(databasePath: PathBuilderLike): ImportanceIndex {
 	using db = new DatabaseClient<CandidateDatabase>(databasePath, { readOnly: true })
 
 	const groups = new Map<string, ScoredPlace[]>()