@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/out/candidate-importance.d.ts

@@ -27,7 +27,7 @@
  *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
  *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
  *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_GATE_KM}. Two artifacts describing the same settlement put its centroid in
+ *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
  *   almost the same place; two same-named towns in one country do not.
  *
  *   ## What lands in the column
@@ -48,18 +48,18 @@
  * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
  * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
  *
- * What sets the gate is where that mode ENDS, and the per-kilometre density says so plainly. It falls from 1,076
- * places/km over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of
- * 760–780 places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns
- * wearing one name in one country, and it does not decay with distance because there is no reason it should. 10 km is
- * the floor between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the
- * gate to 25 km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
+ * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
+ * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
+ * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
+ * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
+ * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
  *
  * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The gate is the definition of
- * "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
+ * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
  */
-export declare const IMPORTANCE_JOIN_GATE_KM = 10;
+export declare const IMPORTANCE_JOIN_RADIUS_KM = 10;
 /**
  * One scored place from the source: where it is, and what it scored.
  */
@@ -93,21 +93,21 @@ export declare class ImportanceIndex {
     #private;
     readonly stats: ImportanceIndexStats;
     /**
-     * Places {@link find} matched inside the gate.
+     * Places {@link find} matched inside the radius.
      */
     matched: number;
     /**
-     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the gate, so
-     * it is a different place wearing the same name.
+     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+     * so it is a different place wearing the same name.
      *
      * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-     * apart and the join is being asked to guess; it does not mean the gate is too tight.
+     * apart and the join is being asked to guess; it does not mean the radius is too tight.
      */
-    gated: number;
+    refused: number;
     constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats);
     /**
      * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-     * null when there is no such place within {@link IMPORTANCE_JOIN_GATE_KM}.
+     * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
      *
      * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
      * column already carries that fallback where it has one, and inventing a second one would make an absence

package/out/candidate-importance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-importance.d.ts","sourceRoot":"","sources":["../candidate-importance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAOH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;GAEG;AACH,UAAU,WAAW;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAUD;;GAEG;AACH,qBAAa,eAAe;;IAE3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC;;OAEG;IACH,OAAO,SAAI;IACX;;;;;;OAMG;IACH,KAAK,SAAI;gBAEG,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,oBAAoB;IAK3E;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CA+B7G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CA4CzE"}
+{"version":3,"file":"candidate-importance.d.ts","sourceRoot":"","sources":["../lib/candidate-importance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAQH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAE3C;;GAEG;AACH,UAAU,WAAW;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAUD;;GAEG;AACH,qBAAa,eAAe;;IAE3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC;;OAEG;IACH,OAAO,SAAI;IACX;;;;;;OAMG;IACH,OAAO,SAAI;gBAEC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,oBAAoB;IAK3E;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CA+B7G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAwCzE"}

package/out/candidate-importance.js

@@ -27,7 +27,7 @@
  *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
  *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
  *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_GATE_KM}. Two artifacts describing the same settlement put its centroid in
+ *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
  *   almost the same place; two same-named towns in one country do not.
  *
  *   ## What lands in the column
@@ -40,9 +40,9 @@
  *   A place with no match gets NULL. NULL is UNMEASURED, never zero — the consumer
  *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
  */
-import { DatabaseSync } from "node:sqlite";
-import { haversineKm } from "./geo.js";
-import { normalizeLocalityForKey } from "./street-normalize.js";
+import { haversineKm } from "@mailwoman/spatial";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { normalizeLocalityForKey } from "#street/normalize";
 /**
  * How far apart two artifacts may put the same place's centroid and still be read as the same place.
  *
@@ -51,18 +51,18 @@ import { normalizeLocalityForKey } from "./street-normalize.js";
  * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
  * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
  *
- * What sets the gate is where that mode ENDS, and the per-kilometre density says so plainly. It falls from 1,076
- * places/km over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of
- * 760–780 places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns
- * wearing one name in one country, and it does not decay with distance because there is no reason it should. 10 km is
- * the floor between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the
- * gate to 25 km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
+ * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
+ * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
+ * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
+ * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
+ * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
  *
  * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The gate is the definition of
- * "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
+ * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
  */
-export const IMPORTANCE_JOIN_GATE_KM = 10;
+export const IMPORTANCE_JOIN_RADIUS_KM = 10;
 /**
  * `(name_key, country, placetype)` → the scored places under it. The separator is U+0000, which no WOF name carries and
  * no fold can produce, so the three fields can't smear into one another.
@@ -77,24 +77,24 @@ export class ImportanceIndex {
     #groups;
     stats;
     /**
-     * Places {@link find} matched inside the gate.
+     * Places {@link find} matched inside the radius.
      */
     matched = 0;
     /**
-     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the gate, so
-     * it is a different place wearing the same name.
+     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+     * so it is a different place wearing the same name.
      *
      * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-     * apart and the join is being asked to guess; it does not mean the gate is too tight.
+     * apart and the join is being asked to guess; it does not mean the radius is too tight.
      */
-    gated = 0;
+    refused = 0;
     constructor(groups, stats) {
         this.#groups = groups;
         this.stats = stats;
     }
     /**
      * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-     * null when there is no such place within {@link IMPORTANCE_JOIN_GATE_KM}.
+     * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
      *
      * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
      * column already carries that fallback where it has one, and inventing a second one would make an absence
@@ -116,8 +116,8 @@ export class ImportanceIndex {
                 best = place;
             }
         }
-        if (!best || bestKm > IMPORTANCE_JOIN_GATE_KM) {
-            this.gated++;
+        if (!best || bestKm > IMPORTANCE_JOIN_RADIUS_KM) {
+            this.refused++;
             return null;
         }
         this.matched++;
@@ -137,38 +137,33 @@ export class ImportanceIndex {
  * 25 s.
  */
 export function loadImportanceIndex(databasePath) {
-    const db = new DatabaseSync(databasePath, { readOnly: true });
-    try {
-        const groups = new Map();
-        let places = 0;
-        let unkeyable = 0;
-        for (const row of db
-            .prepare(`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
-					s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
-				 FROM place_importance i JOIN spr s ON s.id = i.id
-				 WHERE s.is_current != 0 AND s.is_deprecated = 0`)
-            .iterate()) {
-            const importance = Number(row.importance);
-            if (!Number.isFinite(importance))
-                continue;
-            const nameKey = normalizeLocalityForKey(String(row.name ?? ""));
-            if (!nameKey) {
-                unkeyable++;
-                continue;
-            }
-            const key = groupKey(nameKey, row.country, row.placetype);
-            let group = groups.get(key);
-            if (!group) {
-                group = [];
-                groups.set(key, group);
-            }
-            group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance });
-            places++;
+    using db = new DatabaseClient(databasePath, { readOnly: true });
+    const groups = new Map();
+    let places = 0;
+    let unkeyable = 0;
+    for (const row of db
+        .prepare(`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
+				s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
+			 FROM place_importance i JOIN spr s ON s.id = i.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`)
+        .iterate()) {
+        const importance = Number(row.importance);
+        if (!Number.isFinite(importance))
+            continue;
+        const nameKey = normalizeLocalityForKey(String(row.name ?? ""));
+        if (!nameKey) {
+            unkeyable++;
+            continue;
         }
-        return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable });
-    }
-    finally {
-        db.close();
+        const key = groupKey(nameKey, row.country, row.placetype);
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance });
+        places++;
     }
+    return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable });
 }
 //# sourceMappingURL=candidate-importance.js.map

package/out/candidate-importance.js.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-importance.js","sourceRoot":"","sources":["../candidate-importance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"candidate-importance.js","sourceRoot":"","sources":["../lib/candidate-importance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAGzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAA;AA8B3C;;;GAGG;AACH,SAAS,QAAQ,CAAC,OAAe,EAAE,OAAsB,EAAE,SAAwB;IAClF,OAAO,GAAG,OAAO,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,SAAS,SAAS,IAAI,EAAE,EAAE,CAAA;AAClF,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,eAAe;IAClB,OAAO,CAA4B;IACnC,KAAK,CAAsB;IACpC;;OAEG;IACH,OAAO,GAAG,CAAC,CAAA;IACX;;;;;;OAMG;IACH,OAAO,GAAG,CAAC,CAAA;IAEX,YAAY,MAAkC,EAAE,KAA2B;QAC1E,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,IAAY,EAAE,OAAsB,EAAE,SAAwB,EAAE,GAAW,EAAE,GAAW;QAC5F,MAAM,OAAO,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAE7C,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAA;QAEzB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAA;QAErE,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QAEvB,IAAI,IAA6B,CAAA;QACjC,IAAI,MAAM,GAAG,QAAQ,CAAA;QAErB,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;YAC3B,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;YAEtD,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;gBACjB,MAAM,GAAG,EAAE,CAAA;gBACX,IAAI,GAAG,KAAK,CAAA;YACb,CAAC;QACF,CAAC;QAED,IAAI,CAAC,IAAI,IAAI,MAAM,GAAG,yBAAyB,EAAE,CAAC;YACjD,IAAI,CAAC,OAAO,EAAE,CAAA;YAEd,OAAO,IAAI,CAAA;QACZ,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAA;QAEd,OAAO,IAAI,CAAC,UAAU,CAAA;IACvB,CAAC;CACD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACvD,MAAM,EAAE,GAAG,IAAI,cAAc,CAAoB,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAElF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAA;IAC/C,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,KAAK,MAAM,GAAG,IAAI,EAAE;SAClB,OAAO,CACP;;;oDAGiD,CACjD;SACA,OAAO,EAAE,EAAE,CAAC;QACb,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QAEzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;YAAE,SAAQ;QAC1C,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAA;QAE/D,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,SAAS,EAAE,CAAA;YAEX,SAAQ;QACT,CAAC;QAED,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,OAAwB,EAAE,GAAG,CAAC,SAA0B,CAAC,CAAA;QAC3F,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAE3B,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,EAAE,CAAA;YACV,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QACvB,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC,CAAA;QAEjF,MAAM,EAAE,CAAA;IACT,CAAC;IAED,OAAO,IAAI,eAAe,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;AAC7E,CAAC"}

package/out/candidate-lookup.d.ts

@@ -14,7 +14,7 @@
  *   {@link normalizeLocalityForKey} (build- and query-consistent), each row is denormalized (display
  *   `name`, centroid, bbox), and population rank is precomputed into `neg_rank` — so the result is
  *   POPULATION-FIRST and COUNTRY-AGNOSTIC (when no `country` filter is given), exactly like the
- *   demo. That's the deliberate divergence from {@link WOFSqlitePlaceLookup}'s FTS/bm25 ranking: a
+ *   demo. That's the deliberate divergence from {@link WOFSQLitePlaceLookup}'s FTS/bm25 ranking: a
  *   bare "Moscow" resolves to the 10.4 M-pop Russian city, not whichever same-name US township bm25
  *   floats to the top.
  *
@@ -22,76 +22,55 @@
  *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
  *   `bbox` field on {@link FindPlaceQuery}).
  */
-import { DatabaseSync } from "node:sqlite";
-import { type GazetteerArtifactCoverage } from "@mailwoman/resolver";
-import type { CandidateTable } from "./candidate-schema.ts";
-import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "./types.ts";
+import { type Ancestor, type GazetteerArtifactCoverage } from "@mailwoman/resolver";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { PathBuilderLike } from "path-ts";
+import type { CandidateDatabase } from "#candidate-schema";
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "#types";
+export { rankByPrimaryPreference } from "#primary-preference";
+export type { RankedRow } from "#primary-preference";
 export interface WOFCandidateTableLookupOpts {
     /**
      * Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only.
      */
-    databasePath?: string;
+    databasePath?: PathBuilderLike;
     /**
      * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
      */
-    database?: DatabaseSync;
-}
-/**
- * The candidate columns this lookup probes — a typed projection of the SHARED {@link CandidateTable}, so a column rename
- * in `build-candidate` (the writer) is a compile error here (the reader).
- */
-type CandidateRow = Pick<CandidateTable, "spr_id" | "name" | "country_id" | "placetype_id" | "latitude" | "longitude" | "min_lat" | "min_lon" | "max_lat" | "max_lon" | "neg_rank" | "is_primary" | "population"> & Partial<Pick<CandidateTable, "importance">>;
-/**
- * A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag.
- */
-export type RankedRow<R> = R & {
-    /**
-     * `neg_rank` plus the bounded cross-country alias penalty — the value the row is ORDERED by, and the base the emitted
-     * `prominence` is derived from (so the resolver walk's `prominence ?? score` sort, `resolve.ts`, agrees with this
-     * order; the raw `score`/`neg_rank` is left intact for the walk's `minWinningScore` gate).
-     */
-    effectiveNegRank: number;
+    database?: DatabaseClient<CandidateDatabase>;
     /**
-     * True when this row is a cross-country alias that LOST the bounded population contest to the same-key primary — a
-     * coincidental foreign exonym (Changchun's "Çançun" for "Cancun"). Such a row is dropped out of the exact-match tier
-     * (`exactMatch=false`) so the resolver walk's country pin — the model's `anchorPosterior`, which "never crosses the
-     * exact/partial boundary" (`resolve.ts`) — can't ride a spurious posterior (CN 0.86 for "Cancun") back over the
-     * primary. Only the LOSING foreign alias is demoted; a dominant alias (Los Angeles over La, Ghana) keeps its exact
-     * tier, and a same-country nickname (San Francisco's "Frisco") is never touched.
+     * #1882 opt-in: exempt `name_role = 'variant'` aliases — the holder's own primary name in another orthography,
+     * stamped by the build's own-name detector — from the cross-country primary-preference penalty. No-ops on an artifact
+     * without the role column. Default OFF (D-rule).
      */
-    demoted: boolean;
-    /**
-     * True when this row came from the TYPO-CORRECTOR tier — the FTS5-trigram fallback that fires only after the exact
-     * and qualifier-strip probes both missed. Such a row answers a query the gazetteer does not contain, so it is a fuzzy
-     * match by construction and must not claim `exactMatch` (#17). Recall is unaffected: the row is still returned, still
-     * ranked, still resolvable — it just stops asserting a match quality it does not have, which is what the FTS backend
-     * has always done and what every `exactMatch`-filtering consumer assumed.
-     */
-    fuzzy?: boolean;
-};
-/**
- * Bounded cross-country primary-name preference (see {@link PRIMARY_PREFERENCE_LOG10}). Pure + total-ordered so
- * `candidate-lookup.test.ts` can exercise it on synthetic rows. `rows` arrive population-ordered (`neg_rank ASC`); an
- * alias (`is_primary=0`) is pushed back by `delta` in log10-population units ONLY when the top-population primary
- * sharing the key is in a different country, and is `demoted` out of the exact tier when that penalty leaves it BEHIND
- * the primary. Returns the top `limit` after the re-rank, each annotated.
- */
-export declare function rankByPrimaryPreference<R extends Pick<CandidateRow, "neg_rank" | "is_primary" | "country_id">>(rows: readonly R[], limit: number, delta?: number): Array<RankedRow<R>>;
+    variantAliasExemption?: boolean;
+}
 /**
- * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSqlitePlaceLookup} in `createWOFResolver(backend)`
+ * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSQLitePlaceLookup} in `createWOFResolver(backend)`
  * — same `findPlace` contract, population-first ranking.
  */
-export declare class WOFCandidateTableLookup implements PlaceLookup {
+export declare class WOFCandidateTableLookup implements PlaceLookup, Disposable {
     #private;
     /**
      * Facts this candidate DB declares about itself — the coverage manifest (`country_coverage` + `country_bbox`) the
      * gazetteer build emits, read once at open. `undefined` when the artifact predates the manifest, so every consumer
-     * (the hard-country coverage gate, guard-B plausibility) falls back to its code constants byte-identically.
+     * (the hard-country coverage check, guard-B plausibility) falls back to its code constants byte-identically.
      */
     readonly artifactCoverage: GazetteerArtifactCoverage | undefined;
+    /**
+     * The ancestor lineage of a resolved place — nearest-first (locality-tier → county → region → … → country), the same
+     * order the FTS backend's `ancestorLineage` serves, read from the `candidate_ancestor` sidecar in one clustered
+     * probe. Backs `ResolveOpts.includeAncestors` (#404) on this backend, which is what puts region-class ancestry in
+     * front of the admin-coherence check (#1717).
+     *
+     * A PROPERTY, not a method, and assigned only when the artifact carries the sidecar: capability probes (`typeof
+     * backend.ancestors === "function"` — the resolver's gap report) then read the ARTIFACT truthfully. A candidate.db
+     * built before the sidecar reports the capability absent instead of presenting a method that answers `[]` for every
+     * place, which would be an absence dressed as a negative answer.
+     */
+    readonly ancestors: ((id: number | string) => Ancestor[]) | undefined;
     constructor(opts: WOFCandidateTableLookupOpts);
     findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>;
-    close(): void;
+    [Symbol.dispose](): void;
 }
-export {};
 //# sourceMappingURL=candidate-lookup.d.ts.map

package/out/candidate-lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-lookup.d.ts","sourceRoot":"","sources":["../candidate-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,OAAO,EAAyB,KAAK,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAG3F,OAAO,KAAK,EAAE,cAAc,EAAwC,MAAM,uBAAuB,CAAA;AAQjG,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAA;AAE3F,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;CACvB;AAED;;;GAGG;AACH,KAAK,YAAY,GAAG,IAAI,CACvB,cAAc,EACZ,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,cAAc,GACd,UAAU,GACV,WAAW,GACX,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,YAAY,GACZ,YAAY,CACd,GAMA,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC,CAAA;AAgD5C;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC,EAC7G,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,KAAK,SAA2B,GAC9B,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAkCrB;AAqBD;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,WAAW;;IAyB1D;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,yBAAyB,GAAG,SAAS,CAAA;gBASpD,IAAI,EAAE,2BAA2B;IA+FvC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAqWjE,KAAK,IAAI,IAAI;CAKb"}
+{"version":3,"file":"candidate-lookup.d.ts","sourceRoot":"","sources":["../lib/candidate-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAGN,KAAK,QAAQ,EACb,KAAK,yBAAyB,EAC9B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAU9C,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,mBAAmB,CAAA;AAShH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,QAAQ,CAAA;AAEvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IAC5C;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAiFD;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,WAAW,EAAE,UAAU;;IA6BtE;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,yBAAyB,GAAG,SAAS,CAAA;IAsChE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAA;gBAEzD,IAAI,EAAE,2BAA2B;IAsVvC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmYjE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB"}