@mailwoman/resolver-wof-sqlite 10.1.0 → 10.2.0

package/lib/interpolation.ts

@@ -35,11 +35,11 @@ export interface InterpolatedHit {
 	 * True when the matched segment side's parity agrees with the house number
 	 * (or the side is `mixed`); false is an opposite-side fallback.
 	 */
-	parityMatched?: boolean
+	parityMatched: boolean | null
 	/**
 	 * `both` sits between two known neighbor numbers; `single` is extrapolated from one side only.
 	 */
-	bracket?: "both" | "single"
+	bracket: "both" | "single" | null
 	/**
 	 * Uncertainty radius in meters: half the matched segment length for `tiger_range`, half the
 	 * bracket span for `address_point`/`both`, or a larger extrapolation penalty for `single`.
@@ -140,7 +140,7 @@ export class StreetInterpolator<
 		| PreparedAll<[postcode: string, street: RouteKey, minNumber: number, maxNumber: number], SegmentRow>
 		| undefined
 	readonly #byStreet: PreparedAll<[street: RouteKey, minNumber: number, maxNumber: number], SegmentRow> | undefined
-	readonly #radiusCalibration: number | undefined
+	readonly #radiusCalibration: number | null = null
 
 	constructor(opts: { dbPath?: string; database?: DatabaseClient<DB> }) {
 		using resources = new DisposableStack()
@@ -172,7 +172,7 @@ export class StreetInterpolator<
 
 		// The conformal radius multiplier ships in the extract's `interp_calibration` table
 		// and is read once at open time.
-		// Extracts without that table leave it undefined.
+		// Extracts without that table leave it null.
 		if (hasTable(this.#db, "interp_calibration")) {
 			const row = this.#db.prepare("SELECT radius_multiplier FROM interp_calibration LIMIT 1").get() as
 				| { radius_multiplier: unknown }
@@ -190,9 +190,9 @@ export class StreetInterpolator<
 
 	/**
 	 * The artifact's own conformal radius multiplier, read from the extract at construction;
-	 * `undefined` when the extract predates the table or contains no valid row.
+	 * `null` when the extract predates the table or contains no valid row.
 	 */
-	get radiusCalibration(): number | undefined {
+	get radiusCalibration(): number | null {
 		return this.#radiusCalibration
 	}
 
@@ -268,6 +268,7 @@ export class StreetInterpolator<
 			interpolated: true,
 			method: "tiger_range",
 			parityMatched,
+			bracket: null,
 			uncertaintyM: Math.round((lengthKm * 1000) / 2),
 			source: best.source,
 			release: best.release,

package/lib/lookup.ts

@@ -65,13 +65,15 @@ export interface WOFSQLitePlaceLookupOpts {
 	/**
 	 * When true, build the FTS5 `place_search` virtual table on construction if
 	 * it is missing, on the main extract only.
-	 * Default false.
+	 *
+	 * @defaultValue `false`
 	 */
 	buildFTS?: boolean
 	/**
 	 * Geographic Rule Engine convention source, either a ready `ConventionSource`
 	 * or a `{ wofID: Convention }` seed map.
-	 * Default empty resolves every query to `WORLD_DEFAULT`.
+	 *
+	 * @defaultValue `[]`. An empty list resolves every query to `WORLD_DEFAULT`.
 	 */
 	conventions?: ConventionSource | Record<number, Convention>
 	/**
@@ -307,7 +309,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 		// The first non-null result wins and unknown strategy names are skipped.
 		const convention = this.#conventionFor(query)
 
-		let outcome: PlaceCandidate[] = []
+		let found: PlaceCandidate[] = []
 
 		for (const name of convention.candidateStrategies) {
 			const strategy = this.#strategies.get(name)
@@ -320,14 +322,14 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 
 			const result = await strategy(query, convention)
 
-			if (result !== null) {
-				outcome = result
+			if (result) {
+				found = result
 
 				break
 			}
 		}
 
-		if (outcome.length) return outcome
+		if (found.length) return found
 
 		// On a postcode-typed NL-shape miss, retry with the whitespace-joined form then the 4-digit stem,
 		// restricted to NL so the same shape elsewhere cannot coarsen to another system's code.
@@ -350,7 +352,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 			if (stem !== trimmed) return this.findPlace({ ...query, text: stem })
 		}
 
-		return outcome
+		return found
 	}
 
 	/**
@@ -478,7 +480,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 
 		const extract =
 			forceExtract ??
-			pickExtractForPlacetype(this.#extracts, firstPlacetype, {
+			pickExtractForPlacetype(this.#extracts, firstPlacetype ?? null, {
 				country: query.country,
 				countriesBySchema: this.#extractCountries,
 			})
@@ -645,7 +647,7 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 				: wofAliases
 
 			const sName = softNameScore(query.text, cand.name, aliases)
-			const sPop = populationScaleTerm(cand.population, this.#weights)
+			const sPop = populationScaleTerm(cand.population ?? null, this.#weights)
 			scored.push({ ...cand, score: w.pc * sPc + w.name * sName + w.pop * sPop, exact: sName >= 1 })
 		}
 
@@ -703,22 +705,28 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 		)
 
 		return rows.map((row) => {
-			const c: PlaceCandidate = {
+			return {
 				id: row.id,
 				name: row.name,
 				placetype: row.placetype as WOFPlacetype,
 				country: row.country ?? "",
 				lat: row.lat ?? 0,
 				lon: row.lon ?? 0,
-				parent_id: row.parent_id ?? undefined,
+				parent_id: row.parent_id ?? null,
 				score: 0,
-			}
-
-			if (row.population !== null && row.population > 0) {
-				c.population = row.population
-			}
-
-			return c
+				population: row.population !== null && row.population > 0 ? row.population : null,
+				distanceKm: null,
+				exactMatch: null,
+				prominence: null,
+				referential: null,
+				encyclopedic: null,
+				importance: null,
+				bbox: null,
+				mismatch: null,
+				containedByQualifier: null,
+				regionScopeMiss: null,
+				variantAliasExempted: null,
+			} satisfies PlaceCandidate
 		})
 	}
 
@@ -737,5 +745,3 @@ export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements P
 		}
 	}
 }
-
-export type { RankingWeights } from "#ranking-weights"

package/lib/nsul/lookup.ts

@@ -82,7 +82,7 @@ interface PointRow {
  * Disposable, so callers can `using lookup = new NSULLookup(...)`.
  */
 export class NSULLookup extends SQLiteLookup<NSULDatabase> {
-	readonly #postcodeProbe: (uprn: number) => PostcodeRow | undefined
+	readonly #postcodeProbe: (uprn: number) => PostcodeRow | null
 	readonly #pointsProbe: (pcdsCompact: string) => PointRow[]
 
 	constructor(opts: NSULLookupOpts) {

package/lib/place-importance-schema.ts

@@ -89,8 +89,8 @@ export const ENCYCLOPEDIC_BOOST_CAP = 0.25
  * (`referential` 0), and otherwise the encyclopedic score clamped between the
  * referential score and {@link ENCYCLOPEDIC_BOOST_CAP} above it.
  */
-export function blendImportance(referential: number, encyclopedic: number | null | undefined): number {
-	if (encyclopedic === null || encyclopedic === undefined) return referential
+export function blendImportance(referential: number, encyclopedic: number | null): number {
+	if (encyclopedic === null) return referential
 
 	if (referential <= 0) return encyclopedic
 
@@ -159,12 +159,12 @@ export const LEGACY_FALLBACK_EPSILON = 8 * Number.EPSILON
  * Bit equality would invent encyclopedic scores.
  */
 export function splitLegacyImportance(
-	legacy: number | undefined,
+	legacy: number | null,
 	population: number | null | undefined
 ): { referential: number; encyclopedic?: number } {
-	const referential = referentialFromPopulation(population)
+	const referential = referentialFromPopulation(population ?? null)
 
-	if (legacy === undefined) return { referential }
+	if (legacy === null) return { referential }
 
 	if (Math.abs(legacy - referential) <= LEGACY_FALLBACK_EPSILON * Math.max(referential, 1)) return { referential }
 

package/lib/poi/lookup.ts

@@ -54,23 +54,18 @@ const DEFAULT_LIMIT = 20
 
 export interface POISearchQuery {
 	/**
-	 * Poi-taxonomy category id (string side of the dictionary).
+	 * Poi-taxonomy category ids (string side of the dictionary) to search.
 	 *
-	 * Ignored when `brandWikidata` is also set, since brand wins.
-	 */
-	categoryID?: string
-	/**
-	 * Fan-out category ids that a single canonical Overture `taxonomy.primary` category
-	 * rolls up into, as in `supermarket` → `grocery_store`, `organic_grocery_store`, ….
+	 * A single category is a one-element list.
+	 * A canonical Overture `taxonomy.primary` category passes every leaf it rolls up into,
+	 * as in `supermarket` → `grocery_store`, `organic_grocery_store`, ….
 	 *
-	 * When set, the k-ring walk probes every resolvable leaf per cell and unions the rows.
+	 * The k-ring walk probes every resolvable leaf per cell and unions the rows.
 	 * Unknown leaves are skipped.
 	 *
-	 * Supersedes `categoryID` (which is treated as a one-element list `[categoryID]` when this is absent).
-	 *
 	 * Ignored when `brandWikidata` is set, since brand wins.
 	 */
-	categoryIDs?: string[]
+	categoryIDs?: readonly string[]
 	/**
 	 * Wikidata QID for brand-exact search.
 	 */
@@ -86,9 +81,11 @@ export interface POISearchQuery {
 	 */
 	center?: { latitude: number; longitude: number }
 	/**
-	 * Ring budget: how many res-9 k-rings to expand before giving up (default 16 ≈ ~5.4 km).
+	 * Ring budget: how many res-9 k-rings to expand before giving up.
 	 *
 	 * Counts ring 0, so k reaches `maxRings - 1`.
+	 *
+	 * @defaultValue `16` ≈ ~5.4 km
 	 */
 	maxRings?: number
 	limit?: number
@@ -109,7 +106,7 @@ export interface POISearchHit {
 	 * See `POITable.gers_id`.
 	 */
 	gersID: string | null
-	distanceM?: number
+	distanceM: number | null
 }
 
 /**
@@ -189,7 +186,7 @@ export class POILookup<DB extends POIDatabase = POIDatabase> extends SQLiteLooku
 			return this.#searchByName(query.name, limit, query.center)
 		}
 
-		if (query.categoryID || (query.categoryIDs && query.categoryIDs.length) || query.brandWikidata) {
+		if (query.categoryIDs?.length || query.brandWikidata) {
 			if (!query.center) {
 				throw new Error("POILookup.search: category/brand search requires a `center`")
 			}
@@ -233,12 +230,9 @@ export class POILookup<DB extends POIDatabase = POIDatabase> extends SQLiteLooku
 		const maxRings = query.maxRings ?? DEFAULT_MAX_RINGS
 		const categoryIDs: number[] = []
 
-		// `categoryIDs` (the fan-out list) supersedes the single `categoryID`.
 		// Each id resolves through the dictionary.
 		// Unresolved ids are dropped to cover Overture taxonomy drift and identity ids with no rows.
-		const seedIDs = query.categoryIDs?.length ? query.categoryIDs : query.categoryID ? [query.categoryID] : []
-
-		for (const id of seedIDs) {
+		for (const id of query.categoryIDs ?? []) {
 			const resolved = this.#categoryToID.get(id)
 
 			if (resolved !== undefined) {
@@ -369,9 +363,7 @@ function toHit(
 		country: row.country,
 		confidence: row.confidence,
 		gersID: row.gers_id,
-		...(center
-			? { distanceM: haversineKm(center.latitude, center.longitude, row.latitude, row.longitude) * 1000 }
-			: {}),
+		distanceM: center ? haversineKm(center.latitude, center.longitude, row.latitude, row.longitude) * 1000 : null,
 	}
 }
 

package/lib/postcode-point-lookup.ts

@@ -4,21 +4,12 @@
  * @author Teffen Ellis, et al.
  */
 
+import type { PostcodePlace } from "@mailwoman/core/resolver"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { PathBuilderLike } from "path-ts"
 
 import type { WOFDatabase } from "#schema"
 
-/**
- * One postcode row from the WOF gazetteer, where a `lat`/`lon` of 0 means the
- * postcode is known but has no centroid.
- */
-export interface PostcodePlace {
-	country: string
-	lat: number
-	lon: number
-}
-
 const LOOKUP_SQL =
 	"SELECT country, latitude AS lat, longitude AS lon FROM spr WHERE name = ? AND placetype = 'postalcode' AND is_current != 0"
 

package/lib/primary-preference.ts

@@ -95,7 +95,7 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 	placetypes?: ReadonlyMap<number, string>,
 	exemptVariantAliases = false
 ): Array<RankedRow<R>> {
-	let topPrimary: R | undefined
+	let topPrimary: R | null = null
 
 	for (const r of rows) {
 		if (r.is_primary === 1 && (topPrimary == null || r.neg_rank < topPrimary.neg_rank)) {
@@ -126,7 +126,7 @@ export function rankByPrimaryPreference<R extends PrimaryPreferenceRow>(
 	}
 
 	const seatPreference = (r: R): number =>
-		placetypes != null &&
+		placetypes &&
 		typeof r.placetype_id === "number" &&
 		typeof r.population === "number" &&
 		r.population > 0 &&

package/lib/proximity-rerank.ts

@@ -74,7 +74,7 @@ export interface ProximityRerankable {
 	lat: number
 	lon: number
 	score: number
-	prominence?: number
+	prominence?: number | null
 }
 
 /**

package/lib/ranking-weights.ts

@@ -47,17 +47,20 @@ export interface RankingWeights {
 	 * At `proximityScaleKm` it is half magnitude.
 	 * It decays further as distance increases.
 	 *
-	 * Default tuned so proximity can overcome a typical FTS rank tie but not dominate a strong text match.
+	 * Its default is tuned so proximity can overcome a typical FTS rank tie
+	 * but not dominate a strong text match.
 	 */
 	proximityBoost: number
 	/**
 	 * Magnitude of the bias-hint term inside the exact-tier prominence sort (the `bias`/viewport path).
 	 *
-	 * Deliberately population-scale (default = populationBoost), so a candidate near
-	 * the map view or the user beats a distant-but-bigger namesake.
+	 * Deliberately population-scale, so a candidate near the map view
+	 * or the user beats a distant-but-bigger namesake.
 	 * "The map view wins" is the feature.
 	 *
 	 * Same-region ties, where all candidates are far from every hint, still fall to population.
+	 *
+	 * @defaultValue the same value as `populationBoost`
 	 */
 	biasBoost: number
 	/**
@@ -74,23 +77,22 @@ export interface RankingWeights {
 	 * WOF records population for about 15% of localities (mostly larger ones),
 	 * and places without it get +0, never a penalty.
 	 *
-	 * Default tuned so the famous Springfield, IL (pop ~112k) gets about a 0.42 boost,
+	 * Its default is tuned so the famous Springfield, IL (pop ~112k) gets about a 0.42 boost,
 	 * enough to nudge past tiny same-name peers.
 	 */
 	populationBoost: number
 	/**
 	 * Population (in log10) at which the boost reaches its full magnitude.
 	 *
-	 * Default 6, so a population of 1,000,000 gives `populationBoost` exactly.
 	 * Larger populations cap at the same value (no compounding effect for megacities).
+	 *
+	 * @defaultValue `6`, so a population of 1,000,000 gives `populationBoost` exactly
 	 */
 	populationScaleLog10: number
 	/**
 	 * Tier candidates with an exact name/alias match above candidates that only match
 	 * partially, before the weighted-sum score is consulted.
 	 *
-	 * Default true.
-	 *
 	 * The weighted sum adds population as a large additive boost, so famous places
 	 * surface for unambiguous full-name queries.
 	 * Population is a prominence prior.
@@ -103,6 +105,8 @@ export interface RankingWeights {
 	 *
 	 * Note: tiering re-ranks within the over-fetched candidate window (`limit * 4`),
 	 * so a pathological exact match outside that window is not rescued.
+	 *
+	 * @defaultValue `true`
 	 */
 	exactMatchTiering: boolean
 	/**
@@ -116,10 +120,11 @@ export interface RankingWeights {
 	 * Fixes unscoped "Åbo" → Turku (its official Swedish name) over a hamlet literally called Åbo.
 	 * Population still orders within the sub-tier, so Paris → Paris FR is untouched.
 	 *
-	 * Default true.
 	 * It requires a gazetteer carrying the `official` ingest bit.
 	 *
 	 * On older DBs without that column, the probe fails soft and behavior matches the flag being off.
+	 *
+	 * @defaultValue `true`
 	 */
 	officialNameExact: boolean
 	/**
@@ -173,7 +178,7 @@ export const DEFAULT_WEIGHTS: RankingWeights = {
  * The coordinate-first locality path consumes this fraction directly. {@link populationBoostTerm} scales it.
  */
 export function populationScaleTerm(
-	population: number | null | undefined,
+	population: number | null,
 	weights: Pick<RankingWeights, "populationScaleLog10">
 ): number {
 	if (population == null || population <= 0 || weights.populationScaleLog10 <= 0) return 0
@@ -189,7 +194,7 @@ export function populationScaleTerm(
  * The one formula behind the Node weighted sum and the wasm re-rank, so the two backends cannot drift.
  */
 export function populationBoostTerm(
-	population: number | null | undefined,
+	population: number | null,
 	weights: Pick<RankingWeights, "populationBoost" | "populationScaleLog10">
 ): number {
 	return weights.populationBoost * populationScaleTerm(population, weights)

package/lib/region-keys.ts

@@ -107,7 +107,7 @@ function withoutSuffix(value: string, suffixes: readonly string[]): string {
  * Every expansion lands the canonical name and code folds in the set, so `IL`
  * and `Illinois`, or `WA` and `Western Australia`, meet from either side.
  */
-export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
+export function regionKeys(value: string, countryAlpha2?: string | null): Set<string> {
 	const keys = new Set([normalizeLocalityForKey(value)])
 
 	for (const stripped of [
@@ -157,7 +157,7 @@ export function regionKeys(value: string, countryAlpha2?: string): Set<string> {
  * The board has no case for this stored form.
  * Add one before building a change for this suffix.
  */
-export function regionQualifierProbeKeys(value: string, countryAlpha2?: string): Set<string> {
+export function regionQualifierProbeKeys(value: string, countryAlpha2?: string | null): Set<string> {
 	const keys = regionKeys(value, countryAlpha2)
 	// Snapshot before widening: the loop adds `county <key>` members that must not themselves be revisited.
 	const bare = [...keys]

package/lib/reverse.ts

@@ -103,19 +103,21 @@ export interface ReverseGeocodeOpts {
 	/**
 	 * Restrict the hierarchy to these placetypes (both the bbox candidates and the descent tiers).
 	 *
-	 * Default: every admin placetype in the gazetteer.
 	 * E.g.
 	 *
 	 * `["region", "county", "locality"]` to skip the neighborhood grain.
+	 *
+	 * @defaultValue every admin placetype in the gazetteer.
 	 */
 	placetypes?: WOFPlacetype[]
 	/**
 	 * Cap on the bbox candidate fetch.
 	 *
-	 * The default is 128.
 	 * Current measurements show that this covers a dense metro.
 	 *
 	 * The most bbox-overlapping point we have measured is a few dozen neighborhoods plus the admin chain.
+	 *
+	 * @defaultValue `128`
 	 */
 	maxCandidates?: number
 	/**
@@ -124,7 +126,8 @@ export interface ReverseGeocodeOpts {
 	 * This keeps a sparse gazetteer from "refining" to a far-away sibling.
 	 *
 	 * Polygon-confirmed steps ignore it (containment is exact regardless of centroid distance).
-	 * Default 25 km.
+	 *
+	 * @defaultValue `25 km`
 	 */
 	maxApproximateKm?: number
 }
@@ -160,23 +163,35 @@ interface CandidateRow {
 	lon: number
 }
 
-function toPlaceCandidate(row: CandidateRow, distanceKm?: number): PlaceCandidate {
-	const c: PlaceCandidate = {
+const ABSENT_CANDIDATE_FIELDS = {
+	parent_id: null,
+	distanceKm: null,
+	exactMatch: null,
+	prominence: null,
+	population: null,
+	referential: null,
+	encyclopedic: null,
+	importance: null,
+	bbox: null,
+	mismatch: null,
+	containedByQualifier: null,
+	regionScopeMiss: null,
+	variantAliasExempted: null,
+} as const satisfies Partial<PlaceCandidate>
+
+function toPlaceCandidate(row: CandidateRow, distanceKm: number | null = null): PlaceCandidate {
+	return {
+		...ABSENT_CANDIDATE_FIELDS,
 		id: row.id,
 		name: row.name,
 		placetype: row.placetype as WOFPlacetype,
 		country: row.country ?? "",
 		lat: row.lat,
 		lon: row.lon,
-		parent_id: row.parent_id ?? undefined,
+		parent_id: row.parent_id ?? null,
 		score: 0,
+		distanceKm,
 	}
-
-	if (distanceKm !== undefined) {
-		c.distanceKm = distanceKm
-	}
-
-	return c
 }
 
 export class WOFReverseGeocoder implements Disposable {
@@ -253,7 +268,7 @@ export class WOFReverseGeocoder implements Disposable {
 	 * The async method above exists only for call-site symmetry with `PlaceLookup.findPlace`.
 	 *
 	 * Exposed directly for callers that can't await mid-call
-	 * (e.g. `mailwoman/poi-executor.ts`'s `createPOIExecutor`, whose `POIIntentOutcome`
+	 * (e.g. `mailwoman/poi-executor.ts`'s `createPOIExecutor`, whose `POIQueryResult`
 	 * return type is synchronous by interface. See `poi-intent.ts`'s `deps.execute`).
 	 */
 	reverseGeocodeSync(lat: number, lon: number, opts: ReverseGeocodeOpts = {}): ReverseGeocodeResult {
@@ -310,7 +325,7 @@ export class WOFReverseGeocoder implements Disposable {
 		// Approximate descent into finer tiers than the winner.
 		let current = winner
 		let currentConfirmed = winnerConfirmed
-		let currentDistanceKm = currentConfirmed ? undefined : haversineKm(lat, lon, current.lat, current.lon)
+		let currentDistanceKm = currentConfirmed ? null : haversineKm(lat, lon, current.lat, current.lon)
 
 		for (const tier of DESCENT_TIERS) {
 			if (placetypeDepth(tier) <= placetypeDepth(current.placetype)) continue
@@ -319,7 +334,7 @@ export class WOFReverseGeocoder implements Disposable {
 			const kids = this.#descendants(current.id, tier, lat, lon, maxApproximateKm)
 			let next: CandidateRow | null = null
 			let nextConfirmed = false
-			let nextKm: number | undefined
+			let nextKm: number | null = null
 			let bestKm = Infinity
 
 			for (const k of kids) {
@@ -328,7 +343,7 @@ export class WOFReverseGeocoder implements Disposable {
 				if (contains === true) {
 					next = k
 					nextConfirmed = true
-					nextKm = undefined
+					nextKm = null
 
 					break
 				}
@@ -360,7 +375,13 @@ export class WOFReverseGeocoder implements Disposable {
 
 		for (const a of ancestorLineage(this.#admin, current.id)) {
 			if (!byID.has(a.id)) {
-				byID.set(a.id, { ...a, placetype: a.placetype as WOFPlacetype, country: a.country ?? "", score: 0 })
+				byID.set(a.id, {
+					...ABSENT_CANDIDATE_FIELDS,
+					...a,
+					placetype: a.placetype as WOFPlacetype,
+					country: a.country ?? "",
+					score: 0,
+				})
 			}
 		}
 
@@ -369,7 +390,13 @@ export class WOFReverseGeocoder implements Disposable {
 
 			for (const a of ancestorLineage(this.#admin, winner.id)) {
 				if (!byID.has(a.id)) {
-					byID.set(a.id, { ...a, placetype: a.placetype as WOFPlacetype, country: a.country ?? "", score: 0 })
+					byID.set(a.id, {
+						...ABSENT_CANDIDATE_FIELDS,
+						...a,
+						placetype: a.placetype as WOFPlacetype,
+						country: a.country ?? "",
+						score: 0,
+					})
 				}
 			}
 		}

package/lib/schema.ts

@@ -14,6 +14,8 @@
  *   - Per-table sources under https://github.com/whosonfirst/go-whosonfirst-sqlite-features
  */
 
+import type { KeyValueMetaTable } from "@mailwoman/sqlite/database-schema"
+
 /**
  * The FTS5 virtual table this package builds on first open.
  * It is local to this repository.
@@ -193,19 +195,8 @@ export interface CoincidentRolesTable {
  *
  * The build and augment writers adopt it so a column rename is a compile error on both sides.
  */
-/**
- * The provenance row every built extract includes: source fingerprints stored with
- * the database rather than in a document that can drift from it.
- *
- * Written by the postcode builders in `mailwoman/gazetteer-pipeline`.
- */
-export interface ExtractMetaTable {
-	key: string
-	value: string | null
-}
-
 export interface WOFDatabase {
-	meta: ExtractMetaTable
+	meta: KeyValueMetaTable
 	place_search: PlaceSearchTable
 	spr: SprTable
 	names: NamesTable

package/lib/sqlite/convention-source.ts

@@ -32,10 +32,10 @@ export class SqliteConventionSource<DB> implements ConventionSource {
 		this.#schema = schema
 	}
 
-	get(wofID: number): Convention | undefined {
+	get(wofID: number): Convention | null {
 		const cached = this.#cache.get(wofID)
 
-		if (cached !== undefined) return cached ?? undefined
+		if (cached !== undefined) return cached
 		let value: Convention | null = null
 
 		try {
@@ -52,6 +52,6 @@ export class SqliteConventionSource<DB> implements ConventionSource {
 
 		this.#cache.set(wofID, value)
 
-		return value ?? undefined
+		return value
 	}
 }

package/lib/sqlite/utils.ts

@@ -14,7 +14,7 @@ import { hasColumn as columnExists, tableExists } from "@mailwoman/sqlite/intros
  *
  * `StatementSync` accepts any `SQLInputValue[]`, which would erase tagged key types at the call site.
  */
-export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | undefined
+export type PreparedGet<Parameters extends SQLInputValue[], Row> = (...parameters: Parameters) => Row | null
 
 /**
  * Prepares a single-row query with a typed parameter tuple.

package/lib/street/centroid.ts

@@ -92,7 +92,7 @@ export class StreetCentroidSqliteLookup implements StreetCentroidLookup {
 
 		if (!streetNorm) return null
 
-		let row: AggRow | undefined
+		let row: AggRow | null = null
 
 		if (query.postcode?.trim()) {
 			row = this.#byPostcode(query.postcode.trim(), streetNorm)