@mailwoman/resolver-wof-sqlite 10.1.0 → 10.2.1

package/lib/coverage-manifest-schema.ts

@@ -146,8 +146,8 @@ export async function writeGazetteerCoverageManifest(
 				facts.coverage.map((f) => ({
 					country: f.country.toUpperCase(),
 					hard_filter_safe: f.hardFilterSafe ? 1 : 0,
-					hard_resolve_rate: f.hardResolveRate ?? null,
-					sample_size: f.sampleSize ?? null,
+					hard_resolve_rate: f.hardResolveRate,
+					sample_size: f.sampleSize,
 					measured_at: f.measuredAt,
 					source: f.source,
 				}))
@@ -180,11 +180,11 @@ export async function writeGazetteerCoverageManifest(
  *
  * The reads are synchronous because the candidate lookup calls this from its constructor.
  */
-export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): GazetteerArtifactCoverage | undefined {
+export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): GazetteerArtifactCoverage | null {
 	const hasCoverage = hasTable(db, COUNTRY_COVERAGE_TABLE)
 	const hasBBox = hasTable(db, COUNTRY_BBOX_TABLE)
 
-	if (!hasCoverage && !hasBBox) return undefined
+	if (!hasCoverage && !hasBBox) return null
 
 	const countryCoverage = new Map<string, CountryCoverageFact>()
 
@@ -201,8 +201,8 @@ export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): Gazet
 			countryCoverage.set(country, {
 				country,
 				hardFilterSafe: Number(row.hard_filter_safe) !== 0,
-				...(row.hard_resolve_rate === null ? {} : { hardResolveRate: Number(row.hard_resolve_rate) }),
-				...(row.sample_size === null ? {} : { sampleSize: Number(row.sample_size) }),
+				hardResolveRate: row.hard_resolve_rate === null ? null : Number(row.hard_resolve_rate),
+				sampleSize: row.sample_size === null ? null : Number(row.sample_size),
 				measuredAt: String(row.measured_at),
 				source: String(row.source),
 			})

package/lib/currency-backfill.ts

@@ -6,7 +6,7 @@
  *   Restores deprecated WOF localities only when an independent source attests them.
  */
 
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { isStrictlyFiner } from "@mailwoman/core/resources/whosonfirst"
 import { haversineKm } from "@mailwoman/spatial"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
@@ -27,7 +27,7 @@ const CURRENCY_BACKFILL_POP_FLOOR = 1000
  * Restore a deprecated locality only when no nearby live namesake exists and GeoNames
  * attests the same folded name above {@link CURRENCY_BACKFILL_POP_FLOOR}.
  */
-export interface CurrencyBackfillOutcomes {
+export interface CurrencyBackfillResults {
 	judged: number
 	blocked: number
 	unattested: number
@@ -36,14 +36,14 @@ export interface CurrencyBackfillOutcomes {
 }
 
 /**
- * One country's read of the check — every dead name judged, by outcome and by the dead
+ * One country's read of the check — every dead name judged, by result and by the dead
  * row's placetype — so a census can say what a wider query admits.
  */
-export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes {
+export interface CurrencyBackfillCountryReport extends CurrencyBackfillResults {
 	country: string
 	deadPlacetypes: readonly string[]
 	dumpPresent: boolean
-	byDeadPlacetype: Record<string, CurrencyBackfillOutcomes>
+	byDeadPlacetype: Record<string, CurrencyBackfillResults>
 	/**
 	 * The first resurrected names, `placetype:name`, capped because the report is a receipt and not the table.
 	 */
@@ -57,7 +57,7 @@ const REPORT_SAMPLE_SIZE = 25
  */
 export const DEFAULT_DEAD_PLACETYPES: readonly string[] = ["locality"]
 
-function emptyOutcomes(): CurrencyBackfillOutcomes {
+function emptyResults(): CurrencyBackfillResults {
 	return { judged: 0, blocked: 0, unattested: 0, floored: 0, resurrected: 0 }
 }
 
@@ -73,7 +73,7 @@ export async function resurrectCurrencyHoles(ctx: {
 	ccID: (code: string | null) => number
 	ptID: (pt: string | null) => number
 	regionOf: Map<number, number>
-	importance: ReturnType<typeof loadImportanceIndex> | undefined
+	importance: ReturnType<typeof loadImportanceIndex> | null
 	stageRow: StageRow
 	progress: (phase: string, message: string) => void
 
@@ -83,7 +83,7 @@ export async function resurrectCurrencyHoles(ctx: {
 	 */
 	dryRun?: boolean
 	/**
-	 * Receives one report per country judged (a country with no dump or no dead rows reports zero outcomes).
+	 * Receives one report per country judged (a country with no dump or no dead rows reports zero results).
 	 */
 	onCountry?: (report: CurrencyBackfillCountryReport) => void
 }): Promise<number> {
@@ -117,7 +117,7 @@ export async function resurrectCurrencyHoles(ctx: {
 			country: cc,
 			deadPlacetypes,
 			dumpPresent: await pathExists(dumpPath),
-			...emptyOutcomes(),
+			...emptyResults(),
 			byDeadPlacetype: {},
 			sample: [],
 		}
@@ -180,11 +180,11 @@ export async function resurrectCurrencyHoles(ctx: {
 
 		const seen = new Set<string>()
 
-		const count = (deadPlacetype: string, outcome: keyof CurrencyBackfillOutcomes): void => {
-			report[outcome] += 1
-			const bucket = (report.byDeadPlacetype[deadPlacetype] ??= emptyOutcomes())
+		const count = (deadPlacetype: string, result: keyof CurrencyBackfillResults): void => {
+			report[result] += 1
+			const bucket = (report.byDeadPlacetype[deadPlacetype] ??= emptyResults())
 
-			bucket[outcome] += 1
+			bucket[result] += 1
 		}
 
 		if (!dryRun) {

package/lib/exact-match.ts

@@ -58,7 +58,7 @@ export function exactMatchIDs<DB>(
 		const needle = foldQueryText(trimmed)
 
 		for (const r of rows) {
-			if (r.name !== null && foldQueryText(r.name) === needle) {
+			if (r.name && foldQueryText(r.name) === needle) {
 				out.add(r.id)
 			}
 		}

package/lib/extracts.ts

@@ -213,7 +213,7 @@ export function pickExtractsForPlacetype(
  */
 export function pickExtractForPlacetype(
 	extracts: ResolvedExtract[],
-	placetype: string | undefined,
+	placetype: string | null,
 	opts?: {
 		/**
 		 * The query's country constraint, when the caller has one.

package/lib/fst/autocomplete.ts

@@ -54,7 +54,7 @@ export interface AutocompleteSuggestion {
 	 * `undefined` means no article, or a pre-v5 binary.
 	 * It is never 0.
 	 */
-	encyclopedic?: number
+	encyclopedic: number | null
 	wofID: number
 	parentChain: number[]
 	matchDepth: number
@@ -182,7 +182,7 @@ export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteO
 				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

@@ -234,7 +234,7 @@ 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
 	}
@@ -272,7 +272,7 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 		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 {
@@ -296,11 +296,12 @@ export async function buildFSTFromWOF(opts: BuildFSTOpts): Promise<{
 			name: row.name,
 			parentChain,
 			referential: split.referential.get(row.id) ?? 0,
-			// Spread rather than assigned, so a place with no Wikipedia article has no field instead of 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,
 		}
 
 		const primaryTokens = normalizeTokens(row.name)
@@ -352,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

@@ -143,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,
 			}
 		}
 
@@ -154,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/freshness.ts

@@ -6,13 +6,14 @@
  * Does an `fst-*.bin` still match the gazetteer it was built from?
  */
 
-import { pathExists, readFileRange, readLocalTextFile, statPath } from "@mailwoman/core/fs/readers"
+import { readFileRange, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { pathExists, statPath } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalTextFile } from "@mailwoman/core/fs/writers"
 import { md5File } from "@mailwoman/core/hash"
 import { tryParsingJSON } from "@mailwoman/core/json"
 import { basename, resolvePath, type PathBuilderLike } from "path-ts"
 
-import { FST_FORMAT_VERSION } from "#fst/serialize"
+import { FST_FORMAT_VERSION } from "#fst/format"
 import type { FSTProvenance } from "#fst/types"
 
 /**
@@ -48,7 +49,7 @@ export interface FSTSourceIdentity {
  */
 export interface FSTStampFields {
 	formatVersion: number
-	provenance: FSTProvenance | undefined
+	provenance: FSTProvenance | null
 }
 
 /**
@@ -59,37 +60,37 @@ export interface FSTExpectation {
 	/**
 	 * Serializer version to require, defaulting to {@link FST_FORMAT_VERSION}.
 	 */
-	formatVersion?: number
-	exclusionPolicy?: string
+	formatVersion?: number | null
+	exclusionPolicy?: string | null
 }
 
 /**
  * Read an artifact's stamp without deserializing it.
  */
-export async function peekFSTStampFields(path: PathBuilderLike): Promise<FSTStampFields | undefined> {
-	if (!(await pathExists(path))) return undefined
+export async function peekFSTStampFields(path: PathBuilderLike): Promise<FSTStampFields | null> {
+	if (!(await pathExists(path))) return null
 	const size = (await statPath(path)).size
 
-	if (size < HEADER_SIZE) return undefined
+	if (size < HEADER_SIZE) return null
 	const header = await readFileRange(path, 0, HEADER_SIZE)
 
-	if (header.readUInt32LE(0) !== MAGIC) return undefined
+	if (header.readUInt32LE(0) !== MAGIC) return null
 	const formatVersion = header.readUInt16LE(4)
 
-	if (formatVersion < MIN_STAMPED_FORMAT_VERSION) return { formatVersion, provenance: undefined }
+	if (formatVersion < MIN_STAMPED_FORMAT_VERSION) return { formatVersion, provenance: null }
 	const trailerStart = header.readUInt32LE(PROVENANCE_OFFSET_FIELD)
 
 	// 0 means this build wrote no trailer and past-EOF means truncated.
 	// Both read as no stamp.
-	if (trailerStart === 0 || trailerStart + 4 > size) return { formatVersion, provenance: undefined }
+	if (trailerStart === 0 || trailerStart + 4 > size) return { formatVersion, provenance: null }
 
 	const jsonLength = (await readFileRange(path, trailerStart, 4)).readUInt32LE(0)
 
-	if (jsonLength === 0 || trailerStart + 4 + jsonLength > size) return { formatVersion, provenance: undefined }
+	if (jsonLength === 0 || trailerStart + 4 + jsonLength > size) return { formatVersion, provenance: null }
 
 	const json = await readFileRange(path, trailerStart + 4, jsonLength)
 
-	return { formatVersion, provenance: tryParsingJSON<FSTProvenance>(json.toString("utf8")) ?? undefined }
+	return { formatVersion, provenance: tryParsingJSON<FSTProvenance>(json.toString("utf8")) ?? null }
 }
 
 /**
@@ -106,7 +107,7 @@ export async function readWOFSourceIdentity(
 
 	if (hit) return hit
 	const sidecarPath = `${path}.md5`
-	let md5: string | undefined
+	let md5: string | null = null
 
 	if (await pathExists(sidecarPath)) {
 		const sidecarStats = await statPath(sidecarPath)
@@ -141,9 +142,9 @@ export async function readWOFSourceIdentity(
 const sourceIdentityMemo = new Map<string, FSTSourceIdentity>()
 
 /**
- * Why an FST artifact is stale against `expected`, or `undefined` when it still matches.
+ * Why an FST artifact is stale against `expected`, or `null` when it still matches.
  */
-export function fstStaleReason(fields: FSTStampFields | undefined, expected: FSTExpectation): string | undefined {
+export function fstStaleReason(fields: FSTStampFields | null, expected: FSTExpectation): string | null {
 	if (!fields) return "unreadable or not an FST artifact"
 	const requiredFormat = expected.formatVersion ?? FST_FORMAT_VERSION
 
@@ -167,15 +168,15 @@ export function fstStaleReason(fields: FSTStampFields | undefined, expected: FST
 		return `source db ${provenance.sourceDBMD5.slice(0, 8)} → ${expected.source.md5.slice(0, 8)} (built ${provenance.builtAt})`
 	}
 
-	if (provenance.sourceDBBytes !== undefined && provenance.sourceDBBytes !== expected.source.bytes) {
+	if (provenance.sourceDBBytes != null && provenance.sourceDBBytes !== expected.source.bytes) {
 		return `source db size ${provenance.sourceDBBytes} → ${expected.source.bytes} at a matching md5 — one of the two is misrecorded`
 	}
 
-	if (expected.exclusionPolicy !== undefined && provenance.exclusionPolicy !== expected.exclusionPolicy) {
+	if (expected.exclusionPolicy && provenance.exclusionPolicy !== expected.exclusionPolicy) {
 		return `exclusion policy ${provenance.exclusionPolicy ?? "(none)"} → ${expected.exclusionPolicy}`
 	}
 
-	return undefined
+	return null
 }
 
 /**
@@ -190,19 +191,19 @@ export async function fstFreshnessWarning({
 }: {
 	fstPath: PathBuilderLike
 	sourceDBPath: PathBuilderLike
-	formatVersion?: number
-	exclusionPolicy?: string
+	formatVersion?: number | null
+	exclusionPolicy?: string | null
 	rebuildCommand: string
-}): Promise<string | undefined> {
-	if (!(await pathExists(fstPath)) || !(await pathExists(sourceDBPath))) return undefined
+}): Promise<string | null> {
+	if (!(await pathExists(fstPath)) || !(await pathExists(sourceDBPath))) return null
 
 	const reason = fstStaleReason(await peekFSTStampFields(fstPath), {
 		source: await readWOFSourceIdentity(sourceDBPath),
-		...(formatVersion === undefined ? {} : { formatVersion }),
-		...(exclusionPolicy === undefined ? {} : { exclusionPolicy }),
+		formatVersion: formatVersion ?? null,
+		exclusionPolicy: exclusionPolicy ?? null,
 	})
 
-	return reason === undefined ? undefined : formatFSTStaleWarning({ fstPath, reason, rebuildCommand })
+	return reason ? formatFSTStaleWarning({ fstPath, reason, rebuildCommand }) : null
 }
 
 /**

package/lib/fst/matcher.ts

@@ -8,7 +8,9 @@
  *   arrays at accepting states.
  */
 
-import type { FSTContinuation, FSTMatchResult, FSTQueryResult, PlaceEntry } from "#fst/types"
+import type { AncestrieMatch } from "@mailwoman/ancestrie"
+
+import type { FSTContinuation, FSTQueryResult, PlaceEntry } from "#fst/types"
 
 interface FSTNode {
 	edges: Map<string, number>
@@ -36,7 +38,7 @@ export class FSTMatcher {
 		return count
 	}
 
-	walk(tokens: string[]): FSTMatchResult | null {
+	walk(tokens: string[]): AncestrieMatch | null {
 		let stateID = 0
 
 		for (const token of tokens) {
@@ -54,7 +56,7 @@ export class FSTMatcher {
 		return { stateID, accepted: node.places.length > 0, depth: tokens.length }
 	}
 
-	walkFrom(prev: FSTMatchResult, token: string): FSTMatchResult | null {
+	walkFrom(prev: AncestrieMatch, token: string): AncestrieMatch | null {
 		const node = this.nodes[prev.stateID]
 
 		if (!node) return null

package/lib/fst/serialize.ts

@@ -44,11 +44,6 @@ import type { FSTNode } from "#fst/matcher"
 import { FSTMatcher } from "#fst/matcher"
 import type { FSTProvenance, PlaceEntry } from "#fst/types"
 
-/**
- * Re-exports the format version that {@link serializeFST} writes.
- */
-export { FST_FORMAT_VERSION } from "#fst/format"
-
 const MAGIC = Buffer.from(FST_MAGIC_BYTES)
 
 /**
@@ -119,7 +114,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 
 	// Flag bit 0 marks that place rows include `crossCountryBranches`.
 	// Readers of a file without it report `undefined`.
-	const hasAmbiguity = nodes.some((n) => n.places.some((p) => p.crossCountryBranches !== undefined))
+	const hasAmbiguity = nodes.some((n) => n.places.some((p) => p.crossCountryBranches != null))
 	MAGIC.copy(buf, pos)
 	pos += 4
 	buf.writeUInt16LE(FST_FORMAT_VERSION, pos)
@@ -191,7 +186,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 			buf.writeUInt8(hasAmbiguity ? Math.min(place.crossCountryBranches ?? 0, 255) : 0, pp + 6)
 			// An absent encyclopedic score writes flag 0 and a 0.0 float.
 			// Readers skip the float when the flag is 0.
-			const hasEncyclopedic = place.encyclopedic !== undefined
+			const hasEncyclopedic = place.encyclopedic != null
 			buf.writeUInt8(hasEncyclopedic ? PLACE_FLAG_HAS_ENCYCLOPEDIC : 0, pp + 7)
 			buf.writeUInt32LE(intern(place.name), pp + 8)
 			buf.writeFloatLE(place.referential, pp + 12)
@@ -202,7 +197,7 @@ 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)
+			buf.writeFloatLE(place.encyclopedic ?? 0, pp + ENCYCLOPEDIC_OFFSET)
 
 			placeIdx++
 		}
@@ -320,8 +315,8 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 				lat: buf.readFloatLE(pp + 16),
 				lon: buf.readFloatLE(pp + 20),
 				parentChain,
-				...(hasAmbiguity ? { crossCountryBranches: buf.readUInt8(pp + 6) } : {}),
-				...(hasEncyclopedic ? { encyclopedic: buf.readFloatLE(pp + ENCYCLOPEDIC_OFFSET) } : {}),
+				crossCountryBranches: hasAmbiguity ? buf.readUInt8(pp + 6) : null,
+				encyclopedic: hasEncyclopedic ? buf.readFloatLE(pp + ENCYCLOPEDIC_OFFSET) : null,
 			}
 		}
 
@@ -335,23 +330,23 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
  * Reads the provenance trailer from an FST binary, or returns `undefined`
  * when the file has none or it cannot be parsed.
  */
-export function readFSTProvenance(buf: Buffer): FSTProvenance | undefined {
-	if (buf.length < HEADER_SIZE) return undefined
+export function readFSTProvenance(buf: Buffer): FSTProvenance | null {
+	if (buf.length < HEADER_SIZE) return null
 
-	if (!buf.subarray(0, 4).equals(MAGIC)) return undefined
+	if (!buf.subarray(0, 4).equals(MAGIC)) return null
 	const version = buf.readUInt16LE(4)
 
-	if (version < VERSION_WITH_METADATA) return undefined
+	if (version < VERSION_WITH_METADATA) return null
 	const provenanceOffset = buf.readUInt32LE(28)
 
-	if (provenanceOffset === 0 || provenanceOffset >= buf.length) return undefined
+	if (provenanceOffset === 0 || provenanceOffset >= buf.length) return null
 
 	try {
 		const jsonLen = buf.readUInt32LE(provenanceOffset)
 		const jsonStr = buf.toString("utf8", provenanceOffset + 4, provenanceOffset + 4 + jsonLen)
 
-		return tryParsingJSON<FSTProvenance>(jsonStr) ?? undefined
+		return tryParsingJSON<FSTProvenance>(jsonStr) ?? null
 	} catch {
-		return undefined
+		return null
 	}
 }

package/lib/fst/types.ts

@@ -21,16 +21,16 @@ export interface PlaceEntry {
 	referential: number
 	/**
 	 * The encyclopedic importance in [0, 1], for display only.
-	 * It is `undefined` when unavailable.
+	 * It is `null` when unavailable.
 	 */
-	encyclopedic?: number
+	encyclopedic: number | null
 	lat: number
 	lon: number
 	/**
 	 * The number of countries with a place of this surface, clamped to 255.
-	 * It is `undefined` when unavailable.
+	 * It is `null` when unavailable.
 	 */
-	crossCountryBranches?: number
+	crossCountryBranches: number | null
 }
 
 /**
@@ -49,15 +49,6 @@ export type PlacetypeID =
 	| "dependency"
 	| "street_affix"
 
-/**
- * The result of walking a token sequence through the FST.
- */
-export interface FSTMatchResult {
-	stateID: number
-	accepted: boolean
-	depth: number
-}
-
 /**
  * One outgoing edge from an FST state, with the number of places its target state accepts.
  */
@@ -96,16 +87,16 @@ export interface FSTProvenance {
 	/**
 	 * The count of places with an encyclopedic score at build time.
 	 *
-	 * It is `undefined` for a build that predates the separate encyclopedic score.
+	 * It is `null` for a build that predates the separate encyclopedic score.
 	 * The value `0` means a current build used a database without encyclopedic scores.
 	 */
-	encyclopedicMatches?: number
+	encyclopedicMatches: number | null
 	/**
 	 * The {@link ImportanceSplitSource} that records whether the encyclopedic score is real,
 	 * reconstructed from a legacy column, or absent.
 	 */
-	importanceSource?: string
-	sourceDB?: string
+	importanceSource: string | null
+	sourceDB: string | null
 	/**
 	 * The MD5 of the source database's bytes at build time.
 	 * The freshness check compares it.
@@ -113,26 +104,26 @@ export interface FSTProvenance {
 	 * `sourceDB` by itself cannot detect staleness.
 	 * A rebuild replaces the admin database at the same path.
 	 *
-	 * The field is `undefined` for artifacts built before the stamp existed.
+	 * The field is `null` for artifacts built before the stamp existed.
 	 * An unknown digest has a different value.
 	 */
-	sourceDBMD5?: string
+	sourceDBMD5: string | null
 	/**
 	 * The byte size of the source database at build time.
 	 *
 	 * It detects a truncated source and makes a staleness warning readable.
 	 */
-	sourceDBBytes?: number
-	modelCardVersion?: string
+	sourceDBBytes: number | null
+	modelCardVersion: string | null
 	/**
 	 * The surface-exclusion policy applied at build time.
 	 * It is absent for an uncurated build.
 	 */
-	exclusionPolicy?: string
+	exclusionPolicy: string | null
 	/**
 	 * The count of name insertions the exclusion policy rejected.
 	 */
-	excludedInsertions?: number
+	excludedInsertions: number | null
 }
 
 /**

package/lib/fst.ts

@@ -11,4 +11,5 @@ export * from "#fst/format"
 export * from "#fst/freshness"
 export * from "#fst/matcher"
 export * from "#fst/serialize"
+export { FST_FORMAT_VERSION } from "#fst/format"
 export * from "#fst/types"

package/lib/fts.ts

@@ -51,7 +51,7 @@ export function foldQueryText(input: string): string {
  * Only legacy bags use it.
  */
 export function aliasBagExactMatch(altNames: string | null, normalizedQuery: string, anyStrictExact: boolean): boolean {
-	if (altNames === null || altNames === "" || !normalizedQuery) return false
+	if (!altNames || altNames === "" || !normalizedQuery) return false
 
 	if (altNames.includes(ALIAS_SEPARATOR)) {
 		return altNames.split(ALIAS_SEPARATOR).some((alias) => foldQueryText(alias) === normalizedQuery)

package/lib/geonames/aliases.ts

@@ -6,7 +6,7 @@
 
 import { isOfficialLanguage } from "@mailwoman/codex/country"
 import { readUnquotedTSV } from "@mailwoman/core/fs/delimited"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { GEONAMES_ID_BASE, GEONAMES_POSTAL_ID_BASE } from "@mailwoman/core/resolver/synthetic-id-ranges"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { type PathBuilderLike, resolvePathBuilder } from "path-ts"
@@ -63,7 +63,7 @@ export interface GeonamesIngestProgress {
 	 *
 	 * It distinguishes a sparse source from aliases that the fold discarded.
 	 */
-	aliasesRefused?: number
+	aliasesRefused: number | null
 }
 
 /**
@@ -211,7 +211,7 @@ export async function ingestGeonamesAliases(
 		const file = resolvePathBuilder(geonamesDir, `${cc}.txt`)
 
 		if (!(await pathExists(file))) {
-			report({ country: cc, places: 0, skipped: true }, file)
+			report({ country: cc, places: 0, skipped: true, aliasesRefused: null }, file)
 
 			continue
 		}

package/lib/geonames/postal.ts

@@ -24,7 +24,7 @@
  */
 
 import { readUnquotedTSV } from "@mailwoman/core/fs/delimited"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { GEONAMES_POSTAL_ID_BASE } from "@mailwoman/core/resolver/synthetic-id-ranges"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { type PathBuilderLike, resolvePathBuilder } from "path-ts"

package/lib/index.ts

@@ -19,7 +19,8 @@ export type {
 	WOFDatabase,
 } from "#schema"
 
-export { WOFSQLitePlaceLookup, type RankingWeights, type WOFSQLitePlaceLookupOpts } from "#lookup"
+export { WOFSQLitePlaceLookup, type WOFSQLitePlaceLookupOpts } from "#lookup"
+export { type RankingWeights } from "#ranking-weights"
 
 export {
 	CANDIDATE_ANCESTOR_COLUMNS,
@@ -98,7 +99,7 @@ export {
 
 export { SqliteConventionSource } from "#sqlite/convention-source"
 
-export { WOFPostcodeLookup, type PostcodePlace } from "#postcode-point-lookup"
+export { WOFPostcodeLookup } from "#postcode-point-lookup"
 
 export {
 	PLACE_BBOX_TABLE,