@mailwoman/resolver-wof-sqlite 10.8.0 → 11.0.0

package/lib/coincident-roles.ts

@@ -1,347 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
- *
- *   Some 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
- *   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 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 and deferred per-type behavior. V1 completion
- *   is uniform. It is a coarse classification.
- *
- *   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"
-import { allRows } from "@mailwoman/core/utils"
-import { haversine } from "@mailwoman/spatial/geometries/point/distance"
-import type { DatabaseClient } from "@mailwoman/sqlite/client"
-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.
- */
-export const COINCIDENT_ROLES_TABLE = "coincident_roles"
-
-/**
- * A place that plays multiple admin roles, one row of the relation keyed by `admin_id`.
- */
-export interface CoincidentRole {
-	localityID: number
-	relationshipType: "city-state" | "capital-seat" | "consolidated-county"
-	adminPlacetype: string
-	distanceKm: number
-	population: number
-}
-
-export interface BuildCoincidentRolesOpts {
-	/**
-	 * Drop + rebuild the table if it already exists.
-	 *
-	 * @defaultValue `true` (the build is cheap + idempotent)
-	 */
-	drop?: boolean
-	/**
-	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`.
-	 *
-	 * @defaultValue `0.15`
-	 */
-	toleranceFraction?: number
-	/**
-	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify.
-	 *
-	 * @defaultValue `12`
-	 */
-	minToleranceKm?: number
-	/**
-	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
-	 *
-	 * @defaultValue `2`
-	 */
-	cityStateMaxKm?: number
-	onProgress?: (phase: string, detail?: string) => void
-}
-
-export interface BuildCoincidentRolesResult {
-	created: boolean
-	rowCount: number
-	byCountry: Record<string, number>
-	durationMs: number
-}
-
-interface CandidateRow {
-	admin_id: number
-	admin_placetype: string
-	country: string
-	locality_id: number
-	rlat: number
-	rlon: number
-	llat: number
-	llon: number
-	min_latitude: number
-	min_longitude: number
-	max_latitude: number
-	max_longitude: number
-	pop: number
-}
-
-/**
- * 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>,
-	opts: BuildCoincidentRolesOpts = {}
-): BuildCoincidentRolesResult {
-	const start = Date.now()
-	const drop = opts.drop ?? true
-	const toleranceFraction = opts.toleranceFraction ?? 0.15
-	const minToleranceKm = opts.minToleranceKm ?? 12
-	const cityStateMaxKm = opts.cityStateMaxKm ?? 2
-	const onProgress = opts.onProgress ?? (() => {})
-
-	if (tableExists(db, COINCIDENT_ROLES_TABLE) && drop) {
-		onProgress("dropping", COINCIDENT_ROLES_TABLE)
-		db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`)
-	}
-
-	onProgress("creating", COINCIDENT_ROLES_TABLE)
-
-	// 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,
-			locality_id INTEGER NOT NULL,
-			relationship_type TEXT NOT NULL,
-			admin_placetype TEXT NOT NULL,
-			distance_km REAL NOT NULL,
-			locality_population INTEGER NOT NULL DEFAULT 0,
-			PRIMARY KEY (admin_id, locality_id)
-		)
-	`)
-
-	onProgress("scanning")
-
-	// 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,
-				r.latitude AS rlat, r.longitude AS rlon, l.latitude AS llat, l.longitude AS llon,
-				r.min_latitude, r.min_longitude, r.max_latitude, r.max_longitude,
-				COALESCE(p.population, 0) AS pop
-			FROM spr r
-			JOIN spr l ON lower(l.name) = lower(r.name) AND l.placetype = 'locality'
-				AND l.is_current != 0 AND l.is_deprecated = 0
-			JOIN ${"ancestors"} a ON a.id = l.id AND a.ancestor_id = r.id
-			LEFT JOIN place_population p ON p.id = l.id
-			WHERE r.placetype = 'region'
-				AND r.is_current != 0 AND r.is_deprecated = 0`
-		)
-	)
-
-	onProgress("filtering", `${candidates.length} candidates`)
-
-	const insert = db.prepare(
-		`INSERT OR REPLACE INTO ${COINCIDENT_ROLES_TABLE}
-			(admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population)
-			VALUES (?, ?, ?, ?, ?, ?)`
-	)
-
-	const byCountry: Record<string, number> = {}
-	let rowCount = 0
-	db.exec("BEGIN")
-
-	try {
-		for (const c of candidates) {
-			const dist = haversine(c.rlat, c.rlon, c.llat, c.llon)
-			const diag = haversine(c.min_latitude, c.min_longitude, c.max_latitude, c.max_longitude)
-			const tolerance = Math.max(toleranceFraction * diag, minToleranceKm)
-
-			if (dist > tolerance) continue
-			// 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)
-
-			rowCount++
-			byCountry[c.country] = (byCountry[c.country] ?? 0) + 1
-		}
-
-		db.exec("COMMIT")
-	} catch (error) {
-		db.exec("ROLLBACK")
-		throw error
-	}
-
-	db.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON ${COINCIDENT_ROLES_TABLE} (admin_id)`)
-
-	onProgress("done", `${rowCount} coincident-role rows`)
-
-	return { created: true, rowCount, byCountry, durationMs: Date.now() - start }
-}
-
-/**
- * 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 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[]>()
-
-	if (!coincidentRolesExists(db)) return map
-
-	const rows = allRows<{
-		admin_id: number
-		locality_id: number
-		relationship_type: CoincidentRole["relationshipType"]
-		admin_placetype: string
-		distance_km: number
-		locality_population: number
-	}>(
-		db.prepare(
-			`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
-			FROM ${COINCIDENT_ROLES_TABLE}`
-		)
-	)
-
-	for (const r of rows) {
-		const entry: CoincidentRole = {
-			localityID: r.locality_id,
-			relationshipType: r.relationship_type,
-			adminPlacetype: r.admin_placetype,
-			distanceKm: r.distance_km,
-			population: r.locality_population,
-		}
-
-		const list = map.get(r.admin_id)
-
-		if (list) {
-			list.push(entry)
-		} else {
-			map.set(r.admin_id, [entry])
-		}
-	}
-
-	return map
-}
-
-/**
- * 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[]> {
-	const map = new Map<number, CoincidentLocality[]>()
-
-	if (coincidentRolesExists(db)) {
-		const rows = allRows<{
-			adminID: number
-			id: number
-			name: string
-			country: string
-			lat: number
-			lon: number
-			relationshipType: string
-			population: number
-			distanceKm: number
-		}>(
-			db.prepare(
-				`SELECT cr.admin_id AS adminID, s.id AS id, s.name AS name, s.country AS country,
-					s.latitude AS lat, s.longitude AS lon,
-					cr.relationship_type AS relationshipType, cr.locality_population AS population,
-					cr.distance_km AS distanceKm
-				FROM ${COINCIDENT_ROLES_TABLE} cr JOIN spr s ON s.id = cr.locality_id`
-			)
-		)
-
-		for (const r of rows) {
-			const candidate: CoincidentLocality = {
-				id: r.id,
-				name: r.name,
-				placetype: "locality",
-				country: r.country,
-				lat: r.lat,
-				lon: r.lon,
-				score: 0,
-				relationshipType: r.relationshipType,
-				population: r.population,
-				distanceKm: r.distanceKm,
-				parent_id: null,
-				prominence: null,
-				referential: null,
-				encyclopedic: null,
-				importance: null,
-				exactMatch: null,
-				mismatch: null,
-				resolutionQuality: null,
-				containedByQualifier: null,
-				regionScopeMiss: null,
-				variantAliasExempted: null,
-			}
-
-			const list = map.get(r.adminID)
-
-			if (list) {
-				list.push(candidate)
-			} else {
-				map.set(r.adminID, [candidate])
-			}
-		}
-	}
-
-	return map
-}

package/out/coincident-roles.d.ts

@@ -1,121 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
- *
- *   Some 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
- *   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 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 and deferred per-type behavior. V1 completion
- *   is uniform. It is a coarse classification.
- *
- *   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";
-import type { DatabaseClient } from "@mailwoman/sqlite/client";
-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.
- */
-export declare const COINCIDENT_ROLES_TABLE = "coincident_roles";
-/**
- * A place that plays multiple admin roles, one row of the relation keyed by `admin_id`.
- */
-export interface CoincidentRole {
-    localityID: number;
-    relationshipType: "city-state" | "capital-seat" | "consolidated-county";
-    adminPlacetype: string;
-    distanceKm: number;
-    population: number;
-}
-export interface BuildCoincidentRolesOpts {
-    /**
-     * Drop + rebuild the table if it already exists.
-     *
-     * @defaultValue `true` (the build is cheap + idempotent)
-     */
-    drop?: boolean;
-    /**
-     * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`.
-     *
-     * @defaultValue `0.15`
-     */
-    toleranceFraction?: number;
-    /**
-     * Floor (km) under the relative tolerance, so small-bbox city-states still qualify.
-     *
-     * @defaultValue `12`
-     */
-    minToleranceKm?: number;
-    /**
-     * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
-     *
-     * @defaultValue `2`
-     */
-    cityStateMaxKm?: number;
-    onProgress?: (phase: string, detail?: string) => void;
-}
-export interface BuildCoincidentRolesResult {
-    created: boolean;
-    rowCount: number;
-    byCountry: Record<string, number>;
-    durationMs: number;
-}
-/**
- * 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 declare function buildCoincidentRoles(db: DatabaseClient<WOFDatabase>, opts?: BuildCoincidentRolesOpts): BuildCoincidentRolesResult;
-/**
- * True iff the relation table exists.
- *
- * Used by the resolver to decide whether completion can run.
- */
-export declare function coincidentRolesExists<DB>(db: DatabaseClient<DB>): boolean;
-/**
- * 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 declare function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, CoincidentRole[]>;
-/**
- * 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 declare function loadCoincidentLocalities<DB>(db: DatabaseClient<DB>): Map<number, CoincidentLocality[]>;
-//# sourceMappingURL=coincident-roles.d.ts.map

package/out/coincident-roles.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"coincident-roles.d.ts","sourceRoot":"","sources":["../lib/coincident-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAGlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,YAAY,GAAG,cAAc,GAAG,qBAAqB,CAAA;IACvE,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,EAAE,MAAM,CAAA;CAClB;AAkBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,EAC/B,IAAI,GAAE,wBAA6B,GACjC,0BAA0B,CAgG5B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,OAAO,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAsC7F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CA4DtG"}

package/out/coincident-roles.js

@@ -1,222 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
- *
- *   Some 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
- *   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 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 and deferred per-type behavior. V1 completion
- *   is uniform. It is a coarse classification.
- *
- *   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 { allRows } from "@mailwoman/core/utils";
-import { haversine } from "@mailwoman/spatial/geometries/point/distance";
-import { tableExists } from "@mailwoman/sqlite/introspection";
-/**
- * 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";
-/**
- * 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, opts = {}) {
-    const start = Date.now();
-    const drop = opts.drop ?? true;
-    const toleranceFraction = opts.toleranceFraction ?? 0.15;
-    const minToleranceKm = opts.minToleranceKm ?? 12;
-    const cityStateMaxKm = opts.cityStateMaxKm ?? 2;
-    const onProgress = opts.onProgress ?? (() => { });
-    if (tableExists(db, COINCIDENT_ROLES_TABLE) && drop) {
-        onProgress("dropping", COINCIDENT_ROLES_TABLE);
-        db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`);
-    }
-    onProgress("creating", COINCIDENT_ROLES_TABLE);
-    // 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,
-			locality_id INTEGER NOT NULL,
-			relationship_type TEXT NOT NULL,
-			admin_placetype TEXT NOT NULL,
-			distance_km REAL NOT NULL,
-			locality_population INTEGER NOT NULL DEFAULT 0,
-			PRIMARY KEY (admin_id, locality_id)
-		)
-	`);
-    onProgress("scanning");
-    // 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(db.prepare(`SELECT r.id AS admin_id, r.placetype AS admin_placetype, r.country AS country, l.id AS locality_id,
-				r.latitude AS rlat, r.longitude AS rlon, l.latitude AS llat, l.longitude AS llon,
-				r.min_latitude, r.min_longitude, r.max_latitude, r.max_longitude,
-				COALESCE(p.population, 0) AS pop
-			FROM spr r
-			JOIN spr l ON lower(l.name) = lower(r.name) AND l.placetype = 'locality'
-				AND l.is_current != 0 AND l.is_deprecated = 0
-			JOIN ${"ancestors"} a ON a.id = l.id AND a.ancestor_id = r.id
-			LEFT JOIN place_population p ON p.id = l.id
-			WHERE r.placetype = 'region'
-				AND r.is_current != 0 AND r.is_deprecated = 0`));
-    onProgress("filtering", `${candidates.length} candidates`);
-    const insert = db.prepare(`INSERT OR REPLACE INTO ${COINCIDENT_ROLES_TABLE}
-			(admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population)
-			VALUES (?, ?, ?, ?, ?, ?)`);
-    const byCountry = {};
-    let rowCount = 0;
-    db.exec("BEGIN");
-    try {
-        for (const c of candidates) {
-            const dist = haversine(c.rlat, c.rlon, c.llat, c.llon);
-            const diag = haversine(c.min_latitude, c.min_longitude, c.max_latitude, c.max_longitude);
-            const tolerance = Math.max(toleranceFraction * diag, minToleranceKm);
-            if (dist > tolerance)
-                continue;
-            // 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);
-            rowCount++;
-            byCountry[c.country] = (byCountry[c.country] ?? 0) + 1;
-        }
-        db.exec("COMMIT");
-    }
-    catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
-    }
-    db.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON ${COINCIDENT_ROLES_TABLE} (admin_id)`);
-    onProgress("done", `${rowCount} coincident-role rows`);
-    return { created: true, rowCount, byCountry, durationMs: Date.now() - start };
-}
-/**
- * True iff the relation table exists.
- *
- * Used by the resolver to decide whether completion can run.
- */
-export function coincidentRolesExists(db) {
-    return tableExists(db, COINCIDENT_ROLES_TABLE);
-}
-/**
- * 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) {
-    const map = new Map();
-    if (!coincidentRolesExists(db))
-        return map;
-    const rows = allRows(db.prepare(`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
-			FROM ${COINCIDENT_ROLES_TABLE}`));
-    for (const r of rows) {
-        const entry = {
-            localityID: r.locality_id,
-            relationshipType: r.relationship_type,
-            adminPlacetype: r.admin_placetype,
-            distanceKm: r.distance_km,
-            population: r.locality_population,
-        };
-        const list = map.get(r.admin_id);
-        if (list) {
-            list.push(entry);
-        }
-        else {
-            map.set(r.admin_id, [entry]);
-        }
-    }
-    return map;
-}
-/**
- * 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) {
-    const map = new Map();
-    if (coincidentRolesExists(db)) {
-        const rows = allRows(db.prepare(`SELECT cr.admin_id AS adminID, s.id AS id, s.name AS name, s.country AS country,
-					s.latitude AS lat, s.longitude AS lon,
-					cr.relationship_type AS relationshipType, cr.locality_population AS population,
-					cr.distance_km AS distanceKm
-				FROM ${COINCIDENT_ROLES_TABLE} cr JOIN spr s ON s.id = cr.locality_id`));
-        for (const r of rows) {
-            const candidate = {
-                id: r.id,
-                name: r.name,
-                placetype: "locality",
-                country: r.country,
-                lat: r.lat,
-                lon: r.lon,
-                score: 0,
-                relationshipType: r.relationshipType,
-                population: r.population,
-                distanceKm: r.distanceKm,
-                parent_id: null,
-                prominence: null,
-                referential: null,
-                encyclopedic: null,
-                importance: null,
-                exactMatch: null,
-                mismatch: null,
-                resolutionQuality: null,
-                containedByQualifier: null,
-                regionScopeMiss: null,
-                variantAliasExempted: null,
-            };
-            const list = map.get(r.adminID);
-            if (list) {
-                list.push(candidate);
-            }
-            else {
-                map.set(r.adminID, [candidate]);
-            }
-        }
-    }
-    return map;
-}
-//# sourceMappingURL=coincident-roles.js.map