@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/candidate/importance.js

@@ -3,42 +3,30 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The score side of the candidate build (#28) — load a WOF admin database's `place_importance` into
- *   a lookup the candidate builder can probe per place, so every candidate row can carry the
+ *   The score side of the candidate build: load a WOF admin database's `place_importance` into a
+ *   lookup the candidate builder probes per place, so every candidate row can include the
  *   toponym-fame prior a bare city name is decided on.
  *
- *   ## Why this joins on the NAME and not on the id
+ *   The join key is `(name_key, country, placetype)`, the same {@link normalizeLocalityForKey} the
+ *   candidate build uses for its probe key, so the two sides fold identically. An id join is wrong
+ *   here, because the score source (`admin-global-priority-importance.db`) and the candidate build's
+ *   admin source are different snapshots whose ids disagree. An id join silently drops rows and
+ *   leaves the ranking inert on the queries the prior exists for.
  *
- *   The obvious join is `candidate.spr_id = place_importance.id`, and it is wrong here. The score
- *   source (`admin-global-priority-importance.db`) and the candidate build's admin source are
- *   DIFFERENT SNAPSHOTS, and they disagree about ids for exactly the rows that matter: Whitby,
- *   Ontario is `8143502164401` in the shipped `candidate.db` and `8000001156384` in the score source
- *   — the Overture-sourced rows were re-keyed between the two. An id join silently drops every one of
- *   them, which means it drops precisely the FOREIGN HOMONYMS the fame prior exists to demote, and it
- *   drops them invisibly: the build succeeds, the column is populated, and the ranking is inert on
- *   the queries it was built for.
+ *   The key by itself is not enough. `(warwick, US, locality)` covers eleven different places.
+ *   The group's maximum would give every Warwick in America the fame of Warwick, Rhode Island.
+ *   The join picks the nearest centroid when it falls within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+ *   Two artifacts describing the same settlement put its centroid
+ *   in almost the same place. Two towns with the same name in one country do not.
  *
- *   So the join key is `(name_key, country, placetype)` — the same {@link normalizeLocalityForKey} the
- *   candidate build uses for its probe key, so the two sides fold identically by construction.
+ *   `place_importance.importance` lands in the column verbatim, the pre-split conflation that is
+ *   encyclopedia-derived where the concordance matched and a population-derived proxy everywhere
+ *   else. See {@link CandidateTable.importance} for why the split `encyclopedic` channel is not what
+ *   is written here.
  *
- *   ## Why the key alone is not enough
- *
- *   `(warwick, US, locality)` names ELEVEN different places. Taking the group's max would give every
- *   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_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
- *
- *   `place_importance.importance` VERBATIM — the pre-split conflation (encyclopedia-derived where
- *   the concordance matched, a population-derived proxy everywhere else). See
- *   {@link CandidateTable.importance} for why the split `encyclopedic` channel is deliberately NOT
- *   what is written here, with the measurement that settled it.
- *
- *   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.
+ *   A place with no match gets NULL. NULL means the place's fame is unmeasured.
+ *   The consumer (`resolver/toponym-prior.ts`) leaves an unmeasured candidate at the position
+ *   population assigned it.
  */
 import { haversineKm } from "@mailwoman/spatial";
 import { DatabaseClient } from "@mailwoman/sqlite/client";
@@ -46,26 +34,22 @@ 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.
  *
- * MEASURED, not guessed (2026-08-10, `admin-global-priority.db` × `admin-global-priority-importance.db`; 4,476,245
- * current locality-tier places against 676,790 scored ones, 1,020,099 of which matched a scored group by `(name_key,
- * 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.
+ * Measured from two admin snapshots.
+ * The nearest-centroid distances separate into a mode where the two snapshots agree
+ * and a background rate of two different towns wearing one name in one country.
  *
- * 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 background rate does not decay with distance.
+ * Ten kilometers separates the two populations.
  *
- * 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 radius is the definition
- * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * That distance matches the join's purpose.
+ * A radius above the floor starts handing one town's fame to another.
  */
 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.
+ * `(name_key, country, placetype)` → the scored places under it.
+ *
+ * The separator is U+0000, a character no WOF name contains and no fold can produce,
+ * so the three fields cannot smear into one another.
  */
 function groupKey(nameKey, country, placetype) {
     return `${nameKey}\u0000${(country ?? "").toUpperCase()}\u0000${placetype ?? ""}`;
@@ -81,11 +65,15 @@ export class ImportanceIndex {
      */
     matched = 0;
     /**
-     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+     * Places {@link find} refused.
+     *
+     * The key matched a scored group, but the nearest member 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 radius is too tight.
+     * 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 radius is too tight.
      */
     refused = 0;
     constructor(groups, stats) {
@@ -93,12 +81,15 @@ export class ImportanceIndex {
         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_RADIUS_KM}.
+     * 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_RADIUS_KM}.
+     *
+     * Null is unmeasured.
+     * Keep the value null.
+     * Do not substitute zero or a population-derived value here.
      *
-     * 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
-     * indistinguishable from a measurement.
+     * The source column already contains a population-derived fallback where one exists.
+     * A second fallback would make an absence indistinguishable from a measurement.
      */
     find(name, country, placetype, lat, lon) {
         const nameKey = normalizeLocalityForKey(name);
@@ -107,7 +98,7 @@ export class ImportanceIndex {
         const group = this.#groups.get(groupKey(nameKey, country, placetype));
         if (!group)
             return null;
-        let best;
+        let best = null;
         let bestKm = Infinity;
         for (const place of group) {
             const km = haversineKm(lat, lon, place.lat, place.lon);
@@ -125,16 +116,18 @@ export class ImportanceIndex {
     }
 }
 /**
- * Read `place_importance` (joined to `spr` for the name/country/placetype/centroid) out of a WOF admin database into an
- * {@link ImportanceIndex}.
+ * Read `place_importance` from a WOF admin database and join it to `spr`.
+ *
+ * The join retrieves each place's name, country, placetype, plus its centroid.
+ * These fields populate an {@link ImportanceIndex}.
+ *
+ * Only current, non-deprecated places are indexed.
+ * A superseded row's score belongs to a place the gazetteer no longer contains.
  *
- * Only CURRENT, non-deprecated places are indexed — a superseded row's score belongs to a place the gazetteer no longer
- * carries, and letting it win the nearest-centroid contest would hand a live place a dead one's fame.
+ * If that row won the nearest-centroid contest, a live place would inherit the superseded place's fame.
  *
- * The whole table is held in memory on purpose. The 2026-08-10 source holds 676,790 scored places in 544,823 groups,
- * and the build probes it once for every one of its ~4.8 M places; the alternative is a prepared statement per place
- * against a 3.7 GB database. Measured end to end, loading the index plus probing all 4.48 M locality-tier places takes
- * 25 s.
+ * The whole table is held in memory on purpose, because the build probes it once for every place
+ * and the alternative is a prepared statement per place against a multi-gigabyte database.
  */
 export function loadImportanceIndex(databasePath) {
     using db = new DatabaseClient(databasePath, { readOnly: true });

package/out/candidate/importance.js.map

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

package/out/candidate/lookup.d.ts

@@ -2,75 +2,38 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Node-side {@link PlaceLookup} over the byte-range CANDIDATE table (`build-candidate.ts`) — the
- *   SAME gazetteer the browser runtime resolves against ({@link WOFCandidateTableLookup} in
- *   `packages/resolver-wof-wasm/lib/httpvfs/resolver.ts`), but reading a LOCAL `candidate.db` via
- *   `node:sqlite` instead of sql.js-httpvfs. This is what makes the server/CLI resolver match the
- *   browser: one lookup surface, one artifact, one ranking.
- *
- *   The query is a single contiguous probe on the `WITHOUT ROWID` B-tree keyed `(name_key,
- *   country_id, region_id, placetype_id, neg_rank, spr_id)`. `name_key` is the SHARED
- *   {@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
- *   bare "Moscow" resolves to the 10.4 M-pop Russian city, not whichever same-name US township bm25
- *   floats to the top.
- *
- *   Disambiguation rides the same mechanism the cascade already uses: a parsed region resolves to its
- *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
- *   `bbox` field on {@link FindPlaceQuery}).
  */
+import type { VariantAliasExemption } from "@mailwoman/core/geocode";
 import { type Ancestor, type GazetteerArtifactCoverage } from "@mailwoman/core/resolver";
-import { DatabaseClient } from "@mailwoman/sqlite/client";
-import type { PathBuilderLike } from "path-ts";
+import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup";
 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?: PathBuilderLike;
-    /**
-     * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
-     */
-    database?: DatabaseClient<CandidateDatabase>;
+/**
+ * Where a {@link WOFCandidateTableLookup} reads from
+ * (a read-only `candidate.db` or a caller-held connection) and how it ranks.
+ */
+export interface WOFCandidateTableLookupOpts extends SQLiteLookupOptions<CandidateDatabase> {
     /**
-     * #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).
+     * Exempt `name_role = 'variant'` aliases from the cross-country primary-preference penalty.
+     *
+     * - No-ops without the role column.
+     * - `"not_applied"` penalizes variant aliases like any other.
+     *
+     * @defaultValue `"applied"`.
      */
-    variantAliasExemption?: boolean;
+    variantAliasExemption?: VariantAliasExemption;
 }
 /**
- * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSQLitePlaceLookup} in `createWOFResolver(backend)`
- * — same `findPlace` contract, population-first ranking.
+ * Node {@link PlaceLookup} over `candidate.db`.
  */
-export declare class WOFCandidateTableLookup implements PlaceLookup, Disposable {
+export declare class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> implements PlaceLookup {
     #private;
+    readonly artifactCoverage: GazetteerArtifactCoverage | null;
     /**
-     * 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 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.
+     * Ancestor lineage accessor, nearest-first, present only when the artifact supports it.
      */
     readonly ancestors: ((id: number | string) => Ancestor[]) | undefined;
     constructor(opts: WOFCandidateTableLookupOpts);
     findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>;
-    [Symbol.dispose](): void;
 }
 //# sourceMappingURL=lookup.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../lib/candidate/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,yBAAyB,EAA6B,MAAM,0BAA0B,CAAA;AAKnH,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;AAQhH,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;IAErE,YAAY,IAAI,EAAE,2BAA2B,EA+E5C;IAuQK,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAiYhE;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../lib/candidate/lookup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AACpE,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,yBAAyB,EAA6B,MAAM,0BAA0B,CAAA;AAMnH,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAUjF,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,mBAAmB,CAAA;AAQhH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,QAAQ,CAAA;AAEvF;;;GAGG;AACH,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB,CAAC,iBAAiB,CAAC;IAC1F;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;CAC7C;AA6CD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,YAAY,CAAC,iBAAiB,CAAE,YAAW,WAAW;;IAclG,QAAQ,CAAC,gBAAgB,EAAE,yBAAyB,GAAG,IAAI,CAAA;IAgB3D;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAA;IAErE,YAAY,IAAI,EAAE,2BAA2B,EA0D5C;IAkNK,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAyRhE;CACD"}