@mailwoman/resolver-wof-sqlite 7.2.0 → 7.2.1

package/coincident-roles.ts

@@ -0,0 +1,240 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
+ *   unified gazetteer.
+ *
+ *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
+ *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
+ *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
+ *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
+ *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
+ *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
+ *   distance math.
+ *
+ *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
+ *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
+ *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
+ *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
+ *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
+ *   filter.
+ *
+ *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
+ *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
+ *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
+ *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
+ *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
+ *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
+ *   never enters the resolver hot path.
+ *
+ *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
+ *   uniform (see #405). It's a coarse classification, not critical.
+ *
+ *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). Run incrementally
+ *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
+ *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { haversineKm } from "@mailwoman/spatial"
+
+export const COINCIDENT_ROLES_TABLE = "coincident_roles"
+
+/** A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`. */
+export interface CoincidentRole {
+	localityID: number
+	relationshipType: "city-state" | "capital-seat" | "consolidated-county"
+	adminPlacetype: string
+	distanceKm: number
+	population: number
+}
+
+export interface BuildCoincidentRolesOpts {
+	/** Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent). */
+	drop?: boolean
+	/**
+	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`. Default 0.15.
+	 */
+	toleranceFraction?: number
+	/** Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12. */
+	minToleranceKm?: number
+	/**
+	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only). Default 2.
+	 */
+	cityStateMaxKm?: number
+	onProgress?: (phase: string, detail?: string) => void
+}
+
+export interface BuildCoincidentRolesResult {
+	created: boolean
+	rowCount: number
+	byCountry: Record<string, number>
+	durationMs: number
+}
+
+interface CandidateRow {
+	admin_id: number
+	admin_placetype: string
+	country: string
+	locality_id: number
+	rlat: number
+	rlon: number
+	llat: number
+	llon: number
+	min_latitude: number
+	min_longitude: number
+	max_latitude: number
+	max_longitude: number
+	pop: number
+}
+
+function tableExists(db: DatabaseSync, name: string): boolean {
+	return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?").get(name)
+}
+
+/**
+ * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
+ * touches `spr`/`names`/`ancestors`. Idempotent.
+ */
+export function buildCoincidentRoles(
+	db: DatabaseSync,
+	opts: BuildCoincidentRolesOpts = {}
+): BuildCoincidentRolesResult {
+	const start = Date.now()
+	const drop = opts.drop ?? true
+	const toleranceFraction = opts.toleranceFraction ?? 0.15
+	const minToleranceKm = opts.minToleranceKm ?? 12
+	const cityStateMaxKm = opts.cityStateMaxKm ?? 2
+	const onProgress = opts.onProgress ?? (() => {})
+
+	if (tableExists(db, COINCIDENT_ROLES_TABLE) && drop) {
+		onProgress("dropping", COINCIDENT_ROLES_TABLE)
+		db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`)
+	}
+	onProgress("creating", COINCIDENT_ROLES_TABLE)
+	// Raw DDL by design: this is a sync builder consumed by a sync CLI (build-coincident-roles-cli) and
+	// 6 sync unit tests, so routing one table through async Kysely would cascade async through all of
+	// them for no real gain. See AGENTS.md "Database / inline SQL". (The SELECT + INSERT loop below are
+	// likewise the raw hot path.)
+	db.exec(`
+		CREATE TABLE IF NOT EXISTS ${COINCIDENT_ROLES_TABLE} (
+			admin_id INTEGER NOT NULL,
+			locality_id INTEGER NOT NULL,
+			relationship_type TEXT NOT NULL,
+			admin_placetype TEXT NOT NULL,
+			distance_km REAL NOT NULL,
+			locality_population INTEGER NOT NULL DEFAULT 0,
+			PRIMARY KEY (admin_id, locality_id)
+		)
+	`)
+
+	onProgress("scanning")
+	// Admin (region/county tier) ⋈ same-name DESCENDANT locality. `place_population` is optional (LEFT
+	// JOIN → 0 when absent). The relative-tolerance filter + relationship classification happen in JS so
+	// the SQL stays a plain join. `spr` exposes the bbox columns we need for the diagonal.
+	const candidates = db
+		.prepare(
+			`SELECT r.id AS admin_id, r.placetype AS admin_placetype, r.country AS country, l.id AS locality_id,
+				r.latitude AS rlat, r.longitude AS rlon, l.latitude AS llat, l.longitude AS llon,
+				r.min_latitude, r.min_longitude, r.max_latitude, r.max_longitude,
+				COALESCE(p.population, 0) AS pop
+			FROM spr r
+			JOIN spr l ON lower(l.name) = lower(r.name) AND l.placetype = 'locality'
+				AND l.is_current != 0 AND l.is_deprecated = 0
+			JOIN ${"ancestors"} a ON a.id = l.id AND a.ancestor_id = r.id
+			LEFT JOIN place_population p ON p.id = l.id
+			WHERE r.placetype = 'region'
+				AND r.is_current != 0 AND r.is_deprecated = 0`
+		)
+		.all() as unknown as CandidateRow[]
+
+	onProgress("filtering", `${candidates.length} candidates`)
+	const insert = db.prepare(
+		`INSERT OR REPLACE INTO ${COINCIDENT_ROLES_TABLE}
+			(admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population)
+			VALUES (?, ?, ?, ?, ?, ?)`
+	)
+	const byCountry: Record<string, number> = {}
+	let rowCount = 0
+	db.exec("BEGIN")
+
+	try {
+		for (const c of candidates) {
+			const dist = haversineKm(c.rlat, c.rlon, c.llat, c.llon)
+			const diag = haversineKm(c.min_latitude, c.min_longitude, c.max_latitude, c.max_longitude)
+			const tolerance = Math.max(toleranceFraction * diag, minToleranceKm)
+
+			if (dist > tolerance) continue
+			// v1 is region-tier only: a place is a `city-state` when its centroid coincides with the
+			// region's (Berlin/Hamburg), else `capital-seat` (a region named after its principal city, e.g.
+			// Milano province → Milano comune). `consolidated-county` is reserved for a future county-tier
+			// pass (US SF/Denver) — excluded from v1 because county-tier same-name coincidences are
+			// dominated by French cantons / JP counties that don't hit the parser-drops-locality failure.
+			const relationshipType = dist <= cityStateMaxKm ? "city-state" : "capital-seat"
+			insert.run(c.admin_id, c.locality_id, relationshipType, c.admin_placetype, dist, c.pop)
+			rowCount++
+			byCountry[c.country] = (byCountry[c.country] ?? 0) + 1
+		}
+		db.exec("COMMIT")
+	} catch (err) {
+		db.exec("ROLLBACK")
+		throw err
+	}
+	db.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON ${COINCIDENT_ROLES_TABLE} (admin_id)`)
+
+	onProgress("done", `${rowCount} coincident-role rows`)
+
+	return { created: true, rowCount, byCountry, durationMs: Date.now() - start }
+}
+
+/** True iff the relation table exists. Used by the resolver to decide whether completion can run. */
+export function coincidentRolesExists(db: DatabaseSync): boolean {
+	return tableExists(db, COINCIDENT_ROLES_TABLE)
+}
+
+/**
+ * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each admin may map to
+ * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
+ * map when the table is absent.
+ */
+export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRole[]> {
+	const map = new Map<number, CoincidentRole[]>()
+
+	if (!coincidentRolesExists(db)) return map
+	const rows = db
+		.prepare(
+			`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
+			FROM ${COINCIDENT_ROLES_TABLE}`
+		)
+		.all() as unknown as Array<{
+		admin_id: number
+		locality_id: number
+		relationship_type: CoincidentRole["relationshipType"]
+		admin_placetype: string
+		distance_km: number
+		locality_population: number
+	}>
+
+	for (const r of rows) {
+		const entry: CoincidentRole = {
+			localityID: r.locality_id,
+			relationshipType: r.relationship_type,
+			adminPlacetype: r.admin_placetype,
+			distanceKm: r.distance_km,
+			population: r.locality_population,
+		}
+		const list = map.get(r.admin_id)
+
+		if (list) {
+			list.push(entry)
+		} else {
+			map.set(r.admin_id, [entry])
+		}
+	}
+
+	return map
+}

package/convention.ts

@@ -0,0 +1,152 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
+ *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
+ *
+ *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
+ *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
+ *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
+ *   in `candidateStrategies`, first to return candidates wins.
+ *
+ *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
+ *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
+ *   name.
+ *
+ *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
+ *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
+ *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
+ *   source).
+ */
+
+import type { FindPlaceQuery, PlaceCandidate } from "./types.ts"
+
+/**
+ * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
+ */
+export interface ScoringWeights {
+	pc: number
+	name: number
+	pop: number
+}
+
+/**
+ * A geographically-scoped resolution profile. Namespaced sections grow per phase; #289 ships the dispatch + scoring
+ * slice (`candidateStrategies` + `scoringWeights`). Later phases add `fieldMapping` (locale semantics for `locator[]`),
+ * `tokenNormalization`, etc.
+ */
+export interface Convention {
+	/** Ordered strategy names the dispatcher runs; the first to return a non-null result wins. */
+	candidateStrategies?: string[]
+	/**
+	 * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and inherit the rest
+	 * from the layers below it (`resolveConvention` fills any gaps from WORLD_DEFAULT).
+	 */
+	scoringWeights?: Partial<ScoringWeights>
+}
+
+/**
+ * A fully-resolved convention: every field present, weights complete. What `resolveConvention` returns and what
+ * strategies consume.
+ */
+export interface ResolvedConvention {
+	candidateStrategies: string[]
+	scoringWeights: ScoringWeights
+}
+
+/**
+ * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first behavior exactly: try
+ * `postcode_area_resolution`, else fall back to fuzzy name match; soft-score weights 0.6 / 0.3 / 0.1. Changing these
+ * changes EU behavior — don't, without a byte-stability run.
+ */
+export const WORLD_DEFAULT: ResolvedConvention = {
+	candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
+	scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
+}
+
+/**
+ * The strategy names the backend registers. The single source of truth shared by the dispatch registry and the
+ * build-time validator, so an authored convention that names a non-existent strategy is caught at build (loud) rather
+ * than silently skipped at runtime.
+ */
+export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
+
+/**
+ * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the shard
+ * auto-detect all agree.
+ */
+export const ADDRESS_CONVENTION_TABLE = "address_convention"
+
+/**
+ * A named resolution primitive. Returns `null` to abstain (gate unmet / no data) → the dispatcher tries the next
+ * strategy; returns an array (possibly empty) to claim the result.
+ */
+export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>
+
+/**
+ * Look up a convention record by WOF polygon id. Returns `undefined` when the polygon has no override.
+ */
+export interface ConventionSource {
+	get(wofID: number): Convention | undefined
+}
+
+/**
+ * In-memory convention source seeded from a `{ wofID: Convention }` map. Empty for the EU locales (they ride
+ * `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed source built from source, same
+ * distributable-asset discipline as `postcode-locality-intl.db`.
+ */
+export class SeedConventionSource implements ConventionSource {
+	readonly #rows: Map<number, Convention>
+
+	constructor(rows: Record<number, Convention> = {}) {
+		this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]))
+	}
+
+	get(wofID: number): Convention | undefined {
+		return this.#rows.get(wofID)
+	}
+}
+
+/**
+ * Deep-merge convention layers, later (more-specific) layers winning per field. `candidateStrategies` is replaced
+ * wholesale — a convention names its full ordered list, it does not append. `scoringWeights` is merged key-by-key so a
+ * locality can nudge one weight without restating the others.
+ */
+export function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention {
+	const out: Convention = {
+		candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
+		scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
+	}
+
+	for (const o of overrides) {
+		if (!o) continue
+
+		if (o.candidateStrategies !== undefined) {
+			out.candidateStrategies = [...o.candidateStrategies]
+		}
+
+		if (o.scoringWeights !== undefined) {
+			out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights }
+		}
+	}
+
+	return out
+}
+
+/**
+ * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL → MOST-SPECIFIC (country,
+ * region, …, locality). Starts from `WORLD_DEFAULT` so every field is defined regardless of which (if any) ancestors
+ * carry an override.
+ */
+export function resolveConvention(source: ConventionSource, ancestorIds: readonly number[]): ResolvedConvention {
+	const layers = ancestorIds.map((id) => source.get(id))
+	const merged = mergeConventions(WORLD_DEFAULT, ...layers)
+
+	return {
+		candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
+		// Fill any weight gaps from the base so strategies always see a complete set.
+		scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
+	}
+}

package/fst-autocomplete.ts

@@ -0,0 +1,187 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FST-based autocomplete. Prefix walk + BFS expansion to collect ranked place suggestions. O(depth
+ *   × branching) — the FST IS the autocomplete index.
+ *
+ *   Two query shapes are handled (the FST is a trie over normalized WORD tokens):
+ *
+ *   - COMPLETE tokens ("new york") — `walk` lands on a state; collect its accepting entries + BFS a
+ *       couple tokens past it for nearby completions. This is the CLI's "complete a place word"
+ *       path.
+ *   - A PARTIAL last token ("new yor", "chic") — `walk` fails (there is no "yor" edge, only "york"). So
+ *       walk the complete prefix, then complete the partial token by prefix-filtering the
+ *       continuation edges (`token.startsWith(partial)`). This is what a char-level typeahead
+ *       needs; without it "new yor" returns nothing useful. (#587)
+ */
+
+import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
+import type { PlaceEntry } from "./fst-types.ts"
+
+export interface AutocompleteResult {
+	query: string
+	normalizedTokens: string[]
+	depth: number
+	suggestions: AutocompleteSuggestion[]
+}
+
+export interface AutocompleteSuggestion {
+	name: string
+	placetype: string
+	importance: number
+	wofID: number
+	parentChain: number[]
+	matchDepth: number
+	completionTokens: string[]
+}
+
+export interface AutocompleteOpts {
+	maxSuggestions?: number
+	maxExpansionDepth?: number
+	/**
+	 * Collapse same-name suggestions to the single highest-importance 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)
+	 */
+	dedupeByName?: boolean
+}
+
+interface BfsItem {
+	stateID: number
+	depth: number
+	tokens: string[]
+}
+
+/** Max accepting entries collected per BFS branch — keeps one dense branch from starving the search. */
+const PER_BRANCH = 4
+
+/**
+ * The top-`k` entries by importance (descending). Avoids sorting/allocating when `entries` is small.
+ */
+function topByImportance(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
+	if (entries.length <= k) return [...entries]
+
+	return [...entries].sort((a, b) => b.importance - a.importance).slice(0, k)
+}
+
+/**
+ * Autocomplete from the current prefix. Returns suggestions ranked importance-descending.
+ */
+export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteOpts = {}): AutocompleteResult {
+	const maxSuggestions = opts.maxSuggestions ?? 10
+	const maxExpansionDepth = opts.maxExpansionDepth ?? 2
+	const normalizedTokens = normalizeTokens(query)
+
+	if (normalizedTokens.length === 0) {
+		return { query, normalizedTokens: [], depth: 0, suggestions: [] }
+	}
+
+	const seen = new Map<number, AutocompleteSuggestion>()
+	const queue: BfsItem[] = []
+	let depth = 0
+
+	const match = fst.walk(normalizedTokens)
+
+	if (match) {
+		// COMPLETE-token prefix landed on a state. Seed at the match state (accepting + continuations).
+		depth = match.depth
+
+		for (const entry of fst.accepting(match.stateID)) {
+			addSuggestion(seen, entry, match.depth, [])
+		}
+
+		for (const cont of fst.continuations(match.stateID)) {
+			queue.push({ stateID: cont.targetState, depth: 1, tokens: [cont.token] })
+		}
+	} else {
+		// PARTIAL last token — walk the complete prefix, complete the partial by prefix-filtering edges.
+		const complete = normalizedTokens.slice(0, -1)
+		const partial = normalizedTokens[normalizedTokens.length - 1]!
+		const prefixState = complete.length === 0 ? 0 : (fst.walk(complete)?.stateID ?? undefined)
+
+		if (prefixState === undefined) {
+			return { query, normalizedTokens, depth: 0, suggestions: [] }
+		}
+		depth = complete.length
+
+		for (const cont of fst.continuations(prefixState)) {
+			if (!cont.token.startsWith(partial)) continue
+
+			// This edge completes the typed partial token — its target is a real match at depth+1.
+			for (const entry of topByImportance(fst.accepting(cont.targetState), PER_BRANCH)) {
+				addSuggestion(seen, entry, complete.length + 1, [cont.token])
+			}
+			// BFS a little past it too (multi-token completions: "new yor" → "New York Mills").
+			queue.push({ stateID: cont.targetState, depth: 1, tokens: [cont.token] })
+		}
+	}
+
+	// BFS expansion (shared by both paths) — find nearby completions up to maxExpansionDepth. Each
+	// branch contributes only its top PER_BRANCH places: a state like "new london" has dozens of
+	// accepting entries and would otherwise blow the budget before the BFS ever reaches "new york"
+	// (the "new" state has 311 continuations). Per-branch capping keeps the search broad. (#587)
+	while (queue.length > 0 && seen.size < maxSuggestions * 4) {
+		const item = queue.shift()!
+
+		if (item.depth > maxExpansionDepth) continue
+
+		for (const entry of topByImportance(fst.accepting(item.stateID), PER_BRANCH)) {
+			addSuggestion(seen, entry, depth + item.depth, item.tokens)
+		}
+
+		if (item.depth < maxExpansionDepth) {
+			for (const cont of fst.continuations(item.stateID)) {
+				queue.push({ stateID: cont.targetState, depth: item.depth + 1, tokens: [...item.tokens, cont.token] })
+			}
+		}
+	}
+
+	let suggestions = [...seen.values()].sort((a, b) => b.importance - a.importance)
+
+	if (opts.dedupeByName) {
+		suggestions = dedupeByName(suggestions)
+	}
+
+	return { query, normalizedTokens, depth, suggestions: suggestions.slice(0, maxSuggestions) }
+}
+
+function addSuggestion(
+	seen: Map<number, AutocompleteSuggestion>,
+	entry: PlaceEntry,
+	matchDepth: number,
+	completionTokens: string[]
+): void {
+	const existing = seen.get(entry.wofID)
+
+	if (existing && existing.matchDepth <= matchDepth) return
+	seen.set(entry.wofID, {
+		name: entry.name,
+		placetype: entry.placetype,
+		importance: entry.importance,
+		wofID: entry.wofID,
+		parentChain: entry.parentChain,
+		matchDepth,
+		completionTokens: [...completionTokens],
+	})
+}
+
+/**
+ * Keep one suggestion per name — the highest-importance. Input is already importance-sorted, so the first occurrence
+ * per name wins; order is preserved.
+ */
+function dedupeByName(suggestions: AutocompleteSuggestion[]): AutocompleteSuggestion[] {
+	const seenNames = new Set<string>()
+	const out: AutocompleteSuggestion[] = []
+
+	for (const s of suggestions) {
+		const key = s.name.toLowerCase()
+
+		if (seenNames.has(key)) continue
+		seenNames.add(key)
+		out.push(s)
+	}
+
+	return out
+}