@mailwoman/resolver-wof-sqlite 9.0.0 → 9.1.0

package/build-candidate.ts

@@ -26,6 +26,12 @@
  *
  *   Measured (2026-06-20, vs the 2.6 GB full-DB FTS): ~5 M rows; ~12 range fetches per 8-query
  *   session (the full DB needs 243); US locality 96.8% (region bbox), EU coord parity 88.6%.
+ *
+ *   #28 adds one more denormalized field, `importance` — the toponym-fame prior that decides a BARE
+ *   city name, joined in from a separate score source by name rather than by id (see
+ *   `candidate-importance.ts`, which owns that join and explains why the id would be wrong). It is
+ *   optional: without {@link BuildCandidateOptions.importance} the column is NULL on every row, which
+ *   the consumer reads as unmeasured and ignores.
  */
 
 import { existsSync, rmSync } from "node:fs"
@@ -34,6 +40,7 @@ import { DatabaseSync } from "node:sqlite"
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 
 import { createCandidateFTS } from "./candidate-fts.ts"
+import { IMPORTANCE_JOIN_GATE_KM, loadImportanceIndex } from "./candidate-importance.ts"
 import {
 	CANDIDATE_COLUMNS,
 	createCandidateStagingTables,
@@ -65,6 +72,18 @@ export interface BuildCandidateOptions {
 	 * ("Brooklyn" for 11201), and they were previously reachable only through FTS.
 	 */
 	postcodes?: string[]
+	/**
+	 * Optional WOF admin database carrying a `place_importance` table — the source of the `importance` column (#28), the
+	 * toponym-fame prior that decides the bare-city-name class. Joined by `(name_key, country, placetype)` + nearest
+	 * centroid, NOT by id; see `candidate-importance.ts` for why the id join silently drops the foreign homonyms the
+	 * prior exists to demote.
+	 *
+	 * Omit it and every row's `importance` is NULL — unmeasured, which is what the consumer's positive-evidence-only rule
+	 * already treats as "do not participate", so the artifact is byte-identical to a pre-#28 build except for the empty
+	 * column. That is the honest degradation and it is the DEFAULT: a caller with no score source must not get a
+	 * population-derived stand-in written into a column that means fame.
+	 */
+	importance?: string
 	/**
 	 * Optional progress callback for CLI / test introspection.
 	 */
@@ -84,6 +103,21 @@ export interface BuildCandidateResult {
 	 * through `onProgress`.
 	 */
 	postcodeAliases: number
+	/**
+	 * Places that took an `importance` score from the join (#28).
+	 *
+	 * `undefined` and `0` mean different things. `undefined` is "the pass did not run" — no score source was given. A `0`
+	 * would be the source matching NOTHING, which is a finding. Never collapse the two.
+	 */
+	importanceScored?: number
+	/**
+	 * Places whose `(name_key, country, placetype)` matched a scored group but whose nearest scored centroid was outside
+	 * {@link IMPORTANCE_JOIN_GATE_KM} — a different town wearing the same name, refused rather than scored.
+	 *
+	 * Worth watching across rebuilds: a jump here means the score source and the admin source have drifted apart, and the
+	 * join is being asked to guess.
+	 */
+	importanceGated?: number
 }
 
 interface PlaceAttrs {
@@ -100,6 +134,12 @@ interface PlaceAttrs {
 	pop: number
 	neg: number
 	pkey: string
+	/**
+	 * The place's toponym-fame score, or null when the score source has no measurement for it (#28). A property of the
+	 * PLACE, so it rides {@link stageRow} onto the alias and abbrev rows too — that is how a bare `Moscow` reaches
+	 * Москва's score through the alias row that carries the key.
+	 */
+	imp: number | null
 }
 
 export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult> {
@@ -146,6 +186,25 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		return id
 	}
 
+	// --- importance source (#28): loaded BEFORE pass 1, which is the only pass that sees a place's
+	// name/country/placetype/centroid together. Absent → every row's `importance` stays NULL. ---
+	let importance: ReturnType<typeof loadImportanceIndex> | undefined
+
+	if (opts.importance) {
+		progress("importance", `loading place_importance from ${opts.importance}`)
+		importance = loadImportanceIndex(opts.importance)
+
+		progress(
+			"importance",
+			`${importance.stats.places.toLocaleString()} scored places in ${importance.stats.keys.toLocaleString()} (name, country, placetype) groups` +
+				(importance.stats.unkeyable ? `; ${importance.stats.unkeyable.toLocaleString()} unkeyable names skipped` : "")
+		)
+	} else {
+		// Never a silent column of nulls: a build without a score source produces one, and the reason has
+		// to be visible in the log rather than inferred from the artifact.
+		progress("importance", "no score source given — `importance` will be NULL on every row")
+	}
+
 	// --- region_id per place (its region-tier ancestor) for same-name disambiguation ---
 	progress("region", "loading region ancestry")
 	const regionOf = new Map<number, number>()
@@ -206,14 +265,16 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		const neg = -Math.log10(pop + 1)
 		const name = String(r.name ?? "")
 		const pkey = normalizeLocalityForKey(name)
+		const lat = r.lat as number
+		const lon = r.lon as number
 
 		const a: PlaceAttrs = {
 			cid,
 			rid,
 			ptid,
 			name,
-			lat: r.lat as number,
-			lon: r.lon as number,
+			lat,
+			lon,
 			mnLat: r.mnlat as number,
 			mnLon: r.mnlon as number,
 			mxLat: r.mxlat as number,
@@ -221,12 +282,30 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			pop,
 			neg,
 			pkey,
+			imp: importance?.find(name, r.country as string | null, r.placetype as string | null, lat, lon) ?? null,
 		}
 
 		attrs.set(sid, a)
 
 		if (pkey) {
-			insStage.run(pkey, cid, rid, ptid, neg, sid, name, a.lat, a.lon, a.mnLat, a.mnLon, a.mxLat, a.mxLon, pop, 1)
+			insStage.run(
+				pkey,
+				cid,
+				rid,
+				ptid,
+				neg,
+				sid,
+				name,
+				a.lat,
+				a.lon,
+				a.mnLat,
+				a.mnLon,
+				a.mxLat,
+				a.mxLon,
+				pop,
+				1,
+				a.imp
+			)
 
 			nPrim++
 		}
@@ -235,6 +314,14 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	out.exec("COMMIT")
 	progress("primaries", `${nPrim.toLocaleString()} primaries; ${attrs.size.toLocaleString()} places`)
 
+	if (importance) {
+		progress(
+			"importance",
+			`${importance.matched.toLocaleString()} places scored; ` +
+				`${importance.gated.toLocaleString()} refused (nearest same-name place > ${IMPORTANCE_JOIN_GATE_KM} km away)`
+		)
+	}
+
 	const stageRow = (k: string, a: PlaceAttrs, sid: number, isPrimary: number): void => {
 		insStage.run(
 			k,
@@ -251,7 +338,8 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			a.mxLat,
 			a.mxLon,
 			a.pop,
-			isPrimary
+			isPrimary,
+			a.imp
 		)
 	}
 
@@ -352,6 +440,10 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 				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,
 			}
 
 			pcAttrs.set(Number(r.id), a)
@@ -478,5 +570,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		abbrevs: nAbbr,
 		postcodes: nPostcode,
 		postcodeAliases: nPostcodeAlias,
+		...(importance ? { importanceScored: importance.matched, importanceGated: importance.gated } : {}),
 	}
 }

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()
 
@@ -392,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[]
 
@@ -457,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
 					}
@@ -478,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
 
@@ -502,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: {