@mailwoman/resolver-wof-sqlite 9.4.0 → 10.0.0

package/lib/address/index.ts

@@ -4,6 +4,6 @@
  * @author Teffen Ellis, et al.
  */
 
-export * from "#address/point"
-export * from "#address/point-interpolation"
-export * from "#address/point-schema"
+export * from "#address/point/index"
+export * from "#address/point/interpolation"
+export * from "#address/point/schema"

package/lib/address/{point.ts → point/index.ts}

@@ -18,7 +18,7 @@
 import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { AddressPointDatabase, AddressPointTable } from "#address/point-schema"
+import type { AddressPointDatabase, AddressPointTable } from "#address/point/schema"
 import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
 import {
 	normalizeHouseNumberForKey,

package/lib/address/{point-interpolation.ts → point/interpolation.ts}

@@ -37,7 +37,7 @@ import type { InterpolationLookup } from "@mailwoman/core/resolver"
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { AddressPointDatabase } from "#address/point-schema"
+import type { AddressPointDatabase } from "#address/point/schema"
 import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "#interpolation"
 import { hasTable, prepareAll, type PreparedAll } from "#sqlite-utils"
 import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } from "#street/normalize"

package/lib/ancestry/backfill.ts

@@ -45,10 +45,10 @@
  *   nothing.
  */
 
-import { readDirectoryEntries } from "@mailwoman/core/fs/readers"
 import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { join, resolvePath, type PathBuilderLike } from "path-ts"
+import { Globerator } from "spliterator/node/fs"
 
 import type { WOFDatabase } from "#schema"
 
@@ -88,7 +88,9 @@ export async function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promis
 		let names: string[]
 
 		try {
-			names = (await readDirectoryEntries(dir)).filter((e) => e.isDirectory()).map((e) => e.name)
+			names = (await Globerator.from("*", { cwd: dir, withFileTypes: true, onlyFiles: false }).toArray())
+				.filter((entry) => entry.isDirectory())
+				.map((entry) => entry.name)
 		} catch {
 			return
 		}

package/lib/{build-candidate.ts → build/candidate.ts}

@@ -44,20 +44,20 @@ import { pathExists } from "@mailwoman/core/fs/readers"
 import { removePath } from "@mailwoman/core/fs/writers"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { createCandidateFTS } from "#candidate-fts"
-import { IMPORTANCE_JOIN_RADIUS_KM, loadImportanceIndex } from "#candidate-importance"
-import {
-	CANDIDATE_COLUMNS,
-	createCandidateStagingTables,
-	createCandidateTable,
-	type CandidateDatabase,
-} from "#candidate-schema"
 import { explodeAliasBags } from "#candidate/alias-bags"
-import { buildAncestorsSidecar } from "#candidate/ancestors-sidecar"
+import { buildAncestorsSidecar } from "#candidate/ancestors/sidecar"
 import { stageCountryDisplayNames } from "#candidate/country-display-names"
 import { foldExtract } from "#candidate/extract-fold"
+import { createCandidateFTS } from "#candidate/fts"
+import { IMPORTANCE_JOIN_RADIUS_KM, loadImportanceIndex } from "#candidate/importance"
 import { GLOSS_KEY_THRESHOLD, stampNameRoles } from "#candidate/name-roles"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import {
+	CANDIDATE_COLUMNS,
+	createCandidateStagingTables,
+	createCandidateTable,
+	type CandidateDatabase,
+} from "#candidate/schema"
 import { createCapitalTable } from "#capital-schema"
 import type { CapitalPoint } from "#capitals"
 import { resurrectCurrencyHoles } from "#currency-backfill"
@@ -153,6 +153,12 @@ export interface BuildCandidateResult {
 	places: number
 	primaries: number
 	aliases: number
+	/**
+	 * Region aliases refused because another same-country region holds the name as its official name (three pairs in the
+	 * admin artifact: `新竹市`, `嘉義市`, `충청남도`). Zero on a source without a `names` table means the rule had nothing to read,
+	 * not that no pair exists.
+	 */
+	regionOfficialRefused: number
 	abbrevs: number
 	postcodes: number
 	/**
@@ -225,7 +231,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 
 	await createCandidateStagingTables(kdb)
 
-	// --- compact code maps (country/placetype → small int, shrinks the clustered key). The ids are
+	// Build compact country and placetype code maps for clustered keys.
 	// assigned here; the rows are bulk-inserted via kdb once the passes have discovered every code. ---
 	const ccodes = new Map<string, number>()
 	const ptcodes = new Map<string, number>()
@@ -254,7 +260,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		return id
 	}
 
-	// --- importance source (#28): loaded BEFORE pass 1, which is the only pass that sees a place's
+	// Load the importance source before the only pass that sees each place.
 	// name/country/placetype/centroid together. Absent → every row's `importance` stays NULL. ---
 	let importance: ReturnType<typeof loadImportanceIndex> | undefined
 
@@ -273,7 +279,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("importance", "no score source given — `importance` will be NULL on every row")
 	}
 
-	// --- region_id per place (its region-tier ancestor) for same-name disambiguation ---
+	// Derive each place's region ancestor for same-name disambiguation.
 	progress("region", "loading region ancestry")
 	const regionOf = new Map<number, number>()
 	let multiRegion = 0
@@ -309,7 +315,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	// the column COUNT can't drift; the positional run() args below MUST stay in CANDIDATE_COLUMNS order.
 	const insStage = kdb.prepare(`INSERT INTO cand_stage VALUES (${CANDIDATE_COLUMNS.map(() => "?").join(", ")})`)
 
-	// --- pass 1: primaries (and the per-place attrs the alias/abbrev passes reuse) ---
+	// Stage primary names and attributes reused by later alias passes.
 	progress("primaries", "indexing place names")
 	const attrs = new Map<number, PlaceAttrs>()
 	let nPrim = 0
@@ -418,7 +424,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		)
 	}
 
-	// --- pass 1b: country surfaces across scripts (#1678 thread 1) — see stageCountryDisplayNames ---
+	// Stage country display names across scripts.
 	// Never a silent zero: a runtime whose ICU lacks these locales degrades to fewer surfaces, and the count is how a
 	// reader tells that apart from the pass not having run.
 	progress(
@@ -432,7 +438,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		}).toLocaleString()} country surfaces`
 	)
 
-	// --- pass 1c: cross-source currency backfill (#1737 — resurrectCurrencyHoles owns the checks). Runs BEFORE
+	// Backfill cross-source currency before later candidate passes.
 	// the alias pass so a resurrected place's alt names explode like any primary's. ---
 	if (opts.currencyBackfill) {
 		const nBackfill = await resurrectCurrencyHoles({
@@ -457,12 +463,23 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("currency-backfill", "not configured — deprecated-no-successor holes stay dead (#1737)")
 	}
 
-	// --- pass 2: distinct normalized aliases from place_search.alt_names (explodeAliasBags owns the loop) ---
+	// Stage distinct normalized aliases from alternate names.
 	progress("aliases", "exploding alias bags")
-	const { nAlias, keyCounts } = explodeAliasBags(src, kdb, attrs, stageRow)
-	progress("aliases", `${nAlias.toLocaleString()} aliases`)
 
-	// --- pass 3: region abbreviations (place_abbr) ---
+	const { nAlias, keyCounts, regionOfficialRefused } = explodeAliasBags(src, kdb, attrs, stageRow, {
+		regionPlacetypeID: ptID("region"),
+		ccID,
+	})
+
+	progress(
+		"aliases",
+		`${nAlias.toLocaleString()} aliases` +
+			(regionOfficialRefused
+				? `; ${regionOfficialRefused.toLocaleString()} region aliases refused as another region's official name`
+				: "")
+	)
+
+	// Stage region abbreviations.
 	let nAbbr = 0
 	kdb.exec("BEGIN")
 
@@ -481,7 +498,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	kdb.exec("COMMIT")
 	progress("abbrevs", `${nAbbr.toLocaleString()} abbrevs`)
 
-	// --- pass 3b: name roles (#1730 prototype — stampNameRoles owns the detectors) ---
+	// Stamp each name's semantic role.
 	// Independent of the sidecar below: this writes `cand_stage.name_role`, that writes the ancestor and
 	// interval tables, and neither reads the other's output. Ordered by label only.
 	const roles = stampNameRoles({
@@ -495,10 +512,10 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress,
 	})
 
-	// --- pass 3c: the ancestors sidecar (candidate-ancestors-schema.ts owns the encoding decision) ---
+	// Stage the encoded ancestors sidecar.
 	const sidecar = await buildAncestorsSidecar({ src, out: kdb, attrs, ptID, progress })
 
-	// --- pass 4 + 4b: postcode and locality extracts (foldExtract owns the per-extract loop) ---
+	// Fold postcode and locality extracts into candidate records.
 	let nPostcode = 0
 	let nPostcodeAlias = 0
 
@@ -552,7 +569,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		)
 	}
 
-	// --- code dictionaries: typed batch inserts via kdb (a few hundred rows — Kysely is clean here) ---
+	// Insert the small typed code dictionaries through Kysely.
 	if (ccodes.size) {
 		await kdb
 			.insertInto("country_codes")
@@ -567,7 +584,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			.execute()
 	}
 
-	// --- capital-status reference (#1880's distribution home) — cold, small (~3.7k rows), typed ---
+	// Insert the small typed capital-status reference table.
 	if (opts.capitals?.length) {
 		await createCapitalTable<CandidateDatabase>(kdb)
 
@@ -587,7 +604,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("capitals", `${opts.capitals.length.toLocaleString()} capital-reference rows carried in-artifact`)
 	}
 
-	// --- materialize the clustered WITHOUT ROWID table (sorted insert → contiguous leaves) ---
+	// Materialize the clustered WITHOUT ROWID table in sorted order.
 	progress("cluster", "building clustered candidate table + VACUUM")
 	// Column list + clustered-key order are sourced from CANDIDATE_COLUMNS (the first 6 ARE the PRIMARY
 	// KEY) so the SELECT, the ORDER BY, and the table can't drift. The table comes from the shared
@@ -620,6 +637,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		places: attrs.size,
 		primaries: nPrim,
 		aliases: nAlias,
+		regionOfficialRefused,
 		abbrevs: nAbbr,
 		postcodes: nPostcode,
 		postcodeAliases: nPostcodeAlias,

package/lib/candidate/alias-bags.ts

@@ -6,33 +6,83 @@
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import type { CandidateDatabase } from "#candidate-schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import { ALIAS_SEPARATOR } from "#fts/index"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
+/**
+ * The official name of every current region, keyed `${country id}\0${name key}` → region id, from the source `names`
+ * table's `official` bit. Empty when the source carries no `names` table (a fixture, or an extract shape).
+ *
+ * This is the positive evidence behind the one alias refusal below: a name is refused from a region's bag ONLY when
+ * another region of the same country holds it as its official name. Three such pairs exist in the admin artifact —
+ * `新竹市` on Hsinchu County (the city's official name), `嘉義市` on Chiayi County, `충청남도` on Sejong — and each let the more
+ * populous holder of the variant outrank the place the name officially is, so a `新竹市` region node resolved the county
+ * and every district scoped to the city contradicted it.
+ */
+function officialNameHoldersByRegion(
+	src: DatabaseClient<WOFDatabase>,
+	ccID: (code: string | null) => number
+): Map<string, number> {
+	const keys = new Map<string, number>()
+
+	if (!tableExists(src, "names")) return keys
+
+	for (const r of src
+		.prepare(
+			`SELECT n.id AS id, n.name AS name, s.country AS country
+			 FROM names n JOIN spr s ON s.id = n.id
+			 WHERE s.placetype = 'region' AND s.is_current != 0 AND s.is_deprecated = 0 AND n.official = 1`
+		)
+		.iterate()) {
+		const k = normalizeLocalityForKey(String(r.name ?? ""))
+
+		if (k) {
+			keys.set(`${ccID(r.country as string | null)}\0${k}`, Number(r.id))
+		}
+	}
+
+	return keys
+}
+
 /**
  * Pass 2 — explode each place's `place_search.alt_names` bag into distinct-key alias rows (`is_primary = 0`), and count
  * each place's distinct staged keys (primary included) — the gloss detector's key-count signal (#1730).
+ *
+ * With `regionPlacetypeID` and `ccID` given, a REGION's alias that is another same-country region's official name is
+ * refused and counted rather than staged (see {@link officialNameHoldersByRegion}); without them the pass stages every
+ * alias.
  */
 export function explodeAliasBags(
 	src: DatabaseClient<WOFDatabase>,
 	out: DatabaseClient<CandidateDatabase>,
 	attrs: Map<number, PlaceAttrs>,
-	stageRow: StageRow
-): { nAlias: number; keyCounts: Map<number, number> } {
+	stageRow: StageRow,
+	opts: { regionPlacetypeID?: number; ccID?: (code: string | null) => number } = {}
+): { nAlias: number; keyCounts: Map<number, number>; regionOfficialRefused: number } {
 	let nAlias = 0
+	let regionOfficialRefused = 0
 	const keyCounts = new Map<number, number>()
+
+	const official =
+		typeof opts.regionPlacetypeID === "number" && opts.ccID
+			? officialNameHoldersByRegion(src, opts.ccID)
+			: new Map<string, number>()
+
 	out.exec("BEGIN")
 
 	for (const r of src.prepare("SELECT wof_id, alt_names FROM place_search").iterate()) {
-		const a = attrs.get(Number(r.wof_id))
+		const id = Number(r.wof_id)
+		const a = attrs.get(id)
 		const alt = r.alt_names as string | null
 
 		if (!a || !alt) continue
 		const seen = new Set<string>([a.pkey])
+		const isRegion = a.ptid === opts.regionPlacetypeID
 
 		// The writer space-pads each separator and appends a trailing one, so every piece arrives with
 		// surrounding whitespace and the last one is empty. `normalizeLocalityForKey` folds both away,
@@ -42,15 +92,26 @@ export function explodeAliasBags(
 
 			if (!k || seen.has(k)) continue
 			seen.add(k)
-			stageRow(k, a, Number(r.wof_id), 0)
+
+			if (isRegion) {
+				const holder = official.get(`${a.cid}\0${k}`)
+
+				if (typeof holder === "number" && holder !== id) {
+					regionOfficialRefused++
+
+					continue
+				}
+			}
+
+			stageRow(k, a, id, 0)
 
 			nAlias++
 		}
 
-		keyCounts.set(Number(r.wof_id), seen.size)
+		keyCounts.set(id, seen.size)
 	}
 
 	out.exec("COMMIT")
 
-	return { nAlias, keyCounts }
+	return { nAlias, keyCounts, regionOfficialRefused }
 }

package/lib/{candidate-ancestors-schema.ts → candidate/ancestors/schema.ts}

@@ -59,7 +59,7 @@ import { sql, type Kysely } from "kysely"
 // Type-only and circular on purpose (candidate-schema extends CandidateAncestorsDatabase): Kysely's
 // DB parameter is invariant, so the DDL functions must take the FULL database type their caller
 // holds. Erased at runtime.
-import type { CandidateDatabase } from "#candidate-schema"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { NameKey } from "#street/normalize"
 
 /**

package/lib/candidate/{ancestors-sidecar.ts → ancestors/sidecar.ts}

@@ -15,9 +15,9 @@ import {
 	createCandidateAncestorTable,
 	createCandidateIntervalTable,
 	MAX_ANCESTOR_DEPTH,
-} from "#candidate-ancestors-schema"
-import type { CandidateDatabase } from "#candidate-schema"
+} from "#candidate/ancestors/schema"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 
 /**

package/lib/candidate/extract-fold.ts

@@ -8,9 +8,9 @@
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate-ancestors-schema"
-import type { CandidateDatabase } from "#candidate-schema"
+import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate/ancestors/schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
@@ -172,7 +172,7 @@ export function foldExtract(ctx: {
 
 	out.exec("COMMIT")
 
-	// --- pass 4b: postcode ALIAS names (#1495) ---
+	// Fold postcode aliases into the staged candidate names.
 	//
 	// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
 	// the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything

package/lib/{candidate-importance.ts → candidate/importance.ts}

@@ -44,7 +44,7 @@
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { CandidateDatabase } from "#candidate-schema"
+import type { CandidateDatabase } from "#candidate/schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**

package/lib/{candidate-lookup.ts → candidate/lookup.ts}

@@ -23,12 +23,8 @@
  *   `bbox` field on {@link FindPlaceQuery}).
  */
 
-import {
-	expandPlacetypeFilter,
-	type Ancestor,
-	type GazetteerArtifactCoverage,
-	referentialFromPopulation,
-} from "@mailwoman/core/resolver"
+import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
+import { type Ancestor, type GazetteerArtifactCoverage, referentialFromPopulation } from "@mailwoman/core/resolver"
 import { allRows } from "@mailwoman/core/utils"
 import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators"
 import { partitionByContainment } from "@mailwoman/resolver"
@@ -42,11 +38,11 @@ import {
 	intervalContains,
 	type CandidateAncestorTable,
 	type IntervalLabel,
-} from "#candidate-ancestors-schema"
-import { CANDIDATE_FTS_TABLE } from "#candidate-fts"
-import type { CandidateDatabase, CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "#candidate-schema"
+} from "#candidate/ancestors/schema"
+import { CANDIDATE_FTS_TABLE } from "#candidate/fts"
+import type { CandidateDatabase, CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "#candidate/schema"
 import { readGazetteerCoverageManifest } from "#coverage-manifest-schema"
-import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "#postal/city-candidate-schema"
+import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "#postal/city/candidate-schema"
 import { rankByPrimaryPreference, type RankedRow, RERANK_FETCH } from "#primary-preference"
 import { applyProximityRerank } from "#proximity-rerank"
 import { REGION_CLASS_PLACETYPES, regionQualifierProbeKeys } from "#region-keys"

package/lib/candidate/name-roles.ts

@@ -9,9 +9,9 @@ import { isOfficialLanguage } from "@mailwoman/codex/country"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import type { CandidateDatabase } from "#candidate-schema"
 import { isOwnNameVariant } from "#candidate/own-name"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
@@ -141,7 +141,7 @@ export function stampNameRoles(ctx: {
 			.run().changes
 	)
 
-	// --- variant detector (#1882): the alias surface is the holder's OWN primary name in another
+	// Detect aliases that are the holder's own primary name in another variant.
 	// orthography — romanization, spacing/diacritic variant, or abbreviation expansion. The verdict
 	// is per (alias key, primary key) pair, so it runs in JS over the still-unstamped alias rows;
 	// an uncovered script answers no-verdict and stamps nothing (own-name.ts owns the predicate and

package/lib/{candidate-schema.ts → candidate/schema.ts}

@@ -17,7 +17,7 @@
 
 import { sql, type Kysely } from "kysely"
 
-import type { CandidateAncestorsDatabase } from "#candidate-ancestors-schema"
+import type { CandidateAncestorsDatabase } from "#candidate/ancestors/schema"
 import type { CapitalTable } from "#capital-schema"
 import type { NameKey } from "#street/normalize"
 

package/lib/currency-backfill.ts

@@ -16,9 +16,9 @@ import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { resolvePath } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
-import type { loadImportanceIndex } from "#candidate-importance"
-import type { CandidateDatabase } from "#candidate-schema"
+import type { loadImportanceIndex } from "#candidate/importance"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 

package/lib/fst/deserialize-web.ts

@@ -67,7 +67,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	let pos = HEADER_SIZE
 
-	// --- String table ---
+	// Decode the interned string table.
 	const strOffsets = new Uint32Array(stringCount + 1)
 
 	for (let i = 0; i <= stringCount; i++) {
@@ -86,7 +86,7 @@ export function deserializeFSTWeb(input: ArrayBuffer | Uint8Array): FSTMatcher {
 
 	pos += stringBytes
 
-	// --- State table ---
+	// 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.
 	const placeEntrySize = isSplit ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE

package/lib/fst/serialize.ts

@@ -77,7 +77,7 @@ for (let i = 0; i < PLACETYPE_ORDER.length; i++) {
 export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): Buffer {
 	const nodes = matcher.toNodes() as FSTNode[]
 
-	// --- String interning ---
+	// Intern state-edge strings before serializing their table.
 	const stringMap = new Map<string, number>()
 	const strings: string[] = []
 
@@ -106,7 +106,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	const encodedStrings = strings.map((s) => Buffer.from(s, "utf8"))
 	const stringBytes = encodedStrings.reduce((sum, b) => sum + b.length, 0)
 
-	// --- Counts ---
+	// Count each serialized record class.
 	let totalEdges = 0
 	let totalPlaces = 0
 
@@ -115,7 +115,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 		totalPlaces += node.places.length
 	}
 
-	// --- Allocate ---
+	// Allocate the complete binary buffer.
 	const stringTableSize = (strings.length + 1) * 4 + stringBytes
 	const stateTableSize = nodes.length * WIDE_STATE_ENTRY_SIZE
 	const edgeTableSize = totalEdges * EDGE_ENTRY_SIZE
@@ -127,7 +127,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	const buf = Buffer.alloc(totalSize)
 	let pos = 0
 
-	// --- Header ---
+	// Read the versioned binary 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.
@@ -151,7 +151,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 	buf.writeUInt32LE(provenanceJson ? binarySize : 0, pos)
 	pos += 4
 
-	// --- String table ---
+	// Read the interned string table.
 	let strOffset = 0
 
 	for (const encoded of encodedStrings) {
@@ -170,7 +170,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 		pos += encoded.length
 	}
 
-	// --- State, edge, and place tables ---
+	// Read state, edge, and place tables.
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateTableSize
 	const placeTableStart = edgeTableStart + edgeTableSize
@@ -234,7 +234,7 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 }
 
 export function deserializeFST(buf: Buffer): FSTMatcher {
-	// --- Header ---
+	// Verify the versioned binary header.
 	if (buf.length < HEADER_SIZE) throw new Error("FST buffer too small for header")
 
 	if (!buf.subarray(0, 4).equals(MAGIC)) throw new Error("FST magic mismatch")
@@ -257,7 +257,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	let pos = HEADER_SIZE
 
-	// --- String table ---
+	// Verify string-table offsets and contents.
 	const strOffsets = new Uint32Array(stringCount + 1)
 
 	for (let i = 0; i <= stringCount; i++) {
@@ -276,7 +276,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	pos += stringBytes
 
-	// --- State table ---
+	// Verify state-table offsets and 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.
 	const placeEntrySize = version >= VERSION_TWO_SCORE_SPLIT ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE

package/lib/geonames/aliases.ts

@@ -26,19 +26,13 @@
 
 import { isOfficialLanguage } from "@mailwoman/codex/country"
 import { pathExists } from "@mailwoman/core/fs/readers"
+import { GEONAMES_ID_BASE, GEONAMES_POSTAL_ID_BASE } from "@mailwoman/core/resolver/synthetic-id-ranges"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { join, type PathBuilderLike } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
-import { GEONAMES_POSTAL_ID_BASE } from "#geonames/postal"
 import type { WOFDatabase } from "#schema"
 
-/**
- * Synthetic id base for GeoNames-sourced rows (#743/#193) — above Overture's 8e12 so the three sources (WOF real ids,
- * Overture, GeoNames) never collide in a combined DB.
- */
-export const GEONAMES_ID_BASE = 9_000_000_000_000
-
 /**
  * The four tables the alias fold writes into the range it owns. The purge and the ingest must agree on this list — a
  * table written but not purged is exactly the #1514 defect.

package/lib/geonames/postal.ts

@@ -35,6 +35,7 @@
  */
 
 import { pathExists } from "@mailwoman/core/fs/readers"
+import { GEONAMES_POSTAL_ID_BASE } from "@mailwoman/core/resolver/synthetic-id-ranges"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { join, type PathBuilderLike } from "path-ts"
 import { TSVSpliterator } from "spliterator"
@@ -47,13 +48,6 @@ import type { WOFDatabase } from "#schema"
  */
 const GEONAMES_POSTAL_COLUMNS = 11
 
-/**
- * Synthetic id base for GeoNames-POSTAL rows — its own namespace above the alias fold's {@link GEONAMES_ID_BASE} (9e12)
- * allocation so all four sources (WOF, Overture, GeoNames-alias, GeoNames-postal) coexist collision-free in a combined
- * DB.
- */
-export const GEONAMES_POSTAL_ID_BASE = 9_500_000_000_000
-
 /**
  * The #920 name law: reduce a postcode to the sanitized-query token shape — strip every non-letter/number — so the
  * stored name matches what `sanitizeFTSQuery` produces from the parsed postcode token. `"110 00"` → `"11000"`,