@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

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

@@ -39,7 +39,7 @@ export type WOFPlacetype =
  * treat it as ordinal, not absolute.
  *
  * `id` is the WOF place id. It's named generically (not `wof_id`) so the shape stays structurally compatible with
- * `@mailwoman/resolver`'s `ResolvedPlace` — `WOFSqlitePlaceLookup` satisfies the generic `ResolverBackend` contract
+ * `@mailwoman/resolver`'s `ResolvedPlace` — `WOFSQLitePlaceLookup` satisfies the generic `ResolverBackend` contract
  * without an adapter shim.
  *
  * `distanceKm` is populated only when the query carried `near` (and the place has a centroid). Useful for downstream
@@ -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}.
 	 *
@@ -122,6 +122,21 @@ export interface PlaceCandidate {
 	 * the falsehood-detection differentiator.
 	 */
 	mismatch?: boolean
+	/**
+	 * 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 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
 }
 
 /**
@@ -163,6 +178,24 @@ export interface FindPlaceQuery {
 	 * ISO 3166-1 alpha-2 — narrows to one country.
 	 */
 	country?: string
+	/**
+	 * ISO 3166-1 alpha-2 — narrows the TYPO-FUZZY tier only (#1585). Exact and qualifier-strip probes stay worldwide (a
+	 * locale hint is a prior, never a hard filter on exact matches), but a typo CORRECTION into a different country's
+	 * namespace is nearly always a scrape, so the corrected-key probes honor this scope and a scoped-empty ABSTAINS
+	 * rather than falling through to a world-fuzzy candidate. Ignored when `country` is set (already narrower).
+	 */
+	fuzzyCountry?: string
+	/**
+	 * 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
+	/**
+	 * Alias-row NAME ROLES the probe refuses to answer through (#1730) — the bare-toponym side races pass `abbr`/`gloss`.
+	 * Role-NULL alias rows (the exonym tier) stay open; backends/artifacts without a role column ignore it.
+	 */
+	excludeNameRoles?: readonly string[]
 	/**
 	 * WOF place id — narrows to descendants of this place.
 	 */
@@ -171,16 +204,24 @@ 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
+	/**
+	 * The tree's parsed REGION qualifier (#1717 stage 2) — set by the resolver on locality lookups when
+	 * `ResolveOpts.adminContainmentRerank` is on. See the `ResolverBackend` contract in `@mailwoman/core/resolver`: a
+	 * capable backend stamps `containedByQualifier`, ranks contained candidates first, and may ADD contained same-key
+	 * candidates a country scope hid — additive only, never a filter. Ignored on an artifact without the ancestors
+	 * sidecar (candidates then carry no stamp).
+	 */
+	regionQualifier?: string
 	/**
 	 * Proximity hint — candidates close to this point get a ranking boost.
 	 */
@@ -209,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}

@@ -7,28 +7,25 @@
  *   (`scripts/build-unified-wof.ts`). This is the CANONICAL gazetteer — we never use the
  *   off-the-shelf geocode.earth prebuilt dumps (they assign different WOF ids to the same place;
  *   see the `feedback-custom-wof-db-only` memory). The table/column names match the resolver's
- *   expectations (`lookup.ts`) so `WOFSqlitePlaceLookup` works unchanged, INCLUDING the `ancestors`
+ *   expectations (`lookup.ts`) so `WOFSQLitePlaceLookup` works unchanged, INCLUDING the `ancestors`
  *   table (which lookup.ts's parent-constraint subquery needs) — see `populateAncestors`. The
  *   `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/lib/uprn/lookup.ts

@@ -0,0 +1,206 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node reader for `uprn.db` — the OS Open UPRN layer (`uprn-schema.ts`). Two probes:
+ *
+ *   - **`coordinateOf(uprn)`**: rowid B-tree hit on the `uprn` integer PK.
+ *   - **`nearestUPRN(lat, lon, radiusM)`**: bounded nearest-point search over the res-9 `h3_cell`
+ *     index — ring-by-ring `gridDisk` expansion with chunked `IN` probes and haversine ranking.
+ *     Rings stop as soon as geometry proves no unprobed cell could beat the best hit — a distance
+ *     bound, not POILookup's row-count accumulation, so the early exit can never strand a nearer
+ *     point in an unprobed ring.
+ *
+ *   ## `null` is a claim, scoped by coverage
+ *
+ *   OS designates Open UPRN complete for GB (every UPRN in AddressBase Premium with geometry), and
+ *   the builder writes `layer_coverage` with basis `designated` for every cell the product touches.
+ *   So a `null` from either probe inside a covered cell is evidence of absence — "no such published
+ *   GB UPRN" / "no UPRN within the radius". Outside coverage (Northern Ireland, the Isle of Man, the
+ *   Channel Islands, open water) it is UNKNOWN, per the meaning-of-zero rule — callers building
+ *   negative evidence must consult `readLayerCoverage`, not this reader alone.
+ *
+ *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing is
+ *   `@mailwoman/spatial`'s `shortCellToInt` via `uprnFullCell` — never reimplemented here.
+ */
+
+import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { gridDisk } from "h3-js"
+
+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
+ * × edge apart (avg edge 174.4 m → ≈302 m); the worst bearing across a ring costs a further ×0.866, and H3's projection
+ * distortion shrinks edges by well under the slack this leaves (the true worst is ≈217 m per grid step). Dividing a
+ * radius by this over-counts rings and can never miss a cell; multiplying a grid distance by it under-states reach and
+ * can never end the ring walk early.
+ */
+const RES9_CENTER_SPACING_FLOOR_M = 150
+
+/**
+ * Conservative CEILING on a res-9 cell's centre-to-vertex distance, metres (avg edge 174.4 m; distortion stays well
+ * under this). A point within `radiusM` of the query sits in a cell whose CENTRE is within `radiusM` + this.
+ */
+const RES9_CELL_RADIUS_CEILING_M = 300
+
+/**
+ * Hard ceiling on `radiusM`. Keeps the probe bounded (10 km → ~72 rings ≈ 15.8k cells ≈ 18 `IN` chunks); a caller who
+ * wants a wider search than "which property is this coordinate" has outgrown this reader and should say so loudly.
+ */
+export const UPRN_MAX_NEAREST_RADIUS_M = 10_000
+
+/**
+ * `IN`-list chunk size for the cell probe — far under SQLite's 32,766 bound-variable ceiling.
+ */
+const CELL_PROBE_CHUNK = 900
+
+export interface UPRNCoordinate {
+	latitude: number
+	longitude: number
+}
+
+export interface UPRNNearestHit {
+	uprn: number
+	latitude: number
+	longitude: number
+	/**
+	 * Haversine distance from the query point, metres.
+	 */
+	distanceM: number
+}
+
+export interface UPRNLookupOpts {
+	/**
+	 * Path to a `uprn.db` built by `mailwoman`'s gazetteer pipeline. Opened read-only.
+	 */
+	databasePath?: string
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
+	database?: DatabaseClient<UPRNDatabase>
+}
+
+interface UPRNRow {
+	uprn: number
+	lat: number
+	lon: number
+}
+
+/**
+ * Node reader over `uprn.db`. `implements Disposable` so callers can `using lookup = new UPRNLookup(...)` — the same
+ * precedent as {@link POILookup}.
+ */
+export class UPRNLookup implements Disposable {
+	#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<DatabaseClient["prepare"]>
+
+	constructor(opts: UPRNLookupOpts) {
+		if (opts.database) {
+			this.#db = opts.database
+		} else if (opts.databasePath) {
+			this.#db = this.#resources.use(new DatabaseClient<UPRNDatabase>(opts.databasePath, { readOnly: true }))
+		} else {
+			throw new Error("UPRNLookup needs `databasePath` or `database`")
+		}
+
+		this.#coordinateProbe = this.#db.prepare("SELECT lat, lon FROM uprn WHERE uprn = ?")
+	}
+
+	/**
+	 * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such UPRN (see the module docstring for
+	 * what that `null` claims).
+	 */
+	coordinateOf(uprn: number): UPRNCoordinate | null {
+		const row = this.#coordinateProbe.get(uprn) as { lat: number; lon: number } | undefined
+
+		return row ? { latitude: row.lat, longitude: row.lon } : null
+	}
+
+	/**
+	 * The single nearest UPRN within `radiusM` metres of the query point, or `null` when no UPRN lies inside the radius.
+	 *
+	 * Bounded two ways: `radiusM` is capped at {@link UPRN_MAX_NEAREST_RADIUS_M}, and rings expand outward only until no
+	 * unprobed cell could beat the best hit found so far (or the radius, when nothing has been found). The stop rule is
+	 * geometric — a cell at grid distance `g` holds no point nearer than `g` × spacing floor − cell radius, using the
+	 * same conservative constants the reach math uses — so unlike POILookup's row-count accumulation there is no
+	 * early-exit ambiguity: a break can never strand a nearer point in an unprobed ring. This is what keeps a
+	 * capped-radius call over dense ground at milliseconds instead of a full-disk fetch (measured 6.4 s → 13 ms for a 10
+	 * km radius over central London, 41.6M-row layer; an empty-sea miss at the cap runs the full expansion, 74 ms).
+	 *
+	 * @throws {RangeError} When `radiusM` is not a positive finite number, or exceeds the cap.
+	 */
+	nearestUPRN(latitude: number, longitude: number, radiusM: number): UPRNNearestHit | null {
+		if (!Number.isFinite(radiusM) || radiusM <= 0) {
+			throw new RangeError(`nearestUPRN: radiusM must be a positive finite number, received ${radiusM}`)
+		}
+
+		if (radiusM > UPRN_MAX_NEAREST_RADIUS_M) {
+			throw new RangeError(`nearestUPRN: radiusM ${radiusM} exceeds the ${UPRN_MAX_NEAREST_RADIUS_M} m cap`)
+		}
+
+		const origin = uprnFullCell(latitude, longitude)
+		const seenCells = new Set<string>()
+		let best: UPRNNearestHit | null = null
+
+		// `ring` is H3 grid distance; the loop terminates because the break bound is at most radiusM, which the
+		// RangeError above caps.
+		for (let ring = 0; ; ring++) {
+			// A cell at grid distance `ring` holds no point nearer than this. Once it exceeds what could still
+			// win — the best hit so far, or the radius itself — further rings cannot improve the answer.
+			const closestPossibleM = ring * RES9_CENTER_SPACING_FLOOR_M - RES9_CELL_RADIUS_CEILING_M
+
+			if (closestPossibleM > Math.min(radiusM, best?.distanceM ?? radiusM)) break
+
+			// gridDisk(origin, ring) returns the WHOLE disk out to `ring`; diffing against what's already been
+			// probed derives just this ring's new cells (the POILookup pattern).
+			const diskCells = gridDisk(origin, ring) as string[]
+			const newCells: number[] = []
+
+			for (const cell of diskCells) {
+				if (!seenCells.has(cell)) {
+					seenCells.add(cell)
+					newCells.push(shortCellToInt(cell as H3Cell))
+				}
+			}
+
+			for (let i = 0; i < newCells.length; i += CELL_PROBE_CHUNK) {
+				const chunk = newCells.slice(i, i + CELL_PROBE_CHUNK)
+				const placeholders = chunk.map(() => "?").join(", ")
+
+				// Prepared fresh per chunk arity — a cold, per-call path, same posture as POILookup's batched hydration.
+				const rows = allRows<UPRNRow>(
+					this.#db.prepare(`SELECT uprn, lat, lon FROM uprn WHERE h3_cell IN (${placeholders})`),
+					...chunk
+				)
+
+				for (const row of rows) {
+					const distanceM = haversineKm(latitude, longitude, row.lat, row.lon) * 1000
+
+					if (distanceM <= radiusM && (best === null || distanceM < best.distanceM)) {
+						best = { uprn: row.uprn, latitude: row.lat, longitude: row.lon, distanceM }
+					}
+				}
+			}
+		}
+
+		return best
+	}
+
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
+	}
+}

package/lib/uprn/schema.ts

@@ -0,0 +1,124 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for `uprn.db` — the OS Open UPRN spatial layer: every GB Unique Property Reference
+ *   Number with its WGS84 point, so mailwoman results can carry UPRN as an interoperability key
+ *   beside our own `@mailwoman/address-id`. One rowid table keyed `uprn INTEGER PRIMARY KEY` (the
+ *   rowid alias — the optimal shape for an integer-PK point table; `WITHOUT ROWID` buys nothing
+ *   here), plus a secondary res-9 `h3_cell` index for the bounded nearest-point probe.
+ *
+ *   ## Coordinates are OS's own WGS84 columns
+ *
+ *   The source CSV publishes BOTH coordinate systems per row — OSGB36 eastings/northings AND WGS84
+ *   `LATITUDE`/`LONGITUDE`. This layer stores OS's own lat/lon verbatim and never reconverts from
+ *   eastings: `@mailwoman/spatial`'s `osgb36ToWGS84` is a 7-parameter Helmert with a measured p95 of
+ *   4.18 m, and re-deriving what the publisher already computed (with OSTN15, exactly) would replace
+ *   their answer with a strictly worse one.
+ *
+ *   ## Why `h3_cell` exists at all
+ *
+ *   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 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/lib/gazetteer-pipeline/uprn-layer.ts`) writes the manifest and per-res-6-cell
+ *   coverage.
+ */
+
+import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import { shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { latLngToCell } from "h3-js"
+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
+ * extracts).
+ */
+export const UPRN_H3_RESOLUTION = 9
+
+/**
+ * Resolution of the layer's `layer_coverage` cells — coarse, per the contract (matches poi.db).
+ */
+export const UPRN_COVERAGE_H3_RESOLUTION = 6
+
+/**
+ * One UPRN point. `uprn` is the rowid alias, so the primary probe (`coordinateOf`) is a rowid B-tree hit.
+ */
+export interface UPRNTable {
+	/**
+	 * The Unique Property Reference Number — up to 12 digits, so always within `Number.MAX_SAFE_INTEGER`.
+	 */
+	uprn: number
+	/**
+	 * WGS84 latitude, as OS published it (never reconverted from eastings — see the module docstring).
+	 */
+	lat: number
+	/**
+	 * WGS84 longitude, as OS published it.
+	 */
+	lon: number
+	/**
+	 * 48-bit short H3 cell at {@link UPRN_H3_RESOLUTION} (`uprnH3Cell`) — the layer-contract spine key and the
+	 * `nearestUPRN` probe index.
+	 */
+	h3_cell: number
+}
+
+/**
+ * Build-provenance key/value pairs the fixed `layer_manifest` columns have no room for: quality-drop counts, the header
+ * as found, the upstream licence text verbatim (the Code-Point provenance discipline).
+ */
+export interface UPRNMetaTable {
+	key: string
+	value: string
+}
+
+export interface UPRNDatabase extends LayerContractDatabase {
+	uprn: UPRNTable
+	uprn_meta: UPRNMetaTable
+}
+
+/**
+ * The full res-9 cell for a UPRN point — the ONE derivation both the builder and every consumer share, so a fixture
+ * built by a test and a row built by the real ingest can never disagree on which cell a coordinate keys to.
+ */
+export function uprnFullCell(latitude: number, longitude: number): H3Cell {
+	return latLngToCell(latitude, longitude, UPRN_H3_RESOLUTION) as H3Cell
+}
+
+/**
+ * The `h3_cell` column value for a UPRN point: {@link uprnFullCell} packed to the shared 48-bit short-cell integer.
+ */
+export function uprnH3Cell(latitude: number, longitude: number): number {
+	return shortCellToInt(uprnFullCell(latitude, longitude))
+}
+
+export async function createUPRNTable(db: Kysely<UPRNDatabase>): Promise<void> {
+	await db.schema
+		.createTable("uprn")
+		.addColumn("uprn", "integer", (c) => c.primaryKey())
+		.addColumn("lat", "real", (c) => c.notNull())
+		.addColumn("lon", "real", (c) => c.notNull())
+		.addColumn("h3_cell", "integer", (c) => c.notNull())
+		.execute()
+}
+
+export async function createUPRNMetaTable(db: Kysely<UPRNDatabase>): Promise<void> {
+	await db.schema
+		.createTable("uprn_meta")
+		.addColumn("key", "text", (c) => c.primaryKey())
+		.addColumn("value", "text", (c) => c.notNull())
+		.execute()
+}
+
+/**
+ * Secondary index for the `nearestUPRN` ring probe. Builders call this AFTER the bulk load (index-after-load).
+ */
+export async function createUPRNIndexes(db: Kysely<UPRNDatabase>): Promise<void> {
+	await db.schema.createIndex("uprn_h3_cell").on("uprn").column("h3_cell").execute()
+}