@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/fst/autocomplete.ts

@@ -3,18 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FST-based autocomplete — mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm
- *   (#1728 phase 2). The #587 behavior — prefix walk + BFS expansion, partial-last-token completion,
- *   per-branch capping, dedupe — lives in ancestrie's `autocomplete`; this module contributes only
- *   the storage adapter ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to
- *   mailwoman's suggestion shape (name, placetype, referential/encyclopedic, WOF ids).
+ *   FST-based autocomplete, mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm.
+ *   The prefix walk, BFS expansion, partial-last-token completion, per-branch capping and dedupe
+ *   live in ancestrie's `autocomplete`. This module contributes only the storage adapter
+ *   ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to mailwoman's suggestion
+ *   shape (name, placetype, referential and encyclopedic scores, WOF ids).
  *
- *   THE BYTES DO NOT MIGRATE. The shipped artifacts are `FST\0` v1–v5 (`fst-serialize.ts`), not
- *   ancestrie's `ANCT`: ancestrie entries are id-keyed with one record per id, while an FST place row
- *   is per-(surface, place) — `crossCountryBranches` is a property of the SURFACE, so the same wofID
- *   legitimately carries different values under different aliases and cannot be represented id-keyed.
- *   The matcher, both deserializers, and the serializer therefore stay here; what migrated is the
- *   ALGORITHM, which is the half that drifts (the #861 share-the-function rule).
+ *   The bytes do not migrate. The shipped artifacts are `FST\0` v1 to v5 (`fst-serialize.ts`), and
+ *   ancestrie's entries are id-keyed with one record per id. An FST place row is per-(surface,
+ *   place), because `crossCountryBranches` is a property of the surface, so the same wofID
+ *   legitimately has different values under different aliases, so it cannot use IDs as keys.
+ *   The matcher, both deserializers and serializer stay here. The algorithm is the
+ *   half that migrated.
  */
 
 import type {
@@ -41,16 +41,20 @@ export interface AutocompleteSuggestion {
 	name: string
 	placetype: string
 	/**
-	 * 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.
+	 * 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 appears in {@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 (Wikipedia) importance, when the FST artifact stores one for this place.
+	 *
+	 * `undefined` means no article, or a pre-v5 binary.
+	 * It is never 0.
 	 */
-	encyclopedic?: number
+	encyclopedic: number | null
 	wofID: number
 	parentChain: number[]
 	matchDepth: number
@@ -61,22 +65,28 @@ export interface AutocompleteOpts {
 	maxSuggestions?: number
 	maxExpansionDepth?: number
 	/**
-	 * 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)
+	 * Collapse same-name suggestions to the single highest-referential one.
+	 *
+	 * Off by default, because the CLI surfaces distinct same-name places such as
+	 * New York the city and New York the county.
+	 * A typeahead wants it on so the dropdown does not show four "New London"s.
 	 */
 	dedupeByName?: boolean
 }
 
 /**
- * Max accepting entries collected per BFS branch — keeps one dense branch from starving the search.
+ * Max accepting entries collected per BFS branch, keeping one dense branch from starving the search.
  */
 const PER_BRANCH = 4
 
 /**
- * The top-`k` entries by REFERENTIAL likelihood (descending). Avoids sorting/allocating when `entries` is small — and
- * that shortcut is part of the observable contract: at or under `k` the INSERTION order is served, which decides
- * suggestion order among referential ties.
+ * The top-`k` entries by referential likelihood (descending).
+ *
+ * Avoids sorting or allocating when `entries` is small.
+ * That shortcut is part of the observable interface.
+ *
+ * At or under `k`, suggestions retain insertion order.
+ * That order decides suggestions among referential ties.
  */
 function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
 	if (entries.length <= k) return [...entries]
@@ -85,19 +95,23 @@ function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry
 }
 
 /**
- * {@link FSTMatcher} presented through ancestrie's storage interface. Records carry the {@link PlaceEntry} itself as the
- * payload, so the entry that WINS the algorithm's shallowest-depth rule is the entry whose fields the suggestion
- * reports — a side lookup keyed on id could pick a different surface's row (`crossCountryBranches` differs per
- * surface).
+ * {@link FSTMatcher} presented through ancestrie's storage interface.
+ *
+ * Records store the {@link PlaceEntry} itself as the payload, so the entry that wins the
+ * algorithm's shallowest-depth rule is the entry whose fields the suggestion reports.
+ * A side lookup keyed on id could pick a different surface's row
+ * (`crossCountryBranches` differs per surface).
  */
 class FSTReader implements AncestrieReaderLike<PlaceEntry> {
 	readonly #fst: FSTMatcher
 
 	/**
-	 * Parent chains of the entries this reader has served, id-keyed. A place's chain is identical across its surfaces (it
-	 * is place-row data), so last-write-wins is safe. The algorithm asks {@link FSTReader.ancestorsOf} only for ids it
-	 * just received from {@link FSTReader.entriesAt}, so serving from this memo answers every real call without an
-	 * artifact-wide id index.
+	 * Parent chains of the entries this reader has served, id-keyed.
+	 *
+	 * A place's chain is identical across its surfaces (it is place-row data), so last-write-wins is safe.
+	 * The algorithm asks {@link FSTReader.ancestorsOf} only for ids it just received
+	 * from {@link FSTReader.entriesAt}, so serving from this memo answers every
+	 * real call without an artifact-wide id index.
 	 */
 	readonly #chains = new Map<number, number[]>()
 
@@ -110,7 +124,8 @@ class FSTReader implements AncestrieReaderLike<PlaceEntry> {
 	}
 
 	continuations(stateID: number): AncestrieContinuation[] {
-		// Insertion order, verbatim — BFS visit order under the suggestion budget depends on it.
+		// Insertion order, verbatim.
+		// BFS visit order under the suggestion budget depends on it.
 		return this.#fst.continuations(stateID).map((c) => ({
 			token: c.token,
 			targetState: c.targetState,
@@ -140,7 +155,9 @@ class FSTReader implements AncestrieReaderLike<PlaceEntry> {
 }
 
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
+ * Autocomplete from the current prefix.
+ *
+ * @returns Suggestions ranked referential-descending.
  */
 export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteOpts = {}): AutocompleteResult {
 	const normalizedTokens = normalizeTokens(query)
@@ -149,7 +166,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 		...(opts.maxSuggestions === undefined ? {} : { maxSuggestions: opts.maxSuggestions }),
 		...(opts.maxExpansionDepth === undefined ? {} : { maxExpansionDepth: opts.maxExpansionDepth }),
 		perBranchLimit: PER_BRANCH,
-		// The dedupe key is the DISPLAY name, not the token path: two surfaces of one name must still collapse. (#587)
+		// The dedupe key is the display name, so two surfaces of one name still collapse.
 		...(opts.dedupeByName ? { dedupe: (s: AncestrieSuggestion<PlaceEntry>) => s.payload!.name.toLowerCase() } : {}),
 	})
 
@@ -158,14 +175,14 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 		normalizedTokens,
 		depth: result.depth,
 		suggestions: result.suggestions.map((s) => {
-			// Every record this adapter serves carries its entry; the assertion documents the invariant.
+			// Every record this adapter serves includes its entry, so the non-null assertion holds.
 			const entry = s.payload!
 
 			return {
 				name: entry.name,
 				placetype: entry.placetype,
 				referential: entry.referential,
-				...(entry.encyclopedic === undefined ? {} : { encyclopedic: entry.encyclopedic }),
+				encyclopedic: entry.encyclopedic,
 				wofID: s.id,
 				parentChain: s.parentIDs,
 				matchDepth: s.matchDepth,

package/lib/fst/builder.ts

@@ -35,8 +35,10 @@ const DEFAULT_PLACETYPES: PlacetypeID[] = [
 const DEFAULT_COUNTRIES = ["US"]
 const DEFAULT_LANGUAGES = ["eng", ""]
 /**
- * Ids per `IN (…)` batch. SQLITE_MAX_VARIABLE_NUMBER defaults to 32,766; 500 matches the name-load batch a few phases
- * down, so both read paths bind the same shape.
+ * Ids per `IN (…)` batch.
+ *
+ * SQLITE_MAX_VARIABLE_NUMBER defaults to 32,766. 500 matches the name-load batch a
+ * few phases down, so both read paths bind the same shape.
  */
 const ANCESTOR_CHUNK = 500
 
@@ -70,7 +72,6 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 	progress("open", dbPath)
 	using db = new DatabaseClient<WOFDatabase>(dbPath, { open: true })
 
-	// Phase 1: Load all matching SPR rows.
 	progress("spr", `Loading places for countries=[${countries}], placetypes=[${placetypes}]`)
 	const placeholders = (arr: string[]) => arr.map(() => "?").join(",")
 
@@ -85,20 +86,18 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 	const sprRows = allRows<SprRow>(sprStmt, ...countries, ...placetypes)
 	progress("spr", `Loaded ${sprRows.length} places`)
 
-	// Phase 2: Build a lookup for parent chain resolution.
 	const sprByID = new Map<number, SprRow>()
 
 	for (const row of sprRows) {
 		sprByID.set(row.id, row)
 	}
 
-	// Also load parent rows that might be outside our placetype filter (e.g., country for region).
+	// Load parent rows that might be outside the placetype filter, such as a country for a region.
 	const parentStmt = db.prepare("SELECT id, name, placetype, parent_id, latitude, longitude FROM spr WHERE id = ?")
 
-	// Fallback for a sentinel parent_id (-1, -4, …): the ancestors table. Read in chunked `IN (…)`
-	// batches ONCE — the point-query version fired per orphan row, and on a global build the orphans
-	// run to six figures. Ordering is county → region → country, preserved by the same CASE the
-	// per-row query used, with `id` leading so one pass groups the rows.
+	// Fallback for a sentinel parent_id (-1, -4, …): the ancestors table,
+	// read in chunked `IN (…)` batches once.
+	// Sort IDs in county → region → country order so one pass groups the rows.
 	const ancestorsByID = new Map<number, number[]>()
 
 	try {
@@ -139,12 +138,10 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 
 		if (!row) return []
 
-		// If parent_id is a sentinel (≤ 0), use ancestors table.
 		if (row.parent_id <= 0) {
 			return (ancestorsByID.get(id) ?? []).filter((ancestorID) => ancestorID !== id)
 		}
 
-		// Normal case: walk parent_id chain.
 		const chain: number[] = []
 		let current = row.parent_id
 		const seen = new Set<number>([id])
@@ -172,13 +169,13 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 		return chain
 	}
 
-	// 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.
+	// Load both scores (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 importance remains available to consumers and is never handed to the decoder.
+	// `loadImportanceSplit` handles all four schema generations.
+	// Provenance records the source so the artifact identifies the schema it read.
 	progress("importance", "Loading referential + encyclopedic scores")
 	const split = loadImportanceSplit(db)
 
@@ -189,7 +186,6 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 			")"
 	)
 
-	// Phase 4: Load names for matching places.
 	progress("names", "Loading name variants")
 	const placeIDs = sprRows.map((r) => r.id)
 	const namesByPlace = new Map<number, string[]>()
@@ -223,12 +219,12 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 
 	progress("names", `Loaded names for ${namesByPlace.size} places`)
 
-	// Phase 5: Build the trie.
 	progress("trie", "Building trie")
 	const nodes: FSTNode[] = [{ edges: new Map(), places: [] }]
 
-	// 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.
+	// 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
@@ -238,14 +234,15 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 
 		if (excludeSurfaces?.has(tokens.join(" "))) return true
 
-		if (excludeAllTokensOf !== undefined && tokens.every((t) => excludeAllTokensOf.has(t))) return true
+		if (excludeAllTokensOf && 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).
+	// Surface-ambiguity classes are per-surface facts, so clone the entry for each
+	// insertion and attach that surface's count.
+	// The same place under "nyc" and "new york city" records a separate ambiguity count for each surface.
+	// An absent map means entries have no count for back-compat bytes.
 	const surfaceCountryCounts = opts.surfaceCountryCounts
 
 	function insertName(tokens: string[], entry: PlaceEntry): boolean {
@@ -272,11 +269,10 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 			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)) {
-			if (surfaceCountryCounts !== undefined) {
+			if (surfaceCountryCounts) {
 				const count = surfaceCountryCounts.get(tokens.join(" "))
 				existing.push({ ...entry, crossCountryBranches: Math.min(count ?? 1, 255) })
 			} else {
@@ -300,21 +296,20 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 			name: row.name,
 			parentChain,
 			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 }),
+			// A place with no Wikipedia article is `null` rather than a zero.
+			// The serializer's per-place presence bit reads `!== null`.
+			encyclopedic: encyclopedic ?? null,
 			lat: row.latitude,
 			lon: row.longitude,
+			crossCountryBranches: null,
 		}
 
-		// Insert the primary name from spr.
 		const primaryTokens = normalizeTokens(row.name)
 
 		if (insertName(primaryTokens, entry)) {
 			insertCount++
 		}
 
-		// Insert alt names from the names table.
 		const altNames = namesByPlace.get(row.id) ?? []
 
 		for (const altName of altNames) {
@@ -336,12 +331,12 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 	const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0)
 	const matcher = FSTMatcher.fromNodes(nodes)
 
-	// The build stamp (2026-08-05). `sourceDB` alone was never enough to tell a reader whether this
-	// artifact matches the database at that path — the admin DB is sealed and REPLACED by a rebuild, so
-	// the path is constant across every generation of it. Hashing costs 7.3 s for the 5.27 GB admin DB
-	// and is free whenever the `.md5` sidecar is current, which the admin build already writes.
-	// `sourceIdentity` lets a caller that already knows the digest (or is building from something that
-	// is not a file at all) supply it instead.
+	// The build stamp.
+	// `sourceDB` by itself cannot tell a reader whether this artifact matches the database
+	// at that path, because the admin database is sealed and replaced by a rebuild
+	// so the path is constant across every generation.
+	// `sourceIdentity` lets a caller that already knows the digest, or is building
+	// from something that is not a file at all, supply it instead.
 	progress("stamp", `Reading source identity for ${dbPath}`)
 	const source = opts.sourceIdentity ?? (await readWOFSourceIdentity(dbPath))
 
@@ -358,9 +353,10 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 		sourceDB: dbPath,
 		sourceDBMD5: source.md5,
 		sourceDBBytes: source.bytes,
-		...(excludeSurfaces !== undefined || excludeAllTokensOf !== undefined
+		modelCardVersion: null,
+		...(excludeSurfaces || excludeAllTokensOf
 			? { exclusionPolicy: opts.exclusionPolicy ?? "unspecified", excludedInsertions: excludedCount }
-			: {}),
+			: { exclusionPolicy: null, excludedInsertions: null }),
 	}
 
 	return {

package/lib/fst/deserialize-web.ts

@@ -4,10 +4,10 @@
  * @author Teffen Ellis, et al.
  *
  *   Browser-compatible FST deserializer. Uses DataView + TextDecoder instead of Node's Buffer so the
- *   same binary format can be loaded in the browser via fetch(url).then(r => r.arrayBuffer()).
+ *   same binary format loads in the browser through fetch(url).then(r => r.arrayBuffer()).
  *
- *   This is a read-only counterpart to fst-serialize.ts — serialization stays Node-only (it's a
- *   build-time operation).
+ *   This is a read-only counterpart to fst-serialize.ts. Serialization stays Node-only because it is
+ *   a build-time operation.
  */
 
 import { tryParsingJSON } from "@mailwoman/core/json"
@@ -56,7 +56,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.
+	// flags bit0 (mirrors fst-serialize.ts): place rows include surface-ambiguity data.
 	const hasAmbiguity = (view.getUint16(6, true) & 1) === 1
 
 	const stateCount = view.getUint32(8, true)
@@ -67,7 +67,6 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	let pos = HEADER_SIZE
 
-	// Decode the interned string table.
 	const strOffsets = new Uint32Array(stringCount + 1)
 
 	for (let i = 0; i <= stringCount; i++) {
@@ -86,9 +85,8 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	pos += stringBytes
 
-	// Decode the state table and its transitions.
 	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.
+	// 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
@@ -127,8 +125,9 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 				parentChain.push(view.getUint32(pp + 24 + ci * 4, true))
 			}
 
-			// 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.
+			// v1 stored a raw population u32 here. v2-v4 stored the conflated `importance`
+			// float. v5 stored the referential score.
+			// The Node deserializer explains 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)
@@ -144,8 +143,8 @@ 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) } : {}),
-				...(hasEncyclopedic ? { encyclopedic: view.getFloat32(pp + ENCYCLOPEDIC_OFFSET, true) } : {}),
+				crossCountryBranches: hasAmbiguity ? view.getUint8(pp + 6) : null,
+				encyclopedic: hasEncyclopedic ? view.getFloat32(pp + ENCYCLOPEDIC_OFFSET, true) : null,
 			}
 		}
 
@@ -155,25 +154,25 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 	return FSTMatcher.fromNodes(nodes)
 }
 
-export function readFSTProvenanceWeb(input: ArrayBuffer | Uint8Array): FSTProvenance | undefined {
+export function readFSTProvenanceWeb(input: ArrayBuffer | Uint8Array): FSTProvenance | null {
 	const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
 	const decoder = new TextDecoder("utf-8")
 
-	if (bytes.byteLength < HEADER_SIZE) return undefined
+	if (bytes.byteLength < HEADER_SIZE) return null
 	const version = view.getUint16(4, true)
 
-	if (version < VERSION_WITH_METADATA) return undefined
+	if (version < VERSION_WITH_METADATA) return null
 	const provenanceOffset = view.getUint32(28, true)
 
-	if (provenanceOffset === 0 || provenanceOffset >= bytes.byteLength) return undefined
+	if (provenanceOffset === 0 || provenanceOffset >= bytes.byteLength) return null
 
 	try {
 		const jsonLen = view.getUint32(provenanceOffset, true)
 		const jsonStr = decoder.decode(bytes.subarray(provenanceOffset + 4, provenanceOffset + 4 + jsonLen))
 
-		return tryParsingJSON<FSTProvenance>(jsonStr) ?? undefined
+		return tryParsingJSON<FSTProvenance>(jsonStr) ?? null
 	} catch {
-		return undefined
+		return null
 	}
 }

package/lib/fst/format.ts

@@ -4,26 +4,33 @@
  * @author Teffen Ellis, et al.
  *
  *   The FST binary-format constants, shared by the Node serializer/deserializer (`fst-serialize.ts`)
- *   and the browser deserializer (`fst-deserialize-web.ts`). Platform-free by design — no Buffer at
- *   module scope; both runtimes convert {@link FST_MAGIC_BYTES} themselves.
+ *   and the browser deserializer (`fst-deserialize-web.ts`). This module stays platform-free.
+ *   It uses no Buffer at module scope. Both runtimes convert {@link FST_MAGIC_BYTES} themselves.
  */
 
 import type { PlacetypeID } from "#fst/types"
 
 /**
- * Format version this tree WRITES and the maximum either deserializer accepts, published so a freshness guard can call
- * an older artifact format-stale without re-typing the number (mirrors `REQUIRED_PAIR_INDEX_SCHEMA`'s role for PIX1 —
- * see `fst-freshness.ts`).
+ * Format version this tree writes and the maximum either deserializer accepts, published
+ * so a freshness guard can call an older artifact format-stale without re-typing the number
+ * (mirrors `REQUIRED_PAIR_INDEX_SCHEMA`'s role for PIX1 — see `fst-freshness.ts`).
  *
- * ONE constant for the writer and both readers, deliberately. The browser reader's acceptance criterion was a SEPARATE
- * `MAX_VERSION` number from the layout branches, and it drifted twice: left stale at 2 when the v4 wide-state layout
- * shipped (rejecting every real artifact), and stale again at 4 through the v5 two-score split until the line moved by
- * hand. A check that is the writer's version cannot drift from it.
+ * One constant for the writer and both readers, deliberately.
+ * The browser reader once kept a separate `MAX_VERSION` from the layout branches.
+ *
+ * It drifted twice.
+ * It stayed at 2 after the v4 wide-state layout shipped and rejected every real artifact.
+ *
+ * It later stayed at 4 through the v5 two-score split until someone updated it by hand.
+ *
+ * A check that is the writer's version cannot drift from it.
  */
 export const FST_FORMAT_VERSION = 5
 
 /**
- * Fixed header size in bytes: magic, version, and the section offsets that follow it.
+ * Fixed header size in bytes.
+ *
+ * It stores the magic and version, followed by section offsets.
  */
 export const HEADER_SIZE = 32
 
@@ -33,8 +40,10 @@ export const HEADER_SIZE = 32
 export const EDGE_ENTRY_SIZE = 8
 
 /**
- * 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.
+ * 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.
  */
 export const VERSION_WIDE_STATE_COUNTERS = 4
 
@@ -49,14 +58,15 @@ export const WIDE_STATE_ENTRY_SIZE = 16
 export const NARROW_STATE_ENTRY_SIZE = 12
 
 /**
- * First format version carrying the trailing metadata block; older files simply have none.
+ * First format version carrying the trailing metadata block.
+ * Older files simply have none.
  */
 export const VERSION_WITH_METADATA = 3
 
 /**
- * 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 and claiming the previously-reserved `pp+7` byte as
- * {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
+ * 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
+ * and claiming the previously-reserved `pp+7` byte as {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
  */
 export const VERSION_TWO_SCORE_SPLIT = 5
 
@@ -71,25 +81,33 @@ export const SPLIT_PLACE_ENTRY_SIZE = 60
 export const LEGACY_PLACE_ENTRY_SIZE = 56
 
 /**
- * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
+ * Byte offset of the encyclopedic float inside a v5 place entry — immediately
+ * after the 8-slot parent chain.
  */
 export 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.
+ * `placeFlags` bit 0 (byte `pp+7`, v5+): this place has 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.
  */
 export const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
 
 /**
- * File magic, "FST\0" as bytes. A reader rejects anything not starting with these four bytes before parsing further.
+ * File magic, "FST\0" as bytes.
+ *
+ * A reader rejects anything not starting with these four bytes before parsing further.
  */
 export const FST_MAGIC_BYTES: readonly number[] = [0x46, 0x53, 0x54, 0x00]
 
 /**
- * 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.
+ * Placetypes in hierarchy order, largest first.
+ *
+ * The writer stores each placetype's index in a place entry.
+ * A different array order invalidates every existing file.
+ * Append entries and bump the version.
  */
 export const PLACETYPE_ORDER: readonly PlacetypeID[] = [
 	"country",