@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/postal/city/alias/lookup.ts

@@ -3,33 +3,28 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Node reader over the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`) — the observed
+ *   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
  *   ("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
+ *   actually sits in ("Nashville"), so the right place tiers to the top instead of a place with the same name
+ *   town in another state. Opt-in — the lookup is only constructed when a path is supplied.
  *   absent it the resolver is byte-identical.
  *
- *   The reader returns RAW divergent rows for a postcode; normalization + name-matching against the
+ *   The reader returns RAW divergent rows for a postcode. normalization + name-matching against the
  *   candidate localities is the scorer's job (it owns the case/diacritic fold the soft name score
  *   uses), keeping one normalizer in one place.
  */
 
-import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { SQLiteLookup, type SQLiteLookupOptions } from "@mailwoman/sqlite/lookup"
 
 import type { PostalCityAliasDatabase } from "#postal/city/alias/schema"
 
-export interface WOFPostalCityAliasLookupOpts {
-	/**
-	 * Path to a `postal-city-alias-<cc>.db` built by `build-postal-city-alias.ts`. Opened read-only.
-	 */
-	databasePath?: string
-	/**
-	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
-	 */
-	database?: DatabaseClient<PostalCityAliasDatabase>
-}
+/**
+ * Where a {@link WOFPostalCityAliasLookup} reads from: a `postal-city-alias-<cc>.db` built by
+ * `build-postal-city-alias.ts`, opened read-only, or a connection the caller already holds.
+ */
+export type WOFPostalCityAliasLookupOpts = SQLiteLookupOptions<PostalCityAliasDatabase>
 
 /**
  * One divergent alias edge: the postal-system name and the geographic locality it maps to.
@@ -50,38 +45,29 @@ export interface PostalCityAlias {
 }
 
 /**
- * Reader over `postal_city_alias`. The only query is a postcode-scoped probe for DIVERGENT rows (where the postal name
- * differs from the geographic name — the rows that carry alias signal), issued via the typed Kysely query builder
- * against {@link PostalCityAliasDatabase}.
+ * Reader over `postal_city_alias`.
+ *
+ * The only query is a postcode-scoped probe for divergent rows
+ * (where the postal name differs from the geographic name — the rows that provide alias signal),
+ * issued via the typed Kysely query builder against {@link PostalCityAliasDatabase}.
  */
-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()
-
+export class WOFPostalCityAliasLookup extends SQLiteLookup<PostalCityAliasDatabase> {
 	constructor(opts: WOFPostalCityAliasLookupOpts) {
-		if (opts.database) {
-			this.#db = opts.database
-		} else if (opts.databasePath) {
-			this.#db = this.#resources.use(new DatabaseClient<PostalCityAliasDatabase>(opts.databasePath, { readOnly: true }))
-		} else {
-			throw new Error("WOFPostalCityAliasLookup needs `databasePath` or `database`")
-		}
+		super(opts)
 	}
 
 	/**
-	 * Divergent postal-city aliases for a postcode (empty when the postcode isn't in the table). The scorer groups these
-	 * by normalized `geoLocality` and appends the `postalCity` surfaces to the matching candidate locality's alias set.
+	 * Divergent postal-city aliases for a postcode (empty when the postcode isn't in the table).
+	 *
+	 * The scorer groups these by normalized `geoLocality` and appends the `postalCity`
+	 * surfaces to the matching candidate locality's alias set.
 	 */
 	async getDivergentAliases(postcode: string): Promise<PostalCityAlias[]> {
 		const pc = postcode.trim()
 
 		if (!pc) return []
 
-		const rows = await this.#db
+		const rows = await this.database
 			.selectFrom("postal_city_alias")
 			.select(["postal_city", "geo_locality", "n"])
 			.where("postcode", "=", pc)
@@ -90,8 +76,4 @@ export class WOFPostalCityAliasLookup implements Disposable {
 
 		return rows.map((r) => ({ postalCity: String(r.postal_city), geoLocality: String(r.geo_locality), n: Number(r.n) }))
 	}
-
-	[Symbol.dispose](): void {
-		this.#resources[Symbol.dispose]()
-	}
 }

package/lib/postal/city/alias/schema.ts

@@ -3,15 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`, built by
+ *   Typed schema for the postal-city alias table (`postal-city-alias-<cc>.db`, built by
  *   `scripts/build-postal-city-alias.ts`) — the single source of truth for the columns shared by
- *   the BUILDER and the READER ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
- *   contract is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
+ *   the builder and the reader ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
+ *   interface is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
  *   the builder is a compile error in the reader.
  *
- *   Provenance discipline (provenance-first): this is a SIBLING table to the PIP-derived
+ *   Provenance discipline (provenance-first): this is a sibling table to the PIP-derived
  *   `postcode_locality` data, never mixed into it — one table, one provenance class. Each row is an
- *   OBSERVED `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
+ *   observed `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
  *   with a usage count `n`; `divergent = 1` exactly when `postal_city != geo_locality` (the alias
  *   signal — the only rows the resolver consumes).
  */
@@ -19,8 +19,10 @@
 import type { Kysely } from "kysely"
 
 /**
- * One observed postal-city aggregate. The natural key is `(postcode, postal_city, geo_locality)`; the builder enforces
- * a `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
+ * One observed postal-city aggregate.
+ *
+ * The natural key is `(postcode, postal_city, geo_locality)`; the builder enforces a
+ * `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
  */
 export interface PostalCityAliasTable {
 	/**
@@ -61,7 +63,7 @@ export interface PostalCityAliasDatabase {
 }
 
 /**
- * The `postal_city_alias` column order — the builder's INSERT derives its column list from this.
+ * The `postal_city_alias` column order — the builder's insert derives its column list from this.
  */
 export const POSTAL_CITY_ALIAS_COLUMNS = [
 	"postcode",
@@ -74,8 +76,10 @@ export const POSTAL_CITY_ALIAS_COLUMNS = [
 ] as const
 
 /**
- * Create the `postal_city_alias` table + its two probe indexes. Kept here (not only in the builder) so tests can stand
- * up a fixture DB with the exact production shape. Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
+ * Create the `postal_city_alias` table + its two probe indexes.
+ *
+ * Kept here (not only in the builder) so tests can stand up a fixture DB with the exact production shape.
+ * Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
  */
 export async function createPostalCityAliasTable(db: Kysely<PostalCityAliasDatabase>): Promise<void> {
 	await db.schema

package/lib/postal/city/candidate-schema.ts

@@ -3,19 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the POSTAL-CITY CANDIDATE side-index (#741 / #475) — a small `(name_key,
- *   postcode) → geo-locality` table that lives alongside the byte-range `candidate` table so the
- *   candidate-backend resolver (the demo/CLI default) can do what the FTS coordinate-first scorer
- *   does: resolve a user-typed POSTAL city ("Antioch", 37013) to the geographic locality the
- *   postcode sits in ("Nashville").
+ *   Typed schema for the postal-city candidate side-index, a small `(name_key, postcode)` →
+ *   geo-locality table alongside the byte-range `candidate` table.
+ *   The candidate-backend resolver (the demo and CLI default) can then match the FTS coordinate-first scorer.
+ *   It resolves a user-typed postal city ("Antioch", 37013) to the geographic locality the postcode
+ *   resolve a user-typed postal city ("Antioch", 37013) to the geographic locality the postcode
+ *   sits in ("Nashville").
  *
- *   Why a SIDE-INDEX, not cloned `candidate` rows: the `candidate` B-tree is keyed `(name_key,
- *   country_id, region_id, placetype_id, …)` and ranked population-first — it has no postcode
- *   dimension. A cloned alias row was tested (#741) and falsified: a sentinel rank is
- *   bare-name-safe but then loses to any in-region homonym, and there is no single rank that is
- *   both. The fix is an EXACT `(name_key, postcode)` probe that bypasses population/region ranking
- *   entirely — consulted only when the query carries a postcode, so the common no-postcode path is
- *   untouched.
+ *   The `candidate` B-tree is keyed `(name_key, country_id, region_id, placetype_id, …)` and ranked
+ *   population-first, so it has no postcode dimension. A cloned alias row cannot satisfy both
+ *   purposes, because a sentinel rank is bare-name-safe and then loses to any in-region homonym.
+ *   The exact `(name_key, postcode)` probe bypasses population and region ranking entirely.
+ *   It runs only when the query includes a postcode, leaving the common no-postcode path untouched.
  */
 
 import { sql, type Kysely } from "kysely"
@@ -23,12 +22,14 @@ 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`.
+ * 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`.
  */
 export interface PostalCityCandidateTable {
 	/**
-	 * {@link normalizeLocalityForKey} of the postal-city name — the build/query-consistent probe key.
+	 * {@link normalizeLocalityForKey} of the postal-city name, the build/query-consistent probe key.
 	 */
 	name_key: NameKey
 	/**
@@ -60,7 +61,7 @@ export interface PostalCityCandidateDatabase {
 export const POSTAL_CITY_CANDIDATE_TABLE = "postal_city_candidate"
 
 /**
- * Column order for the builder's positional INSERT.
+ * Column order for the builder's positional insert.
  */
 export const POSTAL_CITY_CANDIDATE_COLUMNS = [
 	"name_key",
@@ -72,9 +73,14 @@ export const POSTAL_CITY_CANDIDATE_COLUMNS = [
 ] as const
 
 /**
- * Create the side-index — a clustered `WITHOUT ROWID` B-tree on `(name_key, postcode)` so the resolve is a single exact
- * probe. Idempotent (`IF NOT EXISTS`); pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB. The
- * Kysely schema-builder is the house idiom for table creation — see `AGENTS.md` (inline-SQL → Kysely).
+ * Create the side-index, a clustered `without rowid` B-tree on `(name_key, postcode)`
+ * so the resolve is a single exact probe.
+ *
+ * Idempotent (`if not exists`).
+ * Pass a {@link DatabaseClient} (or any `Kysely`) over the candidate DB.
+ *
+ * The Kysely schema-builder is the house idiom for table creation.
+ * See `agents.md` on inline SQL and Kysely.
  */
 export async function createPostalCityCandidateTable(db: Kysely<PostalCityCandidateDatabase>): Promise<void> {
 	await db.schema
@@ -87,7 +93,7 @@ export async function createPostalCityCandidateTable(db: Kysely<PostalCityCandid
 		.addColumn("latitude", "real", (c) => c.notNull())
 		.addColumn("longitude", "real", (c) => c.notNull())
 		.addPrimaryKeyConstraint("postal_city_candidate_pk", ["name_key", "postcode"])
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		// `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 }

package/lib/postcode-point-lookup.ts

@@ -2,53 +2,34 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @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` 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 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()` interface.
- *
- *   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 type { PostcodePlace } from "@mailwoman/core/resolver"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
 
 import type { WOFDatabase } from "#schema"
 
-/**
- * A gazetteer hit. `lat`/`lon` of 0 means the postcode is known but has no centroid (no admin parent).
- */
-export interface PostcodePlace {
-	country: string
-	lat: number
-	lon: number
-}
-
 const LOOKUP_SQL =
 	"SELECT country, latitude AS lat, longitude AS lon FROM spr WHERE name = ? AND placetype = 'postalcode' AND is_current != 0"
 
+/**
+ * Looks up current WOF `postalcode` places by exact name across one or more read-only gazetteer databases.
+ */
 export class WOFPostcodeLookup {
 	readonly #dbs: DatabaseClient<WOFDatabase>[]
 	readonly #stmts: ReturnType<DatabaseClient["prepare"]>[]
 
 	/**
-	 * Open each extract read-only and prepare its exact-match statement.
+	 * Opens each database read-only and prepares its exact-match statement.
 	 */
-	constructor(dbPaths: readonly string[]) {
+	constructor(dbPaths: readonly PathBuilderLike[]) {
 		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 extract and union the rows.
+	 * Returns the union of exact-name matches for `postcode` across every database, without deduplication.
 	 */
 	lookup(postcode: string): PostcodePlace[] {
 		const out: PostcodePlace[] = []

package/lib/primary-preference.ts

@@ -2,146 +2,91 @@
  * @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 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
 
 /**
- * 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.
+ * Re-ranks population-ordered candidate rows.
  *
- * `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.
+ * A cross-country alias must beat the top primary by `delta` in log10 population.
+ * The function returns the top `limit` rows.
  *
- * 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.
+ * 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<R extends PrimaryPreferenceRow>(
 	rows: readonly R[],
@@ -150,9 +95,7 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 	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
+	let topPrimary: R | null = null
 
 	for (const r of rows) {
 		if (r.is_primary === 1 && (topPrimary == null || r.neg_rank < topPrimary.neg_rank)) {
@@ -162,14 +105,6 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 
 	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
 
@@ -180,10 +115,6 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 		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 {
@@ -194,12 +125,8 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 		}
 	}
 
-	// 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 &&
+		placetypes &&
 		typeof r.placetype_id === "number" &&
 		typeof r.population === "number" &&
 		r.population > 0 &&
@@ -207,21 +134,14 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 			? 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): number =>
 		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 ||