@mailwoman/resolver-wof-sqlite 7.2.0 → 7.2.1

package/sharding.ts

@@ -0,0 +1,235 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Multi-shard support for `WOFSqlitePlaceLookup` — opens multiple WOF SQLite distributions on one
+ *   connection via `ATTACH DATABASE`, and routes queries to the right shard based on placetype.
+ *
+ *   ## The FTS5 syntax rule that drove this design
+ *
+ *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
+ *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
+ *   the spike at PR review time; documented as `_SHARD_RULE.md` should it ever bite again.
+ *
+ *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *
+ *   ```sql
+ *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ * ```
+ *
+ *   Identical table names across attached shards (which is what we have — every shard ships its own
+ *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
+ *   scope.
+ */
+
+import { basename } from "node:path"
+
+/**
+ * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each shard
+ * gets a stable, predictable handle.
+ *
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
+ * `_` for SQL identifier safety.
+ *
+ * Examples:
+ *
+ * - `whosonfirst-data-admin-us-latest.db` → `admin_us`
+ * - `whosonfirst-data-postalcode-us-latest.db` → `postalcode_us`
+ * - `whosonfirst-data-admin-latest.db` → `admin`
+ * - `my-custom.db` → `my_custom`
+ *
+ * Callers can override the derived name explicitly via `ShardConfig.schemaName` when the filename doesn't follow WOF
+ * convention.
+ */
+export function deriveSchemaName(path: string): string {
+	const stem = basename(path)
+		.replace(/^whosonfirst-data-/u, "")
+		.replace(/-latest\.db$/u, "")
+		.replace(/\.db$/u, "")
+		.replace(/[^a-zA-Z0-9_]/g, "_")
+
+	if (!stem) {
+		throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`)
+	}
+
+	return stem
+}
+
+/**
+ * Per-shard configuration. The simple form is just a path string — the schema name is derived from it. The object form
+ * lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach an
+ * extra hint about which placetypes route here.
+ */
+export interface ShardConfig {
+	path: string
+	/**
+	 * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or when you want a
+	 * memorable handle. Must be a valid SQLite identifier — `[a-zA-Z_][a-zA-Z0-9_]*`.
+	 */
+	schemaName?: string
+	/**
+	 * Optional explicit list of placetypes this shard serves. When set, queries against any listed placetype are routed
+	 * to this shard. When omitted, routing falls back to a name-match heuristic: a shard whose `schemaName` contains the
+	 * placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+	 */
+	placetypes?: readonly string[]
+}
+
+/**
+ * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint. Used internally by
+ * `WOFSqlitePlaceLookup` so the routing logic operates on uniform structures.
+ */
+export interface ResolvedShard {
+	path: string
+	schemaName: string
+	placetypes: readonly string[]
+}
+
+/** SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`. */
+const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
+
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
+ * `ShardConfig` objects) into a uniform `ResolvedShard[]`.
+ *
+ * The first shard becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
+ * shards keep their derived (or override) schema name.
+ */
+export function resolveShards(input: string | ReadonlyArray<string | ShardConfig>): ResolvedShard[] {
+	const list = typeof input === "string" ? [input] : input
+
+	if (list.length === 0) throw new Error("resolveShards: at least one shard is required")
+
+	const seen = new Set<string>()
+	const out: ResolvedShard[] = []
+
+	for (let i = 0; i < list.length; i++) {
+		const entry = list[i]!
+		const cfg: ShardConfig = typeof entry === "string" ? { path: entry } : entry
+		const derived = cfg.schemaName ?? deriveSchemaName(cfg.path)
+
+		if (!SQLITE_IDENT_RE.test(derived)) {
+			throw new Error(
+				`resolveShards: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
+					`(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
+					`{ path, schemaName } to override.`
+			)
+		}
+		// The first shard is always main per SQLite semantics — its derived name is informational
+		// only. Subsequent shards must have unique non-main names.
+		const schemaName = i === 0 ? "main" : derived
+
+		if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
+			throw new Error(
+				`resolveShards: schema name ${JSON.stringify(schemaName)} collides ` +
+					`(either with "main" or another shard). Pass an explicit { path, schemaName }.`
+			)
+		}
+		seen.add(schemaName)
+		out.push({
+			path: cfg.path,
+			schemaName,
+			placetypes: cfg.placetypes ?? [],
+		})
+	}
+
+	return out
+}
+
+/**
+ * Pick the shard to route a query to given the requested placetype(s).
+ *
+ * Routing rules, in order:
+ *
+ * 1. If any shard has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main shard's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`), use
+ *    it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately doesn't UNION across shards — BM25 scores aren't comparable across separately- indexed corpora, and
+ * the typical mailwoman query has a single placetype anyway. If a caller needs cross-shard results they can issue two
+ * `findPlace` calls.
+ */
+/**
+ * All placetype-matching shards, in routing order (the country-aware pick chooses among these). Used by the bias path:
+ * a country-less postcode query with proximity hints fans out across every matching shard and merges, because
+ * single-shard routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
+ * postalcode-us AND postalcode-intl).
+ */
+export function pickShardsForPlacetype(shards: ResolvedShard[], placetype: string | undefined): ResolvedShard[] {
+	if (!placetype) return [shards[0]!]
+	const matches: ResolvedShard[] = []
+
+	for (const s of shards) {
+		if (s.placetypes.includes(placetype)) {
+			matches.push(s)
+		}
+	}
+
+	for (const s of shards) {
+		if (s.schemaName === "main" || matches.includes(s)) continue
+
+		if (
+			s.schemaName === placetype ||
+			s.schemaName.startsWith(`${placetype}_`) ||
+			s.schemaName.endsWith(`_${placetype}`)
+		) {
+			matches.push(s)
+		}
+	}
+
+	return matches.length > 0 ? matches : [shards[0]!]
+}
+
+export function pickShardForPlacetype(
+	shards: ResolvedShard[],
+	placetype: string | undefined,
+	opts?: {
+		/**
+		 * #920: the query's country constraint, when the caller has one. With MULTIPLE shards matching a placetype
+		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first shard and
+		 * starved the rest — a FI postcode could never reach the tail shard. When `country` is given and a matching shard's
+		 * probed country set contains it, that shard wins; shards without the country are skipped; the placetype-match
+		 * order remains the tiebreak when no shard claims the country (or none was probed).
+		 */
+		country?: string
+		/** Per-schema probed country sets (see `WOFSqlitePlaceLookup`'s construction probe). */
+		countriesBySchema?: ReadonlyMap<string, ReadonlySet<string>>
+	}
+): ResolvedShard {
+	if (!placetype) return shards[0]!
+
+	const matches: ResolvedShard[] = []
+
+	for (const s of shards) {
+		if (s.placetypes.includes(placetype)) {
+			matches.push(s)
+		}
+	}
+
+	for (const s of shards) {
+		if (s.schemaName === "main" || matches.includes(s)) continue
+
+		// Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
+		// placetype to appear at a word boundary in the schema name to avoid false hits like
+		// `region` matching `arboregion`.
+		if (
+			s.schemaName === placetype ||
+			s.schemaName.startsWith(`${placetype}_`) ||
+			s.schemaName.endsWith(`_${placetype}`)
+		) {
+			matches.push(s)
+		}
+	}
+
+	if (matches.length === 0) return shards[0]!
+
+	if (opts?.country && opts.countriesBySchema) {
+		for (const s of matches) {
+			if (opts.countriesBySchema.get(s.schemaName)?.has(opts.country)) return s
+		}
+	}
+
+	return matches[0]!
+}

package/sqlite-convention-source.ts

@@ -0,0 +1,61 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `SqliteConventionSource` — a `ConventionSource` backed by the build-from-source convention asset
+ *   (#290, Direction E). Conventions live in a read-only, provenance-stamped `address_convention`
+ *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
+ *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
+ *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
+ *   value in memory `feedback-no-load-bearing-trivia`).
+ *
+ *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
+ *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
+ *   swallowed.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { ADDRESS_CONVENTION_TABLE, type Convention, type ConventionSource } from "./convention.ts"
+
+export class SqliteConventionSource implements ConventionSource {
+	readonly #db: DatabaseSync
+	readonly #schema: string
+	/** Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once. */
+	readonly #cache = new Map<number, Convention | null>()
+
+	/**
+	 * @param db An open handle to a DB that has the convention asset attached (or is it).
+	 * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed shard name —
+	 *   `WOFSqlitePlaceLookup` auto-detects which shard carries the table).
+	 */
+	constructor(db: DatabaseSync, schema: string) {
+		this.#db = db
+		this.#schema = schema
+	}
+
+	get(wofID: number): Convention | undefined {
+		const cached = this.#cache.get(wofID)
+
+		if (cached !== undefined) return cached ?? undefined
+		let value: Convention | null = null
+
+		try {
+			const row = this.#db
+				.prepare(`SELECT convention FROM ${this.#schema}.${ADDRESS_CONVENTION_TABLE} WHERE wof_id = ?`)
+				.get(wofID) as { convention: string } | undefined
+
+			if (row?.convention) {
+				value = JSON.parse(row.convention) as Convention
+			}
+		} catch {
+			// Malformed JSON or a missing table → treat as no override (the chain falls back to
+			// WORLD_DEFAULT). The build script validates structure, so this is purely defensive.
+			value = null
+		}
+		this.#cache.set(wofID, value)
+
+		return value ?? undefined
+	}
+}

package/sqlite-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Small shared helpers for the SQLite-backed lookups.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+/**
+ * True when `name` is a table in the open database. The street-level lookups use this to degrade gracefully on an
+ * empty/tableless shard — an interrupted `build-*-shard.ts`, or a stray 0-byte file (e.g. `sqlite3 <missing>.db "…"`
+ * CREATES one) — rather than throwing `no such table` at construction and taking down a whole state's geocode (#568). A
+ * missing table makes the lookup a no-op miss.
+ */
+export function hasTable(db: DatabaseSync, name: string): boolean {
+	try {
+		const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(name)
+
+		return row !== undefined
+	} catch {
+		return false
+	}
+}

package/street-centroid-schema.ts

@@ -0,0 +1,124 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the DERIVED STREET-CENTROID shard (`street-centroids-<cc>.db`, built by
+ *   `ban/scripts/build-street-centroid-shard.ts` — the #1042 street-level tier behind "street-only
+ *   FR queries deserve a street-level answer"). The shard is a `GROUP BY street` roll-up of the
+ *   sealed rooftop address-point shard: one row per (street, postcode, commune) carrying the street's
+ *   CENTROID + bounding-box EXTENT + member-point count. No new data source — a derived artifact.
+ *
+ *   Single source of truth for the columns shared by the BUILDER (a positional prepared INSERT for
+ *   throughput) and the READER ({@link StreetCentroidSqliteLookup}), so a column rename in one is a
+ *   compile error in the other — the same discipline as `address-point-schema.ts`.
+ *
+ *   Probe scopes (most-selective first): by `postcode`, else by `locality_base` (the
+ *   arrondissement-stripped commune — see `stripArrondissement`; BAN names Paris/Lyon/Marseille rows
+ *   per arrondissement, but a query names the base commune). The reader WEIGHTED-aggregates across the
+ *   matched rows (by `point_count`) so a locality-scope probe returns the street's grand centroid over
+ *   every postcode/arrondissement it spans.
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * One street roll-up. `(street_norm, postcode, locality_base)` is unique. `lat`/`lon` are the UNWEIGHTED mean of the
+ * group's member address points (each source row = one point), so a cross-group weighted mean (`SUM(lat*point_count) /
+ * SUM(point_count)`) reconstructs the grand centroid. `min_/max_lat/lon` are the group's extent (the reader turns the
+ * bbox diagonal into an honest `uncertainty_m`).
+ */
+export interface StreetCentroidTable {
+	/** Shared `normalizeStreetForKeyLocale` of the street — the build/query-consistent probe key. */
+	street_norm: string
+	/** The 5-digit postcode of this group, or null when the source row carried none. */
+	postcode: string | null
+	/** Arrondissement-stripped commune (`stripArrondissement(normalizeLocalityForKey(commune))`) — the fallback scope. */
+	locality_base: string
+	/** Weighted-mean centroid latitude of the street's member points. */
+	lat: number
+	/** Weighted-mean centroid longitude of the street's member points. */
+	lon: number
+	min_lat: number
+	max_lat: number
+	min_lon: number
+	max_lon: number
+	/** Member address-point count — the weight for a cross-group centroid aggregate. */
+	point_count: number
+	/** A representative street name as it appeared in the source (display / debugging). */
+	street_raw: string
+	/** Provenance: the register this street was derived from (e.g. `ban:fr`). */
+	source: string
+	/** The pinned data release the underlying points came from. */
+	release: string
+	/**
+	 * #727 phase-4c: `foldStreetSurface(street_raw)` — the contract-fold street-NAME existence key for
+	 * {@link StreetLocalityEvidence}. Distinct from `street_norm` (the `street-normalize` geocoding key): the
+	 * name-evidence rerank folds the model's street surface with the SAME `foldStreetSurface` used to build this column
+	 * (the fold-parity contract), so it must not drift from `street_norm`'s richer normalizer. Indexed (`idx_sc_name`)
+	 * for a direct seek.
+	 */
+	name_key: string
+}
+
+/** The street-centroid database schema for `new DatabaseClient<StreetCentroidDatabase>(...)`. */
+export interface StreetCentroidDatabase {
+	street_centroid: StreetCentroidTable
+}
+
+/**
+ * The `street_centroid` columns in INSERT order. The builder's positional prepared statement derives its placeholder
+ * list from this, so the positional order can't drift from the DDL / the reader.
+ */
+export const STREET_CENTROID_COLUMNS = [
+	"street_norm",
+	"postcode",
+	"locality_base",
+	"lat",
+	"lon",
+	"min_lat",
+	"max_lat",
+	"min_lon",
+	"max_lon",
+	"point_count",
+	"street_raw",
+	"source",
+	"release",
+	"name_key",
+] as const
+
+/** Create the `street_centroid` table — called before the streaming bulk load. */
+export async function createStreetCentroidTable(db: Kysely<StreetCentroidDatabase>): Promise<void> {
+	await db.schema
+		.createTable("street_centroid")
+		.addColumn("street_norm", "text", (c) => c.notNull())
+		.addColumn("postcode", "text")
+		.addColumn("locality_base", "text", (c) => c.notNull())
+		.addColumn("lat", "real", (c) => c.notNull())
+		.addColumn("lon", "real", (c) => c.notNull())
+		.addColumn("min_lat", "real", (c) => c.notNull())
+		.addColumn("max_lat", "real", (c) => c.notNull())
+		.addColumn("min_lon", "real", (c) => c.notNull())
+		.addColumn("max_lon", "real", (c) => c.notNull())
+		.addColumn("point_count", "integer", (c) => c.notNull())
+		.addColumn("street_raw", "text", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.addColumn("release", "text", (c) => c.notNull())
+		.addColumn("name_key", "text", (c) => c.notNull())
+		.execute()
+}
+
+/**
+ * Create the probe indexes: the two geocoding-scope indexes (postcode, locality-base) the resolver reader relies on,
+ * plus `idx_sc_name` — the #727 phase-4c name-existence key for a direct `name_key = ?` seek (the unscoped fragment
+ * lookup; without it that query skip-scans `idx_sc_postcode` at ~5 ms/probe).
+ */
+export async function createStreetCentroidIndexes(db: Kysely<StreetCentroidDatabase>): Promise<void> {
+	await db.schema.createIndex("idx_sc_postcode").on("street_centroid").columns(["postcode", "street_norm"]).execute()
+	await db.schema
+		.createIndex("idx_sc_locality")
+		.on("street_centroid")
+		.columns(["locality_base", "street_norm"])
+		.execute()
+	await db.schema.createIndex("idx_sc_name").on("street_centroid").columns(["name_key"]).execute()
+}

package/street-centroid.ts

@@ -0,0 +1,124 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   SQLite implementation of core's `StreetCentroidLookup` (#1042): the street-level tier BELOW the
+ *   exact address-point tier and ABOVE admin-centroid resolution. Given a street name (no house
+ *   number) plus a postcode/commune scope, it returns the street's CENTROID + an honest extent-derived
+ *   uncertainty from the derived `street-centroids-<cc>.db` roll-up.
+ *
+ *   Query-side normalization is THE shared normalizer (`street-normalize.ts`), selected per the shard's
+ *   `streetLocale`, so build-side and probe-side keys agree by construction. The commune scope folds
+ *   through `normalizeLocalityForKey` + `stripArrondissement` (BAN names Paris/Lyon/Marseille per
+ *   arrondissement; a query names the base commune).
+ *
+ *   Scope order is most-selective first: `postcode`, then the base commune. Each scope WEIGHTED-
+ *   aggregates (by `point_count`) across the matched rows in SQL, so a commune-scope probe returns the
+ *   street's grand centroid over every postcode/arrondissement it spans — one row, one hit. Matching is
+ *   exact-after-normalization only (no fuzzy street matching in this tier).
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import type { StreetCentroidHit, StreetCentroidLookup } from "@mailwoman/resolver"
+
+import { hasTable } from "./sqlite-utils.ts"
+import {
+	normalizeLocalityForKey,
+	normalizeStreetForKeyLocale,
+	type StreetLocale,
+	stripArrondissement,
+} from "./street-normalize.ts"
+
+/** The weighted-centroid + extent + provenance an aggregate probe projects. `lat` is null when nothing matched. */
+interface AggRow {
+	lat: number | null
+	lon: number | null
+	min_lat: number | null
+	max_lat: number | null
+	min_lon: number | null
+	max_lon: number | null
+	source: string | null
+	release: string | null
+}
+
+/** Weighted-centroid aggregate over a WHERE-filtered set. `SUM(coord*n)/SUM(n)` reconstructs the grand centroid. */
+const AGG_SELECT =
+	"SUM(lat * point_count) / SUM(point_count) AS lat, " +
+	"SUM(lon * point_count) / SUM(point_count) AS lon, " +
+	"MIN(min_lat) AS min_lat, MAX(max_lat) AS max_lat, MIN(min_lon) AS min_lon, MAX(max_lon) AS max_lon, " +
+	"MAX(source) AS source, MAX(release) AS release"
+
+/** Half the bbox diagonal, in METERS — an honest coarse radius for a street centroid. */
+function extentRadiusM(minLat: number, maxLat: number, minLon: number, maxLon: number): number {
+	const R = 6_371_000
+	const toRad = (d: number): number => (d * Math.PI) / 180
+	const dLat = toRad(maxLat - minLat)
+	const dLon = toRad(maxLon - minLon)
+	const midLat = toRad((minLat + maxLat) / 2)
+	const a = Math.sin(dLat / 2) ** 2 + Math.cos(midLat) ** 2 * Math.sin(dLon / 2) ** 2
+	const diag = 2 * R * Math.asin(Math.min(1, Math.sqrt(a)))
+
+	return Math.round(diag / 2)
+}
+
+export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
+	readonly #db: DatabaseSync
+	readonly #locale: StreetLocale
+	readonly #byPostcode: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #byLocality: ReturnType<DatabaseSync["prepare"]> | undefined
+
+	/**
+	 * @param dbPath Shard path.
+	 * @param opts.streetLocale The street-normalization locale this shard was BUILT with — must match, or every key
+	 *   misses. Defaults to `"fr"` (BAN is the French national register; the tier is FR-only today).
+	 */
+	constructor(dbPath: string, opts: { streetLocale?: StreetLocale } = {}) {
+		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+		this.#locale = opts.streetLocale ?? "fr"
+
+		// Degrade gracefully on an empty/tableless shard (interrupted build, stray 0-byte file): with no
+		// `street_centroid` table this lookup is a no-op miss, not a crash (mirrors the address-point reader).
+		if (hasTable(this.#db, "street_centroid")) {
+			this.#byPostcode = this.#db.prepare(
+				`SELECT ${AGG_SELECT} FROM street_centroid WHERE postcode = ? AND street_norm = ?`
+			)
+			this.#byLocality = this.#db.prepare(
+				`SELECT ${AGG_SELECT} FROM street_centroid WHERE locality_base = ? AND street_norm = ?`
+			)
+		}
+	}
+
+	find(query: { street: string; postcode?: string; locality?: string }): StreetCentroidHit | null {
+		if (!this.#byPostcode || !this.#byLocality) return null
+		const streetNorm = normalizeStreetForKeyLocale(query.street, this.#locale)
+
+		if (!streetNorm) return null
+
+		let row: AggRow | undefined
+
+		if (query.postcode?.trim()) {
+			row = this.#byPostcode.get(query.postcode.trim(), streetNorm) as AggRow | undefined
+		}
+
+		if ((!row || row.lat == null) && query.locality?.trim()) {
+			const base = stripArrondissement(normalizeLocalityForKey(query.locality))
+			row = this.#byLocality.get(base, streetNorm) as AggRow | undefined
+		}
+
+		if (!row || row.lat == null || row.lon == null) return null
+
+		return {
+			lat: row.lat,
+			lon: row.lon,
+			uncertaintyM: extentRadiusM(row.min_lat!, row.max_lat!, row.min_lon!, row.max_lon!),
+			source: row.source ?? "",
+			release: row.release ?? "",
+		}
+	}
+
+	close(): void {
+		this.#db.close()
+	}
+}