@mailwoman/resolver-wof-sqlite 10.1.0 → 10.2.0

package/README.md

@@ -166,6 +166,7 @@ You can also build the index programmatically via the package's `./fts` subpath:
 
 ```ts
 import { DatabaseSync } from "node:sqlite"
+
 import { buildPlaceSearchFts } from "@mailwoman/resolver-wof-sqlite/fts"
 
 using db = new DatabaseSync("/path/to/wof.db")

package/lib/address/point/interpolation.ts

@@ -107,6 +107,8 @@ export class AddressPointInterpolator<
 		this.#resources = resources.move()
 	}
 
+	readonly radiusCalibration = null
+
 	find(query: InterpolationQuery): InterpolatedHit | null {
 		const numberRaw = query.number.trim()
 
@@ -168,8 +170,8 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 
 	// Nearest known number below and above the query.
 	// The rows never contain n itself.
-	let below: NumberAnchor | undefined
-	let above: NumberAnchor | undefined
+	let below: NumberAnchor | null = null
+	let above: NumberAnchor | null = null
 
 	for (const anchor of anchors) {
 		if (anchor.n < n) {
@@ -190,6 +192,7 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 			lon: below.lon + (above.lon - below.lon) * t,
 			interpolated: true,
 			method: "address_point",
+			parityMatched: null,
 			bracket: "both",
 			uncertaintyM: Math.round(spanM / 2),
 			source: below.source,
@@ -217,6 +220,7 @@ function interpolateFromNeighbors(rows: readonly PointRow[], n: number): Interpo
 		lon,
 		interpolated: true,
 		method: "address_point",
+		parityMatched: null,
 		bracket: "single",
 		// Explicitly larger than the both-sided radius: the whole pair span plus the overshoot.
 		uncertaintyM: Math.round(pairM + overshootM),

package/lib/address/point.ts

@@ -76,13 +76,14 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	 * @param dbPath Extract path.
 	 * @param opts.streetLocale The street-normalization locale the extract was built with.
 	 * A mismatch makes every key miss.
-	 * It defaults to `"us"`.
 	 * @param opts.localityKeys Whether the extract's `locality_norm` holds full place names.
 	 * With `"abbreviated"`, a row's locality can select a row but never rejects one.
 	 * The US situs extract uses NAD city fields.
 	 * Some counties abbreviate them (`addi` for Addison).
 	 * Other counties replace them with the parent town.
-	 * It defaults to `"abbreviated"` for `"us"` and `"full"` for every other locale.
+	 *
+	 * @defaultValue `"us"`
+	 * @defaultValue `"abbreviated"` for `"us"` and `"full"` for every other locale.
 	 */
 	constructor(
 		dbPath: PathBuilderLike,
@@ -133,7 +134,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		locality?: string
 		region?: string
 		subregion?: string
-		bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+		bbox: { minLat: number; maxLat: number; minLon: number; maxLon: number } | null
 	}): AddressPointHit | null {
 		if (!this.#byPostcode || !this.#byLocality || !this.#byBbox) return null
 		const number = normalizeHouseNumberForKey(query.number, this.#locale)
@@ -154,7 +155,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		// `streetKeyVariants` yields the literal key first.
 		// Each variant runs the full number fallback sequence.
 		// The first variant with a match wins.
-		let row: AddressPointRow | undefined
+		let row: AddressPointRow | null = null
 
 		for (const streetNorm of streetKeyVariants(query.street, streetLocaleForSurface(query.street, this.#locale))) {
 			row = this.#findForKey(streetNorm, number, scoped)
@@ -169,8 +170,8 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			lon: row.lon,
 			source: row.source,
 			release: row.release,
-			...(row.locality_norm ? { localityNorm: row.locality_norm } : {}),
-			...(row.postcode ? { postcode: row.postcode } : {}),
+			localityNorm: row.locality_norm || null,
+			postcode: row.postcode || null,
 		}
 	}
 
@@ -187,7 +188,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			postcode?: string
 			locality?: string
 			localityTail?: NameKey
-			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+			bbox: { minLat: number; maxLat: number; minLon: number; maxLon: number } | null
 		}
 	) {
 		let row = this.#probe(streetNorm, number, query)
@@ -241,22 +242,22 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			postcode?: string
 			locality?: string
 			localityTail?: NameKey
-			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+			bbox: { minLat: number; maxLat: number; minLon: number; maxLon: number } | null
 		}
-	): AddressPointRow | undefined {
-		let row: AddressPointRow | undefined
+	): AddressPointRow | null {
+		let row: AddressPointRow | null = null
 
 		if (query.postcode) {
 			const postcode = query.postcode.trim()
-			const localityKey = query.locality ? this.#localityKey(query.locality) : undefined
+			const localityKey = query.locality ? this.#localityKey(query.locality) : null
 
 			// One postcode can cover several places with the same street and number,
 			// so a row whose locality agrees with the query is tried first.
 			// The postcode-only row answers only if `#scopeContradicts` accepts it.
-			const agreeing = localityKey ? this.#byPostcodeLocality!(postcode, localityKey, streetNorm, number) : undefined
+			const agreeing = localityKey ? this.#byPostcodeLocality!(postcode, localityKey, streetNorm, number) : null
 			const candidate = agreeing ?? this.#byPostcode!(postcode, streetNorm, number)
 
-			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
+			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : null
 		}
 
 		if (!row && query.locality) {
@@ -274,7 +275,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			const candidate = this.#byBbox!(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon)
 
 			// A row with its own scope that the scoped probes missed is a different address in the same box.
-			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : undefined
+			row = candidate && !this.#scopeContradicts(candidate, query) ? candidate : null
 		}
 
 		return row

package/lib/build/candidate.ts

@@ -5,7 +5,7 @@
  */
 
 import { COUNTRY_POPULATION } from "@mailwoman/codex/country"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { removePath } from "@mailwoman/core/fs/writers"
 import { stringifyJSON } from "@mailwoman/core/json"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
@@ -32,19 +32,6 @@ import { resurrectCurrencyHoles } from "#currency-backfill"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
-/**
- * Re-exports the country display-name staging pass from the candidate build's public module.
- */
-export { stageCountryDisplayNames } from "#candidate/country-display-names"
-/**
- * Re-exports the gloss detector's excluded placetypes and default key-count threshold.
- */
-export { GLOSS_EXCLUDED_PLACETYPES, GLOSS_KEY_THRESHOLD } from "#candidate/name-roles"
-/**
- * Re-exports the per-place record that every candidate staging pass writes its rows from.
- */
-export type { PlaceAttrs } from "#candidate/place-attrs"
-
 /**
  * Options for {@link buildCandidateTable}.
  */
@@ -111,7 +98,8 @@ export interface BuildCandidateOptions {
 
 		/**
 		 * The deprecated placetypes eligible for restoration.
-		 * The default is `locality`.
+		 *
+		 * @defaultValue `locality`
 		 */
 		deadPlacetypes?: readonly string[]
 	}
@@ -123,9 +111,10 @@ export interface BuildCandidateOptions {
 
 	/**
 	 * The key-count threshold for the gloss anomaly detector.
-	 * The default is {@link GLOSS_KEY_THRESHOLD}.
 	 *
 	 * Tests override it with a value sized for fixtures.
+	 *
+	 * @defaultValue {@linkcode GLOSS_KEY_THRESHOLD}
 	 */
 	glossKeyThreshold?: number
 }
@@ -178,9 +167,9 @@ export interface BuildCandidateResult {
 	/**
 	 * The count of places that received an `importance` score.
 	 *
-	 * It is `undefined` when no score source was given.
+	 * It is `null` when no score source was given.
 	 */
-	importanceScored?: number
+	importanceScored: number | null
 
 	/**
 	 * The count of places that matched a scored group by name key, country and placetype
@@ -188,7 +177,7 @@ export interface BuildCandidateResult {
 	 *
 	 * A large change between rebuilds means the score source and the admin source have diverged.
 	 */
-	importanceFiltered?: number
+	importanceFiltered: number | null
 
 	/**
 	 * The count of alias rows the gloss anomaly detector stamped `name_role = 'gloss'`.
@@ -257,7 +246,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		return id
 	}
 
-	let importance: ReturnType<typeof loadImportanceIndex> | undefined
+	let importance: ReturnType<typeof loadImportanceIndex> | null = null
 
 	if (opts.importance) {
 		progress("importance", `loading place_importance from ${opts.importance}`)
@@ -603,6 +592,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		ancestorPlaces: sidecar.ancestorPlaces + nLocalityScoped,
 		intervalPlaces: sidecar.intervalPlaces,
 		...roles,
-		...(importance ? { importanceScored: importance.matched, importanceFiltered: importance.refused } : {}),
+		importanceScored: importance ? importance.matched : null,
+		importanceFiltered: importance ? importance.refused : null,
 	}
 }

package/lib/build/slim.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { temporaryDirectory } from "@mailwoman/core/fs/temporary"
 import { copyFileTo, removePath } from "@mailwoman/core/fs/writers"
 import { stringifyJSON } from "@mailwoman/core/json"

package/lib/candidate/importance.ts

@@ -140,7 +140,7 @@ export class ImportanceIndex {
 
 		if (!group) return null
 
-		let best: ScoredPlace | undefined
+		let best: ScoredPlace | null = null
 		let bestKm = Infinity
 
 		for (const place of group) {

package/lib/candidate/lookup.ts

@@ -5,6 +5,7 @@
  */
 
 import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
+import type { VariantAliasExemption } from "@mailwoman/core/geocode"
 import { type Ancestor, type GazetteerArtifactCoverage, referentialFromPopulation } from "@mailwoman/core/resolver"
 import { allRows } from "@mailwoman/core/utils"
 import { jaroWinkler, levenshteinSimilarity } from "@mailwoman/match/comparators"
@@ -31,9 +32,6 @@ import { hasColumn, hasTable } from "#sqlite-utils"
 import { type NameKey, normalizeLocalityForKey, stripLocalityQualifier } from "#street/normalize"
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "#types"
 
-export { rankByPrimaryPreference } from "#primary-preference"
-export type { RankedRow } from "#primary-preference"
-
 /**
  * Where a {@link WOFCandidateTableLookup} reads from
  * (a read-only `candidate.db` or a caller-held connection) and how it ranks.
@@ -41,9 +39,13 @@ export type { RankedRow } from "#primary-preference"
 export interface WOFCandidateTableLookupOpts extends SQLiteLookupOptions<CandidateDatabase> {
 	/**
 	 * Exempt `name_role = 'variant'` aliases from the cross-country primary-preference penalty.
-	 * No-ops without the role column and is off by default.
+	 *
+	 * - No-ops without the role column.
+	 * - `"not_applied"` penalizes variant aliases like any other.
+	 *
+	 * @defaultValue `"applied"`.
 	 */
-	variantAliasExemption?: boolean
+	variantAliasExemption?: VariantAliasExemption
 }
 
 type CandidateRow = Pick<
@@ -106,7 +108,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 	 */
 	readonly #nameKeyExistsProbe: ReturnType<DatabaseClient["prepare"]> | undefined
 
-	readonly artifactCoverage: GazetteerArtifactCoverage | undefined
+	readonly artifactCoverage: GazetteerArtifactCoverage | null
 
 	readonly #importanceSelect: string
 
@@ -158,7 +160,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		// Optional columns are detected once here for hot-path reads.
 		this.#importanceSelect = hasColumn(this.database, "candidate", "importance") ? ", importance" : ""
 		this.#hasNameRole = hasColumn(this.database, "candidate", "name_role")
-		this.#variantAliasExemption = opts.variantAliasExemption === true
+		this.#variantAliasExemption = (opts.variantAliasExemption ?? "applied") === "applied"
 		this.#roleSelect = this.#hasNameRole ? ", name_role" : ""
 
 		if (hasTable(this.database, CANDIDATE_ANCESTOR_TABLE)) {
@@ -227,7 +229,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		return label
 	}
 
-	#qualifierRegionIDs(qualifier: string, country: string | undefined): Set<number> {
+	#qualifierRegionIDs(qualifier: string, country: string | null): Set<number> {
 		const ids = new Set<number>()
 
 		if (!this.#qualifierProbe) return ids
@@ -264,7 +266,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 	#applyAdminContainment(
 		rows: Array<RankedRow<CandidateRow>>,
 		qualifier: string,
-		country: string | undefined,
+		country: string | null,
 		opts: {
 			nameKey: NameKey
 			strippedKey: NameKey
@@ -425,8 +427,20 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 						country: query.country?.toUpperCase() ?? "",
 						lat: Number(hit.latitude),
 						lon: Number(hit.longitude),
+						parent_id: null,
 						score: 1,
+						distanceKm: null,
 						exactMatch: true,
+						prominence: null,
+						population: null,
+						referential: null,
+						encyclopedic: null,
+						importance: null,
+						bbox: null,
+						mismatch: null,
+						containedByQualifier: null,
+						regionScopeMiss: null,
+						variantAliasExempted: null,
 					},
 				]
 			}
@@ -482,13 +496,13 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		filterParams.push(...shapeParams)
 
 		// Region scope is optional (`region_id = parentID`); the fallback stays unscoped.
-		const regionParentID = query.parentID || undefined
+		const regionParentID = query.parentID || null
 
-		const probe = (nk: string, regionID: number | undefined, countryID?: number): Array<RankedRow<CandidateRow>> => {
+		const probe = (nk: string, regionID: number | null, countryID?: number): Array<RankedRow<CandidateRow>> => {
 			const conds = ["name_key = ?", ...filters]
 			const params: Array<string | number> = [nk, ...filterParams]
 
-			if (regionID !== undefined) {
+			if (regionID !== null) {
 				conds.push("region_id = ?")
 				params.push(regionID)
 			}
@@ -508,7 +522,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 			return rankByPrimaryPreference(fetched, limit, undefined, this.#idToPlacetype, this.#variantAliasExemption)
 		}
 
-		const cascade = (regionID: number | undefined): Array<RankedRow<CandidateRow>> => {
+		const cascade = (regionID: number | null): Array<RankedRow<CandidateRow>> => {
 			let rows = probe(nameKey, regionID)
 
 			if (!rows.length) {
@@ -567,8 +581,8 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 		let regionScopeMiss = false
 
-		if (!rows.length && regionParentID !== undefined) {
-			rows = cascade(undefined)
+		if (!rows.length && regionParentID !== null) {
+			rows = cascade(null)
 			regionScopeMiss = rows.length > 0
 		}
 
@@ -604,7 +618,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 
 		// Admin-containment re-rank runs last.
 		if (query.regionQualifier?.trim() && this.#qualifierProbe && this.#wantsLocality(query.placetype)) {
-			rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country, {
+			rows = this.#applyAdminContainment(rows, query.regionQualifier.trim(), query.country ?? null, {
 				nameKey,
 				strippedKey: normalizeLocalityForKey(stripLocalityQualifier(text)),
 				shapeFilters,
@@ -616,6 +630,7 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 		const candidates = rows.map((row): PlaceCandidate => {
 			const hasBbox = row.min_lat != null && row.max_lat != null && row.min_lon != null && row.max_lon != null
 			const parent = this.#ancestorLineage(Number(row.spr_id))[0]
+			const hasPopulation = row.population !== null && row.population > 0
 
 			return {
 				id: Number(row.spr_id),
@@ -626,37 +641,35 @@ export class WOFCandidateTableLookup extends SQLiteLookup<CandidateDatabase> imp
 				lat: Number(row.latitude),
 				lon: Number(row.longitude),
 
-				...(parent ? { parent_id: Number(parent.id) } : {}),
+				parent_id: parent ? Number(parent.id) : null,
 
 				score: -Number(row.neg_rank),
+				distanceKm: null,
 
 				prominence: -Number(row.effectiveNegRank),
 
 				exactMatch: !row.demoted && !row.fuzzy,
 
-				...(regionScopeMiss ? { regionScopeMiss: true } : {}),
+				regionScopeMiss: regionScopeMiss ? true : null,
 
-				...(row.containedByQualifier === undefined ? {} : { containedByQualifier: row.containedByQualifier }),
+				containedByQualifier: row.containedByQualifier ?? null,
 
-				...(row.variantExempted ? { variantAliasExempted: true as const } : {}),
+				variantAliasExempted: row.variantExempted ? true : null,
 
-				...(row.population === null || row.population <= 0
-					? {}
-					: { population: row.population, referential: referentialFromPopulation(row.population) }),
+				population: hasPopulation ? row.population : null,
+				referential: hasPopulation ? referentialFromPopulation(row.population) : null,
+				encyclopedic: null,
 
-				...(typeof row.importance === "number" && Number.isFinite(row.importance)
-					? { importance: row.importance }
-					: {}),
-				...(hasBbox
+				importance: typeof row.importance === "number" && Number.isFinite(row.importance) ? row.importance : null,
+				bbox: hasBbox
 					? {
-							bbox: {
-								minLat: Number(row.min_lat),
-								maxLat: Number(row.max_lat),
-								minLon: Number(row.min_lon),
-								maxLon: Number(row.max_lon),
-							},
+							minLat: Number(row.min_lat),
+							maxLat: Number(row.max_lat),
+							minLon: Number(row.min_lon),
+							maxLon: Number(row.max_lon),
 						}
-					: {}),
+					: null,
+				mismatch: null,
 			}
 		})
 

package/lib/candidate/own-name.ts

@@ -135,7 +135,7 @@ export function ownNameSimilarity(primaryKey: string, aliasKey: string): number
 	const primary = romanizeNameKey(primaryKey)
 	const alias = romanizeNameKey(aliasKey)
 
-	if (primary == null || alias == null || !primary || !alias) return null
+	if (!primary || !alias || !primary || !alias) return null
 
 	return levenshteinSimilarity(expandNameAbbreviations(primary), expandNameAbbreviations(alias))
 }

package/lib/candidate/scoring.ts

@@ -56,7 +56,7 @@ export function candidateFromSearchRow(
 
 	// Proximity boost applies only when the query includes `near` and the candidate has real coordinates.
 	// The decay is tunable via proximityBoost + proximityScaleKm.
-	let distanceKm: number | undefined
+	let distanceKm: number | null = null
 	// The best decayed-distance term over `near` and every `bias` point wins, each scaled by its weight.
 	let proximityTerm = 0
 
@@ -96,6 +96,14 @@ export function candidateFromSearchRow(
 	// additive units, so hints can win a cross-country postcode tie without a hard filter.
 	const prominence = popTerm + proximityTerm
 
+	const population = row.population !== null && row.population > 0 ? row.population : null
+
+	// The referential key derives from this row's population and no other field,
+	// so it cannot drift from the ordering.
+	// Consumers read the encyclopedic value.
+	// No ranking site reads it.
+	// The bbox gives parity with the wasm lookup.
+	// Without it the region→bbox constraint is dead and disambiguation falls to population ranking.
 	const candidate: PlaceCandidate = {
 		id: row.id,
 		prominence,
@@ -104,35 +112,27 @@ export function candidateFromSearchRow(
 		country: row.country ?? "",
 		lat: row.lat ?? 0,
 		lon: row.lon ?? 0,
-		parent_id: row.parent_id ?? undefined,
+		parent_id: row.parent_id ?? null,
 		score,
-	}
-
-	if (distanceKm !== undefined) {
-		candidate.distanceKm = distanceKm
-	}
-
-	if (row.population !== null && row.population > 0) {
-		candidate.population = row.population
-		// The referential ranking key is derived as a pure function of this row's population,
-		// so it cannot drift from the ordering.
-		candidate.referential = referentialFromPopulation(row.population)
-	}
-
-	// Returned for consumers (annotations / API surfaces); no ranking site reads it.
-	if (row.encyclopedic !== null) {
-		candidate.encyclopedic = row.encyclopedic
-	}
-
-	// Candidate bbox for parity with the wasm lookup. Without it the Node backend's
-	// region→bbox constraint is dead and disambiguation falls to population ranking.
-	if (row.min_latitude != null && row.max_latitude != null && row.min_longitude != null && row.max_longitude != null) {
-		candidate.bbox = {
-			minLat: row.min_latitude,
-			maxLat: row.max_latitude,
-			minLon: row.min_longitude,
-			maxLon: row.max_longitude,
-		}
+		distanceKm,
+		exactMatch: null,
+		population,
+		referential: population === null ? null : referentialFromPopulation(population),
+		encyclopedic: row.encyclopedic ?? null,
+		importance: null,
+		bbox:
+			row.min_latitude != null && row.max_latitude != null && row.min_longitude != null && row.max_longitude != null
+				? {
+						minLat: row.min_latitude,
+						maxLat: row.max_latitude,
+						minLon: row.min_longitude,
+						maxLon: row.max_longitude,
+					}
+				: null,
+		mismatch: null,
+		containedByQualifier: null,
+		regionScopeMiss: null,
+		variantAliasExempted: null,
 	}
 
 	return candidate

package/lib/capitals.ts

@@ -108,9 +108,9 @@ export class CapitalIndex {
 	 * an unknown country, or no matching entry.
 	 */
 	levelOfPlace(
-		name: string | null | undefined,
-		country: string | null | undefined,
-		latitude: number | null | undefined,
+		name: string | null,
+		country: string | null,
+		latitude: number | null,
 		longitude: number | null | undefined
 	): CapitalLevel {
 		if (!name || !country || typeof latitude !== "number" || typeof longitude !== "number") return CAPITAL_LEVEL.none

package/lib/coincident-roles.ts

@@ -66,25 +66,25 @@ export interface BuildCoincidentRolesOpts {
 	/**
 	 * Drop + rebuild the table if it already exists.
 	 *
-	 * Default true (the build is cheap + idempotent).
+	 * @defaultValue `true` (the build is cheap + idempotent)
 	 */
 	drop?: boolean
 	/**
 	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`.
 	 *
-	 * Default 0.15.
+	 * @defaultValue `0.15`
 	 */
 	toleranceFraction?: number
 	/**
 	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify.
 	 *
-	 * Default 12.
+	 * @defaultValue `12`
 	 */
 	minToleranceKm?: number
 	/**
 	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
 	 *
-	 * Default 2.
+	 * @defaultValue `2`
 	 */
 	cityStateMaxKm?: number
 	onProgress?: (phase: string, detail?: string) => void
@@ -320,6 +320,17 @@ export function loadCoincidentLocalities<DB>(db: DatabaseClient<DB>): Map<number
 				relationshipType: r.relationshipType,
 				population: r.population,
 				distanceKm: r.distanceKm,
+				parent_id: null,
+				prominence: null,
+				referential: null,
+				encyclopedic: null,
+				importance: null,
+				exactMatch: null,
+				mismatch: null,
+				resolutionQuality: null,
+				containedByQualifier: null,
+				regionScopeMiss: null,
+				variantAliasExempted: null,
 			}
 
 			const list = map.get(r.adminID)

package/lib/convention/schema.ts

@@ -9,6 +9,7 @@
  *   other.
  */
 
+import type { KeyValueMetaTable } from "@mailwoman/sqlite/database-schema"
 import type { Kysely } from "kysely"
 
 import { ADDRESS_CONVENTION_TABLE } from "#convention"
@@ -30,17 +31,9 @@ export interface AddressConventionTable {
 	source: string
 }
 
-/**
- * Key/value provenance for the sealed artifact.
- */
-export interface ConventionMetaTable {
-	key: string
-	value: string | null
-}
-
 export interface ConventionDatabase {
 	address_convention: AddressConventionTable
-	meta: ConventionMetaTable
+	meta: KeyValueMetaTable
 }
 
 /**

package/lib/convention.ts

@@ -79,10 +79,10 @@ export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) =
 
 /**
  * Looks up a convention by WOF polygon id.
- * `get` returns `undefined` when the polygon has no override.
+ * `get` returns `null` when the polygon has no override.
  */
 export interface ConventionSource {
-	get(wofID: number): Convention | undefined
+	get(wofID: number): Convention | null
 }
 
 /**
@@ -95,8 +95,8 @@ export class SeedConventionSource implements ConventionSource {
 		this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]))
 	}
 
-	get(wofID: number): Convention | undefined {
-		return this.#rows.get(wofID)
+	get(wofID: number): Convention | null {
+		return this.#rows.get(wofID) ?? null
 	}
 }
 
@@ -106,7 +106,7 @@ export class SeedConventionSource implements ConventionSource {
  * A layer's `candidateStrategies` replaces the whole list.
  * `scoringWeights` merges key by key, so a layer can change one weight without restating the others.
  */
-export function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention {
+export function mergeConventions(base: Convention, ...overrides: Array<Convention | null | undefined>): Convention {
 	const out: Convention = {
 		candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
 		scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
@@ -115,11 +115,11 @@ export function mergeConventions(base: Convention, ...overrides: Array<Conventio
 	for (const o of overrides) {
 		if (!o) continue
 
-		if (o.candidateStrategies !== undefined) {
+		if (o.candidateStrategies) {
 			out.candidateStrategies = [...o.candidateStrategies]
 		}
 
-		if (o.scoringWeights !== undefined) {
+		if (o.scoringWeights) {
 			out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights }
 		}
 	}