@mailwoman/resolver-wof-sqlite 8.0.0 → 8.2.0

package/fst-autocomplete.ts

@@ -17,7 +17,8 @@
  *       needs; without it "new yor" returns nothing useful. (#587)
  */
 
-import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
+import type { FSTMatcher } from "./fst-matcher.ts"
+import { normalizeTokens } from "./fst-matcher.ts"
 import type { PlaceEntry } from "./fst-types.ts"
 
 export interface AutocompleteResult {
@@ -54,7 +55,9 @@ interface BfsItem {
 	tokens: string[]
 }
 
-/** Max accepting entries collected per BFS branch — keeps one dense branch from starving the search. */
+/**
+ * Max accepting entries collected per BFS branch — keeps one dense branch from starving the search.
+ */
 const PER_BRANCH = 4
 
 /**
@@ -63,7 +66,7 @@ const PER_BRANCH = 4
 function topByImportance(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
 	if (entries.length <= k) return [...entries]
 
-	return [...entries].sort((a, b) => b.importance - a.importance).slice(0, k)
+	return [...entries].toSorted((a, b) => b.importance - a.importance).slice(0, k)
 }
 
 /**
@@ -74,13 +77,13 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 	const maxExpansionDepth = opts.maxExpansionDepth ?? 2
 	const normalizedTokens = normalizeTokens(query)
 
-	if (normalizedTokens.length === 0) {
+	if (!normalizedTokens.length) {
 		return { query, normalizedTokens: [], depth: 0, suggestions: [] }
 	}
 
 	const seen = new Map<number, AutocompleteSuggestion>()
 	const queue: BfsItem[] = []
-	let depth = 0
+	let depth: number
 
 	const match = fst.walk(normalizedTokens)
 
@@ -98,12 +101,13 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 	} else {
 		// PARTIAL last token — walk the complete prefix, complete the partial by prefix-filtering edges.
 		const complete = normalizedTokens.slice(0, -1)
-		const partial = normalizedTokens[normalizedTokens.length - 1]!
-		const prefixState = complete.length === 0 ? 0 : (fst.walk(complete)?.stateID ?? undefined)
+		const partial = normalizedTokens.at(-1)!
+		const prefixState = !complete.length ? 0 : (fst.walk(complete)?.stateID ?? undefined)
 
 		if (prefixState === undefined) {
 			return { query, normalizedTokens, depth: 0, suggestions: [] }
 		}
+
 		depth = complete.length
 
 		for (const cont of fst.continuations(prefixState)) {
@@ -113,6 +117,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 			for (const entry of topByImportance(fst.accepting(cont.targetState), PER_BRANCH)) {
 				addSuggestion(seen, entry, complete.length + 1, [cont.token])
 			}
+
 			// BFS a little past it too (multi-token completions: "new yor" → "New York Mills").
 			queue.push({ stateID: cont.targetState, depth: 1, tokens: [cont.token] })
 		}
@@ -122,7 +127,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 	// branch contributes only its top PER_BRANCH places: a state like "new london" has dozens of
 	// accepting entries and would otherwise blow the budget before the BFS ever reaches "new york"
 	// (the "new" state has 311 continuations). Per-branch capping keeps the search broad. (#587)
-	while (queue.length > 0 && seen.size < maxSuggestions * 4) {
+	while (queue.length && seen.size < maxSuggestions * 4) {
 		const item = queue.shift()!
 
 		if (item.depth > maxExpansionDepth) continue
@@ -138,7 +143,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 		}
 	}
 
-	let suggestions = [...seen.values()].sort((a, b) => b.importance - a.importance)
+	let suggestions = [...seen.values()].toSorted((a, b) => b.importance - a.importance)
 
 	if (opts.dedupeByName) {
 		suggestions = dedupeByName(suggestions)
@@ -156,6 +161,7 @@ function addSuggestion(
 	const existing = seen.get(entry.wofID)
 
 	if (existing && existing.matchDepth <= matchDepth) return
+
 	seen.set(entry.wofID, {
 		name: entry.name,
 		placetype: entry.placetype,

package/fst-builder.ts

@@ -26,6 +26,7 @@ const DEFAULT_PLACETYPES: PlacetypeID[] = [
 	"borough",
 	"neighbourhood",
 ]
+
 const DEFAULT_COUNTRIES = ["US"]
 const DEFAULT_LANGUAGES = ["eng", ""]
 
@@ -66,6 +67,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	// Phase 1: Load all matching SPR rows.
 	progress("spr", `Loading places for countries=[${countries}], placetypes=[${placetypes}]`)
 	const placeholders = (arr: string[]) => arr.map(() => "?").join(",")
+
 	const sprStmt = db.prepare(
 		`SELECT id, name, placetype, parent_id, latitude, longitude
 		 FROM spr
@@ -73,6 +75,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		   AND country IN (${placeholders(countries)})
 		   AND placetype IN (${placeholders(placetypes)})`
 	)
+
 	const sprRows = sprStmt.all(...countries, ...placetypes) as unknown as SprRow[]
 	progress("spr", `Loaded ${sprRows.length} places`)
 
@@ -155,6 +158,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		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")
@@ -164,7 +168,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 			const popRows = popStmt.all() as unknown as PopulationRow[]
 
 			for (const row of popRows) {
-				const normalized = row.population > 0 ? Math.min(1.0, Math.log2(1 + row.population / 1000) / 14) : 0
+				const normalized = row.population > 0 ? Math.min(1, Math.log2(1 + row.population / 1000) / 14) : 0
 				importanceMap.set(row.id, normalized)
 			}
 		} catch {
@@ -182,11 +186,13 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	for (let i = 0; i < placeIds.length; i += 500) {
 		const chunk = placeIds.slice(i, i + 500)
 		const idPlaceholders = chunk.map(() => "?").join(",")
+
 		const nameStmt = allLanguages
 			? db.prepare(`SELECT id, name, language, privateuse FROM names WHERE id IN (${idPlaceholders})`)
 			: db.prepare(
 					`SELECT id, name, language, privateuse FROM names WHERE id IN (${idPlaceholders}) AND language IN (${languages.map(() => "?").join(",")})`
 				)
+
 		const nameRows = (allLanguages
 			? nameStmt.all(...chunk)
 			: nameStmt.all(...chunk, ...languages)) as unknown as NameRow[]
@@ -197,17 +203,47 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 			if (!existing.includes(row.name)) {
 				existing.push(row.name)
 			}
+
 			namesByPlace.set(row.id, existing)
 		}
 	}
+
 	progress("names", `Loaded names for ${namesByPlace.size} places`)
 
 	// Phase 5: Build the trie.
 	progress("trie", "Building trie")
 	const nodes: FSTNode[] = [{ edges: new Map(), places: [] }]
 
-	function insertName(tokens: string[], entry: PlaceEntry): void {
-		if (tokens.length === 0) return
+	// Degenerate-surface curation (see BuildFSTOpts.excludeSurfaces). Applied to the WHOLE normalized
+	// surface only — a multi-token name containing a function word ("los angeles") is never affected.
+	const excludeSurfaces = opts.excludeSurfaces
+	const excludeAllTokensOf = opts.excludeAllTokensOf
+	let excludedCount = 0
+
+	function isDegenerate(tokens: string[]): boolean {
+		if (!tokens.length) return false
+
+		if (excludeSurfaces?.has(tokens.join(" "))) return true
+
+		if (excludeAllTokensOf !== undefined && tokens.every((t) => excludeAllTokensOf.has(t))) return true
+
+		return false
+	}
+
+	// Surface-ambiguity classes (survey #4): a per-SURFACE fact, so the entry is cloned per insertion
+	// with its accepting surface's count attached (the same place under "nyc" and "new york city"
+	// records each surface's own ambiguity). Absent map → entries carry no count (back-compat bytes).
+	const surfaceCountryCounts = opts.surfaceCountryCounts
+
+	function insertName(tokens: string[], entry: PlaceEntry): boolean {
+		if (!tokens.length) return false
+
+		if (isDegenerate(tokens)) {
+			excludedCount++
+
+			return false
+		}
+
 		let stateID = 0
 
 		for (const t of tokens) {
@@ -219,20 +255,30 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 				nodes.push({ edges: new Map(), places: [] })
 				node.edges.set(t, next)
 			}
+
 			stateID = next
 		}
+
 		// Deduplicate: don't add the same wofID twice at the same state.
 		const existing = nodes[stateID]!.places
 
 		if (!existing.some((p) => p.wofID === entry.wofID && p.placetype === entry.placetype)) {
-			existing.push(entry)
+			if (surfaceCountryCounts !== undefined) {
+				const count = surfaceCountryCounts.get(tokens.join(" "))
+				existing.push({ ...entry, crossCountryBranches: Math.min(count ?? 1, 255) })
+			} else {
+				existing.push(entry)
+			}
 		}
+
+		return true
 	}
 
 	let insertCount = 0
 
 	for (const row of sprRows) {
 		const parentChain = resolveParentChain(row.id)
+
 		const entry: PlaceEntry = {
 			wofID: row.id,
 			placetype: row.placetype as PlacetypeID,
@@ -245,8 +291,10 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 
 		// Insert the primary name from spr.
 		const primaryTokens = normalizeTokens(row.name)
-		insertName(primaryTokens, entry)
-		insertCount++
+
+		if (insertName(primaryTokens, entry)) {
+			insertCount++
+		}
 
 		// Insert alt names from the names table.
 		const altNames = namesByPlace.get(row.id) ?? []
@@ -255,18 +303,23 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 			if (altName === row.name) continue
 			const altTokens = normalizeTokens(altName)
 
-			if (altTokens.length > 0 && altTokens.join(" ") !== primaryTokens.join(" ")) {
-				insertName(altTokens, entry)
+			if (altTokens.length && altTokens.join(" ") !== primaryTokens.join(" ") && insertName(altTokens, entry)) {
 				insertCount++
 			}
 		}
 	}
 
 	db.close()
-	progress("done", `Built trie: ${nodes.length} states, ${insertCount} name insertions`)
+
+	progress(
+		"done",
+		`Built trie: ${nodes.length} states, ${insertCount} name insertions` +
+			(excludedCount > 0 ? ` (${excludedCount} degenerate surfaces excluded)` : "")
+	)
 
 	const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0)
 	const matcher = FSTMatcher.fromNodes(nodes)
+
 	const provenance: FSTProvenance = {
 		builtAt: new Date().toISOString(),
 		countries,
@@ -276,6 +329,9 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		nameInsertions: insertCount,
 		importanceMatches: importanceMap.size,
 		sourceDB: opts.dbPath,
+		...(excludeSurfaces !== undefined || excludeAllTokensOf !== undefined
+			? { exclusionPolicy: opts.exclusionPolicy ?? "unspecified", excludedInsertions: excludedCount }
+			: {}),
 	}
 
 	return {

package/fst-deserialize-web.ts

@@ -14,13 +14,39 @@ import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher } from "./fst-matcher.ts"
 import type { FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
 
+/**
+ * Format version that widened the per-state edge and place counters from 16 to 32 bits, growing the state entry from 12
+ * to 16 bytes. Readers branch on it to stay backward-compatible with v2/v3 files.
+ */
+const VERSION_WIDE_STATE_COUNTERS = 4
+
+/**
+ * State-table entry size in bytes at or above {@link VERSION_WIDE_STATE_COUNTERS}.
+ */
+const WIDE_STATE_ENTRY_SIZE = 16
+
+/**
+ * State-table entry size in bytes below {@link VERSION_WIDE_STATE_COUNTERS}.
+ */
+const NARROW_STATE_ENTRY_SIZE = 12
+
+/**
+ * First format version carrying the trailing metadata block; older files simply have none.
+ */
+const VERSION_WITH_METADATA = 3
+
 const HEADER_SIZE = 32
 const EDGE_ENTRY_SIZE = 8
 const PLACE_ENTRY_SIZE = 56
-const MAGIC_BYTES = [0x46, 0x53, 0x54, 0x00] // "FST\0"
-// Must track the serializer's VERSION (fst-serialize.ts, currently 4). 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.
+/**
+ * "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
+ * 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.
+ */
 const MAX_VERSION = 4
 
 const PLACETYPE_ORDER: readonly PlacetypeID[] = [
@@ -58,7 +84,10 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 	if (version < 1 || version > MAX_VERSION) {
 		throw new Error(`FST version ${version} unsupported (expected 1..${MAX_VERSION})`)
 	}
+
 	const isV2 = version >= 2
+	// flags bit0 (survey #4, mirrors fst-serialize.ts): place rows carry surface-ambiguity data.
+	const hasAmbiguity = (view.getUint16(6, true) & 1) === 1
 
 	const stateCount = view.getUint32(8, true)
 	const edgeCount = view.getUint32(12, true)
@@ -75,6 +104,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 		strOffsets[i] = view.getUint32(pos, true)
 		pos += 4
 	}
+
 	const strDataStart = pos
 	const strings: string[] = new Array(stringCount)
 
@@ -83,10 +113,11 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 		const end = strDataStart + strOffsets[i + 1]!
 		strings[i] = decoder.decode(bytes.subarray(start, end))
 	}
+
 	pos += stringBytes
 
 	// --- State table ---
-	const stateEntrySize = version >= 4 ? 16 : 12
+	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
 	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
@@ -97,8 +128,12 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 		const sp = stateTableStart + si * stateEntrySize
 		const edgeStart = view.getUint32(sp, true)
 		const placeStart = view.getUint32(sp + 4, true)
-		const edgeCountForState = version >= 4 ? view.getUint32(sp + 8, true) : view.getUint16(sp + 8, true)
-		const placeCountForState = version >= 4 ? view.getUint32(sp + 12, true) : view.getUint16(sp + 10, true)
+
+		const edgeCountForState =
+			version >= VERSION_WIDE_STATE_COUNTERS ? view.getUint32(sp + 8, true) : view.getUint16(sp + 8, true)
+
+		const placeCountForState =
+			version >= VERSION_WIDE_STATE_COUNTERS ? view.getUint32(sp + 12, true) : view.getUint16(sp + 10, true)
 
 		const edges = new Map<string, number>()
 
@@ -119,9 +154,10 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 			for (let ci = 0; ci < chainLen; ci++) {
 				parentChain.push(view.getUint32(pp + 24 + ci * 4, true))
 			}
+
 			const rawImportance = isV2
 				? view.getFloat32(pp + 12, true)
-				: Math.min(1.0, Math.log2(1 + view.getUint32(pp + 12, true) / 1000) / 14)
+				: Math.min(1, Math.log2(1 + view.getUint32(pp + 12, true) / 1000) / 14)
 
 			places[pi] = {
 				wofID: view.getUint32(pp, true),
@@ -131,6 +167,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 				lat: view.getFloat32(pp + 16, true),
 				lon: view.getFloat32(pp + 20, true),
 				parentChain,
+				...(hasAmbiguity ? { crossCountryBranches: view.getUint8(pp + 6) } : {}),
 			}
 		}
 
@@ -148,7 +185,7 @@ export function readFSTProvenanceWeb(input: ArrayBuffer | Uint8Array): FSTProven
 	if (bytes.byteLength < HEADER_SIZE) return undefined
 	const version = view.getUint16(4, true)
 
-	if (version < 3) return undefined
+	if (version < VERSION_WITH_METADATA) return undefined
 	const provenanceOffset = view.getUint32(28, true)
 
 	if (provenanceOffset === 0 || provenanceOffset >= bytes.byteLength) return undefined

package/fst-matcher.ts

@@ -39,15 +39,16 @@ export class FSTMatcher {
 	walk(tokens: string[]): FSTMatchResult | null {
 		let stateID = 0
 
-		for (let i = 0; i < tokens.length; i++) {
+		for (const token of tokens) {
 			const node = this.nodes[stateID]
 
 			if (!node) return null
-			const next = node.edges.get(tokens[i]!)
+			const next = node.edges.get(token)
 
 			if (next === undefined) return null
 			stateID = next
 		}
+
 		const node = this.nodes[stateID]!
 
 		return { stateID, accepted: node.places.length > 0, depth: tokens.length }
@@ -77,6 +78,7 @@ export class FSTMatcher {
 
 		for (const [token, targetID] of node.edges) {
 			const target = this.nodes[targetID]!
+
 			result.push({
 				token,
 				targetState: targetID,
@@ -104,6 +106,7 @@ export class FSTMatcher {
 
 				if (next === undefined) break
 				stateID = next
+
 				depth++
 			}
 
@@ -127,7 +130,9 @@ export class FSTMatcher {
 		return this.nodes.length
 	}
 
-	/** Expose the internal node array for serialization. */
+	/**
+	 * Expose the internal node array for serialization.
+	 */
 	toNodes(): readonly FSTNode[] {
 		return this.nodes
 	}
@@ -137,12 +142,14 @@ export class FSTMatcher {
 	}
 }
 
-/** Normalize text into FST tokens: lowercase, NFKC, strip punctuation, split on whitespace. */
+/**
+ * Normalize text into FST tokens: lowercase, NFKC, strip punctuation, split on whitespace.
+ */
 export function normalizeTokens(text: string): string[] {
 	return text
 		.normalize("NFKC")
 		.toLowerCase()
-		.replace(/[\p{P}\p{S}]/gu, "")
+		.replaceAll(/[\p{P}\p{S}]/gu, "")
 		.split(/\s+/)
 		.filter((t) => t.length > 0)
 }

package/fst-serialize.ts

@@ -27,14 +27,67 @@ import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher } from "./fst-matcher.ts"
 import type { FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
 
+/**
+ * Format version that widened the per-state edge and place counters from 16 to 32 bits, growing the state entry from 12
+ * to 16 bytes. Readers branch on it to stay backward-compatible with v2/v3 files.
+ */
+const VERSION_WIDE_STATE_COUNTERS = 4
+
+/**
+ * State-table entry size in bytes at or above {@link VERSION_WIDE_STATE_COUNTERS}.
+ */
+const WIDE_STATE_ENTRY_SIZE = 16
+
+/**
+ * State-table entry size in bytes below {@link VERSION_WIDE_STATE_COUNTERS}.
+ */
+const NARROW_STATE_ENTRY_SIZE = 12
+
+/**
+ * First format version carrying the trailing metadata block; older files simply have none.
+ */
+const VERSION_WITH_METADATA = 3
+
+/**
+ * File magic. A reader rejects anything not starting with these four bytes before parsing further.
+ */
 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
+
+/**
+ * Fixed header size in bytes: magic, version, and the section offsets that follow it.
+ */
 const HEADER_SIZE = 32
+
+/**
+ * State-table entry: edge offset, place offset, and the two 32-bit counters (v4 widths).
+ */
 const STATE_ENTRY_SIZE = 16
+
+/**
+ * Edge-table entry: the transition label and the target state index.
+ */
 const EDGE_ENTRY_SIZE = 8
+
+/**
+ * Place-table entry: the place id, its placetype, coordinates, and importance.
+ */
 const PLACE_ENTRY_SIZE = 56
+
+/**
+ * Longest ancestry chain stored per place. Deeper hierarchies are truncated at the leaf end, since the specific end of
+ * the chain is what disambiguates and the country end is recoverable anyway.
+ */
 const MAX_CHAIN_LEN = 8
 
+/**
+ * Placetypes in hierarchy order, largest first. The index into this array is what gets written into a place entry, so
+ * REORDERING IT BREAKS EVERY EXISTING FILE — append instead, and bump the version.
+ */
 const PLACETYPE_ORDER: readonly PlacetypeID[] = [
 	"country",
 	"region",
@@ -109,11 +162,15 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	let pos = 0
 
 	// --- Header ---
+	// flags bit0 (survey #4, 2026-07-27): place rows carry surface-ambiguity data in the former _pad
+	// byte (pp+6 = crossCountryBranches u8, pp+7 reserved). Presence-signaled here so VERSION stays
+	// put: pre-ambiguity artifacts read flags=0 → readers expose `undefined`, never a fake 0.
+	const hasAmbiguity = nodes.some((n) => n.places.some((p) => p.crossCountryBranches !== undefined))
 	MAGIC.copy(buf, pos)
 	pos += 4
 	buf.writeUInt16LE(VERSION, pos)
 	pos += 2
-	buf.writeUInt16LE(0, pos)
+	buf.writeUInt16LE(hasAmbiguity ? 1 : 0, pos)
 	pos += 2
 	buf.writeUInt32LE(nodes.length, pos)
 	pos += 4
@@ -131,11 +188,12 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	// --- String table ---
 	let strOffset = 0
 
-	for (let i = 0; i < encodedStrings.length; i++) {
+	for (const encoded of encodedStrings) {
 		buf.writeUInt32LE(strOffset, pos)
 		pos += 4
-		strOffset += encodedStrings[i]!.length
+		strOffset += encoded.length
 	}
+
 	buf.writeUInt32LE(strOffset, pos)
 	pos += 4
 
@@ -167,6 +225,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 			const ep = edgeTableStart + edgeIdx * EDGE_ENTRY_SIZE
 			buf.writeUInt32LE(intern(token), ep)
 			buf.writeUInt32LE(target, ep + 4)
+
 			edgeIdx++
 		}
 
@@ -178,7 +237,9 @@ 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)
-			buf.writeUInt16LE(0, pp + 6) // pad
+			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 reserved.
+			buf.writeUInt8(hasAmbiguity ? Math.min(place.crossCountryBranches ?? 0, 255) : 0, pp + 6)
+			buf.writeUInt8(0, pp + 7)
 			buf.writeUInt32LE(intern(place.name), pp + 8)
 			buf.writeFloatLE(place.importance, pp + 12)
 			buf.writeFloatLE(place.lat, pp + 16)
@@ -187,6 +248,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 			for (let ci = 0; ci < MAX_CHAIN_LEN; ci++) {
 				buf.writeUInt32LE(ci < chainLen ? validChain[ci]! : 0, pp + 24 + ci * 4)
 			}
+
 			placeIdx++
 		}
 	}
@@ -209,6 +271,8 @@ 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
+	// flags bit0 (survey #4): place rows carry surface-ambiguity data in the former _pad byte.
+	const hasAmbiguity = (buf.readUInt16LE(6) & 1) === 1
 
 	const stateCount = buf.readUInt32LE(8)
 	const edgeCount = buf.readUInt32LE(12)
@@ -225,6 +289,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 		strOffsets[i] = buf.readUInt32LE(pos)
 		pos += 4
 	}
+
 	const strDataStart = pos
 	const strings: string[] = new Array(stringCount)
 
@@ -233,10 +298,11 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 		const end = strDataStart + strOffsets[i + 1]!
 		strings[i] = buf.toString("utf8", start, end)
 	}
+
 	pos += stringBytes
 
 	// --- State table ---
-	const stateEntrySize = version >= 4 ? 16 : 12
+	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
 	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
@@ -247,8 +313,12 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 		const sp = stateTableStart + si * stateEntrySize
 		const edgeStart = buf.readUInt32LE(sp)
 		const placeStart = buf.readUInt32LE(sp + 4)
-		const edgeCountForState = version >= 4 ? buf.readUInt32LE(sp + 8) : buf.readUInt16LE(sp + 8)
-		const placeCountForState = version >= 4 ? buf.readUInt32LE(sp + 12) : buf.readUInt16LE(sp + 10)
+
+		const edgeCountForState =
+			version >= VERSION_WIDE_STATE_COUNTERS ? buf.readUInt32LE(sp + 8) : buf.readUInt16LE(sp + 8)
+
+		const placeCountForState =
+			version >= VERSION_WIDE_STATE_COUNTERS ? buf.readUInt32LE(sp + 12) : buf.readUInt16LE(sp + 10)
 
 		const edges = new Map<string, number>()
 
@@ -269,9 +339,11 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 			for (let ci = 0; ci < chainLen; ci++) {
 				parentChain.push(buf.readUInt32LE(pp + 24 + ci * 4))
 			}
+
 			const rawImportance = isV2
 				? buf.readFloatLE(pp + 12)
-				: Math.min(1.0, Math.log2(1 + buf.readUInt32LE(pp + 12) / 1000) / 14)
+				: Math.min(1, Math.log2(1 + buf.readUInt32LE(pp + 12) / 1000) / 14)
+
 			places[pi] = {
 				wofID: buf.readUInt32LE(pp),
 				placetype: PLACETYPE_ORDER[buf.readUInt8(pp + 4)] ?? "locality",
@@ -280,6 +352,8 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 				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) } : {}),
 			}
 		}
 
@@ -295,7 +369,7 @@ export function readFSTProvenance(buf: Buffer): FSTProvenance | undefined {
 	if (!buf.subarray(0, 4).equals(MAGIC)) return undefined
 	const version = buf.readUInt16LE(4)
 
-	if (version < 3) return undefined
+	if (version < VERSION_WITH_METADATA) return undefined
 	const provenanceOffset = buf.readUInt32LE(28)
 
 	if (provenanceOffset === 0 || provenanceOffset >= buf.length) return undefined