@mailwoman/resolver-wof-sqlite 9.3.0 → 10.0.0

package/lib/address/index.ts

@@ -4,6 +4,6 @@
  * @author Teffen Ellis, et al.
  */
 
-export * from "#address/point"
-export * from "#address/point-interpolation"
-export * from "#address/point-schema"
+export * from "#address/point/index"
+export * from "#address/point/interpolation"
+export * from "#address/point/schema"

package/lib/address/{point.ts → point/index.ts}

@@ -15,13 +15,15 @@
  *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
  */
 
-import type { AddressPointHit, AddressPointLookup } from "@mailwoman/resolver"
+import type { AddressPointHit, AddressPointLookup } from "@mailwoman/core/resolver"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { AddressPointDatabase, AddressPointTable } from "#address/point-schema"
+import type { AddressPointDatabase, AddressPointTable } from "#address/point/schema"
 import { hasTable, prepareGet, type PreparedGet } from "#sqlite-utils"
 import {
+	normalizeHouseNumberForKey,
 	normalizeLocalityForKey,
+	normalizeLocalityForKeyLocale,
 	type NameKey,
 	type StreetKey,
 	streetKeyVariants,
@@ -53,6 +55,13 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		| PreparedGet<[postcode: string, locality: NameKey, street: StreetKey, number: string], AddressPointRow>
 		| undefined
 	readonly #byLocality: PreparedGet<[locality: NameKey, street: StreetKey, number: string], AddressPointRow> | undefined
+	/**
+	 * The scope key matched by its TAIL — a `zh` query that names the 鄉鎮市區 without its 縣市. Narrowed by the (street,
+	 * number) index first, so the LIKE walks the handful of rows that share the pair.
+	 */
+	readonly #byLocalityTail:
+		| PreparedGet<[street: StreetKey, number: string, tailPattern: string], AddressPointRow>
+		| undefined
 	readonly #byBbox:
 		| PreparedGet<
 				[street: StreetKey, number: string, minLat: number, maxLat: number, minLon: number, maxLon: number],
@@ -102,6 +111,12 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 				`SELECT ${SELECT_COLS} FROM address_point
 				 WHERE street_norm = ? AND number = ? AND lat BETWEEN ? AND ? AND lon BETWEEN ? AND ? LIMIT 1`
 			)
+
+			this.#byLocalityTail = prepareGet(
+				this.#db,
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND locality_norm LIKE ? LIMIT 1`
+			)
 		}
 	}
 
@@ -110,20 +125,33 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		number: string
 		postcode?: string
 		locality?: string
+		region?: string
+		subregion?: string
 		bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
 	}): AddressPointHit | null {
 		if (!this.#byPostcode || !this.#byLocality || !this.#byBbox) return null
-		const number = query.number.trim().toLowerCase()
+		const number = normalizeHouseNumberForKey(query.number, this.#locale)
 
 		if (!number) return null
 
+		// A `zh` extract scopes a point by 縣市 + 鄉鎮市區, the pair the parse tags `region` + `subregion`; the Taiwanese
+		// register carries no postcode and the parse no `locality`. The pair becomes the locality key here, on the
+		// reader that was built with the same fold, and a Latin extract never sees the two fields. A line that names
+		// only the 鄉鎮市區 (`中和區中興街281號`, 14.7% of the TW board) matches the stored pair by its tail instead.
+		const scoped =
+			this.#locale === "zh" && !query.locality && query.subregion
+				? query.region
+					? { ...query, locality: `${query.region}${query.subregion}` }
+					: { ...query, localityTail: normalizeLocalityForKeyLocale(query.subregion, "zh") }
+				: query
+
 		// Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
 		// collapse and the saint↔st register swap — each variant runs the FULL number ladder below, and
 		// the first variant to answer wins, so an attested literal key is never second-guessed.
 		let row: AddressPointRow | undefined
 
 		for (const streetNorm of streetKeyVariants(query.street, streetLocaleForSurface(query.street, this.#locale))) {
-			row = this.#findForKey(streetNorm, number, query)
+			row = this.#findForKey(streetNorm, number, scoped)
 
 			if (row) break
 		}
@@ -152,6 +180,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			number: string
 			postcode?: string
 			locality?: string
+			localityTail?: NameKey
 			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
 		}
 	) {
@@ -186,6 +215,19 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			}
 		}
 
+		// Sub-number fallback for the Taiwanese register: `14之12` is building 12 off number 14, `30附40` an attached
+		// number, stored as number `14` / `30` with the rest in `unit`. A query that kept the pair on the number span
+		// falls to the base number — the same adjacent-parcel approximation the letter-suffix rung makes, priced the
+		// same: on the 2,000-row served read the rows answered this way sit a median 256 m and at most 1.0 km from the
+		// building.
+		if (!row && this.#locale === "zh") {
+			const base = /^(\d+)(?:[之附]\d+)+$/u.exec(number)?.[1]
+
+			if (base) {
+				row = this.#probe(streetNorm, base, query)
+			}
+		}
+
 		return row
 	}
 
@@ -199,6 +241,7 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 		query: {
 			postcode?: string
 			locality?: string
+			localityTail?: NameKey
 			bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
 		}
 	): AddressPointRow | undefined {
@@ -226,6 +269,11 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 			row = this.#byLocality!(this.#localityKey(query.locality), streetNorm, number)
 		}
 
+		if (!row && query.localityTail && this.#byLocalityTail) {
+			// A Han key carries no `%` or `_`, so the tail is a literal suffix pattern.
+			row = this.#byLocalityTail(streetNorm, number, `%${query.localityTail}`)
+		}
+
 		// Bbox fall-through (#247): the point carries no postcode/locality of its own, but its coordinate falls
 		// inside the resolved locality's box. Only reached when the scoped probes missed AND a bbox was supplied.
 		if (!row && query.bbox) {
@@ -248,9 +296,9 @@ export class AddressPointSqliteLookup<DB extends AddressPointDatabase = AddressP
 	 * 13e Arrondissement" and "Paris" both hit; a no-op for every other locale.
 	 */
 	#localityKey(locality: string): NameKey {
-		return this.#locale === "fr"
-			? stripArrondissement(normalizeLocalityForKey(locality))
-			: normalizeLocalityForKey(locality)
+		if (this.#locale === "fr") return stripArrondissement(normalizeLocalityForKey(locality))
+
+		return normalizeLocalityForKeyLocale(locality, this.#locale)
 	}
 
 	/**

package/lib/address/{point-interpolation.ts → point/interpolation.ts}

@@ -33,15 +33,14 @@
  *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
  */
 
-import type { InterpolationLookup } from "@mailwoman/resolver"
+import type { InterpolationLookup } from "@mailwoman/core/resolver"
 import { haversineKm } from "@mailwoman/spatial"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { AddressPointDatabase } from "#address/point-schema"
+import type { AddressPointDatabase } from "#address/point/schema"
 import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "#interpolation"
 import { hasTable, prepareAll, type PreparedAll } from "#sqlite-utils"
 import { canonicalizeRouteKey, type RouteKey, streetKeyVariants } from "#street/normalize"
-
 /**
  * Extrapolation cap for a single-sided bracket: at most one pair-span beyond the nearest known point (`t = 2`). Past
  * it, the two-point line carries no evidence about the query number.

package/lib/ancestry/backfill.ts

@@ -45,10 +45,10 @@
  *   nothing.
  */
 
-import { readDirectoryEntries } from "@mailwoman/core/fs/readers"
 import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { join, resolvePath, type PathBuilderLike } from "path-ts"
+import { Globerator } from "spliterator/node/fs"
 
 import type { WOFDatabase } from "#schema"
 
@@ -88,7 +88,9 @@ export async function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promis
 		let names: string[]
 
 		try {
-			names = (await readDirectoryEntries(dir)).filter((e) => e.isDirectory()).map((e) => e.name)
+			names = (await Globerator.from("*", { cwd: dir, withFileTypes: true, onlyFiles: false }).toArray())
+				.filter((entry) => entry.isDirectory())
+				.map((entry) => entry.name)
 		} catch {
 			return
 		}

package/lib/ancestry/index.ts

@@ -15,10 +15,9 @@
  *   geocoding always does).
  */
 
+import { allRows } from "@mailwoman/core/utils"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { allRows } from "#sqlite-utils"
-
 /**
  * WOF placetype → containment depth, coarsest = 1. Higher = finer. Placetypes we never resolve (continent, empire, …)
  * map to 0 and sort last. NOT the same table as the FST's `PLACETYPE_ORDER` (fst-serialize.ts) — that one is a

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

@@ -44,20 +44,20 @@ 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"
-import { IMPORTANCE_JOIN_RADIUS_KM, loadImportanceIndex } from "#candidate-importance"
-import {
-	CANDIDATE_COLUMNS,
-	createCandidateStagingTables,
-	createCandidateTable,
-	type CandidateDatabase,
-} from "#candidate-schema"
 import { explodeAliasBags } from "#candidate/alias-bags"
-import { buildAncestorsSidecar } from "#candidate/ancestors-sidecar"
+import { buildAncestorsSidecar } from "#candidate/ancestors/sidecar"
 import { stageCountryDisplayNames } from "#candidate/country-display-names"
 import { foldExtract } from "#candidate/extract-fold"
+import { createCandidateFTS } from "#candidate/fts"
+import { IMPORTANCE_JOIN_RADIUS_KM, loadImportanceIndex } from "#candidate/importance"
 import { GLOSS_KEY_THRESHOLD, stampNameRoles } from "#candidate/name-roles"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import {
+	CANDIDATE_COLUMNS,
+	createCandidateStagingTables,
+	createCandidateTable,
+	type CandidateDatabase,
+} from "#candidate/schema"
 import { createCapitalTable } from "#capital-schema"
 import type { CapitalPoint } from "#capitals"
 import { resurrectCurrencyHoles } from "#currency-backfill"
@@ -97,9 +97,11 @@ export interface BuildCandidateOptions {
 	/**
 	 * 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.
+	 * 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.
 	 */
 	localities?: string[]
 	/**
@@ -151,6 +153,12 @@ export interface BuildCandidateResult {
 	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.
+	 */
+	regionOfficialRefused: number
 	abbrevs: number
 	postcodes: number
 	/**
@@ -223,7 +231,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 
 	await createCandidateStagingTables(kdb)
 
-	// --- compact code maps (country/placetype → small int, shrinks the clustered key). The ids are
+	// 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>()
@@ -252,7 +260,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		return id
 	}
 
-	// --- importance source (#28): loaded BEFORE pass 1, which is the only pass that sees a place's
+	// 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
 
@@ -271,7 +279,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("importance", "no score source given — `importance` will be NULL on every row")
 	}
 
-	// --- region_id per place (its region-tier ancestor) for same-name disambiguation ---
+	// Derive each place's region ancestor for same-name disambiguation.
 	progress("region", "loading region ancestry")
 	const regionOf = new Map<number, number>()
 	let multiRegion = 0
@@ -307,7 +315,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	// 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(", ")})`)
 
-	// --- pass 1: primaries (and the per-place attrs the alias/abbrev passes reuse) ---
+	// Stage primary names and attributes reused by later alias passes.
 	progress("primaries", "indexing place names")
 	const attrs = new Map<number, PlaceAttrs>()
 	let nPrim = 0
@@ -416,7 +424,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		)
 	}
 
-	// --- pass 1b: country surfaces across scripts (#1678 thread 1) — see stageCountryDisplayNames ---
+	// 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(
@@ -430,7 +438,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		}).toLocaleString()} country surfaces`
 	)
 
-	// --- pass 1c: cross-source currency backfill (#1737 — resurrectCurrencyHoles owns the checks). Runs BEFORE
+	// 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({
@@ -455,12 +463,23 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress("currency-backfill", "not configured — deprecated-no-successor holes stay dead (#1737)")
 	}
 
-	// --- pass 2: distinct normalized aliases from place_search.alt_names (explodeAliasBags owns the loop) ---
+	// Stage distinct normalized aliases from alternate names.
 	progress("aliases", "exploding alias bags")
-	const { nAlias, keyCounts } = explodeAliasBags(src, kdb, attrs, stageRow)
-	progress("aliases", `${nAlias.toLocaleString()} aliases`)
 
-	// --- pass 3: region abbreviations (place_abbr) ---
+	const { nAlias, keyCounts, regionOfficialRefused } = explodeAliasBags(src, kdb, attrs, stageRow, {
+		regionPlacetypeID: ptID("region"),
+		ccID,
+	})
+
+	progress(
+		"aliases",
+		`${nAlias.toLocaleString()} aliases` +
+			(regionOfficialRefused
+				? `; ${regionOfficialRefused.toLocaleString()} region aliases refused as another region's official name`
+				: "")
+	)
+
+	// Stage region abbreviations.
 	let nAbbr = 0
 	kdb.exec("BEGIN")
 
@@ -479,7 +498,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	kdb.exec("COMMIT")
 	progress("abbrevs", `${nAbbr.toLocaleString()} abbrevs`)
 
-	// --- pass 3b: name roles (#1730 prototype — stampNameRoles owns the detectors) ---
+	// 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({
@@ -493,10 +512,10 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		progress,
 	})
 
-	// --- pass 3c: the ancestors sidecar (candidate-ancestors-schema.ts owns the encoding decision) ---
+	// Stage the encoded ancestors sidecar.
 	const sidecar = await buildAncestorsSidecar({ src, out: kdb, attrs, ptID, progress })
 
-	// --- pass 4 + 4b: postcode and locality extracts (foldExtract owns the per-extract loop) ---
+	// Fold postcode and locality extracts into candidate records.
 	let nPostcode = 0
 	let nPostcodeAlias = 0
 
@@ -520,6 +539,8 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	}
 
 	let nLocality = 0
+	let nLocalityScoped = 0
+	let nLocalityAncestor = 0
 
 	for (const locDB of opts.localities ?? []) {
 		const folded = foldExtract({
@@ -529,17 +550,26 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			ccID,
 			ptID,
 			stageRow,
+			attrs,
 			progress,
 		})
 
 		nLocality += folded.primaries
+		nLocalityScoped += folded.scoped
+		nLocalityAncestor += folded.ancestorRows
 	}
 
 	if (nLocality > 0) {
-		progress("localities", `${nLocality.toLocaleString()} extract localities folded`)
+		progress(
+			"localities",
+			`${nLocality.toLocaleString()} extract localities folded` +
+				(nLocalityScoped
+					? `; ${nLocalityScoped.toLocaleString()} carry a region scope (${nLocalityAncestor.toLocaleString()} closure rows)`
+					: "")
+		)
 	}
 
-	// --- code dictionaries: typed batch inserts via kdb (a few hundred rows — Kysely is clean here) ---
+	// Insert the small typed code dictionaries through Kysely.
 	if (ccodes.size) {
 		await kdb
 			.insertInto("country_codes")
@@ -554,7 +584,7 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			.execute()
 	}
 
-	// --- capital-status reference (#1880's distribution home) — cold, small (~3.7k rows), typed ---
+	// Insert the small typed capital-status reference table.
 	if (opts.capitals?.length) {
 		await createCapitalTable<CandidateDatabase>(kdb)
 
@@ -574,7 +604,7 @@ 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 (sorted insert → contiguous leaves) ---
+	// 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
@@ -607,11 +637,12 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		places: attrs.size,
 		primaries: nPrim,
 		aliases: nAlias,
+		regionOfficialRefused,
 		abbrevs: nAbbr,
 		postcodes: nPostcode,
 		postcodeAliases: nPostcodeAlias,
-		ancestorRows: sidecar.ancestorRows,
-		ancestorPlaces: sidecar.ancestorPlaces,
+		ancestorRows: sidecar.ancestorRows + nLocalityAncestor,
+		ancestorPlaces: sidecar.ancestorPlaces + nLocalityScoped,
 		intervalPlaces: sidecar.intervalPlaces,
 		...roles,
 		...(importance ? { importanceScored: importance.matched, importanceFiltered: importance.refused } : {}),

package/lib/candidate/alias-bags.ts

@@ -6,33 +6,83 @@
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import type { CandidateDatabase } from "#candidate-schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import { ALIAS_SEPARATOR } from "#fts/index"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
+/**
+ * The official name of every current region, keyed `${country id}\0${name key}` → region id, from the source `names`
+ * table's `official` bit. Empty when the source carries no `names` table (a fixture, or an extract shape).
+ *
+ * This is the positive evidence behind the one alias refusal below: a name is refused from a region's bag ONLY when
+ * another region of the same country holds it as its official name. Three such pairs exist in the admin artifact —
+ * `新竹市` on Hsinchu County (the city's official name), `嘉義市` on Chiayi County, `충청남도` on Sejong — and each let the more
+ * populous holder of the variant outrank the place the name officially is, so a `新竹市` region node resolved the county
+ * and every district scoped to the city contradicted it.
+ */
+function officialNameHoldersByRegion(
+	src: DatabaseClient<WOFDatabase>,
+	ccID: (code: string | null) => number
+): Map<string, number> {
+	const keys = new Map<string, number>()
+
+	if (!tableExists(src, "names")) return keys
+
+	for (const r of src
+		.prepare(
+			`SELECT n.id AS id, n.name AS name, s.country AS country
+			 FROM names n JOIN spr s ON s.id = n.id
+			 WHERE s.placetype = 'region' AND s.is_current != 0 AND s.is_deprecated = 0 AND n.official = 1`
+		)
+		.iterate()) {
+		const k = normalizeLocalityForKey(String(r.name ?? ""))
+
+		if (k) {
+			keys.set(`${ccID(r.country as string | null)}\0${k}`, Number(r.id))
+		}
+	}
+
+	return keys
+}
+
 /**
  * Pass 2 — explode each place's `place_search.alt_names` bag into distinct-key alias rows (`is_primary = 0`), and count
  * each place's distinct staged keys (primary included) — the gloss detector's key-count signal (#1730).
+ *
+ * With `regionPlacetypeID` and `ccID` given, a REGION's alias that is another same-country region's official name is
+ * refused and counted rather than staged (see {@link officialNameHoldersByRegion}); without them the pass stages every
+ * alias.
  */
 export function explodeAliasBags(
 	src: DatabaseClient<WOFDatabase>,
 	out: DatabaseClient<CandidateDatabase>,
 	attrs: Map<number, PlaceAttrs>,
-	stageRow: StageRow
-): { nAlias: number; keyCounts: Map<number, number> } {
+	stageRow: StageRow,
+	opts: { regionPlacetypeID?: number; ccID?: (code: string | null) => number } = {}
+): { nAlias: number; keyCounts: Map<number, number>; regionOfficialRefused: number } {
 	let nAlias = 0
+	let regionOfficialRefused = 0
 	const keyCounts = new Map<number, number>()
+
+	const official =
+		typeof opts.regionPlacetypeID === "number" && opts.ccID
+			? officialNameHoldersByRegion(src, opts.ccID)
+			: new Map<string, number>()
+
 	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 id = Number(r.wof_id)
+		const a = attrs.get(id)
 		const alt = r.alt_names as string | null
 
 		if (!a || !alt) continue
 		const seen = new Set<string>([a.pkey])
+		const isRegion = a.ptid === opts.regionPlacetypeID
 
 		// The writer space-pads each separator and appends a trailing one, so every piece arrives with
 		// surrounding whitespace and the last one is empty. `normalizeLocalityForKey` folds both away,
@@ -42,15 +92,26 @@ export function explodeAliasBags(
 
 			if (!k || seen.has(k)) continue
 			seen.add(k)
-			stageRow(k, a, Number(r.wof_id), 0)
+
+			if (isRegion) {
+				const holder = official.get(`${a.cid}\0${k}`)
+
+				if (typeof holder === "number" && holder !== id) {
+					regionOfficialRefused++
+
+					continue
+				}
+			}
+
+			stageRow(k, a, id, 0)
 
 			nAlias++
 		}
 
-		keyCounts.set(Number(r.wof_id), seen.size)
+		keyCounts.set(id, seen.size)
 	}
 
 	out.exec("COMMIT")
 
-	return { nAlias, keyCounts }
+	return { nAlias, keyCounts, regionOfficialRefused }
 }

package/lib/{candidate-ancestors-schema.ts → candidate/ancestors/schema.ts}

@@ -59,7 +59,7 @@ import { sql, type Kysely } from "kysely"
 // Type-only and circular on purpose (candidate-schema extends CandidateAncestorsDatabase): Kysely's
 // DB parameter is invariant, so the DDL functions must take the FULL database type their caller
 // holds. Erased at runtime.
-import type { CandidateDatabase } from "#candidate-schema"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { NameKey } from "#street/normalize"
 
 /**

package/lib/candidate/{ancestors-sidecar.ts → ancestors/sidecar.ts}

@@ -15,9 +15,9 @@ import {
 	createCandidateAncestorTable,
 	createCandidateIntervalTable,
 	MAX_ANCESTOR_DEPTH,
-} from "#candidate-ancestors-schema"
-import type { CandidateDatabase } from "#candidate-schema"
+} from "#candidate/ancestors/schema"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 
 /**