@mailwoman/resolver-wof-sqlite 8.0.0 → 8.2.0

package/candidate-lookup.ts

@@ -25,10 +25,11 @@
 
 import { DatabaseSync } from "node:sqlite"
 
-import { expandPlacetypeFilter } from "@mailwoman/resolver"
+import { expandPlacetypeFilter, type GazetteerArtifactCoverage } from "@mailwoman/resolver"
 
 import { CANDIDATE_FTS_TABLE } from "./candidate-fts.ts"
 import type { CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "./candidate-schema.ts"
+import { readGazetteerCoverageManifest } from "./coverage-manifest-schema.ts"
 import { haversineKm } from "./geo.ts"
 import { trigramJaccard } from "./lookup.ts"
 import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "./postal-city-candidate-schema.ts"
@@ -37,9 +38,13 @@ import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normal
 import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
 
 export interface WOFCandidateTableLookupOpts {
-	/** Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only. */
+	/**
+	 * Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only.
+	 */
 	databasePath?: string
-	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	/**
+	 * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+	 */
 	database?: DatabaseSync
 }
 
@@ -91,7 +96,7 @@ const FUZZY_MIN = 0.34
  *    ("Los Angeles" over La, Ghana — gap 1.6; "Las Vegas" over Vegas, Cuba — gap 2.4) while a near-tie coincidental
  *    collision defers to the primary (Cancún over Changchun — gap 0.7).
  */
-const PRIMARY_PREFERENCE_LOG10 = 1.0
+const PRIMARY_PREFERENCE_LOG10 = 1
 
 /**
  * Over-fetch cap for {@link rankByPrimaryPreference}: the candidate rows for one `name_key` (all same-name places
@@ -101,7 +106,9 @@ const PRIMARY_PREFERENCE_LOG10 = 1.0
  */
 const RERANK_FETCH = 64
 
-/** A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag. */
+/**
+ * A candidate row annotated with the {@link rankByPrimaryPreference} effective rank + the exact-tier demotion flag.
+ */
 export type RankedRow<R> = R & {
 	/**
 	 * `neg_rank` plus the bounded cross-country alias penalty — the value the row is ORDERED by, and the base the emitted
@@ -143,10 +150,12 @@ export function rankByPrimaryPreference<R extends Pick<CandidateRow, "neg_rank"
 	}
 
 	const topCountry = topPrimary?.country_id
+
 	// A cross-country alias (different country than the top primary) is penalized; it is DEMOTED when even after — i.e.
 	// the penalty leaves its effective rank behind the primary's raw rank (it lost the bounded population contest).
 	const isCrossCountryAlias = (r: R): boolean =>
 		topCountry !== undefined && r.is_primary !== 1 && r.country_id !== topCountry
+
 	const annotate = (r: R): RankedRow<R> => {
 		const penalized = isCrossCountryAlias(r)
 		const effectiveNegRank = r.neg_rank + (penalized ? delta : 0)
@@ -158,6 +167,7 @@ export function rankByPrimaryPreference<R extends Pick<CandidateRow, "neg_rank"
 		rows
 			.map((r, i) => ({ row: annotate(r), i }))
 			// Effective rank ASC; ties keep population order, then original index (stable).
+			// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 			.sort((a, b) => a.row.effectiveNegRank - b.row.effectiveNegRank || a.row.neg_rank - b.row.neg_rank || a.i - b.i)
 			.slice(0, limit)
 			.map((x) => x.row)
@@ -212,6 +222,12 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 	 * country-agnostic retry. Prepared only alongside `#ftsProbe`.
 	 */
 	readonly #nameKeyExistsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	/**
+	 * Facts this candidate DB declares about itself — the coverage manifest (`country_coverage` + `country_bbox`) the
+	 * gazetteer build emits, read once at open. `undefined` when the artifact predates the manifest, so every consumer
+	 * (the hard-country coverage gate, guard-B plausibility) falls back to its code constants byte-identically.
+	 */
+	readonly artifactCoverage: GazetteerArtifactCoverage | undefined
 
 	constructor(opts: WOFCandidateTableLookupOpts) {
 		if (opts.database) {
@@ -253,11 +269,19 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			this.#ftsProbe = this.#db.prepare(
 				`SELECT name_key FROM ${CANDIDATE_FTS_TABLE} WHERE ${CANDIDATE_FTS_TABLE} MATCH ? ORDER BY bm25(${CANDIDATE_FTS_TABLE}) LIMIT ?`
 			)
+
 			this.#nameKeyExistsProbe = this.#db.prepare("SELECT 1 FROM candidate WHERE name_key = ? LIMIT 1")
 		}
+
+		// Coverage manifest (survey candidate #2): the artifact's own coverage facts, existence-gated like
+		// the probes above — a candidate.db built before the manifest reads `undefined` and consumers keep
+		// their code-constant fallbacks byte-identically.
+		this.artifactCoverage = readGazetteerCoverageManifest(this.#db)
 	}
 
-	/** Does this query want a locality-tier place? Postal-city aliases (#741) are all localities. */
+	/**
+	 * Does this query want a locality-tier place? Postal-city aliases (#741) are all localities.
+	 */
 	#wantsLocality(placetype: FindPlaceQuery["placetype"]): boolean {
 		if (!placetype) return true
 		const want = Array.isArray(placetype) ? placetype : [placetype]
@@ -274,8 +298,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// form at build (the GeoNames fold normalizes '624 66' → '62466'), so a postcode-typed query
 		// strips internal whitespace before keying. Postcode-only — locality names keep their spaces.
 		if ([query.placetype].flat().includes("postalcode")) {
-			text = text.replace(/\s+/g, "")
+			text = text.replaceAll(/\s+/g, "")
 		}
+
 		const nameKey = normalizeLocalityForKey(text)
 
 		if (!nameKey) return []
@@ -325,11 +350,12 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// Shared placetype-equivalence expansion (a `locality` query must also reach borough /
 			// localadmin). `postalcode` maps to no admin placetype here → empty → no rows.
 			const want = Array.isArray(query.placetype) ? query.placetype : [query.placetype]
+
 			const ids = expandPlacetypeFilter(want as readonly string[])
 				.map((t) => this.#placetypeToID.get(t))
 				.filter((v): v is number => v !== undefined)
 
-			if (ids.length === 0) return []
+			if (!ids.length) return []
 			filters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`)
 			filterParams.push(...ids)
 		}
@@ -348,7 +374,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// Kept OUT of the shared `filters` so a region MISS falls back to the unscoped cascade below: a
 		// country/non-region parent (no `region_id` match), a `region_id=0` row (place with no region
 		// ancestor), or a wrong parent degrades to today's behavior — never worse, recall-safe by construction.
-		const regionParentID = query.parentID ? query.parentID : undefined
+		const regionParentID = query.parentID || undefined
 
 		const probe = (nk: string, regionID: number | undefined): Array<RankedRow<CandidateRow>> => {
 			const conds = ["name_key = ?", ...filters]
@@ -367,6 +393,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			const sql =
 				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank, is_primary " +
 				`FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
+
 			const fetched = this.#db.prepare(sql).all(...params, Math.max(limit, RERANK_FETCH)) as unknown as CandidateRow[]
 
 			return rankByPrimaryPreference(fetched, limit)
@@ -378,7 +405,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		const cascade = (regionID: number | undefined): Array<RankedRow<CandidateRow>> => {
 			let rows = probe(nameKey, regionID)
 
-			if (rows.length === 0) {
+			if (!rows.length) {
 				// Query-side qualifier-strip fallback: an OA locality with a qualifier the gazetteer's
 				// canonical name omits ("Lenk im Simmental" → "Lenk", "Roche VD"). Tried ONLY on an exact
 				// miss; the cascade's region bbox disambiguates any base-name ambiguity.
@@ -400,15 +427,18 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
 			// pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
 			// correctly lands population-first Vienna AT. The exact/strip probes already covered the real name.
-			if (rows.length === 0 && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
+			if (!rows.length && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
 				const match = ftsTrigramQuery(nameKey)
 
 				if (match) {
 					const hits = this.#ftsProbe.all(match, FUZZY_FETCH) as unknown as Array<{ name_key: string }>
+
 					const ranked = hits
 						.map((h) => ({ nk: String(h.name_key), s: trigramJaccard(nameKey, String(h.name_key)) }))
 						.filter((h) => h.s >= FUZZY_MIN)
+						// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 						.sort((a, b) => b.s - a.s)
+
 					const seen = new Set<string>()
 
 					for (const h of ranked) {
@@ -418,6 +448,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 						if (rows.length >= limit) break
 					}
+
 					rows = rows.slice(0, limit)
 				}
 			}
@@ -430,7 +461,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// Region-scope fallback: if scoping to the parent region found nothing across the whole cascade, retry
 		// unscoped so a place with no in-region row (missing ancestry, or a country/non-region parent) still
 		// resolves exactly as it does today. Only when a region scope was actually applied.
-		if (rows.length === 0 && regionParentID !== undefined) {
+		if (!rows.length && regionParentID !== undefined) {
 			rows = cascade(undefined)
 		}
 
@@ -480,9 +511,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// log10(population + 1), so popTerm is the server formula read straight off it. Constants MIRROR
 		// lookup.ts's DEFAULT_WEIGHTS (biasBoost 4, populationBoost 4, populationScaleLog10 6,
 		// proximityScaleKm 100) — the #861 server↔demo parity contract; keep them in lockstep.
-		if (query.bias && query.bias.length > 0) {
-			const BIAS_BOOST = 4.0
-			const POP_BOOST = 4.0
+		if (query.bias && query.bias.length) {
+			const BIAS_BOOST = 4
+			const POP_BOOST = 4
 			const POP_SCALE_LOG10 = 6
 			// SHARPER than lookup.ts's 100 km on purpose: this backend's `score` is log-population ALONE
 			// (no bm25 document term), so the population signal is weaker relative to the bias and the
@@ -491,6 +522,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// candidates the user is actually LOOKING at — an in-view namesake still wins (Dublin, OH from
 			// an Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
 			const PROX_SCALE_KM = 30
+
 			const combinedProminence = (c: PlaceCandidate): number => {
 				// Population base is the PENALIZED `prominence` (set above = -effectiveNegRank), not raw `score`, so
 				// the cross-country primary preference carries into the bias-weighted order too — a coincidental
@@ -512,6 +544,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 				return popTerm + proxTerm
 			}
+
 			// Persist the combined value into `prominence` so the resolver walk's `prominence ?? score` sort (and any
 			// other node consumer) honors the bias order — then sort. Stable within equal prominence (preserves the
 			// population order the B-tree already gave).
@@ -521,6 +554,7 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 
 					return { c, i, p: c.prominence }
 				})
+				// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
 				.sort((a, b) => b.p - a.p || a.i - b.i)
 				.forEach((x, j) => (candidates[j] = x.c))
 		}

package/candidate-schema.ts

@@ -23,19 +23,29 @@ import { sql, type Kysely } from "kysely"
  * level (a postcode shard row may lack a bbox).
  */
 export interface CandidateTable {
-	/** The shared {@link normalizeLocalityForKey} of the name/alias — the probe key. */
+	/**
+	 * The shared {@link normalizeLocalityForKey} of the name/alias — the probe key.
+	 */
 	name_key: string
-	/** Small int from {@link CountryCodeTable} (shrinks the clustered key). */
+	/**
+	 * Small int from {@link CountryCodeTable} (shrinks the clustered key).
+	 */
 	country_id: number
-	/** The place's region-tier ancestor id, or 0 (carried for the future region 2-step). */
+	/**
+	 * The place's region-tier ancestor id, or 0 (carried for the future region 2-step).
+	 */
 	region_id: number
-	/** Small int from {@link PlacetypeCodeTable}. */
+	/**
+	 * Small int from {@link PlacetypeCodeTable}.
+	 */
 	placetype_id: number
 	/**
 	 * `-log10(population + 1)` — ASC order = highest-population first. 0 for postcodes (no population).
 	 */
 	neg_rank: number
-	/** WOF id of the place this row resolves to. */
+	/**
+	 * WOF id of the place this row resolves to.
+	 */
 	spr_id: number
 	name: string | null
 	latitude: number | null
@@ -45,27 +55,39 @@ export interface CandidateTable {
 	max_lat: number | null
 	max_lon: number | null
 	population: number | null
-	/** 1 when the row is the place's canonical name (vs an alias/abbrev). */
+	/**
+	 * 1 when the row is the place's canonical name (vs an alias/abbrev).
+	 */
 	is_primary: number | null
 }
 
-/** `(id → ISO country code)` dictionary. */
+/**
+ * `(id → ISO country code)` dictionary.
+ */
 export interface CountryCodeTable {
 	id: number
 	code: string
 }
 
-/** `(id → placetype)` dictionary. */
+/**
+ * `(id → placetype)` dictionary.
+ */
 export interface PlacetypeCodeTable {
 	id: number
 	placetype: string
 }
 
-/** The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`. */
+/**
+ * The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`.
+ */
 export interface CandidateDatabase {
-	/** The clustered `WITHOUT ROWID` lookup table the reader probes. */
+	/**
+	 * The clustered `WITHOUT ROWID` lookup table the reader probes.
+	 */
 	candidate: CandidateTable
-	/** Transient staging table (same columns); dropped once `candidate` is materialized. */
+	/**
+	 * Transient staging table (same columns); dropped once `candidate` is materialized.
+	 */
 	cand_stage: CandidateTable
 	country_codes: CountryCodeTable
 	placetype_codes: PlacetypeCodeTable
@@ -105,11 +127,13 @@ export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>
 		.addColumn("id", "integer", (c) => c.primaryKey())
 		.addColumn("code", "text", (c) => c.unique())
 		.execute()
+
 	await db.schema
 		.createTable("placetype_codes")
 		.addColumn("id", "integer", (c) => c.primaryKey())
 		.addColumn("placetype", "text", (c) => c.unique())
 		.execute()
+
 	await db.schema
 		.createTable("cand_stage")
 		.addColumn("name_key", "text")

package/coincident-roles.ts

@@ -42,9 +42,15 @@ import type { DatabaseSync } from "node:sqlite"
 
 import { haversineKm } from "@mailwoman/spatial"
 
+/**
+ * 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
 	relationshipType: "city-state" | "capital-seat" | "consolidated-county"
@@ -54,13 +60,17 @@ 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. Default true (the build is cheap + idempotent).
+	 */
 	drop?: boolean
 	/**
 	 * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`. Default 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. Default 12.
+	 */
 	minToleranceKm?: number
 	/**
 	 * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only). Default 2.
@@ -115,7 +125,9 @@ export function buildCoincidentRoles(
 		onProgress("dropping", COINCIDENT_ROLES_TABLE)
 		db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`)
 	}
+
 	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
@@ -133,6 +145,7 @@ 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.
@@ -153,11 +166,13 @@ export function buildCoincidentRoles(
 		.all() as unknown as CandidateRow[]
 
 	onProgress("filtering", `${candidates.length} candidates`)
+
 	const insert = db.prepare(
 		`INSERT OR REPLACE INTO ${COINCIDENT_ROLES_TABLE}
 			(admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population)
 			VALUES (?, ?, ?, ?, ?, ?)`
 	)
+
 	const byCountry: Record<string, number> = {}
 	let rowCount = 0
 	db.exec("BEGIN")
@@ -176,14 +191,17 @@ export function buildCoincidentRoles(
 			// dominated by French cantons / JP counties that don't 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)
+
 			rowCount++
 			byCountry[c.country] = (byCountry[c.country] ?? 0) + 1
 		}
+
 		db.exec("COMMIT")
-	} catch (err) {
+	} catch (error) {
 		db.exec("ROLLBACK")
-		throw err
+		throw error
 	}
+
 	db.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON ${COINCIDENT_ROLES_TABLE} (admin_id)`)
 
 	onProgress("done", `${rowCount} coincident-role rows`)
@@ -191,7 +209,9 @@ export function buildCoincidentRoles(
 	return { created: true, rowCount, byCountry, durationMs: Date.now() - start }
 }
 
-/** 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: DatabaseSync): boolean {
 	return tableExists(db, COINCIDENT_ROLES_TABLE)
 }
@@ -205,6 +225,7 @@ export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRol
 	const map = new Map<number, CoincidentRole[]>()
 
 	if (!coincidentRolesExists(db)) return map
+
 	const rows = db
 		.prepare(
 			`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
@@ -227,6 +248,7 @@ export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRol
 			distanceKm: r.distance_km,
 			population: r.locality_population,
 		}
+
 		const list = map.get(r.admin_id)
 
 		if (list) {

package/convention.ts

@@ -38,7 +38,9 @@ export interface ScoringWeights {
  * `tokenNormalization`, etc.
  */
 export interface Convention {
-	/** Ordered strategy names the dispatcher runs; the first to return a non-null result wins. */
+	/**
+	 * Ordered strategy names the dispatcher runs; the first to return a non-null result wins.
+	 */
 	candidateStrategies?: string[]
 	/**
 	 * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and inherit the rest

package/coverage-manifest-schema.ts

@@ -0,0 +1,243 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   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
+ *     promote-gate 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 gate (FI 69.5%, PL 77.8%) — distinguishable from a country never measured at all
+ *     (the meaning-of-zero rule, `docs/articles/plan/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.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import {
+	hardCountrySafelistFromCoverage,
+	type CountryBBoxFact,
+	type CountryCoverageFact,
+	type GazetteerArtifactCoverage,
+} from "@mailwoman/core/resolver"
+import { sql, type Kysely } from "kysely"
+
+import { hasTable } from "./sqlite-utils.ts"
+
+/**
+ * One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}.
+ */
+export interface CountryCoverageTable {
+	/**
+	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 */
+	country: string
+	/**
+	 * 0/1 — the promote-gate verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring).
+	 */
+	hard_filter_safe: number
+	/**
+	 * Measured hard-resolve rate 0..1 on the panel named in `source`; NULL when the receipt recorded none.
+	 */
+	hard_resolve_rate: number | null
+	/**
+	 * Panel size behind `hard_resolve_rate`; NULL when unrecorded.
+	 */
+	sample_size: number | null
+	/**
+	 * ISO-8601 date of the measurement / promote gate.
+	 */
+	measured_at: string
+	/**
+	 * The receipt: which panel/gate produced this row.
+	 */
+	source: string
+}
+
+/**
+ * One country's coarse guard-B bounding box — the storage form of {@link CountryBBoxFact}.
+ */
+export interface CountryBBoxTable {
+	/**
+	 * ISO 3166-1 alpha-2, uppercase (PK).
+	 */
+	country: string
+	lat_min: number
+	lat_max: number
+	lon_min: number
+	lon_max: number
+	/**
+	 * Provenance of the box (harness + date).
+	 */
+	source: string
+}
+
+/**
+ * The coverage-manifest schema for `new DatabaseClient<GazetteerCoverageDatabase>(...)`.
+ */
+export interface GazetteerCoverageDatabase {
+	country_coverage: CountryCoverageTable
+	country_bbox: CountryBBoxTable
+}
+
+/**
+ * Table names the lookup probes (existence-gated, so a candidate.db built before the manifest is byte-stable).
+ */
+export const COUNTRY_COVERAGE_TABLE = "country_coverage"
+/**
+ * Table of per-country bounding boxes, used to reject a placement that fell 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.
+ */
+export async function createCountryCoverageTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
+	await db.schema
+		.createTable(COUNTRY_COVERAGE_TABLE)
+		.ifNotExists()
+		.addColumn("country", "text", (c) => c.primaryKey())
+		.addColumn("hard_filter_safe", "integer", (c) => c.notNull())
+		.addColumn("hard_resolve_rate", "real")
+		.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.
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * Create `country_bbox` — same shape discipline as {@link createCountryCoverageTable}.
+ */
+export async function createCountryBBoxTable(db: Kysely<GazetteerCoverageDatabase>): Promise<void> {
+	await db.schema
+		.createTable(COUNTRY_BBOX_TABLE)
+		.ifNotExists()
+		.addColumn("country", "text", (c) => c.primaryKey())
+		.addColumn("lat_min", "real", (c) => c.notNull())
+		.addColumn("lat_max", "real", (c) => c.notNull())
+		.addColumn("lon_min", "real", (c) => c.notNull())
+		.addColumn("lon_max", "real", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * 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.
+ */
+export async function writeGazetteerCoverageManifest(
+	db: Kysely<GazetteerCoverageDatabase>,
+	facts: { coverage: readonly CountryCoverageFact[]; bboxes: readonly CountryBBoxFact[] }
+): Promise<void> {
+	await createCountryCoverageTable(db)
+	await createCountryBBoxTable(db)
+
+	if (facts.coverage.length) {
+		await db
+			.insertInto(COUNTRY_COVERAGE_TABLE)
+			.values(
+				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,
+					measured_at: f.measuredAt,
+					source: f.source,
+				}))
+			)
+			.execute()
+	}
+
+	if (facts.bboxes.length) {
+		await db
+			.insertInto(COUNTRY_BBOX_TABLE)
+			.values(
+				facts.bboxes.map((f) => ({
+					country: f.country.toUpperCase(),
+					lat_min: f.latMin,
+					lat_max: f.latMax,
+					lon_min: f.lonMin,
+					lon_max: f.lonMax,
+					source: f.source,
+				}))
+			)
+			.execute()
+	}
+}
+
+/**
+ * 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.
+ */
+export function readGazetteerCoverageManifest(db: DatabaseSync): GazetteerArtifactCoverage | undefined {
+	const hasCoverage = hasTable(db, COUNTRY_COVERAGE_TABLE)
+	const hasBBox = hasTable(db, COUNTRY_BBOX_TABLE)
+
+	if (!hasCoverage && !hasBBox) return undefined
+
+	const countryCoverage = new Map<string, CountryCoverageFact>()
+
+	if (hasCoverage) {
+		const rows = db
+			.prepare(
+				`SELECT country, hard_filter_safe, hard_resolve_rate, sample_size, measured_at, source FROM ${COUNTRY_COVERAGE_TABLE}`
+			)
+			.all() as unknown as CountryCoverageTable[]
+
+		for (const row of rows) {
+			const country = String(row.country).toUpperCase()
+
+			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) }),
+				measuredAt: String(row.measured_at),
+				source: String(row.source),
+			})
+		}
+	}
+
+	const countryBBoxes = new Map<string, CountryBBoxFact>()
+
+	if (hasBBox) {
+		const rows = db
+			.prepare(`SELECT country, lat_min, lat_max, lon_min, lon_max, source FROM ${COUNTRY_BBOX_TABLE}`)
+			.all() as unknown as CountryBBoxTable[]
+
+		for (const row of rows) {
+			const country = String(row.country).toUpperCase()
+
+			countryBBoxes.set(country, {
+				country,
+				latMin: Number(row.lat_min),
+				latMax: Number(row.lat_max),
+				lonMin: Number(row.lon_min),
+				lonMax: Number(row.lon_max),
+				source: String(row.source),
+			})
+		}
+	}
+
+	return {
+		countryCoverage,
+		countryBBoxes,
+		hardCountrySafelist: hardCountrySafelistFromCoverage(countryCoverage.values()),
+	}
+}