@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/lib/geonames/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#geonames/aliases"
+export * from "#geonames/postal"

package/{geonames-postal.ts → lib/geonames/postal.ts}

@@ -3,15 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   #920 — fold GeoNames POSTAL codes into a WOF/unified postcode shard as first-class
+ *   #920 — fold GeoNames POSTAL codes into a WOF/unified postcode extract as first-class
  *   `postalcode` places, for the countries whose WOF postalcode repos don't exist (the
  *   namesake-tail locales: FI/CZ/SK/SI/DK/NO/HR/PL and any future gap).
  *
  *   Why: the night-31 taxonomy measured the cross-locale resolve tail as NAMESAKE COLLISION
- *   (FI 300/1k … PL 75/1k offender rows), and the controlled experiment showed postcode-shard
+ *   (FI 300/1k … PL 75/1k offender rows), and the controlled experiment showed postcode-extract
  *   coverage alone collapses it (FI 300→1, CZ 131→4): a resolvable postcode node feeds the
  *   resolver's coordinate-first sibling-postcode candidate injection, which binds the locality
- *   pick to its postcode neighborhood. The machinery already ships; it was coverage-starved.
+ *   pick to its postcode neighborhood. The implementation already ships; it was coverage-starved.
  *
  *   Two hard-won laws from the experiment are enforced HERE, in code, not in a runbook:
  *
@@ -30,16 +30,17 @@
  *   --geonames-postal-countries`, any standalone fold, and the `mailwoman gazetteer` commands
  *   share ONE implementation. GeoNames postal dump = `download.geonames.org/export/zip/<CC>.zip`
  *   → `<CC>.txt` (TSV: country, postcode, place, admin1, code1, admin2, code2, admin3, code3,
- *   lat, lon, accuracy). License CC BY 4.0 — attribution rides the shard's `meta` provenance and
+ *   lat, lon, accuracy). License CC BY 4.0 — attribution rides the extract's `meta` provenance and
  *   the model card like the existing GeoNames alias fold.
  */
 
-import { existsSync } from "node:fs"
-import type { DatabaseSync } from "node:sqlite"
-
-import { join } from "path-ts"
+import { pathExists } from "@mailwoman/core/fs/readers"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { join, type PathBuilderLike } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
+import type { WOFDatabase } from "#schema"
+
 /**
  * Column count of a GeoNames postal-code TSV row. Short rows are truncated or blank and are skipped. See the
  * allCountries.zip readme for the field list.
@@ -77,7 +78,7 @@ export type PostcodePoint = readonly [number, number]
  *
  * Distance is squared-Euclidean in DEGREES, not haversine. At the scale a postcode spans, the ranking the two produce
  * is the same, and this one carries no trig into a per-group inner loop. Ties go to the earliest member, which makes
- * the result a pure function of the input order — the property a rebuilt shard's ids depend on.
+ * the result a pure function of the input order — the property a rebuilt extract's ids depend on.
  *
  * Exported (rather than inlined at each ingest) because it is the second half of the #920 pair: every postcode source
  * that groups member points — GeoNames postal, OSM `addr:postcode` — owes the same law, and a second hand-rolled copy
@@ -138,9 +139,9 @@ export interface GeonamesPostalIngestResult {
  * freeze phase).
  */
 export async function ingestGeonamesPostal(
-	db: DatabaseSync,
+	db: DatabaseClient<WOFDatabase>,
 	countries: readonly string[],
-	postalDir: string
+	postalDir: PathBuilderLike
 ): Promise<GeonamesPostalIngestResult> {
 	const sprInsert = db.prepare(
 		`INSERT OR REPLACE INTO spr (id, parent_id, name, placetype, country, latitude, longitude, min_latitude, min_longitude, max_latitude, max_longitude, is_current, is_deprecated, is_ceased, is_superseded, is_superseding, lastmodified) VALUES (?, -1, ?, 'postalcode', ?, ?, ?, ?, ?, ?, ?, 1, 0, 0, 0, 0, 0)`
@@ -159,7 +160,7 @@ export async function ingestGeonamesPostal(
 		const cc = country.toUpperCase()
 		const file = join(postalDir, `${cc}.txt`)
 
-		if (!existsSync(file)) {
+		if (!(await pathExists(file))) {
 			missing.push(cc)
 
 			console.error(
@@ -173,7 +174,7 @@ export async function ingestGeonamesPostal(
 		const members = new Map<string, { display: string; pts: Array<[number, number]> }>()
 
 		// Streamed: a national dump is a caller-supplied size — GB's is 177 MB, and only the caller
-		// knows which country is next. `header: false` is load-bearing; the GeoNames postal dump is
+		// knows which country is next. `header: false` is required; the GeoNames postal dump is
 		// headerless, so row 1 would be consumed as column names and its postcode lost.
 		for await (const cols of TSVSpliterator.fromAsync(file, { header: false })) {
 			if (cols.length < GEONAMES_POSTAL_COLUMNS) continue

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,9 +17,9 @@ 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_ANCESTOR_COLUMNS,
@@ -29,25 +29,25 @@ export {
 	createCandidateIntervalTable,
 	intervalContains,
 	MAX_ANCESTOR_DEPTH,
-} from "./candidate-ancestors-schema.ts"
+} from "#candidate-ancestors-schema"
 
 export type {
 	CandidateAncestorsDatabase,
 	CandidateAncestorTable,
 	CandidateIntervalTable,
 	IntervalLabel,
-} from "./candidate-ancestors-schema.ts"
+} from "#candidate-ancestors-schema"
 
-export { CANDIDATE_FTS_TABLE, createCandidateFTS } from "./candidate-fts.ts"
+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,
@@ -56,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,
@@ -101,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,
@@ -115,9 +115,9 @@ export {
 	placeSearchFTSExists,
 	type BuildPlaceSearchFTSOpts,
 	type BuildPlaceSearchFTSResult,
-} from "./fts.ts"
+} from "#fts/index"
 
-export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth, type AncestorPlaceRow } from "./ancestry.ts"
+export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth, type AncestorPlaceRow } from "#ancestry/index"
 
 export {
 	WOFReverseGeocoder,
@@ -125,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,19 +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, haversineKm, pointAlong } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { hasTable, prepareAll, type PreparedAll } from "./sqlite-utils.ts"
-import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } 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.
@@ -166,27 +166,31 @@ function nearestPostcodeGroup(pool: readonly SegmentRow[], near: { lat: number;
 	return winner.rows
 }
 
-export class StreetInterpolator implements InterpolationLookup {
-	readonly #db: DatabaseSync
-	readonly #ownsDB: boolean
+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`
@@ -205,9 +209,9 @@ export class StreetInterpolator implements InterpolationLookup {
 		}
 
 		// #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
@@ -223,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
@@ -243,7 +247,7 @@ export class StreetInterpolator implements InterpolationLookup {
 		// 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 gate ("saint pauls place" reaches Nassau's rows; the Brooklyn answer
+		// 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)
@@ -323,9 +327,7 @@ export class StreetInterpolator implements InterpolationLookup {
 		}
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
 	}
 }