@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/lib/env.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Environment variables naming the WOF SQLite artifacts this resolver opens, and the development weights the overlay
+ *   linker materializes. CLI flags (`--resolve-db`, …) override these at the call site.
+ */
+
+import { $public as corePublic, liveEnv } from "@mailwoman/core/env"
+import { z } from "zod"
+
+/**
+ * Gazetteer and resolver database paths, plus the development weights overlay.
+ */
+export const PublicWOFSQLiteEnvSchema = z.object({
+	MAILWOMAN_WOF_DB: z.string().optional().meta({
+		title: "Who's On First database",
+		description: "Path to a full Who's On First SQLite distribution used by the search resolver backend.",
+	}),
+	MAILWOMAN_WOF_ADMIN_DB: z.string().optional().meta({
+		title: "Who's On First admin database",
+		description: "Path to the full Who's On First distribution used for reverse geocoding.",
+	}),
+	MAILWOMAN_WOF_POLYGONS_DB: z.string().optional().meta({
+		title: "Who's On First polygon database",
+		description: "Path to the polygon sidecar used for exact reverse-geocode containment.",
+	}),
+	MAILWOMAN_CANDIDATE_DB: z.string().optional().meta({
+		title: "Candidate database",
+		description: "Path to candidate.db; set to `none` to pin the full-distribution search backend.",
+	}),
+	MAILWOMAN_POSTAL_CITY_ALIAS_DB: z.string().optional().meta({
+		title: "Postal city alias database",
+		description: "Path to postal-city alias data used for alias-aware resolution of U.S. mailing addresses.",
+	}),
+	MAILWOMAN_DEV_MODEL: z.string().optional().meta({
+		title: "Development model",
+		description: "Path to the model artifact linked for local neural-weights development.",
+	}),
+	MAILWOMAN_DEV_TOKENIZER: z.string().optional().meta({
+		title: "Development tokenizer",
+		description: "Path to the tokenizer artifact linked for local neural-weights development.",
+	}),
+})
+
+/**
+ * Live resolver settings over core's, sharing core's getters and cached values.
+ */
+export const $public = liveEnv(PublicWOFSQLiteEnvSchema, corePublic)

package/lib/exact-match.ts

@@ -0,0 +1,113 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The exact-match tier's name probes — the two case-folded equality lookups that decide whether a
+ *   candidate holds the query text as its own name, an alias, or an official name.
+ */
+
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import { aliasBagExactMatch, foldQueryText } from "#fts/index"
+
+/**
+ * Among `ids`, return the subset whose name OR any alias equals `text` case-insensitively — the exact-match tier for
+ * ranking. One indexed query over `<schema>.names`. When the extract has no `names` table (a slim DB built with
+ * `dropNames`, or a postcode-only extract), fall back to the self-contained `place_search` FTS content: its `alt_names`
+ * column is the same alias set joined on the boundary-preserving `ALIAS_SEPARATOR` (#523), so `aliasBagExactMatch`
+ * recovers the exact alias tier ("New York City" → New York) that the dropped `names` table used to provide.
+ */
+export function exactMatchIDs<DB>(
+	db: DatabaseClient<DB>,
+	schemaName: string,
+	ids: number[],
+	text: string
+): Set<number> {
+	const out = new Set<number>()
+	const trimmed = text.trim()
+
+	if (!ids.length || !trimmed) return out
+	const placeholders = ids.map(() => "?").join(", ")
+
+	try {
+		const rows = db
+			.prepare(`SELECT DISTINCT id FROM ${schemaName}.names WHERE id IN (${placeholders}) AND name = ? COLLATE NOCASE`)
+			.all(...ids, trimmed) as Array<{ id: number }>
+
+		for (const r of rows) {
+			out.add(r.id)
+		}
+
+		return out
+	} catch {
+		// No `names` table on this extract — fall through to the place_search alias bag.
+	}
+
+	try {
+		const rows = db
+			.prepare(`SELECT wof_id AS id, name, alt_names FROM ${schemaName}.place_search WHERE wof_id IN (${placeholders})`)
+			.all(...ids) as Array<{ id: number; name: string | null; alt_names: string | null }>
+
+		const needle = foldQueryText(trimmed)
+
+		for (const r of rows) {
+			if (r.name !== null && foldQueryText(r.name) === needle) {
+				out.add(r.id)
+			}
+		}
+
+		// Alias pass via the shared bag parser (#523). Separated bags (built since #523) get a true
+		// per-alias equality check, unrestricted — matching the `names`-table branch above, where an
+		// alias match counts as exact regardless of other candidates. Legacy bags (no separator)
+		// fall back to padded containment, conditioned on "no canonical exact in the pool" because their
+		// lost boundaries would otherwise false-promote interior fragments ("York" inside the alias
+		// "New York City") or cross-alias fragments ("York New" across "…York" + "New City…").
+		const anyCanonicalExact = out.size > 0
+
+		for (const r of rows) {
+			if (aliasBagExactMatch(r.alt_names, needle, anyCanonicalExact)) {
+				out.add(r.id)
+			}
+		}
+	} catch {
+		// Extract without place_search either → no exact-match tier. Falls back to weighted-sum order.
+	}
+
+	return out
+}
+
+/**
+ * Among `ids` (already known exact matches), the subset holding `text` as an OFFICIAL name (`names.official = 1`, the
+ * #940 ingest bit). Same COLLATE NOCASE semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs} so the two probes
+ * agree on what "equals the query" means. Fails soft on gazetteers built before #940 (no `official` column) — the
+ * sub-tier then behaves exactly as if `officialNameExact` were off.
+ */
+export function officialNameIDs<DB>(
+	db: DatabaseClient<DB>,
+	schemaName: string,
+	ids: number[],
+	text: string
+): Set<number> {
+	const out = new Set<number>()
+	const trimmed = text.trim()
+
+	if (!ids.length || !trimmed) return out
+	const placeholders = ids.map(() => "?").join(", ")
+
+	try {
+		const rows = db
+			.prepare(
+				`SELECT DISTINCT id FROM ${schemaName}.names WHERE id IN (${placeholders}) AND official = 1 AND name = ? COLLATE NOCASE`
+			)
+			.all(...ids, trimmed) as Array<{ id: number }>
+
+		for (const r of rows) {
+			out.add(r.id)
+		}
+	} catch {
+		// Pre-#940 gazetteer (no `official` column) or a names-less slim extract — feature inert.
+	}
+
+	return out
+}

package/{sharding.ts → lib/extracts.ts}

@@ -1,16 +1,18 @@
+import { basename } from "path-ts"
+
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-shard support for `WOFSqlitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right shard based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
+ *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
  *
  *   ## The FTS5 syntax rule that drove this design
  *
  *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
  *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
- *   the spike at PR review time; documented as `_SHARD_RULE.md` should it ever bite again.
+ *   the spike at PR review time; documented as `_EXTRACT_RULE.md` should it ever bite again.
  *
  *   The working form: schema-qualified in FROM, bare table name in MATCH:
  *
@@ -18,15 +20,13 @@
  *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
  * ```
  *
- *   Identical table names across attached shards (which is what we have — every shard ships its own
+ *   Identical table names across attached extracts (which is what we have — every extract ships its own
  *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
  *   scope.
  */
 
-import { basename } from "node:path"
-
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each shard
+ * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
  * gets a stable, predictable handle.
  *
  * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
@@ -39,7 +39,7 @@ import { basename } from "node:path"
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ShardConfig.schemaName` when the filename doesn't follow WOF
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
  * convention.
  */
 export function deriveSchemaName(path: string): string {
@@ -57,11 +57,11 @@ export function deriveSchemaName(path: string): string {
 }
 
 /**
- * Per-shard configuration. The simple form is just a path string — the schema name is derived from it. The object form
- * lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach an
- * extra hint about which placetypes route here.
+ * Per-extract configuration. The simple form is just a path string — the schema name is derived from it. The object
+ * form lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach
+ * an extra hint about which placetypes route here.
  */
-export interface ShardConfig {
+export interface ExtractConfig {
 	path: string
 	/**
 	 * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or when you want a
@@ -69,18 +69,18 @@ export interface ShardConfig {
 	 */
 	schemaName?: string
 	/**
-	 * Optional explicit list of placetypes this shard serves. When set, queries against any listed placetype are routed
-	 * to this shard. When omitted, routing falls back to a name-match heuristic: a shard whose `schemaName` contains the
-	 * placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+	 * Optional explicit list of placetypes this extract serves. When set, queries against any listed placetype are routed
+	 * to this extract. When omitted, routing falls back to a name-match heuristic: a extract whose `schemaName` contains
+	 * the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
 	 */
 	placetypes?: readonly string[]
 }
 
 /**
  * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint. Used internally by
- * `WOFSqlitePlaceLookup` so the routing logic operates on uniform structures.
+ * `WOFSQLitePlaceLookup` so the routing logic operates on uniform structures.
  */
-export interface ResolvedShard {
+export interface ResolvedExtract {
 	path: string
 	schemaName: string
 	placetypes: readonly string[]
@@ -93,40 +93,40 @@ const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
 
 /**
  * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ShardConfig` objects) into a uniform `ResolvedShard[]`.
+ * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
  *
- * The first shard becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * shards keep their derived (or override) schema name.
+ * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
+ * extracts keep their derived (or override) schema name.
  */
-export function resolveShards(input: string | ReadonlyArray<string | ShardConfig>): ResolvedShard[] {
+export function resolveExtracts(input: string | ReadonlyArray<string | ExtractConfig>): ResolvedExtract[] {
 	const list = typeof input === "string" ? [input] : input
 
-	if (!list.length) throw new Error("resolveShards: at least one shard is required")
+	if (!list.length) throw new Error("resolveExtracts: at least one extract is required")
 
 	const seen = new Set<string>()
-	const out: ResolvedShard[] = []
+	const out: ResolvedExtract[] = []
 
 	for (let i = 0; i < list.length; i++) {
 		const entry = list[i]!
-		const cfg: ShardConfig = typeof entry === "string" ? { path: entry } : entry
+		const cfg: ExtractConfig = typeof entry === "string" ? { path: entry } : entry
 		const derived = cfg.schemaName ?? deriveSchemaName(cfg.path)
 
 		if (!SQLITE_IDENT_RE.test(derived)) {
 			throw new Error(
-				`resolveShards: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
+				`resolveExtracts: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
 					`(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
 					`{ path, schemaName } to override.`
 			)
 		}
 
-		// The first shard is always main per SQLite semantics — its derived name is informational
-		// only. Subsequent shards must have unique non-main names.
+		// The first extract is always main per SQLite semantics — its derived name is informational
+		// only. Subsequent extracts must have unique non-main names.
 		const schemaName = i === 0 ? "main" : derived
 
 		if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
 			throw new Error(
-				`resolveShards: schema name ${JSON.stringify(schemaName)} collides ` +
-					`(either with "main" or another shard). Pass an explicit { path, schemaName }.`
+				`resolveExtracts: schema name ${JSON.stringify(schemaName)} collides ` +
+					`(either with "main" or another extract). Pass an explicit { path, schemaName }.`
 			)
 		}
 
@@ -143,36 +143,39 @@ export function resolveShards(input: string | ReadonlyArray<string | ShardConfig
 }
 
 /**
- * Pick the shard to route a query to given the requested placetype(s).
+ * Pick the extract to route a query to given the requested placetype(s).
  *
  * Routing rules, in order:
  *
- * 1. If any shard has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main shard's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`), use
- *    it.
+ * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
+ *    use it.
  * 3. Otherwise, fall back to `main`.
  *
- * This deliberately doesn't UNION across shards — BM25 scores aren't comparable across separately- indexed corpora, and
- * the typical mailwoman query has a single placetype anyway. If a caller needs cross-shard results they can issue two
- * `findPlace` calls.
+ * This deliberately doesn't UNION across extracts — BM25 scores aren't comparable across separately- indexed corpora,
+ * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
+ * two `findPlace` calls.
  */
 /**
- * All placetype-matching shards, in routing order (the country-aware pick chooses among these). Used by the bias path:
- * a country-less postcode query with proximity hints fans out across every matching shard and merges, because
- * single-shard routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
+ * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
+ * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
  * postalcode-us AND postalcode-intl).
  */
-export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: string | undefined): ResolvedShard[] {
-	if (!placetype) return [shards[0]!]
-	const matches: ResolvedShard[] = []
-
-	for (const s of shards) {
+export function pickExtractsForPlacetype(
+	extracts: ResolvedExtract[],
+	placetype: string | undefined
+): ResolvedExtract[] {
+	if (!placetype) return [extracts[0]!]
+	const matches: ResolvedExtract[] = []
+
+	for (const s of extracts) {
 		if (s.placetypes.includes(placetype)) {
 			matches.push(s)
 		}
 	}
 
-	for (const s of shards) {
+	for (const s of extracts) {
 		if (s.schemaName === "main" || matches.includes(s)) continue
 
 		if (
@@ -184,38 +187,38 @@ export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: strin
 		}
 	}
 
-	return matches.length ? matches : [shards[0]!]
+	return matches.length ? matches : [extracts[0]!]
 }
 
-export function pickShardForPlacetype(
-	shards: ResolvedShard[],
+export function pickExtractForPlacetype(
+	extracts: ResolvedExtract[],
 	placetype: string | undefined,
 	opts?: {
 		/**
-		 * #920: the query's country constraint, when the caller has one. With MULTIPLE shards matching a placetype
-		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first shard and
-		 * starved the rest — a FI postcode could never reach the tail shard. When `country` is given and a matching shard's
-		 * probed country set contains it, that shard wins; shards without the country are skipped; the placetype-match
-		 * order remains the tiebreak when no shard claims the country (or none was probed).
+		 * #920: the query's country constraint, when the caller has one. With MULTIPLE extracts matching a placetype
+		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first extract
+		 * and starved the rest — a FI postcode could never reach the tail extract. When `country` is given and a matching
+		 * extract's probed country set contains it, that extract wins; extracts without the country are skipped; the
+		 * placetype-match order remains the tiebreak when no extract claims the country (or none was probed).
 		 */
 		country?: string
 		/**
-		 * Per-schema probed country sets (see `WOFSqlitePlaceLookup`'s construction probe).
+		 * Per-schema probed country sets (see `WOFSQLitePlaceLookup`'s construction probe).
 		 */
 		countriesBySchema?: ReadonlyMap<string, ReadonlySet<string>>
 	}
-): ResolvedShard {
-	if (!placetype) return shards[0]!
+): ResolvedExtract {
+	if (!placetype) return extracts[0]!
 
-	const matches: ResolvedShard[] = []
+	const matches: ResolvedExtract[] = []
 
-	for (const s of shards) {
+	for (const s of extracts) {
 		if (s.placetypes.includes(placetype)) {
 			matches.push(s)
 		}
 	}
 
-	for (const s of shards) {
+	for (const s of extracts) {
 		if (s.schemaName === "main" || matches.includes(s)) continue
 
 		// Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
@@ -230,7 +233,7 @@ export function pickShardForPlacetype(
 		}
 	}
 
-	if (!matches.length) return shards[0]!
+	if (!matches.length) return extracts[0]!
 
 	if (opts?.country && opts.countriesBySchema) {
 		for (const s of matches) {

package/lib/fst/autocomplete.ts

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FST-based autocomplete — mailwoman vocabulary over `@mailwoman/ancestrie`'s generic algorithm
+ *   (#1728 phase 2). The #587 behavior — prefix walk + BFS expansion, partial-last-token completion,
+ *   per-branch capping, dedupe — lives in ancestrie's `autocomplete`; this module contributes only
+ *   the storage adapter ({@link FSTMatcher} → `AncestrieReaderLike`) and the mapping back to
+ *   mailwoman's suggestion shape (name, placetype, referential/encyclopedic, WOF ids).
+ *
+ *   THE BYTES DO NOT MIGRATE. The shipped artifacts are `FST\0` v1–v5 (`fst-serialize.ts`), not
+ *   ancestrie's `ANCT`: ancestrie entries are id-keyed with one record per id, while an FST place row
+ *   is per-(surface, place) — `crossCountryBranches` is a property of the SURFACE, so the same wofID
+ *   legitimately carries different values under different aliases and cannot be represented id-keyed.
+ *   The matcher, both deserializers, and the serializer therefore stay here; what migrated is the
+ *   ALGORITHM, which is the half that drifts (the #861 share-the-function rule).
+ */
+
+import type {
+	AncestrieContinuation,
+	AncestrieMatch,
+	AncestrieReaderLike,
+	AncestrieRecord,
+	AncestrieSuggestion,
+} from "@mailwoman/ancestrie"
+import { autocomplete as ancestrieAutocomplete } from "@mailwoman/ancestrie"
+
+import type { FSTMatcher } from "#fst/matcher"
+import { normalizeTokens } from "#fst/matcher"
+import type { PlaceEntry } from "#fst/types"
+
+export interface AutocompleteResult {
+	query: string
+	normalizedTokens: string[]
+	depth: number
+	suggestions: AutocompleteSuggestion[]
+}
+
+export interface AutocompleteSuggestion {
+	name: string
+	placetype: string
+	/**
+	 * The REFERENTIAL likelihood the suggestion is ranked by (ROAD_TO_V9 §2). Autocomplete answers "which place does the
+	 * user mean", so it ranks referentially like everything else; encyclopedic importance rides along on
+	 * {@link AutocompleteSuggestion.encyclopedic} for display and never enters the order.
+	 */
+	referential: number
+	/**
+	 * Encyclopedic (Wikipedia) importance, when the FST artifact carries one for this place. `undefined` = no article, or
+	 * a pre-v5 binary — never 0.
+	 */
+	encyclopedic?: number
+	wofID: number
+	parentChain: number[]
+	matchDepth: number
+	completionTokens: string[]
+}
+
+export interface AutocompleteOpts {
+	maxSuggestions?: number
+	maxExpansionDepth?: number
+	/**
+	 * Collapse same-name suggestions to the single highest-referential one. Off by default (the CLI surfaces distinct
+	 * same-name places — New York the city vs the county); a typeahead wants it ON so the dropdown isn't four "New
+	 * London"s. (#587)
+	 */
+	dedupeByName?: boolean
+}
+
+/**
+ * Max accepting entries collected per BFS branch — keeps one dense branch from starving the search.
+ */
+const PER_BRANCH = 4
+
+/**
+ * The top-`k` entries by REFERENTIAL likelihood (descending). Avoids sorting/allocating when `entries` is small — and
+ * that shortcut is part of the observable contract: at or under `k` the INSERTION order is served, which decides
+ * suggestion order among referential ties.
+ */
+function topByReferential(entries: readonly PlaceEntry[], k: number): PlaceEntry[] {
+	if (entries.length <= k) return [...entries]
+
+	return [...entries].toSorted((a, b) => b.referential - a.referential).slice(0, k)
+}
+
+/**
+ * {@link FSTMatcher} presented through ancestrie's storage interface. Records carry the {@link PlaceEntry} itself as the
+ * payload, so the entry that WINS the algorithm's shallowest-depth rule is the entry whose fields the suggestion
+ * reports — a side lookup keyed on id could pick a different surface's row (`crossCountryBranches` differs per
+ * surface).
+ */
+class FSTReader implements AncestrieReaderLike<PlaceEntry> {
+	readonly #fst: FSTMatcher
+
+	/**
+	 * Parent chains of the entries this reader has served, id-keyed. A place's chain is identical across its surfaces (it
+	 * is place-row data), so last-write-wins is safe. The algorithm asks {@link FSTReader.ancestorsOf} only for ids it
+	 * just received from {@link FSTReader.entriesAt}, so serving from this memo answers every real call without an
+	 * artifact-wide id index.
+	 */
+	readonly #chains = new Map<number, number[]>()
+
+	constructor(fst: FSTMatcher) {
+		this.#fst = fst
+	}
+
+	walk(tokens: readonly string[]): AncestrieMatch | null {
+		return this.#fst.walk([...tokens])
+	}
+
+	continuations(stateID: number): AncestrieContinuation[] {
+		// Insertion order, verbatim — BFS visit order under the suggestion budget depends on it.
+		return this.#fst.continuations(stateID).map((c) => ({
+			token: c.token,
+			targetState: c.targetState,
+			entryCount: c.acceptingCount,
+		}))
+	}
+
+	entriesAt(stateID: number, limit?: number): AncestrieRecord<PlaceEntry>[] {
+		const places = this.#fst.accepting(stateID)
+		const selected = limit === undefined ? places : topByReferential(places, limit)
+
+		return selected.map((entry) => {
+			this.#chains.set(entry.wofID, entry.parentChain)
+
+			return {
+				id: entry.wofID,
+				rank: entry.referential,
+				parentIDs: entry.parentChain,
+				payload: entry,
+			}
+		})
+	}
+
+	ancestorsOf(id: number): number[] {
+		return this.#chains.get(id) ?? []
+	}
+}
+
+/**
+ * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
+ */
+export function autocomplete(fst: FSTMatcher, query: string, opts: AutocompleteOpts = {}): AutocompleteResult {
+	const normalizedTokens = normalizeTokens(query)
+
+	const result = ancestrieAutocomplete<PlaceEntry>(new FSTReader(fst), normalizedTokens, {
+		...(opts.maxSuggestions === undefined ? {} : { maxSuggestions: opts.maxSuggestions }),
+		...(opts.maxExpansionDepth === undefined ? {} : { maxExpansionDepth: opts.maxExpansionDepth }),
+		perBranchLimit: PER_BRANCH,
+		// The dedupe key is the DISPLAY name, not the token path: two surfaces of one name must still collapse. (#587)
+		...(opts.dedupeByName ? { dedupe: (s: AncestrieSuggestion<PlaceEntry>) => s.payload!.name.toLowerCase() } : {}),
+	})
+
+	return {
+		query,
+		normalizedTokens,
+		depth: result.depth,
+		suggestions: result.suggestions.map((s) => {
+			// Every record this adapter serves carries its entry; the assertion documents the invariant.
+			const entry = s.payload!
+
+			return {
+				name: entry.name,
+				placetype: entry.placetype,
+				referential: entry.referential,
+				...(entry.encyclopedic === undefined ? {} : { encyclopedic: entry.encyclopedic }),
+				wofID: s.id,
+				parentChain: s.parentIDs,
+				matchDepth: s.matchDepth,
+				completionTokens: s.completionTokens,
+			}
+		}),
+	}
+}