@mailwoman/resolver-wof-sqlite 9.2.0 → 9.4.0

package/{street-segment-schema.ts → lib/street/segment-schema.ts}

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the TIGER STREET-SEGMENT interpolation shards (`street-segments-<cc>-<st>.db`,
- *   built by `scripts/build-interpolation-shard.ts` from TIGER EDGES) — the #483 Method-3 fallback
+ *   Typed schema for the TIGER STREET-SEGMENT interpolation extracts (`street-segments-<cc>-<st>.db`,
+ *   built by `scripts/build-interpolation-extract.ts` from TIGER EDGES) — the #483 Method-3 fallback
  *   the resolver drops to when the address-point tier (Method 2) can't bracket. Single source of
  *   truth for the columns the BUILDER writes and the READER ({@link StreetInterpolator}) probes, so
  *   a column rename in one is a compile error in the other.
@@ -17,7 +17,7 @@
 
 import type { Kysely } from "kysely"
 
-import type { RouteKey } from "./street-normalize.ts"
+import type { RouteKey } from "#street/normalize"
 
 /**
  * One TIGER street-segment edge: a `(from_hn, to_hn)` house-number range on one `side` of a named street, with the
@@ -74,11 +74,11 @@ export interface StreetSegmentTable {
 }
 
 /**
- * The shard's single-row calibration metadata (#374 doctrine, 2026-07-26): the conformal radius multiplier is a
+ * The extract'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).
+ * {@link StreetInterpolator}. Extracts 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 {
 	/**
@@ -147,7 +147,7 @@ export async function createStreetSegmentTable(db: Kysely<StreetSegmentDatabase>
 
 /**
  * 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
+ * by the extract 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.
  */

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

@@ -91,8 +91,8 @@ export interface PlaceCandidate {
 	/**
 	 * STRICT encyclopedia-evidence importance in [0, 1], fan-out-guarded per #1497 — CARRIED, NEVER RANKED ON.
 	 *
-	 * RESERVED SLOT awaiting a strict-channel source: present only when a shard's `place_importance` table carries the
-	 * split columns, and no shipped shard does — the FTS lookup's clauses emit NULL for everything today. `undefined`
+	 * RESERVED SLOT awaiting a strict-channel source: present only when a extract's `place_importance` table carries the
+	 * split columns, and no shipped extract does — the FTS lookup's clauses emit NULL for everything today. `undefined`
 	 * means either "no encyclopedia entry for this place" or "this gazetteer predates the split"; both are absence, and
 	 * neither is 0. The BLENDED prior the ranking reads is {@link PlaceCandidate.importance}.
 	 *
@@ -126,10 +126,17 @@ export interface PlaceCandidate {
 	 * Admin-containment stamp (#1717 stage 2) — TRI-STATE, mirroring `ResolvedPlace.containedByQualifier` in
 	 * `@mailwoman/core`: `true` = the ancestors sidecar vouches this candidate sits under the query's
 	 * {@link FindPlaceQuery.regionQualifier}; `false` = evaluated and not vouched for; absent = never evaluated (no
-	 * qualifier on the query, or an artifact without the sidecar). Absence is load-bearing — the resolver walk reads it
-	 * as `unavailable`, never as "not contained".
+	 * qualifier on the query, or an artifact without the sidecar). Absence is required — the resolver walk reads it as
+	 * `unavailable`, never as "not contained".
 	 */
 	containedByQualifier?: boolean
+	/**
+	 * The #1882 exemption's firing mark (#1893), mirroring `ResolvedPlace.variantAliasExempted` in `@mailwoman/core`:
+	 * present only when this candidate's row would have taken the cross-country alias penalty and the exemption prevented
+	 * it. Emitted by the candidate-table backend alone — the WASM FTS lookup never runs the ranker, and its candidates
+	 * omit the field (not evaluated, never "did not fire").
+	 */
+	variantAliasExempted?: true
 }
 
 /**
@@ -179,8 +186,8 @@ export interface FindPlaceQuery {
 	 */
 	fuzzyCountry?: string
 	/**
-	 * Restrict name matching to PRIMARY-keyed rows (#1632) — set by probes whose surface is a RE-READING (a token cut out
-	 * of a longer classified span), which never named an alias. See the ResolverBackend contract in
+	 * Restrict name matching to PRIMARY-keyed rows (#1632) — set by probes whose surface is a RE-READING (a token taken
+	 * out of a longer classified span), which never named an alias. See the ResolverBackend contract in
 	 * `@mailwoman/core/resolver`.
 	 */
 	primaryOnly?: boolean
@@ -197,14 +204,14 @@ export interface FindPlaceQuery {
 	 * Sibling postcode. When set on a `locality` query AND a `postcode_locality` table is present, triggers the
 	 * coordinate-first soft-score path: postcode→candidate localities are injected and scored `0.6·S_pc + 0.3·S_name +
 	 * 0.1·S_pop` against the FTS name-match set, recovering small localities the name-match alone misses. Ignored when no
-	 * postcode_locality shard is present.
+	 * postcode_locality extract is present.
 	 */
 	postcode?: string
 	/**
 	 * Postcode-containment coherence (#31, Mechanism 2) — when true on a locality query that also carries `postcode`,
-	 * candidate rows within `POSTCODE_CONTAINMENT_GATE_KM` of the postcode's own centroid sort by distance first, the
-	 * rest appended in their original order. Set by the resolver from `ResolveOpts.postcodeContainmentCoherence`; absent
-	 * → the population-first order is untouched (byte-identical).
+	 * candidate rows within `POSTCODE_CONTAINMENT_THRESHOLD_KM` of the postcode's own centroid sort by distance first,
+	 * the rest appended in their original order. Set by the resolver from `ResolveOpts.postcodeContainmentCoherence`;
+	 * absent → the population-first order is untouched (byte-identical).
 	 */
 	postcodeContainmentCoherence?: boolean
 	/**
@@ -243,7 +250,6 @@ export interface FindPlaceQuery {
  * interface is async even though `node:sqlite` is sync — leaves room for `Worker`-backed implementations later without
  * a public API break.
  */
-export interface PlaceLookup {
+export interface PlaceLookup extends Disposable {
 	findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>
-	close(): void
 }

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,14 +25,13 @@
  *   `@mailwoman/spatial`'s `shortCellToInt` via `uprnFullCell` — never reimplemented here.
  */
 
-import { DatabaseSync } from "node:sqlite"
-
+import { allRows } from "@mailwoman/core/utils"
 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 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
  * × edge apart (avg edge 174.4 m → ≈302 m); the worst bearing across a ring costs a further ×0.866, and H3's projection
@@ -82,7 +81,7 @@ export interface UPRNLookupOpts {
 	/**
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
-	database?: DatabaseSync
+	database?: DatabaseClient<UPRNDatabase>
 }
 
 interface UPRNRow {
@@ -96,21 +95,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 +199,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