@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/{coincident-roles.ts → lib/coincident-roles.ts}

@@ -38,9 +38,13 @@
  *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
  */
 
-import type { DatabaseSync } from "node:sqlite"
-
+import type { CoincidentLocality } from "@mailwoman/resolver"
 import { haversineKm } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
+
+import type { WOFDatabase } from "#schema"
+import { allRows } from "#sqlite-utils"
 
 /**
  * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
@@ -102,16 +106,12 @@ interface CandidateRow {
 	pop: number
 }
 
-function tableExists(db: DatabaseSync, name: string): boolean {
-	return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?").get(name)
-}
-
 /**
  * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
  * touches `spr`/`names`/`ancestors`. Idempotent.
  */
 export function buildCoincidentRoles(
-	db: DatabaseSync,
+	db: DatabaseClient<WOFDatabase>,
 	opts: BuildCoincidentRolesOpts = {}
 ): BuildCoincidentRolesResult {
 	const start = Date.now()
@@ -149,8 +149,8 @@ export function buildCoincidentRoles(
 	// 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.
-	const candidates = db
-		.prepare(
+	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,
 				r.latitude AS rlat, r.longitude AS rlon, l.latitude AS llat, l.longitude AS llon,
 				r.min_latitude, r.min_longitude, r.max_latitude, r.max_longitude,
@@ -163,7 +163,7 @@ export function buildCoincidentRoles(
 			WHERE r.placetype = 'region'
 				AND r.is_current != 0 AND r.is_deprecated = 0`
 		)
-		.all() as unknown as CandidateRow[]
+	)
 
 	onProgress("filtering", `${candidates.length} candidates`)
 
@@ -212,7 +212,7 @@ export function buildCoincidentRoles(
 /**
  * True iff the relation table exists. Used by the resolver to decide whether completion can run.
  */
-export function coincidentRolesExists(db: DatabaseSync): boolean {
+export function coincidentRolesExists<DB>(db: DatabaseClient<DB>): boolean {
 	return tableExists(db, COINCIDENT_ROLES_TABLE)
 }
 
@@ -221,24 +221,24 @@ export function coincidentRolesExists(db: DatabaseSync): boolean {
  * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
  * map when the table is absent.
  */
-export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRole[]> {
+export function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, CoincidentRole[]> {
 	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
-			FROM ${COINCIDENT_ROLES_TABLE}`
-		)
-		.all() as unknown as Array<{
+	const rows = allRows<{
 		admin_id: number
 		locality_id: number
 		relationship_type: CoincidentRole["relationshipType"]
 		admin_placetype: string
 		distance_km: number
 		locality_population: number
-	}>
+	}>(
+		db.prepare(
+			`SELECT admin_id, locality_id, relationship_type, admin_placetype, distance_km, locality_population
+			FROM ${COINCIDENT_ROLES_TABLE}`
+		)
+	)
 
 	for (const r of rows) {
 		const entry: CoincidentRole = {
@@ -260,3 +260,59 @@ export function loadCoincidentRoles(db: DatabaseSync): Map<number, CoincidentRol
 
 	return map
 }
+
+/**
+ * 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[]> {
+	const map = new Map<number, CoincidentLocality[]>()
+
+	if (coincidentRolesExists(db)) {
+		const rows = allRows<{
+			adminID: number
+			id: number
+			name: string
+			country: string
+			lat: number
+			lon: number
+			relationshipType: string
+			population: number
+			distanceKm: number
+		}>(
+			db.prepare(
+				`SELECT cr.admin_id AS adminID, s.id AS id, s.name AS name, s.country AS country,
+					s.latitude AS lat, s.longitude AS lon,
+					cr.relationship_type AS relationshipType, cr.locality_population AS population,
+					cr.distance_km AS distanceKm
+				FROM ${COINCIDENT_ROLES_TABLE} cr JOIN spr s ON s.id = cr.locality_id`
+			)
+		)
+
+		for (const r of rows) {
+			const candidate: CoincidentLocality = {
+				id: r.id,
+				name: r.name,
+				placetype: "locality",
+				country: r.country,
+				lat: r.lat,
+				lon: r.lon,
+				score: 0,
+				relationshipType: r.relationshipType,
+				population: r.population,
+				distanceKm: r.distanceKm,
+			}
+
+			const list = map.get(r.adminID)
+
+			if (list) {
+				list.push(candidate)
+			} else {
+				map.set(r.adminID, [candidate])
+			}
+		}
+	}
+
+	return map
+}

package/{convention.ts → lib/convention/index.ts}

@@ -21,7 +21,7 @@
  *   source).
  */
 
-import type { FindPlaceQuery, PlaceCandidate } from "./types.ts"
+import type { FindPlaceQuery, PlaceCandidate } from "#types"
 
 /**
  * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
@@ -76,13 +76,13 @@ export const WORLD_DEFAULT: ResolvedConvention = {
 export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
 
 /**
- * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the shard
+ * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the extract
  * auto-detect all agree.
  */
 export const ADDRESS_CONVENTION_TABLE = "address_convention"
 
 /**
- * A named resolution primitive. Returns `null` to abstain (gate unmet / no data) → the dispatcher tries the next
+ * A named resolution primitive. Returns `null` to abstain (condition unmet / no data) → the dispatcher tries the next
  * strategy; returns an array (possibly empty) to claim the result.
  */
 export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>
@@ -142,8 +142,8 @@ export function mergeConventions(base: Convention, ...overrides: Array<Conventio
  * region, …, locality). Starts from `WORLD_DEFAULT` so every field is defined regardless of which (if any) ancestors
  * carry an override.
  */
-export function resolveConvention(source: ConventionSource, ancestorIds: readonly number[]): ResolvedConvention {
-	const layers = ancestorIds.map((id) => source.get(id))
+export function resolveConvention(source: ConventionSource, ancestorIDs: readonly number[]): ResolvedConvention {
+	const layers = ancestorIDs.map((id) => source.get(id))
 	const merged = mergeConventions(WORLD_DEFAULT, ...layers)
 
 	return {

package/lib/convention/schema.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @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
+ *   {@link createAddressConventionTable} creates the table, so a column added to one is a compile error against the
+ *   other.
+ */
+
+import type { Kysely } from "kysely"
+
+import { ADDRESS_CONVENTION_TABLE } from "#convention/index"
+
+/**
+ * One convention profile, keyed by the WOF admin polygon it attaches to.
+ */
+export interface AddressConventionTable {
+	wof_id: number
+	/**
+	 * The `Convention` record, JSON-encoded. Parsed at read time by `SqliteConventionSource`.
+	 */
+	convention: string
+	/**
+	 * Provenance: why this row exists and where it came from.
+	 */
+	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
+}
+
+/**
+ * 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.
+ */
+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.
+ */
+export async function createAddressConventionTable(db: ConventionSchemaHandle): Promise<void> {
+	await db.schema
+		.createTable(ADDRESS_CONVENTION_TABLE)
+		.addColumn("wof_id", "integer", (column) => column.primaryKey())
+		.addColumn("convention", "text", (column) => column.notNull())
+		.addColumn("source", "text", (column) => column.notNull())
+		.execute()
+}
+
+/**
+ * Create the artifact's `meta` table.
+ */
+export async function createConventionMetaTable(db: ConventionSchemaHandle): Promise<void> {
+	await db.schema
+		.createTable("meta")
+		.addColumn("key", "text", (column) => column.primaryKey())
+		.addColumn("value", "text")
+		.execute()
+}

package/{coverage-manifest-schema.ts → lib/coverage-manifest-schema.ts}

@@ -8,9 +8,9 @@
  *   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
+ *     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 gate (FI 69.5%, PL 77.8%) — distinguishable from a country never measured at all
+ *     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),
@@ -23,17 +23,16 @@
  *   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 type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { sql, type Kysely } from "kysely"
 
-import { hasTable } from "./sqlite-utils.ts"
+import { allRows, hasTable } from "#sqlite-utils"
 
 /**
  * One country's hard-filter coverage measurement — the storage form of {@link CountryCoverageFact}.
@@ -44,7 +43,7 @@ export interface CountryCoverageTable {
 	 */
 	country: string
 	/**
-	 * 0/1 — the promote-gate verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring).
+	 * 0/1 — the promotion-eval verdict (a verdict column, NOT re-derived from the rate; see the fact type's docstring).
 	 */
 	hard_filter_safe: number
 	/**
@@ -56,11 +55,11 @@ export interface CountryCoverageTable {
 	 */
 	sample_size: number | null
 	/**
-	 * ISO-8601 date of the measurement / promote gate.
+	 * ISO-8601 date of the measurement / promote eval.
 	 */
 	measured_at: string
 	/**
-	 * The receipt: which panel/gate produced this row.
+	 * The receipt: which panel/check produced this row.
 	 */
 	source: string
 }
@@ -92,7 +91,7 @@ export interface GazetteerCoverageDatabase {
 }
 
 /**
- * Table names the lookup probes (existence-gated, so a candidate.db built before the manifest is byte-stable).
+ * Table names the lookup probes (existence-restricted, so a candidate.db built before the manifest is byte-stable).
  */
 export const COUNTRY_COVERAGE_TABLE = "country_coverage"
 /**
@@ -185,7 +184,7 @@ export async function writeGazetteerCoverageManifest(
  * 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 {
+export function readGazetteerCoverageManifest<DB>(db: DatabaseClient<DB>): GazetteerArtifactCoverage | undefined {
 	const hasCoverage = hasTable(db, COUNTRY_COVERAGE_TABLE)
 	const hasBBox = hasTable(db, COUNTRY_BBOX_TABLE)
 
@@ -194,11 +193,11 @@ export function readGazetteerCoverageManifest(db: DatabaseSync): GazetteerArtifa
 	const countryCoverage = new Map<string, CountryCoverageFact>()
 
 	if (hasCoverage) {
-		const rows = db
-			.prepare(
+		const rows = allRows<CountryCoverageTable>(
+			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()
@@ -217,9 +216,9 @@ export function readGazetteerCoverageManifest(db: DatabaseSync): GazetteerArtifa
 	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[]
+		const rows = allRows<CountryBBoxTable>(
+			db.prepare(`SELECT country, lat_min, lat_max, lon_min, lon_max, source FROM ${COUNTRY_BBOX_TABLE}`)
+		)
 
 		for (const row of rows) {
 			const country = String(row.country).toUpperCase()

package/lib/currency-backfill.ts

@@ -0,0 +1,334 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Pass 1c of the candidate build (#1737): resurrect deprecated-with-no-successor WOF localities that a second
+ *   source independently attests. Extracted from `build-candidate.ts` as a cohesive unit — the checks, their measured
+ *   constants, and the GeoNames dump reader live together here; the build calls {@link resurrectCurrencyHoles} once,
+ *   between the primaries pass and the alias pass.
+ */
+
+import { pathExists } from "@mailwoman/core/fs/readers"
+import { isStrictlyFiner } from "@mailwoman/core/resources/whosonfirst"
+import { haversineKm } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { resolvePath } from "path-ts"
+import { TSVSpliterator } from "spliterator"
+
+import type { loadImportanceIndex } from "#candidate-importance"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { WOFDatabase } from "#schema"
+import { normalizeLocalityForKey } from "#street/normalize"
+
+/**
+ * Corroboration radius for the currency backfill (#1737), km — both for the live-near blocker and the GeoNames
+ * attestation. Measured basis (2026-08-19 prototype, GB locality slice): at 10 km, 20 of 108 dead names resurrect —
+ * Rochester (Kent), Aldershot, Staines, Telford, Ebbw Vale among them — while the `Birmingham/Wolverhampton/…`
+ * conurbation blobs stay dead (no attestation) and Swansea/Wrexham stay out because a live same-name row already serves
+ * them within the radius.
+ */
+const CURRENCY_BACKFILL_RADIUS_KM = 10
+
+/**
+ * Minimum attestor population for a resurrection. The same prototype measured 44 of 108 dead GB names attested but
+ * under this floor — hamlet-scale ghosts whose absence from the index nobody has reported. A floor keeps the pass
+ * answering the measured defect (real settlements) rather than re-importing the tail WOF chose to prune.
+ */
+const CURRENCY_BACKFILL_POP_FLOOR = 1000
+
+/**
+ * Pass 1c (#1737): resurrect deprecated-with-no-successor localities that a second source independently attests.
+ *
+ * WOF deprecations WITH a successor need nothing — the successor indexes. A deprecation with `is_superseded = 0` on a
+ * populated place is the shape of an upstream mistake (Rochester Kent, Aldershot, Telford; 120 GB localities alone),
+ * and it is indistinguishable from a correct pruning at this layer without outside evidence. So every resurrection
+ * requires all three conditions, positive evidence only:
+ *
+ * 1. NO live same-name spr row of any placetype within {@link CURRENCY_BACKFILL_RADIUS_KM} of the dead record — a live row
+ *    means the place is alive (possibly under another placetype) and there is no hole. A DISTANT same-name row is a
+ *    namesake and does not block.
+ * 2. A GeoNames feature-class-P attestation of the same folded name within the radius.
+ * 3. The attestor at or above {@link CURRENCY_BACKFILL_POP_FLOOR}.
+ *
+ * The staged row keeps the WOF identity — id, name, centroid, bbox, region ancestry — because the dead record's own
+ * data is not what is wrong with it. GeoNames contributes exactly two things: the attestation, and the population that
+ * lets the row stand in prominence races (the dead record's own population is absent). Each name is judged once per
+ * country; the resurrected place joins `attrs`, so the alias pass explodes its alt names like any primary's.
+ */
+export interface CurrencyBackfillOutcomes {
+	judged: number
+	blocked: number
+	unattested: number
+	floored: number
+	resurrected: number
+}
+
+/**
+ * One country's read of the check — every dead name judged, by outcome and by the dead row's placetype — so a census
+ * can say what a wider dead-row query admits before a build carries it.
+ */
+export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes {
+	country: string
+	deadPlacetypes: readonly string[]
+	dumpPresent: boolean
+	byDeadPlacetype: Record<string, CurrencyBackfillOutcomes>
+	/**
+	 * The first resurrected names, `placetype:name`, so a census reads what a wider query admits — capped, because the
+	 * report is a receipt and not the table.
+	 */
+	sample: string[]
+}
+
+const REPORT_SAMPLE_SIZE = 25
+
+/**
+ * The placetypes a dead row may carry to be judged at all. `locality` is the shipped default; `localadmin` is the
+ * second cause #1746 named (one GB row of seventeen) and is admitted through this option once its census is read.
+ */
+export const DEFAULT_DEAD_PLACETYPES: readonly string[] = ["locality"]
+
+function emptyOutcomes(): CurrencyBackfillOutcomes {
+	return { judged: 0, blocked: 0, unattested: 0, floored: 0, resurrected: 0 }
+}
+
+export async function resurrectCurrencyHoles(ctx: {
+	src: DatabaseClient<WOFDatabase>
+	/**
+	 * The candidate build's transaction. Required unless `dryRun` — a dry run judges every row and stages nothing.
+	 */
+	tx?: DatabaseClient<CandidateDatabase>
+	geonamesDir: string
+	countries: readonly string[]
+	attrs: Map<number, PlaceAttrs>
+	ccID: (code: string | null) => number
+	ptID: (pt: string | null) => number
+	regionOf: Map<number, number>
+	importance: ReturnType<typeof loadImportanceIndex> | undefined
+	stageRow: StageRow
+	progress: (phase: string, message: string) => void
+	/**
+	 * Which dead placetypes are judged. Default {@link DEFAULT_DEAD_PLACETYPES}.
+	 */
+	deadPlacetypes?: readonly string[]
+	/**
+	 * Judge and count, stage nothing — the census mode. No transaction is opened.
+	 */
+	dryRun?: boolean
+	/**
+	 * Receives one report per country judged (a country with no dump or no dead rows reports zero outcomes).
+	 */
+	onCountry?: (report: CurrencyBackfillCountryReport) => void
+}): Promise<number> {
+	const deadPlacetypes = ctx.deadPlacetypes ?? DEFAULT_DEAD_PLACETYPES
+	const dryRun = ctx.dryRun === true
+
+	if (!dryRun && !ctx.tx) {
+		throw new Error(
+			"resurrectCurrencyHoles: a build run needs the candidate transaction (tx); pass dryRun to judge only"
+		)
+	}
+
+	const deadStmt = ctx.src.prepare(
+		`SELECT id, name, placetype, latitude, longitude, min_latitude, min_longitude, max_latitude, max_longitude
+		 FROM spr
+		 WHERE country = ? AND placetype IN (${deadPlacetypes.map(() => "?").join(", ")})
+		   AND is_current = 0 AND is_deprecated = 1 AND is_superseded = 0`
+	)
+
+	const liveStmt = ctx.src.prepare(
+		`SELECT latitude, longitude, placetype FROM spr WHERE country = ? AND name = ? AND is_current != 0`
+	)
+
+	let total = 0
+
+	for (const country of ctx.countries) {
+		const cc = country.toUpperCase()
+		const dumpPath = resolvePath(ctx.geonamesDir, `${cc}.txt`)
+
+		const report: CurrencyBackfillCountryReport = {
+			country: cc,
+			deadPlacetypes,
+			dumpPresent: await pathExists(dumpPath),
+			...emptyOutcomes(),
+			byDeadPlacetype: {},
+			sample: [],
+		}
+
+		if (!report.dumpPresent) {
+			ctx.progress("currency-backfill", `${cc}: no GeoNames dump at ${dumpPath} — holes stay dead`)
+			ctx.onCountry?.(report)
+
+			continue
+		}
+
+		// Dead rows FIRST: a country with no deprecated-no-successor localities needs no attestors at all, and
+		// loading a national dump to judge zero rows is pure heap pressure on a build already near its ceiling
+		// (the first live run OOM'd in a later pass with JP/KR dumps loaded for 0 dead names each).
+		const dead = deadStmt.all(cc, ...deadPlacetypes)
+
+		if (!dead.length) {
+			ctx.progress("currency-backfill", `${cc}: 0 dead names — dump not loaded`)
+			ctx.onCountry?.(report)
+
+			continue
+		}
+
+		// Only the dead names' own folded keys can ever be probed, so only those keys are worth holding —
+		// the rest of the national dump streams through without residency.
+		const deadKeys = new Set<string>()
+
+		for (const d of dead) {
+			const k = normalizeLocalityForKey(String(d.name ?? ""))
+
+			if (k) {
+				deadKeys.add(k)
+			}
+		}
+
+		// Folded name → P-class attestors. GeoNames columns by index: 1 name, 2 ascii, 4 lat, 5 lon,
+		// 6 feature_class, 14 population.
+		const attestors = new Map<string, { lat: number; lon: number; pop: number }[]>()
+
+		for await (const f of TSVSpliterator.fromAsync(dumpPath, { header: false })) {
+			if (f[6] !== "P") continue
+
+			const keys = [normalizeLocalityForKey(String(f[1] ?? "")), normalizeLocalityForKey(String(f[2] ?? ""))].filter(
+				(key) => key && deadKeys.has(key)
+			)
+
+			if (!keys.length) continue
+
+			const row = { lat: Number(f[4]), lon: Number(f[5]), pop: Number(f[14]) || 0 }
+
+			for (const key of new Set(keys)) {
+				const bag = attestors.get(key)
+
+				if (bag) {
+					bag.push(row)
+				} else {
+					attestors.set(key, [row])
+				}
+			}
+		}
+
+		const seen = new Set<string>()
+
+		const count = (deadPlacetype: string, outcome: keyof CurrencyBackfillOutcomes): void => {
+			report[outcome] += 1
+			const bucket = (report.byDeadPlacetype[deadPlacetype] ??= emptyOutcomes())
+
+			bucket[outcome] += 1
+		}
+
+		if (!dryRun) {
+			ctx.tx!.exec("BEGIN")
+		}
+
+		for (const d of dead) {
+			const name = String(d.name ?? "")
+			const pkey = normalizeLocalityForKey(name)
+
+			if (!pkey || seen.has(pkey)) continue
+			seen.add(pkey)
+			// Read from the row: the query admits whatever `deadPlacetypes` names, and the rank comparison below must
+			// judge each candidate against ITS dead rung, never a hardcoded one.
+			const deadPlacetype = String(d.placetype ?? "locality")
+
+			count(deadPlacetype, "judged")
+			const dLat = Number(d.latitude)
+			const dLon = Number(d.longitude)
+
+			// A live row blocks only when it is AT LEAST AS COARSE as the dead one. The original check compared name and
+			// distance alone, on the premise that a nearby same-name row means "the place is alive under another
+			// placetype" — true for a place recorded twice, false for a placetype DEMOTION, which is the shape that
+			// actually occurs: WOF retired `Gillingham` the locality (pop 101,187) and kept `Gillingham` the
+			// neighbourhood 3.2 km away, and the check read the surviving CHILD as covering its own dead parent.
+			// Sixteen of seventeen GB refusals had exactly that shape (#1746).
+			//
+			// An UNRANKED placetype blocks, which is the conservative direction: this check's failure mode is inventing
+			// a place, so a row we cannot rank is treated as covering rather than waved through.
+			const liveNear = liveStmt.all(cc, name).some((row) => {
+				if (haversineKm(dLat, dLon, Number(row.latitude), Number(row.longitude)) > CURRENCY_BACKFILL_RADIUS_KM) {
+					return false
+				}
+
+				// Blocks UNLESS the live row is strictly finer. The equal rung must still block — a live `locality`
+				// covers a dead `locality` — and an unranked placetype blocks too, since this check's failure mode
+				// is inventing a place.
+				return isStrictlyFiner(String(row.placetype ?? ""), deadPlacetype) !== true
+			})
+
+			if (liveNear) {
+				count(deadPlacetype, "blocked")
+
+				continue
+			}
+
+			const near = (attestors.get(pkey) ?? []).filter(
+				(g) => haversineKm(dLat, dLon, g.lat, g.lon) <= CURRENCY_BACKFILL_RADIUS_KM
+			)
+
+			if (!near.length) {
+				count(deadPlacetype, "unattested")
+
+				continue
+			}
+
+			const pop = Math.max(...near.map((g) => g.pop))
+
+			if (pop < CURRENCY_BACKFILL_POP_FLOOR) {
+				count(deadPlacetype, "floored")
+
+				continue
+			}
+
+			count(deadPlacetype, "resurrected")
+
+			if (report.sample.length < REPORT_SAMPLE_SIZE) {
+				report.sample.push(`${deadPlacetype}:${name}`)
+			}
+
+			if (dryRun) continue
+
+			const sid = Number(d.id)
+
+			const a: PlaceAttrs = {
+				cid: ctx.ccID(cc),
+				rid: ctx.regionOf.get(sid) ?? 0,
+				ptid: ctx.ptID(deadPlacetype),
+				name,
+				lat: dLat,
+				lon: dLon,
+				mnLat: Number(d.min_latitude),
+				mnLon: Number(d.min_longitude),
+				mxLat: Number(d.max_latitude),
+				mxLon: Number(d.max_longitude),
+				pop,
+				neg: -Math.log10(pop + 1),
+				pkey,
+				imp: ctx.importance?.find(name, cc, deadPlacetype, dLat, dLon) ?? null,
+			}
+
+			ctx.attrs.set(sid, a)
+			ctx.stageRow(pkey, a, sid, 1)
+		}
+
+		if (!dryRun) {
+			ctx.tx!.exec("COMMIT")
+		}
+
+		ctx.progress(
+			"currency-backfill",
+			`${cc}: ${report.resurrected} resurrected of ${report.judged} dead names ` +
+				`(${report.blocked} blocked by a live near row, ${report.unattested} unattested, ` +
+				`${report.floored} under the population floor)${dryRun ? " — dry run, nothing staged" : ""}`
+		)
+
+		ctx.onCountry?.(report)
+		total += report.resurrected
+	}
+
+	return total
+}