@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/{build-candidate.ts → lib/build-candidate.ts}

@@ -22,7 +22,7 @@
  *
  *   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 shard uses, so build/query stay consistent by construction.
+ *   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%.
@@ -32,27 +32,43 @@
  *   `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 { existsSync, rmSync } from "node:fs"
-import { DatabaseSync } from "node:sqlite"
-
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import { COUNTRY_POPULATION } from "@mailwoman/codex/country"
+import { pathExists } from "@mailwoman/core/fs/readers"
+import { removePath } from "@mailwoman/core/fs/writers"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { createCandidateFTS } from "./candidate-fts.ts"
-import { IMPORTANCE_JOIN_GATE_KM, loadImportanceIndex } from "./candidate-importance.ts"
+import { createCandidateFTS } from "#candidate-fts"
+import { IMPORTANCE_JOIN_RADIUS_KM, loadImportanceIndex } from "#candidate-importance"
 import {
 	CANDIDATE_COLUMNS,
 	createCandidateStagingTables,
 	createCandidateTable,
 	type CandidateDatabase,
-} from "./candidate-schema.ts"
-import { normalizeLocalityForKey } from "./street-normalize.ts"
-
-/**
- * Boundary-preserving alias-bag separator (#523, U+E000).
- */
-const ALIAS_SEP = "\u{E000}"
+} from "#candidate-schema"
+import { explodeAliasBags } from "#candidate/alias-bags"
+import { buildAncestorsSidecar } from "#candidate/ancestors-sidecar"
+import { stageCountryDisplayNames } from "#candidate/country-display-names"
+import { foldExtract } from "#candidate/extract-fold"
+import { GLOSS_KEY_THRESHOLD, stampNameRoles } from "#candidate/name-roles"
+import type { PlaceAttrs } from "#candidate/place-attrs"
+import { createCapitalTable } from "#capital-schema"
+import type { CapitalPoint } from "#capitals"
+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.
+export { stageCountryDisplayNames } from "#candidate/country-display-names"
+export { GLOSS_EXCLUDED_PLACETYPES, GLOSS_KEY_THRESHOLD } from "#candidate/name-roles"
+export type { PlaceAttrs } from "#candidate/place-attrs"
 
 export interface BuildCandidateOptions {
 	/**
@@ -64,14 +80,28 @@ export interface BuildCandidateOptions {
 	 */
 	output: string
 	/**
-	 * Optional postcode shards (`spr` rows with `placetype='postalcode'` + real coords, e.g. postalcode-us.db) — folded
+	 * 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.
+	 */
+	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.
 	 *
-	 * Each shard's `names` table is folded in too (#1495) — that's where the GeoNames delivery-city names live
+	 * 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.
 	 */
 	postcodes?: string[]
+	/**
+	 * 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 no region scope and 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.
+	 */
+	localities?: string[]
 	/**
 	 * 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
@@ -84,10 +114,36 @@ export interface BuildCandidateOptions {
 	 * population-derived stand-in written into a column that means fame.
 	 */
 	importance?: string
+	/**
+	 * 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.
+	 */
+	currencyBackfill?: {
+		geonamesDir: string
+		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.
+		 */
+		deadPlacetypes?: readonly string[]
+	}
 	/**
 	 * Optional progress callback for CLI / test introspection.
 	 */
 	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).
+	 */
+	glossKeyThreshold?: number
 }
 
 export interface BuildCandidateResult {
@@ -98,11 +154,26 @@ export interface BuildCandidateResult {
 	abbrevs: number
 	postcodes: number
 	/**
-	 * Delivery-city (and other `names`-table) aliases folded onto postcode rows — #1495. Zero here means the shards
-	 * carried no alias names, NOT that the pass was skipped: a shard with no `names` table reports that separately
+	 * 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`.
 	 */
 	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.
+	 */
+	ancestorRows: number
+	/**
+	 * Places carrying 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.
+	 */
+	intervalPlaces: number
 	/**
 	 * Places that took an `importance` score from the join (#28).
 	 *
@@ -112,49 +183,44 @@ export interface BuildCandidateResult {
 	importanceScored?: number
 	/**
 	 * Places whose `(name_key, country, placetype)` matched a scored group but whose nearest scored centroid was outside
-	 * {@link IMPORTANCE_JOIN_GATE_KM} — a different town wearing the same name, refused rather than scored.
+	 * {@link IMPORTANCE_JOIN_RADIUS_KM} — a different town wearing the same name, refused rather than scored.
 	 *
 	 * 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.
 	 */
-	importanceGated?: number
-}
-
-interface PlaceAttrs {
-	cid: number
-	rid: number
-	ptid: number
-	name: string
-	lat: number
-	lon: number
-	mnLat: number
-	mnLon: number
-	mxLat: number
-	mxLon: number
-	pop: number
-	neg: number
-	pkey: string
+	importanceFiltered?: number
+	/**
+	 * Alias rows stamped `name_role = 'gloss'` — the anomaly detector's certain core (#1730).
+	 */
+	roleGloss: number
+	/**
+	 * Alias rows stamped `name_role = 'abbr'` — the variant-in-official-language provenance signal (#1730/#936).
+	 */
+	roleAbbr: number
 	/**
-	 * The place's toponym-fame score, or null when the score source has no measurement for it (#28). A property of the
-	 * PLACE, so it rides {@link stageRow} onto the alias and abbrev rows too — that is how a bare `Moscow` reaches
-	 * Москва's score through the alias row that carries the key.
+	 * Admin places whose staged key count reached {@link GLOSS_KEY_THRESHOLD} — the sweep's tail, reported so the stamped
+	 * fraction has its denominator.
 	 */
-	imp: number | null
+	keyTailPlaces: number
+	/**
+	 * Of {@link BuildCandidateResult.keyTailPlaces}, how many carry at least one stamped role row.
+	 */
+	keyTailWithRole: number
 }
 
 export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult> {
 	const progress = opts.onProgress ?? (() => {})
 
-	if (existsSync(opts.output)) {
-		rmSync(opts.output)
+	if (await pathExists(opts.output)) {
+		await removePath(opts.output)
 	}
 
-	const src = new DatabaseSync(opts.input, { readOnly: true })
-	const out = new DatabaseSync(opts.output)
+	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}.
-	out.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;")
-	const kdb = new DatabaseClient<CandidateDatabase>({ database: out })
+	kdb.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;")
+
 	await createCandidateStagingTables(kdb)
 
 	// --- compact code maps (country/placetype → small int, shrinks the clustered key). The ids are
@@ -239,13 +305,13 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	// 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 = out.prepare(`INSERT INTO cand_stage VALUES (${CANDIDATE_COLUMNS.map(() => "?").join(", ")})`)
+	const insStage = kdb.prepare(`INSERT INTO cand_stage VALUES (${CANDIDATE_COLUMNS.map(() => "?").join(", ")})`)
 
 	// --- pass 1: primaries (and the per-place attrs the alias/abbrev passes reuse) ---
 	progress("primaries", "indexing place names")
 	const attrs = new Map<number, PlaceAttrs>()
 	let nPrim = 0
-	out.exec("BEGIN")
+	kdb.exec("BEGIN")
 
 	for (const r of src
 		.prepare(
@@ -261,7 +327,12 @@ 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
-		const pop = Number(r.pop) || 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 name = String(r.name ?? "")
 		const pkey = normalizeLocalityForKey(name)
@@ -304,21 +375,22 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 				a.mxLon,
 				pop,
 				1,
-				a.imp
+				a.imp,
+				null
 			)
 
 			nPrim++
 		}
 	}
 
-	out.exec("COMMIT")
+	kdb.exec("COMMIT")
 	progress("primaries", `${nPrim.toLocaleString()} primaries; ${attrs.size.toLocaleString()} places`)
 
 	if (importance) {
 		progress(
 			"importance",
 			`${importance.matched.toLocaleString()} places scored; ` +
-				`${importance.gated.toLocaleString()} refused (nearest same-name place > ${IMPORTANCE_JOIN_GATE_KM} km away)`
+				`${importance.refused.toLocaleString()} refused (nearest same-name place > ${IMPORTANCE_JOIN_RADIUS_KM} km away)`
 		)
 	}
 
@@ -339,39 +411,58 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			a.mxLon,
 			a.pop,
 			isPrimary,
-			a.imp
+			a.imp,
+			null
 		)
 	}
 
-	// --- pass 2: distinct normalized aliases from place_search.alt_names ---
-	progress("aliases", "exploding alias bags")
-	let nAlias = 0
-	out.exec("BEGIN")
-
-	for (const r of src.prepare("SELECT wof_id, alt_names FROM place_search").iterate()) {
-		const a = attrs.get(Number(r.wof_id))
-		const alt = r.alt_names as string | null
-
-		if (!a || !alt) continue
-		const seen = new Set<string>([a.pkey])
-
-		for (const piece of alt.split(ALIAS_SEP)) {
-			const k = normalizeLocalityForKey(piece)
-
-			if (!k || seen.has(k)) continue
-			seen.add(k)
-			stageRow(k, a, Number(r.wof_id), 0)
+	// --- pass 1b: country surfaces across scripts (#1678 thread 1) — see stageCountryDisplayNames ---
+	// 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({
+			attrs,
+			iso2ByID: new Map([...ccodes].map(([code, id]) => [id, code])),
+			countryPtID: ptID("country"),
+			stageRow,
+			tx: kdb,
+		}).toLocaleString()} country surfaces`
+	)
 
-			nAlias++
-		}
+	// --- pass 1c: cross-source currency backfill (#1737 — resurrectCurrencyHoles owns the checks). Runs BEFORE
+	// the alias pass so a resurrected place's alt names explode like any primary's. ---
+	if (opts.currencyBackfill) {
+		const nBackfill = await resurrectCurrencyHoles({
+			src,
+			tx: kdb,
+			geonamesDir: opts.currencyBackfill.geonamesDir,
+			countries: opts.currencyBackfill.countries,
+			...(opts.currencyBackfill.deadPlacetypes ? { deadPlacetypes: opts.currencyBackfill.deadPlacetypes } : {}),
+			attrs,
+			ccID,
+			ptID,
+			regionOf,
+			importance,
+			stageRow,
+			progress,
+		})
+
+		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)")
 	}
 
-	out.exec("COMMIT")
+	// --- pass 2: distinct normalized aliases from place_search.alt_names (explodeAliasBags owns the loop) ---
+	progress("aliases", "exploding alias bags")
+	const { nAlias, keyCounts } = explodeAliasBags(src, kdb, attrs, stageRow)
 	progress("aliases", `${nAlias.toLocaleString()} aliases`)
 
 	// --- pass 3: region abbreviations (place_abbr) ---
 	let nAbbr = 0
-	out.exec("BEGIN")
+	kdb.exec("BEGIN")
 
 	for (const r of src.prepare("SELECT id, abbr FROM place_abbr").iterate()) {
 		const a = attrs.get(Number(r.id))
@@ -385,128 +476,40 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		nAbbr++
 	}
 
-	out.exec("COMMIT")
+	kdb.exec("COMMIT")
 	progress("abbrevs", `${nAbbr.toLocaleString()} abbrevs`)
 
-	/**
-	 * Pass 4 — fold ONE postcode shard (`spr` rows with `placetype='postalcode'`) in, then pass 4b: the delivery-city
-	 * aliases hanging off the same shard's `names` table.
-	 *
-	 * Extracted rather than inlined because the shard loop is self-contained — it shares only the staging statement and
-	 * the code dictionaries with the passes above, and nothing after it reads anything it produces except the two
-	 * counters it returns.
-	 */
-	const foldPostcodeShard = (pcDB: string): { primaries: number; aliases: number } => {
-		progress("postcodes", `reading ${pcDB}`)
-
-		const pc = new DatabaseSync(pcDB, { readOnly: true })
-		const pcPtid = ptID("postalcode")
-		// Per-shard, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
-		// below has nothing to join against unless this primary loop records what it staged.
-		const pcAttrs = new Map<number, PlaceAttrs>()
-		let primaries = 0
-		let aliases = 0
-
-		out.exec("BEGIN")
-
-		for (const r of pc
-			.prepare(
-				`SELECT id, name, country, latitude, longitude,
-					min_latitude AS mnlat, min_longitude AS mnlon, max_latitude AS mxlat, max_longitude AS mxlon
-				 FROM spr WHERE placetype='postalcode' AND latitude != 0 AND longitude != 0`
-			)
-			.iterate()) {
-			const name = String(r.name ?? "")
-			const key = normalizeLocalityForKey(name)
-
-			if (!key) continue
-
-			const lat = r.latitude as number
-			const lon = r.longitude as number
-
-			// region_id 0 (a postcode is unique by name+country — no same-name disambiguation); neg_rank 0
-			// (no population). bbox = the postcode's own min/max (falls back to the centroid point).
-			const a: PlaceAttrs = {
-				cid: ccID(r.country as string | null),
-				rid: 0,
-				ptid: pcPtid,
-				name,
-				lat,
-				lon,
-				mnLat: (r.mnlat as number) || lat,
-				mnLon: (r.mnlon as number) || lon,
-				mxLat: (r.mxlat as number) || lat,
-				mxLon: (r.mxlon as number) || lon,
-				pop: 0,
-				neg: 0,
-				pkey: key,
-				// A postcode has no toponym fame — nobody writes an encyclopedia article about SW1A 2AA — and
-				// the score source carries no `postalcode` rows to join against anyway. NULL is the truthful
-				// value: unmeasured, so the ranking key leaves postcode rows exactly where they were.
-				imp: null,
-			}
-
-			pcAttrs.set(Number(r.id), a)
-			stageRow(key, a, Number(r.id), 1)
-
-			primaries++
-		}
-
-		out.exec("COMMIT")
-
-		// --- pass 4b: postcode ALIAS names (#1495) ---
-		//
-		// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
-		// the shard's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
-		// downstream of `names` picked them up EXCEPT this build: `fts.ts` unions `spr.name` with every
-		// `names` row into `place_search.alt_names`, so the FTS backend resolved "Brooklyn" → 11201
-		// while the candidate backend — whose every row IS an exact-tier row — had no key for it at
-		// all. Pass 2 does the equivalent fold for admin places, but reads the ADMIN `place_search`,
-		// and `attrs` holds admin ids only, so a postcode shard could never reach it.
-		//
-		// Same discipline as pass 2: `is_primary = 0` (so `rankByPrimaryPreference` treats it as an
-		// alias, not a canonical postcode name), the row stays denormalized onto the POSTCODE's own
-		// spr_id/coords/bbox, and the display `name` stays the postcode — resolving "brooklyn" answers
-		// with place 11201, it does not rename the place to its delivery city.
-		const hasNames = pc.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='names'").get() !== undefined
-
-		if (hasNames) {
-			out.exec("BEGIN")
-
-			for (const r of pc.prepare("SELECT id, name FROM names").iterate()) {
-				const a = pcAttrs.get(Number(r.id))
-
-				if (!a) continue
-
-				const k = normalizeLocalityForKey(String(r.name ?? ""))
-
-				// The postcode's own key is already staged as the primary; `INSERT OR IGNORE` at
-				// materialization dedupes repeats, so this only skips the obvious self-alias.
-				if (!k || k === a.pkey) continue
-
-				stageRow(k, a, Number(r.id), 0)
-
-				aliases++
-			}
-
-			out.exec("COMMIT")
-		} else {
-			// Never a silent zero: real shards come from `createUnifiedSchema`, which always creates
-			// `names`. A shard without it has no alias surface to lose, but say so rather than reporting
-			// "0 aliases" from a table that was never read.
-			progress("postcode-aliases", `${pcDB} has no \`names\` table — no delivery-city aliases to fold`)
-		}
-
-		pc.close()
-
-		return { primaries, aliases }
-	}
-
+	// --- pass 3b: name roles (#1730 prototype — stampNameRoles owns the detectors) ---
+	// 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,
+		attrs,
+		keyCounts,
+		glossThreshold: opts.glossKeyThreshold ?? GLOSS_KEY_THRESHOLD,
+		ptcodes,
+		ccodes,
+		progress,
+	})
+
+	// --- pass 3c: the ancestors sidecar (candidate-ancestors-schema.ts owns the encoding decision) ---
+	const sidecar = await buildAncestorsSidecar({ src, out: kdb, attrs, ptID, progress })
+
+	// --- pass 4 + 4b: postcode and locality extracts (foldExtract owns the per-extract loop) ---
 	let nPostcode = 0
 	let nPostcodeAlias = 0
 
 	for (const pcDB of opts.postcodes ?? []) {
-		const folded = foldPostcodeShard(pcDB)
+		const folded = foldExtract({
+			out: kdb,
+			extractPath: pcDB,
+			extractPlacetype: "postalcode",
+			ccID,
+			ptID,
+			stageRow,
+			progress,
+		})
 
 		nPostcode += folded.primaries
 		nPostcodeAlias += folded.aliases
@@ -516,6 +519,26 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("postcodes", `${nPostcode.toLocaleString()} postcodes; ${nPostcodeAlias.toLocaleString()} aliases`)
 	}
 
+	let nLocality = 0
+
+	for (const locDB of opts.localities ?? []) {
+		const folded = foldExtract({
+			out: kdb,
+			extractPath: locDB,
+			extractPlacetype: "locality",
+			ccID,
+			ptID,
+			stageRow,
+			progress,
+		})
+
+		nLocality += folded.primaries
+	}
+
+	if (nLocality > 0) {
+		progress("localities", `${nLocality.toLocaleString()} extract localities folded`)
+	}
+
 	// --- code dictionaries: typed batch inserts via kdb (a few hundred rows — Kysely is clean here) ---
 	if (ccodes.size) {
 		await kdb
@@ -531,6 +554,26 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			.execute()
 	}
 
+	// --- capital-status reference (#1880's distribution home) — cold, small (~3.7k rows), typed ---
+	if (opts.capitals?.length) {
+		await createCapitalTable<CandidateDatabase>(kdb)
+
+		await kdb
+			.insertInto("capital")
+			.values(
+				opts.capitals.map((entry) => ({
+					country: entry.country,
+					latitude: entry.latitude,
+					longitude: entry.longitude,
+					level: entry.level,
+					keys: JSON.stringify(entry.k),
+				}))
+			)
+			.execute()
+
+		progress("capitals", `${opts.capitals.length.toLocaleString()} capital-reference rows carried in-artifact`)
+	}
+
 	// --- materialize the clustered WITHOUT ROWID table (sorted insert → contiguous leaves) ---
 	progress("cluster", "building clustered candidate table + VACUUM")
 	// Column list + clustered-key order are sourced from CANDIDATE_COLUMNS (the first 6 ARE the PRIMARY
@@ -541,26 +584,23 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	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.
-	out.exec(`INSERT OR IGNORE INTO candidate (${cols}) SELECT ${cols} FROM cand_stage ORDER BY ${keyOrder};`)
+	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(out)
+	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.
-	out.exec("PRAGMA page_size=8192")
-	out.exec("VACUUM")
+	kdb.exec("PRAGMA page_size=8192")
+	kdb.exec("VACUUM")
 
 	const { n: rows } = await kdb
 		.selectFrom("candidate")
 		.select((eb) => eb.fn.countAll<number>().as("n"))
 		.executeTakeFirstOrThrow()
 
-	src.close()
-	await kdb.destroy()
-
 	// closes the underlying `out` connection
 	return {
 		rows,
@@ -570,6 +610,10 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		abbrevs: nAbbr,
 		postcodes: nPostcode,
 		postcodeAliases: nPostcodeAlias,
-		...(importance ? { importanceScored: importance.matched, importanceGated: importance.gated } : {}),
+		ancestorRows: sidecar.ancestorRows,
+		ancestorPlaces: sidecar.ancestorPlaces,
+		intervalPlaces: sidecar.intervalPlaces,
+		...roles,
+		...(importance ? { importanceScored: importance.matched, importanceFiltered: importance.refused } : {}),
 	}
 }