@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{candidate → lib/candidate}/name-roles.ts

@@ -2,21 +2,23 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 3c of the candidate build — the `name_role` detectors and the cuts they are judged by.
+ * @file Pass 3c of the candidate build — the `name_role` detectors and the thresholds they are judged by.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import { isOfficialLanguage } from "@mailwoman/codex/country"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import { normalizeLocalityForKey } from "../street-normalize.ts"
-import { isOwnNameVariant } from "./own-name.ts"
-import type { PlaceAttrs } from "./place-attrs.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import { isOwnNameVariant } from "#candidate/own-name"
+import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { WOFDatabase } from "#schema"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Key-count cut for the gloss anomaly detector (#1730) — the sweep's own boundary: 4,000 places carried >= 50 keys, and
- * a legitimate famous place at that count (New York, 176 keys) is separated by the PROMINENCE gate, never by this
- * number alone.
+ * Key-count threshold for the gloss anomaly detector (#1730) — the sweep's own boundary: 4,000 places carried >= 50
+ * keys, and a legitimate famous place at that count (New York, 176 keys) is separated by the PROMINENCE check, never by
+ * this number alone.
  */
 export const GLOSS_KEY_THRESHOLD = 50
 
@@ -39,9 +41,9 @@ export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
 
 /**
  * Pass 3c — the #1730 name-role prototype: two independent detectors over the staged rows, WRITE-ONLY in this
- * generation (no ranking consumer; the rank penalty is its own D-rule-gated step with the `gloss_key` board as
- * tripwire). Both stamp `is_primary = 0` rows only — a place's canonical name and the `place_abbr` region abbreviations
- * are never a gloss or a variant.
+ * generation (no ranking consumer; the rank penalty is its own D-rule-conditional step with the `gloss_key` board as
+ * regression check). Both stamp `is_primary = 0` rows only — a place's canonical name and the `place_abbr` region
+ * abbreviations are never a gloss or a variant.
  *
  * - `gloss` is ANOMALY-based, and stamps only the certain core: key volume at/over the threshold + a non-admin placetype
  *
@@ -55,8 +57,8 @@ export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
  * any role.
  */
 export function stampNameRoles(ctx: {
-	src: DatabaseSync
-	out: DatabaseSync
+	src: DatabaseClient<WOFDatabase>
+	out: DatabaseClient<CandidateDatabase>
 	attrs: Map<number, PlaceAttrs>
 	keyCounts: Map<number, number>
 	glossThreshold: number
@@ -94,8 +96,7 @@ export function stampNameRoles(ctx: {
 	const insRoleKey = out.prepare("INSERT OR IGNORE INTO role_key VALUES (?, ?)")
 
 	// Zero abbr stamps from a skipped detector is a different fact from zero variants found.
-	const hasSourceNames =
-		src.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='names'").get() !== undefined
+	const hasSourceNames = tableExists(src, "names")
 
 	if (hasSourceNames) {
 		out.exec("BEGIN")

package/{candidate → lib/candidate}/own-name.ts

@@ -9,7 +9,7 @@
  *   — rather than a different name that merely shares the folded key?
  *
  *   The comparator is `levenshteinSimilarity`, NOT Jaro-Winkler: JW's common-prefix bonus scores
- *   the load-bearing NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
+ *   the required NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
  *   (`saint george s` vs `st georges` expanded, 0.914), so no JW threshold separates them.
  *   Measured on the #1882 census contests, edit similarity separates every case with margin:
  *

package/{candidate → lib/candidate}/place-attrs.ts

@@ -5,7 +5,7 @@
  * @file The per-place record every candidate-staging pass writes its rows from.
  *
  *   Pass 1 reduces each current `spr` row to one {@link PlaceAttrs}; every later pass (alias bags,
- *   region abbreviations, country display names, the currency backfill, the shard folds) discovers
+ *   region abbreviations, country display names, the currency backfill, the extract folds) discovers
  *   ADDITIONAL name keys for a place already in that map and stages a row against the same record.
  *   That is what keeps each candidate row denormalized without re-reading the source, and it is why
  *   a pass needs exactly four things to stage: the key it found, the place, the id the row hangs on,
@@ -38,7 +38,7 @@ export interface PlaceAttrs {
  * Stage one candidate row: a normalized name key, the place it belongs to, the source id the row hangs on, and whether
  * the key is that place's canonical name (`is_primary`).
  *
- * `sid` is passed separately rather than read off the place because a shard fold and the alias pass stage rows for ids
- * the admin `attrs` map never held.
+ * `sid` is passed separately rather than read off the place because a extract fold and the alias pass stage rows for
+ * ids the admin `attrs` map never held.
  */
 export type StageRow = (k: string, a: PlaceAttrs, sid: number, isPrimary: number) => void

package/{candidate-ancestors-schema.ts → lib/candidate-ancestors-schema.ts}

@@ -50,7 +50,7 @@
  *   "contained along the canonical hierarchy", never "not contained at all".
  *
  *   ABSENCE SEMANTICS (meaning-of-zero): a place with no `candidate_interval` row has no recorded
- *   ancestry in the source (shard-fed postcodes and localities, isolated places, cycle-skipped
+ *   ancestry in the source (extract-fed postcodes and localities, isolated places, cycle-skipped
  *   rows). Absence is UNVERIFIABLE, never a containment verdict.
  */
 
@@ -59,8 +59,8 @@ import { sql, type Kysely } from "kysely"
 // Type-only and circular on purpose (candidate-schema extends CandidateAncestorsDatabase): Kysely's
 // DB parameter is invariant, so the DDL functions must take the FULL database type their caller
 // holds. Erased at runtime.
-import type { CandidateDatabase } from "./candidate-schema.ts"
-import type { NameKey } from "./street-normalize.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { NameKey } from "#street/normalize"
 
 /**
  * The deepest chain the sidecar stores per place. WOF containment within the resolvable placetypes (country …
@@ -76,7 +76,7 @@ export const MAX_ANCESTOR_DEPTH = 8
 export const CANDIDATE_ANCESTOR_TABLE = "candidate_ancestor"
 
 /**
- * The interval-label table's name — the closure table's seal-time sibling; existence-gated the same way.
+ * The interval-label table's name — the closure table's seal-time sibling; existence-restricted the same way.
  */
 export const CANDIDATE_INTERVAL_TABLE = "candidate_interval"
 

package/{candidate-fts.ts → lib/candidate-fts.ts}

@@ -25,10 +25,10 @@
  *   fallback only needs to recover the name_key, then re-probes the B-tree for its rows).
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
 /**
- * Name of the FTS5 trigram virtual table this module owns. The reader gates its fuzzy fallback on it.
+ * Name of the FTS5 trigram virtual table this module owns. The reader conditions its fuzzy fallback on it.
  */
 export const CANDIDATE_FTS_TABLE = "candidate_fts"
 
@@ -36,7 +36,7 @@ export const CANDIDATE_FTS_TABLE = "candidate_fts"
  * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. Call after the candidate
  * B-tree is populated (build pipeline) or against an existing candidate DB (migration).
  */
-export function createCandidateFTS(db: DatabaseSync): void {
+export function createCandidateFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(`DROP TABLE IF EXISTS ${CANDIDATE_FTS_TABLE}`)
 	db.exec(`CREATE VIRTUAL TABLE ${CANDIDATE_FTS_TABLE} USING fts5(name_key, tokenize='trigram')`)
 

package/{candidate-importance.ts → lib/candidate-importance.ts}

@@ -27,7 +27,7 @@
  *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
  *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
  *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_GATE_KM}. Two artifacts describing the same settlement put its centroid in
+ *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
  *   almost the same place; two same-named towns in one country do not.
  *
  *   ## What lands in the column
@@ -41,11 +41,11 @@
  *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { normalizeLocalityForKey } from "./street-normalize.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
  * How far apart two artifacts may put the same place's centroid and still be read as the same place.
@@ -55,18 +55,18 @@ import { normalizeLocalityForKey } from "./street-normalize.ts"
  * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
  * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
  *
- * What sets the gate is where that mode ENDS, and the per-kilometre density says so plainly. It falls from 1,076
- * places/km over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of
- * 760–780 places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns
- * wearing one name in one country, and it does not decay with distance because there is no reason it should. 10 km is
- * the floor between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the
- * gate to 25 km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
+ * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
+ * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
+ * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
+ * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
+ * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
  *
  * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The gate is the definition of
- * "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
+ * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
  */
-export const IMPORTANCE_JOIN_GATE_KM = 10
+export const IMPORTANCE_JOIN_RADIUS_KM = 10
 
 /**
  * One scored place from the source: where it is, and what it scored.
@@ -111,17 +111,17 @@ export class ImportanceIndex {
 	readonly #groups: Map<string, ScoredPlace[]>
 	readonly stats: ImportanceIndexStats
 	/**
-	 * Places {@link find} matched inside the gate.
+	 * Places {@link find} matched inside the radius.
 	 */
 	matched = 0
 	/**
-	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the gate, so
-	 * it is a different place wearing the same name.
+	 * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+	 * so it is a different place wearing the same name.
 	 *
 	 * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-	 * apart and the join is being asked to guess; it does not mean the gate is too tight.
+	 * apart and the join is being asked to guess; it does not mean the radius is too tight.
 	 */
-	gated = 0
+	refused = 0
 
 	constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats) {
 		this.#groups = groups
@@ -130,7 +130,7 @@ export class ImportanceIndex {
 
 	/**
 	 * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-	 * null when there is no such place within {@link IMPORTANCE_JOIN_GATE_KM}.
+	 * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
 	 *
 	 * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
 	 * column already carries that fallback where it has one, and inventing a second one would make an absence
@@ -157,8 +157,8 @@ export class ImportanceIndex {
 			}
 		}
 
-		if (!best || bestKm > IMPORTANCE_JOIN_GATE_KM) {
-			this.gated++
+		if (!best || bestKm > IMPORTANCE_JOIN_RADIUS_KM) {
+			this.refused++
 
 			return null
 		}
@@ -182,47 +182,43 @@ export class ImportanceIndex {
  * 25 s.
  */
 export function loadImportanceIndex(databasePath: string): ImportanceIndex {
-	const db = new DatabaseSync(databasePath, { readOnly: true })
-
-	try {
-		const groups = new Map<string, ScoredPlace[]>()
-		let places = 0
-		let unkeyable = 0
-
-		for (const row of db
-			.prepare(
-				`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
-					s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
-				 FROM place_importance i JOIN spr s ON s.id = i.id
-				 WHERE s.is_current != 0 AND s.is_deprecated = 0`
-			)
-			.iterate()) {
-			const importance = Number(row.importance)
-
-			if (!Number.isFinite(importance)) continue
-			const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
-
-			if (!nameKey) {
-				unkeyable++
-
-				continue
-			}
+	using db = new DatabaseClient<CandidateDatabase>(databasePath, { readOnly: true })
 
-			const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
-			let group = groups.get(key)
+	const groups = new Map<string, ScoredPlace[]>()
+	let places = 0
+	let unkeyable = 0
 
-			if (!group) {
-				group = []
-				groups.set(key, group)
-			}
+	for (const row of db
+		.prepare(
+			`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
+				s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
+			 FROM place_importance i JOIN spr s ON s.id = i.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`
+		)
+		.iterate()) {
+		const importance = Number(row.importance)
 
-			group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+		if (!Number.isFinite(importance)) continue
+		const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
 
-			places++
+		if (!nameKey) {
+			unkeyable++
+
+			continue
 		}
 
-		return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
-	} finally {
-		db.close()
+		const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
+		let group = groups.get(key)
+
+		if (!group) {
+			group = []
+			groups.set(key, group)
+		}
+
+		group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+
+		places++
 	}
+
+	return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
 }