@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/candidate/scoring.ts

@@ -0,0 +1,222 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { compareReferential, referentialFromPopulation } from "@mailwoman/core/resolver"
+import { haversineKm } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import { exactMatchIDs, officialNameIDs } from "#exact-match"
+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 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,
+	context: {
+		query: FindPlaceQuery
+		placetypes: WOFPlacetype[] | null
+		queryLen: number
+		weights: RankingWeights
+	}
+): PlaceCandidate {
+	const { query, placetypes, queryLen, weights } = context
+
+	// 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)) {
+		score += weights.placetypeMatchBoost
+	}
+
+	if (!placetypes && row.placetype === "locality") {
+		score += weights.localityImplicitBoost
+	}
+
+	if (query.country && row.country === query.country) {
+		score += weights.countryMatchBoost
+	}
+
+	if (query.parentID !== undefined) {
+		score += row.parent_id === query.parentID ? weights.directChildBoost : weights.descendantBoost
+	}
+
+	const extraLen = Math.max(0, row.name.length - queryLen - 3)
+	score -= (weights.lengthPenaltyWeight * extraLen) / 10
+
+	// 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 | undefined
+	// 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)) {
+		const hints: Array<{ lat: number; lon: number; weight: number }> = []
+
+		if (query.near) {
+			hints.push({ lat: query.near.lat, lon: query.near.lon, weight: 1 })
+		}
+
+		for (const b of query.bias ?? []) {
+			hints.push({ lat: b.lat, lon: b.lon, weight: b.weight ?? 1 })
+		}
+
+		let scoreTerm = 0
+
+		for (const h of hints) {
+			const d = haversineKm(h.lat, h.lon, row.lat, row.lon)
+			const decay = h.weight / (1 + d / weights.proximityScaleKm)
+			const prom = decay * weights.biasBoost
+
+			if (prom > proximityTerm) {
+				proximityTerm = prom
+				distanceKm = d
+				scoreTerm = decay * weights.proximityBoost
+			}
+		}
+
+		score += scoreTerm
+	}
+
+	// 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: 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 candidate: PlaceCandidate = {
+		id: row.id,
+		prominence,
+		name: row.name,
+		placetype: row.placetype as WOFPlacetype,
+		country: row.country ?? "",
+		lat: row.lat ?? 0,
+		lon: row.lon ?? 0,
+		parent_id: row.parent_id ?? undefined,
+		score,
+	}
+
+	if (distanceKm !== undefined) {
+		candidate.distanceKm = distanceKm
+	}
+
+	if (row.population !== null && row.population > 0) {
+		candidate.population = row.population
+		// The referential ranking key is derived as a pure function of this row's population,
+		// so it cannot drift from the ordering.
+		candidate.referential = referentialFromPopulation(row.population)
+	}
+
+	// Returned for consumers (annotations / API surfaces); no ranking site reads it.
+	if (row.encyclopedic !== null) {
+		candidate.encyclopedic = row.encyclopedic
+	}
+
+	// Candidate bbox for parity with the wasm lookup. Without it the Node backend's
+	// region→bbox constraint is dead and disambiguation falls to population ranking.
+	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,
+		}
+	}
+
+	return candidate
+}
+
+/**
+ * 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[],
+	options: {
+		db: DatabaseClient<DB>
+		schemaName: string
+		query: FindPlaceQuery
+		weights: RankingWeights
+	}
+): void {
+	const { db, schemaName, query, weights } = options
+
+	// 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,
+			schemaName,
+			candidates.map((c) => c.id as number),
+			query.text
+		)
+
+		// 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) {
+			// 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)
+
+			// 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,
+						schemaName,
+						candidates
+							.filter((c) => exactIDs.has(c.id as number) && (c.population ?? 0) >= weights.officialNameExactFloor)
+							.map((c) => c.id as number),
+						query.text
+					)
+				: undefined
+
+			const kind = (c: PlaceCandidate): number => {
+				if (!exactIDs.has(c.id as number)) return 0
+
+				if (foldQueryText(String(c.name ?? "")) === needle) return 2
+
+				return officialIDs?.has(c.id as number) ? 2 : 1
+			}
+
+			// 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) => {
+				const ax = kind(a)
+				const bx = kind(b)
+
+				if (bx !== ax) return bx - ax
+
+				if (ax >= 1) {
+					if (hasHints) return (b.prominence ?? 0) - (a.prominence ?? 0) || b.score - a.score
+
+					return compareReferential(a, b) || b.score - a.score
+				}
+
+				return b.score - a.score
+			})
+
+			return
+		}
+	}
+
+	candidates.sort((a, b) => b.score - a.score)
+}

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,8 +102,10 @@ 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,

package/lib/coincident-roles.ts

@@ -3,39 +3,37 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
- *   unified gazetteer.
+ *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
  *
- *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
- *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
- *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
- *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
- *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
- *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
- *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
- *   distance math.
+ *   Many places occupy multiple admin tiers under one name: German city-states (Berlin, Hamburg,
+ *   Bremen), Italian provinces whose names match their capital (Milano, Varese), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals (Utrecht,
+ *   Groningen), and Shanghai. When an address surfaces only the admin role because the parser
+ *   dropped the locality span, the resolver has no locality to place. The hierarchy-completion step
+ *   consults this relation. The table preserves the gazetteer's own structure, so the runtime is an
+ *   O(1) membership lookup with no distance math.
  *
- *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
- *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
- *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
- *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
- *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
- *   filter.
+ *   V1 is region-tier only (admin.placetype = `region`), the ~124 places matching the census across
+ *   nine countries. County-tier same-name coincidences are excluded because they are dominated by
+ *   French cantons and JP counties, admin subdivisions whose names match a seat town that do not hit the
+ *   parser-drops-locality failure. Consolidated city-counties (US SF, Denver) are a separate
+ *   follow-up needing a relative-size filter.
  *
- *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
- *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
- *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
- *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
- *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
- *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
- *   never enters the resolver hot path.
+ *   A pair `(admin, locality)` is recorded when the names match case-insensitively, the locality descends from the admin in `ancestors`,
+ *   and their centroids fall within a
+ *   relative tolerance of `toleranceFraction × admin-bbox-diagonal`, floored at `minToleranceKm`.
+ *   The relative term lets a large Italian province admit a city tens of km from its centroid while
+ *   a tiny city-state stays tight. The floor catches city-states whose bbox is small (Bremen's
+ *   centroids sit 9.3 km apart). The tolerance lives only here at build time and never enters the
+ *   resolver hot path.
  *
- *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
- *   uniform (see #405). It's a coarse classification, not critical.
+ *   `relationship_type` is recorded for debuggability and deferred per-type behavior. V1 completion
+ *   is uniform. It is a coarse classification.
  *
- *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). Run incrementally
- *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
- *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ *   This mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). It runs
+ *   incrementally against an existing `admin-global-priority.db` via
+ *   `build-coincident-roles-cli.ts`, and it should also be wired as a post-step of the main
+ *   `scripts/build-unified-wof.ts`.
  */
 
 import type { CoincidentLocality } from "@mailwoman/core/resolver"
@@ -46,13 +44,15 @@ import { tableExists } from "@mailwoman/sqlite/introspection"
 
 import type { WOFDatabase } from "#schema"
 /**
- * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
- * gazetteer build, read by the resolver when a coincident locality has to be chosen.
+ * Table of places that hold more than one admin role.
+ * A locality that is also its county seat.
+ *
+ * Written by the gazetteer build, read by the resolver when a coincident locality has to be chosen.
  */
 export const COINCIDENT_ROLES_TABLE = "coincident_roles"
 
 /**
- * A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`.
+ * A place that plays multiple admin roles, one row of the relation keyed by `admin_id`.
  */
 export interface CoincidentRole {
 	localityID: number
@@ -64,19 +64,27 @@ export interface CoincidentRole {
 
 export interface BuildCoincidentRolesOpts {
 	/**
-	 * Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent).
+	 * Drop + rebuild the table if it already exists.
+	 *
+	 * Default true (the build is cheap + idempotent).
 	 */
 	drop?: boolean
 	/**
-	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`. Default 0.15.
+	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`.
+	 *
+	 * Default 0.15.
 	 */
 	toleranceFraction?: number
 	/**
-	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12.
+	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify.
+	 *
+	 * Default 12.
 	 */
 	minToleranceKm?: number
 	/**
-	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only). Default 2.
+	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
+	 *
+	 * Default 2.
 	 */
 	cityStateMaxKm?: number
 	onProgress?: (phase: string, detail?: string) => void
@@ -106,8 +114,11 @@ interface CandidateRow {
 }
 
 /**
- * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
- * touches `spr`/`names`/`ancestors`. Idempotent.
+ * Derive the coincident-roles relation into `db`.
+ *
+ * Additive, only creating or replacing the `coincident_roles` table.
+ * It never touches `spr`, `names`, or `ancestors`.
+ * Idempotent.
  */
 export function buildCoincidentRoles(
 	db: DatabaseClient<WOFDatabase>,
@@ -127,10 +138,9 @@ export function buildCoincidentRoles(
 
 	onProgress("creating", COINCIDENT_ROLES_TABLE)
 
-	// Raw DDL by design: this is a sync builder consumed by a sync CLI (build-coincident-roles-cli) and
-	// 6 sync unit tests, so routing one table through async Kysely would cascade async through all of
-	// them for no real gain. See AGENTS.md "Database / inline SQL". (The SELECT + INSERT loop below are
-	// likewise the raw hot path.)
+	// Raw DDL by design: this is a sync builder consumed by a sync CLI and six sync unit tests,
+	// so routing one table through async Kysely would cascade async through all of them.
+	// See agents.md "Database / inline SQL".
 	db.exec(`
 		CREATE TABLE IF NOT EXISTS ${COINCIDENT_ROLES_TABLE} (
 			admin_id INTEGER NOT NULL,
@@ -145,9 +155,11 @@ export function buildCoincidentRoles(
 
 	onProgress("scanning")
 
-	// Admin (region/county tier) ⋈ same-name DESCENDANT locality. `place_population` is optional (LEFT
-	// JOIN → 0 when absent). The relative-tolerance filter + relationship classification happen in JS so
-	// the SQL stays a plain join. `spr` exposes the bbox columns we need for the diagonal.
+	// Admin (region or county tier) joined to a same-name descendant locality.
+	// `place_population` is optional, so the left join yields 0 when absent.
+	// JavaScript applies the relative-tolerance filter and classifies the relationship.
+	// SQL stays a plain join.
+	// `spr` exposes the bbox columns needed for the diagonal.
 	const candidates = allRows<CandidateRow>(
 		db.prepare(
 			`SELECT r.id AS admin_id, r.placetype AS admin_placetype, r.country AS country, l.id AS locality_id,
@@ -183,11 +195,12 @@ export function buildCoincidentRoles(
 			const tolerance = Math.max(toleranceFraction * diag, minToleranceKm)
 
 			if (dist > tolerance) continue
-			// v1 is region-tier only: a place is a `city-state` when its centroid coincides with the
-			// region's (Berlin/Hamburg), else `capital-seat` (a region named after its principal city, e.g.
-			// Milano province → Milano comune). `consolidated-county` is reserved for a future county-tier
-			// pass (US SF/Denver) — excluded from v1 because county-tier same-name coincidences are
-			// dominated by French cantons / JP counties that don't hit the parser-drops-locality failure.
+			// v1 is region-tier only: a place is `city-state` when its centroid coincides with the
+			// region's (Berlin, Hamburg), otherwise `capital-seat` (a region whose name matches its
+			// principal city, such as Milano province and Milano comune). `consolidated-county` is
+			// reserved for a future county-tier pass (US SF, Denver), excluded from v1 because
+			// county-tier same-name coincidences are dominated by French cantons and JP counties
+			// that do not hit the parser-drops-locality failure.
 			const relationshipType = dist <= cityStateMaxKm ? "city-state" : "capital-seat"
 			insert.run(c.admin_id, c.locality_id, relationshipType, c.admin_placetype, dist, c.pop)
 
@@ -209,16 +222,20 @@ export function buildCoincidentRoles(
 }
 
 /**
- * True iff the relation table exists. Used by the resolver to decide whether completion can run.
+ * True iff the relation table exists.
+ *
+ * Used by the resolver to decide whether completion can run.
  */
 export function coincidentRolesExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, COINCIDENT_ROLES_TABLE)
 }
 
 /**
- * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each admin may map to
- * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
- * map when the table is absent.
+ * Load the relation into an in-memory map keyed by `admin_id` for an O(1) runtime lookup.
+ *
+ * Each admin may map to multiple same-name descendants.
+ * The consumer disambiguates by minimum distance, then population, then abstains.
+ * Returns an empty map when the table is absent.
  */
 export function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, CoincidentRole[]> {
 	const map = new Map<number, CoincidentRole[]>()
@@ -261,8 +278,10 @@ export function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, Coi
 }
 
 /**
- * The relation joined with `spr`, as an in-memory map keyed by `admin_id` — the resolver-facing view of
- * {@link loadCoincidentRoles}, carrying the canonical name and coordinates each coincident locality resolves to.
+ * The relation joined with `spr`, as an in-memory map keyed by `admin_id`.
+ *
+ * The resolver-facing view of {@link loadCoincidentRoles}, carrying the canonical name
+ * and coordinates each coincident locality resolves to.
  * Returns an empty map when the relation table is absent.
  */
 export function loadCoincidentLocalities<DB>(db: DatabaseClient<DB>): Map<number, CoincidentLocality[]> {

package/lib/convention/schema.ts

@@ -4,14 +4,14 @@
  * @author Teffen Ellis, et al.
  *
  *   Typed schema for the convention asset — the `address_convention` table `SqliteConventionSource` probes, plus the
- *   `meta` provenance row every sealed artifact here carries. The interface is the read/write contract and
+ *   `meta` provenance row every sealed artifact here includes. The interface is the read/write interface and
  *   {@link createAddressConventionTable} creates the table, so a column added to one is a compile error against the
  *   other.
  */
 
 import type { Kysely } from "kysely"
 
-import { ADDRESS_CONVENTION_TABLE } from "#convention/index"
+import { ADDRESS_CONVENTION_TABLE } from "#convention"
 
 /**
  * One convention profile, keyed by the WOF admin polygon it attaches to.
@@ -19,7 +19,9 @@ import { ADDRESS_CONVENTION_TABLE } from "#convention/index"
 export interface AddressConventionTable {
 	wof_id: number
 	/**
-	 * The `Convention` record, JSON-encoded. Parsed at read time by `SqliteConventionSource`.
+	 * The `Convention` record, JSON-encoded.
+	 *
+	 * Parsed at read time by `SqliteConventionSource`.
 	 */
 	convention: string
 	/**
@@ -42,14 +44,18 @@ export interface ConventionDatabase {
 }
 
 /**
- * The slice of a Kysely handle the convention 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.
+ * The subset of a Kysely handle the convention 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 ConventionSchemaHandle = Pick<Kysely<ConventionDatabase>, "schema">
 
 /**
- * Create `address_convention`. The table name comes from {@link ADDRESS_CONVENTION_TABLE} so the build script, the
- * runtime source, and the extract auto-detect cannot drift apart.
+ * Create `address_convention`.
+ *
+ * The table name comes from {@link ADDRESS_CONVENTION_TABLE} so the build script, the runtime source.
+ * The extract auto-detect stays aligned with it.
  */
 export async function createAddressConventionTable(db: ConventionSchemaHandle): Promise<void> {
 	await db.schema