@mailwoman/resolver-wof-sqlite 9.0.0 → 9.2.0

package/candidate-schema.ts

@@ -17,6 +17,10 @@
 
 import { sql, type Kysely } from "kysely"
 
+import type { CandidateAncestorsDatabase } from "./candidate-ancestors-schema.ts"
+import type { CapitalTable } from "./capital-schema.ts"
+import type { NameKey } from "./street-normalize.ts"
+
 /**
  * One candidate row. `name_key` + the four small int keys + `neg_rank` + `spr_id` form the clustered primary key; the
  * rest is denormalized so a resolve is one probe (no join to `spr`). Coordinates + bbox + name are nullable at the SQL
@@ -26,7 +30,7 @@ export interface CandidateTable {
 	/**
 	 * The shared {@link normalizeLocalityForKey} of the name/alias — the probe key.
 	 */
-	name_key: string
+	name_key: NameKey
 	/**
 	 * Small int from {@link CountryCodeTable} (shrinks the clustered key).
 	 */
@@ -59,6 +63,45 @@ export interface CandidateTable {
 	 * 1 when the row is the place's canonical name (vs an alias/abbrev).
 	 */
 	is_primary: number | null
+	/**
+	 * Blended place importance in [0, 1] — the toponym-fame prior the bare-city-name class is decided on (#28). NULL
+	 * means the score source had no row for this place: UNMEASURED, never "an importance of zero" (meaning-of-zero).
+	 * Constant across every row of one place — primary, alias and abbrev alike — because it is a property of the PLACE,
+	 * not of the name that reached it, which is what lets a bare `Moscow` inherit Москва's score through the alias row.
+	 *
+	 * **THIS IS THE PRE-SPLIT CONFLATION, AND THE NAME SAYS SO.** It is `place_importance.importance` copied verbatim
+	 * from the score source — the bounded blend `place-importance-schema.ts`'s `blendImportance` writes (the
+	 * concordance's encyclopedia-derived channel clamped around a population-derived base); that module calls the column
+	 * DEPRECATED. It is NOT the split `encyclopedic` channel, and the two must not be conflated in a future build:
+	 * writing the split value here instead was measured on 2026-08-10 and makes the ranking key INERT on three of the
+	 * four rows it exists to fix. The reason is coverage, not principle — the encyclopedia-concordance join in
+	 * `admin-global-priority-importance.db` reaches 133,888 of 702,709 scored places and only eleven countries
+	 * (US/FR/GB/DE/IT/ES/NL/JP/CN/KR/TW). CA, AU and RU have ZERO concordance rows, so Whitby CA, Windsor CA and Epping
+	 * AU carry the population fallback and nothing else. Under the strict split those three become unmeasured, the
+	 * consumer's positive-evidence-only rule leaves them exactly where population put them (first), and the famous GB
+	 * bearer can never overtake them. The conflated column is the only one on which every bearer of a name is scored on a
+	 * single comparable scale, which is the precondition for comparing them at all.
+	 *
+	 * So a consumer reads this as "fame, with population standing in where fame was never measured" — the legacy blended
+	 * semantics — and NOT as "this place has an encyclopedia entry of this importance". When the score source grows a
+	 * real `encyclopedic` column for every country, add a SECOND column rather than redefining this one.
+	 */
+	importance: number | null
+	/**
+	 * The NAME'S detected role on this row, or NULL (#1730). Two build-time detectors stamp `is_primary = 0` rows only:
+	 *
+	 * - `'abbr'` — provenance-based: the surface is a WOF `variant` name in one of the place's country's official languages
+	 *   (or English) — the #936 signal, measured at a 13× key-collision rate vs preferred names.
+	 * - `'gloss'` — anomaly-based: the row belongs to a place whose key count crosses the gloss threshold with a non-admin
+	 *   placetype and NO measured prominence (population absent AND importance unmeasured) — the translation-gloss
+	 *   fingerprint (#1730's sweep; `Poisson` → a US fish-name place). Provenance CANNOT separate a gloss from an exonym
+	 *   (WOF imported both as `x_preferred`), which is why this detector is an anomaly test and stamps only the certain
+	 *   core.
+	 *
+	 * NULL = no role detected. The column is WRITE-ONLY in this build generation: no ranking consumer reads it — a rank
+	 * penalty is its own future, D-rule-gated step with the `gloss_key` board as tripwire.
+	 */
+	name_role: string | null
 }
 
 /**
@@ -78,9 +121,11 @@ export interface PlacetypeCodeTable {
 }
 
 /**
- * The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`.
+ * The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`. Extends the ancestors sidecar
+ * (`candidate_ancestor` + `candidate_interval` — see candidate-ancestors-schema.ts for the encoding decision), so the
+ * builder's one typed client covers every table in the artifact.
  */
-export interface CandidateDatabase {
+export interface CandidateDatabase extends CandidateAncestorsDatabase {
 	/**
 	 * The clustered `WITHOUT ROWID` lookup table the reader probes.
 	 */
@@ -91,6 +136,10 @@ export interface CandidateDatabase {
 	cand_stage: CandidateTable
 	country_codes: CountryCodeTable
 	placetype_codes: PlacetypeCodeTable
+	/**
+	 * The capital-status reference carried in-artifact (#1880's distribution home) — see capital-schema.ts.
+	 */
+	capital: CapitalTable
 }
 
 /**
@@ -114,6 +163,10 @@ export const CANDIDATE_COLUMNS = [
 	"max_lon",
 	"population",
 	"is_primary",
+	// Appended, never inserted mid-list: the first six entries ARE the clustered primary key, and the
+	// positional `INSERT INTO cand_stage VALUES (…)` in the builder binds by position.
+	"importance",
+	"name_role",
 ] as const
 
 /**
@@ -151,6 +204,8 @@ export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>
 		.addColumn("max_lon", "real")
 		.addColumn("population", "integer")
 		.addColumn("is_primary", "integer")
+		.addColumn("importance", "real")
+		.addColumn("name_role", "text")
 		.execute()
 }
 
@@ -176,6 +231,8 @@ export async function createCandidateTable(db: Kysely<CandidateDatabase>): Promi
 		.addColumn("max_lon", "real")
 		.addColumn("population", "integer")
 		.addColumn("is_primary", "integer")
+		.addColumn("importance", "real")
+		.addColumn("name_role", "text")
 		.addPrimaryKeyConstraint("candidate_pk", [
 			"name_key",
 			"country_id",

package/candidate-scoring.ts

@@ -0,0 +1,268 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   How a raw `place_search` row becomes a scored `PlaceCandidate`, and how the resulting pool is
+ *   ordered — the weighted-sum score and the exact-match tiering that ranks over it.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { haversineKm } from "@mailwoman/spatial"
+
+import { exactMatchIDs, officialNameIDs } from "./exact-match.ts"
+import { compareReferential, referentialFromPopulation } from "./place-importance-schema.ts"
+import type { RankingWeights } from "./ranking-weights.ts"
+import type { RawSearchRow } from "./search-fetch.ts"
+import type { FindPlaceQuery, PlaceCandidate, WOFPlacetype } from "./types.ts"
+
+/**
+ * Score one raw FTS row into a `PlaceCandidate`: the weighted sum over the negated BM25 baseline, the placetype /
+ * country / parent boosts, the length penalty, the proximity and population terms, and the carried fields (referential,
+ * encyclopedic, bbox) consumers read. `queryLen` is the query text's length, hoisted out of the per-row loop.
+ */
+export function candidateFromSearchRow(
+	row: RawSearchRow,
+	context: {
+		query: FindPlaceQuery
+		placetypes: WOFPlacetype[] | null
+		queryLen: number
+		weights: RankingWeights
+	}
+): PlaceCandidate {
+	const { query, placetypes, queryLen, weights } = context
+
+	// SQLite's bm25() returns a lower-is-better score (negative for matches). Negate so we
+	// start from a higher-is-better baseline.
+	let score = -row.rank
+
+	if (placetypes && placetypes.length && placetypes.includes(row.placetype as WOFPlacetype)) {
+		score += weights.placetypeMatchBoost
+	}
+
+	if (!placetypes && row.placetype === "locality") {
+		score += weights.localityImplicitBoost
+	}
+
+	if (query.country && row.country === query.country) {
+		score += weights.countryMatchBoost
+	}
+
+	if (query.parentID !== undefined) {
+		score += row.parent_id === query.parentID ? weights.directChildBoost : weights.descendantBoost
+	}
+
+	const extraLen = Math.max(0, row.name.length - queryLen - 3)
+	score -= (weights.lengthPenaltyWeight * extraLen) / 10
+
+	// Proximity boost: only applied when the query carries `near` AND the candidate has real
+	// coordinates. The formula decays smoothly with distance so close-but-not-exact hits
+	// still benefit; tunable via proximityBoost + proximityScaleKm.
+	let distanceKm: number | undefined
+	// The best decayed-distance term over `near` + every `bias` point (each point's term is
+	// scaled by its weight; the MAX wins — a candidate near ANY hint is "nearby"). Carried
+	// into the exact-tier prominence sort below when hints are present.
+	let proximityTerm = 0
+
+	if (row.lat !== null && row.lon !== null && !(row.lat === 0 && row.lon === 0)) {
+		const hints: Array<{ lat: number; lon: number; weight: number }> = []
+
+		if (query.near) {
+			hints.push({ lat: query.near.lat, lon: query.near.lon, weight: 1 })
+		}
+
+		for (const b of query.bias ?? []) {
+			hints.push({ lat: b.lat, lon: b.lon, weight: b.weight ?? 1 })
+		}
+
+		let scoreTerm = 0
+
+		for (const h of hints) {
+			const d = haversineKm(h.lat, h.lon, row.lat, row.lon)
+			const decay = h.weight / (1 + d / weights.proximityScaleKm)
+			const prom = decay * weights.biasBoost
+
+			if (prom > proximityTerm) {
+				proximityTerm = prom
+				distanceKm = d
+				scoreTerm = decay * weights.proximityBoost
+			}
+		}
+
+		score += scoreTerm
+	}
+
+	// Population boost: capped at `populationBoost` magnitude at `10^populationScaleLog10`
+	// people. Missing population → no contribution. Never penalizes.
+	let popTerm = 0
+
+	if (row.population !== null && row.population > 0 && weights.populationScaleLog10 > 0) {
+		const popLog = Math.log10(1 + row.population)
+		const popFraction = Math.min(1, popLog / weights.populationScaleLog10)
+		popTerm = weights.populationBoost * popFraction
+		score += popTerm
+	}
+
+	// Combined prominence for the exact-tier sort when proximity hints are present: population
+	// and nearness in the SAME additive units, so the map view / the user's location can win a
+	// cross-country postcode tie without a hard filter.
+	const prominence = popTerm + proximityTerm
+
+	const candidate: PlaceCandidate = {
+		id: row.id,
+		prominence,
+		name: row.name,
+		placetype: row.placetype as WOFPlacetype,
+		country: row.country ?? "",
+		lat: row.lat ?? 0,
+		lon: row.lon ?? 0,
+		parent_id: row.parent_id ?? undefined,
+		score,
+	}
+
+	if (distanceKm !== undefined) {
+		candidate.distanceKm = distanceKm
+	}
+
+	if (row.population !== null && row.population > 0) {
+		candidate.population = row.population
+		// The named ranking key (ROAD_TO_V9 §2). DERIVED, not stored — a pure function of the
+		// population already on this row, so it cannot drift from what the ordering uses.
+		candidate.referential = referentialFromPopulation(row.population)
+	}
+
+	// Carried for consumers (annotations / API surfaces). No ranking site reads it.
+	if (row.encyclopedic !== null) {
+		candidate.encyclopedic = row.encyclopedic
+	}
+
+	// Candidate bbox — parity with the WASM lookup (resolver-wof-wasm/lookup.ts), whose
+	// consumers (the demo cascade's region constraint) read it. Without this the Node
+	// backend's region→bbox constraint is dead and disambiguation falls to population
+	// ranking (the Springfield-IL→MO failure the #524 smoke eval caught).
+	if (row.min_latitude != null && row.max_latitude != null && row.min_longitude != null && row.max_longitude != null) {
+		candidate.bbox = {
+			minLat: row.min_latitude,
+			maxLat: row.max_latitude,
+			minLon: row.min_longitude,
+			maxLon: row.max_longitude,
+		}
+	}
+
+	return candidate
+}
+
+/**
+ * Order `candidates` IN PLACE — the exact-match tier first when the shard can answer the name probes, otherwise plain
+ * weighted-score order. Every candidate is stamped with its `exactMatch` flag on the way through.
+ */
+export function rankCandidates(
+	candidates: PlaceCandidate[],
+	options: {
+		db: DatabaseSync
+		schemaName: string
+		query: FindPlaceQuery
+		weights: RankingWeights
+	}
+): void {
+	const { db, schemaName, query, weights } = options
+
+	// Exact-match tiering: a candidate whose name OR any alias equals the query text (case-folded)
+	// ranks above any partial match, with the weighted-sum score (incl. population) breaking ties
+	// WITHIN a tier. See the RankingWeights.exactMatchTiering docstring for why this aligns the
+	// population prior rather than overriding it. One cheap indexed lookup over the candidate ids.
+	// Runs even for a SINGLE candidate so `exactMatch` is stamped consistently (parity with the
+	// WASM lookup) — a sole alias hit ("New York City" → New York) must still carry the flag the
+	// demo cascade / #369 re-rank read.
+	if (weights.exactMatchTiering && candidates.length) {
+		const exactIDs = exactMatchIDs(
+			db,
+			schemaName,
+			candidates.map((c) => c.id as number),
+			query.text
+		)
+
+		// Stamp the tier onto every candidate (not just when the tiering sort fires) so a downstream
+		// re-rank — #369's postcode-anchor country pin in `resolveTree` — can keep the country pin from
+		// crossing the exact/partial boundary ("ME" → Maine, not the more-populous Missouri).
+		for (const c of candidates) {
+			c.exactMatch = exactIDs.has(c.id as number)
+		}
+
+		if (exactIDs.size) {
+			// #905: WITHIN the exact tier, population is the PRIMARY key and the weighted score
+			// only breaks population ties. Exactness saturates text relevance, and the bm25
+			// residue inside `score` is length-noise (see the fetch-site comment), so letting it
+			// order the tier is what sent unscoped "Paris" to an Ohio township. The partial tier
+			// keeps score order — text relevance still means something there. This makes the
+			// exactMatchTiering docstring literal: match quality primary, prominence within.
+			//
+			// #912 sub-tier: a NAME-exact candidate (spr.name equals the query) outranks an
+			// ALIAS-exact one ('Paris' the place beats 'Paris Township' held via alias 'Paris').
+			// The place's own name is a stronger identity claim than an alias — aliases exist to
+			// widen recall, not to tie primaries. ME→Maine is untouched: 'ME' name-exact-matches
+			// nothing, so the alias sub-tier still decides there. Population orders within each
+			// sub-tier as before.
+			const norm = (v: string): string => v.toLowerCase().trim().replaceAll(/\s+/g, " ")
+			const needle = norm(query.text)
+
+			// #936 option 3: an OFFICIAL name (preferred form in an official language of the place's
+			// country, `names.official = 1`) counts as the place's own name for the sub-tier — "Åbo" is
+			// Turku's name, not merely its alias. Floor-gated on the holder's population (see the
+			// RankingWeights docstring for the measured 100k boundary). officialIDs ⊆ exactIDs by
+			// construction (official rows are names rows), so only the sub-tier KIND changes.
+			const officialIDs = weights.officialNameExact
+				? officialNameIDs(
+						db,
+						schemaName,
+						candidates
+							.filter((c) => exactIDs.has(c.id as number) && (c.population ?? 0) >= weights.officialNameExactFloor)
+							.map((c) => c.id as number),
+						query.text
+					)
+				: undefined
+
+			const kind = (c: PlaceCandidate): number => {
+				if (!exactIDs.has(c.id as number)) return 0
+
+				if (norm(String(c.name ?? "")) === needle) return 2
+
+				return officialIDs?.has(c.id as number) ? 2 : 1
+			}
+
+			// With proximity hints (near/bias), prominence (population + nearness, same units)
+			// replaces raw population as the within-tier key — the 48026 rule: the map view or
+			// the user's location breaks a cross-country postcode tie. Without hints, REFERENTIAL
+			// ordering decides.
+			//
+			// ROAD_TO_V9 §2: this is the site that "orders namesakes", so it is the site that has to
+			// say what it orders by. `compareReferential` is referential DESC with raw population as
+			// the tiebreak, which is provably the SAME ORDER as the `(b.population ?? 0) - (a.population ?? 0)`
+			// it replaces — referential is strictly increasing in population below saturation and
+			// constant above it, and the tiebreak restores the order in the saturated tail. Measured
+			// zero-delta, not assumed: see `place-importance-schema.test.ts` and `resolver-referential-ranking.test.ts`.
+			// Encyclopedic importance is not, and must not become, an input here.
+			const hasHints = !!query.near || (query.bias?.length ?? 0) > 0
+
+			candidates.sort((a, b) => {
+				const ax = kind(a)
+				const bx = kind(b)
+
+				if (bx !== ax) return bx - ax
+
+				if (ax >= 1) {
+					if (hasHints) return (b.prominence ?? 0) - (a.prominence ?? 0) || b.score - a.score
+
+					return compareReferential(a, b) || b.score - a.score
+				}
+
+				return b.score - a.score
+			})
+
+			return
+		}
+	}
+
+	candidates.sort((a, b) => b.score - a.score)
+}

package/capital-schema.ts

@@ -0,0 +1,90 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The `capital` table (#1880's distribution home): the capital-status reference carried INSIDE
+ *   `candidate.db`, so an npm consumer who pulled the artifact can run `capital_tier` without the
+ *   repo's `data/gazetteer/capitals-v1.json` — which published packages do not ship. One row per
+ *   reference entry (241 national capitals + 3,463 admin-1 seats at the 2026-08-24 build); the
+ *   loader reads the WHOLE table once into a `CapitalIndex` at session construction, so there is no
+ *   per-probe query and no index beyond the rowid.
+ *
+ *   `keys` holds the entry's folded name set as a JSON array — the name-membership conjunct that
+ *   keeps the coordinate radius from promoting a capital's same-name neighbours (`capitals.ts`).
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { tryParsingJSON } from "@mailwoman/core/objects"
+import type { Kysely } from "kysely"
+
+import type { CapitalPoint } from "./capitals.ts"
+import { hasTable } from "./sqlite-utils.ts"
+
+/**
+ * The table name the builder writes and the reader probes — one word, singular, matching the artifact's other reference
+ * tables (`candidate`, `country_codes`).
+ */
+export const CAPITAL_TABLE = "capital"
+
+/**
+ * One reference entry as the artifact stores it. `level` is the reference vocabulary (`national` | `admin1`) kept as
+ * text — the reader validates on load rather than trusting bytes.
+ */
+export interface CapitalTable {
+	country: string
+	latitude: number
+	longitude: number
+	level: string
+	/**
+	 * JSON array of folded name keys (name + romanization + alternates).
+	 */
+	keys: string
+}
+
+/**
+ * Create the table on a build in progress. Async because Kysely's schema-builder is; called from the candidate build's
+ * DDL phase alongside the other typed builders.
+ */
+export async function createCapitalTable<DB extends { capital: CapitalTable }>(db: Kysely<DB>): Promise<void> {
+	await db.schema
+		.createTable(CAPITAL_TABLE)
+		.addColumn("country", "text", (c) => c.notNull())
+		.addColumn("latitude", "real", (c) => c.notNull())
+		.addColumn("longitude", "real", (c) => c.notNull())
+		.addColumn("level", "text", (c) => c.notNull())
+		.addColumn("keys", "text", (c) => c.notNull())
+		.execute()
+}
+
+/**
+ * Read the whole reference out of an artifact, or `null` when the artifact predates the table — the caller then falls
+ * back to its next source rather than treating an old artifact as "no capitals" (the meaning-of-zero rule: a missing
+ * table is UNMEASURED, an empty one is a finding).
+ */
+export function readCapitalPoints(db: DatabaseSync): CapitalPoint[] | null {
+	if (!hasTable(db, CAPITAL_TABLE)) return null
+
+	const points: CapitalPoint[] = []
+
+	for (const row of db.prepare(`SELECT country, latitude, longitude, level, keys FROM ${CAPITAL_TABLE}`).iterate()) {
+		const level = String(row.level)
+
+		if (level !== "national" && level !== "admin1") continue
+
+		const keys = tryParsingJSON<string[]>(String(row.keys))
+
+		if (!Array.isArray(keys)) continue
+
+		points.push({
+			country: String(row.country),
+			latitude: Number(row.latitude),
+			longitude: Number(row.longitude),
+			level,
+			k: keys,
+		})
+	}
+
+	return points
+}

package/capitals.ts

@@ -0,0 +1,148 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The CAPITAL-STATUS reference index (#1880) — answers, for one resolved candidate, "is this
+ *   place the national capital or an admin-1 seat of its country?". The consumer is the resolver's
+ *   bounded capital promotion (`@mailwoman/resolver`'s `promoteCapitals`, applied after the fame
+ *   key on the bare-toponym class); this module only matches, it never ranks. PURE and
+ *   platform-free (the #861 parity discipline).
+ *
+ *   Matching is an IDENTITY test with three conjuncts: same country, within
+ *   {@link CAPITAL_MATCH_RADIUS_KM} of the reference point, and the candidate's own folded name a
+ *   member of the reference entry's folded name set (name + romanization + the source's alternate
+ *   names, so exonym rows — "Vienna" for Wien — still match). All three are load-bearing. The
+ *   iteration-1 board run matched on country + coordinate alone, and the 25 km radius promoted
+ *   capital-ADJACENT namesakes instead of capitals: North Salt Lake beside the Utah seat, a Gujarat
+ *   Indiranagar beside Gandhinagar, Via delle Parti beside Perugia. The name set is what makes the
+ *   radius a centroid-drift allowance rather than a catchment.
+ */
+
+import { haversineKm } from "@mailwoman/spatial"
+
+import { normalizeLocalityForKey } from "./street-normalize.ts"
+
+/**
+ * Capital status of one candidate: national capital, admin-1 seat, or neither. Numeric so the resolver's promotion can
+ * compare levels.
+ */
+export const CAPITAL_LEVEL = {
+	none: 0,
+	admin1: 1,
+	national: 2,
+} as const
+
+export type CapitalLevel = (typeof CAPITAL_LEVEL)[keyof typeof CAPITAL_LEVEL]
+
+/**
+ * How far a candidate row may sit from the reference point and still read as the same place — a centroid-convention
+ * allowance (GeoNames point vs WOF centroid on a metro-scale city), not a catchment: the name-membership conjunct is
+ * what excludes neighbours inside the radius.
+ */
+export const CAPITAL_MATCH_RADIUS_KM = 25
+
+/**
+ * One reference entry, as `data/gazetteer/capitals-v1.json` carries it (`entries[]`).
+ */
+export interface CapitalPoint {
+	/**
+	 * ISO alpha-2, uppercase.
+	 */
+	country: string
+	latitude: number
+	longitude: number
+	level: "national" | "admin1"
+	/**
+	 * Folded name keys (name + romanization + alternate names, `normalizeLocalityForKey` fold) — the membership set for
+	 * the name conjunct.
+	 */
+	k: string[]
+}
+
+const LEVEL_OF: Record<CapitalPoint["level"], CapitalLevel> = {
+	national: CAPITAL_LEVEL.national,
+	admin1: CAPITAL_LEVEL.admin1,
+}
+
+interface IndexedPoint {
+	latitude: number
+	longitude: number
+	level: CapitalLevel
+	keys: ReadonlySet<string>
+}
+
+/**
+ * Country-bucketed capital points with the three-conjunct identity probe. Construct from the parsed reference file's
+ * `entries` — the loader that reads the file off disk lives with the path owners (`mailwoman`'s resolver backend),
+ * keeping this module platform-free.
+ */
+export class CapitalIndex {
+	readonly #byCountry = new Map<string, IndexedPoint[]>()
+
+	constructor(entries: Iterable<CapitalPoint>) {
+		for (const entry of entries) {
+			const country = entry.country.toUpperCase()
+
+			const point: IndexedPoint = {
+				latitude: entry.latitude,
+				longitude: entry.longitude,
+				level: LEVEL_OF[entry.level],
+				keys: new Set(entry.k),
+			}
+
+			const bucket = this.#byCountry.get(country)
+
+			if (bucket) {
+				bucket.push(point)
+			} else {
+				this.#byCountry.set(country, [point])
+			}
+		}
+	}
+
+	/**
+	 * The highest capital level whose entry passes all three conjuncts for this place. `none` — never a throw — for a
+	 * missing name, country, or coordinate, an unknown country, or no matching entry.
+	 */
+	levelOfPlace(
+		name: string | null | undefined,
+		country: string | null | undefined,
+		latitude: number | null | undefined,
+		longitude: number | null | undefined
+	): CapitalLevel {
+		if (!name || !country || typeof latitude !== "number" || typeof longitude !== "number") return CAPITAL_LEVEL.none
+
+		const bucket = this.#byCountry.get(country.toUpperCase())
+
+		if (!bucket) return CAPITAL_LEVEL.none
+
+		const key = String(normalizeLocalityForKey(name))
+
+		if (!key) return CAPITAL_LEVEL.none
+
+		let best: CapitalLevel = CAPITAL_LEVEL.none
+
+		for (const point of bucket) {
+			if (
+				point.level > best &&
+				point.keys.has(key) &&
+				haversineKm(latitude, longitude, point.latitude, point.longitude) <= CAPITAL_MATCH_RADIUS_KM
+			) {
+				best = point.level
+			}
+		}
+
+		return best
+	}
+
+	get size(): number {
+		let n = 0
+
+		for (const bucket of this.#byCountry.values()) {
+			n += bucket.length
+		}
+
+		return n
+	}
+}