@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/proximity-rerank.ts

@@ -3,23 +3,24 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The proximity re-rank (#938): with bias hints — the demo's map viewport, a user location — re-order exact-match
- *   candidates by population and nearness on one additive scale, so an in-view namesake wins a tie without a hard
- *   filter. Byte-identical to plain population order when no bias is passed.
+ *   Re-order exact-match candidates by population and nearness on one additive scale when bias hints
+ *   are present (the demo's map viewport, a user location), so an in-view namesake wins a tie
+ *   without a hard filter. With no bias the order is plain population order, byte-identical.
  *
- *   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 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.
+ *   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 server and demo parity
+ *   interface held by construction. Constants by themselves were not enough, since 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.
  *
  *   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
- *      whenever a viewport hint happens to be present.
- *   2. The combined value is PERSISTED into `prominence`. The resolver walk re-sorts by `prominence ?? score`, so a
- *      caller that only returns the array in bias order has its ordering silently discarded downstream.
+ *   1. The population base is `prominence ?? score`. `prominence` contains the bounded cross-country
+ *      primary preference, so reading raw score lets a coincidental foreign alias ride population
+ *      back over a primary whenever a viewport hint happens to be present.
+ *   2. The combined value is persisted into `prominence`. The resolver walk re-sorts by
+ *      `prominence ?? score`, so a caller that only returns the array in bias order has its
+ *      ordering silently discarded downstream.
  */
 
 import { haversineKm } from "@mailwoman/spatial"
@@ -35,24 +36,27 @@ export const BIAS_BOOST = 4
 export const POP_BOOST = 4
 
 /**
- * `log10(population + 1)` at which the population term saturates — 6 means a population of one million earns the whole
- * {@link POP_BOOST}, and larger populations earn no more.
+ * `log10(population + 1)` at which the population term saturates.
+ *
+ * A value of 6 means a population of one million warrants the whole {@link POP_BOOST},
+ * and larger populations warrant no more.
  */
 export const POP_SCALE_LOG10 = 6
 
 /**
  * Distance at which the nearness term halves.
  *
- * SHARPER than the FTS reader's 100 km on purpose: the candidate backend's score is log-population ALONE, with no bm25
- * document term, so the population signal is weaker relative to the bias and a gentle 100 km decay let a 230 km-distant
- * alias-exact township ("Paris Township", OH) edge out a global city ("Paris", FR) from a nearby view. At ~30 km the
- * boost reaches only candidates the user is actually looking at: an in-view namesake still wins (Dublin, OH from an
- * Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
+ * Sharper than the FTS reader's 100 km on purpose, because the candidate backend's
+ * score is log-population by itself with no bm25 document term.
+ * This weakens the population signal relative to the bias.
+ *
+ * At around 30 km the boost reaches only candidates the user is looking at,
+ * so an in-view namesake still wins and a distant one does not.
  */
 export const PROX_SCALE_KM = 30
 
 /**
- * One bias hint — a coordinate the user is looking at or standing on, optionally weighted.
+ * One bias hint, a coordinate the user is looking at or standing on, optionally weighted.
  */
 export interface ProximityBias {
 	lat: number
@@ -61,27 +65,31 @@ export interface ProximityBias {
 }
 
 /**
- * The candidate fields the re-rank reads and writes. Structural rather than a concrete candidate type, so the Node
- * reader's `PlaceCandidate` and the browser twin's row shape both satisfy it without an adapter.
+ * The candidate fields the re-rank reads and writes.
+ *
+ * This is structural, so the Node reader's `PlaceCandidate` and the browser twin's
+ * row shape both satisfy it without an adapter.
  */
 export interface ProximityRerankable {
 	lat: number
 	lon: number
 	score: number
-	prominence?: number
+	prominence?: number | null
 }
 
 /**
- * Population plus nearness on one additive scale. Exported for tests and for a caller that wants the value without the
- * sort; ordinary callers want {@link applyProximityRerank}.
+ * Population plus nearness on one additive scale.
+ *
+ * Exported for tests and for a caller that wants the value without the sort.
+ * Ordinary callers want {@link applyProximityRerank}.
  */
 export function combinedProminence(candidate: ProximityRerankable, bias: readonly ProximityBias[]): number {
 	const popBase = candidate.prominence ?? candidate.score
 	const popTerm = POP_BOOST * Math.min(1, Math.max(0, popBase) / POP_SCALE_LOG10)
 	let proxTerm = 0
 
-	// A candidate at the null island has no coordinate, not a coordinate at 0,0 — it earns no nearness term rather
-	// than an enormous one.
+	// A candidate at the null island has no coordinate, so it warrants no nearness term.
+	// A 0,0 pair interpreted as a real coordinate would receive an enormous score.
 	if (!(candidate.lat === 0 && candidate.lon === 0)) {
 		for (const b of bias) {
 			const d = haversineKm(b.lat, b.lon, candidate.lat, candidate.lon)
@@ -97,10 +105,13 @@ export function combinedProminence(candidate: ProximityRerankable, bias: readonl
 }
 
 /**
- * Re-order `candidates` in place by {@link combinedProminence}, persisting each combined value into `prominence` so the
- * resolver walk's own `prominence ?? score` sort carries the bias order rather than undoing it. Stable within equal
- * prominence, preserving the population order the index already gave. A caller with no bias hints must not call this —
- * the no-bias path is plain population order by construction.
+ * Re-order `candidates` in place by {@link combinedProminence}, persisting each
+ * combined value into `prominence` so the resolver walk's own `prominence ?? score`
+ * sort preserves the bias order rather than undoing it.
+ *
+ * Stable within equal prominence, preserving the population order the index already gave.
+ * A caller with no bias hints must not call this.
+ * The no-bias path is plain population order by construction.
  */
 export function applyProximityRerank<T extends ProximityRerankable>(
 	candidates: T[],
@@ -112,7 +123,7 @@ export function applyProximityRerank<T extends ProximityRerankable>(
 
 			return { c, i, p: c.prominence }
 		})
-		// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+		// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array. toSorted would double-allocate on a hot path
 		.sort((a, b) => b.p - a.p || a.i - b.i)
 		.forEach((x, j) => (candidates[j] = x.c))
 

package/lib/ranking-weights.ts

@@ -3,14 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   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 change at a time.
+ *   The locality-ranking weights and their shipped defaults live here because each value is a measured tuning decision
+ *   with its rationale attached. This block reads as a reference table outside the lookup's control flow.
+ *   Tests import it directly to pin one change at a time.
  */
 
 /**
- * Ranking weights for `findPlace`. Tweakable per-instance but defaults match the values declared in the Phase 4.2 plan
- * doc.
+ * The weights used to rank `findPlace` results.
+ *
+ * Tweakable per-instance but defaults match the values declared in the Phase 4.2 plan doc.
  */
 export interface RankingWeights {
 	/**
@@ -38,83 +39,110 @@ export interface RankingWeights {
 	 */
 	lengthPenaltyWeight: number
 	/**
-	 * Magnitude of the proximity boost when the query carries `near`. The contribution is `proximityBoost / (1 +
-	 * distanceKm / proximityScaleKm)` — at distance 0 the boost is full magnitude, at `proximityScaleKm` it's half,
-	 * decaying further with distance. Default tuned so proximity can overcome a typical FTS rank tie but not dominate a
-	 * strong text match.
+	 * Magnitude of the proximity boost when the query includes `near`.
+	 *
+	 * The contribution is `proximityBoost / (1 + distanceKm / proximityScaleKm)`.
+	 * At distance 0 the boost has full magnitude.
+	 *
+	 * At `proximityScaleKm` it is half magnitude.
+	 * It decays further as distance increases.
+	 *
+	 * Its default is tuned so proximity can overcome a typical FTS rank tie
+	 * but not dominate a strong text match.
 	 */
 	proximityBoost: number
 	/**
-	 * Magnitude of the bias-hint term inside the exact-tier PROMINENCE sort (the `bias`/viewport path). Deliberately
-	 * population-scale (default = populationBoost) so a candidate near the map view / the user beats a distant-but-bigger
-	 * namesake — "the map view wins" is the feature; same-region ties (all candidates far from every hint) still fall to
-	 * population.
+	 * Magnitude of the bias-hint term inside the exact-tier prominence sort (the `bias`/viewport path).
+	 *
+	 * Deliberately population-scale, so a candidate near the map view
+	 * or the user beats a distant-but-bigger namesake.
+	 * "The map view wins" is the feature.
+	 *
+	 * Same-region ties, where all candidates are far from every hint, still fall to population.
+	 *
+	 * @defaultValue the same value as `populationBoost`
 	 */
 	biasBoost: number
 	/**
-	 * Distance (km) at which the proximity boost halves. Tune to the typical query radius.
+	 * Distance (km) at which the proximity boost halves.
+	 *
+	 * Tune to the typical query radius.
 	 */
 	proximityScaleKm: number
 	/**
-	 * Magnitude of the population boost when the candidate has a known `wof:population`. The contribution is
-	 * `populationBoost * log10(1 + population) / populationScaleLog10`, capped at `populationBoost`. WOF only carries
-	 * population for ~15% of localities (mostly larger ones); places without it get +0 (never a penalty). Default tuned
-	 * so the famous Springfield, IL (pop ~112k) gets ~0.42 boost — enough to nudge past tiny same-name peers.
+	 * Magnitude of the population boost when the candidate has a known `wof:population`.
+	 *
+	 * The contribution is `populationBoost * log10(1 + population) / populationScaleLog10`,
+	 * capped at `populationBoost`.
+	 * WOF records population for about 15% of localities (mostly larger ones),
+	 * and places without it get +0, never a penalty.
+	 *
+	 * Its default is tuned so the famous Springfield, IL (pop ~112k) gets about a 0.42 boost,
+	 * enough to nudge past tiny same-name peers.
 	 */
 	populationBoost: number
 	/**
-	 * Population (in log10) at which the boost reaches its full magnitude. Default 6 — i.e. a population of 1,000,000
-	 * gives `populationBoost` exactly. Larger populations cap at the same value (no compounding effect for megacities).
+	 * Population (in log10) at which the boost reaches its full magnitude.
+	 *
+	 * Larger populations cap at the same value (no compounding effect for megacities).
+	 *
+	 * @defaultValue `6`, so a population of 1,000,000 gives `populationBoost` exactly
 	 */
 	populationScaleLog10: number
 	/**
-	 * Tier candidates with an EXACT name/alias match above candidates that only match partially, BEFORE the weighted-sum
-	 * score is consulted. Default true.
-	 *
-	 * Why this is needed (and why it ALIGNS with — rather than overrides — the population/importance signal): the
-	 * weighted sum adds population as a large additive boost (`populationBoost`, up to +4) so that famous places surface
-	 * for unambiguous full-name queries. But population is a _prominence prior_ — its job is to break ties among
-	 * candidates that match the query EQUALLY WELL (e.g. "Springfield" → Springfield IL over Springfield MA, both exact
-	 * name matches). It was never meant to promote a place that matches the query WORSE. For a 2-letter region
-	 * abbreviation that backfires: querying "ME" returns Maine (which has the exact alias `ME`) AND Missouri/
-	 * Michigan/etc. (which do not), and Missouri's larger population (+4) overcomes Maine's bm25 edge — so "Portland, ME"
-	 * resolves its region to Missouri and the locality then cascades to the wrong state. Tiering restores the intended
-	 * ordering: **match quality is the primary key, prominence (population) the secondary key WITHIN a tier.**
-	 * Springfield-IL-over-MA still works (both exact → same tier → population decides); ME→Maine now works (only Maine is
-	 * exact → higher tier → population never gets to override it). See
-	 * docs/articles/evals/resolver-geo/2026-05-30-resolver-exact-match.md.
-	 *
-	 * Note: tiering re-ranks within the over-fetched candidate window (`limit * 4`); a pathological exact match that
-	 * falls outside that window is not rescued. For the region-abbrev case the window is comfortably sufficient (a
-	 * handful of states match a 2-letter query).
+	 * Tier candidates with an exact name/alias match above candidates that only match
+	 * partially, before the weighted-sum score is consulted.
+	 *
+	 * The weighted sum adds population as a large additive boost, so famous places
+	 * surface for unambiguous full-name queries.
+	 * Population is a prominence prior.
+	 *
+	 * Its job is to break ties among candidates that match the query equally well,
+	 * as in "Springfield" → Springfield IL over Springfield MA.
+	 *
+	 * It does not promote a place that matches the query worse.
+	 * Tiers keep match quality as the primary key and prominence as the secondary key within each tier.
+	 *
+	 * Note: tiering re-ranks within the over-fetched candidate window (`limit * 4`),
+	 * so a pathological exact match outside that window is not rescued.
+	 *
+	 * @defaultValue `true`
 	 */
 	exactMatchTiering: boolean
 	/**
-	 * #936 option 3 — official-language names ARE names. When true, a candidate holding the query as an OFFICIAL name
-	 * (`names.official = 1`: a preferred-form name in an official language of its country, stamped at ingest) joins the
-	 * NAME-exact sub-tier rather than the alias-exact one, provided its population clears {@link officialNameExactFloor}.
-	 * 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 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.
+	 * Official-language names count as names.
+	 *
+	 * When true, a candidate holding the query as an official name (`names.official = 1`,
+	 * a preferred-form name in an official language of its country, stamped at ingest)
+	 * joins the name-exact sub-tier rather than the alias-exact one, provided its
+	 * population clears {@link officialNameExactFloor}.
+	 *
+	 * Fixes unscoped "Åbo" → Turku (its official Swedish name) over a hamlet literally called Åbo.
+	 * Population still orders within the sub-tier, so Paris → Paris FR is untouched.
+	 *
+	 * It requires a gazetteer carrying the `official` ingest bit.
+	 *
+	 * On older DBs without that column, the probe fails soft and behavior matches the flag being off.
+	 *
+	 * @defaultValue `true`
 	 */
 	officialNameExact: boolean
 	/**
-	 * Minimum population for a candidate's official names to join the name-exact sub-tier. The #936 review's no-floor
-	 * census measured the boundary: ≥100k holders are the famous-exonym class (757 flips, intent-correct; 7 collisions,
-	 * none harmful) while 10k–100k holders are junk-dominated (3,481 flips led by short-form mis-tags — Villeneuve-Loubet
-	 * carrying "villeneuve" would bury five real villages of that name). Rank-time knob: tunable without re-ingest;
-	 * below-floor official names simply stay alias-tier (today's behavior).
+	 * Minimum population for a candidate's official names to join the name-exact sub-tier.
+	 *
+	 * The floor separates the famous-exonym class from a junk-dominated one led by short-form
+	 * mis-tags, where a place carrying a short form would bury real villages of that name.
+	 * This is a rank-time knob, tunable without re-ingest.
+	 * Below-floor official names stay in the alias tier.
 	 */
 	officialNameExactFloor: number
 }
 
 /**
- * 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 change moves and what motivated its current value.
+ * The shipped weights.
+ *
+ * Every value is a measured decision, so change one and re-run the resolver eval.
+ * The per-field docs on {@link RankingWeights} say what each change moves.
  */
 export const DEFAULT_WEIGHTS: RankingWeights = {
 	placetypeMatchBoost: 0.5,
@@ -126,34 +154,31 @@ export const DEFAULT_WEIGHTS: RankingWeights = {
 	proximityBoost: 0.8,
 	proximityScaleKm: 100,
 	biasBoost: 4,
-	// populationBoost is intentionally large — empirical tuning against real WOF showed BM25 gaps
-	// of 1.5-3.0 between famous places and tiny same-name peers (because the famous ones have
-	// hundreds of alt-name entries that hurt their FTS document score). To consistently surface
-	// "the famous one" for unambiguous queries like "New York" or "Chicago", the population signal
-	// needs to dominate. Callers wanting a more conservative balance can drop this in the
-	// RankingWeights override.
-	//
-	// Note: this resolver uses `place_population` directly. The separate `place_importance` table
-	// (Wikipedia-derived) is consumed by the FST layer, not here. See
-	// docs/articles/concepts/importance-vs-population.md for the two-signal contract.
+	// populationBoost is intentionally large.
+	// Real WOF showed BM25 gaps of 1.5 to 3.0 between famous places and tiny same-name peers,
+	// because the famous ones have hundreds of alt-name entries that hurt their FTS document score.
+	// This resolver reads `place_population` directly.
+	// The separate Wikipedia-derived `place_importance` table is consumed by the FST layer.
 	populationBoost: 4,
 	populationScaleLog10: 6,
-	// Exact name/alias match outranks partial match before the weighted sum (incl. population) is
-	// 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).
+	// Exact name and alias matches outrank partial matches before the weighted sum.
+	// This keeps population as an intra-tier prominence tiebreaker instead of a cross-tier promoter.
 	exactMatchTiering: true,
-	// #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.
+ * The population contribution as a 0..1 fraction: `min(1, log10(1 + population) / populationScaleLog10)`.
+ *
+ * Returns zero for an absent or non-positive population.
+ * It also returns zero for a non-positive scale.
+ *
+ * A magnitude never represents its own absence.
+ * The coordinate-first locality path consumes this fraction directly. {@link populationBoostTerm} scales it.
  */
 export function populationScaleTerm(
-	population: number | null | undefined,
+	population: number | null,
 	weights: Pick<RankingWeights, "populationScaleLog10">
 ): number {
 	if (population == null || population <= 0 || weights.populationScaleLog10 <= 0) return 0
@@ -162,12 +187,14 @@ export function populationScaleTerm(
 }
 
 /**
- * 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.
+ * The additive population boost: `populationBoost * populationScaleTerm(...)`,
+ * capped at `populationBoost` magnitude at `10^populationScaleLog10` people.
+ *
+ * A missing population contributes 0, without 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,
+	population: number | null,
 	weights: Pick<RankingWeights, "populationBoost" | "populationScaleLog10">
 ): number {
 	return weights.populationBoost * populationScaleTerm(population, weights)

package/lib/region-keys.ts

@@ -3,15 +3,13 @@
  * @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`
+ *   Both consumers use this expansion to compare parsed region qualifiers with stored keys.
+ *   Admin-coherence verdicts (`mailwoman/admin-coherence.ts`) fold a qualifier and the winner's ancestry
+ *   to decide `confirmed` or `contradicted`. The candidate backend's admin-containment re-rank
+ *   (`candidate-lookup.ts`) uses the same fold to find region-class rows. The shared function keeps
+ *   both decisions aligned.
+ *
+ *   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.
  */
@@ -21,26 +19,39 @@ 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.
+ * The ancestry placetypes that answer for a parsed `region` qualifier,
+ * WOF's admin band between country and locality.
+ *
+ * The full band covers qualifiers at any grain, such as "Lancashire"
+ * (a ceremonial county) or "Thüringen" (a Land).
+ * A qualifier may confirm against any level the backend stored.
+ *
+ * `contradicted` requires every level in the band to miss.
+ * A wider band 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.
+ * 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 would read `contradicted`.
+ * The stripped form is added to the key set, never substituted.
+ *
+ * `County Durham` is a real name that also matches after prefix removal.
+ * 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.
+ * Admin-qualifier words at the end, the suffix form 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
 
@@ -83,14 +94,20 @@ function withoutSuffix(value: string, suffixes: readonly string[]): string {
 }
 
 /**
- * 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.
+ * The comparable keys a region string expands to: its own fold (the shared candidate.db `name_key`
+ * normalizer, {@link normalizeLocalityForKey}, so build side and check side agree by construction).
+ *
+ * A county-prefix-stripped variant.
+ * The codex subdivision expansions.
+ *
+ * The disjoint US and CA table always, plus the country-scoped table when the caller knows a country.
+ * `WA` under AU is Western Australia, while under US it is 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`
+ * and `Illinois`, or `WA` and `Western Australia`, meet from either side.
  */
-export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
+export function regionKeys(value: string, countryAlpha2?: string | null): Set<string> {
 	const keys = new Set([normalizeLocalityForKey(value)])
 
 	for (const stripped of [
@@ -111,25 +128,36 @@ export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
 		}
 	}
 
-	// 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.
+	// 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.
+ * 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 matches the stored fold verbatim in one direction.
+ *
+ * WOF stores Irish counties under `county donegal`.
+ * The table has no bare `donegal` key.
+ *
+ * The qualifier probe missed every Irish county until this variant landed.
+ *
+ * The `county <key>` form restores two-sidedness for the one stored-form family with an evidenced case.
+ * The union is monotone because a wider qualifier set can only find more bearers.
+ *
+ * Each bearer must still contain a candidate before anything moves.
+ *
+ * The suffix sibling (`<key> province`) is deliberately absent.
+ * The board has no case for this stored form.
+ * Add one before building a change for this suffix.
  */
-export function regionQualifierProbeKeys(value: string, countryAlpha2?: string): Set<string> {
+export function regionQualifierProbeKeys(value: string, countryAlpha2?: string | null): 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]