@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/candidate/scoring.ts

@@ -2,9 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   How a raw `place_search` row becomes a scored `PlaceCandidate`, and how the resulting pool is
- *   ordered — the weighted-sum score and the exact-match tiering that ranks over it.
  */
 
 import { compareReferential, referentialFromPopulation } from "@mailwoman/core/resolver"
@@ -12,15 +9,17 @@ import { haversineKm } from "@mailwoman/spatial"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 import { exactMatchIDs, officialNameIDs } from "#exact-match"
-import { foldQueryText } from "#fts/index"
+import { foldQueryText } from "#fts"
 import { populationBoostTerm, type RankingWeights } from "#ranking-weights"
 import type { RawSearchRow } from "#search-fetch"
 import type { FindPlaceQuery, PlaceCandidate, WOFPlacetype } from "#types"
 
 /**
- * Score one raw FTS row into a `PlaceCandidate`: the weighted sum over the negated BM25 baseline, the placetype /
- * country / parent boosts, the length penalty, the proximity and population terms, and the carried fields (referential,
- * encyclopedic, bbox) consumers read. `queryLen` is the query text's length, hoisted out of the per-row loop.
+ * Score one raw FTS row into a `PlaceCandidate`: the weighted sum over the negated
+ * BM25 baseline plus placetype, country and parent boosts.
+ *
+ * It also applies the length penalty, proximity and population terms,
+ * then returns the fields consumers read.
  */
 export function candidateFromSearchRow(
 	row: RawSearchRow,
@@ -33,8 +32,7 @@ export function candidateFromSearchRow(
 ): PlaceCandidate {
 	const { query, placetypes, queryLen, weights } = context
 
-	// SQLite's bm25() returns a lower-is-better score (negative for matches). Negate so we
-	// start from a higher-is-better baseline.
+	// SQLite's bm25() is lower-is-better, so negate it to get a higher-is-better baseline.
 	let score = -row.rank
 
 	if (placetypes && placetypes.length && placetypes.includes(row.placetype as WOFPlacetype)) {
@@ -56,13 +54,10 @@ export function candidateFromSearchRow(
 	const extraLen = Math.max(0, row.name.length - queryLen - 3)
 	score -= (weights.lengthPenaltyWeight * extraLen) / 10
 
-	// Proximity boost: only applied when the query carries `near` AND the candidate has real
-	// coordinates. The formula decays smoothly with distance so close-but-not-exact hits
-	// still benefit; tunable via proximityBoost + proximityScaleKm.
-	let distanceKm: number | undefined
-	// The best decayed-distance term over `near` + every `bias` point (each point's term is
-	// scaled by its weight; the MAX wins — a candidate near ANY hint is "nearby"). Carried
-	// into the exact-tier prominence sort below when hints are present.
+	// Proximity boost applies only when the query includes `near` and the candidate has real coordinates.
+	// The decay is tunable via proximityBoost + proximityScaleKm.
+	let distanceKm: number | null = null
+	// The best decayed-distance term over `near` and every `bias` point wins, each scaled by its weight.
 	let proximityTerm = 0
 
 	if (row.lat !== null && row.lon !== null && !(row.lat === 0 && row.lon === 0)) {
@@ -93,16 +88,22 @@ export function candidateFromSearchRow(
 		score += scoreTerm
 	}
 
-	// Population boost: capped at `populationBoost` magnitude at `10^populationScaleLog10`
-	// people. Missing population → no contribution. Never penalizes.
+	// Population boost caps at `populationBoost` magnitude at `10^populationScaleLog10` people and never penalizes.
 	const popTerm = populationBoostTerm(row.population, weights)
 	score += popTerm
 
-	// Combined prominence for the exact-tier sort when proximity hints are present: population
-	// and nearness in the SAME additive units, so the map view / the user's location can win a
-	// cross-country postcode tie without a hard filter.
+	// Combined prominence for the exact-tier sort: population and nearness in the same
+	// additive units, so hints can win a cross-country postcode tie without a hard filter.
 	const prominence = popTerm + proximityTerm
 
+	const population = row.population !== null && row.population > 0 ? row.population : null
+
+	// The referential key derives from this row's population and no other field,
+	// so it cannot drift from the ordering.
+	// Consumers read the encyclopedic value.
+	// No ranking site reads it.
+	// The bbox gives parity with the wasm lookup.
+	// Without it the region→bbox constraint is dead and disambiguation falls to population ranking.
 	const candidate: PlaceCandidate = {
 		id: row.id,
 		prominence,
@@ -111,45 +112,35 @@ export function candidateFromSearchRow(
 		country: row.country ?? "",
 		lat: row.lat ?? 0,
 		lon: row.lon ?? 0,
-		parent_id: row.parent_id ?? undefined,
+		parent_id: row.parent_id ?? null,
 		score,
-	}
-
-	if (distanceKm !== undefined) {
-		candidate.distanceKm = distanceKm
-	}
-
-	if (row.population !== null && row.population > 0) {
-		candidate.population = row.population
-		// The named ranking key (ROAD_TO_V9 §2). DERIVED, not stored — a pure function of the
-		// population already on this row, so it cannot drift from what the ordering uses.
-		candidate.referential = referentialFromPopulation(row.population)
-	}
-
-	// Carried for consumers (annotations / API surfaces). No ranking site reads it.
-	if (row.encyclopedic !== null) {
-		candidate.encyclopedic = row.encyclopedic
-	}
-
-	// Candidate bbox — parity with the WASM lookup (resolver-wof-wasm/lookup.ts), whose
-	// consumers (the demo cascade's region constraint) read it. Without this the Node
-	// backend's region→bbox constraint is dead and disambiguation falls to population
-	// ranking (the Springfield-IL→MO failure the #524 smoke eval caught).
-	if (row.min_latitude != null && row.max_latitude != null && row.min_longitude != null && row.max_longitude != null) {
-		candidate.bbox = {
-			minLat: row.min_latitude,
-			maxLat: row.max_latitude,
-			minLon: row.min_longitude,
-			maxLon: row.max_longitude,
-		}
+		distanceKm,
+		exactMatch: null,
+		population,
+		referential: population === null ? null : referentialFromPopulation(population),
+		encyclopedic: row.encyclopedic ?? null,
+		importance: null,
+		bbox:
+			row.min_latitude != null && row.max_latitude != null && row.min_longitude != null && row.max_longitude != null
+				? {
+						minLat: row.min_latitude,
+						maxLat: row.max_latitude,
+						minLon: row.min_longitude,
+						maxLon: row.max_longitude,
+					}
+				: null,
+		mismatch: null,
+		containedByQualifier: null,
+		regionScopeMiss: null,
+		variantAliasExempted: null,
 	}
 
 	return candidate
 }
 
 /**
- * Order `candidates` IN PLACE — the exact-match tier first when the extract can answer the name probes, otherwise plain
- * weighted-score order. Every candidate is stamped with its `exactMatch` flag on the way through.
+ * Order `candidates` in place with the exact-match tier first when the extract can answer name probes.
+ * Stamp every candidate's `exactMatch` flag.
  */
 export function rankCandidates<DB>(
 	candidates: PlaceCandidate[],
@@ -162,13 +153,8 @@ export function rankCandidates<DB>(
 ): void {
 	const { db, schemaName, query, weights } = options
 
-	// Exact-match tiering: a candidate whose name OR any alias equals the query text (case-folded)
-	// ranks above any partial match, with the weighted-sum score (incl. population) breaking ties
-	// WITHIN a tier. See the RankingWeights.exactMatchTiering docstring for why this aligns the
-	// population prior rather than overriding it. One cheap indexed lookup over the candidate ids.
-	// Runs even for a SINGLE candidate so `exactMatch` is stamped consistently (parity with the
-	// WASM lookup) — a sole alias hit ("New York City" → New York) must still carry the flag the
-	// demo cascade / #369 re-rank read.
+	// Exact-match tiering ranks a case-folded full match above a partial one.
+	// It also runs for a single candidate so `exactMatch` is stamped consistently.
 	if (weights.exactMatchTiering && candidates.length) {
 		const exactIDs = exactMatchIDs(
 			db,
@@ -177,34 +163,18 @@ export function rankCandidates<DB>(
 			query.text
 		)
 
-		// Stamp the tier onto every candidate (not just when the tiering sort fires) so a downstream
-		// re-rank — #369's postcode-anchor country pin in `resolveTree` — can keep the country pin from
-		// crossing the exact/partial boundary ("ME" → Maine, not the more-populous Missouri).
+		// Stamp the tier onto every candidate so a downstream re-rank's country pin
+		// cannot cross the exact/partial boundary.
 		for (const c of candidates) {
 			c.exactMatch = exactIDs.has(c.id as number)
 		}
 
 		if (exactIDs.size) {
-			// #905: WITHIN the exact tier, population is the PRIMARY key and the weighted score
-			// only breaks population ties. Exactness saturates text relevance, and the bm25
-			// residue inside `score` is length-noise (see the fetch-site comment), so letting it
-			// order the tier is what sent unscoped "Paris" to an Ohio township. The partial tier
-			// keeps score order — text relevance still means something there. This makes the
-			// exactMatchTiering docstring literal: match quality primary, prominence within.
-			//
-			// #912 sub-tier: a NAME-exact candidate (spr.name equals the query) outranks an
-			// ALIAS-exact one ('Paris' the place beats 'Paris Township' held via alias 'Paris').
-			// The place's own name is a stronger identity claim than an alias — aliases exist to
-			// widen recall, not to tie primaries. ME→Maine is untouched: 'ME' name-exact-matches
-			// nothing, so the alias sub-tier still decides there. Population orders within each
-			// sub-tier as before.
+			// Within the exact tier, population is the primary key and the score only breaks
+			// ties. a name-exact candidate outranks an alias-exact one.
 			const needle = foldQueryText(query.text)
 
-			// #936 option 3: an OFFICIAL name (preferred form in an official language of the place's
-			// country, `names.official = 1`) counts as the place's own name for the sub-tier — "Åbo" is
-			// Turku's name, not merely its alias. Floor-conditioned on the holder's population (see the
-			// RankingWeights docstring for the measured 100k boundary). officialIDs ⊆ exactIDs by
-			// construction (official rows are names rows), so only the sub-tier KIND changes.
+			// An official name counts as the place's own name for the sub-tier, floor-conditioned on the holder's population.
 			const officialIDs = weights.officialNameExact
 				? officialNameIDs(
 						db,
@@ -224,18 +194,9 @@ export function rankCandidates<DB>(
 				return officialIDs?.has(c.id as number) ? 2 : 1
 			}
 
-			// With proximity hints (near/bias), prominence (population + nearness, same units)
-			// replaces raw population as the within-tier key — the 48026 rule: the map view or
-			// the user's location breaks a cross-country postcode tie. Without hints, REFERENTIAL
-			// ordering decides.
-			//
-			// ROAD_TO_V9 §2: this is the site that "orders namesakes", so it is the site that has to
-			// say what it orders by. `compareReferential` is referential DESC with raw population as
-			// the tiebreak, which is provably the SAME ORDER as the `(b.population ?? 0) - (a.population ?? 0)`
-			// it replaces — referential is strictly increasing in population below saturation and
-			// constant above it, and the tiebreak restores the order in the saturated tail. Measured
-			// zero-delta, not assumed: see `place-importance-schema.test.ts` and `resolver-referential-ranking.test.ts`.
-			// Encyclopedic importance is not, and must not become, an input here.
+			// With proximity hints, prominence replaces raw population as the within-tier key.
+			// Without them, referential ordering decides.
+			// Encyclopedic importance does not affect this order.
 			const hasHints = !!query.near || (query.bias?.length ?? 0) > 0
 
 			candidates.sort((a, b) => {

package/lib/capital-schema.ts

@@ -3,15 +3,14 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The `capital` table (#1880's distribution home): the capital-status reference carried INSIDE
- *   `candidate.db`, so an npm consumer who pulled the artifact can run `capital_tier` without the
- *   repo's `data/gazetteer/capitals-v1.json` — which published packages do not ship. One row per
- *   reference entry (241 national capitals + 3,463 admin-1 seats at the 2026-08-24 build); the
- *   loader reads the WHOLE table once into a `CapitalIndex` at session construction, so there is no
- *   per-probe query and no index beyond the rowid.
+ *   The `capital` table: the capital-status reference included inside `candidate.db`, so an npm
+ *   consumer who pulled the artifact can run `capital_tier` without the repo's
+ *   `data/gazetteer/capitals-v1.json`, which published packages do not ship. One row per reference
+ *   entry. The loader reads the whole table once into a `CapitalIndex` at session construction, so
+ *   there is no per-probe query and no index beyond the rowid.
  *
- *   `keys` holds the entry's folded name set as a JSON array — the name-membership conjunct that
- *   keeps the coordinate radius from promoting a capital's same-name neighbours (`capitals.ts`).
+ *   `keys` holds the entry's folded name set as a JSON array, the name-membership conjunct that keeps
+ *   the coordinate radius from promoting a capital's same-name neighbors (`capitals.ts`).
  */
 
 import { tryParsingJSON } from "@mailwoman/core/json"
@@ -22,14 +21,16 @@ import type { CapitalPoint } from "#capitals"
 import { hasTable } from "#sqlite-utils"
 
 /**
- * The table name the builder writes and the reader probes — one word, singular, matching the artifact's other reference
- * tables (`candidate`, `country_codes`).
+ * The table name the builder writes and the reader probes, one word and singular,
+ * matching the artifact's other reference tables (`candidate`, `country_codes`).
  */
 export const CAPITAL_TABLE = "capital"
 
 /**
- * One reference entry as the artifact stores it. `level` is the reference vocabulary (`national` | `admin1`) kept as
- * text — the reader validates on load rather than trusting bytes.
+ * One reference entry as the artifact stores it.
+ *
+ * `level` is the reference vocabulary (`national` | `admin1`) kept as text.
+ * and the reader validates on load rather than trusting bytes.
  */
 export interface CapitalTable {
 	country: string
@@ -43,8 +44,10 @@ export interface CapitalTable {
 }
 
 /**
- * Create the table on a build in progress. Async because Kysely's schema-builder is; called from the candidate build's
- * DDL phase alongside the other typed builders.
+ * Create the table on a build in progress.
+ *
+ * Async because Kysely's schema-builder is.
+ * Called from the candidate build's DDL phase alongside the other typed builders.
  */
 export async function createCapitalTable<DB extends { capital: CapitalTable }>(db: Kysely<DB>): Promise<void> {
 	await db.schema
@@ -58,9 +61,10 @@ export async function createCapitalTable<DB extends { capital: CapitalTable }>(d
 }
 
 /**
- * Read the whole reference out of an artifact, or `null` when the artifact predates the table — the caller then falls
- * back to its next source rather than treating an old artifact as "no capitals" (the meaning-of-zero rule: a missing
- * table is UNMEASURED, an empty one is a finding).
+ * Read the whole reference out of an artifact, or `null` when the artifact predates the table.
+ *
+ * The caller then falls back to its next source rather than treating an old artifact as "no
+ * capitals" (the meaning-of-zero rule: a missing table is unmeasured, an empty one is a finding).
  */
 export function readCapitalPoints<DB>(db: DatabaseClient<DB>): CapitalPoint[] | null {
 	if (!hasTable(db, CAPITAL_TABLE)) return null

package/lib/capitals.ts

@@ -3,19 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The CAPITAL-STATUS reference index (#1880) — answers, for one resolved candidate, "is this
- *   place the national capital or an admin-1 seat of its country?". The consumer is the resolver's
+ *   The capital-status reference index answers whether a resolved candidate is its country's national capital or admin-1 seat.
+ *   The consumer is the resolver's
  *   bounded capital promotion (`@mailwoman/resolver`'s `promoteCapitals`, applied after the fame
- *   key on the bare-toponym class); this module only matches, it never ranks. PURE and
- *   platform-free (the #861 parity discipline).
+ *   key on the bare-toponym class). This module only matches and never ranks. It is pure and
+ *   platform-free.
  *
- *   Matching is an IDENTITY test with three conjuncts: same country, within
- *   {@link CAPITAL_MATCH_RADIUS_KM} of the reference point, and the candidate's own folded name a
- *   member of the reference entry's folded name set (name + romanization + the source's alternate
- *   names, so exonym rows — "Vienna" for Wien — still match). All three are required. The
- *   iteration-1 board run matched on country + coordinate alone, and the 25 km radius promoted
- *   capital-ADJACENT namesakes instead of capitals: North Salt Lake beside the Utah seat, a Gujarat
- *   Indiranagar beside Gandhinagar, Via delle Parti beside Perugia. The name set is what makes the
+ *   A match requires the same country and a distance within {@link CAPITAL_MATCH_RADIUS_KM} of the reference point.
+ *   The candidate's folded name must also appear in the reference entry's folded name set (name + romanization + the source's alternate
+ *   names, so exonym rows such as "Vienna" for Wien still match). The name set is what makes the
  *   radius a centroid-drift allowance rather than a catchment.
  */
 
@@ -24,8 +20,9 @@ import { haversineKm } from "@mailwoman/spatial"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Capital status of one candidate: national capital, admin-1 seat, or neither. Numeric so the resolver's promotion can
- * compare levels.
+ * Capital status of one candidate: national capital, admin-1 seat, or neither.
+ *
+ * Numeric so the resolver's promotion can compare levels.
  */
 export const CAPITAL_LEVEL = {
 	none: 0,
@@ -36,14 +33,15 @@ export const CAPITAL_LEVEL = {
 export type CapitalLevel = (typeof CAPITAL_LEVEL)[keyof typeof CAPITAL_LEVEL]
 
 /**
- * How far a candidate row may sit from the reference point and still read as the same place — a centroid-convention
- * allowance (GeoNames point vs WOF centroid on a metro-scale city), not a catchment: the name-membership conjunct is
- * what excludes neighbours inside the radius.
+ * How far a candidate row may sit from the reference point and still read as the same place.
+ *
+ * A centroid-convention allowance for a GeoNames point against a WOF centroid on a metro-scale city.
+ * The name-membership conjunct excludes neighbors inside the radius.
  */
 export const CAPITAL_MATCH_RADIUS_KM = 25
 
 /**
- * One reference entry, as `data/gazetteer/capitals-v1.json` carries it (`entries[]`).
+ * One reference entry, as recorded in `data/gazetteer/capitals-v1.json` (`entries[]`).
  */
 export interface CapitalPoint {
 	/**
@@ -54,8 +52,8 @@ export interface CapitalPoint {
 	longitude: number
 	level: "national" | "admin1"
 	/**
-	 * Folded name keys (name + romanization + alternate names, `normalizeLocalityForKey` fold) — the membership set for
-	 * the name conjunct.
+	 * Folded name keys (name + romanization + alternate names, `normalizeLocalityForKey` fold).
+	 * The membership set for the name conjunct.
 	 */
 	k: string[]
 }
@@ -73,9 +71,11 @@ interface IndexedPoint {
 }
 
 /**
- * Country-bucketed capital points with the three-conjunct identity probe. Construct from the parsed reference file's
- * `entries` — the loader that reads the file off disk lives with the path owners (`mailwoman`'s resolver backend),
- * keeping this module platform-free.
+ * Country-bucketed capital points with the three-conjunct identity probe.
+ *
+ * Construct from the parsed reference file's `entries`.
+ * The loader that reads the file off disk lives with the path owners
+ * (`mailwoman`'s resolver backend), keeping this module platform-free.
  */
 export class CapitalIndex {
 	readonly #byCountry = new Map<string, IndexedPoint[]>()
@@ -102,13 +102,15 @@ export class CapitalIndex {
 	}
 
 	/**
-	 * The highest capital level whose entry passes all three conjuncts for this place. `none` — never a throw — for a
-	 * missing name, country, or coordinate, an unknown country, or no matching entry.
+	 * The highest capital level whose entry passes all three conjuncts for this place.
+	 *
+	 * `none`, never a throw, for a missing name, country, or coordinate,
+	 * an unknown country, or no matching entry.
 	 */
 	levelOfPlace(
-		name: string | null | undefined,
-		country: string | null | undefined,
-		latitude: number | null | undefined,
+		name: string | null,
+		country: string | null,
+		latitude: number | null,
 		longitude: number | null | undefined
 	): CapitalLevel {
 		if (!name || !country || typeof latitude !== "number" || typeof longitude !== "number") return CAPITAL_LEVEL.none