@mailwoman/resolver-wof-sqlite 9.0.0 → 9.1.0

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/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[] {

package/fst-builder.ts

@@ -17,6 +17,7 @@ import { readWOFSourceIdentity } from "./fst-freshness.ts"
 import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
 import type { BuildFSTOpts, BuildFSTResult, FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
+import { loadImportanceSplit } from "./place-importance-schema.ts"
 
 const DEFAULT_PLACETYPES: PlacetypeID[] = [
 	"country",
@@ -52,11 +53,6 @@ interface NameRow {
 	privateuse: string
 }
 
-interface PopulationRow {
-	id: number
-	population: number
-}
-
 export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	matcher: FSTMatcher
 	provenance: FSTProvenance
@@ -171,35 +167,22 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		return chain
 	}
 
-	// Phase 3: Load importance data (Wikipedia-based, falls back to population-scaled).
-	// See docs/articles/concepts/importance-vs-population.md for the two-signal contract.
-	progress("importance", "Loading importance data")
-	const importanceMap = new Map<number, number>()
-
-	try {
-		const impStmt = db.prepare("SELECT id, importance FROM place_importance")
-		const impRows = impStmt.all() as unknown as Array<{ id: number; importance: number }>
-
-		for (const row of impRows) {
-			importanceMap.set(row.id, row.importance)
-		}
-
-		progress("importance", `Loaded ${importanceMap.size} importance scores`)
-	} catch {
-		progress("importance", "No place_importance table — falling back to population")
-
-		try {
-			const popStmt = db.prepare("SELECT id, population FROM place_population")
-			const popRows = popStmt.all() as unknown as PopulationRow[]
+	// Phase 3: Load BOTH scores (ROAD_TO_V9 §2 R1, the two-score split).
+	//
+	// Referential is ALWAYS population-anchored and never read out of a legacy `place_importance`
+	// column, because a legacy row that got a Wikipedia score overwrote whatever population would have
+	// said and the two are indistinguishable afterwards. Encyclopedic rides along for consumers and is
+	// never handed to the decoder. `loadImportanceSplit` handles all four schema generations; the
+	// source it reports is stamped into provenance so an artifact says which one it read.
+	progress("importance", "Loading referential + encyclopedic scores")
+	const split = loadImportanceSplit(db)
 
-			for (const row of popRows) {
-				const normalized = row.population > 0 ? Math.min(1, Math.log2(1 + row.population / 1000) / 14) : 0
-				importanceMap.set(row.id, normalized)
-			}
-		} catch {
-			progress("importance", "No place_population either — using 0 for all")
-		}
-	}
+	progress(
+		"importance",
+		`${split.referential.size} referential, ${split.encyclopedic.size} encyclopedic (source: ${split.source}` +
+			(split.legacyFallbackRows ? `, ${split.legacyFallbackRows} legacy rows attributed to the population pass` : "") +
+			")"
+	)
 
 	// Phase 4: Load names for matching places.
 	progress("names", "Loading name variants")
@@ -304,12 +287,17 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	for (const row of sprRows) {
 		const parentChain = resolveParentChain(row.id)
 
+		const encyclopedic = split.encyclopedic.get(row.id)
+
 		const entry: PlaceEntry = {
 			wofID: row.id,
 			placetype: row.placetype as PlacetypeID,
 			name: row.name,
 			parentChain,
-			importance: importanceMap.get(row.id) ?? 0,
+			referential: split.referential.get(row.id) ?? 0,
+			// Spread rather than assigned: a place with no Wikipedia article must carry NO field, not a
+			// zero. The serializer's per-place presence bit reads `!== undefined`.
+			...(encyclopedic === undefined ? {} : { encyclopedic }),
 			lat: row.latitude,
 			lon: row.longitude,
 		}
@@ -361,7 +349,9 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		placeCount: sprRows.length,
 		edgeCount,
 		nameInsertions: insertCount,
-		importanceMatches: importanceMap.size,
+		importanceMatches: split.referential.size,
+		encyclopedicMatches: split.encyclopedic.size,
+		importanceSource: split.source,
 		sourceDB: opts.dbPath,
 		sourceDBMD5: source.md5,
 		sourceDBBytes: source.bytes,

package/fst-deserialize-web.ts

@@ -39,17 +39,44 @@ const VERSION_WITH_METADATA = 3
 
 const HEADER_SIZE = 32
 const EDGE_ENTRY_SIZE = 8
-const PLACE_ENTRY_SIZE = 56
+
+/**
+ * Format version that split the single `importance` float into `referential` + `encyclopedic` (ROAD_TO_V9 §2 R1),
+ * growing the place entry from 56 to 60 bytes. Mirrors `fst-serialize.ts`'s constant of the same name.
+ */
+const VERSION_TWO_SCORE_SPLIT = 5
+
+/**
+ * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const SPLIT_PLACE_ENTRY_SIZE = 60
+
+/**
+ * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const LEGACY_PLACE_ENTRY_SIZE = 56
+
+/**
+ * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
+ */
+const ENCYCLOPEDIC_OFFSET = 56
+
+/**
+ * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-place because absence is the
+ * common case; see `fst-serialize.ts`.
+ */
+const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
 /**
  * "FST\0".
  */
 const MAGIC_BYTES = [0x46, 0x53, 0x54, 0x00]
 /**
- * Must track the serializer's VERSION (fst-serialize.ts, currently 4). The v3 provenance + v4 16-byte-state/u32-count
+ * Must track the serializer's VERSION (fst-serialize.ts, currently 5). The v3 provenance + v4 16-byte-state/u32-count
  * layout logic below already matches the Node deserializer; only this gate was left stale at 2, so the browser FST
- * loader rejected every real (v4) artifact.
+ * loader rejected every real (v4) artifact. It was left stale again at 4 by the v5 two-score split until this line
+ * moved with it — the gate is a SEPARATE number from the layout branches, which is exactly why it keeps drifting.
  */
-const MAX_VERSION = 4
+const MAX_VERSION = 5
 
 const PLACETYPE_ORDER: readonly PlacetypeID[] = [
 	"country",
@@ -88,6 +115,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 	}
 
 	const isV2 = version >= 2
+	const isSplit = version >= VERSION_TWO_SCORE_SPLIT
 	// flags bit0 (survey #4, mirrors fst-serialize.ts): place rows carry surface-ambiguity data.
 	const hasAmbiguity = (view.getUint16(6, true) & 1) === 1
 
@@ -120,6 +148,8 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	// --- State table ---
 	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
+	// v5 grew the place entry by the encyclopedic float; v4-and-below files are read at the old stride.
+	const placeEntrySize = isSplit ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
 	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
@@ -149,7 +179,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 		const places: PlaceEntry[] = new Array(placeCountForState)
 
 		for (let pi = 0; pi < placeCountForState; pi++) {
-			const pp = placeTableStart + (placeStart + pi) * PLACE_ENTRY_SIZE
+			const pp = placeTableStart + (placeStart + pi) * placeEntrySize
 			const chainLen = view.getUint8(pp + 5)
 			const parentChain: number[] = []
 
@@ -157,19 +187,25 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 				parentChain.push(view.getUint32(pp + 24 + ci * 4, true))
 			}
 
-			const rawImportance = isV2
+			// v1 stored a raw population u32 here; v2-v4 the conflated `importance` float; v5 the
+			// referential score. See the Node deserializer for why a v1 value is genuinely referential.
+			const referential = isV2
 				? view.getFloat32(pp + 12, true)
 				: Math.min(1, Math.log2(1 + view.getUint32(pp + 12, true) / 1000) / 14)
 
+			const hasEncyclopedic =
+				isSplit && (view.getUint8(pp + 7) & PLACE_FLAG_HAS_ENCYCLOPEDIC) === PLACE_FLAG_HAS_ENCYCLOPEDIC
+
 			places[pi] = {
 				wofID: view.getUint32(pp, true),
 				placetype: PLACETYPE_ORDER[view.getUint8(pp + 4)] ?? "locality",
 				name: strings[view.getUint32(pp + 8, true)]!,
-				importance: rawImportance,
+				referential,
 				lat: view.getFloat32(pp + 16, true),
 				lon: view.getFloat32(pp + 20, true),
 				parentChain,
 				...(hasAmbiguity ? { crossCountryBranches: view.getUint8(pp + 6) } : {}),
+				...(hasEncyclopedic ? { encyclopedic: view.getFloat32(pp + ENCYCLOPEDIC_OFFSET, true) } : {}),
 			}
 		}
 

package/fst-serialize.ts

@@ -18,9 +18,19 @@
  *
  *   EDGE TABLE [edgeCount × 8 bytes] stringIdx u32 index into string table targetState u32
  *
- *   PLACE TABLE [placeCount × 56 bytes] wofID u32 placetypeIdx u8 index into PLACETYPE_ORDER chainLen
- *   u8 0..8 _pad u16 nameIdx u32 index into string table importance f32 Wikipedia importance [0,1]
- *   (V2); was population u32 (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0)
+ *   PLACE TABLE [placeCount × 60 bytes at V5, 56 below] wofID u32 placetypeIdx u8 index into
+ *   PLACETYPE_ORDER chainLen u8 0..8 crossCountryBranches u8 (header flags bit0 gates the read)
+ *   placeFlags u8 (V5; bit0 = encyclopedic present) nameIdx u32 index into string table referential f32
+ *   population-anchored likelihood [0,1] — was the conflated `importance` (V2–V4), was population u32
+ *   (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0) encyclopedic f32 (V5 only;
+ *   read only when placeFlags bit0 is set)
+ *
+ *   THE V5 BUMP IS THE TWO-SCORE SPLIT (ROAD_TO_V9 §2 R1). Through V4 one float carried whichever score
+ *   the source database held, and nothing in the bytes said which — so a reader could not tell a
+ *   population proxy from a Wikipedia score. V5 names the ranking score `referential` and gives the
+ *   encyclopedic signal its own slot plus a PER-PLACE presence bit, because most places have no
+ *   Wikipedia article and a 0 there would be a fact nobody recorded. `fst-freshness.ts` reports every
+ *   V4-and-below artifact as format-stale for exactly this reason: its single float is unattributable.
  */
 
 import { tryParsingJSON } from "@mailwoman/core/objects"
@@ -50,6 +60,34 @@ const NARROW_STATE_ENTRY_SIZE = 12
  */
 const VERSION_WITH_METADATA = 3
 
+/**
+ * Format version that split the single `importance` float into `referential` + `encyclopedic`, growing the place entry
+ * from 56 to 60 bytes and claiming the previously-reserved `pp+7` byte as {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
+ */
+const VERSION_TWO_SCORE_SPLIT = 5
+
+/**
+ * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const SPLIT_PLACE_ENTRY_SIZE = 60
+
+/**
+ * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const LEGACY_PLACE_ENTRY_SIZE = 56
+
+/**
+ * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
+ */
+const ENCYCLOPEDIC_OFFSET = 56
+
+/**
+ * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-PLACE rather than per-file
+ * because absence is the common case — roughly 89% of the 2026-08-05 gazetteer has no Wikipedia article — and a
+ * file-level flag would force every one of those rows to claim a 0 it never had.
+ */
+const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
+
 /**
  * File magic. A reader rejects anything not starting with these four bytes before parsing further.
  */
@@ -58,7 +96,7 @@ const MAGIC = Buffer.from("FST\0", "ascii")
 /**
  * Format version this serializer emits. See {@link VERSION_WIDE_STATE_COUNTERS} for what each bump changed.
  */
-const VERSION = 4
+const VERSION = 5
 
 /**
  * The format version this tree WRITES, published so a freshness guard can call an older artifact format-stale without
@@ -83,9 +121,9 @@ const STATE_ENTRY_SIZE = 16
 const EDGE_ENTRY_SIZE = 8
 
 /**
- * Place-table entry: the place id, its placetype, coordinates, and importance.
+ * Place-table entry at the version this tree WRITES: the place id, its placetype, coordinates, and both scores.
  */
-const PLACE_ENTRY_SIZE = 56
+const PLACE_ENTRY_SIZE = SPLIT_PLACE_ENTRY_SIZE
 
 /**
  * Longest ancestry chain stored per place. Deeper hierarchies are truncated at the leaf end, since the specific end of
@@ -246,11 +284,14 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 			buf.writeUInt32LE(place.wofID, pp)
 			buf.writeUInt8(placetypeToIdx.get(place.placetype) ?? 0, pp + 4)
 			buf.writeUInt8(chainLen, pp + 5)
-			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 reserved.
+			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 = v5 placeFlags.
 			buf.writeUInt8(hasAmbiguity ? Math.min(place.crossCountryBranches ?? 0, 255) : 0, pp + 6)
-			buf.writeUInt8(0, pp + 7)
+			// An absent encyclopedic score writes flag 0 AND a 0.0 float. The float is unread in that
+			// state, so absence can never surface as a score — the meaning-of-zero rule, in bytes.
+			const hasEncyclopedic = place.encyclopedic !== undefined
+			buf.writeUInt8(hasEncyclopedic ? PLACE_FLAG_HAS_ENCYCLOPEDIC : 0, pp + 7)
 			buf.writeUInt32LE(intern(place.name), pp + 8)
-			buf.writeFloatLE(place.importance, pp + 12)
+			buf.writeFloatLE(place.referential, pp + 12)
 			buf.writeFloatLE(place.lat, pp + 16)
 			buf.writeFloatLE(place.lon, pp + 20)
 
@@ -258,6 +299,8 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 				buf.writeUInt32LE(ci < chainLen ? validChain[ci]! : 0, pp + 24 + ci * 4)
 			}
 
+			buf.writeFloatLE(hasEncyclopedic ? place.encyclopedic! : 0, pp + ENCYCLOPEDIC_OFFSET)
+
 			placeIdx++
 		}
 	}
@@ -280,6 +323,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	if (version < 1 || version > VERSION) throw new Error(`FST version ${version} unsupported (expected 1..${VERSION})`)
 	const isV2 = version >= 2
+	const isSplit = version >= VERSION_TWO_SCORE_SPLIT
 	// flags bit0 (survey #4): place rows carry surface-ambiguity data in the former _pad byte.
 	const hasAmbiguity = (buf.readUInt16LE(6) & 1) === 1
 
@@ -312,6 +356,8 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	// --- State table ---
 	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
+	// v5 grew the place entry by the encyclopedic float; v4-and-below files are read at the old stride.
+	const placeEntrySize = version >= VERSION_TWO_SCORE_SPLIT ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
 	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
@@ -341,7 +387,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 		const places: PlaceEntry[] = new Array(placeCountForState)
 
 		for (let pi = 0; pi < placeCountForState; pi++) {
-			const pp = placeTableStart + (placeStart + pi) * PLACE_ENTRY_SIZE
+			const pp = placeTableStart + (placeStart + pi) * placeEntrySize
 			const chainLen = buf.readUInt8(pp + 5)
 			const parentChain: number[] = []
 
@@ -349,20 +395,30 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 				parentChain.push(buf.readUInt32LE(pp + 24 + ci * 4))
 			}
 
-			const rawImportance = isV2
+			// v1 stored a raw population u32 here; v2–v4 the conflated `importance` float; v5 the
+			// referential score. A v1 file's population is mapped through the SAME curve
+			// `referentialFromPopulation` uses, so its value is genuinely referential — the only
+			// generation of this format for which that can be said without reading the source database.
+			const referential = isV2
 				? buf.readFloatLE(pp + 12)
 				: Math.min(1, Math.log2(1 + buf.readUInt32LE(pp + 12) / 1000) / 14)
 
+			// Per-place presence bit (v5+). A v4-and-below file has no encyclopedic channel at all, so
+			// the field stays undefined rather than reading the reserved byte as a flag.
+			const hasEncyclopedic =
+				isSplit && (buf.readUInt8(pp + 7) & PLACE_FLAG_HAS_ENCYCLOPEDIC) === PLACE_FLAG_HAS_ENCYCLOPEDIC
+
 			places[pi] = {
 				wofID: buf.readUInt32LE(pp),
 				placetype: PLACETYPE_ORDER[buf.readUInt8(pp + 4)] ?? "locality",
 				name: strings[buf.readUInt32LE(pp + 8)]!,
-				importance: rawImportance,
+				referential,
 				lat: buf.readFloatLE(pp + 16),
 				lon: buf.readFloatLE(pp + 20),
 				parentChain,
 				// Header flags bit0 gates the read (survey #4): pre-ambiguity artifacts expose undefined.
 				...(hasAmbiguity ? { crossCountryBranches: buf.readUInt8(pp + 6) } : {}),
+				...(hasEncyclopedic ? { encyclopedic: buf.readFloatLE(pp + ENCYCLOPEDIC_OFFSET) } : {}),
 			}
 		}
 

package/fst-types.ts

@@ -13,7 +13,25 @@ export interface PlaceEntry {
 	placetype: PlacetypeID
 	name: string
 	parentChain: number[]
-	importance: number
+	/**
+	 * REFERENTIAL likelihood in [0, 1] — population-anchored (`referentialFromPopulation`), and the ONLY score the
+	 * decoder bias is allowed to read (ROAD_TO_V9 §2, ratified 2026-08-06).
+	 *
+	 * This field was called `importance` through format v4, where it carried whichever score the source database happened
+	 * to hold: the population proxy on a database with no `place_importance` table (which is every shipped
+	 * `fst-per-locale` binary), the Wikipedia score where the concordance join landed otherwise. The rename is the point
+	 * — a v4 artifact's value is a CONFLATION that cannot be told apart after the fact, which is why `fst-freshness.ts`
+	 * reports anything below {@link FST_FORMAT_VERSION} as format-stale rather than reading it as referential.
+	 */
+	referential: number
+	/**
+	 * Encyclopedic (Wikipedia) importance in [0, 1], fan-out-guarded per #1497. Carried for consumers that want to
+	 * DISPLAY salience; never read by the decoder or by any ranking.
+	 *
+	 * `undefined` = this place has no encyclopedic signal, or the artifact predates format 5. NEVER conflate either with
+	 * 0 — the meaning-of-zero rule; roughly 89% of the 2026-08-05 gazetteer's rows have no Wikipedia article at all.
+	 */
+	encyclopedic?: number
 	lat: number
 	lon: number
 	/**
@@ -64,7 +82,23 @@ export interface FSTProvenance {
 	placeCount: number
 	edgeCount: number
 	nameInsertions: number
+	/**
+	 * How many places carried a non-zero REFERENTIAL score at build time. Named `importanceMatches` for stamp
+	 * compatibility with every artifact written before the two-score split — renaming the JSON key would make every
+	 * existing stamp unreadable, and the number means the same thing it always did on a population-built artifact.
+	 */
 	importanceMatches: number
+	/**
+	 * How many places carried an ENCYCLOPEDIC score at build time. `undefined` on a pre-split build — which is not the
+	 * same as 0 (a v5 build against a population-only database), so the freshness report says the two in different
+	 * words.
+	 */
+	encyclopedicMatches?: number
+	/**
+	 * How the builder obtained its two scores — an {@link ImportanceSplitSource}. Recorded so an artifact states, in its
+	 * own provenance, whether its encyclopedic channel is real, reconstructed from a legacy conflated column, or absent.
+	 */
+	importanceSource?: string
 	sourceDB?: string
 	/**
 	 * MD5 of the source database's bytes at build time — the artifact's link to the gazetteer it is a projection of.

package/fts.ts

@@ -123,6 +123,18 @@ export const PLACE_BBOX_TABLE = "place_bbox"
  */
 export const PLACE_POPULATION_TABLE = "place_population"
 
+/**
+ * Name of the auxiliary table holding the two salience scores per place — `referential` (population-anchored, the
+ * ranking backbone) and `encyclopedic` (the Wikipedia join, NULL when there is no article). Built by `mailwoman
+ * gazetteer importance`; schema and derivations in `place-importance-schema.ts`.
+ *
+ * The lookup reads ONLY `encyclopedic` from it, and only to CARRY the value onto the result — referential is derived
+ * from the population already joined, and no ORDER BY anywhere touches this table (ROAD_TO_V9 §2). Sparse and
+ * schema-versioned: a pre-split gazetteer has this table with a single conflated `importance` column instead, which the
+ * lookup's column probe deliberately refuses to read.
+ */
+export const PLACE_IMPORTANCE_TABLE = "place_importance"
+
 /**
  * Counters for a single `buildPlaceSearchFTS` run. Exposed so callers (CLI, lazy-build) can render progress to the
  * user.

package/index.ts

@@ -22,6 +22,14 @@ export type {
 export { WOFSqlitePlaceLookup, type RankingWeights, type WOFSqlitePlaceLookupOpts } from "./lookup.ts"
 
 export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "./candidate-fts.ts"
+
+export {
+	ImportanceIndex,
+	IMPORTANCE_JOIN_GATE_KM,
+	type ImportanceIndexStats,
+	loadImportanceIndex,
+} from "./candidate-importance.ts"
+
 export { WOFCandidateTableLookup, type WOFCandidateTableLookupOpts } from "./candidate-lookup.ts"
 
 export {