@mailwoman/resolver-wof-sqlite 10.0.0 → 10.1.0

package/lib/build/candidate.ts

@@ -2,48 +2,16 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Build the global "candidate" lookup DB from a unified admin WOF DB — the byte-range-optimal
- *   gazetteer the browser demo resolves against. Instead of FTS5 (whose postings for a common name
- *   scatter across a multi-GB file → hundreds of serial range fetches), this materializes one
- *   `WITHOUT ROWID` B-tree keyed `(name_key, country_id, region_id, placetype_id, neg_rank,
- *   spr_id)`: every place's normalized name + distinct aliases + region abbreviations become rows,
- *   population rank is precomputed into `neg_rank`, and the rows are bulk-loaded PRE-SORTED so a
- *   resolve is one contiguous B-tree probe (a handful of pages → 1-2 chunk fetches, regardless of
- *   global volume).
- *
- *   Each row is DENORMALIZED — it carries the place's display `name`, centroid (`latitude`/
- *   `longitude`), and `min/max` bbox — so a resolve is one statement, no FTS, no join to spr:
- *   SELECT spr_id, name, latitude, longitude, min_lat, ... FROM candidate WHERE name_key = ? AND
- *   country_id = ? AND placetype_id IN (...) [AND latitude BETWEEN ...] ORDER BY neg_rank ASC LIMIT
- *   K; The demo cascade resolves a parsed region first (its bbox), then constrains the locality to
- *   that bbox; `region_id` (the place's region-tier ancestor) is also carried for a future region
- *   2-step.
- *
- *   The name_key normalizer is the SHARED {@link normalizeLocalityForKey} — the query side (the demo
- *   resolver {@link WOFCandidateTableLookup}) MUST use the same function, the one-normalizer
- *   discipline the address-point extract uses, so build/query stay consistent by construction.
- *
- *   Measured (2026-06-20, vs the 2.6 GB full-DB FTS): ~5 M rows; ~12 range fetches per 8-query
- *   session (the full DB needs 243); US locality 96.8% (region bbox), EU coord parity 88.6%.
- *
- *   #28 adds one more denormalized field, `importance` — the toponym-fame prior that decides a BARE
- *   city name, joined in from a separate score source by name rather than by id (see
- *   `candidate-importance.ts`, which owns that join and explains why the id would be wrong). It is
- *   optional: without {@link BuildCandidateOptions.importance} the column is NULL on every row, which
- *   the consumer reads as unmeasured and ignores.
- *
- *   The build also materializes the ANCESTORS SIDECAR (`candidate_ancestor` closure rows +
- *   `candidate_interval` pre/post labels) from the source `ancestors` table — the containment
- *   lineage behind {@link WOFCandidateTableLookup.ancestors} and the admin-coherence check.
- *   `candidate-ancestors-schema.ts` owns the encoding decision and the DAG/absence semantics.
  */
 
 import { COUNTRY_POPULATION } from "@mailwoman/codex/country"
 import { pathExists } from "@mailwoman/core/fs/readers"
 import { removePath } from "@mailwoman/core/fs/writers"
+import { stringifyJSON } from "@mailwoman/core/json"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
 
+import { POPULATION_CORRECTIONS } from "#build/population-corrections"
 import { explodeAliasBags } from "#candidate/alias-bags"
 import { buildAncestorsSidecar } from "#candidate/ancestors/sidecar"
 import { stageCountryDisplayNames } from "#candidate/country-display-names"
@@ -64,158 +32,190 @@ import { resurrectCurrencyHoles } from "#currency-backfill"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
-// The build's contract is this module path; the passes behind it live in `./candidate/`. Re-exported
-// here so a consumer never has to know which pass owns which name.
+/**
+ * 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}.
+ */
 export interface BuildCandidateOptions {
 	/**
-	 * Source unified admin DB — needs spr, place_population, place_search, place_abbr, ancestors.
+	 * The source WOF admin database.
+	 *
+	 * It must have the `spr`, `place_population`, `place_search`, `place_abbr` and `ancestors` tables.
 	 */
-	input: string
+	input: PathBuilderLike
+
 	/**
-	 * Output candidate DB path (overwritten if present).
+	 * The candidate database to write, replacing any existing file.
 	 */
-	output: string
+	output: PathBuilderLike
+
 	/**
-	 * The capital-status reference entries (#1880) to carry in-artifact — the parsed `data/gazetteer/capitals-v1.json`
-	 * entries, passed by the CALLER because this module publishes to npm and must not read repo-root paths. Absent → the
-	 * `capital` table is not created, and the session loader falls back to the repo file where one exists.
+	 * The capital reference entries to store in the artifact's `capital` table.
+	 *
+	 * The caller supplies these entries because this published module cannot read repository paths.
+	 * The builder creates no `capital` table when the caller omits them.
+	 *
+	 * The capital loader then falls back to the repository's `capitals-v1.json`.
 	 */
 	capitals?: readonly CapitalPoint[]
+
 	/**
-	 * Optional postcode extracts (`spr` rows with `placetype='postalcode'` + real coords, e.g. postalcode-us.db) — folded
-	 * in as `postalcode` candidate rows so `findPlace(postalcode)` resolves a ZIP directly (the demo's primary postcode
-	 * path; the postcode-*.bin anchor stays the fallback). Matches the slim wof-hot.db, which took one such postcode DB.
+	 * Postcode extract databases whose located `spr` rows become `postalcode` candidate rows.
 	 *
-	 * Each extract's `names` table is folded in too (#1495) — that's where the GeoNames delivery-city names live
-	 * ("Brooklyn" for 11201), and they were previously reachable only through FTS.
+	 * Each extract's `names` table becomes aliases, such as the delivery city "Brooklyn" for 11201.
 	 */
-	postcodes?: string[]
+	postcodes?: readonly PathBuilderLike[]
+
 	/**
-	 * Optional LOCALITY extracts (`spr` rows with `placetype='locality'` + real coords, e.g. localities-nz-linz.db — the
-	 * #1564 NZ suburb tier) — folded through the same extract loop as the postcode extracts, staged as `locality`
-	 * candidate rows with UNMEASURED population (`neg_rank 0`: a extract row ranks behind any populated namesake and wins
-	 * only where its key is the answer). Each extract's `names` table folds as aliases, `is_primary = 0`, same as the
-	 * delivery-city pass. An extract whose `ancestors` table names an admin region for a row gives that row the region's
-	 * scope (`region_id`) plus closure rows for the region and the region's own chain above it; an extract without one
-	 * stays unscoped, as before.
+	 * Locality extract databases whose located `spr` rows become `locality`
+	 * candidate rows with zero population.
+	 *
+	 * Their `names` tables become non-primary aliases.
+	 * When an extract's `ancestors` table gives a row's region, the row gets
+	 * that region's scope and closure rows.
+	 * Other rows stay unscoped.
 	 */
-	localities?: string[]
+	localities?: readonly PathBuilderLike[]
+
 	/**
-	 * Optional WOF admin database carrying a `place_importance` table — the source of the `importance` column (#28), the
-	 * toponym-fame prior that decides the bare-city-name class. Joined by `(name_key, country, placetype)` + nearest
-	 * centroid, NOT by id; see `candidate-importance.ts` for why the id join silently drops the foreign homonyms the
-	 * prior exists to demote.
+	 * A WOF admin database with a `place_importance` table supplies the `importance` column.
 	 *
-	 * Omit it and every row's `importance` is NULL — unmeasured, which is what the consumer's positive-evidence-only rule
-	 * already treats as "do not participate", so the artifact is byte-identical to a pre-#28 build except for the empty
-	 * column. That is the honest degradation and it is the DEFAULT: a caller with no score source must not get a
-	 * population-derived stand-in written into a column that means fame.
+	 * Rows join on name key, country and placetype, then on the nearest centroid.
+	 * Without this option every row's `importance` is NULL.
+	 * Consumers treat NULL as unmeasured.
 	 */
-	importance?: string
+	importance?: PathBuilderLike
+
 	/**
-	 * Cross-source currency backfill (#1737). WOF carries deprecated-with-no-successor records for real, populated
-	 * settlements (Rochester Kent, Aldershot, Telford — 120 GB localities alone), and the currency filter correctly drops
-	 * them, leaving holes no ranking can fill. When this option is set, pass 1c resurrects a dead locality ONLY under
-	 * three conditions, positive evidence throughout: no live same-name row of any placetype near the dead record (a
-	 * distant same-name row is a NAMESAKE and does not block — Rochester, Northumberland pop 318 must not veto Rochester,
-	 * Kent); an independent GeoNames P-class attestation of the same folded name within
-	 * {@link CURRENCY_BACKFILL_RADIUS_KM}; and the attestor at or above {@link CURRENCY_BACKFILL_POP_FLOOR}. The staged
-	 * row keeps the real WOF id, name, centroid and bbox — GeoNames only ATTESTS the place and supplies the population
-	 * that lets it stand in prominence races. `countries` are judged only where `<cc>.txt` exists under `geonamesDir`;
-	 * absent dumps are skipped loudly.
+	 * Settings for restoring deprecated WOF places that have no successor and have a GeoNames attestation.
+	 *
+	 * A deprecated place is restored only when no live row of the same name lies within 10 km and
+	 * a GeoNames populated place with the same folded name and at least 1,000 people lies within 10 km.
+	 * Countries without `<cc>.txt` under `geonamesDir` are skipped and reported.
 	 */
 	currencyBackfill?: {
-		geonamesDir: string
+		geonamesDir: PathBuilderLike
 		countries: readonly string[]
+
 		/**
-		 * The dead placetypes the resurrection judges; `resurrectCurrencyHoles`'s default (`locality`) when absent. The
-		 * `localadmin` widening #1746 named is admitted here once its census is read.
+		 * The deprecated placetypes eligible for restoration.
+		 * The default is `locality`.
 		 */
 		deadPlacetypes?: readonly string[]
 	}
+
 	/**
-	 * Optional progress callback for CLI / test introspection.
+	 * Receives a phase name and a message as each build step runs.
 	 */
 	onProgress?: (phase: string, message: string) => void
+
 	/**
-	 * Key-count threshold for the gloss anomaly detector — {@link GLOSS_KEY_THRESHOLD} unless a test passes a
-	 * fixture-scale value. The production number is the #1730 sweep's own threshold (4,000 places at >= 50 keys).
+	 * 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.
 	 */
 	glossKeyThreshold?: number
 }
 
+/**
+ * Row and place counts from each stage of {@link buildCandidateTable}.
+ */
 export interface BuildCandidateResult {
 	rows: number
 	places: number
 	primaries: number
 	aliases: number
+
 	/**
-	 * Region aliases refused because another same-country region holds the name as its official name (three pairs in the
-	 * admin artifact: `新竹市`, `嘉義市`, `충청남도`). Zero on a source without a `names` table means the rule had nothing to read,
-	 * not that no pair exists.
+	 * The count of region aliases dropped because another region in the same
+	 * country uses the name as its official name.
+	 *
+	 * The count is always zero for a source without a `names` table.
 	 */
 	regionOfficialRefused: number
 	abbrevs: number
 	postcodes: number
+
 	/**
-	 * Delivery-city (and other `names`-table) aliases folded onto postcode rows — #1495. Zero here means the extracts
-	 * carried no alias names, NOT that the pass was skipped: a extract with no `names` table reports that separately
-	 * through `onProgress`.
+	 * The count of aliases added to postcode rows from the extracts' `names` tables.
+	 *
+	 * An extract without a `names` table is reported through `onProgress`.
 	 */
 	postcodeAliases: number
+
 	/**
-	 * Closure rows in the `candidate_ancestor` sidecar (see candidate-ancestors-schema.ts). Zero means the source
-	 * `ancestors` table contributed nothing within the resolvable placetypes — a finding, reported rather than implied.
+	 * The count of closure rows written to the `candidate_ancestor` sidecar,
+	 * including rows from locality extracts.
 	 */
 	ancestorRows: number
+
 	/**
-	 * Places carrying at least one closure row.
+	 * The count of places with at least one closure row.
 	 */
 	ancestorPlaces: number
+
 	/**
-	 * Places that received a pre/post interval label — the canonical-parent forest's node count. Places outside it (no
-	 * recorded ancestry, extract rows, cycle-skipped) have NO label: containment against them is unverifiable, never
-	 * false.
+	 * The count of places that received a pre/post interval label.
+	 * It equals the node count of the canonical-parent forest.
+	 *
+	 * Containment against a place outside the forest is unknown.
 	 */
 	intervalPlaces: number
+
 	/**
-	 * Places that took an `importance` score from the join (#28).
+	 * The count of places that received an `importance` score.
 	 *
-	 * `undefined` and `0` mean different things. `undefined` is "the pass did not run" — no score source was given. A `0`
-	 * would be the source matching NOTHING, which is a finding. Never collapse the two.
+	 * It is `undefined` when no score source was given.
 	 */
 	importanceScored?: number
+
 	/**
-	 * Places whose `(name_key, country, placetype)` matched a scored group but whose nearest scored centroid was outside
-	 * {@link IMPORTANCE_JOIN_RADIUS_KM} — a different town wearing the same name, refused rather than scored.
+	 * The count of places that matched a scored group by name key, country and placetype
+	 * but whose nearest scored centroid lay beyond {@link IMPORTANCE_JOIN_RADIUS_KM}.
 	 *
-	 * Worth watching across rebuilds: a jump here means the score source and the admin source have drifted apart, and the
-	 * join is being asked to guess.
+	 * A large change between rebuilds means the score source and the admin source have diverged.
 	 */
 	importanceFiltered?: number
+
 	/**
-	 * Alias rows stamped `name_role = 'gloss'` — the anomaly detector's certain core (#1730).
+	 * The count of alias rows the gloss anomaly detector stamped `name_role = 'gloss'`.
 	 */
 	roleGloss: number
+
 	/**
-	 * Alias rows stamped `name_role = 'abbr'` — the variant-in-official-language provenance signal (#1730/#936).
+	 * The count of alias rows stamped `name_role = 'abbr'`, which marks a variant in the official language.
 	 */
 	roleAbbr: number
+
 	/**
-	 * Admin places whose staged key count reached {@link GLOSS_KEY_THRESHOLD} — the sweep's tail, reported so the stamped
-	 * fraction has its denominator.
+	 * The count of admin places whose staged key count reached the gloss key threshold.
+	 * It is the denominator for `keyTailWithRole`.
 	 */
 	keyTailPlaces: number
+
 	/**
-	 * Of {@link BuildCandidateResult.keyTailPlaces}, how many carry at least one stamped role row.
+	 * The count of places in `keyTailPlaces` with at least one stamped role row.
 	 */
 	keyTailWithRole: number
 }
 
+/**
+ * Builds the candidate lookup database from a WOF admin database and replaces any existing output.
+ * The builder adds an FTS5 trigram index for fuzzy lookup.
+ */
 export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult> {
 	const progress = opts.onProgress ?? (() => {})
 
@@ -224,15 +224,12 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	}
 
 	using src = new DatabaseClient<WOFDatabase>(opts.input, { readOnly: true })
-	await using kdb = new DatabaseClient<CandidateDatabase>(opts.output)
-	// Build-tuning pragmas (raw — Kysely doesn't model PRAGMA). The code dictionaries + the transient
-	// staging table come from the SHARED schema DDL, so they can't drift from {@link CandidateDatabase}.
+	using kdb = new DatabaseClient<CandidateDatabase>(opts.output)
+
 	kdb.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;")
 
 	await createCandidateStagingTables(kdb)
 
-	// Build compact country and placetype code maps for clustered keys.
-	// assigned here; the rows are bulk-inserted via kdb once the passes have discovered every code. ---
 	const ccodes = new Map<string, number>()
 	const ptcodes = new Map<string, number>()
 
@@ -260,8 +257,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		return id
 	}
 
-	// Load the importance source before the only pass that sees each place.
-	// name/country/placetype/centroid together. Absent → every row's `importance` stays NULL. ---
 	let importance: ReturnType<typeof loadImportanceIndex> | undefined
 
 	if (opts.importance) {
@@ -274,23 +269,13 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 				(importance.stats.unkeyable ? `; ${importance.stats.unkeyable.toLocaleString()} unkeyable names skipped` : "")
 		)
 	} else {
-		// Never a silent column of nulls: a build without a score source produces one, and the reason has
-		// to be visible in the log rather than inferred from the artifact.
 		progress("importance", "no score source given — `importance` will be NULL on every row")
 	}
 
-	// Derive each place's region ancestor for same-name disambiguation.
 	progress("region", "loading region ancestry")
 	const regionOf = new Map<number, number>()
 	let multiRegion = 0
 
-	// A place can carry more than one region-tier ancestor — 59 do on the 2026-08-03 artifact (42
-	// localities, mostly Chinese places on an ambiguous boundary). One `region_id` column holds one of
-	// them, and which one it ought to be is a real question this is not the place to answer.
-	//
-	// MIN is arbitrary but STABLE: an unordered pick lets the stamp for those places differ between two
-	// builds of the same source. The count is logged because the number is expected to grow, and should
-	// be visible rather than inferred.
 	for (const r of src
 		.prepare(
 			"SELECT id, MIN(ancestor_id) AS ancestor_id, COUNT(DISTINCT ancestor_id) AS n" +
@@ -310,12 +295,8 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			(multiRegion ? ` (${multiRegion.toLocaleString()} carry more than one; stamped with the lowest id)` : "")
 	)
 
-	// The hot path — millions of clustered rows. Kept a single positional prepared statement (the fastest
-	// node:sqlite insert) rather than a per-row query builder. Placeholders come from CANDIDATE_COLUMNS so
-	// the column COUNT can't drift; the positional run() args below MUST stay in CANDIDATE_COLUMNS order.
 	const insStage = kdb.prepare(`INSERT INTO cand_stage VALUES (${CANDIDATE_COLUMNS.map(() => "?").join(", ")})`)
 
-	// Stage primary names and attributes reused by later alias passes.
 	progress("primaries", "indexing place names")
 	const attrs = new Map<number, PlaceAttrs>()
 	let nPrim = 0
@@ -326,7 +307,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			`SELECT s.id AS id, s.name AS name, s.placetype AS placetype, s.country AS country,
 				s.latitude AS lat, s.longitude AS lon,
 				s.min_latitude AS mnlat, s.min_longitude AS mnlon, s.max_latitude AS mxlat, s.max_longitude AS mxlon,
-				COALESCE(pp.population,0) AS pop
+				pp.population AS pop
 			 FROM spr s LEFT JOIN place_population pp ON pp.id = s.id
 			 WHERE s.is_current != 0 AND s.is_deprecated = 0`
 		)
@@ -335,13 +316,14 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		const cid = ccID(r.country as string | null)
 		const ptid = ptID(r.placetype as string | null)
 		const rid = regionOf.get(sid) ?? 0
-		// A zero population on a COUNTRY row is a WOF absence artifact, never a real zero — 147 of 237
-		// primary country records carried none (measured 2026-08-18, #1650), which ranked those nations
-		// below any namesake hamlet in every prominence race ("Georgia" → Georgia VT). The codex table is
-		// the secondary source; a country absent from it too stays at zero honestly.
-		const wofPop = Number(r.pop) || 0
-		const pop = wofPop === 0 && r.placetype === "country" ? (COUNTRY_POPULATION[String(r.country ?? "")] ?? 0) : wofPop
-		const neg = -Math.log10(pop + 1)
+
+		const wofPop = r.pop === null || r.pop === undefined ? null : Number(r.pop)
+
+		const pop =
+			POPULATION_CORRECTIONS[sid]?.population ??
+			(wofPop === null && r.placetype === "country" ? (COUNTRY_POPULATION[String(r.country ?? "")] ?? null) : wofPop)
+
+		const neg = -Math.log10((pop ?? 0) + 1)
 		const name = String(r.name ?? "")
 		const pkey = normalizeLocalityForKey(name)
 		const lat = r.lat as number
@@ -424,9 +406,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		)
 	}
 
-	// Stage country display names across scripts.
-	// Never a silent zero: a runtime whose ICU lacks these locales degrades to fewer surfaces, and the count is how a
-	// reader tells that apart from the pass not having run.
 	progress(
 		"country-display-names",
 		`${stageCountryDisplayNames({
@@ -438,8 +417,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		}).toLocaleString()} country surfaces`
 	)
 
-	// Backfill cross-source currency before later candidate passes.
-	// the alias pass so a resurrected place's alt names explode like any primary's. ---
 	if (opts.currencyBackfill) {
 		const nBackfill = await resurrectCurrencyHoles({
 			src,
@@ -458,12 +435,9 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 
 		progress("currency-backfill", `${nBackfill.toLocaleString()} resurrections staged`)
 	} else {
-		// Never a silent absence: a build without the option leaves the deprecated-no-successor holes dead,
-		// and the log must say so rather than leave it inferable only from a missing row.
 		progress("currency-backfill", "not configured — deprecated-no-successor holes stay dead (#1737)")
 	}
 
-	// Stage distinct normalized aliases from alternate names.
 	progress("aliases", "exploding alias bags")
 
 	const { nAlias, keyCounts, regionOfficialRefused } = explodeAliasBags(src, kdb, attrs, stageRow, {
@@ -479,7 +453,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 				: "")
 	)
 
-	// Stage region abbreviations.
 	let nAbbr = 0
 	kdb.exec("BEGIN")
 
@@ -498,9 +471,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	kdb.exec("COMMIT")
 	progress("abbrevs", `${nAbbr.toLocaleString()} abbrevs`)
 
-	// Stamp each name's semantic role.
-	// Independent of the sidecar below: this writes `cand_stage.name_role`, that writes the ancestor and
-	// interval tables, and neither reads the other's output. Ordered by label only.
 	const roles = stampNameRoles({
 		src,
 		out: kdb,
@@ -512,10 +482,8 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress,
 	})
 
-	// Stage the encoded ancestors sidecar.
 	const sidecar = await buildAncestorsSidecar({ src, out: kdb, attrs, ptID, progress })
 
-	// Fold postcode and locality extracts into candidate records.
 	let nPostcode = 0
 	let nPostcodeAlias = 0
 
@@ -569,7 +537,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		)
 	}
 
-	// Insert the small typed code dictionaries through Kysely.
 	if (ccodes.size) {
 		await kdb
 			.insertInto("country_codes")
@@ -584,7 +551,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			.execute()
 	}
 
-	// Insert the small typed capital-status reference table.
 	if (opts.capitals?.length) {
 		await createCapitalTable<CandidateDatabase>(kdb)
 
@@ -596,7 +562,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 					latitude: entry.latitude,
 					longitude: entry.longitude,
 					level: entry.level,
-					keys: JSON.stringify(entry.k),
+					keys: stringifyJSON(entry.k),
 				}))
 			)
 			.execute()
@@ -604,25 +570,18 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("capitals", `${opts.capitals.length.toLocaleString()} capital-reference rows carried in-artifact`)
 	}
 
-	// Materialize the clustered WITHOUT ROWID table in sorted order.
 	progress("cluster", "building clustered candidate table + VACUUM")
-	// Column list + clustered-key order are sourced from CANDIDATE_COLUMNS (the first 6 ARE the PRIMARY
-	// KEY) so the SELECT, the ORDER BY, and the table can't drift. The table comes from the shared
-	// createCandidateTable().
+
 	const cols = CANDIDATE_COLUMNS.join(", ")
 	const keyOrder = CANDIDATE_COLUMNS.slice(0, 6).join(", ")
 	await createCandidateTable(kdb)
-	// OR IGNORE: an abbrev/alias can normalize to a place's primary key (same place, same rank) → any one
-	// row. The bulk sorted INSERT…SELECT (clustered materialization) stays raw — a single hot bulk statement.
+
 	kdb.exec(`INSERT OR IGNORE INTO candidate (${cols}) SELECT ${cols} FROM cand_stage ORDER BY ${keyOrder};`)
 	await kdb.schema.dropTable("cand_stage").execute()
-	// Typo-tolerant fallback index (the unified gazetteer's second mode): the exact name_key probe can't
-	// recover misspellings, so FTS5-trigram over `name` lets the reader fuzzy-match on an exact+strip miss.
+
 	progress("fts", "building FTS5-trigram fuzzy index")
 	createCandidateFTS(kdb)
-	// page_size MUST be set right before VACUUM: node:sqlite initializes the file at the 4096 default on
-	// `new DatabaseSync`, so the creation-time pragma is a no-op — only a VACUUM rebuilds at the new size.
-	// 8192 matches the sql.js-httpvfs 64 KiB request chunk cleanly (8 pages) and shallows the B-tree.
+
 	kdb.exec("PRAGMA page_size=8192")
 	kdb.exec("VACUUM")
 
@@ -631,7 +590,6 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		.select((eb) => eb.fn.countAll<number>().as("n"))
 		.executeTakeFirstOrThrow()
 
-	// closes the underlying `out` connection
 	return {
 		rows,
 		places: attrs.size,

package/lib/build/population-corrections.ts

@@ -0,0 +1,64 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Populations the gazetteer records at a fraction of their size, corrected against the record's own concordance.
+ *
+ *   This file records corrections for review. The build must not rewrite populations from a
+ *   same-name-parent ratio. The detector cannot distinguish a district's mis-recorded namesake
+ *   city from a small village with the district name. Both places are real.
+ *
+ *   Each entry identifies one row that a reviewer checked against a second source.
+ *   The row's own `gn:id` must agree with the coordinates. The GeoNames record must identify the same place.
+ *
+ *   The correction applies to the candidate artifact rather than the admin gazetteer.
+ *   `place_population` in `admin-global-priority.db` still stores the WOF figure, so a reader going
+ *   there sees WOF's value and a reader going to `candidate.db` sees the corroborated number. The
+ *   admin database is a transcription of its source, so correcting it there would make the
+ *   transcription disagree with what it transcribes.
+ */
+
+/**
+ * One corrected population, with what corroborates it.
+ */
+export interface PopulationCorrection {
+	/**
+	 * The GeoNames id from the WOF record's own `concordances` row makes this a
+	 * correction rather than a substitution.
+	 *
+	 * The two sources describe the same place according to WOF.
+	 */
+	geonamesID: string
+	population: number
+	/**
+	 * What the gazetteer recorded, kept so a reader can see the size of the
+	 * disagreement without opening the artifact.
+	 */
+	recorded: number
+	/**
+	 * The place and the reviewer's reading.
+	 */
+	note: string
+}
+
+/**
+ * WOF id → the corrected population.
+ *
+ * One entry, because one row has been followed.
+ * A second correction requires the same review.
+ *
+ * Read the row's `gn:id` and confirm the coordinates agree.
+ * Then record the second source's value.
+ */
+export const POPULATION_CORRECTIONS: Readonly<Record<number, PopulationCorrection>> = {
+	102_030_887: {
+		geonamesID: "1278149",
+		population: 1_175_116,
+		recorded: 19_172,
+		note:
+			"Aurangabad (Chhatrapati Sambhaji Nagar), Maharashtra. The WOF record sits at 19.870 / 75.349 and GeoNames " +
+			"1278149 — the id that record's own concordance names — sits at 19.878 / 75.342, about 1 km apart, classed " +
+			"`PPLA2`. WOF's 19,172 against its parent district's 3,701,282 is the 193x ratio that surfaced it; the " +
+			"corroborated figure makes the city 32% of its district rather than 0.5% of it.",
+	},
+}