@mailwoman/resolver-wof-sqlite 8.0.0 → 8.2.0

package/poi-lookup.ts

@@ -32,7 +32,9 @@ import { gridDisk, latLngToCell } from "h3-js"
 
 import type { POICategoryCodeTable, POITable } from "./poi-schema.ts"
 
-/** Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4). */
+/**
+ * Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4).
+ */
 export const POI_H3_RESOLUTION = 9
 
 /**
@@ -57,11 +59,15 @@ const DEFAULT_MAX_RINGS = 16
  */
 const BRAND_MAX_DISTANCE_KM = 500
 
-/** Row-count default when a query doesn't specify `limit`. */
+/**
+ * Row-count default when a query doesn't specify `limit`.
+ */
 const DEFAULT_LIMIT = 20
 
 export interface POISearchQuery {
-	/** Poi-taxonomy category id (string side of the dictionary). Ignored when `brandWikidata` is also set — brand wins. */
+	/**
+	 * Poi-taxonomy category id (string side of the dictionary). Ignored when `brandWikidata` is also set — brand wins.
+	 */
 	categoryID?: string
 	/**
 	 * Fan-out category ids — the Overture `taxonomy.primary` leaves a single canonical category rolls up into (e.g.
@@ -70,11 +76,17 @@ export interface POISearchQuery {
 	 * one-element list `[categoryID]` when this is absent). Ignored when `brandWikidata` is set — brand wins.
 	 */
 	categoryIDs?: string[]
-	/** Wikidata QID for brand-exact search. */
+	/**
+	 * Wikidata QID for brand-exact search.
+	 */
 	brandWikidata?: string
-	/** Free-text name (FTS5). */
+	/**
+	 * Free-text name (FTS5).
+	 */
 	name?: string
-	/** Search center. Required for category/brand queries (k-ring expansion). */
+	/**
+	 * Search center. Required for category/brand queries (k-ring expansion).
+	 */
 	center?: { latitude: number; longitude: number }
 	/**
 	 * Ring budget: how many res-9 k-rings to expand before giving up (default 16 ≈ ~5.4 km). Counts ring 0, so k reaches
@@ -92,19 +104,27 @@ export interface POISearchHit {
 	longitude: number
 	country: string
 	confidence: number
-	/** Overture GERS id — nullable METADATA ONLY, never a key (the #470 rule; see `POITable.gers_id`). */
+	/**
+	 * Overture GERS id — nullable METADATA ONLY, never a key (the #470 rule; see `POITable.gers_id`).
+	 */
 	gersID: string | null
 	distanceM?: number
 }
 
 export interface POILookupOpts {
-	/** Path to a `poi.db` built by the (future) POI builder. Opened read-only. */
+	/**
+	 * Path to a `poi.db` built by the (future) POI builder. Opened read-only.
+	 */
 	databasePath?: string
-	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
 	database?: DatabaseSync
 }
 
-/** The `poi` columns every search mode hydrates — a typed projection of the SHARED {@link POITable}. */
+/**
+ * The `poi` columns every search mode hydrates — a typed projection of the SHARED {@link POITable}.
+ */
 type POIRow = Pick<
 	POITable,
 	| "name"
@@ -129,11 +149,17 @@ export class POILookup implements Disposable {
 	readonly #categoryToID = new Map<string, number>()
 	readonly #idToCategory = new Map<number, string>()
 
-	/** `(h3_cell, category_id)` → the cell's category-clustered range, most-confident-first. */
+	/**
+	 * `(h3_cell, category_id)` → the cell's category-clustered range, most-confident-first.
+	 */
 	readonly #categoryCellProbe: ReturnType<DatabaseSync["prepare"]>
-	/** `brand_wikidata` → ALL of a brand's rows globally (partial-index range-scan); distance-sorted in JS, not SQL. */
+	/**
+	 * `brand_wikidata` → ALL of a brand's rows globally (partial-index range-scan); distance-sorted in JS, not SQL.
+	 */
 	readonly #brandProbe: ReturnType<DatabaseSync["prepare"]>
-	/** FTS5 `MATCH` over `poi_search`, returning candidate `name_key`s to hydrate. */
+	/**
+	 * FTS5 `MATCH` over `poi_search`, returning candidate `name_key`s to hydrate.
+	 */
 	readonly #nameFTSProbe: ReturnType<DatabaseSync["prepare"]>
 
 	constructor(opts: POILookupOpts) {
@@ -161,7 +187,9 @@ export class POILookup implements Disposable {
 		this.#categoryCellProbe = this.#db.prepare(
 			`SELECT ${columns} FROM poi WHERE h3_cell = ? AND category_id = ? ORDER BY neg_rank ASC LIMIT ?`
 		)
+
 		this.#brandProbe = this.#db.prepare(`SELECT ${columns} FROM poi WHERE brand_wikidata = ?`)
+
 		this.#nameFTSProbe = this.#db.prepare(
 			"SELECT name_key FROM poi_search WHERE poi_search MATCH ? ORDER BY bm25(poi_search) LIMIT ?"
 		)
@@ -174,7 +202,7 @@ export class POILookup implements Disposable {
 			return this.#searchByName(query.name, limit, query.center)
 		}
 
-		if (query.categoryID || (query.categoryIDs && query.categoryIDs.length > 0) || query.brandWikidata) {
+		if (query.categoryID || (query.categoryIDs && query.categoryIDs.length) || query.brandWikidata) {
 			if (!query.center) {
 				throw new Error("POILookup.search: category/brand search requires a `center`")
 			}
@@ -208,7 +236,9 @@ export class POILookup implements Disposable {
 			.map((row) => toHit(row, this.#idToCategory, center))
 	}
 
-	/** Category path: k-ring expansion from `query.center`'s res-9 cell, probing each new ring's cells. */
+	/**
+	 * Category path: k-ring expansion from `query.center`'s res-9 cell, probing each new ring's cells.
+	 */
 	#searchKRing(query: POISearchQuery, limit: number): POISearchHit[] {
 		const center = query.center!
 		const maxRings = query.maxRings ?? DEFAULT_MAX_RINGS
@@ -227,7 +257,7 @@ export class POILookup implements Disposable {
 		}
 
 		// No resolvable leaf (every id unknown to the dictionary) can't have rows — a clean miss, not a throw.
-		if (categoryIds.length === 0) return []
+		if (!categoryIds.length) return []
 
 		const origin = latLngToCell(center.latitude, center.longitude, POI_H3_RESOLUTION) as H3Cell
 		const seenCells = new Set<string>()
@@ -281,7 +311,7 @@ export class POILookup implements Disposable {
 			uniqueKeys.push(hit.name_key)
 		}
 
-		if (uniqueKeys.length === 0) return []
+		if (!uniqueKeys.length) return []
 
 		const hydrated = this.#hydrateByNameKeys(uniqueKeys)
 		const rowsByKey = new Map<string, POIRow[]>()
@@ -334,13 +364,15 @@ export class POILookup implements Disposable {
 	}
 }
 
-/** `poi.h3_cell` is the SHORTENED (48-bit) cell — never the full h3-js cell string. */
+/**
+ * `poi.h3_cell` is the SHORTENED (48-bit) cell — never the full h3-js cell string.
+ */
 function h3CellToInt(cell: H3Cell): number {
 	return Number(BigInt(`0x${shortenH3Cell(cell)}`))
 }
 
 function sortByDistance(rows: POIRow[], center: { latitude: number; longitude: number }): POIRow[] {
-	return [...rows].sort(
+	return [...rows].toSorted(
 		(a, b) =>
 			haversineKm(center.latitude, center.longitude, a.latitude, a.longitude) -
 			haversineKm(center.latitude, center.longitude, b.latitude, b.longitude)
@@ -378,10 +410,10 @@ function toHit(
  */
 function sanitizePOINameQuery(text: string): string {
 	return text
-		.replace(/["*:]/g, "")
+		.replaceAll(/["*:]/g, "")
 		.trim()
 		.split(/\s+/u)
 		.filter(Boolean)
-		.map((token) => `"${token.replace(/"/g, '""')}"`)
+		.map((token) => `"${token.replaceAll('"', '""')}"`)
 		.join(" ")
 }

package/poi-schema.ts

@@ -17,27 +17,45 @@ import type { DatabaseSync } from "node:sqlite"
 import type { LayerContractDatabase } from "@mailwoman/core/layers"
 import { sql, type Kysely } from "kysely"
 
-/** One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key. */
+/**
+ * One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key.
+ */
 export interface POITable {
-	/** 48-bit short H3 cell at res 9 (`latLngToCell` → `shortenH3Cell`). */
+	/**
+	 * 48-bit short H3 cell at res 9 (`latLngToCell` → `shortenH3Cell`).
+	 */
 	h3_cell: number
-	/** Small int from {@link POICategoryCodeTable}; 0 = uncategorized. */
+	/**
+	 * Small int from {@link POICategoryCodeTable}; 0 = uncategorized.
+	 */
 	category_id: number
-	/** `-log10(confidence + epsilon)` so ASC = most-confident-first within a cell+category. */
+	/**
+	 * `-log10(confidence + epsilon)` so ASC = most-confident-first within a cell+category.
+	 */
 	neg_rank: number
-	/** Uniquifier within the clustered key (builder-assigned monotonic int). */
+	/**
+	 * Uniquifier within the clustered key (builder-assigned monotonic int).
+	 */
 	rowid_key: number
 	name: string | null
-	/** Lowercased, diacritic-flattened probe key for exact name lookups. */
+	/**
+	 * Lowercased, diacritic-flattened probe key for exact name lookups.
+	 */
 	name_key: string | null
 	brand_wikidata: string | null
 	latitude: number
 	longitude: number
-	/** ISO 3166-1 alpha-2 (from the Overture partition). */
+	/**
+	 * ISO 3166-1 alpha-2 (from the Overture partition).
+	 */
 	country: string
-	/** Overture existence confidence (already filtered ≥ 0.85 at build). */
+	/**
+	 * Overture existence confidence (already filtered ≥ 0.85 at build).
+	 */
 	confidence: number
-	/** GERS id — nullable METADATA ONLY, never a key (the #470 rule). */
+	/**
+	 * GERS id — nullable METADATA ONLY, never a key (the #470 rule).
+	 */
 	gers_id: string | null
 }
 
@@ -60,7 +78,9 @@ export interface POIStageTable {
 	gers_id: string | null
 }
 
-/** `(id → poi-taxonomy category id)` dictionary, e.g. `3 → "cafe"`. */
+/**
+ * `(id → poi-taxonomy category id)` dictionary, e.g. `3 → "cafe"`.
+ */
 export interface POICategoryCodeTable {
 	id: number
 	category: string
@@ -72,7 +92,9 @@ export interface POIDatabase extends LayerContractDatabase {
 	poi_category_codes: POICategoryCodeTable
 }
 
-/** Clustered-key-order column list shared by builder + `INSERT INTO poi SELECT … FROM poi_stage`. */
+/**
+ * Clustered-key-order column list shared by builder + `INSERT INTO poi SELECT … FROM poi_stage`.
+ */
 export const POI_COLUMNS = [
 	"h3_cell",
 	"category_id",
@@ -94,6 +116,7 @@ export async function createPOIStagingTables(db: Kysely<POIDatabase>): Promise<v
 		.addColumn("id", "integer", (c) => c.primaryKey())
 		.addColumn("category", "text", (c) => c.unique())
 		.execute()
+
 	await db.schema
 		.createTable("poi_stage")
 		.addColumn("h3_cell", "integer")
@@ -132,7 +155,9 @@ export async function createPOITable(db: Kysely<POIDatabase>): Promise<void> {
 		.execute()
 }
 
-/** Secondary index for the FTS-hydration path. Builders call this AFTER the bulk materialize (index-after-load). */
+/**
+ * Secondary index for the FTS-hydration path. Builders call this AFTER the bulk materialize (index-after-load).
+ */
 export async function createPOINameKeyIndex(db: Kysely<POIDatabase>): Promise<void> {
 	await db.schema.createIndex("poi_name_key").on("poi").column("name_key").execute()
 }
@@ -154,9 +179,14 @@ export async function createPOIBrandIndex(db: Kysely<POIDatabase>): Promise<void
 		.execute()
 }
 
+/**
+ * FTS5 virtual table backing POI name search in poi.db.
+ */
 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. */
+/**
+ * FTS5 stays raw SQL by project rule (Kysely can't express virtual tables). Content-keyed by name_key.
+ */
 export function createPOISearchFTS(db: DatabaseSync): void {
 	db.exec(
 		`CREATE VIRTUAL TABLE ${POI_FTS_TABLE} USING fts5(name, name_key UNINDEXED, h3_cell UNINDEXED, tokenize = 'unicode61')`

package/postal-city-alias-lookup.ts

@@ -23,19 +23,31 @@ import { DatabaseClient } from "@mailwoman/core/kysley/client"
 import type { PostalCityAliasDatabase } from "./postal-city-alias-schema.ts"
 
 export interface WOFPostalCityAliasLookupOpts {
-	/** Path to a `postal-city-alias-<cc>.db` built by `build-postal-city-alias.ts`. Opened read-only. */
+	/**
+	 * 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`. */
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
 	database?: DatabaseSync
 }
 
-/** One divergent alias edge: the postal-system name and the geographic locality it maps to. */
+/**
+ * One divergent alias edge: the postal-system name and the geographic locality it maps to.
+ */
 export interface PostalCityAlias {
-	/** The postal-system surface (what a user types). */
+	/**
+	 * The postal-system surface (what a user types).
+	 */
 	postalCity: string
-	/** The geographic locality name the postcode sits in (≈ the gazetteer's canonical name). */
+	/**
+	 * The geographic locality name the postcode sits in (≈ the gazetteer's canonical name).
+	 */
 	geoLocality: string
-	/** Observed usage count — the evidence weight. */
+	/**
+	 * Observed usage count — the evidence weight.
+	 */
 	n: number
 }
 
@@ -59,6 +71,7 @@ export class WOFPostalCityAliasLookup {
 		} 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 })
 	}
@@ -71,6 +84,7 @@ export class WOFPostalCityAliasLookup {
 		const pc = postcode.trim()
 
 		if (!pc) return []
+
 		const rows = await this.#kdb
 			.selectFrom("postal_city_alias")
 			.select(["postal_city", "geo_locality", "n"])

package/postal-city-alias-schema.ts

@@ -23,28 +23,46 @@ import type { Kysely } from "kysely"
  * a `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
  */
 export interface PostalCityAliasTable {
-	/** The postcode the aggregate is scoped to (the resolver probes by this). */
+	/**
+	 * The postcode the aggregate is scoped to (the resolver probes by this).
+	 */
 	postcode: string
-	/** What the postal system calls the place (the surface a user is likely to type). */
+	/**
+	 * What the postal system calls the place (the surface a user is likely to type).
+	 */
 	postal_city: string
-	/** The geographic locality name the postcode actually sits in (≈ the gazetteer's canonical name). */
+	/**
+	 * The geographic locality name the postcode actually sits in (≈ the gazetteer's canonical name).
+	 */
 	geo_locality: string
-	/** Observed row count — the evidence weight behind this alias. */
+	/**
+	 * Observed row count — the evidence weight behind this alias.
+	 */
 	n: number
-	/** 1 when `postal_city != geo_locality` (the alias signal); 0 when they agree. */
+	/**
+	 * 1 when `postal_city != geo_locality` (the alias signal); 0 when they agree.
+	 */
 	divergent: number
-	/** Provenance: the dataset this aggregate came from (e.g. `overture:US`). */
+	/**
+	 * Provenance: the dataset this aggregate came from (e.g. `overture:US`).
+	 */
 	source: string
-	/** The pinned data release the aggregate was computed from. */
+	/**
+	 * The pinned data release the aggregate was computed from.
+	 */
 	release: string
 }
 
-/** The postal-city-alias database schema for `new DatabaseClient<PostalCityAliasDatabase>(...)`. */
+/**
+ * The postal-city-alias database schema for `new DatabaseClient<PostalCityAliasDatabase>(...)`.
+ */
 export interface PostalCityAliasDatabase {
 	postal_city_alias: PostalCityAliasTable
 }
 
-/** 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",
 	"postal_city",
@@ -70,6 +88,7 @@ export async function createPostalCityAliasTable(db: Kysely<PostalCityAliasDatab
 		.addColumn("source", "text", (c) => c.notNull())
 		.addColumn("release", "text", (c) => c.notNull())
 		.execute()
+
 	await db.schema.createIndex("idx_pca_postcode").on("postal_city_alias").column("postcode").execute()
 	await db.schema.createIndex("idx_pca_pair").on("postal_city_alias").columns(["postal_city", "geo_locality"]).execute()
 }

package/postal-city-candidate-schema.ts

@@ -25,13 +25,21 @@ import { sql, type Kysely } from "kysely"
  * 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: string
-	/** The postcode the alias is scoped to (the second half of the exact key). */
+	/**
+	 * The postcode the alias is scoped to (the second half of the exact key).
+	 */
 	postcode: string
-	/** WOF id of the geographic locality the postcode sits in (the resolve target). */
+	/**
+	 * WOF id of the geographic locality the postcode sits in (the resolve target).
+	 */
 	spr_id: number
-	/** The geographic locality's display name. */
+	/**
+	 * The geographic locality's display name.
+	 */
 	name: string
 	latitude: number
 	longitude: number
@@ -49,7 +57,9 @@ 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",
 	"postcode",

package/postcode-point-lookup.ts

@@ -37,13 +37,17 @@ export class WOFPostcodeLookup {
 	readonly #dbs: DatabaseSync[]
 	readonly #stmts: ReturnType<DatabaseSync["prepare"]>[]
 
-	/** Open each shard read-only and prepare its exact-match statement. */
+	/**
+	 * Open each shard read-only and prepare its exact-match statement.
+	 */
 	constructor(dbPaths: readonly string[]) {
 		this.#dbs = dbPaths.map((p) => new DatabaseSync(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 shard and union the rows.
+	 */
 	lookup(postcode: string): PostcodePlace[] {
 		const out: PostcodePlace[] = []
 

package/ranking-weights.ts

@@ -0,0 +1,148 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The locality-ranking weights and their shipped defaults. Its own module because every value here is
+ *   a measured tuning decision with its rationale attached — the block reads as a reference table, not
+ *   as part of the lookup's control flow, and the tests import it directly to pin one lever at a time.
+ */
+
+/**
+ * Ranking weights for `findPlace`. Tweakable per-instance but defaults match the values declared in the Phase 4.2 plan
+ * doc.
+ */
+export interface RankingWeights {
+	/**
+	 * Boost when the candidate's placetype matches an explicit `placetype` filter.
+	 */
+	placetypeMatchBoost: number
+	/**
+	 * Boost when the candidate is a locality and no explicit placetype was requested.
+	 */
+	localityImplicitBoost: number
+	/**
+	 * Boost when the candidate's country matches an explicit `country` filter.
+	 */
+	countryMatchBoost: number
+	/**
+	 * Boost when the candidate is a direct child of the requested `parentID`.
+	 */
+	directChildBoost: number
+	/**
+	 * Boost when the candidate is a transitive descendant of the requested `parentID`.
+	 */
+	descendantBoost: number
+	/**
+	 * Multiplier on the length-penalty term (penalizes much-longer-than-query names).
+	 */
+	lengthPenaltyWeight: number
+	/**
+	 * Magnitude of the proximity boost when the query carries `near`. The contribution is `proximityBoost / (1 +
+	 * distanceKm / proximityScaleKm)` — at distance 0 the boost is full magnitude, at `proximityScaleKm` it's half,
+	 * decaying further with distance. Default tuned so proximity can overcome a typical FTS rank tie but not dominate a
+	 * strong text match.
+	 */
+	proximityBoost: number
+	/**
+	 * Magnitude of the bias-hint term inside the exact-tier PROMINENCE sort (the `bias`/viewport path). Deliberately
+	 * population-scale (default = populationBoost) so a candidate near the map view / the user beats a distant-but-bigger
+	 * namesake — "the map view wins" is the feature; same-region ties (all candidates far from every hint) still fall to
+	 * population.
+	 */
+	biasBoost: number
+	/**
+	 * Distance (km) at which the proximity boost halves. Tune to the typical query radius.
+	 */
+	proximityScaleKm: number
+	/**
+	 * Magnitude of the population boost when the candidate has a known `wof:population`. The contribution is
+	 * `populationBoost * log10(1 + population) / populationScaleLog10`, capped at `populationBoost`. WOF only carries
+	 * population for ~15% of localities (mostly larger ones); places without it get +0 (never a penalty). Default tuned
+	 * so the famous Springfield, IL (pop ~112k) gets ~0.42 boost — enough to nudge past tiny same-name peers.
+	 */
+	populationBoost: number
+	/**
+	 * Population (in log10) at which the boost reaches its full magnitude. Default 6 — i.e. a population of 1,000,000
+	 * gives `populationBoost` exactly. Larger populations cap at the same value (no compounding effect for megacities).
+	 */
+	populationScaleLog10: number
+	/**
+	 * Tier candidates with an EXACT name/alias match above candidates that only match partially, BEFORE the weighted-sum
+	 * score is consulted. Default true.
+	 *
+	 * Why this is needed (and why it ALIGNS with — rather than overrides — the population/importance signal): the
+	 * weighted sum adds population as a large additive boost (`populationBoost`, up to +4) so that famous places surface
+	 * for unambiguous full-name queries. But population is a _prominence prior_ — its job is to break ties among
+	 * candidates that match the query EQUALLY WELL (e.g. "Springfield" → Springfield IL over Springfield MA, both exact
+	 * name matches). It was never meant to promote a place that matches the query WORSE. For a 2-letter region
+	 * abbreviation that backfires: querying "ME" returns Maine (which has the exact alias `ME`) AND Missouri/
+	 * Michigan/etc. (which do not), and Missouri's larger population (+4) overcomes Maine's bm25 edge — so "Portland, ME"
+	 * resolves its region to Missouri and the locality then cascades to the wrong state. Tiering restores the intended
+	 * ordering: **match quality is the primary key, prominence (population) the secondary key WITHIN a tier.**
+	 * Springfield-IL-over-MA still works (both exact → same tier → population decides); ME→Maine now works (only Maine is
+	 * exact → higher tier → population never gets to override it). See
+	 * docs/articles/evals/resolver-geo/2026-05-30-resolver-exact-match.md.
+	 *
+	 * Note: tiering re-ranks within the over-fetched candidate window (`limit * 4`); a pathological exact match that
+	 * falls outside that window is not rescued. For the region-abbrev case the window is comfortably sufficient (a
+	 * handful of states match a 2-letter query).
+	 */
+	exactMatchTiering: boolean
+	/**
+	 * #936 option 3 — official-language names ARE names. When true, a candidate holding the query as an OFFICIAL name
+	 * (`names.official = 1`: a preferred-form name in an official language of its country, stamped at ingest) joins the
+	 * NAME-exact sub-tier rather than the alias-exact one, provided its population clears {@link officialNameExactFloor}.
+	 * Fixes unscoped "Åbo" → Turku (its official Swedish name) over a hamlet literally named Åbo; population still orders
+	 * within the sub-tier, so Paris → Paris FR is untouched.
+	 *
+	 * Default true (operator-promoted 2026-07-03 after the pre-registered gate battery: four intended exonym flips —
+	 * Berne→Bern, Bruges→Brugge, Roma→Rome, Åbo→Turku — with the namesake/abbreviation rows and the US/FI panels
+	 * byte-identical). Requires a gazetteer carrying the #940 ingest bit — on older DBs without the `official` column the
+	 * probe fails soft and behavior is identical to the flag being off.
+	 */
+	officialNameExact: boolean
+	/**
+	 * Minimum population for a candidate's official names to join the name-exact sub-tier. The #936 review's no-floor
+	 * census measured the boundary: ≥100k holders are the famous-exonym class (757 flips, intent-correct; 7 collisions,
+	 * none harmful) while 10k–100k holders are junk-dominated (3,481 flips led by short-form mis-tags — Villeneuve-Loubet
+	 * carrying "villeneuve" would bury five real villages of that name). Rank-time knob: tunable without re-ingest;
+	 * below-floor official names simply stay alias-tier (today's behavior).
+	 */
+	officialNameExactFloor: number
+}
+
+/**
+ * The shipped weights. Every value is a measured decision — change one and re-run the resolver eval; the per-field docs
+ * on {@link RankingWeights} say what each lever moves and what motivated its current value.
+ */
+export const DEFAULT_WEIGHTS: RankingWeights = {
+	placetypeMatchBoost: 0.5,
+	localityImplicitBoost: 0.2,
+	countryMatchBoost: 0.3,
+	directChildBoost: 0.5,
+	descendantBoost: 0.2,
+	lengthPenaltyWeight: 0.1,
+	proximityBoost: 0.8,
+	proximityScaleKm: 100,
+	biasBoost: 4,
+	// populationBoost is intentionally large — empirical tuning against real WOF showed BM25 gaps
+	// of 1.5-3.0 between famous places and tiny same-name peers (because the famous ones have
+	// hundreds of alt-name entries that hurt their FTS document score). To consistently surface
+	// "the famous one" for unambiguous queries like "New York" or "Chicago", the population signal
+	// needs to dominate. Callers wanting a more conservative balance can drop this in the
+	// RankingWeights override.
+	//
+	// Note: this resolver uses `place_population` directly. The separate `place_importance` table
+	// (Wikipedia-derived) is consumed by the FST layer, not here. See
+	// docs/articles/concepts/importance-vs-population.md for the two-signal contract.
+	populationBoost: 4,
+	populationScaleLog10: 6,
+	// Exact name/alias match outranks partial match before the weighted sum (incl. population) is
+	// consulted — keeps population as an intra-tier prominence tiebreaker, not a cross-tier promoter.
+	// Fixes the 2-letter-region-abbrev bug ("ME" → Maine, not the more-populous Missouri).
+	exactMatchTiering: true,
+	// #936 option 3 — promoted default-ON 2026-07-03 (gate battery PASS; see the RankingWeights docstring).
+	officialNameExact: true,
+	officialNameExactFloor: 100_000,
+}