@mailwoman/resolver-wof-sqlite 9.1.0 → 9.2.0

package/out/polygon-schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the polygon sidecar (`wof-polygons.db`) — the one table `WOFReverseGeocoder` probes for a
+ *   place's geometry. The interface is the read/write contract and {@link createPolygonsTable} creates the table, so a
+ *   column added to one is a compile error against the other.
+ *
+ *   The sidecar is OPTIONAL to the reverse geocoder: without it every result falls back to a centroid, so the reader
+ *   checks for the table's presence rather than assuming it.
+ */
+import type { Kysely } from "kysely";
+/**
+ * One admin polygon, keyed by WOF id.
+ */
+export interface PolygonsTable {
+    id: number;
+    /**
+     * The GeoJSON geometry, JSON-encoded. A row that fails to parse reads as no-polygon, never as an error — a malformed
+     * geometry must not fail the whole reverse query.
+     */
+    geom: string;
+}
+export interface PolygonDatabase {
+    polygons: PolygonsTable;
+}
+/**
+ * The slice of a Kysely handle the polygon DDL touches. Kysely is invariant in its schema parameter, so naming only
+ * `schema` lets a builder holding a wider handle pass it without a cast.
+ */
+export type PolygonSchemaHandle = Pick<Kysely<PolygonDatabase>, "schema">;
+/**
+ * Create the `polygons` table — called before the streaming bulk load.
+ */
+export declare function createPolygonsTable(db: PolygonSchemaHandle): Promise<void>;
+//# sourceMappingURL=polygon-schema.d.ts.map

package/out/polygon-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon-schema.d.ts","sourceRoot":"","sources":["../polygon-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,aAAa,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAA;AAEzE;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhF"}

package/out/polygon-schema.js

@@ -0,0 +1,23 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the polygon sidecar (`wof-polygons.db`) — the one table `WOFReverseGeocoder` probes for a
+ *   place's geometry. The interface is the read/write contract and {@link createPolygonsTable} creates the table, so a
+ *   column added to one is a compile error against the other.
+ *
+ *   The sidecar is OPTIONAL to the reverse geocoder: without it every result falls back to a centroid, so the reader
+ *   checks for the table's presence rather than assuming it.
+ */
+/**
+ * Create the `polygons` table — called before the streaming bulk load.
+ */
+export async function createPolygonsTable(db) {
+    await db.schema
+        .createTable("polygons")
+        .addColumn("id", "integer", (column) => column.primaryKey())
+        .addColumn("geom", "text", (column) => column.notNull())
+        .execute();
+}
+//# sourceMappingURL=polygon-schema.js.map

package/out/polygon-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polygon-schema.js","sourceRoot":"","sources":["../polygon-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAuB;IAChE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,UAAU,CAAC;SACvB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;SAC3D,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;SACvD,OAAO,EAAE,CAAA;AACZ,CAAC"}

package/out/postal-city-alias-lookup.d.ts

@@ -5,7 +5,7 @@
  *
  *   Node reader over the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`) — the observed
  *   `postal_city → geo_locality` aliases per postcode (`build-postal-city-alias.ts`). Consumed by
- *   {@link WOFSqlitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
+ *   {@link WOFSQLitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
  *   ("Antioch", postcode 37013) becomes a name-match alias for the geographic locality the postcode
  *   actually sits in ("Nashville"), so the right place tiers to the top instead of a same-named
  *   town in another state. Opt-in — the lookup is only constructed when a path is supplied, and

package/out/postal-city-alias-lookup.js

@@ -5,7 +5,7 @@
  *
  *   Node reader over the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`) — the observed
  *   `postal_city → geo_locality` aliases per postcode (`build-postal-city-alias.ts`). Consumed by
- *   {@link WOFSqlitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
+ *   {@link WOFSQLitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
  *   ("Antioch", postcode 37013) becomes a name-match alias for the geographic locality the postcode
  *   actually sits in ("Nashville"), so the right place tiers to the top instead of a same-named
  *   town in another state. Opt-in — the lookup is only constructed when a path is supplied, and

package/out/postal-city-candidate-schema.d.ts

@@ -18,6 +18,7 @@
  *   untouched.
  */
 import { type Kysely } from "kysely";
+import type { NameKey } from "./street-normalize.ts";
 /**
  * One postal-city → geo-locality edge, keyed exactly by `(name_key, postcode)`. The probe returns the geographic
  * locality directly; the denormalized name/coord avoid a join back to `candidate`.
@@ -26,7 +27,7 @@ export interface PostalCityCandidateTable {
     /**
      * {@link normalizeLocalityForKey} of the postal-city name — the build/query-consistent probe key.
      */
-    name_key: string;
+    name_key: NameKey;
     /**
      * The postcode the alias is scoped to (the second half of the exact key).
      */

package/out/postal-city-candidate-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postal-city-candidate-schema.d.ts","sourceRoot":"","sources":["../postal-city-candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEzC;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,qBAAqB,EAAE,wBAAwB,CAAA;CAC/C;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,0BAA0B,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,6BAA6B,8EAOhC,CAAA;AAEV;;;;GAIG;AACH,wBAAsB,8BAA8B,CAAC,EAAE,EAAE,MAAM,CAAC,2BAA2B,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAc3G"}
+{"version":3,"file":"postal-city-candidate-schema.d.ts","sourceRoot":"","sources":["../postal-city-candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAEpD;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,qBAAqB,EAAE,wBAAwB,CAAA;CAC/C;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,0BAA0B,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,6BAA6B,8EAOhC,CAAA;AAEV;;;;GAIG;AACH,wBAAsB,8BAA8B,CAAC,EAAE,EAAE,MAAM,CAAC,2BAA2B,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAc3G"}

package/out/postal-city-candidate-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"postal-city-candidate-schema.js","sourceRoot":"","sources":["../postal-city-candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,GAAG,EAAe,MAAM,QAAQ,CAAA;AAkCzC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,uBAAuB,CAAA;AAElE;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC5C,UAAU;IACV,UAAU;IACV,QAAQ;IACR,MAAM;IACN,UAAU;IACV,WAAW;CACF,CAAA;AAEV;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAAC,EAAuC;IAC3F,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,2BAA2B,CAAC;SACxC,WAAW,EAAE;SACb,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,uBAAuB,CAAC,0BAA0B,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC9E,0FAA0F;SACzF,SAAS,CAAC,GAAG,CAAA,eAAe,CAAC;SAC7B,OAAO,EAAE,CAAA;AACZ,CAAC"}
+{"version":3,"file":"postal-city-candidate-schema.js","sourceRoot":"","sources":["../postal-city-candidate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,GAAG,EAAe,MAAM,QAAQ,CAAA;AAoCzC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,uBAAuB,CAAA;AAElE;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC5C,UAAU;IACV,UAAU;IACV,QAAQ;IACR,MAAM;IACN,UAAU;IACV,WAAW;CACF,CAAA;AAEV;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAAC,EAAuC;IAC3F,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,2BAA2B,CAAC;SACxC,WAAW,EAAE;SACb,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,uBAAuB,CAAC,0BAA0B,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC9E,0FAA0F;SACzF,SAAS,CAAC,GAAG,CAAA,eAAe,CAAC;SAC7B,OAAO,EAAE,CAAA;AACZ,CAAC"}

package/out/postcode-point-lookup.d.ts

@@ -13,7 +13,7 @@
  *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
  *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` seam.
  *
- *   Why multiple shards instead of the multi-shard `WOFSqlitePlaceLookup`: that resolver routes a
+ *   Why multiple shards instead of the multi-shard `WOFSQLitePlaceLookup`: that resolver routes a
  *   query to ONE shard by placetype, but every postcode shard shares `placetype='postalcode'`, so a
  *   single query could only ever hit one country's shard. The anchor needs the union across
  *   countries to build its country posterior, so it queries each shard directly.

package/out/postcode-point-lookup.js

@@ -13,7 +13,7 @@
  *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
  *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` seam.
  *
- *   Why multiple shards instead of the multi-shard `WOFSqlitePlaceLookup`: that resolver routes a
+ *   Why multiple shards instead of the multi-shard `WOFSQLitePlaceLookup`: that resolver routes a
  *   query to ONE shard by placetype, but every postcode shard shares `placetype='postalcode'`, so a
  *   single query could only ever hit one country's shard. The anchor needs the union across
  *   countries to build its country posterior, so it queries each shard directly.

package/out/primary-preference.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Bounded cross-country PRIMARY-NAME preference over a population-ordered candidate row set — the
+ *   `is_primary` ranking signal, PURE and platform-free so the Node candidate lookup
+ *   (`candidate-lookup.ts`) and the browser twin (`docs/src/shared/httpvfs-resolver.ts`) rank with the
+ *   SAME function rather than two copies that drift (the #861 server↔demo parity contract).
+ *
+ *   Only type imports and arithmetic live here: anything with a `node:` import stays out.
+ */
+import type { CandidateTable } from "./candidate-schema.ts";
+/**
+ * The row shape the re-rank needs. `is_primary` is optional: a reader over an artifact vintage that predates the column
+ * omits it from the SELECT, no row reads as primary, and the re-rank no-ops by construction — the exact degradation the
+ * browser reader's vintage guard relies on.
+ */
+export type PrimaryPreferenceRow = Pick<CandidateTable, "neg_rank" | "country_id"> & Partial<Pick<CandidateTable, "is_primary" | "placetype_id" | "population" | "name_role">>;
+/**
+ * Bounded PRIMARY-NAME preference across a CROSS-COUNTRY name collision (the `is_primary` ranking signal).
+ *
+ * The raw candidate order is population-first (`neg_rank ASC`) and treats an ALIAS row (a place's alt-name / exonym,
+ * `is_primary=0`) and a PRIMARY-name row (`is_primary=1`) on equal footing. So a foreign place whose transliterated
+ * exonym coincidentally normalizes to a query — Changchun CN stores the Turkish exonym "Çançun" (`name_key="cancun"`),
+ * 4.19 M pop — outranks the PRIMARY-name place the query actually means (Cancún MX, 0.89 M pop). This penalty makes a
+ * same-key alias have to clear a population MARGIN over a foreign primary before it wins.
+ *
+ * It is deliberately NOT a dominant sort key (no `ORDER BY is_primary DESC`, which would make every primary outrank
+ * every alias and break the alt-names users depend on — "NYC"→New York, "LA"→Los Angeles, "Frisco"→San Francisco). Two
+ * bounds keep it a soft prior:
+ *
+ * 1. **Cross-country only.** The penalty applies to an alias ONLY when the top-population primary sharing the key is in a
+ *    DIFFERENT country. A SAME-country nickname contest (San Francisco's alias "Frisco" vs the primary Frisco, TX —
+ *    both US) is left on pure population, so the legitimate alias still wins.
+ * 2. **Population-bounded.** The penalty is {@link PRIMARY_PREFERENCE_LOG10} in log10-population units — an alias must be
+ *    at least 10x more populous than the foreign primary to still win. So a genuinely dominant alias keeps winning
+ *    ("Los Angeles" over La, Ghana — gap 1.6; "Las Vegas" over Vegas, Cuba — gap 2.4) while a near-tie coincidental
+ *    collision defers to the primary (Cancún over Changchun — gap 0.7).
+ */
+export declare const PRIMARY_PREFERENCE_LOG10 = 1;
+/**
+ * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
+ * worldwide) are re-ranked in-process, so the probe fetches this many (population-ordered) before the re-rank rather
+ * than the caller's small `limit`, ensuring the intended primary isn't cut below the fold by a cluster of more-populous
+ * foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ */
+export declare const RERANK_FETCH = 64;
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * The admin-containment verdict (#1717 stage 2), stamped by `candidate-lookup.ts` when the query carried a
+     * `regionQualifier` and the artifact carries the ancestors sidecar — the `fuzzy` precedent: a lookup-tier annotation
+     * declared on the shared row shape. Tri-state like `ResolvedPlace.containedByQualifier`: absent means the question
+     * was never asked, never "not contained".
+     */
+    containedByQualifier?: 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.
+ *
+ * `placetypes` (the artifact's own `placetype_codes` map) enables the LAST tiebreak, the SEAT preference: when
+ * `effectiveNegRank` and raw `neg_rank` both tie — two same-key rows population cannot separate at all — a
+ * {@link SEAT_PLACETYPE} row carrying a real population outranks every other placetype. Omit the map and every row
+ * scores 0, the term cancels, and the order is exactly the population-then-scan-order it was before.
+ *
+ * The tie it exists for is a DUPLICATE, not a contest. A district and its identically-named seat town are stored as two
+ * rows carrying the SAME population, so `neg_rank` is equal to the bit and `referential` follows it
+ * (`referentialFromPopulation` is a pure function of population). Turkey's `Of` is the measured case — locality
+ * 8114738869649 and its parent county 8837168432019 both hold population 44212 — and 358 locality/parent-county pairs
+ * across 15 countries share the shape in `admin-global-priority.db` (TR 162, CA 77, US 47, HR 24, DO 14). Without the
+ * term their order is whatever the scan hands the sorter.
+ *
+ * WHERE THE TERM DECIDES, AND WHERE IT CANNOT (#1729). It binds inside `findPlace`, so it orders every row set that
+ * actually CONTAINS the tie — but the resolver walk's probes all carry a placetype filter, and
+ * `PLACETYPE_FILTER_GROUPS` (core/resolver) never mixes `locality` with `county`: the `Of`-shape locality/county pair
+ * is PARTITIONED before this ranker runs, the locality probe fetches one row, and the walk's own `locality` request
+ * selects the seat by construction — the same winner, decided upstream. The tie that reaches an end-to-end answer
+ * through this term is the IN-GROUP residue: a locality/localadmin (or borough) duplicate whose `importance` values
+ * also tie. Downstream the resolver re-sorts by importance (`resolver/toponym-prior.ts`) but is stable on equal keys,
+ * so the order stamped here is the order that answers — inverting this term moves bare `Pu-cheng-hsien` 1,100 km
+ * (locality Pucheng over the 浦城县 localadmin, identical population and importance). Where importance separates the pair,
+ * the fame prior overrides by design; a probe with NO placetype filter (the browser cascade's last resort, the dev
+ * lookup tools) presents the full tie and this term is all that breaks it.
+ *
+ * BOTH GATES ARE LOAD-BEARING, and a plain "finer placetype wins" measured wrong before this shape was settled: it
+ * moved the top slot on 11,377 keys in `candidate.db`, of which only 722 were the seat/district duplicate. The rest
+ * were contests between genuinely distinct places that merely tie — 2,885 `locality → neighbourhood` (a bare city name
+ * losing to a same-named hood), 2,973 `region → county`, 2,662 `postalcode → locality` — and 7,179 of the 11,377 sat at
+ * population 0, where a tie means NO EVIDENCE rather than equal evidence. Requiring a real population keeps the term
+ * off every no-evidence tie; promoting the populated-place tier specifically, rather than whatever is finer, keeps it
+ * off the admin-tier and hood contests. It can never reach a pair population separates: it does not override a
+ * population gap, it replaces an undetermined order with a stated one.
+ */
+export declare function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(rows: readonly R[], limit: number, delta?: number, placetypes?: ReadonlyMap<number, string>, exemptVariantAliases?: boolean): Array<RankedRow<R>>;
+//# sourceMappingURL=primary-preference.d.ts.map

package/out/primary-preference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primary-preference.d.ts","sourceRoot":"","sources":["../primary-preference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAE3D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,YAAY,CAAC,GACjF,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,CAAC,CAAC,CAAA;AAE1F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AASzC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,KAAK,CAAA;AAE9B;;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;IACf;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC9B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,oBAAoB,EACrE,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,KAAK,SAA2B,EAChC,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,oBAAoB,UAAQ,GAC1B,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CA+DrB"}

package/out/primary-preference.js

@@ -0,0 +1,138 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Bounded cross-country PRIMARY-NAME preference over a population-ordered candidate row set — the
+ *   `is_primary` ranking signal, PURE and platform-free so the Node candidate lookup
+ *   (`candidate-lookup.ts`) and the browser twin (`docs/src/shared/httpvfs-resolver.ts`) rank with the
+ *   SAME function rather than two copies that drift (the #861 server↔demo parity contract).
+ *
+ *   Only type imports and arithmetic live here: anything with a `node:` import stays out.
+ */
+/**
+ * Bounded PRIMARY-NAME preference across a CROSS-COUNTRY name collision (the `is_primary` ranking signal).
+ *
+ * The raw candidate order is population-first (`neg_rank ASC`) and treats an ALIAS row (a place's alt-name / exonym,
+ * `is_primary=0`) and a PRIMARY-name row (`is_primary=1`) on equal footing. So a foreign place whose transliterated
+ * exonym coincidentally normalizes to a query — Changchun CN stores the Turkish exonym "Çançun" (`name_key="cancun"`),
+ * 4.19 M pop — outranks the PRIMARY-name place the query actually means (Cancún MX, 0.89 M pop). This penalty makes a
+ * same-key alias have to clear a population MARGIN over a foreign primary before it wins.
+ *
+ * It is deliberately NOT a dominant sort key (no `ORDER BY is_primary DESC`, which would make every primary outrank
+ * every alias and break the alt-names users depend on — "NYC"→New York, "LA"→Los Angeles, "Frisco"→San Francisco). Two
+ * bounds keep it a soft prior:
+ *
+ * 1. **Cross-country only.** The penalty applies to an alias ONLY when the top-population primary sharing the key is in a
+ *    DIFFERENT country. A SAME-country nickname contest (San Francisco's alias "Frisco" vs the primary Frisco, TX —
+ *    both US) is left on pure population, so the legitimate alias still wins.
+ * 2. **Population-bounded.** The penalty is {@link PRIMARY_PREFERENCE_LOG10} in log10-population units — an alias must be
+ *    at least 10x more populous than the foreign primary to still win. So a genuinely dominant alias keeps winning
+ *    ("Los Angeles" over La, Ghana — gap 1.6; "Las Vegas" over Vegas, Cuba — gap 2.4) while a near-tie coincidental
+ *    collision defers to the primary (Cancún over Changchun — gap 0.7).
+ */
+export const PRIMARY_PREFERENCE_LOG10 = 1;
+/**
+ * The placetype the seat preference promotes: the populated-place tier a district duplicate shares its name and its
+ * population with. Named rather than inlined because narrowing the term to this ONE tier is what keeps it off the
+ * region/county and locality/neighbourhood contests — see `rankByPrimaryPreference` for the measurement.
+ */
+const SEAT_PLACETYPE = "locality";
+/**
+ * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
+ * worldwide) are re-ranked in-process, so the probe fetches this many (population-ordered) before the re-rank rather
+ * than the caller's small `limit`, ensuring the intended primary isn't cut below the fold by a cluster of more-populous
+ * foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ */
+export const RERANK_FETCH = 64;
+/**
+ * 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.
+ *
+ * `placetypes` (the artifact's own `placetype_codes` map) enables the LAST tiebreak, the SEAT preference: when
+ * `effectiveNegRank` and raw `neg_rank` both tie — two same-key rows population cannot separate at all — a
+ * {@link SEAT_PLACETYPE} row carrying a real population outranks every other placetype. Omit the map and every row
+ * scores 0, the term cancels, and the order is exactly the population-then-scan-order it was before.
+ *
+ * The tie it exists for is a DUPLICATE, not a contest. A district and its identically-named seat town are stored as two
+ * rows carrying the SAME population, so `neg_rank` is equal to the bit and `referential` follows it
+ * (`referentialFromPopulation` is a pure function of population). Turkey's `Of` is the measured case — locality
+ * 8114738869649 and its parent county 8837168432019 both hold population 44212 — and 358 locality/parent-county pairs
+ * across 15 countries share the shape in `admin-global-priority.db` (TR 162, CA 77, US 47, HR 24, DO 14). Without the
+ * term their order is whatever the scan hands the sorter.
+ *
+ * WHERE THE TERM DECIDES, AND WHERE IT CANNOT (#1729). It binds inside `findPlace`, so it orders every row set that
+ * actually CONTAINS the tie — but the resolver walk's probes all carry a placetype filter, and
+ * `PLACETYPE_FILTER_GROUPS` (core/resolver) never mixes `locality` with `county`: the `Of`-shape locality/county pair
+ * is PARTITIONED before this ranker runs, the locality probe fetches one row, and the walk's own `locality` request
+ * selects the seat by construction — the same winner, decided upstream. The tie that reaches an end-to-end answer
+ * through this term is the IN-GROUP residue: a locality/localadmin (or borough) duplicate whose `importance` values
+ * also tie. Downstream the resolver re-sorts by importance (`resolver/toponym-prior.ts`) but is stable on equal keys,
+ * so the order stamped here is the order that answers — inverting this term moves bare `Pu-cheng-hsien` 1,100 km
+ * (locality Pucheng over the 浦城县 localadmin, identical population and importance). Where importance separates the pair,
+ * the fame prior overrides by design; a probe with NO placetype filter (the browser cascade's last resort, the dev
+ * lookup tools) presents the full tie and this term is all that breaks it.
+ *
+ * BOTH GATES ARE LOAD-BEARING, and a plain "finer placetype wins" measured wrong before this shape was settled: it
+ * moved the top slot on 11,377 keys in `candidate.db`, of which only 722 were the seat/district duplicate. The rest
+ * were contests between genuinely distinct places that merely tie — 2,885 `locality → neighbourhood` (a bare city name
+ * losing to a same-named hood), 2,973 `region → county`, 2,662 `postalcode → locality` — and 7,179 of the 11,377 sat at
+ * population 0, where a tie means NO EVIDENCE rather than equal evidence. Requiring a real population keeps the term
+ * off every no-evidence tie; promoting the populated-place tier specifically, rather than whatever is finer, keeps it
+ * off the admin-tier and hood contests. It can never reach a pair population separates: it does not override a
+ * population gap, it replaces an undetermined order with a stated one.
+ */
+export function rankByPrimaryPreference(rows, limit, delta = PRIMARY_PREFERENCE_LOG10, placetypes, exemptVariantAliases = false) {
+    // The primary the alias actually competes with for the top slot: highest population (min neg_rank). Undefined
+    // when the set has no primary → nothing to prefer, penalty is 0, order stays population-first (today's behavior).
+    let topPrimary;
+    for (const r of rows) {
+        if (r.is_primary === 1 && (topPrimary == null || r.neg_rank < topPrimary.neg_rank)) {
+            topPrimary = r;
+        }
+    }
+    const topCountry = topPrimary?.country_id;
+    // A cross-country alias (different country than the top primary) is penalized; it is DEMOTED when even after — i.e.
+    // the penalty leaves its effective rank behind the primary's raw rank (it lost the bounded population contest).
+    //
+    // #1882 exemption (opt-in): a `name_role = 'variant'` alias is the holder's OWN primary name in another
+    // orthography (`Брэст` → `brest`, `George Town` → `georgetown` — the build's own-name detector), so the
+    // query is naming THAT place, not colliding with it; the penalty exists for the coincidental-collision
+    // class ("Çançun"/`cancun`), which the detector's measured threshold keeps un-stamped. An artifact
+    // predating the role column carries no 'variant' rows, so the flag no-ops there by construction.
+    const isCrossCountryAlias = (r) => typeof topCountry === "number" &&
+        r.is_primary !== 1 &&
+        r.country_id !== topCountry &&
+        !(exemptVariantAliases && r.name_role === "variant");
+    const annotate = (r) => {
+        const penalized = isCrossCountryAlias(r);
+        const effectiveNegRank = r.neg_rank + (penalized ? delta : 0);
+        return { ...r, effectiveNegRank, demoted: penalized && effectiveNegRank > topPrimary.neg_rank };
+    };
+    // 1 for a populated-place row that can BE a district's seat, 0 for everything else — no code map, no
+    // placetype on the row, an id the map does not carry, a placetype that is not the seat tier, or no
+    // recorded population. Every row scoring 0 cancels the term, leaving exactly the
+    // population-then-scan-order the sort had before it existed.
+    const seatPreference = (r) => placetypes != null &&
+        typeof r.placetype_id === "number" &&
+        typeof r.population === "number" &&
+        r.population > 0 &&
+        placetypes.get(r.placetype_id) === SEAT_PLACETYPE
+        ? 1
+        : 0;
+    return (rows
+        .map((r, i) => ({ row: annotate(r), i }))
+        // Effective rank ASC; ties keep population order, then the seat preference DESC, then original
+        // index (stable).
+        // oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+        .sort((a, b) => a.row.effectiveNegRank - b.row.effectiveNegRank ||
+        a.row.neg_rank - b.row.neg_rank ||
+        seatPreference(b.row) - seatPreference(a.row) ||
+        a.i - b.i)
+        .slice(0, limit)
+        .map((x) => x.row));
+}
+//# sourceMappingURL=primary-preference.js.map

package/out/primary-preference.js.map

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

package/out/proximity-rerank.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The proximity re-rank (#938): with bias hints — the demo's map viewport, a user location — re-order exact-match
+ *   candidates by population and nearness on one additive scale, so an in-view namesake wins a tie without a hard
+ *   filter. Byte-identical to plain population order when no bias is passed.
+ *
+ *   This lives in its own platform-free module because it has to run identically in two places: the Node candidate
+ *   reader and the browser byte-range twin. That is the #861 server↔demo parity contract, and it is the second thing
+ *   here held by construction rather than by comment (`primary-preference.ts` was the first). Constants alone were not
+ *   enough — the two copies agreed on every literal and still diverged on which field the population term reads and on
+ *   whether the combined value is written back, which is the half that actually decides the answer.
+ *
+ *   Two properties are load-bearing and easy to lose when transcribing:
+ *
+ *   1. The population base is `prominence ?? score`, NOT `score`. `prominence` carries the bounded cross-country
+ *      primary preference, so reading raw score lets a coincidental foreign alias ride population back over a primary
+ *      whenever a viewport hint happens to be present.
+ *   2. The combined value is PERSISTED into `prominence`. The resolver walk re-sorts by `prominence ?? score`, so a
+ *      caller that only returns the array in bias order has its ordering silently discarded downstream.
+ */
+/**
+ * Full magnitude of the nearness term at distance 0, before decay.
+ */
+export declare const BIAS_BOOST = 4;
+/**
+ * Full magnitude of the population term, reached at {@link POP_SCALE_LOG10} and capped there.
+ */
+export declare const POP_BOOST = 4;
+/**
+ * `log10(population + 1)` at which the population term saturates — 6 means a population of one million earns the whole
+ * {@link POP_BOOST}, and larger populations earn no more.
+ */
+export declare const POP_SCALE_LOG10 = 6;
+/**
+ * Distance at which the nearness term halves.
+ *
+ * SHARPER than the FTS reader's 100 km on purpose: the candidate backend's score is log-population ALONE, with no bm25
+ * document term, so the population signal is weaker relative to the bias and a gentle 100 km decay let a 230 km-distant
+ * alias-exact township ("Paris Township", OH) edge out a global city ("Paris", FR) from a nearby view. At ~30 km the
+ * boost reaches only candidates the user is actually looking at: an in-view namesake still wins (Dublin, OH from an
+ * Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
+ */
+export declare const PROX_SCALE_KM = 30;
+/**
+ * One bias hint — a coordinate the user is looking at or standing on, optionally weighted.
+ */
+export interface ProximityBias {
+    lat: number;
+    lon: number;
+    weight?: number;
+}
+/**
+ * The candidate fields the re-rank reads and writes. Structural rather than a concrete candidate type, so the Node
+ * reader's `PlaceCandidate` and the browser twin's row shape both satisfy it without an adapter.
+ */
+export interface ProximityRerankable {
+    lat: number;
+    lon: number;
+    score: number;
+    prominence?: number;
+}
+/**
+ * Population plus nearness on one additive scale. Exported for tests and for a caller that wants the value without the
+ * sort; ordinary callers want {@link applyProximityRerank}.
+ */
+export declare function combinedProminence(candidate: ProximityRerankable, bias: readonly ProximityBias[]): number;
+/**
+ * Re-order `candidates` in place by {@link combinedProminence}, persisting each combined value into `prominence` so the
+ * resolver walk's own `prominence ?? score` sort carries the bias order rather than undoing it. Stable within equal
+ * prominence, preserving the population order the index already gave. A caller with no bias hints must not call this —
+ * the no-bias path is plain population order by construction.
+ */
+export declare function applyProximityRerank<T extends ProximityRerankable>(candidates: T[], bias: readonly ProximityBias[]): T[];
+//# sourceMappingURL=proximity-rerank.d.ts.map

package/out/proximity-rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proximity-rerank.d.ts","sourceRoot":"","sources":["../proximity-rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;GAEG;AACH,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;GAEG;AACH,eAAO,MAAM,SAAS,IAAI,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,KAAK,CAAA;AAE/B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAmBzG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,mBAAmB,EACjE,UAAU,EAAE,CAAC,EAAE,EACf,IAAI,EAAE,SAAS,aAAa,EAAE,GAC5B,CAAC,EAAE,CAYL"}

package/out/proximity-rerank.js

@@ -0,0 +1,86 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The proximity re-rank (#938): with bias hints — the demo's map viewport, a user location — re-order exact-match
+ *   candidates by population and nearness on one additive scale, so an in-view namesake wins a tie without a hard
+ *   filter. Byte-identical to plain population order when no bias is passed.
+ *
+ *   This lives in its own platform-free module because it has to run identically in two places: the Node candidate
+ *   reader and the browser byte-range twin. That is the #861 server↔demo parity contract, and it is the second thing
+ *   here held by construction rather than by comment (`primary-preference.ts` was the first). Constants alone were not
+ *   enough — the two copies agreed on every literal and still diverged on which field the population term reads and on
+ *   whether the combined value is written back, which is the half that actually decides the answer.
+ *
+ *   Two properties are load-bearing and easy to lose when transcribing:
+ *
+ *   1. The population base is `prominence ?? score`, NOT `score`. `prominence` carries the bounded cross-country
+ *      primary preference, so reading raw score lets a coincidental foreign alias ride population back over a primary
+ *      whenever a viewport hint happens to be present.
+ *   2. The combined value is PERSISTED into `prominence`. The resolver walk re-sorts by `prominence ?? score`, so a
+ *      caller that only returns the array in bias order has its ordering silently discarded downstream.
+ */
+import { haversineKm } from "@mailwoman/spatial";
+/**
+ * Full magnitude of the nearness term at distance 0, before decay.
+ */
+export const BIAS_BOOST = 4;
+/**
+ * Full magnitude of the population term, reached at {@link POP_SCALE_LOG10} and capped there.
+ */
+export const POP_BOOST = 4;
+/**
+ * `log10(population + 1)` at which the population term saturates — 6 means a population of one million earns the whole
+ * {@link POP_BOOST}, and larger populations earn no more.
+ */
+export const POP_SCALE_LOG10 = 6;
+/**
+ * Distance at which the nearness term halves.
+ *
+ * SHARPER than the FTS reader's 100 km on purpose: the candidate backend's score is log-population ALONE, with no bm25
+ * document term, so the population signal is weaker relative to the bias and a gentle 100 km decay let a 230 km-distant
+ * alias-exact township ("Paris Township", OH) edge out a global city ("Paris", FR) from a nearby view. At ~30 km the
+ * boost reaches only candidates the user is actually looking at: an in-view namesake still wins (Dublin, OH from an
+ * Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
+ */
+export const PROX_SCALE_KM = 30;
+/**
+ * Population plus nearness on one additive scale. Exported for tests and for a caller that wants the value without the
+ * sort; ordinary callers want {@link applyProximityRerank}.
+ */
+export function combinedProminence(candidate, bias) {
+    const popBase = candidate.prominence ?? candidate.score;
+    const popTerm = POP_BOOST * Math.min(1, Math.max(0, popBase) / POP_SCALE_LOG10);
+    let proxTerm = 0;
+    // A candidate at the null island has no coordinate, not a coordinate at 0,0 — it earns no nearness term rather
+    // than an enormous one.
+    if (!(candidate.lat === 0 && candidate.lon === 0)) {
+        for (const b of bias) {
+            const d = haversineKm(b.lat, b.lon, candidate.lat, candidate.lon);
+            const term = (BIAS_BOOST * (b.weight ?? 1)) / (1 + d / PROX_SCALE_KM);
+            if (term > proxTerm) {
+                proxTerm = term;
+            }
+        }
+    }
+    return popTerm + proxTerm;
+}
+/**
+ * Re-order `candidates` in place by {@link combinedProminence}, persisting each combined value into `prominence` so the
+ * resolver walk's own `prominence ?? score` sort carries the bias order rather than undoing it. Stable within equal
+ * prominence, preserving the population order the index already gave. A caller with no bias hints must not call this —
+ * the no-bias path is plain population order by construction.
+ */
+export function applyProximityRerank(candidates, bias) {
+    candidates
+        .map((c, i) => {
+        c.prominence = combinedProminence(c, bias);
+        return { c, i, p: c.prominence };
+    })
+        // oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+        .sort((a, b) => b.p - a.p || a.i - b.i)
+        .forEach((x, j) => (candidates[j] = x.c));
+    return candidates;
+}
+//# sourceMappingURL=proximity-rerank.js.map

package/out/proximity-rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proximity-rerank.js","sourceRoot":"","sources":["../proximity-rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAA;AAE3B;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAA;AAE1B;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAA;AAEhC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAA;AAsB/B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA8B,EAAE,IAA8B;IAChG,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,IAAI,SAAS,CAAC,KAAK,CAAA;IACvD,MAAM,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,eAAe,CAAC,CAAA;IAC/E,IAAI,QAAQ,GAAG,CAAC,CAAA;IAEhB,+GAA+G;IAC/G,wBAAwB;IACxB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;YACjE,MAAM,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,CAAA;YAErE,IAAI,IAAI,GAAG,QAAQ,EAAE,CAAC;gBACrB,QAAQ,GAAG,IAAI,CAAA;YAChB,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,OAAO,GAAG,QAAQ,CAAA;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CACnC,UAAe,EACf,IAA8B;IAE9B,UAAU;SACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACb,CAAC,CAAC,UAAU,GAAG,kBAAkB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;QAE1C,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,CAAA;IACjC,CAAC,CAAC;QACF,8HAA8H;SAC7H,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACtC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAE1C,OAAO,UAAU,CAAA;AAClB,CAAC"}