@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/{index.ts → lib/index.ts}

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 
-export type { FindPlaceQuery, GeoBbox, GeoPoint, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
+export type { FindPlaceQuery, GeoBbox, GeoPoint, PlaceCandidate, PlaceLookup, WOFPlacetype } from "#types"
 
 export type {
 	AncestorsTable,
@@ -17,20 +17,37 @@ export type {
 	PlaceSearchTable,
 	SprTable,
 	WOFDatabase,
-} from "./schema.ts"
+} from "#schema"
 
-export { WOFSqlitePlaceLookup, type RankingWeights, type WOFSqlitePlaceLookupOpts } from "./lookup.ts"
+export { WOFSQLitePlaceLookup, type RankingWeights, type WOFSQLitePlaceLookupOpts } from "#lookup"
 
-export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "./candidate-fts.ts"
+export {
+	CANDIDATE_ANCESTOR_COLUMNS,
+	CANDIDATE_ANCESTOR_TABLE,
+	CANDIDATE_INTERVAL_TABLE,
+	createCandidateAncestorTable,
+	createCandidateIntervalTable,
+	intervalContains,
+	MAX_ANCESTOR_DEPTH,
+} from "#candidate-ancestors-schema"
+
+export type {
+	CandidateAncestorsDatabase,
+	CandidateAncestorTable,
+	CandidateIntervalTable,
+	IntervalLabel,
+} from "#candidate-ancestors-schema"
+
+export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "#candidate-fts"
 
 export {
 	ImportanceIndex,
-	IMPORTANCE_JOIN_GATE_KM,
+	IMPORTANCE_JOIN_RADIUS_KM,
 	type ImportanceIndexStats,
 	loadImportanceIndex,
-} from "./candidate-importance.ts"
+} from "#candidate-importance"
 
-export { WOFCandidateTableLookup, type WOFCandidateTableLookupOpts } from "./candidate-lookup.ts"
+export { WOFCandidateTableLookup, type WOFCandidateTableLookupOpts } from "#candidate-lookup"
 
 export {
 	COUNTRY_BBOX_TABLE,
@@ -39,38 +56,38 @@ export {
 	createCountryCoverageTable,
 	readGazetteerCoverageManifest,
 	writeGazetteerCoverageManifest,
-} from "./coverage-manifest-schema.ts"
+} from "#coverage-manifest-schema"
 
-export type { CountryBBoxTable, CountryCoverageTable, GazetteerCoverageDatabase } from "./coverage-manifest-schema.ts"
-export { SQLiteStreetNameLookup, type SQLiteStreetNameLookupOpts } from "./street-name-lookup.ts"
+export type { CountryBBoxTable, CountryCoverageTable, GazetteerCoverageDatabase } from "#coverage-manifest-schema"
+export { SQLiteStreetNameLookup, type SQLiteStreetNameLookupOpts } from "#street/name-lookup"
 
 export {
 	GEONAMES_ID_BASE,
 	type GeonamesIngestProgress,
 	ingestGeonamesAliases,
 	purgeGeonamesAliasRange,
-} from "./geonames-aliases.ts"
+} from "#geonames/aliases"
 
-export { GEONAMES_POSTAL_ID_BASE } from "./geonames-postal.ts"
+export { GEONAMES_POSTAL_ID_BASE } from "#geonames/postal"
 
-export { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable } from "./address-point-schema.ts"
-export type { AddressPointDatabase, AddressPointTable } from "./address-point-schema.ts"
+export { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable } from "#address/point-schema"
+export type { AddressPointDatabase, AddressPointTable } from "#address/point-schema"
 
 export {
 	WOFPostalCityAliasLookup,
 	type PostalCityAlias,
 	type WOFPostalCityAliasLookupOpts,
-} from "./postal-city-alias-lookup.ts"
+} from "#postal/city-alias-lookup"
 
-export type { PostalCityAliasDatabase, PostalCityAliasTable } from "./postal-city-alias-schema.ts"
+export type { PostalCityAliasDatabase, PostalCityAliasTable } from "#postal/city-alias-schema"
 
 export {
 	POSTAL_CITY_CANDIDATE_COLUMNS,
 	POSTAL_CITY_CANDIDATE_TABLE,
 	createPostalCityCandidateTable,
-} from "./postal-city-candidate-schema.ts"
+} from "#postal/city-candidate-schema"
 
-export type { PostalCityCandidateDatabase, PostalCityCandidateTable } from "./postal-city-candidate-schema.ts"
+export type { PostalCityCandidateDatabase, PostalCityCandidateTable } from "#postal/city-candidate-schema"
 
 export {
 	ADDRESS_CONVENTION_TABLE,
@@ -84,11 +101,11 @@ export {
 	type ResolvedConvention,
 	type ScoringWeights,
 	type Strategy,
-} from "./convention.ts"
+} from "#convention/index"
 
-export { SqliteConventionSource } from "./sqlite-convention-source.ts"
+export { SqliteConventionSource } from "#sqlite-convention-source"
 
-export { WOFPostcodeLookup, type PostcodePlace } from "./postcode-point-lookup.ts"
+export { WOFPostcodeLookup, type PostcodePlace } from "#postcode-point-lookup"
 
 export {
 	PLACE_BBOX_TABLE,
@@ -98,22 +115,9 @@ export {
 	placeSearchFTSExists,
 	type BuildPlaceSearchFTSOpts,
 	type BuildPlaceSearchFTSResult,
-} from "./fts.ts"
+} from "#fts/index"
 
-export {
-	bboxAround,
-	geometryContains,
-	haversineKm,
-	pointInPolygonRings,
-	pointInRing,
-	type Bbox,
-	type GeojsonGeometry,
-	type GeojsonMultiPolygon,
-	type GeojsonPolygon,
-	type GeojsonPosition,
-} from "./geo.ts"
-
-export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth, type AncestorPlaceRow } from "./ancestry.ts"
+export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth, type AncestorPlaceRow } from "#ancestry/index"
 
 export {
 	WOFReverseGeocoder,
@@ -121,31 +125,31 @@ export {
 	type ReverseGeocodeOpts,
 	type ReverseGeocodeResult,
 	type WOFReverseGeocoderOpts,
-} from "./reverse.ts"
+} from "#reverse"
 
-export { AddressPointInterpolator } from "./address-point-interpolation.ts"
-export { AddressPointSqliteLookup } from "./address-point.ts"
+export { AddressPointInterpolator } from "#address/point-interpolation"
+export { AddressPointSqliteLookup } from "#address/point"
 
 export {
 	STREET_CENTROID_COLUMNS,
 	createStreetCentroidIndexes,
 	createStreetCentroidTable,
-} from "./street-centroid-schema.ts"
+} from "#street/centroid-schema"
 
-export type { StreetCentroidDatabase, StreetCentroidTable } from "./street-centroid-schema.ts"
-export { StreetCentroidSqliteLookup } from "./street-centroid.ts"
+export type { StreetCentroidDatabase, StreetCentroidTable } from "#street/centroid-schema"
+export { StreetCentroidSqliteLookup } from "#street/centroid"
 
 export {
 	StreetInterpolator,
 	type InterpolatedHit,
 	type InterpolationMethod,
 	type InterpolationQuery,
-} from "./interpolation.ts"
+} from "#interpolation"
 
 export {
 	deriveSchemaName,
-	pickShardForPlacetype,
-	resolveShards,
-	type ResolvedShard,
-	type ShardConfig,
-} from "./sharding.ts"
+	pickExtractForPlacetype,
+	resolveExtracts,
+	type ResolvedExtract,
+	type ExtractConfig,
+} from "#extracts"

package/{interpolation.ts → lib/interpolation.ts}

@@ -8,7 +8,7 @@
  *   then linear interpolation along the segment polyline. Design:
  *   `docs/articles/plan/2026-06-11-interpolation-design.md`.
  *
- *   Reads the per-state shard built by `scripts/build-interpolation-shard.ts` (`street_segment`: one
+ *   Reads the per-state extract built by `scripts/build-interpolation-extract.ts` (`street_segment`: one
  *   row per TIGER edge SIDE — independent left/right ranges, ZIPs, parity). Query-side
  *   normalization is THE shared normalizer (`street-normalize.ts`) — identical to build-side, by
  *   construction.
@@ -26,20 +26,19 @@
  *   `AddressPointLookup.find()` to keep that wiring mechanical.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
-import { parseJSONStrict } from "@mailwoman/core/objects"
+import { parseJSONStrict } from "@mailwoman/core/json"
 import type { InterpolationLookup } from "@mailwoman/resolver"
-import { clampFraction, pointAlong } from "@mailwoman/spatial"
+import { clampFraction, haversineKm, pointAlong } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { haversineKm } from "./geo.ts"
-import { hasTable } from "./sqlite-utils.ts"
-import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.ts"
+import { hasTable, prepareAll, type PreparedAll } from "#sqlite-utils"
+import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } from "#street/normalize"
+import type { StreetSegmentDatabase } from "#street/segment-schema"
 
 /**
  * How an interpolated answer was computed (#483 Method 2):
  *
- * - `address_point` — bracketed/extrapolated between REAL neighbor points from the #476 shard
+ * - `address_point` — bracketed/extrapolated between REAL neighbor points from the #476 extract
  *   (`AddressPointInterpolator`), replacing TIGER's uniform-spacing assumption with occupancy.
  * - `tiger_range` — linear position within a TIGER segment's theoretical house-number range (`StreetInterpolator`), the
  *   fallback for streets too sparse to bracket.
@@ -92,8 +91,27 @@ export interface InterpolationQuery {
 	 * ZIP scope — strongly preferred; without it common street names abstain (see module doc).
 	 */
 	postcode?: string
+	/**
+	 * The resolved locality's coordinate — the tie-breaker when no postcode was given and the parity-preferred covering
+	 * ranges still span several postcodes. See {@link NEAR_MAX_KM} for the acceptance geometry.
+	 */
+	near?: { lat: number; lon: number }
 }
 
+/**
+ * Acceptance geometry for the `near` tie-break: the winning postcode group's closest segment must sit within this many
+ * kilometres of `near`, AND the runner-up group must be at least {@link NEAR_DOMINANCE} times farther. Both measured on
+ * the two live failures: Brooklyn's `st pauls place` 11226 segment is ~2 km from the Brooklyn centroid with Great
+ * Neck's 11021 at ~24 km (12×); Fraser's `east 13 mile road` 48026 is ~2 km with Mecosta's namesake ~190 km away. A
+ * near-tie between groups is genuine ambiguity and stays an abstention.
+ */
+const NEAR_MAX_KM = 25
+
+/**
+ * See {@link NEAR_MAX_KM}.
+ */
+const NEAR_DOMINANCE = 2
+
 interface SegmentRow {
 	from_hn: number
 	to_hn: number
@@ -106,44 +124,94 @@ interface SegmentRow {
 	release: string
 }
 
-export class StreetInterpolator implements InterpolationLookup {
-	readonly #db: DatabaseSync
-	readonly #ownsDB: boolean
-	readonly #byPostcode: ReturnType<DatabaseSync["prepare"]> | undefined
-	readonly #byStreet: ReturnType<DatabaseSync["prepare"]> | undefined
+/**
+ * The postcode group nearest `near`, under the {@link NEAR_MAX_KM} dominance geometry — or null when no group qualifies
+ * (out of range, or the runner-up is too close to call). A group's distance is its closest segment's first polyline
+ * vertex; a segment whose geometry fails to parse prices as unreachable rather than aborting the tie-break.
+ */
+function nearestPostcodeGroup(pool: readonly SegmentRow[], near: { lat: number; lon: number }): SegmentRow[] | null {
+	const groups = new Map<string, { rows: SegmentRow[]; km: number }>()
+
+	for (const row of pool) {
+		const key = row.postcode ?? ""
+		let km = Number.POSITIVE_INFINITY
+
+		try {
+			const [firstVertex] = parseJSONStrict<[number, number][]>(row.geometry)
+
+			if (firstVertex) {
+				km = haversineKm(near.lat, near.lon, firstVertex[1], firstVertex[0])
+			}
+		} catch {
+			// Unparseable geometry: this row cannot be sited, so it cannot win the tie-break.
+		}
+
+		const group = groups.get(key)
+
+		if (group) {
+			group.rows.push(row)
+			group.km = Math.min(group.km, km)
+		} else {
+			groups.set(key, { rows: [row], km })
+		}
+	}
+
+	const ranked = [...groups.values()].toSorted((a, b) => a.km - b.km)
+	const [winner, runnerUp] = ranked
+
+	if (!winner || winner.km > NEAR_MAX_KM) return null
+
+	if (runnerUp && runnerUp.km < winner.km * NEAR_DOMINANCE) return null
+
+	return winner.rows
+}
+
+export class StreetInterpolator<
+	DB extends StreetSegmentDatabase = StreetSegmentDatabase,
+> implements InterpolationLookup {
+	readonly #db: DatabaseClient<DB>
+	/**
+	 * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
+	 * ownership is membership rather than a flag a later branch has to check.
+	 */
+	readonly #resources = new DisposableStack()
+	readonly #byPostcode:
+		| PreparedAll<[postcode: string, street: RouteKey, minNumber: number, maxNumber: number], SegmentRow>
+		| undefined
+	readonly #byStreet: PreparedAll<[street: RouteKey, minNumber: number, maxNumber: number], SegmentRow> | undefined
 	readonly #radiusCalibration: number | undefined
 
-	constructor(opts: { dbPath?: string; database?: DatabaseSync }) {
+	constructor(opts: { dbPath?: string; database?: DatabaseClient<DB> }) {
 		if (opts.database) {
 			this.#db = opts.database
-			this.#ownsDB = false
 		} else if (opts.dbPath) {
-			this.#db = new DatabaseSync(opts.dbPath, { readOnly: true })
-			this.#ownsDB = true
+			this.#db = this.#resources.use(new DatabaseClient<DB>(opts.dbPath, { readOnly: true }))
 		} else {
 			throw new Error("StreetInterpolator: one of dbPath or database is required")
 		}
 
-		// Degrade gracefully on an empty/tableless shard (interrupted build, stray 0-byte file): with no
+		// Degrade gracefully on an empty/tableless extract (interrupted build, stray 0-byte file): with no
 		// `street_segment` table this interpolator is a no-op miss, not a crash that loses the state (#568).
 		if (hasTable(this.#db, "street_segment")) {
 			const columns = `from_hn, to_hn, min_hn, max_hn, parity, postcode, geometry, source, release`
 
-			this.#byPostcode = this.#db.prepare(
+			this.#byPostcode = prepareAll(
+				this.#db,
 				`SELECT ${columns} FROM street_segment
 				 WHERE postcode = ? AND street_norm = ? AND min_hn <= ? AND max_hn >= ?`
 			)
 
-			this.#byStreet = this.#db.prepare(
+			this.#byStreet = prepareAll(
+				this.#db,
 				`SELECT ${columns} FROM street_segment
 				 WHERE street_norm = ? AND min_hn <= ? AND max_hn >= ?`
 			)
 		}
 
 		// #374 doctrine: the conformal radius multiplier is a property of the calibration set the ARTIFACT was
-		// built against, so it ships in the shard's `interp_calibration` metadata table (street-segment-schema.ts)
+		// built against, so it ships in the extract's `interp_calibration` metadata table (street-segment-schema.ts)
 		// and is read here, once, at open time — sync raw `.prepare()` per the sync-by-interface doctrine
-		// (AGENTS.md). Shards predating the table (the pre-2026-07 fleet) yield `undefined`; callers then fall
+		// (AGENTS.md). Extracts predating the table (the pre-2026-07 fleet) yield `undefined`; callers then fall
 		// back to their in-code table, byte-identically.
 		if (hasTable(this.#db, "interp_calibration")) {
 			const row = this.#db.prepare("SELECT radius_multiplier FROM interp_calibration LIMIT 1").get() as
@@ -159,9 +227,9 @@ export class StreetInterpolator implements InterpolationLookup {
 	}
 
 	/**
-	 * The artifact's own conformal radius multiplier (#374), read from the shard's `interp_calibration` metadata table at
-	 * construction. `undefined` = the shard predates the table (or carries no valid row) — the resolver then applies no
-	 * artifact default and callers may supply a legacy fallback.
+	 * The artifact's own conformal radius multiplier (#374), read from the extract's `interp_calibration` metadata table
+	 * at construction. `undefined` = the extract predates the table (or carries no valid row) — the resolver then applies
+	 * no artifact default and callers may supply a legacy fallback.
 	 */
 	get radiusCalibration(): number | undefined {
 		return this.#radiusCalibration
@@ -169,29 +237,41 @@ export class StreetInterpolator implements InterpolationLookup {
 
 	find(query: InterpolationQuery): InterpolatedHit | null {
 		if (!this.#byPostcode || !this.#byStreet) return null
-		const streetNorm = canonicalizeRouteKey(normalizeStreetForKey(query.street))
 		const numberRaw = query.number.trim()
 
 		// Strictly-numeric house numbers only — this tier estimates, it doesn't guess at
 		// hyphenated/alphanumeric schemes the ranges don't model.
-		if (!streetNorm || !/^\d+$/.test(numberRaw)) return null
+		if (!/^\d+$/.test(numberRaw)) return null
 		const n = Number(numberRaw)
 
-		let rows: SegmentRow[]
+		// Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
+		// collapse and the saint↔st register swap. A variant advances the ladder when it produces no
+		// ANSWER, not merely no rows — a wrong-register key can cover the number in far-away towns and
+		// then fail the ambiguity check ("saint pauls place" reaches Nassau's rows; the Brooklyn answer
+		// lives under "st pauls place"), and stopping at rows would eclipse the right variant.
+		for (const variant of streetKeyVariants(query.street)) {
+			const streetNorm = canonicalizeRouteKey(variant)
 
-		if (query.postcode) {
 			// A given ZIP that scopes to nothing is a MISS, not a statewide guess: the retry was
 			// measured (2026-06-11 VT eval) at +2.3pp coverage for a poisoned tail (p99 1.0 → 20.8
 			// km, max 204 km — a unique name statewide can live in a far-away town).
-			rows = this.#byPostcode.all(query.postcode.trim(), streetNorm, n, n) as unknown as SegmentRow[]
-		} else {
-			// No scope given: a name matching ranges across several ZIPs is ambiguous — abstain.
-			rows = this.#byStreet.all(streetNorm, n, n) as unknown as SegmentRow[]
-			const postcodes = new Set(rows.map((r) => r.postcode ?? ""))
+			const rows = query.postcode
+				? this.#byPostcode(query.postcode.trim(), streetNorm, n, n)
+				: this.#byStreet(streetNorm, n, n)
+
+			const hit = this.#answerFromRows(rows, n, query)
 
-			if (postcodes.size > 1) return null
+			if (hit) return hit
 		}
 
+		return null
+	}
+
+	/**
+	 * Resolve one key variant's covering rows to an answer, or null when they cannot honestly give one — the
+	 * parity/ambiguity/tightest-range pipeline the module doc describes.
+	 */
+	#answerFromRows(rows: SegmentRow[], n: number, query: InterpolationQuery): InterpolatedHit | null {
 		if (!rows.length) return null
 
 		// Parity preference: exact side first, then 'mixed' (matches either), then the
@@ -200,9 +280,27 @@ export class StreetInterpolator implements InterpolationLookup {
 		const exact = rows.filter((r) => r.parity === (wantOdd ? "odd" : "even"))
 		const mixed = rows.filter((r) => r.parity === "mixed")
 		const preferred = exact.length ? exact : mixed
-		const pool = preferred.length ? preferred : rows
+		let pool = preferred.length ? preferred : rows
 		const parityMatched = preferred.length > 0
 
+		// No scope given: the covering ranges must agree on ONE postcode or the lookup abstains — a
+		// name spanning towns is ambiguity, not an answer. Counted over the PARITY pool, not all
+		// rows: a section-line boundary road carries a different ZIP per side ("east 13 mile road"
+		// is Fraser 48026 odd / Roseville 48066 even), and the opposite side can never hold the
+		// number it would otherwise veto. When several postcodes survive parity, the caller's
+		// resolved-locality coordinate breaks the tie by segment proximity under the dominance
+		// geometry of {@link NEAR_MAX_KM} — a near-tie stays an abstention.
+		if (!query.postcode) {
+			const postcodes = new Set(pool.map((r) => r.postcode ?? ""))
+
+			if (postcodes.size > 1) {
+				const scoped = query.near ? nearestPostcodeGroup(pool, query.near) : null
+
+				if (!scoped) return null
+				pool = scoped
+			}
+		}
+
 		// Tightest range wins — the most specific claim about where this number lives.
 		let best = pool[0]!
 
@@ -229,9 +327,7 @@ export class StreetInterpolator implements InterpolationLookup {
 		}
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
 	}
 }