@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/primary-preference.d.ts

@@ -2,132 +2,78 @@
  * @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 (`packages/resolver-wof-wasm/lib/httpvfs/resolver.ts`) rank with
- *   the SAME function rather than two copies that drift (the #861 server↔browser parity contract).
- *
- *   Only type imports and arithmetic live here: anything with a `node:` import stays out.
  */
 import type { CandidateTable } from "#candidate/schema";
 /**
- * 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.
+ * The candidate-row fields that {@link rankByPrimaryPreference} reads.
+ *
+ * `is_primary` is optional, so an older artifact without the column skips the re-rank without an error.
  */
 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.
+ * The log10-population penalty applied to an alias row when the top primary-name
+ * row for the same key is in another country.
  *
- * 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).
+ * An alias at least 10 times as populous still wins, so alternate names such as "LA" keep working.
  */
 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 pushed below the fold by a cluster of
- * more-populous foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ * The number of population-ordered rows fetched per name key before
+ * {@link rankByPrimaryPreference} re-ranks them.
+ *
+ * A fetch of only the caller's `limit` could miss the intended primary behind more populous foreign aliases.
  */
 export declare const RERANK_FETCH = 64;
 /**
- * A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag.
+ * A candidate row with its re-ranked `effectiveNegRank` and its `demoted` 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` floor).
+     * `neg_rank` plus any cross-country alias penalty.
+     *
+     * Rows are ordered by this value.
+     * The emitted `prominence` derives from it.
+     *
+     * The raw `neg_rank` stays on the row for the resolver's minimum winning score.
      */
     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.
+     * True when this row is a cross-country alias that the penalty moved behind
+     * the top primary for the same key.
+     *
+     * A demoted row loses `exactMatch`, so the resolver's country pin cannot promote
+     * a coincidental foreign exonym back over the primary.
+     * A dominant alias and a same-country alias are never demoted.
      */
     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.
+     * True when this row came from the typo-correction fallback.
+     * The fallback runs only after the exact probes miss.
+     *
+     * The row is still returned and ranked, but it never claims `exactMatch`.
      */
     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".
+     * Whether the row lies inside the query's region qualifier.
+     *
+     * The candidate lookup sets it when the artifact has the ancestors sidecar.
+     *
+     * When the field is absent, containment was not checked.
      */
     containedByQualifier?: boolean;
     /**
-     * The #1882 exemption's firing mark (#1893): this row would have taken the cross-country alias penalty and
-     * `exemptVariantAliases` prevented it. PRESENT only when the exemption changed this row's treatment; absent on every
-     * row it merely inspected — an in-country variant, a primary, a set with no foreign top primary. The winner-level
-     * receipt downstream (`mechanism_fired_on.variant_alias_exemption`) counts this mark only when it survives onto the
-     * selected candidate.
+     * Set only when the variant-alias exemption spared this row the cross-country alias penalty.
      */
     variantExempted?: true;
 };
 /**
- * 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.
+ * Re-ranks population-ordered candidate rows.
  *
- * 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.
+ * A cross-country alias must beat the top primary by `delta` in log10 population.
+ * The function returns the top `limit` rows.
  *
- * BOTH CONDITIONS ARE required, 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.
+ * When `placetypes` is given, an exact tie prefers a populated `locality`.
+ * This places a seat town ahead of a district with the same name and population.
  */
 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

@@ -1 +1 @@
-{"version":3,"file":"primary-preference.d.ts","sourceRoot":"","sources":["../lib/primary-preference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;;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;IAC9B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,IAAI,CAAA;CACtB,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,CAoFrB"}
+{"version":3,"file":"primary-preference.d.ts","sourceRoot":"","sources":["../lib/primary-preference.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD;;;;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;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAIzC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,KAAK,CAAA;AAE9B;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG;IAC9B;;;;;;;OAOG;IACH,gBAAgB,EAAE,MAAM,CAAA;IAExB;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAE9B;;OAEG;IACH,eAAe,CAAC,EAAE,IAAI,CAAA;CACtB,CAAA;AAED;;;;;;;;GAQG;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,CA2DrB"}

package/out/primary-preference.js

@@ -2,116 +2,44 @@
  * @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 (`packages/resolver-wof-wasm/lib/httpvfs/resolver.ts`) rank with
- *   the SAME function rather than two copies that drift (the #861 server↔browser 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.
+ * The log10-population penalty applied to an alias row when the top primary-name
+ * row for the same key is in another country.
  *
- * 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).
+ * An alias at least 10 times as populous still wins, so alternate names such as "LA" keep working.
  */
 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 pushed below the fold by a cluster of
- * more-populous foreign aliases. Bounded and small — a single contiguous B-tree scan.
+ * The number of population-ordered rows fetched per name key before
+ * {@link rankByPrimaryPreference} re-ranks them.
+ *
+ * A fetch of only the caller's `limit` could miss the intended primary behind more populous foreign aliases.
  */
 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.
+ * Re-ranks population-ordered candidate rows.
  *
- * 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.
+ * A cross-country alias must beat the top primary by `delta` in log10 population.
+ * The function returns the top `limit` rows.
  *
- * BOTH CONDITIONS ARE required, 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.
+ * When `placetypes` is given, an exact tie prefers a populated `locality`.
+ * This places a seat town ahead of a district with the same name and population.
  */
 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;
+    let topPrimary = null;
     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 wouldPenalize = (r) => typeof topCountry === "number" && r.is_primary !== 1 && r.country_id !== topCountry;
     const isCrossCountryAlias = (r) => wouldPenalize(r) && !(exemptVariantAliases && r.name_role === "variant");
     const annotate = (r) => {
         const penalized = isCrossCountryAlias(r);
         const effectiveNegRank = r.neg_rank + (penalized ? delta : 0);
-        // The firing mark (#1893): this row WOULD have taken the cross-country penalty and the exemption
-        // prevented it — conditions the winner-level receipt needs, computed where the decision is made. A
-        // variant row that was in-country, primary, or keyed under a set with no foreign primary never
-        // fired, and stays unmarked.
         const exempted = !penalized && exemptVariantAliases && r.name_role === "variant" && wouldPenalize(r);
         return {
             ...r,
@@ -120,29 +48,17 @@ export function rankByPrimaryPreference(rows, limit, delta = PRIMARY_PREFERENCE_
             ...(exempted ? { variantExempted: true } : {}),
         };
     };
-    // 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 &&
+    const seatPreference = (r) => placetypes &&
         typeof r.placetype_id === "number" &&
         typeof r.population === "number" &&
         r.population > 0 &&
         placetypes.get(r.placetype_id) === SEAT_PLACETYPE
         ? 1
         : 0;
-    // 1 for a PRIMARY-name row whose prominence is unmeasured (population 0), 0 for everything else. Two unmeasured
-    // rows tie on `neg_rank`, and that tie used to fall through to scan order — the B-tree's `spr_id`, which is no
-    // evidence about either place. A row that IS named X ranks ahead of one merely also-known-as X when nothing else
-    // separates them: Taiwan's 溪州鄉 township row (its own name, unmeasured) over the village 溪洲 30 km away that
-    // carries `溪州鄉` as an alias (unmeasured), which the lower WOF id had been winning. Populated ties are untouched —
-    // a populated alias ("NYC") never reaches this term, and two populated rows keep the order they had.
     const unmeasuredPrimary = (r) => r.is_primary === 1 && typeof r.population === "number" && r.population === 0 ? 1 : 0;
     return (rows
         .map((r, i) => ({ row: annotate(r), i }))
-        // Effective rank ASC; ties keep population order, then the seat preference DESC, then the primary name
-        // among unmeasured rows, 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
+        // 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) ||

package/out/primary-preference.js.map

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

package/out/proximity-rerank.d.ts

@@ -3,23 +3,24 @@
  * @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.
+ *   Re-order exact-match candidates by population and nearness on one additive scale when bias hints
+ *   are present (the demo's map viewport, a user location), so an in-view namesake wins a tie
+ *   without a hard filter. With no bias the order is plain population order, byte-identical.
  *
- *   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 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.
+ *   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 server and demo parity
+ *   interface held by construction. Constants by themselves were not enough, since 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.
  *
  *   Two properties are required 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.
+ *   1. The population base is `prominence ?? score`. `prominence` contains 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.
@@ -30,22 +31,25 @@ export declare const BIAS_BOOST = 4;
  */
 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.
+ * `log10(population + 1)` at which the population term saturates.
+ *
+ * A value of 6 means a population of one million warrants the whole {@link POP_BOOST},
+ * and larger populations warrant 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).
+ * Sharper than the FTS reader's 100 km on purpose, because the candidate backend's
+ * score is log-population by itself with no bm25 document term.
+ * This weakens the population signal relative to the bias.
+ *
+ * At around 30 km the boost reaches only candidates the user is looking at,
+ * so an in-view namesake still wins and a distant one does not.
  */
 export declare const PROX_SCALE_KM = 30;
 /**
- * One bias hint — a coordinate the user is looking at or standing on, optionally weighted.
+ * One bias hint, a coordinate the user is looking at or standing on, optionally weighted.
  */
 export interface ProximityBias {
     lat: number;
@@ -53,25 +57,32 @@ export interface ProximityBias {
     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.
+ * The candidate fields the re-rank reads and writes.
+ *
+ * This is structural, 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;
+    prominence?: number | null;
 }
 /**
- * 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}.
+ * 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.
+ * Re-order `candidates` in place by {@link combinedProminence}, persisting each
+ * combined value into `prominence` so the resolver walk's own `prominence ?? score`
+ * sort preserves 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

@@ -1 +1 @@
-{"version":3,"file":"proximity-rerank.d.ts","sourceRoot":"","sources":["../lib/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"}
+{"version":3,"file":"proximity-rerank.d.ts","sourceRoot":"","sources":["../lib/proximity-rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;GAEG;AACH,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B;;GAEG;AACH,eAAO,MAAM,SAAS,IAAI,CAAA;AAE1B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC;;;;;;;;;GASG;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;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAmBzG;AAED;;;;;;;;GAQG;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

@@ -3,23 +3,24 @@
  * @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.
+ *   Re-order exact-match candidates by population and nearness on one additive scale when bias hints
+ *   are present (the demo's map viewport, a user location), so an in-view namesake wins a tie
+ *   without a hard filter. With no bias the order is plain population order, byte-identical.
  *
- *   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 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.
+ *   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 server and demo parity
+ *   interface held by construction. Constants by themselves were not enough, since 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.
  *
  *   Two properties are required 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.
+ *   1. The population base is `prominence ?? score`. `prominence` contains 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";
 /**
@@ -31,30 +32,35 @@ export const BIAS_BOOST = 4;
  */
 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.
+ * `log10(population + 1)` at which the population term saturates.
+ *
+ * A value of 6 means a population of one million warrants the whole {@link POP_BOOST},
+ * and larger populations warrant 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).
+ * Sharper than the FTS reader's 100 km on purpose, because the candidate backend's
+ * score is log-population by itself with no bm25 document term.
+ * This weakens the population signal relative to the bias.
+ *
+ * At around 30 km the boost reaches only candidates the user is looking at,
+ * so an in-view namesake still wins and a distant one does not.
  */
 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}.
+ * 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.
+    // A candidate at the null island has no coordinate, so it warrants no nearness term.
+    // A 0,0 pair interpreted as a real coordinate would receive an enormous score.
     if (!(candidate.lat === 0 && candidate.lon === 0)) {
         for (const b of bias) {
             const d = haversineKm(b.lat, b.lon, candidate.lat, candidate.lon);
@@ -67,10 +73,13 @@ export function combinedProminence(candidate, bias) {
     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.
+ * Re-order `candidates` in place by {@link combinedProminence}, persisting each
+ * combined value into `prominence` so the resolver walk's own `prominence ?? score`
+ * sort preserves 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
@@ -78,7 +87,7 @@ export function applyProximityRerank(candidates, bias) {
         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
+        // 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;