@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/coincident-roles.ts

@@ -3,39 +3,37 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
- *   unified gazetteer.
+ *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
  *
- *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
- *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
- *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
- *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
- *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
- *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
- *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
- *   distance math.
+ *   Many places occupy multiple admin tiers under one name: German city-states (Berlin, Hamburg,
+ *   Bremen), Italian provinces whose names match their capital (Milano, Varese), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals (Utrecht,
+ *   Groningen), and Shanghai. When an address surfaces only the admin role because the parser
+ *   dropped the locality span, the resolver has no locality to place. The hierarchy-completion step
+ *   consults this relation. The table preserves the gazetteer's own structure, so the runtime is an
+ *   O(1) membership lookup with no distance math.
  *
- *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
- *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
- *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
- *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
- *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
- *   filter.
+ *   V1 is region-tier only (admin.placetype = `region`), the ~124 places matching the census across
+ *   nine countries. County-tier same-name coincidences are excluded because they are dominated by
+ *   French cantons and JP counties, admin subdivisions whose names match a seat town that do not hit the
+ *   parser-drops-locality failure. Consolidated city-counties (US SF, Denver) are a separate
+ *   follow-up needing a relative-size filter.
  *
- *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
- *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
- *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
- *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
- *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
- *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
- *   never enters the resolver hot path.
+ *   A pair `(admin, locality)` is recorded when the names match case-insensitively, the locality descends from the admin in `ancestors`,
+ *   and their centroids fall within a
+ *   relative tolerance of `toleranceFraction × admin-bbox-diagonal`, floored at `minToleranceKm`.
+ *   The relative term lets a large Italian province admit a city tens of km from its centroid while
+ *   a tiny city-state stays tight. The floor catches city-states whose bbox is small (Bremen's
+ *   centroids sit 9.3 km apart). The tolerance lives only here at build time and never enters the
+ *   resolver hot path.
  *
- *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
- *   uniform (see #405). It's a coarse classification, not critical.
+ *   `relationship_type` is recorded for debuggability and deferred per-type behavior. V1 completion
+ *   is uniform. It is a coarse classification.
  *
- *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). Run incrementally
- *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
- *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ *   This mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). It runs
+ *   incrementally against an existing `admin-global-priority.db` via
+ *   `build-coincident-roles-cli.ts`, and it should also be wired as a post-step of the main
+ *   `scripts/build-unified-wof.ts`.
  */
 
 import type { CoincidentLocality } from "@mailwoman/core/resolver"
@@ -46,13 +44,15 @@ import { tableExists } from "@mailwoman/sqlite/introspection"
 
 import type { WOFDatabase } from "#schema"
 /**
- * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
- * gazetteer build, read by the resolver when a coincident locality has to be chosen.
+ * Table of places that hold more than one admin role.
+ * A locality that is also its county seat.
+ *
+ * Written by the gazetteer build, read by the resolver when a coincident locality has to be chosen.
  */
 export const COINCIDENT_ROLES_TABLE = "coincident_roles"
 
 /**
- * A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`.
+ * A place that plays multiple admin roles, one row of the relation keyed by `admin_id`.
  */
 export interface CoincidentRole {
 	localityID: number
@@ -64,19 +64,27 @@ export interface CoincidentRole {
 
 export interface BuildCoincidentRolesOpts {
 	/**
-	 * Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent).
+	 * Drop + rebuild the table if it already exists.
+	 *
+	 * @defaultValue `true` (the build is cheap + idempotent)
 	 */
 	drop?: boolean
 	/**
-	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`. Default 0.15.
+	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`.
+	 *
+	 * @defaultValue `0.15`
 	 */
 	toleranceFraction?: number
 	/**
-	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12.
+	 * Floor (km) under the relative tolerance, so small-bbox city-states still qualify.
+	 *
+	 * @defaultValue `12`
 	 */
 	minToleranceKm?: number
 	/**
-	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only). Default 2.
+	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
+	 *
+	 * @defaultValue `2`
 	 */
 	cityStateMaxKm?: number
 	onProgress?: (phase: string, detail?: string) => void
@@ -106,8 +114,11 @@ interface CandidateRow {
 }
 
 /**
- * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
- * touches `spr`/`names`/`ancestors`. Idempotent.
+ * Derive the coincident-roles relation into `db`.
+ *
+ * Additive, only creating or replacing the `coincident_roles` table.
+ * It never touches `spr`, `names`, or `ancestors`.
+ * Idempotent.
  */
 export function buildCoincidentRoles(
 	db: DatabaseClient<WOFDatabase>,
@@ -127,10 +138,9 @@ export function buildCoincidentRoles(
 
 	onProgress("creating", COINCIDENT_ROLES_TABLE)
 
-	// Raw DDL by design: this is a sync builder consumed by a sync CLI (build-coincident-roles-cli) and
-	// 6 sync unit tests, so routing one table through async Kysely would cascade async through all of
-	// them for no real gain. See AGENTS.md "Database / inline SQL". (The SELECT + INSERT loop below are
-	// likewise the raw hot path.)
+	// Raw DDL by design: this is a sync builder consumed by a sync CLI and six sync unit tests,
+	// so routing one table through async Kysely would cascade async through all of them.
+	// See agents.md "Database / inline SQL".
 	db.exec(`
 		CREATE TABLE IF NOT EXISTS ${COINCIDENT_ROLES_TABLE} (
 			admin_id INTEGER NOT NULL,
@@ -145,9 +155,11 @@ export function buildCoincidentRoles(
 
 	onProgress("scanning")
 
-	// Admin (region/county tier) ⋈ same-name DESCENDANT locality. `place_population` is optional (LEFT
-	// JOIN → 0 when absent). The relative-tolerance filter + relationship classification happen in JS so
-	// the SQL stays a plain join. `spr` exposes the bbox columns we need for the diagonal.
+	// Admin (region or county tier) joined to a same-name descendant locality.
+	// `place_population` is optional, so the left join yields 0 when absent.
+	// JavaScript applies the relative-tolerance filter and classifies the relationship.
+	// SQL stays a plain join.
+	// `spr` exposes the bbox columns needed for the diagonal.
 	const candidates = allRows<CandidateRow>(
 		db.prepare(
 			`SELECT r.id AS admin_id, r.placetype AS admin_placetype, r.country AS country, l.id AS locality_id,
@@ -183,11 +195,12 @@ export function buildCoincidentRoles(
 			const tolerance = Math.max(toleranceFraction * diag, minToleranceKm)
 
 			if (dist > tolerance) continue
-			// v1 is region-tier only: a place is a `city-state` when its centroid coincides with the
-			// region's (Berlin/Hamburg), else `capital-seat` (a region named after its principal city, e.g.
-			// Milano province → Milano comune). `consolidated-county` is reserved for a future county-tier
-			// pass (US SF/Denver) — excluded from v1 because county-tier same-name coincidences are
-			// dominated by French cantons / JP counties that don't hit the parser-drops-locality failure.
+			// v1 is region-tier only: a place is `city-state` when its centroid coincides with the
+			// region's (Berlin, Hamburg), otherwise `capital-seat` (a region whose name matches its
+			// principal city, such as Milano province and Milano comune). `consolidated-county` is
+			// reserved for a future county-tier pass (US SF, Denver), excluded from v1 because
+			// county-tier same-name coincidences are dominated by French cantons and JP counties
+			// that do not hit the parser-drops-locality failure.
 			const relationshipType = dist <= cityStateMaxKm ? "city-state" : "capital-seat"
 			insert.run(c.admin_id, c.locality_id, relationshipType, c.admin_placetype, dist, c.pop)
 
@@ -209,16 +222,20 @@ export function buildCoincidentRoles(
 }
 
 /**
- * True iff the relation table exists. Used by the resolver to decide whether completion can run.
+ * True iff the relation table exists.
+ *
+ * Used by the resolver to decide whether completion can run.
  */
 export function coincidentRolesExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, COINCIDENT_ROLES_TABLE)
 }
 
 /**
- * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each admin may map to
- * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
- * map when the table is absent.
+ * Load the relation into an in-memory map keyed by `admin_id` for an O(1) runtime lookup.
+ *
+ * Each admin may map to multiple same-name descendants.
+ * The consumer disambiguates by minimum distance, then population, then abstains.
+ * Returns an empty map when the table is absent.
  */
 export function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, CoincidentRole[]> {
 	const map = new Map<number, CoincidentRole[]>()
@@ -261,8 +278,10 @@ export function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, Coi
 }
 
 /**
- * The relation joined with `spr`, as an in-memory map keyed by `admin_id` — the resolver-facing view of
- * {@link loadCoincidentRoles}, carrying the canonical name and coordinates each coincident locality resolves to.
+ * The relation joined with `spr`, as an in-memory map keyed by `admin_id`.
+ *
+ * The resolver-facing view of {@link loadCoincidentRoles}, carrying the canonical name
+ * and coordinates each coincident locality resolves to.
  * Returns an empty map when the relation table is absent.
  */
 export function loadCoincidentLocalities<DB>(db: DatabaseClient<DB>): Map<number, CoincidentLocality[]> {
@@ -301,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

@@ -4,14 +4,15 @@
  * @author Teffen Ellis, et al.
  *
  *   Typed schema for the convention asset — the `address_convention` table `SqliteConventionSource` probes, plus the
- *   `meta` provenance row every sealed artifact here carries. The interface is the read/write contract and
+ *   `meta` provenance row every sealed artifact here includes. The interface is the read/write interface and
  *   {@link createAddressConventionTable} creates the table, so a column added to one is a compile error against the
  *   other.
  */
 
+import type { KeyValueMetaTable } from "@mailwoman/sqlite/database-schema"
 import type { Kysely } from "kysely"
 
-import { ADDRESS_CONVENTION_TABLE } from "#convention/index"
+import { ADDRESS_CONVENTION_TABLE } from "#convention"
 
 /**
  * One convention profile, keyed by the WOF admin polygon it attaches to.
@@ -19,7 +20,9 @@ import { ADDRESS_CONVENTION_TABLE } from "#convention/index"
 export interface AddressConventionTable {
 	wof_id: number
 	/**
-	 * The `Convention` record, JSON-encoded. Parsed at read time by `SqliteConventionSource`.
+	 * The `Convention` record, JSON-encoded.
+	 *
+	 * Parsed at read time by `SqliteConventionSource`.
 	 */
 	convention: string
 	/**
@@ -28,28 +31,24 @@ 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
 }
 
 /**
- * The slice of a Kysely handle the convention DDL touches. Kysely is invariant in its schema parameter, so naming only
- * `schema` lets a builder holding a wider handle pass it without a cast.
+ * The subset of a Kysely handle the convention DDL touches.
+ *
+ * Kysely is invariant in its schema parameter, so naming only `schema` lets a
+ * builder holding a wider handle pass it without a cast.
  */
 export type ConventionSchemaHandle = Pick<Kysely<ConventionDatabase>, "schema">
 
 /**
- * Create `address_convention`. The table name comes from {@link ADDRESS_CONVENTION_TABLE} so the build script, the
- * runtime source, and the extract auto-detect cannot drift apart.
+ * Create `address_convention`.
+ *
+ * The table name comes from {@link ADDRESS_CONVENTION_TABLE} so the build script, the runtime source.
+ * The extract auto-detect stays aligned with it.
  */
 export async function createAddressConventionTable(db: ConventionSchemaHandle): Promise<void> {
 	await db.schema

package/lib/convention.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Defines resolution conventions as per-polygon profiles merged along a place's ancestor chain.
+ *
+ *   The strategy implementations live in `lookup.ts` and are registered by name.
+ */
+
+import type { FindPlaceQuery, PlaceCandidate } from "#types"
+
+/**
+ * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
+ */
+export interface ScoringWeights {
+	pc: number
+	name: number
+	pop: number
+}
+
+/**
+ * A resolution profile attached to a Who's On First admin polygon.
+ */
+export interface Convention {
+	/**
+	 * The strategies that the dispatcher runs in order, by registered name.
+	 * The first strategy that returns a non-null result wins.
+	 */
+	candidateStrategies?: string[]
+	/**
+	 * Weights for the `postcode_area_resolution` soft score.
+	 *
+	 * A layer may set some weights and inherit the rest from the layers below it.
+	 */
+	scoringWeights?: Partial<ScoringWeights>
+}
+
+/**
+ * A convention with every field set, as `resolveConvention` returns it to strategies.
+ */
+export interface ResolvedConvention {
+	candidateStrategies: string[]
+	scoringWeights: ScoringWeights
+}
+
+/**
+ * The base layer that every ancestor chain starts from.
+ *
+ * It tries `postcode_area_resolution` and then falls back to fuzzy name matching.
+ * Every place without a convention override uses these values, so a change here
+ * changes resolution in every such country.
+ */
+export const WORLD_DEFAULT: ResolvedConvention = {
+	candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
+	scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
+}
+
+/**
+ * The names of the strategies that the backend registers.
+ *
+ * The dispatch registry and the build-time validator share this list, so the build
+ * rejects a convention that lists an unknown strategy.
+ */
+export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
+
+/**
+ * The table name for the convention asset, shared by the build script,
+ * the runtime source and extract detection.
+ */
+export const ADDRESS_CONVENTION_TABLE = "address_convention"
+
+/**
+ * A resolution strategy selected by name.
+ *
+ * @returns `null` to abstain, so the dispatcher tries the next strategy,
+ * or an array, possibly empty, to claim the result.
+ */
+export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>
+
+/**
+ * Looks up a convention by WOF polygon id.
+ * `get` returns `null` when the polygon has no override.
+ */
+export interface ConventionSource {
+	get(wofID: number): Convention | null
+}
+
+/**
+ * An in-memory convention source built from a `{ wofID: Convention }` map.
+ */
+export class SeedConventionSource implements ConventionSource {
+	readonly #rows: Map<number, Convention>
+
+	constructor(rows: Record<number, Convention> = {}) {
+		this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]))
+	}
+
+	get(wofID: number): Convention | null {
+		return this.#rows.get(wofID) ?? null
+	}
+}
+
+/**
+ * Merges convention layers, with later, more specific layers winning per field.
+ *
+ * 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 | null | undefined>): Convention {
+	const out: Convention = {
+		candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
+		scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
+	}
+
+	for (const o of overrides) {
+		if (!o) continue
+
+		if (o.candidateStrategies) {
+			out.candidateStrategies = [...o.candidateStrategies]
+		}
+
+		if (o.scoringWeights) {
+			out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights }
+		}
+	}
+
+	return out
+}
+
+/**
+ * Resolves the effective convention for a place from its ancestor ids,
+ * ordered from most general to most specific.
+ *
+ * The merge starts from `WORLD_DEFAULT`, so every field is defined.
+ */
+export function resolveConvention(source: ConventionSource, ancestorIDs: readonly number[]): ResolvedConvention {
+	const layers = ancestorIDs.map((id) => source.get(id))
+	const merged = mergeConventions(WORLD_DEFAULT, ...layers)
+
+	return {
+		candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
+		scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
+	}
+}

package/lib/coverage-manifest-schema.ts

@@ -2,25 +2,11 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
+ * @file Schema and read/write helpers for the candidate gazetteer's coverage manifest.
  *
- *   Typed schema + read/write helpers for the candidate gazetteer's COVERAGE MANIFEST — the two
- *   country-keyed tables through which the artifact declares facts about ITSELF, so those facts are
- *   updated at gazetteer REBUILD, not by a hand-edited code PR after someone remembers:
- *
- *   - `country_coverage`: the hard-country-filter coverage record (#743/#194) — per-country
- *     promotion-eval verdicts + the measured hard-resolve rates that used to live in a code comment on
- *     `HARD_PLACE_COUNTRY_SAFELIST`. Presence = measured; `hard_filter_safe = 0` = measured and
- *     FAILED the check (FI 69.5%, PL 77.8%) — distinguishable from a country never measured at all
- *     (the meaning-of-zero rule, `docs/engineering/reference/layer-contract.mdx`).
- *   - `country_bbox`: the coarse guard-B plausibility boxes that used to live in
- *     `resolver/plausibility.ts`'s `COUNTRY_BBOX`. An absent row fails open (never trips the guard),
- *     exactly like an absent key in the constant.
- *
- *   Emission happens at build time (`mailwoman/gazetteer-pipeline/coverage-manifest.ts` owns the
- *   measured record and calls {@link writeGazetteerCoverageManifest} before the DB is sealed — never
- *   patch a shipped DB, rebuild). The read happens at open time ({@link WOFCandidateTableLookup}
- *   calls {@link readGazetteerCoverageManifest} in its constructor); an artifact that predates the
- *   manifest returns `undefined` and every consumer falls back to the code constants byte-identically.
+ *   The manifest holds two country-keyed tables. `country_coverage` records each measured country's hard-filter
+ *   verdict. A missing row means the country was never measured. `hard_filter_safe = 0` means measurement found the
+ *   filter unsafe. `country_bbox` holds coarse plausibility boxes. A missing bbox row never trips the guard.
  */
 
 import {
@@ -36,41 +22,45 @@ import { sql, type Kysely } from "kysely"
 import { hasTable } from "#sqlite-utils"
 
 /**
- * One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}.
+ * The stored form of {@link CountryCoverageFact}, one row per country.
  */
 export interface CountryCoverageTable {
 	/**
-	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 * The upper-case ISO 3166-1 alpha-2 code.
+	 * This field is the primary key.
 	 */
 	country: string
 	/**
-	 * 0/1 — the promotion-eval verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring).
+	 * The promotion-eval verdict as 0 or 1.
+	 *
+	 * It is stored directly because the rate by itself does not decide it.
 	 */
 	hard_filter_safe: number
 	/**
-	 * Measured hard-resolve rate 0..1 on the panel named in `source`; NULL when the receipt recorded none.
+	 * The hard-resolve rate from 0 to 1 on the panel given in `source`, or NULL when none was recorded.
 	 */
 	hard_resolve_rate: number | null
 	/**
-	 * Panel size behind `hard_resolve_rate`; NULL when unrecorded.
+	 * The panel size behind `hard_resolve_rate`, or NULL when none was recorded.
 	 */
 	sample_size: number | null
 	/**
-	 * ISO-8601 date of the measurement / promote eval.
+	 * The ISO 8601 date of the measurement.
 	 */
 	measured_at: string
 	/**
-	 * The receipt: which panel/check produced this row.
+	 * The panel or check that produced this row.
 	 */
 	source: string
 }
 
 /**
- * One country's coarse guard-B bounding box — the storage form of {@link CountryBBoxFact}.
+ * The stored form of {@link CountryBBoxFact}, one coarse bounding box per country.
  */
 export interface CountryBBoxTable {
 	/**
-	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 * The upper-case ISO 3166-1 alpha-2 code.
+	 * This field is the primary key.
 	 */
 	country: string
 	lat_min: number
@@ -78,7 +68,7 @@ export interface CountryBBoxTable {
 	lon_min: number
 	lon_max: number
 	/**
-	 * Provenance of the box (harness + date).
+	 * The provenance of the box.
 	 */
 	source: string
 }
@@ -92,16 +82,17 @@ export interface GazetteerCoverageDatabase {
 }
 
 /**
- * Table names the lookup probes (existence-restricted, so a candidate.db built before the manifest is byte-stable).
+ * The name of the per-country coverage table.
+ * Readers check that it exists before querying it.
  */
 export const COUNTRY_COVERAGE_TABLE = "country_coverage"
 /**
- * Table of per-country bounding boxes, used to reject a placement that fell outside its own country.
+ * The name of the per-country bounding-box table, used to reject a placement outside its own country.
  */
 export const COUNTRY_BBOX_TABLE = "country_bbox"
 
 /**
- * Create `country_coverage` — a handful of small PK-probed rows, the WITHOUT ROWID sweet spot.
+ * Creates the `country_coverage` table as a `WITHOUT ROWID` table keyed by country.
  */
 export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
 	await db.schema
@@ -113,13 +104,13 @@ export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDat
 		.addColumn("sample_size", "integer")
 		.addColumn("measured_at", "text", (c) => c.notNull())
 		.addColumn("source", "text", (c) => c.notNull())
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		// Kysely has no builder method for `without rowid`.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 }
 
 /**
- * Create `country_bbox` — same shape discipline as {@link createCountryCoverageTable}.
+ * Creates the `country_bbox` table as a `WITHOUT ROWID` table keyed by country.
  */
 export async function createCountryBBoxTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
 	await db.schema
@@ -136,8 +127,10 @@ export async function createCountryBBoxTable(db: Kysely<GazetteerCoverageDatabas
 }
 
 /**
- * Write the coverage manifest into a candidate DB UNDER CONSTRUCTION (pre-seal — a shipped DB is never patched, rebuild
- * instead). Creates both tables and inserts the facts; call exactly once, from the gazetteer build.
+ * Creates both manifest tables in a candidate database under construction and inserts the facts.
+ *
+ * The gazetteer build calls it once.
+ * A shipped database is rebuilt instead of patched.
  */
 export async function writeGazetteerCoverageManifest(
 	db: Kysely<GazetteerCoverageDatabase>,
@@ -153,8 +146,8 @@ export async function writeGazetteerCoverageManifest(
 				facts.coverage.map((f) => ({
 					country: f.country.toUpperCase(),
 					hard_filter_safe: f.hardFilterSafe ? 1 : 0,
-					hard_resolve_rate: f.hardResolveRate ?? null,
-					sample_size: f.sampleSize ?? null,
+					hard_resolve_rate: f.hardResolveRate,
+					sample_size: f.sampleSize,
 					measured_at: f.measuredAt,
 					source: f.source,
 				}))
@@ -180,16 +173,18 @@ export async function writeGazetteerCoverageManifest(
 }
 
 /**
- * Read the coverage manifest from an OPEN candidate DB, or `undefined` when the artifact predates it (neither table
- * present) — the signal for consumers to fall back to the code constants byte-identically. Synchronous raw reads on
- * purpose: this runs inside {@link WOFCandidateTableLookup}'s synchronous constructor (the sync-reader carve-out in
- * `AGENTS.md`), and the tables are a few dozen rows read once per open.
+ * Reads the coverage manifest from an open candidate database.
+ *
+ * It returns `undefined` when neither table exists.
+ * Consumers then fall back to the code constants.
+ *
+ * The reads are synchronous because the candidate lookup calls this from its constructor.
  */
-export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): GazetteerArtifactCoverage | undefined {
+export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): GazetteerArtifactCoverage | null {
 	const hasCoverage = hasTable(db, COUNTRY_COVERAGE_TABLE)
 	const hasBBox = hasTable(db, COUNTRY_BBOX_TABLE)
 
-	if (!hasCoverage && !hasBBox) return undefined
+	if (!hasCoverage && !hasBBox) return null
 
 	const countryCoverage = new Map<string, CountryCoverageFact>()
 
@@ -206,8 +201,8 @@ export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): Gazet
 			countryCoverage.set(country, {
 				country,
 				hardFilterSafe: Number(row.hard_filter_safe) !== 0,
-				...(row.hard_resolve_rate === null ? {} : { hardResolveRate: Number(row.hard_resolve_rate) }),
-				...(row.sample_size === null ? {} : { sampleSize: Number(row.sample_size) }),
+				hardResolveRate: row.hard_resolve_rate === null ? null : Number(row.hard_resolve_rate),
+				sampleSize: row.sample_size === null ? null : Number(row.sample_size),
 				measuredAt: String(row.measured_at),
 				source: String(row.source),
 			})