@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/unified-schema.ts

@@ -3,13 +3,11 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Schema for the unified WOF SQLite database we build from cloned WOF GeoJSON repos
- *   (`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`
- *   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).
+ * Schema for the unified WOF SQLite database built from cloned WOF GeoJSON repos
+ * (`scripts/build-unified-wof.ts`). The table and column names match the resolver's
+ * expectations (`lookup.ts`) so `WOFSQLitePlaceLookup` works unchanged. The `ancestors` table
+ * table is what lookup.ts's parent-constraint subquery reads (see `populateAncestors`).
+ * The `place_search` FTS5 and `place_bbox` R*Tree tables are built separately by `build-fts` (fts.ts).
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
@@ -17,13 +15,14 @@ import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { WOFDatabase } from "#schema"
 
 export async function createUnifiedSchema(db: DatabaseClient<WOFDatabase>): Promise<void> {
-	// PRAGMAs stay raw — not Kysely-modelled, and these tune the bulk build.
+	// PRAGMAs run raw because Kysely does not model them.
+	// They tune the bulk build.
 	db.exec("PRAGMA journal_mode = WAL")
 	db.exec("PRAGMA busy_timeout = 10000")
 	db.exec("PRAGMA synchronous = OFF")
 
-	// `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.
+	// The caller owns `db`'s lifecycle, so this function does not destroy it.
+	// The bulk INSERTs (populateAncestors + build-unified-wof) run on the raw handle.
 
 	await db.schema
 		.createTable("spr")
@@ -47,12 +46,16 @@ export async function createUnifiedSchema(db: DatabaseClient<WOFDatabase>): Prom
 		.addColumn("lastmodified", "integer", (c) => c.notNull().defaultTo(0))
 		.execute()
 
-	// `privateuse` carries WOF's x_<variant> kind (preferred | variant) / GeoNames' isPreferredName
-	// ("preferred" | ""). `official` is the #936 ingest bit: 1 when the row's language is an official
-	// language of the place's country (codex OFFICIAL_LANGUAGES) AND the row is a preferred form —
-	// 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.
+	// `privateuse` represents WOF's x_<variant> kind (preferred | variant) or GeoNames'
+	// isPreferredName ("preferred" | "").
+	// `official` is the ingest bit.
+	// It is 1 when the row's language is an official language of the place's country
+	// (codex OFFICIAL_LANGUAGES) and the row is a preferred form. 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 db.schema
 		.createTable("names")
 		.ifNotExists()
@@ -82,11 +85,12 @@ export async function createUnifiedSchema(db: DatabaseClient<WOFDatabase>): Prom
 		.addColumn("population", "integer", (c) => c.notNull().defaultTo(0))
 		.execute()
 
-	// `ancestors` maps each place to every place above it in the hierarchy (and itself). The
-	// resolver's parent-constraint scopes a child lookup to a parent's descendants via
-	// `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`.
+	// `ancestors` maps each place to every place above it in the hierarchy (and itself).
+	// The resolver's parent-constraint scopes a child lookup to a parent's descendants
+	// via `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 db.schema
 		.createTable("ancestors")
 		.ifNotExists()
@@ -98,11 +102,9 @@ export async function createUnifiedSchema(db: DatabaseClient<WOFDatabase>): Prom
 }
 
 /**
- * Populate the `ancestors` table by walking each place's `parent_id` chain in `spr` (transitive closure, including the
- * place itself). Idempotent: drops + rebuilds the table contents. Returns the row count. Run after `spr` is fully
- * ingested (build-unified-wof freeze phase) or standalone on an existing unified DB (`scripts/add-ancestors.ts`).
- * Sentinel/negative parent_ids and cycles terminate the walk. ~4 rows/place average; a transaction keeps the ~5M
- * inserts fast.
+ * Populate the `ancestors` table by walking each place's `parent_id` chain in `spr`
+ * to a transitive closure that includes the place itself.
+ * Run this after `spr` is fully ingested.
  */
 export function populateAncestors<DB>(db: DatabaseClient<DB>): number {
 	db.exec("DELETE FROM ancestors")
@@ -126,7 +128,6 @@ export function populateAncestors<DB>(db: DatabaseClient<DB>): number {
 	for (const r of rows) {
 		insert.run(r.id, r.id, r.placetype)
 
-		// self
 		count++
 		const seen = new Set<number>([r.id])
 		let cur = r.parent_id
@@ -169,8 +170,7 @@ export async function createUnifiedIndexes(db: DatabaseClient<WOFDatabase>): Pro
 		.columns(["other_source", "other_id"])
 		.execute()
 
-	// ancestor_id is the hot column (parent-constraint queries `WHERE ancestor_id = ?`); id supports
-	// the reverse lookup.
+	// ancestor_id is the hot column for parent-constraint queries. id supports the reverse lookup.
 	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

@@ -3,16 +3,16 @@
  * @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`,
+ *   `readLayerCoverage`, not this reader by itself." A bare `null` from `nearestUPRN` is two different facts — no uprn here,
+ *   or an unsurveyed area — 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
+ *   `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 reviewers
  *   reviewing an exclusion can see it.
  */
 
-import { readLayerCoverage, readLayerManifest, type LayerContractHandle } from "@mailwoman/core/layers"
+import { readLayerCoverage, readLayerManifest, type layerschemahandle } from "@mailwoman/core/layers"
 import { foldIdentity, requireExclusionBasis, type Exclusion } from "@mailwoman/evidence"
 import { shortCellToParentInt } from "@mailwoman/spatial"
 
@@ -20,24 +20,31 @@ 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.
+ * The identity fold, on purpose: this probe keys on a coordinate rather than a name,
+ * so there is no string folding for the builder and the probe to disagree about.
+ *
+ * The same identity in 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.
+ * 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.
+	 * The same file the lookup reads.
+	 * The layer interface tables live beside the points.
 	 */
-	contractDB: LayerContractHandle
+	schemadb: layerschemahandle
 	latitude: number
 	longitude: number
 	radiusM: number
@@ -48,27 +55,31 @@ export interface UPRNAbsenceInput {
 }
 
 /**
- * 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.
+ * The coverage cell a coordinate falls in, derived from its stored res-9 cell exactly
+ * as the builder derives it rather than from the centroid.
+ *
+ * The centroid 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.
+ * 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)
+	const coverage = await readLayerCoverage(input.schemadb, coverageCell)
 
 	if (!coverage) return null
 
 	if (input.lookup.nearestUPRN(input.latitude, input.longitude, input.radiusM)) return null
 
-	const manifest = await readLayerManifest(input.contractDB)
+	const manifest = await readLayerManifest(input.schemadb)
 
 	return requireExclusionBasis({
 		layer: manifest.name,

package/lib/uprn/lookup.ts

@@ -3,53 +3,32 @@
  * @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.
+ * Node reader for `uprn.db`, where a `null` is evidence of absence only inside published coverage, so callers building negative evidence must consult `readLayerCoverage`.
  */
 
 import { allRows } from "@mailwoman/core/utils"
-import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { haversineKm, shortCellToInt, type GeoCoordinate, type H3Cell } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { gridDisk } from "h3-js"
+import type { PathBuilderLike } from "path-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
- * 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.
+ * Conservative floor, in meters, on the center distance one unit of res-9 grid distance buys,
+ * so multiplying a grid distance 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.
+ * Conservative ceiling, in meters, on a res-9 cell's center-to-vertex distance, so a point
+ * within `radiusM` of the query sits in a cell whose center is within `radiusM` plus 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.
+ * Hard ceiling on `radiusM` that keeps the probe bounded, since a caller wanting a wider
+ * search than "which property is this coordinate" has outgrown this reader.
  */
 export const UPRN_MAX_NEAREST_RADIUS_M = 10_000
 
@@ -58,28 +37,23 @@ export const UPRN_MAX_NEAREST_RADIUS_M = 10_000
  */
 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.
+	 * Haversine distance from the query point, meters.
 	 */
 	distanceM: number
 }
 
 export interface UPRNLookupOpts {
 	/**
-	 * Path to a `uprn.db` built by `mailwoman`'s gazetteer pipeline. Opened read-only.
+	 * Path to a `uprn.db` built by `mailwoman`'s gazetteer pipeline, opened read-only.
 	 */
-	databasePath?: string
+	databasePath?: PathBuilderLike
 	/**
-	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 * Pre-opened handle (tests / shared connections), mutually exclusive with `databasePath`.
 	 */
 	database?: DatabaseClient<UPRNDatabase>
 }
@@ -91,54 +65,45 @@ interface UPRNRow {
 }
 
 /**
- * Node reader over `uprn.db`. `implements Disposable` so callers can `using lookup = new UPRNLookup(...)` — the same
- * precedent as {@link POILookup}.
+ * Node reader over `uprn.db`, disposable so callers can take it with `using`.
  */
 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.
+	 * Ownership is membership: a connection handed in by a caller is not in here,
+	 * so disposal cannot reach it.
 	 */
-	readonly #resources = new DisposableStack()
+	readonly #resources: DisposableStack
 
-	/**
-	 * `uprn` → its point (rowid-alias PK hit).
-	 */
 	readonly #coordinateProbe: ReturnType<DatabaseClient["prepare"]>
 
 	constructor(opts: UPRNLookupOpts) {
+		using resources = new DisposableStack()
+
 		if (opts.database) {
 			this.#db = opts.database
 		} else if (opts.databasePath) {
-			this.#db = this.#resources.use(new DatabaseClient<UPRNDatabase>(opts.databasePath, { readOnly: true }))
+			this.#db = 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 = ?")
+		this.#resources = resources.move()
 	}
 
 	/**
-	 * 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).
+	 * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such uprn.
 	 */
-	coordinateOf(uprn: number): UPRNCoordinate | null {
+	coordinateOf(uprn: number): GeoCoordinate | 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).
+	 * The single nearest uprn within `radiusM` meters of the query point, or `null`
+	 * when no uprn lies inside the radius.
 	 *
 	 * @throws {RangeError} When `radiusM` is not a positive finite number, or exceeds the cap.
 	 */
@@ -155,17 +120,14 @@ export class UPRNLookup implements Disposable {
 		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.
+		// The loop terminates because the break bound is at most `radiusM`.
+		// The RangeError above caps that value.
 		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.
+			// Once this bound exceeds the best hit so far, or the radius, 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[] = []
 
@@ -180,7 +142,6 @@ export class UPRNLookup implements Disposable {
 				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
@@ -189,7 +150,7 @@ export class UPRNLookup implements Disposable {
 				for (const row of rows) {
 					const distanceM = haversineKm(latitude, longitude, row.lat, row.lon) * 1000
 
-					if (distanceM <= radiusM && (best === null || distanceM < best.distanceM)) {
+					if (distanceM <= radiusM && (!best || distanceM < best.distanceM)) {
 						best = { uprn: row.uprn, latitude: row.lat, longitude: row.lon, distanceM }
 					}
 				}

package/lib/uprn/schema.ts

@@ -3,51 +3,27 @@
  * @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.
+ * Typed schema for `uprn.db`, storing OS's own WGS84 latitude/longitude verbatim rather than reconverting from the source's eastings.
  */
 
-import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import type { layerschemadatabase } 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).
+ * Resolution the `uprn` table's `h3_cell` column is keyed at, shared with the other layer spines.
  */
 export const UPRN_H3_RESOLUTION = 9
 
 /**
- * Resolution of the layer's `layer_coverage` cells — coarse, per the contract (matches poi.db).
+ * Resolution of the layer's `layer_coverage` cells, coarse per the layer interface
+ * and shared with the other spines.
  */
 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.
+ * One uprn point whose `uprn` is a rowid alias, making the primary probe a rowid B-tree hit.
  */
 export interface UPRNTable {
 	/**
@@ -55,7 +31,7 @@ export interface UPRNTable {
 	 */
 	uprn: number
 	/**
-	 * WGS84 latitude, as OS published it (never reconverted from eastings — see the module docstring).
+	 * WGS84 latitude, as OS published it, never reconverted from eastings.
 	 */
 	lat: number
 	/**
@@ -63,36 +39,38 @@ export interface UPRNTable {
 	 */
 	lon: number
 	/**
-	 * 48-bit short H3 cell at {@link UPRN_H3_RESOLUTION} (`uprnH3Cell`) — the layer-contract spine key and the
-	 * `nearestUPRN` probe index.
+	 * 48-bit short H3 cell at {@link UPRN_H3_RESOLUTION} — the layer-interface 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).
+ * Build-provenance key/value pairs the fixed `layer_manifest` columns have no room for,
+ * including the upstream license text verbatim.
  */
 export interface UPRNMetaTable {
 	key: string
 	value: string
 }
 
-export interface UPRNDatabase extends LayerContractDatabase {
+export interface UPRNDatabase extends layerschemadatabase {
 	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.
+ * The full res-9 cell for a UPRN point.
+ *
+ * This is the one derivation the builder and its consumers share so their cells cannot disagree.
  */
 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.
+ * The `h3_cell` column value for a uprn point, packing {@link uprnFullCell} to
+ * the shared 48-bit short-cell integer.
  */
 export function uprnH3Cell(latitude: number, longitude: number): number {
 	return shortCellToInt(uprnFullCell(latitude, longitude))
@@ -117,7 +95,7 @@ export async function createUPRNMetaTable(db: Kysely<UPRNDatabase>): Promise<voi
 }
 
 /**
- * Secondary index for the `nearestUPRN` ring probe. Builders call this AFTER the bulk load (index-after-load).
+ * Secondary index for the `nearestUPRN` ring probe, created after the bulk load.
  */
 export async function createUPRNIndexes(db: Kysely<UPRNDatabase>): Promise<void> {
 	await db.schema.createIndex("uprn_h3_cell").on("uprn").column("h3_cell").execute()