@mailwoman/resolver-wof-sqlite 8.1.0 → 8.2.0

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,9 +203,11 @@ 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.
@@ -213,7 +221,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	let excludedCount = 0
 
 	function isDegenerate(tokens: string[]): boolean {
-		if (tokens.length === 0) return false
+		if (!tokens.length) return false
 
 		if (excludeSurfaces?.has(tokens.join(" "))) return true
 
@@ -222,14 +230,20 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		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 === 0) return false
+		if (!tokens.length) return false
 
 		if (isDegenerate(tokens)) {
 			excludedCount++
 
 			return false
 		}
+
 		let stateID = 0
 
 		for (const t of tokens) {
@@ -241,13 +255,20 @@ 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
@@ -257,6 +278,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 
 	for (const row of sprRows) {
 		const parentChain = resolveParentChain(row.id)
+
 		const entry: PlaceEntry = {
 			wofID: row.id,
 			placetype: row.placetype as PlacetypeID,
@@ -281,13 +303,14 @@ 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` +
@@ -296,6 +319,7 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 
 	const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0)
 	const matcher = FSTMatcher.fromNodes(nodes)
+
 	const provenance: FSTProvenance = {
 		builtAt: new Date().toISOString(),
 		countries,

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

package/fst-types.ts

@@ -16,6 +16,13 @@ export interface PlaceEntry {
 	importance: number
 	lat: number
 	lon: number
+	/**
+	 * Surface-ambiguity class (survey #4): how many DISTINCT countries carry a place with THIS entry's accepting surface,
+	 * counted over the whole admin DB at build time (clamped to 255). A property of the surface, not the place — the same
+	 * place reached via different alias surfaces reports each surface's own count. `undefined` = built without ambiguity
+	 * data (pre-2026-07-27 artifacts) — NEVER conflate with 1 (the unambiguous case); the meaning-of-zero rule.
+	 */
+	crossCountryBranches?: number
 }
 
 export type PlacetypeID =
@@ -60,9 +67,13 @@ export interface FSTProvenance {
 	importanceMatches: number
 	sourceDB?: string
 	modelCardVersion?: string
-	/** Degenerate-surface curation policy applied at build time (absent = uncurated build). */
+	/**
+	 * Degenerate-surface curation policy applied at build time (absent = uncurated build).
+	 */
 	exclusionPolicy?: string
-	/** Name insertions refused by the curation policy. */
+	/**
+	 * Name insertions refused by the curation policy.
+	 */
 	excludedInsertions?: number
 }
 
@@ -85,8 +96,20 @@ export interface BuildFSTOpts {
 	 * street-type words ("Avenue Road" is a real name; "de la" is not).
 	 */
 	excludeAllTokensOf?: ReadonlySet<string>
-	/** Recorded verbatim into provenance when either exclusion set is supplied. */
+	/**
+	 * Recorded verbatim into provenance when either exclusion set is supplied.
+	 */
 	exclusionPolicy?: string
+	/**
+	 * Surface-ambiguity classes (survey #4, 2026-07-27): normalized-join surface → the number of DISTINCT countries
+	 * (across the WHOLE admin DB, not just this build's country scope) with a place carrying that surface. When supplied,
+	 * every inserted place row records the count for ITS accepting surface (`PlaceEntry.crossCountryBranches`) — an entry
+	 * accessible under several surfaces records each surface's own count. Serialized into the place row's former `_pad`
+	 * byte with presence signaled by header flags bit0, so VERSION stays put and pre-ambiguity artifacts read as "no
+	 * data" (never "0 branches" — the meaning-of-zero rule). No decoder consumes it yet; consumers (FST-prior tempering,
+	 * the Option-A evidence channel) arrive behind their own measured gates.
+	 */
+	surfaceCountryCounts?: ReadonlyMap<string, number>
 	onProgress?: (phase: string, detail?: string) => void
 }
 

package/fts-query.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Query shaping for the FTS5 lookup: placetype normalization and the MATCH-expression sanitizer.
+ *   Both turn a caller's loose input into something SQLite's FTS5 parser accepts without throwing —
+ *   an unescaped quote or a bare `*` is a syntax error, not an empty result.
+ */
+
+import type { FindPlaceQuery, WOFPlacetype } from "./types.ts"
+
+export function normalizePlacetypes(p: FindPlaceQuery["placetype"]): WOFPlacetype[] | null {
+	if (!p) return null
+
+	return Array.isArray(p) ? p : [p]
+}
+
+/**
+ * Make an arbitrary user-typed string safe for FTS5 MATCH.
+ *
+ * FTS5 has its own query syntax (`"phrase"`, `term1 OR term2`, `prefix*`, NEAR/N, etc.). Letting raw user input through
+ * means a user typing `Paris's` or `St. (Petersburg)` causes a syntax error.
+ *
+ * Per-token rules:
+ *
+ * - Strip all punctuation except trailing `*` from each whitespace-separated token.
+ * - **Trailing `*`** is preserved as FTS5 **prefix syntax** — `627*` becomes the literal `627*` (unquoted). The caller
+ *   signaled they want a prefix; respect that.
+ * - All other tokens are wrapped in `"..."` as a single-word phrase. Conservative — handles apostrophes, parens, accented
+ *   input, etc. safely.
+ * - Multiple tokens join with implicit AND.
+ *
+ * Examples:
+ *
+ * - `"Paris"` → `"Paris"` (phrase)
+ * - `"627*"` → `627*` (prefix)
+ * - `"St. (Petersburg)"` → `"St" "Petersburg"` (two phrases, AND-joined)
+ * - `"Thiron-Gardais"` → `"Thiron" "Gardais"` (intra-token punctuation SPLITS — #945; fusing to `ThironGardais` matched
+ *   nothing because the FTS doc tokenizes the hyphenated name as two terms)
+ * - `"110 00"` with `fuseTokens` (postcode-typed) → `"110" "00"` per-token fused — the #920 name law
+ * - `"Pari* TX"` → `Pari* "TX"` (mixed prefix + phrase)
+ * - `"*"` alone → `""` (no body → drop)
+ */
+export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }): string {
+	const out: string[] = []
+
+	for (const rawToken of text.normalize("NFKC").split(/\s+/u)) {
+		const trimmed = rawToken.trim()
+
+		if (!trimmed) continue
+		const hasPrefixStar = trimmed.endsWith("*")
+
+		// #920 name law (postcode-typed queries ONLY): delete intra-token punctuation and FUSE the
+		// remainder — postal names are stored in this collapsed shape ("SW1A" stays one term).
+		if (opts?.fuseTokens) {
+			const body = trimmed.replaceAll(/[^\p{L}\p{N}]/gu, "")
+
+			if (!body) continue
+			out.push(hasPrefixStar ? `${body}*` : `"${body.replaceAll('"', '""')}"`)
+
+			continue
+		}
+
+		// Everything else SPLITS on intra-token punctuation — the behavior the docstring always
+		// promised ("St. (Petersburg)" → two phrases). The old code DELETED punctuation instead,
+		// fusing "Thiron-Gardais" into the unmatchable single term `ThironGardais` while the FTS
+		// doc holds two terms (#945 — the entire hyphenated-name class missed at the raw lookup;
+		// masked for years because pre-splice tokenizers never emitted hyphen-preserved values).
+		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter(Boolean)
+
+		if (!parts.length) continue
+
+		for (let i = 0; i < parts.length; i++) {
+			const body = parts[i]!.replaceAll("*", "")
+
+			if (!body) continue
+			// The caller's trailing `*` applies to the FINAL part ("Thiron-Gard*" → "Thiron" Gard*).
+			out.push(hasPrefixStar && i === parts.length - 1 ? `${body}*` : `"${body.replaceAll('"', '""')}"`)
+		}
+	}
+
+	return out.join(" ")
+}