@mailwoman/resolver-wof-sqlite 9.1.0 → 9.2.0

package/candidate/ancestors-sidecar.ts

@@ -0,0 +1,206 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pass 3b of the candidate build — the containment sidecar (closure rows + interval labels).
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import type { DatabaseClient } from "@mailwoman/core/kysley/client"
+
+import { placetypeDepth } from "../ancestry.ts"
+import {
+	CANDIDATE_ANCESTOR_COLUMNS,
+	CANDIDATE_ANCESTOR_TABLE,
+	CANDIDATE_INTERVAL_TABLE,
+	createCandidateAncestorTable,
+	createCandidateIntervalTable,
+	MAX_ANCESTOR_DEPTH,
+} from "../candidate-ancestors-schema.ts"
+import type { CandidateDatabase } from "../candidate-schema.ts"
+import type { PlaceAttrs } from "./place-attrs.ts"
+
+/**
+ * Pass 3b — the ancestors sidecar: closure rows + interval labels (candidate-ancestors-schema.ts owns the encoding
+ * decision and the DAG/absence semantics). Reads the same source `ancestors` table the region stamp reads,
+ * denormalizing each edge with the parent's name/key from `attrs`, streamed `ORDER BY id` so the clustered `(spr_id,
+ * depth)` insert is sorted — the contiguous-leaves discipline of the candidate table itself.
+ *
+ * Excluded by policy: self rows, and placetypes outside the containment ladder (continent, empire, …: `placetypeDepth`
+ * 0) — they discriminate nothing a consumer of this sidecar checks. An edge to a parent with no current `spr` row has
+ * no name to denormalize; it is dropped and counted rather than stored blind.
+ */
+export async function buildAncestorsSidecar(ctx: {
+	src: DatabaseSync
+	out: DatabaseSync
+	kdb: DatabaseClient<CandidateDatabase>
+	attrs: Map<number, PlaceAttrs>
+	ptID: (pt: string | null) => number
+	progress: (phase: string, message: string) => void
+}): Promise<{ ancestorRows: number; ancestorPlaces: number; intervalPlaces: number }> {
+	const { src, out, attrs, ptID, progress } = ctx
+
+	progress("ancestors", "building containment sidecar (closure rows + interval labels)")
+	await createCandidateAncestorTable(ctx.kdb)
+	await createCandidateIntervalTable(ctx.kdb)
+
+	const insAncestor = out.prepare(
+		`INSERT INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
+	)
+
+	// The canonical-parent forest the interval labels are computed over. One parent per place — the
+	// depth-1 edge (finest containment tier, lowest ancestor id; the `regionOf` MIN-stability
+	// convention). ALL parents stay in the closure rows; only the interval tree canonicalizes.
+	const canonicalParentOf = new Map<number, number>()
+	const childrenOf = new Map<number, number[]>()
+	const forest = new Set<number>()
+
+	let ancestorRows = 0
+	let ancestorPlaces = 0
+	let droppedParents = 0
+
+	// Per-child edge buffer; the stream below is grouped by child id, so each flush owns one place.
+	let childID = -1
+	let edges: Array<{ aid: number; apt: string }> = []
+
+	const flush = (): void => {
+		if (childID < 0 || !edges.length) return
+
+		// Deterministic nearest-first: containment depth descending, then ancestor id ascending —
+		// the FTS backend's `ancestorLineage` ordering, made stable across rebuilds.
+		edges.sort((a, b) => placetypeDepth(b.apt) - placetypeDepth(a.apt) || a.aid - b.aid)
+
+		if (edges.length > MAX_ANCESTOR_DEPTH) {
+			edges = edges.slice(0, MAX_ANCESTOR_DEPTH)
+		}
+
+		ancestorPlaces++
+
+		for (const [i, edge] of edges.entries()) {
+			const parent = attrs.get(edge.aid)!
+
+			insAncestor.run(childID, i + 1, edge.aid, ptID(edge.apt), parent.name, parent.pkey)
+
+			ancestorRows++
+		}
+
+		const canonical = edges[0]!.aid
+
+		canonicalParentOf.set(childID, canonical)
+
+		const siblings = childrenOf.get(canonical)
+
+		if (siblings) {
+			siblings.push(childID)
+		} else {
+			childrenOf.set(canonical, [childID])
+		}
+
+		forest.add(childID)
+		forest.add(canonical)
+	}
+
+	out.exec("BEGIN")
+
+	for (const r of src
+		.prepare("SELECT id, ancestor_id, ancestor_placetype FROM ancestors WHERE ancestor_id != id ORDER BY id")
+		.iterate()) {
+		const id = Number(r.id)
+
+		if (id !== childID) {
+			flush()
+			childID = id
+			edges = []
+		}
+
+		if (!attrs.has(id)) continue
+
+		const apt = String(r.ancestor_placetype ?? "")
+
+		if (placetypeDepth(apt) === 0) continue
+
+		const aid = Number(r.ancestor_id)
+
+		if (!attrs.has(aid)) {
+			droppedParents++
+
+			continue
+		}
+
+		edges.push({ aid, apt })
+	}
+
+	flush()
+	out.exec("COMMIT")
+
+	// Interval labels: pre/post-order DFS over the canonical-parent forest. Root order and child
+	// order are id-ascending so the labels are stable across rebuilds of the same source.
+	const preOf = new Map<number, number>()
+	const postOf = new Map<number, number>()
+
+	for (const kids of childrenOf.values()) {
+		// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass just built
+		kids.sort((a, b) => a - b)
+	}
+
+	const roots = [...forest].filter((id) => !canonicalParentOf.has(id))
+
+	// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass just built
+	roots.sort((a, b) => a - b)
+
+	let counter = 0
+
+	for (const root of roots) {
+		preOf.set(root, counter++)
+		const stack: Array<{ id: number; next: number }> = [{ id: root, next: 0 }]
+
+		while (stack.length) {
+			const top = stack.at(-1)!
+			const kids = childrenOf.get(top.id)
+
+			if (kids && top.next < kids.length) {
+				const kid = kids[top.next++]!
+
+				// Each child holds exactly one canonical parent, so a labeled node here means the
+				// grouping upstream broke — skip rather than corrupt the numbering.
+				if (preOf.has(kid)) continue
+
+				preOf.set(kid, counter++)
+				stack.push({ id: kid, next: 0 })
+			} else {
+				postOf.set(top.id, counter++)
+				stack.pop()
+			}
+		}
+	}
+
+	// A canonical-parent CYCLE (corrupt source ancestry) leaves its members unreachable from any
+	// root: they simply receive no label, and containment against them reads unverifiable — the
+	// absence semantics the schema module states. Counted so a jump is visible across rebuilds.
+	const cycleSkipped = forest.size - preOf.size
+
+	const insInterval = out.prepare(`INSERT INTO ${CANDIDATE_INTERVAL_TABLE} VALUES (?, ?, ?)`)
+	const labeled = [...preOf.keys()]
+
+	// oxlint-disable-next-line unicorn/no-array-sort -- sorts an array this pass just built
+	labeled.sort((a, b) => a - b)
+
+	out.exec("BEGIN")
+
+	for (const id of labeled) {
+		insInterval.run(id, preOf.get(id)!, postOf.get(id)!)
+	}
+
+	out.exec("COMMIT")
+
+	progress(
+		"ancestors",
+		`${ancestorRows.toLocaleString()} closure rows across ${ancestorPlaces.toLocaleString()} places; ` +
+			`${preOf.size.toLocaleString()} interval labels` +
+			(droppedParents ? `; ${droppedParents.toLocaleString()} edges dropped (parent has no current spr row)` : "") +
+			(cycleSkipped ? `; ${cycleSkipped.toLocaleString()} places skipped (canonical-parent cycle)` : "")
+	)
+
+	return { ancestorRows, ancestorPlaces, intervalPlaces: preOf.size }
+}

package/candidate/country-display-names.ts

@@ -0,0 +1,79 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pass 1b of the candidate build — fold ICU's country display names onto the country rows.
+ */
+
+import { enumerateCountryDisplayNames } from "@mailwoman/codex/country"
+
+import { normalizeLocalityForKey } from "../street-normalize.ts"
+import type { PlaceAttrs, StageRow } from "./place-attrs.ts"
+
+/**
+ * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).
+ *
+ * A bare `格鲁吉亚` (Georgia the country) resolved to NOTHING while `佐治亚州` (Georgia the US state) resolved correctly, and
+ * the model gave both the same wrong `locality` tag — so the tag was never the variable. Measured 2026-08-15: 140 of
+ * 237 country rows are synthetic and carry a canonical English name and nothing else; WOF holds no Chinese country
+ * names at all; and the GeoNames alias fold filters through a Latin-script regex, so neither existing source could ever
+ * supply them.
+ *
+ * `Intl.DisplayNames` already knows every one — ~280 regions, ~5,244 surfaces, from the same ICU the runtime uses for
+ * every other locale-sensitive operation. No download, no vendored corpus, no snapshot to drift.
+ *
+ * `is_primary = 0`: these are NAMES THE WORLD USES, not the country's canonical name. The display `name` stays whatever
+ * the gazetteer already had, so resolving `格鲁吉亚` answers with the Georgia country row rather than renaming it.
+ *
+ * Returns the row count so the caller can report it — a zero means ICU supplied nothing, which is a different fact from
+ * the pass not having run.
+ */
+export function stageCountryDisplayNames(ctx: {
+	attrs: Map<number, PlaceAttrs>
+	iso2ByID: Map<number, string>
+	countryPtID: number
+	stageRow: StageRow
+	tx: { exec(sql: string): void }
+}): number {
+	// One country row per ISO2. Where a code has several (historic rows surviving the is_current filter), the most
+	// populous wins — the same tiebreak the ranking uses everywhere else.
+	const countryByISO2 = new Map<string, { sid: number; a: PlaceAttrs }>()
+
+	for (const [sid, a] of ctx.attrs) {
+		if (a.ptid !== ctx.countryPtID) continue
+
+		const iso2 = ctx.iso2ByID.get(a.cid)
+
+		if (!iso2 || iso2 === "??") continue
+
+		const held = countryByISO2.get(iso2)
+
+		if (!held || a.pop > held.a.pop) {
+			countryByISO2.set(iso2, { sid, a })
+		}
+	}
+
+	let staged = 0
+
+	ctx.tx.exec("BEGIN")
+
+	for (const { iso2, name } of enumerateCountryDisplayNames()) {
+		const target = countryByISO2.get(iso2)
+
+		if (!target) continue
+
+		const k = normalizeLocalityForKey(name)
+
+		// The country's own key is already staged as its primary; INSERT OR IGNORE at materialization dedupes the
+		// rest, so this only skips the obvious self-alias.
+		if (!k || k === target.a.pkey) continue
+
+		ctx.stageRow(k, target.a, target.sid, 0)
+
+		staged++
+	}
+
+	ctx.tx.exec("COMMIT")
+
+	return staged
+}

package/candidate/name-roles.ts

@@ -0,0 +1,237 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pass 3c of the candidate build — the `name_role` detectors and the cuts they are judged by.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { isOfficialLanguage } from "@mailwoman/codex/country"
+
+import { normalizeLocalityForKey } from "../street-normalize.ts"
+import { isOwnNameVariant } from "./own-name.ts"
+import type { PlaceAttrs } from "./place-attrs.ts"
+
+/**
+ * Key-count cut for the gloss anomaly detector (#1730) — the sweep's own boundary: 4,000 places carried >= 50 keys, and
+ * a legitimate famous place at that count (New York, 176 keys) is separated by the PROMINENCE gate, never by this
+ * number alone.
+ */
+export const GLOSS_KEY_THRESHOLD = 50
+
+/**
+ * Placetypes the gloss detector never flags. A country or region legitimately carries a name in every language — that
+ * is what an exonym set IS — so key volume discriminates nothing there. The detector's population is the non-admin
+ * tail, where a place named by a common noun ("Poisson", "Sunday") accumulating 200+ translations is a
+ * machine-translated gloss set, not fame.
+ */
+export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
+	"country",
+	"dependency",
+	"disputed",
+	"empire",
+	"macroregion",
+	"region",
+	"macrocounty",
+	"county",
+])
+
+/**
+ * Pass 3c — the #1730 name-role prototype: two independent detectors over the staged rows, WRITE-ONLY in this
+ * generation (no ranking consumer; the rank penalty is its own D-rule-gated step with the `gloss_key` board as
+ * tripwire). Both stamp `is_primary = 0` rows only — a place's canonical name and the `place_abbr` region abbreviations
+ * are never a gloss or a variant.
+ *
+ * - `gloss` is ANOMALY-based, and stamps only the certain core: key volume at/over the threshold + a non-admin placetype
+ *
+ *   - NO measured prominence (population absent AND importance unmeasured). Provenance cannot separate a gloss from an
+ *     exonym — WOF imported both as `x_preferred` — and prominence is what rescues New York/Paris.
+ * - `abbr` is PROVENANCE-based — the #936 signal: a WOF `variant` name in one of the country's official languages (or
+ *   English), measured there at a 13× key-collision rate. A source without a `names` table (fixture-scale admin DBs)
+ *   skips this detector loudly.
+ *
+ * Returns the stamp counts plus the census the prototype exists to report: how much of the ≥-threshold key tail carries
+ * any role.
+ */
+export function stampNameRoles(ctx: {
+	src: DatabaseSync
+	out: DatabaseSync
+	attrs: Map<number, PlaceAttrs>
+	keyCounts: Map<number, number>
+	glossThreshold: number
+	ptcodes: Map<string, number>
+	ccodes: Map<string, number>
+	progress: (phase: string, message: string) => void
+}): { roleGloss: number; roleAbbr: number; roleVariant: number; keyTailPlaces: number; keyTailWithRole: number } {
+	const { src, out, attrs, keyCounts, glossThreshold, progress } = ctx
+	progress("roles", "stamping name roles (gloss anomaly + abbr provenance)")
+
+	const ptNameByID = new Map([...ctx.ptcodes].map(([placetype, id]) => [id, placetype]))
+	const iso2ByCID = new Map([...ctx.ccodes].map(([code, id]) => [id, code]))
+
+	let keyTailPlaces = 0
+	const glossSids: number[] = []
+
+	for (const [sid, count] of keyCounts) {
+		if (count < glossThreshold) continue
+
+		keyTailPlaces++
+		const a = attrs.get(sid)
+
+		if (!a) continue
+
+		if (GLOSS_EXCLUDED_PLACETYPES.has(ptNameByID.get(a.ptid) ?? "")) continue
+
+		if (a.pop > 0 || a.imp != null) continue
+		glossSids.push(sid)
+	}
+
+	out.exec(
+		"CREATE TEMP TABLE role_key (spr_id INTEGER NOT NULL, name_key TEXT NOT NULL, PRIMARY KEY (spr_id, name_key)) WITHOUT ROWID"
+	)
+
+	const insRoleKey = out.prepare("INSERT OR IGNORE INTO role_key VALUES (?, ?)")
+
+	// Zero abbr stamps from a skipped detector is a different fact from zero variants found.
+	const hasSourceNames =
+		src.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='names'").get() !== undefined
+
+	if (hasSourceNames) {
+		out.exec("BEGIN")
+
+		// Two provenance routes into the same stamp: WOF's abbreviation/short name KINDS arrive in the
+		// LANGUAGE column ('abbr'/'short' — 280 rows, measured 2026-08-18, Toledo's 'TO' among them) and
+		// qualify by kind alone; everything else qualifies as a variant in an official language.
+		for (const r of src
+			.prepare("SELECT id, name, language FROM names WHERE privateuse = 'variant' OR language IN ('abbr', 'short')")
+			.iterate()) {
+			const a = attrs.get(Number(r.id))
+
+			if (!a) continue
+			const language = String(r.language ?? "")
+
+			if (language !== "abbr" && language !== "short") {
+				const iso2 = iso2ByCID.get(a.cid) ?? "??"
+
+				if (language !== "eng" && !isOfficialLanguage(iso2, language)) continue
+			}
+
+			const k = normalizeLocalityForKey(String(r.name ?? ""))
+
+			if (!k || k === a.pkey) continue
+			insRoleKey.run(Number(r.id), k)
+		}
+
+		out.exec("COMMIT")
+	} else {
+		progress("roles", "source carries no `names` table — abbr detector skipped (gloss still runs)")
+	}
+
+	// Stamp order is precedence: the provenance-based abbr first, then the own-name variant verdict,
+	// then gloss fills what neither claimed.
+	const roleAbbr = Number(
+		out
+			.prepare(
+				`UPDATE cand_stage SET name_role = 'abbr'
+				 WHERE is_primary = 0 AND EXISTS (
+					SELECT 1 FROM role_key rk WHERE rk.spr_id = cand_stage.spr_id AND rk.name_key = cand_stage.name_key)`
+			)
+			.run().changes
+	)
+
+	// --- variant detector (#1882): the alias surface is the holder's OWN primary name in another
+	// 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
+	// its measured threshold). Runs BEFORE gloss on purpose: a surface that IS the place's own name
+	// is not a translation, whatever the key volume says.
+	out.exec(
+		"CREATE TEMP TABLE variant_key (spr_id INTEGER NOT NULL, name_key TEXT NOT NULL, PRIMARY KEY (spr_id, name_key)) WITHOUT ROWID"
+	)
+
+	const insVariantKey = out.prepare("INSERT OR IGNORE INTO variant_key VALUES (?, ?)")
+	let variantScanned = 0
+
+	out.exec("BEGIN")
+
+	for (const r of out
+		.prepare("SELECT DISTINCT spr_id, name_key FROM cand_stage WHERE is_primary = 0 AND name_role IS NULL")
+		.iterate()) {
+		variantScanned++
+		const a = attrs.get(Number(r.spr_id))
+
+		if (!a?.pkey) continue
+
+		if (isOwnNameVariant(String(a.pkey), String(r.name_key))) {
+			insVariantKey.run(Number(r.spr_id), String(r.name_key))
+		}
+	}
+
+	out.exec("COMMIT")
+
+	const roleVariant = Number(
+		out
+			.prepare(
+				`UPDATE cand_stage SET name_role = 'variant'
+				 WHERE is_primary = 0 AND name_role IS NULL AND EXISTS (
+					SELECT 1 FROM variant_key vk WHERE vk.spr_id = cand_stage.spr_id AND vk.name_key = cand_stage.name_key)`
+			)
+			.run().changes
+	)
+
+	out.exec("DROP TABLE variant_key")
+
+	progress(
+		"roles",
+		`variant: ${roleVariant.toLocaleString()} of ${variantScanned.toLocaleString()} unstamped alias keys are own-name variants`
+	)
+
+	out.exec("CREATE TEMP TABLE role_place (spr_id INTEGER PRIMARY KEY) WITHOUT ROWID")
+	out.exec("CREATE TEMP TABLE key_tail (spr_id INTEGER PRIMARY KEY) WITHOUT ROWID")
+	const insRolePlace = out.prepare("INSERT OR IGNORE INTO role_place VALUES (?)")
+	const insKeyTail = out.prepare("INSERT OR IGNORE INTO key_tail VALUES (?)")
+	out.exec("BEGIN")
+
+	for (const sid of glossSids) {
+		insRolePlace.run(sid)
+	}
+
+	for (const [sid, count] of keyCounts) {
+		if (count >= glossThreshold) {
+			insKeyTail.run(sid)
+		}
+	}
+
+	out.exec("COMMIT")
+
+	const roleGloss = Number(
+		out
+			.prepare(
+				`UPDATE cand_stage SET name_role = 'gloss'
+				 WHERE is_primary = 0 AND name_role IS NULL AND spr_id IN (SELECT spr_id FROM role_place)`
+			)
+			.run().changes
+	)
+
+	const keyTailWithRole = Number(
+		out
+			.prepare(
+				`SELECT count(DISTINCT spr_id) AS n FROM cand_stage
+				 WHERE name_role IS NOT NULL AND spr_id IN (SELECT spr_id FROM key_tail)`
+			)
+			.get()!["n"]
+	)
+
+	out.exec("DROP TABLE role_key")
+	out.exec("DROP TABLE role_place")
+	out.exec("DROP TABLE key_tail")
+
+	progress(
+		"roles",
+		`${roleAbbr.toLocaleString()} abbr + ${roleGloss.toLocaleString()} gloss rows stamped; ` +
+			`key tail (>= ${glossThreshold} keys): ${keyTailWithRole.toLocaleString()} of ${keyTailPlaces.toLocaleString()} places carry a role`
+	)
+
+	return { roleGloss, roleAbbr, roleVariant, keyTailPlaces, keyTailWithRole }
+}

package/candidate/own-name.ts

@@ -0,0 +1,146 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The OWN-NAME VARIANT predicate (#1882): is an alias surface the holder's own primary name in
+ *   another orthography — a romanization (`Брэст` → `brest`), a spacing/diacritic variant
+ *   (`George Town` → `georgetown`), an abbreviation expansion (`St. George's` → `Saint George's`)
+ *   — rather than a different name that merely shares the folded key?
+ *
+ *   The comparator is `levenshteinSimilarity`, NOT Jaro-Winkler: JW's common-prefix bonus scores
+ *   the load-bearing NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
+ *   (`saint george s` vs `st georges` expanded, 0.914), so no JW threshold separates them.
+ *   Measured on the #1882 census contests, edit similarity separates every case with margin:
+ *
+ *   - IN: `brest`/`brest` 1.0 · `george town`/`georgetown` 0.909 · `saint george s`/`saint georges`
+ *       0.929 · `adamovka`/`adamowka` 0.875
+ *   - OUT: `lievin`/`levin` 0.833 (Liévin FR vs Levin NZ — different places with near-identical
+ *       names; the panel's `41 Weraroa Road, Levin` row needs this side) · `chanchun`/`cancun` 0.75 ·
+ *       `augsburg`/`augusta` 0.375 · `west bay`/`west end` 0.625 · `derry`/`londonderry` 0.455
+ *       (Derry/Londonderry is a DUAL NAME, not a variant — its own follow-up on #1882)
+ *
+ *   An unhandled script (Arabic, Hebrew, CJK — the romanizer covers Cyrillic only) answers NULL,
+ *   never "different name": absence of a verdict must not stamp anything (the meaning-of-zero rule).
+ *   The #1882 census counted 396 demoted Arabic/Hebrew-primary aliases left unclassified by this.
+ */
+
+import { levenshteinSimilarity } from "@mailwoman/match/comparators"
+
+/**
+ * Edit-similarity floor for the variant verdict. The measured band: nearest admitted pair 0.875
+ * (`adamovka`/`adamowka`), nearest refused pair 0.833 (`lievin`/`levin`).
+ */
+export const VARIANT_SIMILARITY_MIN = 0.85
+
+/**
+ * BGN/PCGN-flavored Cyrillic romanization, folded to the name-key alphabet. Digraph outputs (zh, kh, ts, ch, sh, shch,
+ * yu, ya) match the dominant transliteration conventions the gazetteer's Latin aliases actually use; the `w`/`v` and
+ * `kh`/`h` style variance between systems is what the edit-similarity threshold absorbs.
+ */
+const CYRILLIC_TO_LATIN: Record<string, string> = {
+	а: "a",
+	б: "b",
+	в: "v",
+	г: "g",
+	д: "d",
+	е: "e",
+	ё: "e",
+	ж: "zh",
+	з: "z",
+	и: "i",
+	і: "i",
+	й: "i",
+	к: "k",
+	л: "l",
+	м: "m",
+	н: "n",
+	о: "o",
+	п: "p",
+	р: "r",
+	с: "s",
+	т: "t",
+	у: "u",
+	ў: "u",
+	ф: "f",
+	х: "kh",
+	ц: "ts",
+	ч: "ch",
+	ш: "sh",
+	щ: "shch",
+	ъ: "",
+	ы: "y",
+	ь: "",
+	э: "e",
+	ю: "yu",
+	я: "ya",
+	ґ: "g",
+	є: "e",
+	ї: "i",
+}
+
+/**
+ * Leading-word abbreviations expanded BEFORE comparison, so `st georges` meets `saint george s` inside the edit
+ * threshold. Whole-word only — `st` inside `stanley` never expands.
+ */
+const NAME_ABBREVIATIONS: ReadonlyArray<[RegExp, string]> = [
+	[/\bst\b/g, "saint"],
+	[/\bste\b/g, "sainte"],
+	[/\bmt\b/g, "mount"],
+	[/\bft\b/g, "fort"],
+]
+
+/**
+ * Expand the whole-word abbreviations above.
+ */
+export function expandNameAbbreviations(key: string): string {
+	let out = key
+
+	for (const [pattern, replacement] of NAME_ABBREVIATIONS) {
+		out = out.replaceAll(pattern, replacement)
+	}
+
+	return out
+}
+
+/**
+ * Romanize a folded name key to the a–z0–9/space alphabet. `null` when characters outside the covered scripts remain —
+ * an unhandled script is NO VERDICT, not a mismatch.
+ */
+export function romanizeNameKey(key: string): string | null {
+	let out = ""
+
+	for (const ch of key.toLowerCase()) {
+		out += CYRILLIC_TO_LATIN[ch] ?? ch
+	}
+
+	out = out
+		.normalize("NFD")
+		.replaceAll(/[̀-ͯ]/g, "")
+		.replaceAll(/\s+/g, " ")
+		.trim()
+
+	return /^[a-z0-9 ]*$/.test(out) ? out : null
+}
+
+/**
+ * Edit similarity between a holder's primary name key and one of its alias keys, both romanized and
+ * abbreviation-expanded. `null` when either side's script is uncovered.
+ */
+export function ownNameSimilarity(primaryKey: string, aliasKey: string): number | null {
+	const primary = romanizeNameKey(primaryKey)
+	const alias = romanizeNameKey(aliasKey)
+
+	if (primary == null || alias == null || !primary || !alias) return null
+
+	return levenshteinSimilarity(expandNameAbbreviations(primary), expandNameAbbreviations(alias))
+}
+
+/**
+ * The stamp predicate: the alias surface is the holder's own name in another orthography.
+ */
+export function isOwnNameVariant(primaryKey: string, aliasKey: string): boolean {
+	const similarity = ownNameSimilarity(primaryKey, aliasKey)
+
+	return similarity != null && similarity >= VARIANT_SIMILARITY_MIN
+}