@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/{poi-schema.ts → lib/poi/schema.ts}

@@ -12,11 +12,12 @@
  *   manifest (tier `shipped`, spine `h3` res 9) and per-res-6-cell coverage.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { sql, type Kysely } from "kysely"
 
+import type { NameKey } from "#street/normalize"
+
 /**
  * One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key.
  */
@@ -39,9 +40,12 @@ export interface POITable {
 	rowid_key: number
 	name: string | null
 	/**
-	 * Lowercased, diacritic-flattened probe key for exact name lookups.
+	 * Probe key for exact name lookups, minted by {@link normalizeLocalityForKey} at build AND at query.
+	 *
+	 * Branded because a `toLowerCase()` approximation of the fold is still a `string`: it binds to the parameter, returns
+	 * fewer rows, and the shortfall reads as a coverage gap in the data rather than a defect in the probe.
 	 */
-	name_key: string | null
+	name_key: NameKey | null
 	brand_wikidata: string | null
 	latitude: number
 	longitude: number
@@ -69,7 +73,7 @@ export interface POIStageTable {
 	neg_rank: number | null
 	rowid_key: number | null
 	name: string | null
-	name_key: string | null
+	name_key: NameKey | null
 	brand_wikidata: string | null
 	latitude: number
 	longitude: number
@@ -187,7 +191,7 @@ export const POI_FTS_TABLE = "poi_search"
 /**
  * FTS5 stays raw SQL by project rule (Kysely can't express virtual tables). Content-keyed by name_key.
  */
-export function createPOISearchFTS(db: DatabaseSync): void {
+export function createPOISearchFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(
 		`CREATE VIRTUAL TABLE ${POI_FTS_TABLE} USING fts5(name, name_key UNINDEXED, h3_cell UNINDEXED, tokenize = 'unicode61')`
 	)

package/lib/polygon-schema.ts

@@ -0,0 +1,47 @@
+/**
+ * @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 async function createPolygonsTable(db: PolygonSchemaHandle): Promise<void> {
+	await db.schema
+		.createTable("polygons")
+		.addColumn("id", "integer", (column) => column.primaryKey())
+		.addColumn("geom", "text", (column) => column.notNull())
+		.execute()
+}

package/{postal-city-alias-lookup.ts → lib/postal/city-alias-lookup.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
@@ -16,11 +16,9 @@
  *   uses), keeping one normalizer in one place.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
-
-import type { PostalCityAliasDatabase } from "./postal-city-alias-schema.ts"
+import type { PostalCityAliasDatabase } from "#postal/city-alias-schema"
 
 export interface WOFPostalCityAliasLookupOpts {
 	/**
@@ -30,7 +28,7 @@ export interface WOFPostalCityAliasLookupOpts {
 	/**
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
-	database?: DatabaseSync
+	database?: DatabaseClient<PostalCityAliasDatabase>
 }
 
 /**
@@ -56,24 +54,22 @@ export interface PostalCityAlias {
  * differs from the geographic name — the rows that carry alias signal), issued via the typed Kysely query builder
  * against {@link PostalCityAliasDatabase}.
  */
-export class WOFPostalCityAliasLookup {
-	#db: DatabaseSync
-	#kdb: DatabaseClient<PostalCityAliasDatabase>
-	#ownsDB: boolean
+export class WOFPostalCityAliasLookup implements Disposable {
+	#db: DatabaseClient<PostalCityAliasDatabase>
+	/**
+	 * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
+	 * ownership is membership rather than a flag a later branch has to check.
+	 */
+	readonly #resources = new DisposableStack()
 
 	constructor(opts: WOFPostalCityAliasLookupOpts) {
 		if (opts.database) {
 			this.#db = opts.database
-			this.#ownsDB = false
 		} else if (opts.databasePath) {
-			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
-			this.#ownsDB = true
+			this.#db = this.#resources.use(new DatabaseClient<PostalCityAliasDatabase>(opts.databasePath, { readOnly: true }))
 		} else {
 			throw new Error("WOFPostalCityAliasLookup needs `databasePath` or `database`")
 		}
-
-		// `#kdb` wraps `#db` for the typed query; close() owns the raw handle directly (sync).
-		this.#kdb = new DatabaseClient<PostalCityAliasDatabase>({ database: this.#db })
 	}
 
 	/**
@@ -85,7 +81,7 @@ export class WOFPostalCityAliasLookup {
 
 		if (!pc) return []
 
-		const rows = await this.#kdb
+		const rows = await this.#db
 			.selectFrom("postal_city_alias")
 			.select(["postal_city", "geo_locality", "n"])
 			.where("postcode", "=", pc)
@@ -95,9 +91,7 @@ export class WOFPostalCityAliasLookup {
 		return rows.map((r) => ({ postalCity: String(r.postal_city), geoLocality: String(r.geo_locality), n: Number(r.n) }))
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
 	}
 }

package/{postal-city-candidate-schema.ts → lib/postal/city-candidate-schema.ts}

@@ -20,6 +20,8 @@
 
 import { sql, type Kysely } from "kysely"
 
+import type { NameKey } from "#street/normalize"
+
 /**
  * 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`.
@@ -28,7 +30,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).
 	 */
@@ -53,7 +55,7 @@ export interface PostalCityCandidateDatabase {
 }
 
 /**
- * The table name the lookup probes (existence-gated, so an old candidate.db without it is byte-stable).
+ * The table name the lookup probes (existence-restricted, so an old candidate.db without it is byte-stable).
  */
 export const POSTAL_CITY_CANDIDATE_TABLE = "postal_city_candidate"
 

package/lib/postal/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#postal/city-alias-lookup"
+export * from "#postal/city-alias-schema"
+export * from "#postal/city-candidate-schema"

package/{postcode-point-lookup.ts → lib/postcode-point-lookup.ts}

@@ -4,22 +4,24 @@
  * @author Teffen Ellis, et al.
  *
  *   SQLite-backed postcode lookup for the postcode anchor (#240). A thin exact-match resolver over
- *   one or more `postalcode-*.db` shards (the `spr` schema built by `build-unified-wof --placetypes
+ *   one or more `postalcode-*.db` extracts (the `spr` schema built by `build-unified-wof --placetypes
  *   postalcode`, then centroid-backfilled by `scripts/backfill-postcode-centroids.ts`).
  *
  *   This is the production implementation of the `PostcodeResolver` interface consumed by
  *   `@mailwoman/neural`'s `extractPostcodeAnchors`. It is deliberately dumb: an indexed exact-match
- *   on the postcode string across every shard, unioned. No FTS, no ranking, no proximity — the
+ *   on the postcode string across every extract, unioned. No FTS, no ranking, no proximity — the
  *   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.
+ *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` interface.
  *
- *   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.
+ *   Why multiple extracts instead of the multi-extract `WOFSQLitePlaceLookup`: that resolver routes a
+ *   query to ONE extract by placetype, but every postcode extract shares `placetype='postalcode'`, so a
+ *   single query could only ever hit one country's extract. The anchor needs the union across
+ *   countries to build its country posterior, so it queries each extract directly.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import type { WOFDatabase } from "#schema"
 
 /**
  * A gazetteer hit. `lat`/`lon` of 0 means the postcode is known but has no centroid (no admin parent).
@@ -34,19 +36,19 @@ const LOOKUP_SQL =
 	"SELECT country, latitude AS lat, longitude AS lon FROM spr WHERE name = ? AND placetype = 'postalcode' AND is_current != 0"
 
 export class WOFPostcodeLookup {
-	readonly #dbs: DatabaseSync[]
-	readonly #stmts: ReturnType<DatabaseSync["prepare"]>[]
+	readonly #dbs: DatabaseClient<WOFDatabase>[]
+	readonly #stmts: ReturnType<DatabaseClient["prepare"]>[]
 
 	/**
-	 * Open each shard read-only and prepare its exact-match statement.
+	 * Open each extract read-only and prepare its exact-match statement.
 	 */
 	constructor(dbPaths: readonly string[]) {
-		this.#dbs = dbPaths.map((p) => new DatabaseSync(p, { readOnly: true }))
+		this.#dbs = dbPaths.map((p) => new DatabaseClient<WOFDatabase>(p, { readOnly: true }))
 		this.#stmts = this.#dbs.map((db) => db.prepare(LOOKUP_SQL))
 	}
 
 	/**
-	 * Exact-match the postcode across every shard and union the rows.
+	 * Exact-match the postcode across every extract and union the rows.
 	 */
 	lookup(postcode: string): PostcodePlace[] {
 		const out: PostcodePlace[] = []
@@ -60,9 +62,9 @@ export class WOFPostcodeLookup {
 		return out
 	}
 
-	close(): void {
+	[Symbol.dispose](): void {
 		for (const db of this.#dbs) {
-			db.close()
+			db.destroy()
 		}
 	}
 }

package/lib/primary-preference.ts

@@ -0,0 +1,226 @@
+/**
+ * @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"
+
+/**
+ * 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 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.
+ */
+export 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` floor).
+	 */
+	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
+	/**
+	 * 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.
+	 */
+	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.
+ *
+ * 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 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.
+ */
+export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
+	rows: readonly R[],
+	limit: number,
+	delta = PRIMARY_PREFERENCE_LOG10,
+	placetypes?: ReadonlyMap<number, string>,
+	exemptVariantAliases = false
+): Array<RankedRow<R>> {
+	// 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: R | undefined
+
+	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: R): boolean =>
+		typeof topCountry === "number" && r.is_primary !== 1 && r.country_id !== topCountry
+
+	const isCrossCountryAlias = (r: R): boolean =>
+		wouldPenalize(r) && !(exemptVariantAliases && r.name_role === "variant")
+
+	const annotate = (r: R): RankedRow<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,
+			effectiveNegRank,
+			demoted: penalized && effectiveNegRank > topPrimary!.neg_rank,
+			...(exempted ? { variantExempted: true as const } : {}),
+		}
+	}
+
+	// 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: R): number =>
+		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)
+	)
+}

package/lib/proximity-rerank.ts

@@ -0,0 +1,120 @@
+/**
+ * @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 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 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.
+ */
+
+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
+
+/**
+ * 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 function combinedProminence(candidate: ProximityRerankable, bias: readonly ProximityBias[]): number {
+	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<T extends ProximityRerankable>(
+	candidates: T[],
+	bias: readonly ProximityBias[]
+): T[] {
+	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
+}