@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/address/point/index.ts

@@ -1,328 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
- *   postcode (preferred), locality, or — for extracts whose points carry no scope tag (OSM, #247) —
- *   the resolved locality's BBOX. Query-side normalization is THE shared normalizer
- *   (`street-normalize.ts`), selected per the extract's `streetLocale` so build-side and probe-side
- *   stay identical by construction (US delegates to the USPS pipeline; FR/DE/NL use the locale rules).
- *
- *   Matching is exact-after-normalization only — no fuzzy street matching in this tier (measure how
- *   far exact gets first; fuzz is a later, separate decision). Scope order is most-selective first:
- *   postcode, then locality, then the bbox fall-through (only when a bbox is supplied AND the prior
- *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
- */
-
-import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver"
-import { DatabaseClient } from "@mailwoman/sqlite/client"
-
-import type { AddressPointDatabase, AddressPointTable } from "#address/point/schema"
-import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
-import {
-	normalizeHouseNumberForKey,
-	normalizeLocalityForKey,
-	normalizeLocalityForKeyLocale,
-	type NameKey,
-	type StreetKey,
-	streetKeyVariants,
-	streetLocaleForSurface,
-	stripArrondissement,
-	type StreetLocale,
-} from "#street/normalize"
-
-/**
- * The columns this lookup projects — a typed slice of the SHARED {@link AddressPointTable}, so a column rename in
- * `build-address-point-extract.ts` (the writer) is a compile error here (the reader).
- */
-type AddressPointRow = Pick<AddressPointTable, "lat" | "lon" | "source" | "release" | "locality_norm" | "postcode">
-
-/**
- * The 4 columns the reader SELECTs, in the schema's order — referenced by the prepared SELECTs so the projected
- * `AddressPointRow` stays in lockstep with the shared schema.
- */
-const SELECT_COLS = "lat, lon, source, release, locality_norm, postcode"
-
-export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressPointDatabase>
-	implements AddressPointLookup, Disposable
-{
-	readonly #db: DatabaseClient<DB>
-	readonly #locale: StreetLocale
-	readonly #localityKeys: "full" | "abbreviated"
-	readonly #byPostcode: PreparedGet<[postcode: string, street: StreetKey, number: string], AddressPointRow> | undefined
-	readonly #byPostcodeLocality:
-		| PreparedGet<[postcode: string, locality: NameKey, street: StreetKey, number: string], AddressPointRow>
-		| undefined
-	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey, number: string], AddressPointRow> | undefined
-	/**
-	 * The scope key matched by its TAIL — a `zh` query that names the 鄉鎮市區 without its 縣市. Narrowed by the (street,
-	 * number) index first, so the LIKE walks the handful of rows that share the pair.
-	 */
-	readonly #byLocalityTail:
-		| PreparedGet<[street: StreetKey, number: string, tailPattern: string], AddressPointRow>
-		| undefined
-	readonly #byBbox:
-		| PreparedGet<
-				[street: StreetKey, number: string, minLat: number, maxLat: number, minLon: number, maxLon: number],
-				AddressPointRow
-		  >
-		| undefined
-
-	/**
-	 * @param dbPath Extract path.
-	 * @param opts.streetLocale The street-normalization locale this extract was BUILT with — must match, or every key
-	 *   misses. Defaults to `"us"` (the situs tier), so existing callers are unchanged.
-	 * @param opts.localityKeys Whether the extract's `locality_norm` is a FULL place name a query can be held to. The BAN
-	 *   and OSM extracts write the commune or `addr:city` in full; the US situs extract writes the NAD city field, which
-	 *   several counties abbreviate (`addi` for Addison on 5,174 Texas rows, 327,264 Texas rows at four characters or
-	 *   fewer) or give as the parent town (`easton` for North Easton). A key like that can steer WHICH row answers but
-	 *   cannot refuse one, so it never contradicts. Defaults from the street locale: `"us"` is abbreviated, the rest
-	 *   full.
-	 */
-	constructor(dbPath: string, opts: { streetLocale?: StreetLocale; localityKeys?: "full" | "abbreviated" } = {}) {
-		this.#db = new DatabaseClient<DB>(dbPath, { readOnly: true })
-		this.#locale = opts.streetLocale ?? "us"
-		this.#localityKeys = opts.localityKeys ?? (this.#locale === "us" ? "abbreviated" : "full")
-
-		// Degrade gracefully on an empty/tableless extract (interrupted build, stray 0-byte file): with no
-		// `address_point` table this lookup is a no-op miss, not a crash that loses the whole state (#568).
-		if (hasTable(this.#db, "address_point")) {
-			this.#byPostcode = prepareGet(
-				this.#db,
-				`SELECT ${SELECT_COLS} FROM address_point
-				 WHERE postcode = ? AND street_norm = ? AND number = ? LIMIT 1`
-			)
-
-			this.#byPostcodeLocality = prepareGet(
-				this.#db,
-				`SELECT ${SELECT_COLS} FROM address_point
-				 WHERE postcode = ? AND locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
-			)
-
-			this.#byLocality = prepareGet(
-				this.#db,
-				`SELECT ${SELECT_COLS} FROM address_point
-				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
-			)
-
-			this.#byBbox = prepareGet(
-				this.#db,
-				`SELECT ${SELECT_COLS} FROM address_point
-				 WHERE street_norm = ? AND number = ? AND lat BETWEEN ? AND ? AND lon BETWEEN ? AND ? LIMIT 1`
-			)
-
-			this.#byLocalityTail = prepareGet(
-				this.#db,
-				`SELECT ${SELECT_COLS} FROM address_point
-				 WHERE street_norm = ? AND number = ? AND locality_norm LIKE ? LIMIT 1`
-			)
-		}
-	}
-
-	find(query: {
-		street: string
-		number: string
-		postcode?: string
-		locality?: string
-		region?: string
-		subregion?: string
-		bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
-	}): AddressPointHit | null {
-		if (!this.#byPostcode || !this.#byLocality || !this.#byBbox) return null
-		const number = normalizeHouseNumberForKey(query.number, this.#locale)
-
-		if (!number) return null
-
-		// A `zh` extract scopes a point by 縣市 + 鄉鎮市區, the pair the parse tags `region` + `subregion`; the Taiwanese
-		// register carries no postcode and the parse no `locality`. The pair becomes the locality key here, on the
-		// reader that was built with the same fold, and a Latin extract never sees the two fields. A line that names
-		// only the 鄉鎮市區 (`中和區中興街281號`, 14.7% of the TW board) matches the stored pair by its tail instead.
-		const scoped =
-			this.#locale === "zh" && !query.locality && query.subregion
-				? query.region
-					? { ...query, locality: `${query.region}${query.subregion}` }
-					: { ...query, localityTail: normalizeLocalityForKeyLocale(query.subregion, "zh") }
-				: query
-
-		// Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
-		// collapse and the saint↔st register swap — each variant runs the FULL number ladder below, and
-		// the first variant to answer wins, so an attested literal key is never second-guessed.
-		let row: AddressPointRow | undefined
-
-		for (const streetNorm of streetKeyVariants(query.street, streetLocaleForSurface(query.street, this.#locale))) {
-			row = this.#findForKey(streetNorm, number, scoped)
-
-			if (row) break
-		}
-
-		if (!row) return null
-
-		return {
-			lat: row.lat,
-			lon: row.lon,
-			source: row.source,
-			release: row.release,
-			...(row.locality_norm ? { localityNorm: row.locality_norm } : {}),
-			...(row.postcode ? { postcode: row.postcode } : {}),
-		}
-	}
-
-	/**
-	 * The full number ladder for ONE normalized street key: exact, then the range low-end, then letter-suffix spacing
-	 * with the base-number fall — see each rung's note in place.
-	 */
-	#findForKey(
-		streetNorm: StreetKey,
-		number: string,
-		query: {
-			street: string
-			number: string
-			postcode?: string
-			locality?: string
-			localityTail?: NameKey
-			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
-		}
-	) {
-		let row = this.#probe(streetNorm, number, query)
-
-		// Range-surface fallback: every register this reader serves stores ONE number per point
-		// (G-NAF `NUMBER_FIRST`, BAN, OA, OSM `addr:housenumber`), but the attested surface is often
-		// a range — "385-387 Esplanade" keys `385`. Null-only: an exact range key that matched above
-		// (some OSM points DO carry "385-387" verbatim) is never second-guessed.
-		if (!row) {
-			const low = /^(\d+[a-z]?)-\d+[a-z]?$/.exec(number)?.[1]
-
-			if (low) {
-				row = this.#probe(streetNorm, low, query)
-			}
-		}
-
-		// Letter-suffix spacing fallback: the registers disagree on the joint — BAN stores "3 a"
-		// (space-separated), G-NAF and most OA sources store "3a" — and the parsed surface can arrive
-		// either way. On a miss, retry the OTHER spacing; on a double miss, the BASE number (the
-		// register attests no 3A but does attest 3 — the adjacent-parcel approximation, priced the
-		// same as the range fallback's low end). Null-only throughout, and only for the
-		// digits+single-letter shape (never touches "12 1/2" or unit-bearing forms).
-		if (!row) {
-			const joined = /^(\d+)\s+([a-z])$/.exec(number)
-			const spaced = /^(\d+)([a-z])$/.exec(number)
-
-			if (joined) {
-				row = this.#probe(streetNorm, `${joined[1]}${joined[2]}`, query) ?? this.#probe(streetNorm, joined[1]!, query)
-			} else if (spaced) {
-				row = this.#probe(streetNorm, `${spaced[1]} ${spaced[2]}`, query) ?? this.#probe(streetNorm, spaced[1]!, query)
-			}
-		}
-
-		// Sub-number fallback for the Taiwanese register: `14之12` is building 12 off number 14, `30附40` an attached
-		// number, stored as number `14` / `30` with the rest in `unit`. A query that kept the pair on the number span
-		// falls to the base number — the same adjacent-parcel approximation the letter-suffix rung makes, priced the
-		// same: on the 2,000-row served read the rows answered this way sit a median 256 m and at most 1.0 km from the
-		// building.
-		if (!row && this.#locale === "zh") {
-			const base = /^(\d+)(?:[之附]\d+)+$/u.exec(number)?.[1]
-
-			if (base) {
-				row = this.#probe(streetNorm, base, query)
-			}
-		}
-
-		return row
-	}
-
-	/**
-	 * The scope ladder for one (street, number) key: postcode, then locality, then the bbox fall-through — each rung only
-	 * when the prior missed.
-	 */
-	#probe(
-		streetNorm: StreetKey,
-		number: string,
-		query: {
-			postcode?: string
-			locality?: string
-			localityTail?: NameKey
-			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
-		}
-	): AddressPointRow | undefined {
-		let row: AddressPointRow | undefined
-
-		if (query.postcode) {
-			const postcode = query.postcode.trim()
-			const localityKey = query.locality ? this.#localityKey(query.locality) : undefined
-
-			// A postcode can span several places — DE 04509 covers Schönwölkau and Werlitzsch, both with a Teichstraße 3 —
-			// so when the query names a locality the row whose own locality agrees is asked for FIRST. Only when no such
-			// row exists does the postcode-only row answer, and then only if its locality does not name a different place
-			// (see `#scopeContradicts` for what "different" tolerates): a query naming a third village under the postcode
-			// falls through to the locality rung rather than answering the wrong rooftop.
-			const agreeing = localityKey ? this.#byPostcodeLocality!(postcode, localityKey, streetNorm, number) : undefined
-			const candidate = agreeing ?? this.#byPostcode!(postcode, streetNorm, number)
-
-			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
-		}
-
-		if (!row && query.locality) {
-			// FR extracts key arrondissement communes at the base city (both-sides fold, see the BAN
-			// builder + stripArrondissement) — fold the probe too so "Paris 13e Arrondissement" and
-			// "Paris" both hit. No-op for "us" extracts and every non-arrondissement commune.
-			row = this.#byLocality!(this.#localityKey(query.locality), streetNorm, number)
-		}
-
-		if (!row && query.localityTail && this.#byLocalityTail) {
-			// A Han key carries no `%` or `_`, so the tail is a literal suffix pattern.
-			row = this.#byLocalityTail(streetNorm, number, `%${query.localityTail}`)
-		}
-
-		// Bbox fall-through (#247): the point carries no postcode/locality of its own, but its coordinate falls
-		// inside the resolved locality's box. Only reached when the scoped probes missed AND a bbox was supplied.
-		if (!row && query.bbox) {
-			const b = query.bbox
-			const candidate = this.#byBbox!(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon)
-
-			// A register row that carries its own scope and was NOT found by the scoped rungs is a different address that
-			// happens to share the street and number inside the box: `10 rue de la République, 75008 Paris` reached
-			// Servon's `10 rue de la République` (postcode 77170) 26 km away this way, at rooftop tier and 1 m uncertainty.
-			// The rung exists for points with no scope of their own; a point whose scope disagrees with the query is a miss.
-			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
-		}
-
-		return row
-	}
-
-	/**
-	 * The query's locality folded the way the extract's builder folded its `locality_norm`. FR extracts key
-	 * arrondissement communes at the base city (both-sides fold, see the BAN builder + stripArrondissement), so "Paris
-	 * 13e Arrondissement" and "Paris" both hit; a no-op for every other locale.
-	 */
-	#localityKey(locality: string): NameKey {
-		if (this.#locale === "fr") return stripArrondissement(normalizeLocalityForKey(locality))
-
-		return normalizeLocalityForKeyLocale(locality, this.#locale)
-	}
-
-	/**
-	 * Whether a row's OWN postcode or locality names a different place than the query did. Absent scope on the row is not
-	 * a contradiction — it is the case the bbox rung was built for — and a rung that matched ON a field cannot contradict
-	 * it, so at the postcode rung only the locality can disagree and at the bbox rung either can.
-	 *
-	 * The locality is consulted only on an extract whose keys are full names (the constructor's `localityKeys`). Under
-	 * exact comparison against the US extract's abbreviated keys, the postcode rung refused `4900 Airport Pkwy, Addison
-	 * TX 75001`'s own rooftop row (`addi`) and `678 Depot St, North Easton, MA 02356`'s (`easton`), and both `pass` board
-	 * rows fell to interpolation 144–198 m away — invisible to a 1 km grade (#2155). `servon` against `paris` and
-	 * `werlitzsch` against `krensitz`, on the BAN and OSM extracts, are different places and still refuse.
-	 */
-	#scopeContradicts(row: AddressPointRow, query: { postcode?: string; locality?: string }): boolean {
-		if (query.postcode && row.postcode && row.postcode.trim() !== query.postcode.trim()) return true
-
-		if (this.#localityKeys === "full" && query.locality && row.locality_norm) {
-			return row.locality_norm !== this.#localityKey(query.locality)
-		}
-
-		return false
-	}
-
-	[Symbol.dispose](): void {
-		this.#db[Symbol.dispose]()
-	}
-}

package/lib/convention/index.ts

@@ -1,154 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
- *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
- *
- *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
- *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
- *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
- *   in `candidateStrategies`, first to return candidates wins.
- *
- *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
- *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
- *   name.
- *
- *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
- *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
- *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
- *   source).
- */
-
-import type { FindPlaceQuery, PlaceCandidate } from "#types"
-
-/**
- * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
- */
-export interface ScoringWeights {
-	pc: number
-	name: number
-	pop: number
-}
-
-/**
- * A geographically-scoped resolution profile. Namespaced sections grow per phase; #289 ships the dispatch + scoring
- * slice (`candidateStrategies` + `scoringWeights`). Later phases add `fieldMapping` (locale semantics for `locator[]`),
- * `tokenNormalization`, etc.
- */
-export interface Convention {
-	/**
-	 * Ordered strategy names the dispatcher runs; the first to return a non-null result wins.
-	 */
-	candidateStrategies?: string[]
-	/**
-	 * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and inherit the rest
-	 * from the layers below it (`resolveConvention` fills any gaps from WORLD_DEFAULT).
-	 */
-	scoringWeights?: Partial<ScoringWeights>
-}
-
-/**
- * A fully-resolved convention: every field present, weights complete. What `resolveConvention` returns and what
- * strategies consume.
- */
-export interface ResolvedConvention {
-	candidateStrategies: string[]
-	scoringWeights: ScoringWeights
-}
-
-/**
- * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first behavior exactly: try
- * `postcode_area_resolution`, else fall back to fuzzy name match; soft-score weights 0.6 / 0.3 / 0.1. Changing these
- * changes EU behavior — don't, without a byte-stability run.
- */
-export const WORLD_DEFAULT: ResolvedConvention = {
-	candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
-	scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
-}
-
-/**
- * The strategy names the backend registers. The single source of truth shared by the dispatch registry and the
- * build-time validator, so an authored convention that names a non-existent strategy is caught at build (loud) rather
- * than silently skipped at runtime.
- */
-export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
-
-/**
- * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the extract
- * auto-detect all agree.
- */
-export const ADDRESS_CONVENTION_TABLE = "address_convention"
-
-/**
- * A named resolution primitive. Returns `null` to abstain (condition unmet / no data) → the dispatcher tries the next
- * strategy; returns an array (possibly empty) to claim the result.
- */
-export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>
-
-/**
- * Look up a convention record by WOF polygon id. Returns `undefined` when the polygon has no override.
- */
-export interface ConventionSource {
-	get(wofID: number): Convention | undefined
-}
-
-/**
- * In-memory convention source seeded from a `{ wofID: Convention }` map. Empty for the EU locales (they ride
- * `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed source built from source, same
- * distributable-asset discipline as `postcode-locality-intl.db`.
- */
-export class SeedConventionSource implements ConventionSource {
-	readonly #rows: Map<number, Convention>
-
-	constructor(rows: Record<number, Convention> = {}) {
-		this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]))
-	}
-
-	get(wofID: number): Convention | undefined {
-		return this.#rows.get(wofID)
-	}
-}
-
-/**
- * Deep-merge convention layers, later (more-specific) layers winning per field. `candidateStrategies` is replaced
- * wholesale — a convention names its full ordered list, it does not append. `scoringWeights` is merged key-by-key so a
- * locality can nudge one weight without restating the others.
- */
-export function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention {
-	const out: Convention = {
-		candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
-		scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
-	}
-
-	for (const o of overrides) {
-		if (!o) continue
-
-		if (o.candidateStrategies !== undefined) {
-			out.candidateStrategies = [...o.candidateStrategies]
-		}
-
-		if (o.scoringWeights !== undefined) {
-			out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights }
-		}
-	}
-
-	return out
-}
-
-/**
- * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL → MOST-SPECIFIC (country,
- * region, …, locality). Starts from `WORLD_DEFAULT` so every field is defined regardless of which (if any) ancestors
- * carry an override.
- */
-export function resolveConvention(source: ConventionSource, ancestorIDs: readonly number[]): ResolvedConvention {
-	const layers = ancestorIDs.map((id) => source.get(id))
-	const merged = mergeConventions(WORLD_DEFAULT, ...layers)
-
-	return {
-		candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
-		// Fill any weight gaps from the base so strategies always see a complete set.
-		scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
-	}
-}