@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{unified-schema.ts → lib/unified-schema.ts}

@@ -12,23 +12,20 @@
  *   `place_search` FTS5 + `place_bbox` R*Tree are built separately by `build-fts` (fts.ts).
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import type { WOFDatabase } from "#schema"
 
-import type { WOFDatabase } from "./schema.ts"
-
-export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
+export async function createUnifiedSchema(db: DatabaseClient<WOFDatabase>): Promise<void> {
 	// PRAGMAs stay raw — not Kysely-modelled, and these tune the bulk build.
 	db.exec("PRAGMA journal_mode = WAL")
 	db.exec("PRAGMA busy_timeout = 10000")
 	db.exec("PRAGMA synchronous = OFF")
 
-	// `kdb` wraps `db` for the DDL (the house idiom); the caller owns `db`'s lifecycle, so we don't
+	// `db` wraps `db` for the DDL (the house idiom); the caller owns `db`'s lifecycle, so we don't
 	// destroy it here. The bulk INSERTs (populateAncestors + build-unified-wof) stay on the raw handle.
-	const kdb = new DatabaseClient<WOFDatabase>({ database: db })
 
-	await kdb.schema
+	await db.schema
 		.createTable("spr")
 		.ifNotExists()
 		.addColumn("id", "integer", (c) => c.primaryKey())
@@ -56,7 +53,7 @@ export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
 	// x_variant rows tagged with an official language ("MSP", "Frisco") stay 0. Primary-name mirror
 	// rows stay 0 too: the name-exact tier already consults spr.name; `official` only marks the
 	// ALIASES eligible to join it. Both are ingest-time facts, never computed at query time.
-	await kdb.schema
+	await db.schema
 		.createTable("names")
 		.ifNotExists()
 		.addColumn("id", "integer", (c) => c.notNull())
@@ -69,7 +66,7 @@ export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
 		.addColumn("lastmodified", "integer", (c) => c.notNull().defaultTo(0))
 		.execute()
 
-	await kdb.schema
+	await db.schema
 		.createTable("concordances")
 		.ifNotExists()
 		.addColumn("id", "integer", (c) => c.notNull())
@@ -78,7 +75,7 @@ export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
 		.addColumn("lastmodified", "integer", (c) => c.notNull().defaultTo(0))
 		.execute()
 
-	await kdb.schema
+	await db.schema
 		.createTable("place_population")
 		.ifNotExists()
 		.addColumn("id", "integer", (c) => c.primaryKey())
@@ -90,7 +87,7 @@ export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
 	// `spr.id IN (SELECT id FROM ancestors WHERE ancestor_id = ?)`. The off-the-shelf WOF dumps
 	// ship this table; our build derives it from the parent_id chain (see populateAncestors) since
 	// we don't capture `wof:hierarchy`.
-	await kdb.schema
+	await db.schema
 		.createTable("ancestors")
 		.ifNotExists()
 		.addColumn("id", "integer", (c) => c.notNull())
@@ -107,7 +104,7 @@ export async function createUnifiedSchema(db: DatabaseSync): Promise<void> {
  * Sentinel/negative parent_ids and cycles terminate the walk. ~4 rows/place average; a transaction keeps the ~5M
  * inserts fast.
  */
-export function populateAncestors(db: DatabaseSync): number {
+export function populateAncestors<DB>(db: DatabaseClient<DB>): number {
 	db.exec("DELETE FROM ancestors")
 
 	const rows = db.prepare("SELECT id, parent_id, placetype FROM spr").all() as Array<{
@@ -151,22 +148,21 @@ export function populateAncestors(db: DatabaseSync): number {
 	return count
 }
 
-export async function createUnifiedIndexes(db: DatabaseSync): Promise<void> {
-	const kdb = new DatabaseClient<WOFDatabase>({ database: db })
-	await kdb.schema.createIndex("spr_by_placetype").ifNotExists().on("spr").column("placetype").execute()
-	await kdb.schema.createIndex("spr_by_country").ifNotExists().on("spr").column("country").execute()
-	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()
+export async function createUnifiedIndexes(db: DatabaseClient<WOFDatabase>): Promise<void> {
+	await db.schema.createIndex("spr_by_placetype").ifNotExists().on("spr").column("placetype").execute()
+	await db.schema.createIndex("spr_by_country").ifNotExists().on("spr").column("country").execute()
+	await db.schema.createIndex("spr_by_parent").ifNotExists().on("spr").column("parent_id").execute()
+	await db.schema.createIndex("names_by_id").ifNotExists().on("names").column("id").execute()
+	await db.schema.createIndex("names_by_name").ifNotExists().on("names").column("name").execute()
 
-	await kdb.schema
+	await db.schema
 		.createIndex("concordances_by_id")
 		.ifNotExists()
 		.on("concordances")
 		.columns(["id", "lastmodified"])
 		.execute()
 
-	await kdb.schema
+	await db.schema
 		.createIndex("concordances_by_other_id")
 		.ifNotExists()
 		.on("concordances")
@@ -175,6 +171,6 @@ export async function createUnifiedIndexes(db: DatabaseSync): Promise<void> {
 
 	// 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()
-	await kdb.schema.createIndex("ancestors_by_id").ifNotExists().on("ancestors").column("id").execute()
+	await db.schema.createIndex("ancestors_by_ancestor").ifNotExists().on("ancestors").column("ancestor_id").execute()
+	await db.schema.createIndex("ancestors_by_id").ifNotExists().on("ancestors").column("id").execute()
 }

package/lib/uprn/existence.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The consult `./lookup.ts`'s docstring instructs: "callers building negative evidence must consult
+ *   `readLayerCoverage`, not this reader alone." A bare `null` from `nearestUPRN` is two different facts — no UPRN here,
+ *   or nobody surveyed here — and this is the only place that separates them. It answers an {@link Exclusion} or `null`,
+ *   so a caller cannot read an unsurveyed cell as an empty one by accident.
+ *
+ *   `radiusM` is a CALLER'S parameter with no default. There is no radius that is correct for both "which property is
+ *   this coordinate" and "is this street built at all", and picking one here would bury that choice where nobody
+ *   reviewing an exclusion can see it.
+ */
+
+import { readLayerCoverage, readLayerManifest, type LayerContractHandle } from "@mailwoman/core/layers"
+import { foldIdentity, requireExclusionBasis, type Exclusion } from "@mailwoman/evidence"
+import { shortCellToParentInt } from "@mailwoman/spatial"
+
+import type { UPRNLookup } from "#uprn/lookup"
+import { UPRN_COVERAGE_H3_RESOLUTION, UPRN_H3_RESOLUTION, uprnH3Cell } from "#uprn/schema"
+
+/**
+ * The identity fold, on purpose: this probe keys on a COORDINATE, not a name, so there is no string folding for the
+ * builder and the probe to disagree about. Passing the same identity as both `probeFold` and `layerFold` records that
+ * the fold axis is not in play here, rather than silently omitting the check. It is not a stub.
+ */
+export const UPRN_EXISTENCE_FOLD = foldIdentity((s) => s)
+
+/**
+ * The countries OS Open UPRN covers. Northern Ireland is outside the product, so a `null` there is unknown and must
+ * never become evidence of absence; the country check is what keeps it out.
+ */
+export const UPRN_COVERED_COUNTRIES: ReadonlySet<string> = new Set(["GB"])
+
+export interface UPRNAbsenceInput {
+	lookup: UPRNLookup
+	/**
+	 * The same file the lookup reads; the layer contract tables live beside the points.
+	 */
+	contractDB: LayerContractHandle
+	latitude: number
+	longitude: number
+	radiusM: number
+	/**
+	 * ISO-2 country of the thing whose absence is being asserted, when known.
+	 */
+	country?: string
+}
+
+/**
+ * The coverage cell a coordinate falls in, derived from its stored res-9 cell exactly as the builder derives it — never
+ * from the centroid, which lands in a different parent for a fraction of cells.
+ */
+export function uprnCoverageCell(latitude: number, longitude: number): number {
+	return shortCellToParentInt(uprnH3Cell(latitude, longitude), UPRN_H3_RESOLUTION, UPRN_COVERAGE_H3_RESOLUTION)
+}
+
+/**
+ * An {@link Exclusion} when no UPRN lies within `radiusM` AND the layer's coverage licenses saying so; `null` on a hit
+ * (presence is not this probe's business) and on every refusal (unsurveyed cell, `source_present` basis, a country the
+ * product does not cover). Never throws on a refusal: the caller falls open to the ranking it already had.
+ */
+export async function uprnAbsenceAt(input: UPRNAbsenceInput): Promise<Exclusion | null> {
+	const coverageCell = uprnCoverageCell(input.latitude, input.longitude)
+	const coverage = await readLayerCoverage(input.contractDB, coverageCell)
+
+	if (!coverage) return null
+
+	if (input.lookup.nearestUPRN(input.latitude, input.longitude, input.radiusM)) return null
+
+	const manifest = await readLayerManifest(input.contractDB)
+
+	return requireExclusionBasis({
+		layer: manifest.name,
+		source: manifest.source,
+		vintage: manifest.sourceVintage,
+		h3Cell: coverageCell,
+		cell: coverage,
+		probeFold: UPRN_EXISTENCE_FOLD,
+		layerFold: UPRN_EXISTENCE_FOLD,
+		country: input.country,
+		countries: UPRN_COVERED_COUNTRIES,
+	})
+}

package/lib/uprn/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#uprn/existence"
+export * from "#uprn/lookup"
+export * from "#uprn/schema"

package/{uprn-lookup.ts → lib/uprn/lookup.ts}

@@ -25,13 +25,13 @@
  *   `@mailwoman/spatial`'s `shortCellToInt` via `uprnFullCell` — never reimplemented here.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { gridDisk } from "h3-js"
 
-import { allRows } from "./sqlite-utils.ts"
-import { uprnFullCell } from "./uprn-schema.ts"
+import { allRows } from "#sqlite-utils"
+import type { UPRNDatabase } from "#uprn/schema"
+import { uprnFullCell } from "#uprn/schema"
 
 /**
  * Conservative FLOOR on how much CENTRE distance one unit of res-9 GRID distance buys, metres. Adjacent centres sit √3
@@ -82,7 +82,7 @@ export interface UPRNLookupOpts {
 	/**
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
-	database?: DatabaseSync
+	database?: DatabaseClient<UPRNDatabase>
 }
 
 interface UPRNRow {
@@ -96,21 +96,23 @@ interface UPRNRow {
  * precedent as {@link POILookup}.
  */
 export class UPRNLookup implements Disposable {
-	#db: DatabaseSync
-	#ownsDB: boolean
+	#db: DatabaseClient<UPRNDatabase>
+	/**
+	 * 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()
 
 	/**
 	 * `uprn` → its point (rowid-alias PK hit).
 	 */
-	readonly #coordinateProbe: ReturnType<DatabaseSync["prepare"]>
+	readonly #coordinateProbe: ReturnType<DatabaseClient["prepare"]>
 
 	constructor(opts: UPRNLookupOpts) {
 		if (opts.database) {
 			this.#db = opts.database
-			this.#ownsDB = false
 		} else if (opts.databasePath) {
-			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
-			this.#ownsDB = true
+			this.#db = this.#resources.use(new DatabaseClient<UPRNDatabase>(opts.databasePath, { readOnly: true }))
 		} else {
 			throw new Error("UPRNLookup needs `databasePath` or `database`")
 		}
@@ -198,13 +200,7 @@ export class UPRNLookup implements Disposable {
 		return best
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
-	}
-
 	[Symbol.dispose](): void {
-		this.close()
+		this.#resources[Symbol.dispose]()
 	}
 }

package/{uprn-schema.ts → lib/uprn/schema.ts}

@@ -22,11 +22,11 @@
  *   The layer contract requires every domain row to be addressable by at least one spine key —
  *   `writeLayerManifest` throws on a manifest that declares none — and UPRN is its own id space, not
  *   H3/WOF/address-id/street. The res-9 short cell (`shortCellToInt`, the same packing as poi.db and
- *   the OSM situs shards) is the spine that fits a point table, and its index doubles as the
+ *   the OSM situs extracts) is the spine that fits a point table, and its index doubles as the
  *   `nearestUPRN` ring probe.
  *
  *   The DB also embeds the layer-contract tables from `@mailwoman/core/layers`; the builder
- *   (`packages/mailwoman/gazetteer-pipeline/uprn-layer.ts`) writes the manifest and per-res-6-cell
+ *   (`packages/mailwoman/lib/gazetteer-pipeline/uprn-layer.ts`) writes the manifest and per-res-6-cell
  *   coverage.
  */
 
@@ -37,7 +37,7 @@ import type { Kysely } from "kysely"
 
 /**
  * Resolution the `uprn` table's `h3_cell` column is keyed at — the shared layer-spine resolution (poi.db, the OSM situs
- * shards).
+ * extracts).
  */
 export const UPRN_H3_RESOLUTION = 9