@mailwoman/resolver-wof-sqlite 9.0.0 → 9.2.0

package/out/currency-backfill.js

@@ -0,0 +1,180 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Pass 1c of the candidate build (#1737): resurrect deprecated-with-no-successor WOF localities that a second
+ *   source independently attests. Extracted from `build-candidate.ts` as a cohesive unit — the gates, their measured
+ *   constants, and the GeoNames dump reader live together here; the build calls {@link resurrectCurrencyHoles} once,
+ *   between the primaries pass and the alias pass.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { isStrictlyFiner } from "@mailwoman/core/resources/whosonfirst";
+import { haversineKm } from "@mailwoman/spatial";
+import { TSVSpliterator } from "spliterator";
+import { normalizeLocalityForKey } from "./street-normalize.js";
+/**
+ * Corroboration radius for the currency backfill (#1737), km — both for the live-near blocker and the GeoNames
+ * attestation. Measured basis (2026-08-19 prototype, GB locality slice): at 10 km, 20 of 108 dead names resurrect —
+ * Rochester (Kent), Aldershot, Staines, Telford, Ebbw Vale among them — while the `Birmingham/Wolverhampton/…`
+ * conurbation blobs stay dead (no attestation) and Swansea/Wrexham stay out because a live same-name row already serves
+ * them within the radius.
+ */
+const CURRENCY_BACKFILL_RADIUS_KM = 10;
+/**
+ * Minimum attestor population for a resurrection. The same prototype measured 44 of 108 dead GB names attested but
+ * under this floor — hamlet-scale ghosts whose absence from the index nobody has reported. A floor keeps the pass
+ * answering the measured defect (real settlements) rather than re-importing the tail WOF chose to prune.
+ */
+const CURRENCY_BACKFILL_POP_FLOOR = 1000;
+/**
+ * Pass 1c (#1737): resurrect deprecated-with-no-successor localities that a second source independently attests.
+ *
+ * WOF deprecations WITH a successor need nothing — the successor indexes. A deprecation with `is_superseded = 0` on a
+ * populated place is the shape of an upstream mistake (Rochester Kent, Aldershot, Telford; 120 GB localities alone),
+ * and it is indistinguishable from a correct pruning at this layer without outside evidence. So every resurrection
+ * requires all three gates, positive evidence only:
+ *
+ * 1. NO live same-name spr row of any placetype within {@link CURRENCY_BACKFILL_RADIUS_KM} of the dead record — a live row
+ *    means the place is alive (possibly under another placetype) and there is no hole. A DISTANT same-name row is a
+ *    namesake and does not block.
+ * 2. A GeoNames feature-class-P attestation of the same folded name within the radius.
+ * 3. The attestor at or above {@link CURRENCY_BACKFILL_POP_FLOOR}.
+ *
+ * The staged row keeps the WOF identity — id, name, centroid, bbox, region ancestry — because the dead record's own
+ * data is not what is wrong with it. GeoNames contributes exactly two things: the attestation, and the population that
+ * lets the row stand in prominence races (the dead record's own population is absent). Each name is judged once per
+ * country; the resurrected place joins `attrs`, so the alias pass explodes its alt names like any primary's.
+ */
+export async function resurrectCurrencyHoles(ctx) {
+    const deadStmt = ctx.src.prepare(`SELECT id, name, placetype, latitude, longitude, min_latitude, min_longitude, max_latitude, max_longitude
+		 FROM spr
+		 WHERE country = ? AND placetype = 'locality'
+		   AND is_current = 0 AND is_deprecated = 1 AND is_superseded = 0`);
+    const liveStmt = ctx.src.prepare(`SELECT latitude, longitude, placetype FROM spr WHERE country = ? AND name = ? AND is_current != 0`);
+    let total = 0;
+    for (const country of ctx.countries) {
+        const cc = country.toUpperCase();
+        const dumpPath = resolve(ctx.geonamesDir, `${cc}.txt`);
+        if (!existsSync(dumpPath)) {
+            ctx.progress("currency-backfill", `${cc}: no GeoNames dump at ${dumpPath} — holes stay dead`);
+            continue;
+        }
+        // Dead rows FIRST: a country with no deprecated-no-successor localities needs no attestors at all, and
+        // loading a national dump to judge zero rows is pure heap pressure on a build already near its ceiling
+        // (the first live run OOM'd in a later pass with JP/KR dumps loaded for 0 dead names each).
+        const dead = deadStmt.all(cc);
+        if (!dead.length) {
+            ctx.progress("currency-backfill", `${cc}: 0 dead names — dump not loaded`);
+            continue;
+        }
+        // Only the dead names' own folded keys can ever be probed, so only those keys are worth holding —
+        // the rest of the national dump streams through without residency.
+        const deadKeys = new Set();
+        for (const d of dead) {
+            const k = normalizeLocalityForKey(String(d.name ?? ""));
+            if (k) {
+                deadKeys.add(k);
+            }
+        }
+        // Folded name → P-class attestors. GeoNames columns by index: 1 name, 2 ascii, 4 lat, 5 lon,
+        // 6 feature_class, 14 population.
+        const attestors = new Map();
+        for await (const f of TSVSpliterator.fromAsync(dumpPath, { header: false })) {
+            if (f[6] !== "P")
+                continue;
+            const keys = [normalizeLocalityForKey(String(f[1] ?? "")), normalizeLocalityForKey(String(f[2] ?? ""))].filter((key) => key && deadKeys.has(key));
+            if (!keys.length)
+                continue;
+            const row = { lat: Number(f[4]), lon: Number(f[5]), pop: Number(f[14]) || 0 };
+            for (const key of new Set(keys)) {
+                const bag = attestors.get(key);
+                if (bag) {
+                    bag.push(row);
+                }
+                else {
+                    attestors.set(key, [row]);
+                }
+            }
+        }
+        let judged = 0;
+        let blocked = 0;
+        let unattested = 0;
+        let floored = 0;
+        let resurrected = 0;
+        const seen = new Set();
+        ctx.tx.exec("BEGIN");
+        for (const d of dead) {
+            const name = String(d.name ?? "");
+            const pkey = normalizeLocalityForKey(name);
+            if (!pkey || seen.has(pkey))
+                continue;
+            seen.add(pkey);
+            judged++;
+            const dLat = Number(d.latitude);
+            const dLon = Number(d.longitude);
+            // The dead-row query is scoped to `locality` today; read it from the row anyway so widening that query
+            // cannot silently start comparing every candidate against a hardcoded rung.
+            const deadPlacetype = String(d.placetype ?? "locality");
+            // A live row blocks only when it is AT LEAST AS COARSE as the dead one. The original gate compared name and
+            // distance alone, on the premise that a nearby same-name row means "the place is alive under another
+            // placetype" — true for a place recorded twice, false for a placetype DEMOTION, which is the shape that
+            // actually occurs: WOF retired `Gillingham` the locality (pop 101,187) and kept `Gillingham` the
+            // neighbourhood 3.2 km away, and the gate read the surviving CHILD as covering its own dead parent.
+            // Sixteen of seventeen GB refusals had exactly that shape (#1746).
+            //
+            // An UNRANKED placetype blocks, which is the conservative direction: this gate's failure mode is inventing
+            // a place, so a row we cannot rank is treated as covering rather than waved through.
+            const liveNear = liveStmt.all(cc, name).some((row) => {
+                if (haversineKm(dLat, dLon, Number(row.latitude), Number(row.longitude)) > CURRENCY_BACKFILL_RADIUS_KM) {
+                    return false;
+                }
+                // Blocks UNLESS the live row is strictly finer. The equal rung must still block — a live `locality`
+                // covers a dead `locality` — and an unranked placetype blocks too, since this gate's failure mode
+                // is inventing a place.
+                return isStrictlyFiner(String(row.placetype ?? ""), deadPlacetype) !== true;
+            });
+            if (liveNear) {
+                blocked++;
+                continue;
+            }
+            const near = (attestors.get(pkey) ?? []).filter((g) => haversineKm(dLat, dLon, g.lat, g.lon) <= CURRENCY_BACKFILL_RADIUS_KM);
+            if (!near.length) {
+                unattested++;
+                continue;
+            }
+            const pop = Math.max(...near.map((g) => g.pop));
+            if (pop < CURRENCY_BACKFILL_POP_FLOOR) {
+                floored++;
+                continue;
+            }
+            const sid = Number(d.id);
+            const a = {
+                cid: ctx.ccID(cc),
+                rid: ctx.regionOf.get(sid) ?? 0,
+                ptid: ctx.ptID("locality"),
+                name,
+                lat: dLat,
+                lon: dLon,
+                mnLat: Number(d.min_latitude),
+                mnLon: Number(d.min_longitude),
+                mxLat: Number(d.max_latitude),
+                mxLon: Number(d.max_longitude),
+                pop,
+                neg: -Math.log10(pop + 1),
+                pkey,
+                imp: ctx.importance?.find(name, cc, "locality", dLat, dLon) ?? null,
+            };
+            ctx.attrs.set(sid, a);
+            ctx.stageRow(pkey, a, sid, 1);
+            resurrected++;
+        }
+        ctx.tx.exec("COMMIT");
+        ctx.progress("currency-backfill", `${cc}: ${resurrected} resurrected of ${judged} dead names ` +
+            `(${blocked} blocked by a live near row, ${unattested} unattested, ${floored} under the population floor)`);
+        total += resurrected;
+    }
+    return total;
+}
+//# sourceMappingURL=currency-backfill.js.map

package/out/currency-backfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency-backfill.js","sourceRoot":"","sources":["../currency-backfill.ts"],"names":[],"mappings":"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"}

package/out/exact-match.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 { DatabaseSync } from "node:sqlite";
+/**
+ * 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 shard has no `names` table (a slim DB built with
+ * `dropNames`, or a postcode-only shard), 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 declare function exactMatchIDs(db: DatabaseSync, schemaName: string, ids: number[], text: string): Set<number>;
+/**
+ * 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 declare function officialNameIDs(db: DatabaseSync, schemaName: string, ids: number[], text: string): Set<number>;
+//# sourceMappingURL=exact-match.d.ts.map

package/out/exact-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-match.d.ts","sourceRoot":"","sources":["../exact-match.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAqD5G;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAsB9G"}

package/out/exact-match.js

@@ -0,0 +1,89 @@
+/**
+ * @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 { aliasBagExactMatch } from "./fts.js";
+/**
+ * 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 shard has no `names` table (a slim DB built with
+ * `dropNames`, or a postcode-only shard), 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, schemaName, ids, text) {
+    const out = new Set();
+    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);
+        for (const r of rows) {
+            out.add(r.id);
+        }
+        return out;
+    }
+    catch {
+        // No `names` table on this shard — 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);
+        const norm = (s) => s.toLowerCase().trim().replaceAll(/\s+/g, " ");
+        const needle = norm(trimmed);
+        for (const r of rows) {
+            if (r.name !== null && norm(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, ungated — 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, gated 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 {
+        // Shard 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, schemaName, ids, text) {
+    const out = new Set();
+    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);
+        for (const r of rows) {
+            out.add(r.id);
+        }
+    }
+    catch {
+        // Pre-#940 gazetteer (no `official` column) or a names-less slim shard — feature inert.
+    }
+    return out;
+}
+//# sourceMappingURL=exact-match.js.map

package/out/exact-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-match.js","sourceRoot":"","sources":["../exact-match.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,EAAgB,EAAE,UAAkB,EAAE,GAAa,EAAE,IAAY;IAC9F,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAE3B,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,CAAA;IACvC,MAAM,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAElD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,EAAE;aACb,OAAO,CAAC,2BAA2B,UAAU,uBAAuB,YAAY,+BAA+B,CAAC;aAChH,GAAG,CAAC,GAAG,GAAG,EAAE,OAAO,CAA0B,CAAA;QAE/C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACtB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACd,CAAC;QAED,OAAO,GAAG,CAAA;IACX,CAAC;IAAC,MAAM,CAAC;QACR,+EAA+E;IAChF,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,EAAE;aACb,OAAO,CAAC,6CAA6C,UAAU,kCAAkC,YAAY,GAAG,CAAC;aACjH,GAAG,CAAC,GAAG,GAAG,CAAyE,CAAA;QAErF,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QAClF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;QAE5B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;gBAChD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YACd,CAAC;QACF,CAAC;QAED,4FAA4F;QAC5F,wFAAwF;QACxF,yFAAyF;QACzF,2FAA2F;QAC3F,4FAA4F;QAC5F,uFAAuF;QACvF,MAAM,iBAAiB,GAAG,GAAG,CAAC,IAAI,GAAG,CAAC,CAAA;QAEtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACtB,IAAI,kBAAkB,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YACd,CAAC;QACF,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,6FAA6F;IAC9F,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,EAAgB,EAAE,UAAkB,EAAE,GAAa,EAAE,IAAY;IAChG,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAE3B,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,CAAA;IACvC,MAAM,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAElD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,EAAE;aACb,OAAO,CACP,2BAA2B,UAAU,uBAAuB,YAAY,gDAAgD,CACxH;aACA,GAAG,CAAC,GAAG,GAAG,EAAE,OAAO,CAA0B,CAAA;QAE/C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACtB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACd,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,wFAAwF;IACzF,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC"}

package/out/fst-autocomplete.d.ts

@@ -3,18 +3,18 @@
  * @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.
+ *   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).
  *
- *   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)
+ *   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 { FSTMatcher } from "./fst-matcher.ts";
 export interface AutocompleteResult {
@@ -26,7 +26,17 @@ export interface AutocompleteResult {
 export interface AutocompleteSuggestion {
     name: string;
     placetype: string;
-    importance: number;
+    /**
+     * 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;
@@ -36,14 +46,14 @@ export interface AutocompleteOpts {
     maxSuggestions?: number;
     maxExpansionDepth?: number;
     /**
-     * Collapse same-name suggestions to the single highest-importance one. Off by default (the CLI surfaces distinct
+     * 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;
 }
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked importance-descending.
+ * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
  */
 export declare function autocomplete(fst: FSTMatcher, query: string, opts?: AutocompleteOpts): AutocompleteResult;
 //# sourceMappingURL=fst-autocomplete.d.ts.map

package/out/fst-autocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fst-autocomplete.d.ts","sourceRoot":"","sources":["../fst-autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAIlD,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAsBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA8E5G"}
+{"version":3,"file":"fst-autocomplete.d.ts","sourceRoot":"","sources":["../fst-autocomplete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAIlD,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,sBAAsB,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAChC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB;AAyED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,kBAAkB,CA+B5G"}

package/out/fst-autocomplete.js

@@ -3,127 +3,111 @@
  * @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.
+ *   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).
  *
- *   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)
+ *   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 { autocomplete as ancestrieAutocomplete } from "@mailwoman/ancestrie";
 import { normalizeTokens } from "./fst-matcher.js";
 /**
  * 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.
+ * 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 topByImportance(entries, k) {
+function topByReferential(entries, k) {
     if (entries.length <= k)
         return [...entries];
-    return [...entries].toSorted((a, b) => b.importance - a.importance).slice(0, k);
+    return [...entries].toSorted((a, b) => b.referential - a.referential).slice(0, k);
 }
 /**
- * Autocomplete from the current prefix. Returns suggestions ranked importance-descending.
+ * {@link FSTMatcher} presented through ancestrie's storage seam. 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).
  */
-export function autocomplete(fst, query, opts = {}) {
-    const maxSuggestions = opts.maxSuggestions ?? 10;
-    const maxExpansionDepth = opts.maxExpansionDepth ?? 2;
-    const normalizedTokens = normalizeTokens(query);
-    if (!normalizedTokens.length) {
-        return { query, normalizedTokens: [], depth: 0, suggestions: [] };
+class FSTReader {
+    #fst;
+    /**
+     * 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.
+     */
+    #chains = new Map();
+    constructor(fst) {
+        this.#fst = fst;
     }
-    const seen = new Map();
-    const queue = [];
-    let depth;
-    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] });
-        }
+    walk(tokens) {
+        return this.#fst.walk([...tokens]);
     }
-    else {
-        // PARTIAL last token — walk the complete prefix, complete the partial by prefix-filtering edges.
-        const complete = normalizedTokens.slice(0, -1);
-        const partial = normalizedTokens.at(-1);
-        const prefixState = !complete.length ? 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] });
-        }
+    continuations(stateID) {
+        // 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,
+        }));
     }
-    // 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 && 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] });
-            }
-        }
+    entriesAt(stateID, limit) {
+        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,
+            };
+        });
     }
-    let suggestions = [...seen.values()].toSorted((a, b) => b.importance - a.importance);
-    if (opts.dedupeByName) {
-        suggestions = dedupeByName(suggestions);
+    ancestorsOf(id) {
+        return this.#chains.get(id) ?? [];
     }
-    return { query, normalizedTokens, depth, suggestions: suggestions.slice(0, maxSuggestions) };
-}
-function addSuggestion(seen, entry, matchDepth, completionTokens) {
-    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.
+ * Autocomplete from the current prefix. Returns suggestions ranked referential-descending.
  */
-function dedupeByName(suggestions) {
-    const seenNames = new Set();
-    const out = [];
-    for (const s of suggestions) {
-        const key = s.name.toLowerCase();
-        if (seenNames.has(key))
-            continue;
-        seenNames.add(key);
-        out.push(s);
-    }
-    return out;
+export function autocomplete(fst, query, opts = {}) {
+    const normalizedTokens = normalizeTokens(query);
+    const result = ancestrieAutocomplete(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) => 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,
+            };
+        }),
+    };
 }
 //# sourceMappingURL=fst-autocomplete.js.map