@mailwoman/resolver-wof-sqlite 8.6.0 → 9.1.0

package/ancestry-backfill.ts

@@ -3,9 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Repair the only-self ancestry that {@link populateAncestors} (the parent_id closure in
- *   unified-schema.ts) leaves for places whose `wof:parent_id` is the WOF `-4` "ambiguous /
- *   multi-parent" sentinel.
+ *   Repair the truncated ancestry that {@link populateAncestors} (the parent_id closure in
+ *   unified-schema.ts) leaves wherever the closure dead-ends before reaching the top.
  *
  *   Root cause (#440 / #832): a place that straddles multiple parents — New York City spans five
  *   counties (its boroughs), London 30+ — carries `wof:parent_id = -4`, so the parent_id closure
@@ -14,22 +13,47 @@
  *   a correctly-parented namesake ("New York Mills", pop 3,190) wins over NYC's 8.8M. The same defect
  *   orphans London, Singapore, and ~2,850 other localities — the most demo-visible queries.
  *
+ *   **The dead end is inherited by children (#1445).** Repairing the `-4` place itself does not repair
+ *   anything BELOW it: the closure walks Brooklyn → New York and stops, because New York's own
+ *   `parent_id` is `-4`. Brooklyn-the-borough (pop 2.5M) therefore carried exactly two ancestor rows —
+ *   itself and New York — with no county, region or country, and the only US locality-tier place named
+ *   "Brooklyn" that survived a New-York-State descendant filter was Pillar Point, a Jefferson County
+ *   hamlet 411 km away carrying "Brooklyn" as an alternate name. All five NYC boroughs, every London
+ *   borough and Hyderabad's zones were in the same state.
+ *
+ *   So the candidate test is NOT "has only a self ancestor" — that misses every child of a repaired
+ *   place, which by construction has two. It is **"has no `country`-tier ancestor"**. Country is the
+ *   universal terminal for every non-{@link TOP_PLACETYPES} placetype, so its absence is exactly the
+ *   signal that the chain dead-ended somewhere, at whatever depth. On a wide-coverage build this
+ *   selects ~24k places against 2.55M rows.
+ *
+ *   A place whose `wof:hierarchy` genuinely stops short is NOT a candidate and needs no repair: the
+ *   source is the authority on what a place should have. American Samoa's localities, for instance,
+ *   have `{country_id, locality_id}` and no region in WOF itself — the artifact matching that is
+ *   correct, not truncated.
+ *
  *   The authoritative hierarchy IS in the source geojson: `wof:hierarchy` is an array of branches,
  *   each a `<placetype>_id` → id map (region_id, county_id, country_id, …), fully populated even when
- *   parent_id is -4. This reads it for every only-self place and inserts the missing ancestor rows
- *   (one per distinct ancestor across branches).
+ *   parent_id is -4. This reads it for every candidate and inserts the missing ancestor rows (one per
+ *   distinct ancestor across branches).
  *
  *   MUST run AFTER populateAncestors and BEFORE the build freezes (VACUUM INTO), so the rows land in
  *   the shipped artifact — `scripts/build-unified-wof.ts` Phase 3 calls it inline. The standalone
  *   `scripts/backfill-ancestors-from-hierarchy.ts` is a thin CLI over the same function for ad-hoc
- *   repair of an already-built DB. Idempotent: only touches places with <= 1 ancestor row (self), and
- *   inserts each (id, ancestor_id) at most once.
+ *   repair of an already-built DB. Idempotent by the per-pair existence check, not by the candidate
+ *   test: each (id, ancestor_id) is inserted at most once, so a second run over the same DB adds
+ *   nothing.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { join } from "node:path"
+import { readdirSync } from "node:fs"
 import type { DatabaseSync } from "node:sqlite"
 
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst"
+import { join } from "path-ts"
+
+import type { WOFDatabase } from "./schema.ts"
+
 /**
  * Genuinely top-level placetypes — they never have (or need) an ancestor, so skip them.
  */
@@ -45,8 +69,8 @@ export interface AncestryBackfillResult {
 	 */
 	rowsAdded: number
 	/**
-	 * Only-self candidates whose source geojson could not be found (non-WOF backfilled places, or repos not present
-	 * locally) — skipped, not an error.
+	 * Candidates whose source geojson could not be found (non-WOF backfilled places, or repos not present locally) —
+	 * skipped, not an error.
 	 */
 	noGeojson: number
 }
@@ -89,34 +113,6 @@ export function discoverAdminDataRoots(reposRoot: string): string[] {
 	return roots
 }
 
-/**
- * WOF geojson lives sharded: an id resolves to `<3-char chunks>/<id>.geojson` under each data root.
- */
-function geojsonForID(id: number, roots: readonly string[]): Record<string, unknown> | null {
-	const s = String(id)
-	const chunks: string[] = []
-
-	for (let i = 0; i < s.length; i += 3) {
-		chunks.push(s.slice(i, i + 3))
-	}
-
-	const rel = join(chunks.join("/"), `${s}.geojson`)
-
-	for (const root of roots) {
-		const fp = join(root, rel)
-
-		if (existsSync(fp)) {
-			try {
-				return JSON.parse(readFileSync(fp, "utf8")) as Record<string, unknown>
-			} catch {
-				return null
-			}
-		}
-	}
-
-	return null
-}
-
 // `<placetype>_id` key → ancestor placetype. WOF hierarchy keys are e.g. region_id, county_id. Self
 // is filtered downstream by the `aid === id` check, so we do NOT special-case locality here: for a
 // locality candidate `locality_id` IS self (dropped by aid===id), but for a neighbourhood candidate
@@ -128,48 +124,82 @@ function placetypeFromKey(key: string): string | null {
 }
 
 /**
- * Insert missing ancestor rows for only-self places by reading `wof:hierarchy` from their source geojson under
- * `geojsonRoots` (see {@link discoverAdminDataRoots}). Runs inside a single transaction; caller owns connection
- * lifecycle (open, WAL checkpoint, close).
+ * Insert missing ancestor rows for every place whose ancestry chain dead-ended before reaching a country, by reading
+ * `wof:hierarchy` from its source geojson under `geojsonRoots` (see {@link discoverAdminDataRoots}). Runs inside a
+ * single transaction; caller owns connection lifecycle (open, WAL checkpoint, close).
  *
- * `opts.maxId` bounds the candidate scan to ids BELOW it — pass the synthetic-id base (`OVERTURE_ID_BASE`, 8e12) so the
+ * `opts.maxID` bounds the candidate scan to ids BELOW it — pass the synthetic-id base (`OVERTURE_ID_BASE`, 8e12) so the
  * backfill considers only real WOF places. Overture/GeoNames rows carry synthetic ids and have NO `wof:hierarchy`
- * geojson, so probing them is pure waste: on a wide-coverage DB the only-self set is millions of Overture/GeoNames leaf
- * localities, and the per-candidate geojson probe across every repo root turns a seconds-long WOF-only pass into a
+ * geojson, so probing them is pure waste: on a wide-coverage DB the country-less set is millions of Overture/GeoNames
+ * leaf localities, and the per-candidate geojson probe across every repo root turns a seconds-long WOF-only pass into a
  * ~40-minute one (their ancestry comes from the parent_id closure, not this backfill). Correctness-preserving — the
- * skipped rows would have `noGeojson`-skipped anyway. Omit `maxId` (default) for the legacy WOF-only DBs.
+ * skipped rows would have `noGeojson`-skipped anyway. Omit `maxID` (default) for the legacy WOF-only DBs.
  */
-export function backfillAncestorsFromHierarchy(
+export async function backfillAncestorsFromHierarchy(
 	db: DatabaseSync,
 	geojsonRoots: readonly string[],
-	opts: { maxId?: number } = {}
-): AncestryBackfillResult {
-	const maxId = opts.maxId ?? Number.MAX_SAFE_INTEGER
-
-	// `s.id < ?` first lets SQLite prune by the PK index before the correlated only-self subquery runs at all.
-	const candidates = db
-		.prepare(
-			`SELECT s.id AS id, s.placetype AS placetype FROM spr s
-			 WHERE s.id < ? AND (SELECT count(*) FROM ancestors a WHERE a.id = s.id) <= 1`
+	opts: { maxID?: number } = {}
+): Promise<AncestryBackfillResult> {
+	const maxID = opts.maxID ?? Number.MAX_SAFE_INTEGER
+	const kdb = new DatabaseClient<WOFDatabase>({ database: db })
+
+	// "No country-tier ancestor" is the dead-end signal at any depth — see the module docstring. The
+	// earlier "<= 1 ancestor row" test only caught the dead end's origin, never the children that
+	// inherit it (a child of a repaired -4 place has two rows: itself and that parent) (#1445).
+	// The id bound is stated first so SQLite prunes by the PK index before the NOT EXISTS runs at all.
+	const candidateBase = kdb
+		.selectFrom("spr")
+		.where("id", "<", maxID)
+		.where((eb) =>
+			eb.not(
+				eb.exists(
+					eb
+						.selectFrom("ancestors as a")
+						.select("a.id")
+						.whereRef("a.id", "=", "spr.id")
+						.where("a.ancestor_placetype", "=", "country")
+				)
+			)
 		)
-		.all(maxId) as Array<{ id: number; placetype: string }>
+
+	const candidates = await candidateBase.select(["id", "placetype"]).execute()
+
+	// Every candidate's existing ancestors in ONE query rather than an indexed read each. The widened
+	// candidate test made that per-candidate read the dominant cost of the pass, and the set is bounded:
+	// a candidate reaching this point has a handful of rows at most. The candidate set rides in as the
+	// SAME predicate re-issued as a subquery, never a materialized `IN (?, ?, …)` list — node:sqlite
+	// caps a statement at 32,766 bound variables and the wide-coverage build has 67,521 candidates
+	// (measured 2026-08-04).
+	const alreadyPresent = new Map<number, Set<number>>()
+
+	for (const row of await kdb
+		.selectFrom("ancestors")
+		.select(["id", "ancestor_id"])
+		.where("id", "in", candidateBase.select("spr.id"))
+		.execute()) {
+		let set = alreadyPresent.get(row.id)
+
+		if (!set) {
+			set = new Set()
+			alreadyPresent.set(row.id, set)
+		}
+
+		set.add(Number(row.ancestor_id))
+	}
 
 	const insert = db.prepare(
 		"INSERT INTO ancestors (id, ancestor_id, ancestor_placetype, lastmodified) VALUES (?, ?, ?, 0)"
 	)
 
-	const hasRow = db.prepare("SELECT 1 FROM ancestors WHERE id = ? AND ancestor_id = ? LIMIT 1")
-
 	let placesFixed = 0
 	let rowsAdded = 0
 	let noGeojson = 0
 	db.exec("BEGIN")
 
 	for (const { id, placetype } of candidates) {
-		if (TOP_PLACETYPES.has(placetype)) continue
-		const gj = geojsonForID(id, geojsonRoots)
-		const props = (gj?.["properties"] ?? null) as Record<string, unknown> | null
-		const hierarchy = (props?.["wof:hierarchy"] ?? null) as Array<Record<string, number>> | null
+		if (placetype && TOP_PLACETYPES.has(placetype)) continue
+		const gj = readWOFFeature(id, geojsonRoots)
+		const hierarchy = gj?.properties?.["wof:hierarchy"]
 
 		if (!hierarchy || !hierarchy.length) {
 			if (!gj) {
@@ -197,11 +227,20 @@ export function backfillAncestorsFromHierarchy(
 			}
 		}
 
+		let present = alreadyPresent.get(id)
+
+		if (!present) {
+			present = new Set()
+			alreadyPresent.set(id, present)
+		}
+
 		let added = 0
 
 		for (const [aid, pt] of seen) {
-			if (hasRow.get(id, aid)) continue
+			if (present.has(aid)) continue
+
 			insert.run(id, aid, pt)
+			present.add(aid)
 
 			added++
 		}

package/build-candidate.ts

@@ -26,6 +26,12 @@
  *
  *   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.
  */
 
 import { existsSync, rmSync } from "node:fs"
@@ -34,6 +40,7 @@ import { DatabaseSync } from "node:sqlite"
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 
 import { createCandidateFTS } from "./candidate-fts.ts"
+import { IMPORTANCE_JOIN_GATE_KM, loadImportanceIndex } from "./candidate-importance.ts"
 import {
 	CANDIDATE_COLUMNS,
 	createCandidateStagingTables,
@@ -60,8 +67,23 @@ export interface BuildCandidateOptions {
 	 * Optional postcode shards (`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
+	 * ("Brooklyn" for 11201), and they were previously reachable only through FTS.
 	 */
 	postcodes?: 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
+	 * centroid, NOT by id; see `candidate-importance.ts` for why the id join silently drops the foreign homonyms the
+	 * prior exists to demote.
+	 *
+	 * 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.
+	 */
+	importance?: string
 	/**
 	 * Optional progress callback for CLI / test introspection.
 	 */
@@ -75,6 +97,27 @@ export interface BuildCandidateResult {
 	aliases: number
 	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
+	 * through `onProgress`.
+	 */
+	postcodeAliases: number
+	/**
+	 * Places that took an `importance` score from the join (#28).
+	 *
+	 * `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.
+	 */
+	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.
+	 *
+	 * 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 {
@@ -91,6 +134,12 @@ interface PlaceAttrs {
 	pop: number
 	neg: number
 	pkey: string
+	/**
+	 * 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.
+	 */
+	imp: number | null
 }
 
 export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult> {
@@ -137,15 +186,55 @@ 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
+	// name/country/placetype/centroid together. Absent → every row's `importance` stays NULL. ---
+	let importance: ReturnType<typeof loadImportanceIndex> | undefined
+
+	if (opts.importance) {
+		progress("importance", `loading place_importance from ${opts.importance}`)
+		importance = loadImportanceIndex(opts.importance)
+
+		progress(
+			"importance",
+			`${importance.stats.places.toLocaleString()} scored places in ${importance.stats.keys.toLocaleString()} (name, country, placetype) groups` +
+				(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")
+	}
+
 	// --- region_id per place (its region-tier ancestor) for same-name disambiguation ---
 	progress("region", "loading region ancestry")
 	const regionOf = new Map<number, number>()
-
-	for (const r of src.prepare("SELECT id, ancestor_id FROM ancestors WHERE ancestor_placetype='region'").iterate()) {
+	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" +
+				" FROM ancestors WHERE ancestor_placetype='region' GROUP BY id"
+		)
+		.iterate()) {
 		regionOf.set(Number(r.id), Number(r.ancestor_id))
+
+		if (Number(r.n) > 1) {
+			multiRegion++
+		}
 	}
 
-	progress("region", `${regionOf.size.toLocaleString()} places carry a region`)
+	progress(
+		"region",
+		`${regionOf.size.toLocaleString()} places carry a region` +
+			(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
@@ -176,14 +265,16 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 		const neg = -Math.log10(pop + 1)
 		const name = String(r.name ?? "")
 		const pkey = normalizeLocalityForKey(name)
+		const lat = r.lat as number
+		const lon = r.lon as number
 
 		const a: PlaceAttrs = {
 			cid,
 			rid,
 			ptid,
 			name,
-			lat: r.lat as number,
-			lon: r.lon as number,
+			lat,
+			lon,
 			mnLat: r.mnlat as number,
 			mnLon: r.mnlon as number,
 			mxLat: r.mxlat as number,
@@ -191,12 +282,30 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			pop,
 			neg,
 			pkey,
+			imp: importance?.find(name, r.country as string | null, r.placetype as string | null, lat, lon) ?? null,
 		}
 
 		attrs.set(sid, a)
 
 		if (pkey) {
-			insStage.run(pkey, cid, rid, ptid, neg, sid, name, a.lat, a.lon, a.mnLat, a.mnLon, a.mxLat, a.mxLon, pop, 1)
+			insStage.run(
+				pkey,
+				cid,
+				rid,
+				ptid,
+				neg,
+				sid,
+				name,
+				a.lat,
+				a.lon,
+				a.mnLat,
+				a.mnLon,
+				a.mxLat,
+				a.mxLon,
+				pop,
+				1,
+				a.imp
+			)
 
 			nPrim++
 		}
@@ -205,6 +314,14 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	out.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)`
+		)
+	}
+
 	const stageRow = (k: string, a: PlaceAttrs, sid: number, isPrimary: number): void => {
 		insStage.run(
 			k,
@@ -221,7 +338,8 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			a.mxLat,
 			a.mxLon,
 			a.pop,
-			isPrimary
+			isPrimary,
+			a.imp
 		)
 	}
 
@@ -270,13 +388,25 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	out.exec("COMMIT")
 	progress("abbrevs", `${nAbbr.toLocaleString()} abbrevs`)
 
-	// --- pass 4: postcodes (separate shards: spr placetype='postalcode' with real coords) ---
-	let nPostcode = 0
-
-	for (const pcDB of opts.postcodes ?? []) {
+	/**
+	 * 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
@@ -290,38 +420,100 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 			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).
-			insStage.run(
-				key,
-				ccID(r.country as string | null),
-				0,
-				pcPtid,
-				0,
-				Number(r.id),
+			const a: PlaceAttrs = {
+				cid: ccID(r.country as string | null),
+				rid: 0,
+				ptid: pcPtid,
 				name,
 				lat,
 				lon,
-				(r.mnlat as number) || lat,
-				(r.mnlon as number) || lon,
-				(r.mxlat as number) || lat,
-				(r.mxlon as number) || lon,
-				0,
-				1
-			)
-
-			nPostcode++
+				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 }
+	}
+
+	let nPostcode = 0
+	let nPostcodeAlias = 0
+
+	for (const pcDB of opts.postcodes ?? []) {
+		const folded = foldPostcodeShard(pcDB)
+
+		nPostcode += folded.primaries
+		nPostcodeAlias += folded.aliases
 	}
 
 	if (nPostcode > 0) {
-		progress("postcodes", `${nPostcode.toLocaleString()} postcodes`)
+		progress("postcodes", `${nPostcode.toLocaleString()} postcodes; ${nPostcodeAlias.toLocaleString()} aliases`)
 	}
 
 	// --- code dictionaries: typed batch inserts via kdb (a few hundred rows — Kysely is clean here) ---
@@ -370,5 +562,14 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	await kdb.destroy()
 
 	// closes the underlying `out` connection
-	return { rows, places: attrs.size, primaries: nPrim, aliases: nAlias, abbrevs: nAbbr, postcodes: nPostcode }
+	return {
+		rows,
+		places: attrs.size,
+		primaries: nPrim,
+		aliases: nAlias,
+		abbrevs: nAbbr,
+		postcodes: nPostcode,
+		postcodeAliases: nPostcodeAlias,
+		...(importance ? { importanceScored: importance.matched, importanceGated: importance.gated } : {}),
+	}
 }