@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/lib/nsul/lookup.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node reader for `nsul.db` — the GB UPRN → unit-postcode register (`nsul/schema.ts`). Two probes,
+ *   both synchronous `.prepare()` hits in the `uprn/lookup.ts` style:
+ *
+ *   - **`postcodeForUPRN(uprn)`**: primary-key hit on the `WITHOUT ROWID` table.
+ *   - **`uprnsForPostcode(postcode)`**: the `pcds_compact` index, answering every UPRN the register
+ *     assigns to one unit postcode with the point OS publishes for each — the "assigned points and
+ *     their bound" the physical-constraint design record names as the prior's soft structure.
+ *
+ *   ## `null` and `[]` are claims, scoped by coverage
+ *
+ *   The register designates GB complete (every UPRN in AddressBase with a Code-Point Open postcode),
+ *   and the builder writes `layer_coverage` with basis `designated` for every cell the register
+ *   touches. Inside a covered cell an empty answer is evidence of absence: no GB UPRN by that number
+ *   carries a Code-Point postcode, or no UPRN carries that postcode. Two absences the reader cannot
+ *   tell from those are recorded in `nsul_meta` as counts rather than as rows — a UPRN whose `PCDS` is
+ *   null (its postcode is not in Code-Point Open) and one Open UPRN publishes no coordinate for — so a
+ *   caller building negative evidence reads the coverage table and those counts, not this reader
+ *   alone. Outside coverage (Northern Ireland, the Isle of Man, the Channel Islands) the answer is
+ *   UNKNOWN, per the meaning-of-zero rule.
+ */
+
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import { compactPostcode, type NSULDatabase } from "#nsul/schema"
+import { prepareAll, prepareGet } from "#sqlite-utils"
+
+/**
+ * The unit postcode the register assigns to a UPRN, in both stored forms.
+ */
+export interface NSULPostcode {
+	/**
+	 * As NSUL writes it — `RG40 4HR`.
+	 */
+	pcds: string
+	/**
+	 * Space removed — `RG404HR`, Code-Point Open's `spr.name` form.
+	 */
+	pcdsCompact: string
+}
+
+/**
+ * One UPRN assigned to a unit postcode, with the point `uprn.db` holds for it.
+ */
+export interface NSULAssignedPoint {
+	uprn: number
+	latitude: number
+	longitude: number
+	/**
+	 * 48-bit short res-9 H3 cell, as `uprn.db` stores it.
+	 */
+	h3Cell: number
+}
+
+export interface NSULLookupOpts {
+	/**
+	 * Path to a `nsul.db` built by `mailwoman`'s gazetteer pipeline. Opened read-only.
+	 */
+	databasePath?: string
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
+	database?: DatabaseClient<NSULDatabase>
+}
+
+interface PostcodeRow {
+	pcds: string
+	pcds_compact: string
+}
+
+interface PointRow {
+	uprn: number
+	lat: number
+	lon: number
+	h3_cell: number
+}
+
+/**
+ * Node reader over `nsul.db`. `implements Disposable` so callers can `using lookup = new NSULLookup(...)` — the same
+ * precedent as `UPRNLookup`.
+ */
+export class NSULLookup implements Disposable {
+	#db: DatabaseClient<NSULDatabase>
+	/**
+	 * 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 #postcodeProbe: (uprn: number) => PostcodeRow | undefined
+	readonly #pointsProbe: (pcdsCompact: string) => PointRow[]
+
+	constructor(opts: NSULLookupOpts) {
+		if (opts.database) {
+			this.#db = opts.database
+		} else if (opts.databasePath) {
+			this.#db = this.#resources.use(new DatabaseClient<NSULDatabase>(opts.databasePath, { readOnly: true }))
+		} else {
+			throw new Error("NSULLookup needs `databasePath` or `database`")
+		}
+
+		this.#postcodeProbe = prepareGet<[number], PostcodeRow, NSULDatabase>(
+			this.#db,
+			"SELECT pcds, pcds_compact FROM uprn_postcode WHERE uprn = ?"
+		)
+
+		this.#pointsProbe = prepareAll<[string], PointRow, NSULDatabase>(
+			this.#db,
+			"SELECT uprn, lat, lon, h3_cell FROM uprn_postcode WHERE pcds_compact = ? ORDER BY uprn"
+		)
+	}
+
+	/**
+	 * The unit postcode the register assigns to `uprn`, or `null` when the register holds no row for it (see the module
+	 * docstring for what that `null` claims).
+	 */
+	postcodeForUPRN(uprn: number): NSULPostcode | null {
+		const row = this.#postcodeProbe(uprn)
+
+		return row ? { pcds: row.pcds, pcdsCompact: row.pcds_compact } : null
+	}
+
+	/**
+	 * Every UPRN the register assigns to one unit postcode, with its published point, in ascending UPRN order. The key is
+	 * compacted through {@link compactPostcode} first, so `PO21 1HR` and `PO211HR` answer identically. An empty array is
+	 * the register's answer, scoped as the module docstring says.
+	 */
+	uprnsForPostcode(postcode: string): NSULAssignedPoint[] {
+		return this.#pointsProbe(compactPostcode(postcode)).map((row) => ({
+			uprn: row.uprn,
+			latitude: row.lat,
+			longitude: row.lon,
+			h3Cell: row.h3_cell,
+		}))
+	}
+
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
+	}
+}

package/lib/nsul/schema.ts

@@ -0,0 +1,130 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for `nsul.db` — the GB UPRN → unit-postcode register: the ONS **National Statistics
+ *   UPRN Lookup** (NSUL) joined to the WGS84 point OS Open UPRN publishes for the same UPRN. One row per
+ *   GB UPRN that carries a unit postcode AND has a published coordinate; the postcode is Code-Point
+ *   Open's, so this table and `postcode-gb.bin` agree by construction on the universe of unit postcodes.
+ *
+ *   ## Why this table exists
+ *
+ *   Code-Point Open gives one coordinate per unit postcode; Open UPRN gives one coordinate per
+ *   addressable object; neither says which object carries which postcode. NSUL does, as field `PCDS`,
+ *   under OGL-UK-3.0. The `PO`-area measurement that produced this design (recorded on #1975) showed a
+ *   nearest-centroid reconstruction of the register is exact on 69.6% of 531,266 UPRNs and a building
+ *   footprint adds nothing, so the register is stored rather than inferred.
+ *
+ *   ## Shape
+ *
+ *   `uprn_postcode` is `WITHOUT ROWID` keyed on the UPRN: small fixed rows, probed by primary key, with
+ *   one secondary index on `pcds_compact`. The postcode is stored twice on purpose — `pcds` exactly as
+ *   NSUL writes it (`RG40 4HR`, one space) and `pcds_compact` with the space removed (`RG404HR`), which
+ *   is the form Code-Point Open's `spr.name` uses, so the two artifacts join on a column rather than an
+ *   expression. `lat`/`lon`/`h3_cell` are COPIED from `uprn.db` at build time by UPRN join — OS's own
+ *   WGS84 columns, never a reprojection of NSUL's `GRIDGB1E`/`GRIDGB1N` — so a coordinate here is
+ *   byte-identical to the one `uprn.db` holds for the same UPRN.
+ *
+ *   The DB also embeds the layer-contract tables from `@mailwoman/core/layers`; the builder
+ *   (`packages/mailwoman/lib/gazetteer-pipeline/nsul-layer.ts`) writes the manifest and coverage.
+ */
+
+import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import { sql, type Kysely } from "kysely"
+
+/**
+ * Resolution of the `h3_cell` column — the same res-9 spine `uprn.db` keys on, because the value is copied from it.
+ */
+export const NSUL_H3_RESOLUTION = 9
+
+/**
+ * Resolution of the layer's `layer_coverage` cells — coarse, per the contract, and the same as `uprn.db`'s so the two
+ * layers' coverage tables describe the same cells.
+ */
+export const NSUL_COVERAGE_H3_RESOLUTION = 6
+
+/**
+ * One UPRN with its unit postcode and the point OS publishes for it.
+ */
+export interface UPRNPostcodeTable {
+	/**
+	 * The Unique Property Reference Number — up to 12 digits, so always within `Number.MAX_SAFE_INTEGER`.
+	 */
+	uprn: number
+	/**
+	 * The unit postcode as NSUL writes it — outward code, one space, inward code (`RG40 4HR`).
+	 */
+	pcds: string
+	/**
+	 * {@link pcds} with the space removed (`RG404HR`) — the form Code-Point Open's `spr.name` carries, and the column
+	 * `uprnsForPostcode` probes.
+	 */
+	pcds_compact: string
+	/**
+	 * WGS84 latitude, copied from `uprn.db` for the same UPRN.
+	 */
+	lat: number
+	/**
+	 * WGS84 longitude, copied from `uprn.db` for the same UPRN.
+	 */
+	lon: number
+	/**
+	 * 48-bit short H3 cell at {@link NSUL_H3_RESOLUTION}, copied from `uprn.db` for the same UPRN.
+	 */
+	h3_cell: number
+}
+
+/**
+ * Build-provenance key/value pairs the fixed `layer_manifest` columns have no room for: the accounting counts, the
+ * header as found, the per-region row counts, the four attribution lines.
+ */
+export interface NSULMetaTable {
+	key: string
+	value: string
+}
+
+export interface NSULDatabase extends LayerContractDatabase {
+	uprn_postcode: UPRNPostcodeTable
+	nsul_meta: NSULMetaTable
+}
+
+/**
+ * The compact form of a unit postcode: every space removed, upper-cased. `RG40 4HR` → `RG404HR`. The ONE derivation
+ * both the builder and every consumer share, so a caller holding NSUL's spaced form and one holding Code-Point's
+ * compact form reach the same key.
+ */
+export function compactPostcode(pcds: string): string {
+	return pcds.replaceAll(/\s+/g, "").toUpperCase()
+}
+
+export async function createUPRNPostcodeTable(db: Kysely<NSULDatabase>): Promise<void> {
+	await db.schema
+		.createTable("uprn_postcode")
+		.addColumn("uprn", "integer", (c) => c.primaryKey())
+		.addColumn("pcds", "text", (c) => c.notNull())
+		.addColumn("pcds_compact", "text", (c) => c.notNull())
+		.addColumn("lat", "real", (c) => c.notNull())
+		.addColumn("lon", "real", (c) => c.notNull())
+		.addColumn("h3_cell", "integer", (c) => c.notNull())
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+export async function createNSULMetaTable(db: Kysely<NSULDatabase>): Promise<void> {
+	await db.schema
+		.createTable("nsul_meta")
+		.addColumn("key", "text", (c) => c.primaryKey())
+		.addColumn("value", "text", (c) => c.notNull())
+		.execute()
+}
+
+/**
+ * The `pcds_compact` index the `uprnsForPostcode` probe reads. Builders call this AFTER the bulk load
+ * (index-after-load). There is no index on the spaced `pcds`: it is derivable from `pcds_compact` through
+ * {@link compactPostcode}, and a second index over 40 million rows would buy nothing a caller cannot get by compacting
+ * its key first.
+ */
+export async function createNSULIndexes(db: Kysely<NSULDatabase>): Promise<void> {
+	await db.schema.createIndex("uprn_postcode_pcds_compact").on("uprn_postcode").column("pcds_compact").execute()
+}

package/{place-importance-schema.ts → lib/place-importance-schema.ts}

@@ -31,12 +31,11 @@
  *   should read it; new code reads the split columns.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import { referentialFromPopulation } from "@mailwoman/core/resolver"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { Kysely } from "kysely"
 
-import { allRows } from "./sqlite-utils.ts"
+import { allRows } from "#sqlite-utils"
 
 //#region Schema
 
@@ -205,12 +204,12 @@ export type ImportanceSplitSource = (typeof IMPORTANCE_SPLIT_SOURCES)[keyof type
  *
  * There is deliberately no ORDER BY counterpart, and there should never be one: §2's policy is that this score is
  * carried and never ranked on. Without the column the select degrades to a literal `NULL` and the join is the empty
- * string, so a pre-split shard's query plan is byte-identical to what it was before the split. No shipped gazetteer
+ * string, so a pre-split extract's query plan is byte-identical to what it was before the split. No shipped gazetteer
  * carries the column yet, so today that degraded form is the only one anything builds.
  *
- * Call it ONCE per shard and cache the result — it runs a `PRAGMA`, and the callers are per-keystroke hot.
+ * Call it ONCE per extract and cache the result — it runs a `PRAGMA`, and the callers are per-keystroke hot.
  */
-export function encyclopedicClauses(db: DatabaseSync, schemaName: string): { select: string; join: string } {
+export function encyclopedicClauses<DB>(db: DatabaseClient<DB>, schemaName: string): { select: string; join: string } {
 	let present: boolean
 
 	try {
@@ -300,7 +299,7 @@ export interface ImportanceSplit {
 /**
  * Does `table` exist in `db`, and if so which of `columns` does it have?
  */
-function tableColumns(db: DatabaseSync, table: string): Set<string> {
+function tableColumns<DB>(db: DatabaseClient<DB>, table: string): Set<string> {
 	try {
 		const rows = allRows<{ name: string }>(db.prepare(`PRAGMA table_info(${table})`))
 
@@ -317,7 +316,7 @@ function tableColumns(db: DatabaseSync, table: string): Set<string> {
  * builder in particular must read the shipped population-only databases, the read-only 2026-08-05 staging database
  * (legacy conflated column), and post-split builds with one code path.
  */
-export function loadImportanceSplit(db: DatabaseSync): ImportanceSplit {
+export function loadImportanceSplit<DB>(db: DatabaseClient<DB>): ImportanceSplit {
 	const referential = new Map<number, number>()
 	const encyclopedic = new Map<number, number>()
 	const population = new Map<number, number>()

package/lib/poi/index.ts

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

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

@@ -25,13 +25,12 @@
  *   it).
  */
 
-import { DatabaseSync } from "node:sqlite"
-
 import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { gridDisk, latLngToCell } from "h3-js"
 
-import type { POICategoryCodeTable, POITable } from "./poi-schema.ts"
-import { allRows } from "./sqlite-utils.ts"
+import type { POICategoryCodeTable, POIDatabase, POITable } from "#poi/schema"
+import { allRows } from "#sqlite-utils"
 
 /**
  * Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4).
@@ -48,8 +47,9 @@ export const POI_H3_RESOLUTION = 9
  * unaffected: the loop breaks the ring it accumulates `limit` rows (cafe@Paris fills 20 by ring 2), so this ceiling
  * never enters their probe budget. Only sparse-but-present categories that never reach `limit` scan the fuller budget —
  * a cold, one-shot `mailwoman poi` path, not per-keystroke. 16 (not the bare threshold 14) leaves ~2 rings of margin so
- * the gate is stable against small db rebuilds, while staying ~4x tighter than the board's 25 km "roughly right place"
- * window (no wrong-city false positives). The browser reader passes its own smaller `maxRings` and is untouched.
+ * the radius is stable against small db rebuilds, while staying ~4x tighter than the board's 25 km "roughly right
+ * place" window (no wrong-city false positives). The browser reader passes its own smaller `maxRings` and is
+ * untouched.
  */
 const DEFAULT_MAX_RINGS = 16
 
@@ -112,7 +112,7 @@ export interface POISearchHit {
 	distanceM?: number
 }
 
-export interface POILookupOpts {
+export interface POILookupOpts<DB extends POIDatabase = POIDatabase> {
 	/**
 	 * Path to a `poi.db` built by the (future) POI builder. Opened read-only.
 	 */
@@ -120,7 +120,7 @@ export interface POILookupOpts {
 	/**
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
-	database?: DatabaseSync
+	database?: DatabaseClient<DB>
 }
 
 /**
@@ -140,36 +140,36 @@ type POIRow = Pick<
 >
 
 /**
- * Node reader over `poi.db`. `implements Disposable` so callers can `using lookup = new POILookup(...)` (or call
- * `[Symbol.dispose]()` explicitly), the same precedent as {@link WOFCandidateTableLookup} /
- * {@link WOFSQLitePlaceLookup}.
+ * Node reader over `poi.db`.
  */
-export class POILookup implements Disposable {
-	#db: DatabaseSync
-	#ownsDB: boolean
+export class POILookup<DB extends POIDatabase = POIDatabase> implements Disposable {
+	#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 #categoryToID = new Map<string, number>()
 	readonly #idToCategory = new Map<number, string>()
 
 	/**
 	 * `(h3_cell, category_id)` → the cell's category-clustered range, most-confident-first.
 	 */
-	readonly #categoryCellProbe: ReturnType<DatabaseSync["prepare"]>
+	readonly #categoryCellProbe: ReturnType<DatabaseClient["prepare"]>
 	/**
 	 * `brand_wikidata` → ALL of a brand's rows globally (partial-index range-scan); distance-sorted in JS, not SQL.
 	 */
-	readonly #brandProbe: ReturnType<DatabaseSync["prepare"]>
+	readonly #brandProbe: ReturnType<DatabaseClient["prepare"]>
 	/**
 	 * FTS5 `MATCH` over `poi_search`, returning candidate `name_key`s to hydrate.
 	 */
-	readonly #nameFTSProbe: ReturnType<DatabaseSync["prepare"]>
+	readonly #nameFTSProbe: ReturnType<DatabaseClient["prepare"]>
 
-	constructor(opts: POILookupOpts) {
+	constructor(opts: POILookupOpts<DB>) {
 		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<DB>(opts.databasePath, { readOnly: true }))
 		} else {
 			throw new Error("POILookup needs `databasePath` or `database`")
 		}
@@ -352,14 +352,8 @@ export class POILookup implements Disposable {
 		return allRows<POIRow>(stmt, ...nameKeys)
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
-	}
-
 	[Symbol.dispose](): void {
-		this.close()
+		this.#resources[Symbol.dispose]()
 	}
 }
 

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

@@ -12,12 +12,11 @@
  *   manifest (tier `shipped`, spine `h3` res 9) and per-res-6-cell coverage.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
 import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { sql, type Kysely } from "kysely"
 
-import type { NameKey } from "./street-normalize.ts"
+import type { NameKey } from "#street/normalize"
 
 /**
  * One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key.
@@ -192,7 +191,7 @@ export const POI_FTS_TABLE = "poi_search"
 /**
  * FTS5 stays raw SQL by project rule (Kysely can't express virtual tables). Content-keyed by name_key.
  */
-export function createPOISearchFTS(db: DatabaseSync): void {
+export function createPOISearchFTS<DB>(db: DatabaseClient<DB>): void {
 	db.exec(
 		`CREATE VIRTUAL TABLE ${POI_FTS_TABLE} USING fts5(name, name_key UNINDEXED, h3_cell UNINDEXED, tokenize = 'unicode61')`
 	)

package/{postal-city-alias-lookup.ts → lib/postal/city-alias-lookup.ts}

@@ -16,11 +16,9 @@
  *   uses), keeping one normalizer in one place.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
-
-import type { PostalCityAliasDatabase } from "./postal-city-alias-schema.ts"
+import type { PostalCityAliasDatabase } from "#postal/city-alias-schema"
 
 export interface WOFPostalCityAliasLookupOpts {
 	/**
@@ -30,7 +28,7 @@ export interface WOFPostalCityAliasLookupOpts {
 	/**
 	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
 	 */
-	database?: DatabaseSync
+	database?: DatabaseClient<PostalCityAliasDatabase>
 }
 
 /**
@@ -56,24 +54,22 @@ export interface PostalCityAlias {
  * differs from the geographic name — the rows that carry alias signal), issued via the typed Kysely query builder
  * against {@link PostalCityAliasDatabase}.
  */
-export class WOFPostalCityAliasLookup {
-	#db: DatabaseSync
-	#kdb: DatabaseClient<PostalCityAliasDatabase>
-	#ownsDB: boolean
+export class WOFPostalCityAliasLookup implements Disposable {
+	#db: DatabaseClient<PostalCityAliasDatabase>
+	/**
+	 * 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()
 
 	constructor(opts: WOFPostalCityAliasLookupOpts) {
 		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<PostalCityAliasDatabase>(opts.databasePath, { readOnly: true }))
 		} else {
 			throw new Error("WOFPostalCityAliasLookup needs `databasePath` or `database`")
 		}
-
-		// `#kdb` wraps `#db` for the typed query; close() owns the raw handle directly (sync).
-		this.#kdb = new DatabaseClient<PostalCityAliasDatabase>({ database: this.#db })
 	}
 
 	/**
@@ -85,7 +81,7 @@ export class WOFPostalCityAliasLookup {
 
 		if (!pc) return []
 
-		const rows = await this.#kdb
+		const rows = await this.#db
 			.selectFrom("postal_city_alias")
 			.select(["postal_city", "geo_locality", "n"])
 			.where("postcode", "=", pc)
@@ -95,9 +91,7 @@ export class WOFPostalCityAliasLookup {
 		return rows.map((r) => ({ postalCity: String(r.postal_city), geoLocality: String(r.geo_locality), n: Number(r.n) }))
 	}
 
-	close(): void {
-		if (this.#ownsDB) {
-			this.#db.close()
-		}
+	[Symbol.dispose](): void {
+		this.#resources[Symbol.dispose]()
 	}
 }

package/{postal-city-candidate-schema.ts → lib/postal/city-candidate-schema.ts}

@@ -20,7 +20,7 @@
 
 import { sql, type Kysely } from "kysely"
 
-import type { NameKey } from "./street-normalize.ts"
+import type { NameKey } from "#street/normalize"
 
 /**
  * One postal-city → geo-locality edge, keyed exactly by `(name_key, postcode)`. The probe returns the geographic
@@ -55,7 +55,7 @@ export interface PostalCityCandidateDatabase {
 }
 
 /**
- * The table name the lookup probes (existence-gated, so an old candidate.db without it is byte-stable).
+ * The table name the lookup probes (existence-restricted, so an old candidate.db without it is byte-stable).
  */
 export const POSTAL_CITY_CANDIDATE_TABLE = "postal_city_candidate"
 

package/lib/postal/index.ts

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

package/{postcode-point-lookup.ts → lib/postcode-point-lookup.ts}

@@ -4,22 +4,24 @@
  * @author Teffen Ellis, et al.
  *
  *   SQLite-backed postcode lookup for the postcode anchor (#240). A thin exact-match resolver over
- *   one or more `postalcode-*.db` shards (the `spr` schema built by `build-unified-wof --placetypes
+ *   one or more `postalcode-*.db` extracts (the `spr` schema built by `build-unified-wof --placetypes
  *   postalcode`, then centroid-backfilled by `scripts/backfill-postcode-centroids.ts`).
  *
  *   This is the production implementation of the `PostcodeResolver` interface consumed by
  *   `@mailwoman/neural`'s `extractPostcodeAnchors`. It is deliberately dumb: an indexed exact-match
- *   on the postcode string across every shard, unioned. No FTS, no ranking, no proximity — the
+ *   on the postcode string across every extract, unioned. No FTS, no ranking, no proximity — the
  *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
- *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` seam.
+ *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` interface.
  *
- *   Why multiple shards instead of the multi-shard `WOFSQLitePlaceLookup`: that resolver routes a
- *   query to ONE shard by placetype, but every postcode shard shares `placetype='postalcode'`, so a
- *   single query could only ever hit one country's shard. The anchor needs the union across
- *   countries to build its country posterior, so it queries each shard directly.
+ *   Why multiple extracts instead of the multi-extract `WOFSQLitePlaceLookup`: that resolver routes a
+ *   query to ONE extract by placetype, but every postcode extract shares `placetype='postalcode'`, so a
+ *   single query could only ever hit one country's extract. The anchor needs the union across
+ *   countries to build its country posterior, so it queries each extract directly.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import type { WOFDatabase } from "#schema"
 
 /**
  * A gazetteer hit. `lat`/`lon` of 0 means the postcode is known but has no centroid (no admin parent).
@@ -34,19 +36,19 @@ const LOOKUP_SQL =
 	"SELECT country, latitude AS lat, longitude AS lon FROM spr WHERE name = ? AND placetype = 'postalcode' AND is_current != 0"
 
 export class WOFPostcodeLookup {
-	readonly #dbs: DatabaseSync[]
-	readonly #stmts: ReturnType<DatabaseSync["prepare"]>[]
+	readonly #dbs: DatabaseClient<WOFDatabase>[]
+	readonly #stmts: ReturnType<DatabaseClient["prepare"]>[]
 
 	/**
-	 * Open each shard read-only and prepare its exact-match statement.
+	 * Open each extract read-only and prepare its exact-match statement.
 	 */
 	constructor(dbPaths: readonly string[]) {
-		this.#dbs = dbPaths.map((p) => new DatabaseSync(p, { readOnly: true }))
+		this.#dbs = dbPaths.map((p) => new DatabaseClient<WOFDatabase>(p, { readOnly: true }))
 		this.#stmts = this.#dbs.map((db) => db.prepare(LOOKUP_SQL))
 	}
 
 	/**
-	 * Exact-match the postcode across every shard and union the rows.
+	 * Exact-match the postcode across every extract and union the rows.
 	 */
 	lookup(postcode: string): PostcodePlace[] {
 		const out: PostcodePlace[] = []
@@ -60,9 +62,9 @@ export class WOFPostcodeLookup {
 		return out
 	}
 
-	close(): void {
+	[Symbol.dispose](): void {
 		for (const db of this.#dbs) {
-			db.close()
+			db.destroy()
 		}
 	}
 }