@mailwoman/resolver-wof-sqlite 7.2.0 → 7.3.0

package/address-point-interpolation.ts

@@ -0,0 +1,207 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Address-point interpolation — "Method 2" of the resolution ladder (#483, Phase 1 of
+ *   `docs/articles/plan/2026-06-11-resolution-ladder.md`): when the exact address-point tier (#476)
+ *   misses a house number, bracket the number with REAL neighbor points on the same street from the
+ *   same #476 shard and interpolate linearly in house-number space between them. Real occupancy
+ *   replaces TIGER's uniform-spacing assumption — the dominant error term of the TIGER pilot's gate
+ *   miss; TIGER range interpolation (`StreetInterpolator`) demotes to the fallback for streets too
+ *   sparse to bracket.
+ *
+ *   Matching key is `street_key` — THE shared normalizer plus the route fold
+ *   (`canonicalizeRouteKey`), identical at build time (`scripts/build-address-point-shard.ts`) and
+ *   query time, by construction. Scope is postcode-first like the segment tier; a query without a
+ *   postcode goes straight to the fallback (which carries its own statewide-ambiguity abstention).
+ *
+ *   Bracketing contract:
+ *
+ *   - Neighbor candidates NEVER include the queried number itself (any unit/duplicate row of it) — in
+ *       production the exact tier would already have answered an on-file number, and in the eval
+ *       this is what makes grading against the same shard non-circular by construction.
+ *   - Both-sided bracket (`bracket: "both"`): linear interpolation between the nearest known number
+ *       below and above; `uncertaintyM` = half the distance between them.
+ *   - Single-sided (`bracket: "single"`): linear extrapolation along the two nearest known numbers on
+ *       that side, capped at one pair-span beyond the nearest point (`t ≤ 2` — beyond that the line
+ *       carries no evidence and the query falls through); `uncertaintyM` = the pair distance plus
+ *       the extrapolated overshoot, explicitly larger than the both-sided radius.
+ *   - No bracket (no neighbors, a single known number, or past the extrapolation cap): fall through to
+ *       the TIGER fallback when configured, else null.
+ *
+ *   Standalone like the segment tier — core wiring rides the Phase 2 ordered `spatialTiers` list.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import type { InterpolationLookup } from "@mailwoman/resolver"
+
+import { haversineKm } from "./geo.ts"
+import type { InterpolatedHit, InterpolationQuery, StreetInterpolator } from "./interpolation.ts"
+import { hasTable } from "./sqlite-utils.ts"
+import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.ts"
+
+/**
+ * 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.
+ */
+const MAX_EXTRAPOLATION_T = 2
+
+interface PointRow {
+	n: number
+	lat: number
+	lon: number
+	source: string
+	release: string
+}
+
+/** One known house number on the street: the centroid of its rows (unit siblings collapse). */
+interface NumberAnchor {
+	n: number
+	lat: number
+	lon: number
+	source: string
+	release: string
+}
+
+export class AddressPointInterpolator implements InterpolationLookup {
+	readonly #db: DatabaseSync
+	readonly #ownsDB: boolean
+	readonly #fallback: StreetInterpolator | undefined
+	readonly #byPostcode: ReturnType<DatabaseSync["prepare"]> | undefined
+
+	constructor(opts: { dbPath?: string; database?: DatabaseSync; fallback?: StreetInterpolator }) {
+		if (opts.database) {
+			this.#db = opts.database
+			this.#ownsDB = false
+		} else if (opts.dbPath) {
+			this.#db = new DatabaseSync(opts.dbPath, { readOnly: true })
+			this.#ownsDB = true
+		} else {
+			throw new Error("AddressPointInterpolator: one of dbPath or database is required")
+		}
+		this.#fallback = opts.fallback
+
+		// Degrade gracefully on an empty/tableless shard (#568): with no `address_point` table this tier
+		// is skipped, deferring to the segment fallback rather than crashing at construction.
+		if (hasTable(this.#db, "address_point")) {
+			// Strictly-numeric neighbor numbers on the route-folded street key within the ZIP. The
+			// queried number itself is excluded HERE (see module doc: non-circular by construction).
+			this.#byPostcode = this.#db.prepare(
+				`SELECT CAST(number AS INTEGER) AS n, lat, lon, source, release
+				 FROM address_point
+				 WHERE postcode = ? AND street_key = ?
+					AND number GLOB '[0-9]*' AND number NOT GLOB '*[^0-9]*'
+					AND CAST(number AS INTEGER) != ?`
+			)
+		}
+	}
+
+	find(query: InterpolationQuery): InterpolatedHit | null {
+		const streetKey = canonicalizeRouteKey(normalizeStreetForKey(query.street))
+		const numberRaw = query.number.trim()
+
+		if (!streetKey || !/^\d+$/.test(numberRaw)) return null
+		const n = Number(numberRaw)
+
+		// No own table (empty shard) or no postcode → defer to the segment fallback rather than query.
+		if (!this.#byPostcode || !query.postcode) return this.#fallback?.find(query) ?? null
+
+		const rows = this.#byPostcode.all(query.postcode.trim(), streetKey, n) as unknown as PointRow[]
+		const hit = rows.length >= 2 ? interpolateFromNeighbors(rows, n) : null
+
+		return hit ?? this.#fallback?.find(query) ?? null
+	}
+
+	close(): void {
+		if (this.#ownsDB) {
+			this.#db.close()
+		}
+	}
+}
+
+/** Collapse rows to one centroid anchor per distinct house number, sorted ascending. */
+function anchorsByNumber(rows: readonly PointRow[]): NumberAnchor[] {
+	const byN = new Map<number, PointRow[]>()
+
+	for (const row of rows) {
+		const group = byN.get(row.n)
+
+		if (group) {
+			group.push(row)
+		} else {
+			byN.set(row.n, [row])
+		}
+	}
+
+	return [...byN.entries()]
+		.map(([n, group]) => ({
+			n,
+			lat: group.reduce((sum, r) => sum + r.lat, 0) / group.length,
+			lon: group.reduce((sum, r) => sum + r.lon, 0) / group.length,
+			source: group[0]!.source,
+			release: group[0]!.release,
+		}))
+		.sort((a, b) => a.n - b.n)
+}
+
+function interpolateFromNeighbors(rows: readonly PointRow[], n: number): InterpolatedHit | null {
+	const anchors = anchorsByNumber(rows)
+
+	// Nearest known number below and above the query (the rows never contain n itself).
+	let below: NumberAnchor | undefined
+	let above: NumberAnchor | undefined
+
+	for (const anchor of anchors) {
+		if (anchor.n < n) {
+			below = anchor
+		} else {
+			above = anchor
+			break
+		}
+	}
+
+	if (below && above) {
+		const t = (n - below.n) / (above.n - below.n)
+		const spanM = haversineKm(below.lat, below.lon, above.lat, above.lon) * 1000
+
+		return {
+			lat: below.lat + (above.lat - below.lat) * t,
+			lon: below.lon + (above.lon - below.lon) * t,
+			interpolated: true,
+			method: "address_point",
+			bracket: "both",
+			uncertaintyM: Math.round(spanM / 2),
+			source: below.source,
+			release: below.release,
+		}
+	}
+
+	// Single-sided: extrapolate along the two nearest known numbers on the populated side.
+	// `near` is the anchor closest to n, `far` the next one out; t > 1 by construction.
+	const side = below ? anchors.slice(-2) : anchors.slice(0, 2)
+
+	if (side.length < 2) return null
+	const [far, near] = below ? [side[0]!, side[1]!] : [side[1]!, side[0]!]
+	const t = (n - far.n) / (near.n - far.n)
+
+	if (t > MAX_EXTRAPOLATION_T) return null
+
+	const lat = far.lat + (near.lat - far.lat) * t
+	const lon = far.lon + (near.lon - far.lon) * t
+	const pairM = haversineKm(near.lat, near.lon, far.lat, far.lon) * 1000
+	const overshootM = haversineKm(lat, lon, near.lat, near.lon) * 1000
+
+	return {
+		lat,
+		lon,
+		interpolated: true,
+		method: "address_point",
+		bracket: "single",
+		// Explicitly larger than the both-sided radius: the whole pair span plus the overshoot.
+		uncertaintyM: Math.round(pairM + overshootM),
+		source: near.source,
+		release: near.release,
+	}
+}

package/address-point-schema.ts

@@ -0,0 +1,107 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the SITUS / rooftop ADDRESS-POINT shards (`address-points-<cc>-<slug>.db`, built
+ *   by `scripts/build-address-point-shard.ts` — the #476/#567 national rooftop tier behind the
+ *   demo's "type any US address, get the building"). Single source of truth for the columns shared
+ *   by the BUILDER and the READER ({@link AddressPointSqliteLookup}), so a column rename in one is a
+ *   compile error in the other.
+ *
+ *   The builder's hot INSERT (tens of millions of rows per state) stays a POSITIONAL prepared
+ *   statement for throughput — but its column list is derived from {@link ADDRESS_POINT_COLUMNS}
+ *   here, and its table comes from {@link createAddressPointTable}, so the positional order can't
+ *   silently drift from what the reader expects. (Same convention as the candidate build: typed
+ *   schema guards the contract; positional inserts keep the speed.)
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * One rooftop address point. `(street_norm, number)` within a `postcode` (preferred) or `locality_norm` scope is the
+ * lookup; `street_key` is the #483 route-fold key for interpolation. Coordinates are non-null (the builder drops
+ * non-finite coords). `unit`/`postcode`/`locality_norm` are nullable (not every source carries all three).
+ */
+export interface AddressPointTable {
+	/** Shared {@link normalizeStreetForKey} of the street — the build/query-consistent probe key. */
+	street_norm: string
+	/** `canonicalizeRouteKey(street_norm)` — the route-fold key (#483 Method 2). */
+	street_key: string
+	/** House number, normalized lower-case (kept TEXT — "123-A", "12 1/2" must survive). */
+	number: string
+	unit: string | null
+	postcode: string | null
+	/** Shared {@link normalizeLocalityForKey} of the locality — the fallback scope. */
+	locality_norm: string | null
+	/** The street as it appeared in the source (kept for display / debugging). */
+	street_raw: string
+	lat: number
+	lon: number
+	/** Provenance: the dataset this point came from (e.g. `overture:us`, `openaddresses`). */
+	source: string
+	/** The pinned data release the point was ingested from. */
+	release: string
+}
+
+/** The address-point database schema for `new DatabaseClient<AddressPointDatabase>(...)`. */
+export interface AddressPointDatabase {
+	address_point: AddressPointTable
+}
+
+/**
+ * The `address_point` columns in INSERT order. The builder's positional prepared statement derives its placeholder list
+ * from this, so the positional order can't drift from the DDL / the reader.
+ */
+export const ADDRESS_POINT_COLUMNS = [
+	"street_norm",
+	"street_key",
+	"number",
+	"unit",
+	"postcode",
+	"locality_norm",
+	"street_raw",
+	"lat",
+	"lon",
+	"source",
+	"release",
+] as const
+
+/** Create the `address_point` table — called before the streaming bulk load. */
+export async function createAddressPointTable(db: Kysely<AddressPointDatabase>): Promise<void> {
+	await db.schema
+		.createTable("address_point")
+		.addColumn("street_norm", "text", (c) => c.notNull())
+		// `street_key` = canonicalizeRouteKey(street_norm): the route-fold key (#483 Method 2).
+		.addColumn("street_key", "text", (c) => c.notNull())
+		.addColumn("number", "text", (c) => c.notNull())
+		.addColumn("unit", "text")
+		.addColumn("postcode", "text")
+		.addColumn("locality_norm", "text")
+		.addColumn("street_raw", "text", (c) => c.notNull())
+		.addColumn("lat", "real", (c) => c.notNull())
+		.addColumn("lon", "real", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.addColumn("release", "text", (c) => c.notNull())
+		.execute()
+}
+
+/** Create the three probe indexes the reader relies on (postcode-scope, locality-scope, route-key). */
+export async function createAddressPointIndexes(db: Kysely<AddressPointDatabase>): Promise<void> {
+	await db.schema
+		.createIndex("idx_ap_postcode")
+		.on("address_point")
+		.columns(["postcode", "street_norm", "number"])
+		.execute()
+	await db.schema
+		.createIndex("idx_ap_locality")
+		.on("address_point")
+		.columns(["locality_norm", "street_norm", "number"])
+		.execute()
+	await db.schema.createIndex("idx_ap_streetkey").on("address_point").columns(["postcode", "street_key"]).execute()
+	// Street-first index for the BBOX scope (#247): OSM points often carry no postcode/locality, so the
+	// reader scopes a `(street_norm, number)` probe by the resolved locality's bbox (lat/lon BETWEEN). The
+	// postcode/locality indexes lead with their scope column and can't serve this; US situs never probes by
+	// bbox so it simply carries one extra (cheap) index on a future rebuild.
+	await db.schema.createIndex("idx_ap_street").on("address_point").columns(["street_norm", "number"]).execute()
+}

package/address-point.ts

@@ -0,0 +1,122 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   SQLite implementation of core's `AddressPointLookup` (#476): exact `(street, number)` within a
+ *   postcode (preferred), locality, or — for shards whose points carry no scope tag (OSM, #247) —
+ *   the resolved locality's BBOX. Query-side normalization is THE shared normalizer
+ *   (`street-normalize.ts`), selected per the shard's `streetLocale` so build-side and probe-side
+ *   stay identical by construction (US delegates to the USPS pipeline; FR/DE/NL use the locale rules).
+ *
+ *   Matching is exact-after-normalization only — no fuzzy street matching in this tier (measure how
+ *   far exact gets first; fuzz is a later, separate decision). Scope order is most-selective first:
+ *   postcode, then locality, then the bbox fall-through (only when a bbox is supplied AND the prior
+ *   scopes missed). Multiple hits return the first by rowid — unit siblings share the building coord.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import type { AddressPointHit, AddressPointLookup } from "@mailwoman/resolver"
+
+import type { AddressPointTable } from "./address-point-schema.ts"
+import { hasTable } from "./sqlite-utils.ts"
+import {
+	normalizeLocalityForKey,
+	normalizeStreetForKeyLocale,
+	stripArrondissement,
+	type StreetLocale,
+} from "./street-normalize.ts"
+
+/**
+ * The columns this lookup projects — a typed slice of the SHARED {@link AddressPointTable}, so a column rename in
+ * `build-address-point-shard.ts` (the writer) is a compile error here (the reader).
+ */
+type AddressPointRow = Pick<AddressPointTable, "lat" | "lon" | "source" | "release">
+
+/**
+ * The 4 columns the reader SELECTs, in the schema's order — referenced by the prepared SELECTs so the projected
+ * `AddressPointRow` stays in lockstep with the shared schema.
+ */
+const SELECT_COLS = "lat, lon, source, release"
+
+export class AddressPointSqliteLookup implements AddressPointLookup {
+	readonly #db: DatabaseSync
+	readonly #locale: StreetLocale
+	readonly #byPostcode: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #byLocality: ReturnType<DatabaseSync["prepare"]> | undefined
+	readonly #byBbox: ReturnType<DatabaseSync["prepare"]> | undefined
+
+	/**
+	 * @param dbPath Shard path.
+	 * @param opts.streetLocale The street-normalization locale this shard was BUILT with — must match, or every key
+	 *   misses. Defaults to `"us"` (the situs tier), so existing callers are unchanged.
+	 */
+	constructor(dbPath: string, opts: { streetLocale?: StreetLocale } = {}) {
+		this.#db = new DatabaseSync(dbPath, { readOnly: true })
+		this.#locale = opts.streetLocale ?? "us"
+
+		// Degrade gracefully on an empty/tableless shard (interrupted build, stray 0-byte file): with no
+		// `address_point` table this lookup is a no-op miss, not a crash that loses the whole state (#568).
+		if (hasTable(this.#db, "address_point")) {
+			this.#byPostcode = this.#db.prepare(
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE postcode = ? AND street_norm = ? AND number = ? LIMIT 1`
+			)
+			this.#byLocality = this.#db.prepare(
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE locality_norm = ? AND street_norm = ? AND number = ? LIMIT 1`
+			)
+			this.#byBbox = this.#db.prepare(
+				`SELECT ${SELECT_COLS} FROM address_point
+				 WHERE street_norm = ? AND number = ? AND lat BETWEEN ? AND ? AND lon BETWEEN ? AND ? LIMIT 1`
+			)
+		}
+	}
+
+	find(query: {
+		street: string
+		number: string
+		postcode?: string
+		locality?: string
+		bbox?: { minLat: number; maxLat: number; minLon: number; maxLon: number }
+	}): AddressPointHit | null {
+		if (!this.#byPostcode || !this.#byLocality || !this.#byBbox) return null
+		const streetNorm = normalizeStreetForKeyLocale(query.street, this.#locale)
+		const number = query.number.trim().toLowerCase()
+
+		if (!streetNorm || !number) return null
+
+		let row: AddressPointRow | undefined
+
+		if (query.postcode) {
+			row = this.#byPostcode.get(query.postcode.trim(), streetNorm, number) as AddressPointRow | undefined
+		}
+
+		if (!row && query.locality) {
+			// FR shards key arrondissement communes at the base city (both-sides fold, see the BAN
+			// builder + stripArrondissement) — fold the probe too so "Paris 13e Arrondissement" and
+			// "Paris" both hit. No-op for "us" shards and every non-arrondissement commune.
+			const localityKey =
+				this.#locale === "fr"
+					? stripArrondissement(normalizeLocalityForKey(query.locality))
+					: normalizeLocalityForKey(query.locality)
+			row = this.#byLocality.get(localityKey, streetNorm, number) as AddressPointRow | undefined
+		}
+
+		// 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) {
+			const b = query.bbox
+			row = this.#byBbox.get(streetNorm, number, b.minLat, b.maxLat, b.minLon, b.maxLon) as AddressPointRow | undefined
+		}
+
+		if (!row) return null
+
+		return { lat: row.lat, lon: row.lon, source: row.source, release: row.release }
+	}
+
+	close(): void {
+		this.#db.close()
+	}
+}

package/ancestry-backfill.ts

@@ -0,0 +1,205 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ *
+ *   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
+ *   dead-ends and the place gets NO region/county/country ancestry. The resolver's region-descendant
+ *   filter then can't reach it: given "New York, NY", NYC (with no NY-state ancestor) is excluded and
+ *   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 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).
+ *
+ *   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.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type { DatabaseSync } from "node:sqlite"
+
+/** Genuinely top-level placetypes — they never have (or need) an ancestor, so skip them. */
+const TOP_PLACETYPES = new Set(["country", "continent", "empire", "ocean", "marinearea", "planet"])
+
+export interface AncestryBackfillResult {
+	/** Places that gained at least one ancestor row. */
+	placesFixed: number
+	/** Total ancestor rows inserted. */
+	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.
+	 */
+	noGeojson: number
+}
+
+/**
+ * Discover the `data` directories under a WOF repos root that hold sharded geojson, e.g.
+ * `<root>/whosonfirst-data/whosonfirst-data-admin-us/data`. Resolves an id to its geojson via these roots. Accepts both
+ * the nested lab layout (a `whosonfirst-data` group dir holding the admin repos) and a flat layout (admin repos
+ * directly under the root); searches at most two directory levels deep.
+ */
+export function discoverAdminDataRoots(reposRoot: string): string[] {
+	const roots: string[] = []
+
+	const visit = (dir: string, depth: number): void => {
+		if (depth > 2) return
+
+		let names: string[]
+
+		try {
+			names = readdirSync(dir, { withFileTypes: true })
+				.filter((e) => e.isDirectory())
+				.map((e) => e.name)
+		} catch {
+			return
+		}
+
+		for (const name of names) {
+			const child = join(dir, name)
+
+			if (name === "data") {
+				roots.push(child)
+			} else if (name.startsWith("whosonfirst-data")) {
+				visit(child, depth + 1)
+			}
+		}
+	}
+
+	visit(reposRoot, 0)
+
+	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
+// `locality_id` is its PARENT locality — a real ancestor we must keep.
+function placetypeFromKey(key: string): string | null {
+	if (!key.endsWith("_id")) return null
+
+	return key.slice(0, -3)
+}
+
+/**
+ * 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).
+ *
+ * `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
+ * ~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.
+ */
+export 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`
+		)
+		.all(maxId) as Array<{ id: number; placetype: string }>
+
+	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 (!hierarchy || hierarchy.length === 0) {
+			if (!gj) {
+				noGeojson++
+			}
+			continue
+		}
+
+		// Collect distinct (ancestor_id, placetype) across all hierarchy branches, excluding self.
+		const seen = new Map<number, string>()
+
+		for (const branch of hierarchy) {
+			for (const [key, val] of Object.entries(branch)) {
+				const pt = placetypeFromKey(key)
+
+				if (!pt) continue
+				const aid = Number(val)
+
+				if (!Number.isFinite(aid) || aid <= 0 || aid === id) continue
+
+				if (!seen.has(aid)) {
+					seen.set(aid, pt)
+				}
+			}
+		}
+
+		let added = 0
+
+		for (const [aid, pt] of seen) {
+			if (hasRow.get(id, aid)) continue
+			insert.run(id, aid, pt)
+			added++
+		}
+
+		if (added > 0) {
+			placesFixed++
+			rowsAdded += added
+		}
+	}
+
+	db.exec("COMMIT")
+
+	return { placesFixed, rowsAdded, noGeojson }
+}