@mailwoman/resolver-wof-sqlite 8.0.0 → 8.2.0

package/street-name-lookup.ts

@@ -39,9 +39,13 @@ function hasColumn(db: DatabaseSync, table: string, column: string): boolean {
 }
 
 export interface SQLiteStreetNameLookupOpts {
-	/** ISO-2 (upper-case) countries this index answers for. Default `["FR"]` (the BAN street-centroids instance). */
+	/**
+	 * ISO-2 (upper-case) countries this index answers for. Default `["FR"]` (the BAN street-centroids instance).
+	 */
 	countries?: Iterable<string>
-	/** Table name. Default `street_centroid`. */
+	/**
+	 * Table name. Default `street_centroid`.
+	 */
 	table?: string
 }
 
@@ -68,9 +72,11 @@ export class SQLiteStreetNameLookup implements StreetLocalityEvidence {
 			// `name_key` MUST match `foldStreetSurface` here (the fold-parity contract).
 			const keyCol = hasColumn(this.#db, table, "name_key") ? "name_key" : "street_norm"
 			this.#byName = this.#db.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? LIMIT 1`)
+
 			this.#byNameLocality = this.#db.prepare(
 				`SELECT 1 FROM ${table} WHERE ${keyCol} = ? AND locality_base = ? LIMIT 1`
 			)
+
 			this.#byNamePostcode = this.#db.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? AND postcode = ? LIMIT 1`)
 		}
 	}
@@ -83,18 +89,24 @@ export class SQLiteStreetNameLookup implements StreetLocalityEvidence {
 
 		// Scoped lookups tighten precision when the hypothesis carries a locality/postcode; a scoped MISS falls back to the
 		// unscoped probe (index incompleteness in the scope column is not evidence of absence — positive-evidence rule).
-		if (scope?.locality && this.#byNameLocality) {
-			if (this.#byNameLocality.get(norm, foldStreetSurface(scope.locality)) !== undefined) return true
+		if (
+			scope?.locality &&
+			this.#byNameLocality &&
+			this.#byNameLocality.get(norm, foldStreetSurface(scope.locality)) !== undefined
+		) {
+			return true
 		}
 
-		if (scope?.postcode && this.#byNamePostcode) {
-			if (this.#byNamePostcode.get(norm, scope.postcode) !== undefined) return true
+		if (scope?.postcode && this.#byNamePostcode && this.#byNamePostcode.get(norm, scope.postcode) !== undefined) {
+			return true
 		}
 
 		return this.#byName.get(norm) !== undefined
 	}
 
-	/** Close the underlying handle. */
+	/**
+	 * Close the underlying handle.
+	 */
 	close(): void {
 		this.#db.close()
 	}

package/street-normalize.ts

@@ -24,6 +24,12 @@
 
 import { AbbreviationToDirectional, US_STREET_SUFFIX_LOOKUP } from "@mailwoman/codex/us"
 
+/**
+ * Token count a street must exceed before its trailing pair is merged. At or below it the pair IS the whole street
+ * name, and merging would leave nothing to match on.
+ */
+const MIN_TOKENS_FOR_TAIL_MERGE = 3
+
 /**
  * Spelled ordinal street names → their digit-ordinal form ("tenth" → "10th"), applied ONLY when a street-type suffix
  * follows (#723 admin-tail) — so the ordinal cross-streets common in grid cities ("Tenth Street", "Fifth Avenue") match
@@ -63,14 +69,16 @@ const SPELLED_ORDINAL_TO_DIGIT = new Map<string, string>([
 	["hundredth", "100th"],
 ])
 
-/** Lowercase + diacritic-fold + punctuation strip + whitespace collapse. */
+/**
+ * Lowercase + diacritic-fold + punctuation strip + whitespace collapse.
+ */
 function fold(input: string): string {
 	return input
 		.normalize("NFKD")
-		.replace(/[̀-ͯ]/g, "")
+		.replaceAll(/[̀-ͯ]/g, "")
 		.toLowerCase()
-		.replace(/[.,'’]/g, "")
-		.replace(/\s+/g, " ")
+		.replaceAll(/[.,'’]/g, "")
+		.replaceAll(/\s+/g, " ")
 		.trim()
 }
 
@@ -81,7 +89,7 @@ function fold(input: string): string {
 export function normalizeStreetForKey(street: string): string {
 	const tokens = fold(street).split(" ")
 
-	if (tokens.length === 0) return ""
+	if (!tokens.length) return ""
 
 	// Spelled-ordinal street names → digit form when a street suffix follows ("Tenth Street" →
 	// "10th street", #723). Gated on the next token being a suffix so ordinal-WORD names are untouched.
@@ -99,6 +107,7 @@ export function normalizeStreetForKey(street: string): string {
 	// ("southeast"), and also merge an already-written two-token pair ("South East …").
 	const edgeDirectional = (raw: string) =>
 		AbbreviationToDirectional.get(raw.toUpperCase())?.toLowerCase().replace(" ", "")
+
 	const mergePair = (a?: string, b?: string) =>
 		a && b && /^(north|south)$/.test(a) && /^(east|west)$/.test(b) ? a + b : undefined
 
@@ -107,20 +116,21 @@ export function normalizeStreetForKey(street: string): string {
 	if (leadPair && tokens.length > 2) {
 		tokens.splice(0, 2, leadPair)
 	}
+
 	const first = edgeDirectional(tokens[0]!)
 
 	if (first && tokens.length > 1) {
 		tokens[0] = first
 	}
 
-	const tailPair = mergePair(tokens[tokens.length - 2], tokens[tokens.length - 1])
+	const tailPair = mergePair(tokens.at(-2), tokens.at(-1))
 
-	if (tailPair && tokens.length > 3) {
-		tokens.splice(tokens.length - 2, 2, tailPair)
+	if (tailPair && tokens.length > MIN_TOKENS_FOR_TAIL_MERGE) {
+		tokens.splice(-2, 2, tailPair)
 	}
 
 	if (tokens.length > 2) {
-		const last = edgeDirectional(tokens[tokens.length - 1]!)
+		const last = edgeDirectional(tokens.at(-1)!)
 
 		if (last) {
 			tokens[tokens.length - 1] = last
@@ -136,6 +146,7 @@ export function normalizeStreetForKey(street: string): string {
 
 		if (canonical) {
 			tokens[at] = canonical.toLowerCase()
+
 			break
 		}
 	}
@@ -196,9 +207,9 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 	// hyphen ("Champs-Élysées", "St-Honoré") or a space — both sides fold identically, so this is pure
 	// robustness. It also splits a hyphenated abbreviation ("St-Honoré" → "st honore") into tokens the
 	// per-locale type/Saint map can see.
-	const tokens = fold(street).replace(/ß/g, "ss").replace(/-/g, " ").split(/\s+/).filter(Boolean)
+	const tokens = fold(street).replaceAll("ß", "ss").replaceAll("-", " ").split(/\s+/).filter(Boolean)
 
-	if (tokens.length === 0) return ""
+	if (!tokens.length) return ""
 
 	switch (locale) {
 		case "fr":
@@ -229,7 +240,9 @@ export function normalizeStreetForKeyLocale(street: string, locale: StreetLocale
 	return tokens.join(" ")
 }
 
-/** Normalize a locality name for address-point keying (fold only — no street semantics). */
+/**
+ * Normalize a locality name for address-point keying (fold only — no street semantics).
+ */
 export function normalizeLocalityForKey(locality: string): string {
 	return fold(locality)
 }
@@ -268,7 +281,9 @@ export function stripLocalityQualifier(locality: string): string {
 
 	if (s.includes("/")) {
 		s = s.split("/")[0]!.trim()
-	} // "Kraubath/Mur", "St.Kanzian/Klopeiner See"
+	}
+
+	// "Kraubath/Mur", "St.Kanzian/Klopeiner See"
 	s = s.replace(/\s+[a-zà-ÿ]\.\s*\S.*$/iu, "") // abbreviated " b.Graz" / " o.Bleiburg" / " a.d. …"
 	s = s.replace(/\s+(im|an der|ob|bei|in der|unter|vor)\s+\S.*$/iu, "") // " im Simmental", " bei Graz"
 	s = s.replace(/\s+(S|N|E|W|V|Ø|Sø|Fyn|Thy|Sjælland|Jylland|[A-ZÅÄÖ]{2})$/u, "") // " S", " VD", " Thy"

package/street-segment-schema.ts

@@ -23,34 +23,79 @@ import type { Kysely } from "kysely"
  * `odd`/`even`/`mixed`.
  */
 export interface StreetSegmentTable {
-	/** Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key. */
+	/**
+	 * Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key.
+	 */
 	street_norm: string
-	/** `L` or `R` — the TIGER side the address range sits on. */
+	/**
+	 * `L` or `R` — the TIGER side the address range sits on.
+	 */
 	side: string
 	from_hn: number
 	to_hn: number
-	/** Sorted lower bound of `(from_hn, to_hn)` — the probe filters `min_hn <= n <= max_hn`. */
+	/**
+	 * Sorted lower bound of `(from_hn, to_hn)` — the probe filters `min_hn <= n <= max_hn`.
+	 */
 	min_hn: number
-	/** Sorted upper bound of `(from_hn, to_hn)`. */
+	/**
+	 * Sorted upper bound of `(from_hn, to_hn)`.
+	 */
 	max_hn: number
-	/** `odd` | `even` | `mixed` — the house-number parity along the range. */
+	/**
+	 * `odd` | `even` | `mixed` — the house-number parity along the range.
+	 */
 	parity: string
 	postcode: string | null
-	/** 5-digit state+county FIPS the edge came from. */
+	/**
+	 * 5-digit state+county FIPS the edge came from.
+	 */
 	county_fips: string
-	/** The street as it appeared in TIGER (kept for display / debugging). */
+	/**
+	 * The street as it appeared in TIGER (kept for display / debugging).
+	 */
 	street_raw: string
-	/** GeoJSON LineString text (no SpatiaLite — read back with `JSON.parse`). */
+	/**
+	 * GeoJSON LineString text (no SpatiaLite — read back with `JSON.parse`).
+	 */
 	geometry: string
-	/** Provenance: the dataset this edge came from (e.g. `tiger:edges`). */
+	/**
+	 * Provenance: the dataset this edge came from (e.g. `tiger:edges`).
+	 */
 	source: string
-	/** The pinned TIGER release the edge was ingested from. */
+	/**
+	 * The pinned TIGER release the edge was ingested from.
+	 */
 	release: string
 }
 
-/** The street-segment database schema for `new DatabaseClient<StreetSegmentDatabase>(...)`. */
+/**
+ * The shard's single-row calibration metadata (#374 doctrine, 2026-07-26): the conformal radius multiplier is a
+ * property of the CALIBRATION SET the artifact was built against — so it ships IN the artifact (the pair-index δ
+ * precedent, `neural/pair-index-resolver.ts`), not in caller code. Written once by the builder; read at open time by
+ * {@link StreetInterpolator}. Shards built before this table exists simply lack it — the reader degrades to `undefined`
+ * and callers fall back to the in-code per-region table (never patch shipped DBs — rebuild).
+ */
+export interface InterpCalibrationRow {
+	/**
+	 * Conformal multiplier for the raw half-segment `uncertainty_m` radius (#374/#584) — ×Q̂ for a ~90% bound.
+	 */
+	radius_multiplier: number
+	/**
+	 * Provenance of the multiplier (e.g. `split-conformal:2026-06-14`).
+	 */
+	method: string
+	/**
+	 * The calibration-table key the multiplier was selected by (a USPS region code, or `default` for unmeasured).
+	 */
+	region: string
+}
+
+/**
+ * The street-segment database schema for `new DatabaseClient<StreetSegmentDatabase>(...)`.
+ */
 export interface StreetSegmentDatabase {
 	street_segment: StreetSegmentTable
+	interp_calibration: InterpCalibrationRow
 }
 
 /**
@@ -73,7 +118,9 @@ export const STREET_SEGMENT_COLUMNS = [
 	"release",
 ] as const
 
-/** Create the `street_segment` table — called before the streaming bulk load. */
+/**
+ * Create the `street_segment` table — called before the streaming bulk load.
+ */
 export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>): Promise<void> {
 	await db.schema
 		.createTable("street_segment")
@@ -93,12 +140,35 @@ export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>
 		.execute()
 }
 
-/** Create the two probe indexes the reader relies on (postcode-scope, street-scope). */
+/**
+ * Create + populate the single-row `interp_calibration` metadata table (see {@link InterpCalibrationRow}) — called once
+ * by the shard builder, after the value is selected from the calibration source of record. Build-time only (async
+ * Kysely is fine here); the READ side is the raw sync probe in {@link StreetInterpolator}'s constructor, per the
+ * sync-by-interface doctrine.
+ */
+export async function writeInterpCalibration(
+	db: Kysely<StreetSegmentDatabase>,
+	row: InterpCalibrationRow
+): Promise<void> {
+	await db.schema
+		.createTable("interp_calibration")
+		.addColumn("radius_multiplier", "real", (c) => c.notNull())
+		.addColumn("method", "text", (c) => c.notNull())
+		.addColumn("region", "text", (c) => c.notNull())
+		.execute()
+
+	await db.insertInto("interp_calibration").values(row).execute()
+}
+
+/**
+ * Create the two probe indexes the reader relies on (postcode-scope, street-scope).
+ */
 export async function createStreetSegmentIndexes(db: Kysely<StreetSegmentDatabase>): Promise<void> {
 	await db.schema
 		.createIndex("idx_seg_postcode")
 		.on("street_segment")
 		.columns(["postcode", "street_norm", "min_hn"])
 		.execute()
+
 	await db.schema.createIndex("idx_seg_street").on("street_segment").columns(["street_norm", "min_hn"]).execute()
 }

package/types.ts

@@ -49,7 +49,9 @@ export interface PlaceCandidate {
 	id: number
 	name: string
 	placetype: WOFPlacetype
-	/** ISO 3166-1 alpha-2 country code. */
+	/**
+	 * ISO 3166-1 alpha-2 country code.
+	 */
 	country: string
 	lat: number
 	lon: number
@@ -125,9 +127,13 @@ export interface GeoBbox {
 export interface FindPlaceQuery {
 	text: string
 	placetype?: WOFPlacetype | WOFPlacetype[]
-	/** ISO 3166-1 alpha-2 — narrows to one country. */
+	/**
+	 * ISO 3166-1 alpha-2 — narrows to one country.
+	 */
 	country?: string
-	/** WOF place id — narrows to descendants of this place. */
+	/**
+	 * WOF place id — narrows to descendants of this place.
+	 */
 	parentID?: number
 	/**
 	 * Sibling postcode. When set on a `locality` query AND a `postcode_locality` table is present, triggers the
@@ -136,7 +142,9 @@ export interface FindPlaceQuery {
 	 * postcode_locality shard is present.
 	 */
 	postcode?: string
-	/** Proximity hint — candidates close to this point get a ranking boost. */
+	/**
+	 * Proximity hint — candidates close to this point get a ranking boost.
+	 */
 	near?: GeoPoint & { maxDistanceKm?: number }
 	/**
 	 * Ordered proximity-bias points (viewport center, user location, …), each optionally weighted (default 1.0, first
@@ -147,9 +155,13 @@ export interface FindPlaceQuery {
 	 * back-compat.
 	 */
 	bias?: Array<GeoPoint & { weight?: number }>
-	/** Bounding-box filter — only candidates whose bbox intersects this box are returned. */
+	/**
+	 * Bounding-box filter — only candidates whose bbox intersects this box are returned.
+	 */
 	bbox?: GeoBbox
-	/** Default 10. */
+	/**
+	 * Default 10.
+	 */
 	limit?: number
 }
 

package/unified-schema.ts

@@ -12,7 +12,7 @@
  *   `place_search` FTS5 + `place_bbox` R*Tree are built separately by `build-fts` (fts.ts).
  */
 
-import { DatabaseSync } from "node:sqlite"
+import type { DatabaseSync } from "node:sqlite"
 
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 
@@ -109,11 +109,13 @@ export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
  */
 export function populateAncestors(db: DatabaseSync): number {
 	db.exec("DELETE FROM ancestors")
+
 	const rows = db.prepare("SELECT id, parent_id, placetype FROM spr").all() as Array<{
 		id: number
 		parent_id: number
 		placetype: string
 	}>
+
 	const byID = new Map<number, { parent: number; placetype: string }>()
 
 	for (const r of rows) {
@@ -125,7 +127,9 @@ export function populateAncestors(db: DatabaseSync): number {
 	let count = 0
 
 	for (const r of rows) {
-		insert.run(r.id, r.id, r.placetype) // self
+		insert.run(r.id, r.id, r.placetype)
+
+		// self
 		count++
 		const seen = new Set<number>([r.id])
 		let cur = r.parent_id
@@ -135,11 +139,13 @@ export function populateAncestors(db: DatabaseSync): number {
 
 			if (!node) break
 			insert.run(r.id, cur, node.placetype)
+
 			count++
 			seen.add(cur)
 			cur = node.parent
 		}
 	}
+
 	db.exec("COMMIT")
 
 	return count
@@ -152,18 +158,21 @@ export async function createUnifiedIndexes(db: DatabaseSync): Promise<void> {
 	await kdb.schema.createIndex("spr_by_parent").ifNotExists().on("spr").column("parent_id").execute()
 	await kdb.schema.createIndex("names_by_id").ifNotExists().on("names").column("id").execute()
 	await kdb.schema.createIndex("names_by_name").ifNotExists().on("names").column("name").execute()
+
 	await kdb.schema
 		.createIndex("concordances_by_id")
 		.ifNotExists()
 		.on("concordances")
 		.columns(["id", "lastmodified"])
 		.execute()
+
 	await kdb.schema
 		.createIndex("concordances_by_other_id")
 		.ifNotExists()
 		.on("concordances")
 		.columns(["other_source", "other_id"])
 		.execute()
+
 	// ancestor_id is the hot column (parent-constraint queries `WHERE ancestor_id = ?`); id supports
 	// the reverse lookup.
 	await kdb.schema.createIndex("ancestors_by_ancestor").ifNotExists().on("ancestors").column("ancestor_id").execute()