@mailwoman/resolver-wof-sqlite 8.6.0 → 9.0.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

@@ -60,6 +60,9 @@ 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[]
 	/**
@@ -75,6 +78,12 @@ 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
 }
 
 interface PlaceAttrs {
@@ -140,12 +149,33 @@ export async function buildCandidateTable(opts: BuildCandidateOptions): Promise<
 	// --- 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
@@ -270,13 +300,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 +332,96 @@ 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,
+			}
+
+			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 +470,13 @@ 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,
+	}
 }

package/candidate-lookup.ts

@@ -297,7 +297,9 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 		// #920 name law, candidate-key edition: postcode rows are keyed by their whitespace-stripped
 		// form at build (the GeoNames fold normalizes '624 66' → '62466'), so a postcode-typed query
 		// strips internal whitespace before keying. Postcode-only — locality names keep their spaces.
-		if ([query.placetype].flat().includes("postalcode")) {
+		const wantsPostcode = [query.placetype].flat().includes("postalcode")
+
+		if (wantsPostcode) {
 			text = text.replaceAll(/\s+/g, "")
 		}
 
@@ -427,7 +429,18 @@ export class WOFCandidateTableLookup implements PlaceLookup {
 			// — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
 			// pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
 			// correctly lands population-first Vienna AT. The exact/strip probes already covered the real name.
-			if (!rows.length && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
+			//
+			// NEVER for postcodes: fuzzy is a typo corrector for place NAMES, and a "corrected" postcode is a
+			// DIFFERENT postcode. The 2026-08-05 Code-Point swap exposed the trap at scale: Northern Ireland's
+			// `BT3 9QQ` (absent — no permissive NI source) trigram-matched Sheffield's `S3 9QQ` (Jaccard 0.4
+			// on {39q, 9qq}) and resolved 200+ km wrong with full confidence. An unknown postcode must abstain.
+			if (
+				!rows.length &&
+				!wantsPostcode &&
+				this.#ftsProbe &&
+				this.#nameKeyExistsProbe &&
+				!this.#nameKeyExistsProbe.get(nameKey)
+			) {
 				const match = ftsTrigramQuery(nameKey)
 
 				if (match) {

package/coverage-manifest-schema.ts

@@ -11,7 +11,7 @@
  *     promote-gate verdicts + the measured hard-resolve rates that used to live in a code comment on
  *     `HARD_PLACE_COUNTRY_SAFELIST`. Presence = measured; `hard_filter_safe = 0` = measured and
  *     FAILED the gate (FI 69.5%, PL 77.8%) — distinguishable from a country never measured at all
- *     (the meaning-of-zero rule, `docs/articles/plan/reference/layer-contract.mdx`).
+ *     (the meaning-of-zero rule, `docs/engineering/reference/layer-contract.mdx`).
  *   - `country_bbox`: the coarse guard-B plausibility boxes that used to live in
  *     `resolver/plausibility.ts`'s `COUNTRY_BBOX`. An absent row fails open (never trips the guard),
  *     exactly like an absent key in the constant.

package/fst-builder.ts

@@ -13,6 +13,7 @@
 
 import { DatabaseSync } from "node:sqlite"
 
+import { readWOFSourceIdentity } from "./fst-freshness.ts"
 import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher, normalizeTokens } from "./fst-matcher.ts"
 import type { BuildFSTOpts, BuildFSTResult, FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
@@ -29,6 +30,11 @@ const DEFAULT_PLACETYPES: PlacetypeID[] = [
 
 const DEFAULT_COUNTRIES = ["US"]
 const DEFAULT_LANGUAGES = ["eng", ""]
+/**
+ * Ids per `IN (…)` batch. SQLITE_MAX_VARIABLE_NUMBER defaults to 32,766; 500 matches the name-load batch a few phases
+ * down, so both read paths bind the same shape.
+ */
+const ANCESTOR_CHUNK = 500
 
 interface SprRow {
 	id: number
@@ -89,19 +95,40 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	// Also load parent rows that might be outside our placetype filter (e.g., country for region).
 	const parentStmt = db.prepare("SELECT id, name, placetype, parent_id, latitude, longitude FROM spr WHERE id = ?")
 
-	// Fallback: use ancestors table when parent_id is a sentinel (-1, -4, etc.).
-	let ancestorStmt: ReturnType<typeof db.prepare> | null = null
+	// Fallback for a sentinel parent_id (-1, -4, …): the ancestors table. Read in chunked `IN (…)`
+	// batches ONCE — the point-query version fired per orphan row, and on a global build the orphans
+	// run to six figures. Ordering is county → region → country, preserved by the same CASE the
+	// per-row query used, with `id` leading so one pass groups the rows.
+	const ancestorsByID = new Map<number, number[]>()
 
 	try {
-		ancestorStmt = db.prepare(
-			`SELECT DISTINCT ancestor_id FROM ancestors
-			 WHERE id = ? AND ancestor_placetype IN ('country', 'region', 'county')
-			 ORDER BY CASE ancestor_placetype
-			   WHEN 'county' THEN 1
-			   WHEN 'region' THEN 2
-			   WHEN 'country' THEN 3
-			 END`
-		)
+		const orphanIDs = sprRows.filter((row) => row.parent_id <= 0).map((row) => row.id)
+
+		for (let i = 0; i < orphanIDs.length; i += ANCESTOR_CHUNK) {
+			const chunk = orphanIDs.slice(i, i + ANCESTOR_CHUNK)
+
+			const rows = db
+				.prepare(
+					`SELECT DISTINCT id, ancestor_id FROM ancestors
+					 WHERE id IN (${chunk.map(() => "?").join(",")}) AND ancestor_placetype IN ('country', 'region', 'county')
+					 ORDER BY id, CASE ancestor_placetype
+					   WHEN 'county' THEN 1
+					   WHEN 'region' THEN 2
+					   WHEN 'country' THEN 3
+					 END`
+				)
+				.all(...chunk) as unknown as Array<{ id: number; ancestor_id: number }>
+
+			for (const row of rows) {
+				let chain = ancestorsByID.get(row.id)
+
+				if (!chain) {
+					ancestorsByID.set(row.id, (chain = []))
+				}
+
+				chain.push(row.ancestor_id)
+			}
+		}
 	} catch {
 		progress("ancestors", "No ancestors table — sentinel parent_ids will produce empty chains")
 	}
@@ -112,10 +139,8 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		if (!row) return []
 
 		// If parent_id is a sentinel (≤ 0), use ancestors table.
-		if (row.parent_id <= 0 && ancestorStmt) {
-			const ancestors = ancestorStmt.all(id) as unknown as Array<{ ancestor_id: number }>
-
-			return ancestors.map((a) => a.ancestor_id).filter((aid) => aid !== id)
+		if (row.parent_id <= 0) {
+			return (ancestorsByID.get(id) ?? []).filter((ancestorID) => ancestorID !== id)
 		}
 
 		// Normal case: walk parent_id chain.
@@ -320,6 +345,15 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 	const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0)
 	const matcher = FSTMatcher.fromNodes(nodes)
 
+	// The build stamp (2026-08-05). `sourceDB` alone was never enough to tell a reader whether this
+	// artifact matches the database at that path — the admin DB is sealed and REPLACED by a rebuild, so
+	// the path is constant across every generation of it. Hashing costs 7.3 s for the 5.27 GB admin DB
+	// and is free whenever the `.md5` sidecar is current, which the admin build already writes.
+	// `sourceIdentity` lets a caller that already knows the digest (or is building from something that
+	// is not a file at all) supply it instead.
+	progress("stamp", `Reading source identity for ${opts.dbPath}`)
+	const source = opts.sourceIdentity ?? readWOFSourceIdentity(opts.dbPath)
+
 	const provenance: FSTProvenance = {
 		builtAt: new Date().toISOString(),
 		countries,
@@ -329,6 +363,8 @@ export function buildFSTFromWOF(opts: BuildFSTOpts): {
 		nameInsertions: insertCount,
 		importanceMatches: importanceMap.size,
 		sourceDB: opts.dbPath,
+		sourceDBMD5: source.md5,
+		sourceDBBytes: source.bytes,
 		...(excludeSurfaces !== undefined || excludeAllTokensOf !== undefined
 			? { exclusionPolicy: opts.exclusionPolicy ?? "unspecified", excludedInsertions: excludedCount }
 			: {}),

package/fst-deserialize-web.ts

@@ -10,6 +10,8 @@
  *   build-time operation).
  */
 
+import { tryParsingJSON } from "@mailwoman/core/objects"
+
 import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher } from "./fst-matcher.ts"
 import type { FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
@@ -194,7 +196,7 @@ export function readFSTProvenanceWeb(input: ArrayBuffer | Uint8Array): FSTProven
 		const jsonLen = view.getUint32(provenanceOffset, true)
 		const jsonStr = decoder.decode(bytes.subarray(provenanceOffset + 4, provenanceOffset + 4 + jsonLen))
 
-		return JSON.parse(jsonStr) as FSTProvenance
+		return tryParsingJSON<FSTProvenance>(jsonStr) ?? undefined
 	} catch {
 		return undefined
 	}