@mailwoman/resolver-wof-sqlite 8.6.0 → 9.1.0

package/candidate-importance.ts

@@ -0,0 +1,227 @@
+/**
+ * @copyright Sister Software
+ * @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
+ *   toponym-fame prior a bare city name is decided on.
+ *
+ *   ## Why this joins on the NAME and not on the id
+ *
+ *   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.
+ *
+ *   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.
+ *
+ *   ## 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_GATE_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.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { haversineKm } from "./geo.ts"
+import { normalizeLocalityForKey } from "./street-normalize.ts"
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export const IMPORTANCE_JOIN_GATE_KM = 10
+
+/**
+ * One scored place from the source: where it is, and what it scored.
+ */
+interface ScoredPlace {
+	lat: number
+	lon: number
+	importance: number
+}
+
+/**
+ * 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.
+ */
+export interface ImportanceIndexStats {
+	/**
+	 * Scored places read out of the source.
+	 */
+	places: number
+	/**
+	 * Distinct `(name_key, country, placetype)` groups they fall into.
+	 */
+	keys: number
+	/**
+	 * 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.
+ */
+function groupKey(nameKey: string, country: string | null, placetype: string | null): string {
+	return `${nameKey}\u0000${(country ?? "").toUpperCase()}\u0000${placetype ?? ""}`
+}
+
+/**
+ * A loaded `place_importance`, probed by name + country + placetype + position.
+ */
+export class ImportanceIndex {
+	readonly #groups: Map<string, ScoredPlace[]>
+	readonly stats: ImportanceIndexStats
+	/**
+	 * Places {@link find} matched inside the gate.
+	 */
+	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.
+	 *
+	 * 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.
+	 */
+	gated = 0
+
+	constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats) {
+		this.#groups = groups
+		this.stats = stats
+	}
+
+	/**
+	 * 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 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.
+	 */
+	find(name: string, country: string | null, placetype: string | null, lat: number, lon: number): number | null {
+		const nameKey = normalizeLocalityForKey(name)
+
+		if (!nameKey) return null
+
+		const group = this.#groups.get(groupKey(nameKey, country, placetype))
+
+		if (!group) return null
+
+		let best: ScoredPlace | undefined
+		let bestKm = Infinity
+
+		for (const place of group) {
+			const km = haversineKm(lat, lon, place.lat, place.lon)
+
+			if (km < bestKm) {
+				bestKm = km
+				best = place
+			}
+		}
+
+		if (!best || bestKm > IMPORTANCE_JOIN_GATE_KM) {
+			this.gated++
+
+			return null
+		}
+
+		this.matched++
+
+		return best.importance
+	}
+}
+
+/**
+ * Read `place_importance` (joined to `spr` for the name/country/placetype/centroid) out of a WOF admin database into an
+ * {@link ImportanceIndex}.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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
+			}
+
+			const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
+			let group = groups.get(key)
+
+			if (!group) {
+				group = []
+				groups.set(key, group)
+			}
+
+			group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+
+			places++
+		}
+
+		return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
+	} finally {
+		db.close()
+	}
+}

package/candidate-lookup.ts

@@ -32,8 +32,9 @@ import type { CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "./can
 import { readGazetteerCoverageManifest } from "./coverage-manifest-schema.ts"
 import { haversineKm } from "./geo.ts"
 import { trigramJaccard } from "./lookup.ts"
+import { referentialFromPopulation } from "./place-importance-schema.ts"
 import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "./postal-city-candidate-schema.ts"
-import { hasTable } from "./sqlite-utils.ts"
+import { hasColumn, hasTable } from "./sqlite-utils.ts"
 import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.ts"
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
 
@@ -66,7 +67,14 @@ type CandidateRow = Pick<
 	| "max_lon"
 	| "neg_rank"
 	| "is_primary"
->
+	| "population"
+> &
+	// `importance` is OPTIONAL on the row rather than `number | null`, because whether the SELECT names it
+	// depends on the artifact: a candidate.db built before #28 has no such column and the probe leaves it
+	// out (see `#importanceSelect`). `undefined` therefore means "this build cannot tell you", which is the
+	// same answer as `null`'s "the score source had no measurement" — both are UNMEASURED, and the emit
+	// below collapses them into the one thing the consumer understands: no `importance` field at all.
+	Partial<Pick<CandidateTable, "importance">>
 
 /**
  * FTS5-trigram over-fetch before the trigram-Jaccard re-rank, and the minimum similarity to count as a fuzzy hit (below
@@ -75,6 +83,14 @@ type CandidateRow = Pick<
 const FUZZY_FETCH = 40
 const FUZZY_MIN = 0.34
 
+/**
+ * Postcode-containment re-rank gate radius (km) — the SAME value the resolver's country pass measures at
+ * (`POSTCODE_COUNTRY_COHERENCE_GATE_KM`, resolver/postcode-country-coherence.ts): a locality within this distance of
+ * the postcode's own centroid counts as "containing" it. One number, two passes — a divergence here would make the two
+ * mechanisms disagree about what is proximal.
+ */
+const POSTCODE_CONTAINMENT_GATE_KM = 25
+
 /**
  * Bounded PRIMARY-NAME preference across a CROSS-COUNTRY name collision (the `is_primary` ranking signal).
  *
@@ -125,6 +141,14 @@ export type RankedRow<R> = R & {
 	 * tier, and a same-country nickname (San Francisco's "Frisco") is never touched.
 	 */
 	demoted: boolean
+	/**
+	 * True when this row came from the TYPO-CORRECTOR tier — the FTS5-trigram fallback that fires only after the exact
+	 * and qualifier-strip probes both missed. Such a row answers a query the gazetteer does not contain, so it is a fuzzy
+	 * match by construction and must not claim `exactMatch` (#17). Recall is unaffected: the row is still returned, still
+	 * ranked, still resolvable — it just stops asserting a match quality it does not have, which is what the FTS backend
+	 * has always done and what every `exactMatch`-filtering consumer assumed.
+	 */
+	fuzzy?: boolean
 }
 
 /**
@@ -228,6 +252,13 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	 * (the hard-country coverage gate, guard-B plausibility) falls back to its code constants byte-identically.
 	 */
 	readonly artifactCoverage: GazetteerArtifactCoverage | undefined
+	/**
+	 * `", importance"` when this artifact carries the #28 fame column, `""` when it does not — spliced into the probe's
+	 * SELECT list. Existence-gated exactly like `#ftsProbe` and `#postalCityProbe` above, and for the same reason: a
+	 * candidate.db built before the column is a valid artifact, and naming a column it lacks would turn a stale gazetteer
+	 * into `no such column` on the first keystroke rather than into "no fame signal", which is what it is.
+	 */
+	readonly #importanceSelect: string
 
 	constructor(opts: WOFCandidateTableLookupOpts) {
 		if (opts.database) {
@@ -273,6 +304,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			this.#nameKeyExistsProbe = this.#db.prepare("SELECT 1 FROM candidate WHERE name_key = ? LIMIT 1")
 		}
 
+		// #28 fame column: probed ONCE here (it runs a PRAGMA, and `findPlace` is per-keystroke hot).
+		this.#importanceSelect = hasColumn(this.#db, "candidate", "importance") ? ", importance" : ""
+
 		// Coverage manifest (survey candidate #2): the artifact's own coverage facts, existence-gated like
 		// the probes above — a candidate.db built before the manifest reads `undefined` and consumers keep
 		// their code-constant fallbacks byte-identically.
@@ -289,6 +323,38 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		return expandPlacetypeFilter(want as readonly string[]).includes("locality")
 	}
 
+	/**
+	 * The postcode-containment anchor: the postcode's own centroid row in the candidate table, keyed whitespace-stripped
+	 * (#920 — the same fold the build applies to postcode rows), country-scoped when the query is, first
+	 * coordinate-bearing row wins. null when the candidate table carries no such postcode — the re-rank then abstains,
+	 * because a recall gap is not evidence for the name match. Meaning-of-zero: a 0,0 row is the build's unlocated
+	 * sentinel, never a real centroid.
+	 */
+	#postcodeAnchor(postcode: string, country?: string): { lat: number; lon: number } | null {
+		const placetypeID = this.#placetypeToID.get("postalcode")
+
+		if (placetypeID === undefined) return null
+
+		const conds = ["name_key = ?", "placetype_id = ?"]
+		const params: Array<string | number> = [postcode.replaceAll(/\s+/g, ""), placetypeID]
+
+		if (country) {
+			const countryID = this.#countryToID.get(country.toUpperCase())
+
+			if (countryID === undefined) return null // a country the candidate table doesn't carry
+			conds.push("country_id = ?")
+			params.push(countryID)
+		}
+
+		const row = this.#db
+			.prepare(`SELECT latitude, longitude FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT 1`)
+			.get(...params) as { latitude: number; longitude: number } | undefined
+
+		if (!row || (Number(row.latitude) === 0 && Number(row.longitude) === 0)) return null
+
+		return { lat: Number(row.latitude), lon: Number(row.longitude) }
+	}
+
 	async findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]> {
 		let text = (query.text ?? "").trim()
 
@@ -297,7 +363,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// #920 name law, candidate-key edition: postcode rows are keyed by their whitespace-stripped
 		// form at build (the GeoNames fold normalizes '624 66' → '62466'), so a postcode-typed query
 		// strips internal whitespace before keying. Postcode-only — locality names keep their spaces.
-		if ([query.placetype].flat().includes("postalcode")) {
+		const wantsPostcode = [query.placetype].flat().includes("postalcode")
+
+		if (wantsPostcode) {
 			text = text.replaceAll(/\s+/g, "")
 		}
 
@@ -390,9 +458,16 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// intended primary even when a cluster of more-populous foreign aliases sits ahead of it. `is_primary`
 			// + `country_id` feed that re-rank. A single-country probe (a country filter, or all rows same
 			// country) re-ranks to the identical population order, so the common path is untouched.
+			// `population` rides along for the REFERENTIAL score on the result (ROAD_TO_V9 §2) — one more
+			// column off a clustered row the probe already reads, and it is NOT what the probe orders by:
+			// `neg_rank` remains the sort key, so this changes no ordering, only what the result reports.
+			// `importance` (#28) rides along on the same terms, and there is deliberately NO `ORDER BY` on it:
+			// the fame prior is applied by the RESOLVER (`resolver/toponym-prior.ts`), which alone knows
+			// whether the query was bare enough to deserve it. A backend that pre-sorted by fame would apply
+			// it to every lookup, including the qualified addresses the D-rule guard exists to protect.
 			const sql =
-				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary " +
-				`FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
+				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary, population" +
+				`${this.#importanceSelect} FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
 
 			const fetched = this.#db.prepare(sql).all(...params, Math.max(limit, RERANK_FETCH)) as unknown as CandidateRow[]
 
@@ -427,7 +502,18 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
 			// pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
 			// correctly lands population-first Vienna AT. The exact/strip probes already covered the real name.
-			if (!rows.length && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
+			//
+			// NEVER for postcodes: fuzzy is a typo corrector for place NAMES, and a "corrected" postcode is a
+			// DIFFERENT postcode. The 2026-08-05 Code-Point swap exposed the trap at scale: Northern Ireland's
+			// `BT3 9QQ` (absent — no permissive NI source) trigram-matched Sheffield's `S3 9QQ` (Jaccard 0.4
+			// on {39q, 9qq}) and resolved 200+ km wrong with full confidence. An unknown postcode must abstain.
+			if (
+				!rows.length &&
+				!wantsPostcode &&
+				this.#ftsProbe &&
+				this.#nameKeyExistsProbe &&
+				!this.#nameKeyExistsProbe.get(nameKey)
+			) {
 				const match = ftsTrigramQuery(nameKey)
 
 				if (match) {
@@ -444,7 +530,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 					for (const h of ranked) {
 						if (seen.has(h.nk)) continue
 						seen.add(h.nk)
-						rows.push(...probe(h.nk, regionID))
+						// #17: stamp the tier. These rows answer a name the gazetteer does not carry, so they are
+						// fuzzy matches and `exactMatch` below must say so — see `RankedRow.fuzzy`.
+						rows.push(...probe(h.nk, regionID).map((r) => ({ ...r, fuzzy: true })))
 
 						if (rows.length >= limit) break
 					}
@@ -465,6 +553,44 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			rows = cascade(undefined)
 		}
 
+		// Postcode-containment coherence (#31, Mechanism 2): re-rank the rows by proximity to the postcode's
+		// own centroid, so the locality that CONTAINS the postcode wins the name-match tie (the "Paris" that
+		// holds 75001, not the one that holds a 75001-free namesake). The resolver sends this flag on locality
+		// lookups when `ResolveOpts.postcodeContainmentCoherence` is on. Strictly beneath the #741 postal-city
+		// short-circuit above — an exact (name, postcode) hit IS the answer and outranks any re-rank — and after
+		// the region-scope fallback, so it sees the final row set. Rows within the gate sort by distance first;
+		// the out-gate tail keeps its original population-first order. No in-gate row, or no postcode row in
+		// the candidate table → unchanged (byte-identical to the flag-off path).
+		if (
+			query.postcode &&
+			query.postcodeContainmentCoherence === true &&
+			this.#wantsLocality(query.placetype) &&
+			rows.length > 1
+		) {
+			const anchor = this.#postcodeAnchor(query.postcode, query.country)
+
+			if (anchor) {
+				const inGate: Array<{ row: RankedRow<CandidateRow>; distanceKm: number }> = []
+				const outGate: RankedRow<CandidateRow>[] = []
+
+				for (const row of rows) {
+					const distanceKm = haversineKm(anchor.lat, anchor.lon, Number(row.latitude), Number(row.longitude))
+
+					if (distanceKm <= POSTCODE_CONTAINMENT_GATE_KM) {
+						inGate.push({ row, distanceKm })
+					} else {
+						outGate.push(row)
+					}
+				}
+
+				if (inGate.length) {
+					// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+					inGate.sort((a, b) => a.distanceKm - b.distanceKm)
+					rows = [...inGate.map(({ row }) => row), ...outGate]
+				}
+			}
+		}
+
 		const candidates = rows.map((row): PlaceCandidate => {
 			const hasBbox = row.min_lat != null && row.max_lat != null && row.min_lon != null && row.max_lon != null
 
@@ -489,8 +615,32 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 				// Every candidate row IS an exact normalized-name (or alias/abbrev) match — the cascade's exact tier
 				// accepts alias-exact hits ("New York City" → New York) the same as canonical — EXCEPT a cross-country
 				// alias that lost the bounded contest to a same-key primary (`demoted`): it drops to the partial tier so
-				// the walk's country posterior can't cross back over the primary (see `RankedRow.demoted`).
-				exactMatch: !row.demoted,
+				// the walk's country posterior can't cross back over the primary (see `RankedRow.demoted`) — and
+				// EXCEPT a row the typo-corrector produced (`fuzzy`), which by definition answers a name the
+				// gazetteer does not carry (see `RankedRow.fuzzy`).
+				exactMatch: !row.demoted && !row.fuzzy,
+				// The two-score split's carry (ROAD_TO_V9 §2). `referential` names the prominence this
+				// backend has always ordered by — `neg_rank` IS `-log10(population + 1)`, so the score and
+				// the sort key are two readings of the same number.
+				...(row.population === null || row.population <= 0
+					? {}
+					: { population: row.population, referential: referentialFromPopulation(row.population) }),
+				// #28: the fame prior, from the `importance` column the candidate build joins in. Emitted ONLY
+				// when the artifact measured this place — an absent field is what `rankByImportance` reads as
+				// "does not participate", and a 0 would be a claim nobody made (meaning-of-zero).
+				//
+				// The field name matches the column because they hold the same thing: the score source's
+				// BLENDED prior — the concordance's encyclopedia-derived channel where a concordance matched, a
+				// population-derived proxy everywhere else. It is NOT the strict `encyclopedic` channel
+				// `place-importance-schema.ts` defines, and it deliberately does not land in that field: the
+				// strict channel was measured on 2026-08-10 and covers eleven countries, none of them CA/AU/RU,
+				// which makes it inert on three of the four homonym contests the prior exists to settle.
+				// `PlaceCandidate.encyclopedic` stays reserved for a strict-channel source (the FTS backend's
+				// clauses are strict and today emit NULL for everything — no shipped admin DB has the split
+				// table at all). See `candidate-schema.ts` → {@link CandidateTable.importance}.
+				...(typeof row.importance === "number" && Number.isFinite(row.importance)
+					? { importance: row.importance }
+					: {}),
 				...(hasBbox
 					? {
 							bbox: {

package/candidate-schema.ts

@@ -59,6 +59,30 @@ 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 — a legacy blended importance whose own build already coalesced the concordance's
+	 * encyclopedia-derived channel with a population-derived fallback; `place-importance-schema.ts` calls that 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
 }
 
 /**
@@ -114,6 +138,9 @@ 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",
 ] as const
 
 /**
@@ -151,6 +178,7 @@ export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>
 		.addColumn("max_lon", "real")
 		.addColumn("population", "integer")
 		.addColumn("is_primary", "integer")
+		.addColumn("importance", "real")
 		.execute()
 }
 
@@ -176,6 +204,7 @@ export async function createCandidateTable(db: Kysely<CandidateDatabase>): Promi
 		.addColumn("max_lon", "real")
 		.addColumn("population", "integer")
 		.addColumn("is_primary", "integer")
+		.addColumn("importance", "real")
 		.addPrimaryKeyConstraint("candidate_pk", [
 			"name_key",
 			"country_id",

package/coverage-manifest-schema.ts

@@ -11,7 +11,7 @@
  *     promote-gate verdicts + the measured hard-resolve rates that used to live in a code comment on
  *     `HARD_PLACE_COUNTRY_SAFELIST`. Presence = measured; `hard_filter_safe = 0` = measured and
  *     FAILED the gate (FI 69.5%, PL 77.8%) — distinguishable from a country never measured at all
- *     (the meaning-of-zero rule, `docs/articles/plan/reference/layer-contract.mdx`).
+ *     (the meaning-of-zero rule, `docs/engineering/reference/layer-contract.mdx`).
  *   - `country_bbox`: the coarse guard-B plausibility boxes that used to live in
  *     `resolver/plausibility.ts`'s `COUNTRY_BBOX`. An absent row fails open (never trips the guard),
  *     exactly like an absent key in the constant.

package/fst-autocomplete.ts

@@ -31,7 +31,17 @@ export interface AutocompleteResult {
 export interface AutocompleteSuggestion {
 	name: string
 	placetype: string
-	importance: number
+	/**
+	 * The REFERENTIAL likelihood the suggestion is ranked by (ROAD_TO_V9 §2). Autocomplete answers "which place does the
+	 * user mean", so it ranks referentially like everything else; encyclopedic importance rides along on
+	 * {@link AutocompleteSuggestion.encyclopedic} for display and never enters the order.
+	 */
+	referential: number
+	/**
+	 * Encyclopedic (Wikipedia) importance, when the FST artifact carries one for this place. `undefined` = no article, or
+	 * a pre-v5 binary — never 0.
+	 */
+	encyclopedic?: number
 	wofID: number
 	parentChain: number[]
 	matchDepth: number
@@ -42,7 +52,7 @@ export interface AutocompleteOpts {
 	maxSuggestions?: number
 	maxExpansionDepth?: number
 	/**
-	 * Collapse same-name suggestions to the single highest-importance one. Off by default (the CLI surfaces distinct
+	 * Collapse same-name suggestions to the single highest-referential one. Off by default (the CLI surfaces distinct
 	 * same-name places — New York the city vs the county); a typeahead wants it ON so the dropdown isn't four "New
 	 * London"s. (#587)
 	 */
@@ -61,16 +71,16 @@ interface BfsItem {
 const PER_BRANCH = 4
 
 /**
- * The top-`k` entries by importance (descending). Avoids sorting/allocating when `entries` is small.
+ * The top-`k` entries by REFERENTIAL likelihood (descending). Avoids sorting/allocating when `entries` is small.
  */
-function topByImportance(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
+function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
 	if (entries.length <= k) return [...entries]
 
-	return [...entries].toSorted((a, b) => b.importance - a.importance).slice(0, k)
+	return [...entries].toSorted((a, b) => b.referential - a.referential).slice(0, k)
 }
 
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked importance-descending.
+ * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
  */
 export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteOpts = {}): AutocompleteResult {
 	const maxSuggestions = opts.maxSuggestions ?? 10
@@ -114,7 +124,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 			if (!cont.token.startsWith(partial)) continue
 
 			// This edge completes the typed partial token — its target is a real match at depth+1.
-			for (const entry of topByImportance(fst.accepting(cont.targetState), PER_BRANCH)) {
+			for (const entry of topByReferential(fst.accepting(cont.targetState), PER_BRANCH)) {
 				addSuggestion(seen, entry, complete.length + 1, [cont.token])
 			}
 
@@ -132,7 +142,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 
 		if (item.depth > maxExpansionDepth) continue
 
-		for (const entry of topByImportance(fst.accepting(item.stateID), PER_BRANCH)) {
+		for (const entry of topByReferential(fst.accepting(item.stateID), PER_BRANCH)) {
 			addSuggestion(seen, entry, depth + item.depth, item.tokens)
 		}
 
@@ -143,7 +153,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 		}
 	}
 
-	let suggestions = [...seen.values()].toSorted((a, b) => b.importance - a.importance)
+	let suggestions = [...seen.values()].toSorted((a, b) => b.referential - a.referential)
 
 	if (opts.dedupeByName) {
 		suggestions = dedupeByName(suggestions)
@@ -165,7 +175,8 @@ function addSuggestion(
 	seen.set(entry.wofID, {
 		name: entry.name,
 		placetype: entry.placetype,
-		importance: entry.importance,
+		referential: entry.referential,
+		...(entry.encyclopedic === undefined ? {} : { encyclopedic: entry.encyclopedic }),
 		wofID: entry.wofID,
 		parentChain: entry.parentChain,
 		matchDepth,
@@ -174,7 +185,7 @@ function addSuggestion(
 }
 
 /**
- * Keep one suggestion per name — the highest-importance. Input is already importance-sorted, so the first occurrence
+ * Keep one suggestion per name — the highest-referential. Input is already referential-sorted, so the first occurrence
  * per name wins; order is preserved.
  */
 function dedupeByName(suggestions: AutocompleteSuggestion[]): AutocompleteSuggestion[] {