@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/place-importance-schema.js

@@ -2,39 +2,12 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The TWO-SCORE SPLIT (ROAD_TO_V9 §2 R1) — typed schema, table builder, and the two derivations, in
- *   one module so the read contract and the DDL cannot drift.
- *
- *   THE POLICY THIS ENCODES, ratified 2026-08-06: **the importance of a knowledge-base article is not
- *   the probability that this is the place the user means.** The geocoder ranks by REFERENTIAL
- *   likelihood; encyclopedic importance is carried as data and is never the ranking key. So the one
- *   `place_importance.importance` column — which was a Wikipedia score where the concordance join
- *   landed and a population-derived pseudo-score everywhere else — becomes two named columns that can
- *   never be confused for one another:
- *
- *   - {@link PlaceImportanceTable.referential} — population-anchored, ALWAYS derivable, the ranking
- *     backbone. {@link referentialFromPopulation} is the normalization the FST builder's population
- *     fallback has always used; naming it here is the whole change.
- *   - {@link PlaceImportanceTable.encyclopedic} — the fan-out-guarded Wikipedia join
- *     (`importance-fanout.ts`, #1497). NULLABLE, and null means ABSENT, never "an importance of
- *     zero": ~1.5 M of the 1.54 M rows in the 2026-08-05 build have no Wikipedia article at all, and
- *     a consumer that reads a 0 there would be reading a fact nobody recorded.
- *
- *   WHY SAINT-DENIS IS THE TEST. The Seine-Saint-Denis suburb (pop 96,128) carries encyclopedic
- *   0.1173; the Aude hamlet (pop 418) carries 0.5683 — the encyclopedic signal ranks the hamlet 4.8x
- *   ABOVE the place every user means. Referentially the suburb wins by 230x on population. One score
- *   cannot serve both readers, which is why there are two.
- *
- *   THE LEGACY COLUMN STAYS, AND IS DERIVED. `importance` is written by {@link blendImportance} — the
- *   bounded blend the bare-toponym fame consumer (#28) ranks on. It is the CONFLATION, and nothing new
- *   should read it; new code reads the split columns.
  */
 import { referentialFromPopulation } from "@mailwoman/core/resolver";
 import { allRows } from "@mailwoman/core/utils";
 /**
- * The columns in declaration order. The builder's INSERT derives its column list from this, so a field added to
- * {@link PlaceImportanceTable} without a matching DDL column is a compile error at the insert site.
+ * Lists the `place_importance` columns in declaration order, each checked
+ * against {@link PlaceImportanceTable}.
  */
 export const PLACE_IMPORTANCE_COLUMNS = [
     "id",
@@ -43,8 +16,7 @@ export const PLACE_IMPORTANCE_COLUMNS = [
     "importance",
 ];
 /**
- * Create `place_importance` at the split schema. Drops any existing table first — this is a rebuild-in-place step of
- * `mailwoman gazetteer importance`, never a migration.
+ * Drops and recreates the `place_importance` table with separate referential and encyclopedic columns.
  */
 export async function createPlaceImportanceTable(db) {
     await db.schema.dropTable("place_importance").ifExists().execute();
@@ -56,98 +28,43 @@ export async function createPlaceImportanceTable(db) {
         .addColumn("importance", "real", (c) => c.notNull())
         .execute();
 }
-//#endregion
-//#region The referential derivation
 /**
- * Re-exported from `@mailwoman/core/resolver`, which is where the derivation lives so that `@mailwoman/resolver`
- * (backend-agnostic — it cannot import this package) reads the same number. Re-exported HERE so the schema module stays
- * the one-stop read for the table: the column and the function that fills it are one hop apart.
- */
-//#endregion
-//#region The legacy blend
-/**
- * The most the encyclopedic channel may raise a place's blended importance above its population-anchored referential
- * score.
- *
- * In referential units 0.25 is 3.5 population doublings (the referential curve divides log2 by 14), so an article can
- * promote a place as if it were up to ~11x its recorded population — never more. The bound exists because the two
- * channels' scales CROSS at the article floor: merely having a Wikipedia article scores ~0.25–0.35, which exceeds the
- * referential score of a mid-size town, so an unbounded blend ranks a 136-person village with an article above a
- * 16,026-person town without one.
- *
- * The value is bracketed by two decided contests, measured on the 2026-08-24 staging build:
- *
- * - `> 0.2282`, or bare `Whitby` stops answering Whitby GB (pop 13,130, referential 0.2729, encyclopedic 0.5496) over
- *   Whitby CA (pop 128,377, referential 0.5011) — the #28 design case the fame prior exists to serve.
- * - `< 0.2790`, or bare `Tó`/`To` answers Tó PT (pop 136, referential 0.0131, encyclopedic 0.3375) over Tô BF (pop
- *   16,026, no article) — the `bf-gloss-to-*` board pair.
+ * Caps how far the encyclopedic score may raise a place's blended importance above its referential score.
  *
- * 0.25 sits mid-interval with ~0.02 margin to each bound.
+ * Merely having an article scores about 0.25 to 0.35, above a mid-size town's referential score,
+ * so without the cap a tiny village with an article outranks a large town without one.
  */
 export const ENCYCLOPEDIC_BOOST_CAP = 0.25;
 /**
- * The legacy `importance` blend — one cross-bearer fame scale for the #28 consumer, derived from the two split
- * channels:
- *
- * - No article → the referential score.
- * - No population evidence (`referential` 0) → the encyclopedic score stands alone: there is nothing to bound the
- *   article's claim against, and a constant cap would demote every famous place WOF records no population for
- *   (meaning-of-zero: referential 0 is "unmeasured", not "tiny").
- * - Both present → the encyclopedic value clamped to at most {@link ENCYCLOPEDIC_BOOST_CAP} above the referential score,
- *   and never below it. The floor half repairs the downward inversion (the Seine-Saint-Denis suburb's weak article
- *   scored 0.1173 and REPLACED its referential 0.4716 under the old `COALESCE`, so a 418-person Aude hamlet outranked
- *   it 4.8x); the cap half repairs the upward one (`Tó`, above).
- *
- * Scale of the clamp on the 2026-08-24 staging build: of 628,202 article-bearing rows, 209,738 sit above the cap and
- * 13,888 sit below their referential floor; the 305,168 article-without-population rows pass through unchanged.
+ * Blends the two channels into the legacy `importance` column: the referential score
+ * when there is no article, only the encyclopedic score when population is unknown
+ * (`referential` 0), and otherwise the encyclopedic score clamped between the
+ * referential score and {@link ENCYCLOPEDIC_BOOST_CAP} above it.
  */
 export function blendImportance(referential, encyclopedic) {
-    if (encyclopedic === null || encyclopedic === undefined)
+    if (encyclopedic === null)
         return referential;
     if (referential <= 0)
         return encyclopedic;
     return Math.max(referential, Math.min(encyclopedic, referential + ENCYCLOPEDIC_BOOST_CAP));
 }
-//#endregion
-//#region Reading a database that may or may not carry the split
 /**
- * Where a reader's two scores came from. Recorded into the FST stamp so an artifact says, in its own provenance,
- * whether its encyclopedic channel is real, reconstructed, or absent.
+ * Source names used by {@link loadImportanceSplit}.
+ * The FST stamp records these values as provenance.
  */
 export const IMPORTANCE_SPLIT_SOURCES = {
-    /**
-     * `place_importance` carries `referential` + `encyclopedic` — the post-split build.
-     */
     splitColumns: "split-columns",
-    /**
-     * `place_importance` carries only the conflated `importance`; the split was RECONSTRUCTED against `place_population`
-     * (see {@link splitLegacyImportance}).
-     */
     legacyReconstructed: "legacy-reconstructed",
-    /**
-     * No `place_importance` at all — referential from `place_population`, encyclopedic absent for every place.
-     */
     populationOnly: "population-only",
-    /**
-     * Neither table. Every score is 0, and 0 here means the database carries no salience evidence whatsoever.
-     */
     none: "none",
 };
 /**
- * The `SELECT` term and `LEFT JOIN` a name lookup needs in order to CARRY `encyclopedic` onto its results, probed
- * against `schemaName`'s `place_importance`.
- *
- * THE PROBE IS A COLUMN, NOT A TABLE, and that is the whole reason this lives here rather than beside a caller's other
- * table probes. The pre-split table exists and holds a single conflated `importance` column whose value is a Wikipedia
- * score on some rows and a population proxy on others, with nothing in the row to say which — reading that as
- * encyclopedic would surface the exact confusion ROAD_TO_V9 §2 exists to end.
+ * Returns the `select` term and `left join` that add `encyclopedic` to name-lookup results
+ * for `schemaName`, degrading to `NULL` and no join when the column is absent.
  *
- * There is deliberately no ORDER BY counterpart, and there should never be one: §2's policy is that this score is
- * carried and never ranked on. Without the column the select degrades to a literal `NULL` and the join is the empty
- * string, so a pre-split extract's query plan is byte-identical to what it was before the split. No shipped gazetteer
- * carries the column yet, so today that degraded form is the only one anything builds.
- *
- * Call it ONCE per extract and cache the result — it runs a `PRAGMA`, and the callers are per-keystroke hot.
+ * It probes for the column rather than the table, because a pre-split table's
+ * `importance` mixes Wikipedia and population scores.
+ * Cache the result per extract, since it runs a `PRAGMA` and lookups are per keystroke.
  */
 export function encyclopedicClauses(db, schemaName) {
     let present;
@@ -166,50 +83,26 @@ export function encyclopedicClauses(db, schemaName) {
     };
 }
 /**
- * The tolerance {@link splitLegacyImportance} treats as "this value reproduces the population curve". Eight ULP —
- * comfortably wider than the one-ULP `log2` spread measured between CPython and V8 (see that function's docstring), and
- * ~1e-15 absolute against scores Nominatim publishes to four decimals.
+ * Sets the relative tolerance within which {@link splitLegacyImportance} treats
+ * a value as lying on the population curve.
  */
 export const LEGACY_FALLBACK_EPSILON = 8 * Number.EPSILON;
 /**
- * Split one row of a LEGACY (pre-split) `place_importance` table back into its two components.
- *
- * WHY THIS IS RECOVERABLE AT ALL. The legacy builder ran in two passes: Wikipedia scores first, then `INSERT OR IGNORE`
- * of `min(1, log2(1+pop/1000)/14)` for every place with a population that Wikipedia had missed. So a legacy value is a
- * fallback row IFF it reproduces {@link referentialFromPopulation} of that place's population — the two passes wrote
- * different arithmetic, and a score from Nominatim's four-decimal TSV landing on the log2 curve is a measure-zero
- * event.
+ * Splits a legacy `place_importance` value into referential and encyclopedic scores,
+ * treating it as a population fallback when it matches {@link referentialFromPopulation}
+ * within {@link LEGACY_FALLBACK_EPSILON}.
  *
- * THE COMPARISON IS ULP-TOLERANT, AND THAT IS NOT DEFENSIVE PADDING. The first version compared for exact bit equality,
- * which is correct — in the runtime that wrote the values. Cross-checking the same rule in CPython returned 166,638
- * encyclopedic rows against Node's 133,096: `math.log2` and V8's `Math.log2` disagree by one ULP on 33,542 of the 1.5 M
- * inputs (worked example: wof 85803233, population 21,299 — stored 0.31992193633838988953, CPython
- * 0.31992193633838994504, delta 5.55e-17). Bit equality would therefore INVENT 33,542 encyclopedic scores for anyone
- * who ported this rule to another runtime, and invented data is the failure mode this whole module exists to end. The
- * tolerance is a few ULP of the score's own magnitude; a genuine Wikipedia value that close to the population curve is
- * not distinguishable from it by any consequence.
- *
- * MEASURED, not reasoned (2026-08-06, `wof/fst-staging-2026-08-05/admin-global-priority-importance.db`): 1,543,753 rows
- * split **1,410,657 fallback / 133,096 encyclopedic**, and the arithmetic closes on itself — 1,410,657 + 108,861
- * (encyclopedic rows that ALSO have a population) = 1,519,518, which is exactly the count of `place_population` rows
- * with `population > 0`, i.e. every row the fallback pass could have written. The remaining 24,235 encyclopedic rows
- * have no population row at all. Under the exact-equality rule, Node found ZERO mismatches within one ULP, so the
- * tolerance changes no classification on this database — it only makes the answer runtime-independent.
- *
- * Referential is NOT read out of the legacy column under any branch — it is always re-derived from population, because
- * a legacy Wikipedia row overwrote whatever population would have said.
+ * The match allows a small tolerance because `log2` differs by an ULP across runtimes.
+ * Bit equality would invent encyclopedic scores.
  */
 export function splitLegacyImportance(legacy, population) {
-    const referential = referentialFromPopulation(population);
-    if (legacy === undefined)
+    const referential = referentialFromPopulation(population ?? null);
+    if (legacy === null)
         return { referential };
     if (Math.abs(legacy - referential) <= LEGACY_FALLBACK_EPSILON * Math.max(referential, 1))
         return { referential };
     return { referential, encyclopedic: legacy };
 }
-/**
- * Does `table` exist in `db`, and if so which of `columns` does it have?
- */
 function tableColumns(db, table) {
     try {
         const rows = allRows(db.prepare(`PRAGMA table_info(${table})`));
@@ -220,11 +113,7 @@ function tableColumns(db, table) {
     }
 }
 /**
- * Load both scores from a WOF admin database, whatever schema generation it is at.
- *
- * Handles all four states in {@link IMPORTANCE_SPLIT_SOURCES} so callers never branch on schema themselves — the FST
- * builder in particular must read the shipped population-only databases, the read-only 2026-08-05 staging database
- * (legacy conflated column), and post-split builds with one code path.
+ * Loads both importance scores from a WOF admin database, whichever schema generation it uses.
  */
 export function loadImportanceSplit(db) {
     const referential = new Map();
@@ -243,9 +132,6 @@ export function loadImportanceSplit(db) {
     }
     const importanceColumns = tableColumns(db, "place_importance");
     if (importanceColumns.has("referential")) {
-        // Post-split build: the columns ARE the contract. Referential is read verbatim rather than
-        // re-derived, so a build that scored referential differently stays visible instead of being
-        // silently overwritten by this reader's own formula.
         const rows = allRows(db.prepare("SELECT id, referential, encyclopedic FROM place_importance"));
         for (const row of rows) {
             if (row.referential > 0) {
@@ -283,5 +169,4 @@ export function loadImportanceSplit(db) {
         legacyFallbackRows: 0,
     };
 }
-//#endregion
 //# sourceMappingURL=place-importance-schema.js.map

package/out/place-importance-schema.js.map

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

package/out/poi/lookup.d.ts

@@ -3,45 +3,34 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Node reader for `poi.db` (spec §3.4) — the res-9 k-ring reader over the clustered `poi`
- *   `WITHOUT ROWID` B-tree `poi-schema.ts` builds. Three search modes share one
- *   artifact:
+ *   Node reader for `poi.db` (spec §3.4), the res-9 k-ring reader over the clustered `poi`
+ *   `without rowid` B-tree `poi-schema.ts` builds. Category, brand and name searches share one
+ *   artifact. Each path has a method that returns its details.
  *
- *   - **Category**: `latLngToCell(center, 9)` → `gridDisk` ring-by-ring expansion, probing each
- *     cell's clustered `(h3_cell, category_id, neg_rank, …)` range. Rings accumulate until `limit`
- *     rows are on hand after a completed ring, or `maxRings` is exhausted; the pool is sorted by
- *     haversine distance from `center` after every ring.
- *   - **Brand**: NOT a k-ring walk. Brand rows are globally sparse (~0.31% of poi.db; median nearest
- *     tagged instance ~110 km), so ring expansion could never reach them. Instead a single brand-wide
- *     indexed fetch on `brand_wikidata` (the partial `poi_brand_wikidata` index) pulls EVERY row for
- *     the QID — category unconstrained — then haversine-sorts from `center` and takes the nearest
- *     `limit`, bounded by a `BRAND_MAX_DISTANCE_KM` sanity radius.
- *   - **Name**: FTS5 `MATCH` against the `poi_search` virtual table, hydrated back to full rows by
- *     `name_key`. No center required; if one is given, hits are still distance-sorted.
- *
- *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing that turns a raw H3
- *   cell into the integer `poi.h3_cell` stores is `@mailwoman/spatial`'s `shortCellToInt` — that math
- *   is NEVER reimplemented here (see AGENTS.md on `@mailwoman/spatial` being the one true home for
- *   it).
+ *   `latLngToCell` and `gridDisk` come from `h3-js`. The 48-bit short-cell packing that turns a raw
+ *   H3 cell into the integer `poi.h3_cell` stores is `@mailwoman/spatial`'s `shortCellToInt`, and
+ *   that math is never reimplemented here.
  */
-import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup";
 import type { POIDatabase } from "#poi/schema";
 /**
- * Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4).
+ * Resolution the `poi` table's `h3_cell` column is keyed at, matching the builder (spec §3.4).
  */
 export declare const POI_H3_RESOLUTION = 9;
 export interface POISearchQuery {
     /**
-     * Poi-taxonomy category id (string side of the dictionary). Ignored when `brandWikidata` is also set — brand wins.
-     */
-    categoryID?: string;
-    /**
-     * Fan-out category ids — the Overture `taxonomy.primary` leaves a single canonical category rolls up into (e.g.
-     * `supermarket` → `grocery_store`, `organic_grocery_store`, …). When set, the k-ring walk probes EVERY resolvable
-     * leaf per cell and unions the rows; unknown leaves are skipped. Supersedes `categoryID` (which is treated as a
-     * one-element list `[categoryID]` when this is absent). Ignored when `brandWikidata` is set — brand wins.
+     * Poi-taxonomy category ids (string side of the dictionary) to search.
+     *
+     * A single category is a one-element list.
+     * A canonical Overture `taxonomy.primary` category passes every leaf it rolls up into,
+     * as in `supermarket` → `grocery_store`, `organic_grocery_store`, ….
+     *
+     * The k-ring walk probes every resolvable leaf per cell and unions the rows.
+     * Unknown leaves are skipped.
+     *
+     * Ignored when `brandWikidata` is set, since brand wins.
      */
-    categoryIDs?: string[];
+    categoryIDs?: readonly string[];
     /**
      * Wikidata QID for brand-exact search.
      */
@@ -51,15 +40,20 @@ export interface POISearchQuery {
      */
     name?: string;
     /**
-     * Search center. Required for category/brand queries (k-ring expansion).
+     * Search center.
+     *
+     * Required for category/brand queries (k-ring expansion).
      */
     center?: {
         latitude: number;
         longitude: number;
     };
     /**
-     * Ring budget: how many res-9 k-rings to expand before giving up (default 16 ≈ ~5.4 km). Counts ring 0, so k reaches
-     * `maxRings - 1`.
+     * Ring budget: how many res-9 k-rings to expand before giving up.
+     *
+     * Counts ring 0, so k reaches `maxRings - 1`.
+     *
+     * @defaultValue `16` ≈ ~5.4 km
      */
     maxRings?: number;
     limit?: number;
@@ -73,28 +67,27 @@ export interface POISearchHit {
     country: string;
     confidence: number;
     /**
-     * Overture GERS id — nullable METADATA ONLY, never a key (the #470 rule; see `POITable.gers_id`).
+     * Overture gers id.
+     *
+     * Nullable metadata, never a key.
+     * See `POITable.gers_id`.
      */
     gersID: string | null;
-    distanceM?: number;
-}
-export interface POILookupOpts<DB extends POIDatabase = POIDatabase> {
-    /**
-     * Path to a `poi.db` built by the (future) POI builder. Opened read-only.
-     */
-    databasePath?: string;
-    /**
-     * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
-     */
-    database?: DatabaseClient<DB>;
+    distanceM: number | null;
 }
+/**
+ * Where a {@link POILookup} reads from.
+ *
+ * The source is a `poi.db` built by the POI builder, opened read-only,
+ * or a connection the caller already holds.
+ */
+export type POILookupOpts<DB extends POIDatabase = POIDatabase> = SQLiteLookupOptions<DB>;
 /**
  * Node reader over `poi.db`.
  */
-export declare class POILookup<DB extends POIDatabase = POIDatabase> implements Disposable {
+export declare class POILookup<DB extends POIDatabase = POIDatabase> extends SQLiteLookup<DB> {
     #private;
     constructor(opts: POILookupOpts<DB>);
     search(query: POISearchQuery): POISearchHit[];
-    [Symbol.dispose](): void;
 }
 //# sourceMappingURL=lookup.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../lib/poi/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAGzD,OAAO,KAAK,EAAwB,WAAW,EAAY,MAAM,aAAa,CAAA;AAC9E;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AA8BlC,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,aAAa,CAAC,EAAE,SAAS,WAAW,GAAG,WAAW;IAClE;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,CAAA;CAC7B;AAkBD;;GAEG;AACH,qBAAa,SAAS,CAAC,EAAE,SAAS,WAAW,GAAG,WAAW,CAAE,YAAW,UAAU;;IAuBjF,YAAY,IAAI,EAAE,aAAa,CAAC,EAAE,CAAC,EA2BlC;IAED,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,EAAE,CAsB5C;IAwID,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../lib/poi/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAGjF,OAAO,KAAK,EAAwB,WAAW,EAAY,MAAM,aAAa,CAAA;AAC9E;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AA8BlC,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,WAAW,GAAG,WAAW,IAAI,mBAAmB,CAAC,EAAE,CAAC,CAAA;AAkBzF;;GAEG;AACH,qBAAa,SAAS,CAAC,EAAE,SAAS,WAAW,GAAG,WAAW,CAAE,SAAQ,YAAY,CAAC,EAAE,CAAC;;IAkBpF,YAAY,IAAI,EAAE,aAAa,CAAC,EAAE,CAAC,EAuBlC;IAED,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,EAAE,CAoB5C;CA4ID"}