@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/currency-backfill.ts

@@ -3,17 +3,14 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Pass 1c of the candidate build (#1737): resurrect deprecated-with-no-successor WOF localities that a second
- *   source independently attests. Extracted from `build-candidate.ts` as a cohesive unit — the checks, their measured
- *   constants, and the GeoNames dump reader live together here; the build calls {@link resurrectCurrencyHoles} once,
- *   between the primaries pass and the alias pass.
+ *   Restores deprecated WOF localities only when an independent source attests them.
  */
 
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { isStrictlyFiner } from "@mailwoman/core/resources/whosonfirst"
 import { haversineKm } from "@mailwoman/spatial"
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
-import { resolvePath } from "path-ts"
+import { type PathBuilderLike, resolvePath } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
 import type { loadImportanceIndex } from "#candidate/importance"
@@ -22,42 +19,15 @@ import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
-/**
- * Corroboration radius for the currency backfill (#1737), km — both for the live-near blocker and the GeoNames
- * attestation. Measured basis (2026-08-19 prototype, GB locality slice): at 10 km, 20 of 108 dead names resurrect —
- * Rochester (Kent), Aldershot, Staines, Telford, Ebbw Vale among them — while the `Birmingham/Wolverhampton/…`
- * conurbation blobs stay dead (no attestation) and Swansea/Wrexham stay out because a live same-name row already serves
- * them within the radius.
- */
 const CURRENCY_BACKFILL_RADIUS_KM = 10
 
-/**
- * Minimum attestor population for a resurrection. The same prototype measured 44 of 108 dead GB names attested but
- * under this floor — hamlet-scale ghosts whose absence from the index nobody has reported. A floor keeps the pass
- * answering the measured defect (real settlements) rather than re-importing the tail WOF chose to prune.
- */
 const CURRENCY_BACKFILL_POP_FLOOR = 1000
 
 /**
- * Pass 1c (#1737): resurrect deprecated-with-no-successor localities that a second source independently attests.
- *
- * WOF deprecations WITH a successor need nothing — the successor indexes. A deprecation with `is_superseded = 0` on a
- * populated place is the shape of an upstream mistake (Rochester Kent, Aldershot, Telford; 120 GB localities alone),
- * and it is indistinguishable from a correct pruning at this layer without outside evidence. So every resurrection
- * requires all three conditions, positive evidence only:
- *
- * 1. NO live same-name spr row of any placetype within {@link CURRENCY_BACKFILL_RADIUS_KM} of the dead record — a live row
- *    means the place is alive (possibly under another placetype) and there is no hole. A DISTANT same-name row is a
- *    namesake and does not block.
- * 2. A GeoNames feature-class-P attestation of the same folded name within the radius.
- * 3. The attestor at or above {@link CURRENCY_BACKFILL_POP_FLOOR}.
- *
- * The staged row keeps the WOF identity — id, name, centroid, bbox, region ancestry — because the dead record's own
- * data is not what is wrong with it. GeoNames contributes exactly two things: the attestation, and the population that
- * lets the row stand in prominence races (the dead record's own population is absent). Each name is judged once per
- * country; the resurrected place joins `attrs`, so the alias pass explodes its alt names like any primary's.
+ * Restore a deprecated locality only when no nearby live namesake exists and GeoNames
+ * attests the same folded name above {@link CURRENCY_BACKFILL_POP_FLOOR}.
  */
-export interface CurrencyBackfillOutcomes {
+export interface CurrencyBackfillResults {
 	judged: number
 	blocked: number
 	unattested: number
@@ -66,17 +36,16 @@ export interface CurrencyBackfillOutcomes {
 }
 
 /**
- * One country's read of the check — every dead name judged, by outcome and by the dead row's placetype — so a census
- * can say what a wider dead-row query admits before a build carries it.
+ * One country's read of the check — every dead name judged, by result and by the dead
+ * row's placetype — so a census can say what a wider query admits.
  */
-export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes {
+export interface CurrencyBackfillCountryReport extends CurrencyBackfillResults {
 	country: string
 	deadPlacetypes: readonly string[]
 	dumpPresent: boolean
-	byDeadPlacetype: Record<string, CurrencyBackfillOutcomes>
+	byDeadPlacetype: Record<string, CurrencyBackfillResults>
 	/**
-	 * The first resurrected names, `placetype:name`, so a census reads what a wider query admits — capped, because the
-	 * report is a receipt and not the table.
+	 * The first resurrected names, `placetype:name`, capped because the report is a receipt and not the table.
 	 */
 	sample: string[]
 }
@@ -84,40 +53,37 @@ export interface CurrencyBackfillCountryReport extends CurrencyBackfillOutcomes
 const REPORT_SAMPLE_SIZE = 25
 
 /**
- * The placetypes a dead row may carry to be judged at all. `locality` is the shipped default; `localadmin` is the
- * second cause #1746 named (one GB row of seventeen) and is admitted through this option once its census is read.
+ * The placetypes a dead row may have to be judged at all; `locality` is the shipped default.
  */
 export const DEFAULT_DEAD_PLACETYPES: readonly string[] = ["locality"]
 
-function emptyOutcomes(): CurrencyBackfillOutcomes {
+function emptyResults(): CurrencyBackfillResults {
 	return { judged: 0, blocked: 0, unattested: 0, floored: 0, resurrected: 0 }
 }
 
 export async function resurrectCurrencyHoles(ctx: {
 	src: DatabaseClient<WOFDatabase>
 	/**
-	 * The candidate build's transaction. Required unless `dryRun` — a dry run judges every row and stages nothing.
+	 * The candidate build's transaction, required unless `dryRun`.
 	 */
 	tx?: DatabaseClient<CandidateDatabase>
-	geonamesDir: string
+	geonamesDir: PathBuilderLike
 	countries: readonly string[]
 	attrs: Map<number, PlaceAttrs>
 	ccID: (code: string | null) => number
 	ptID: (pt: string | null) => number
 	regionOf: Map<number, number>
-	importance: ReturnType<typeof loadImportanceIndex> | undefined
+	importance: ReturnType<typeof loadImportanceIndex> | null
 	stageRow: StageRow
 	progress: (phase: string, message: string) => void
-	/**
-	 * Which dead placetypes are judged. Default {@link DEFAULT_DEAD_PLACETYPES}.
-	 */
+
 	deadPlacetypes?: readonly string[]
 	/**
-	 * Judge and count, stage nothing — the census mode. No transaction is opened.
+	 * Judge and count while staging no row and opening no transaction.
 	 */
 	dryRun?: boolean
 	/**
-	 * Receives one report per country judged (a country with no dump or no dead rows reports zero outcomes).
+	 * Receives one report per country judged (a country with no dump or no dead rows reports zero results).
 	 */
 	onCountry?: (report: CurrencyBackfillCountryReport) => void
 }): Promise<number> {
@@ -151,7 +117,7 @@ export async function resurrectCurrencyHoles(ctx: {
 			country: cc,
 			deadPlacetypes,
 			dumpPresent: await pathExists(dumpPath),
-			...emptyOutcomes(),
+			...emptyResults(),
 			byDeadPlacetype: {},
 			sample: [],
 		}
@@ -163,9 +129,9 @@ export async function resurrectCurrencyHoles(ctx: {
 			continue
 		}
 
-		// Dead rows FIRST: a country with no deprecated-no-successor localities needs no attestors at all, and
-		// loading a national dump to judge zero rows is pure heap pressure on a build already near its ceiling
-		// (the first live run OOM'd in a later pass with JP/KR dumps loaded for 0 dead names each).
+		// Read dead rows first.
+		// A country with no dead names then avoids loading its national dump.
+		// That avoids heap pressure on a build near its limit.
 		const dead = deadStmt.all(cc, ...deadPlacetypes)
 
 		if (!dead.length) {
@@ -175,8 +141,8 @@ export async function resurrectCurrencyHoles(ctx: {
 			continue
 		}
 
-		// Only the dead names' own folded keys can ever be probed, so only those keys are worth holding —
-		// the rest of the national dump streams through without residency.
+		// Only the dead names' own folded keys can ever be probed, so the rest of the
+		// national dump streams through without residency.
 		const deadKeys = new Set<string>()
 
 		for (const d of dead) {
@@ -187,8 +153,7 @@ export async function resurrectCurrencyHoles(ctx: {
 			}
 		}
 
-		// Folded name → P-class attestors. GeoNames columns by index: 1 name, 2 ascii, 4 lat, 5 lon,
-		// 6 feature_class, 14 population.
+		// GeoNames columns by index: 1 name, 2 ascii, 4 lat, 5 lon, 6 feature_class, 14 population.
 		const attestors = new Map<string, { lat: number; lon: number; pop: number }[]>()
 
 		for await (const f of TSVSpliterator.fromAsync(dumpPath, { header: false })) {
@@ -215,11 +180,11 @@ export async function resurrectCurrencyHoles(ctx: {
 
 		const seen = new Set<string>()
 
-		const count = (deadPlacetype: string, outcome: keyof CurrencyBackfillOutcomes): void => {
-			report[outcome] += 1
-			const bucket = (report.byDeadPlacetype[deadPlacetype] ??= emptyOutcomes())
+		const count = (deadPlacetype: string, result: keyof CurrencyBackfillResults): void => {
+			report[result] += 1
+			const bucket = (report.byDeadPlacetype[deadPlacetype] ??= emptyResults())
 
-			bucket[outcome] += 1
+			bucket[result] += 1
 		}
 
 		if (!dryRun) {
@@ -232,31 +197,21 @@ export async function resurrectCurrencyHoles(ctx: {
 
 			if (!pkey || seen.has(pkey)) continue
 			seen.add(pkey)
-			// Read from the row: the query admits whatever `deadPlacetypes` names, and the rank comparison below must
-			// judge each candidate against ITS dead rung, never a hardcoded one.
+			// The query admits whatever `deadPlacetypes` names, so the rank comparison
+			// judges each candidate against its own dead rung.
 			const deadPlacetype = String(d.placetype ?? "locality")
 
 			count(deadPlacetype, "judged")
 			const dLat = Number(d.latitude)
 			const dLon = Number(d.longitude)
 
-			// A live row blocks only when it is AT LEAST AS COARSE as the dead one. The original check compared name and
-			// distance alone, on the premise that a nearby same-name row means "the place is alive under another
-			// placetype" — true for a place recorded twice, false for a placetype DEMOTION, which is the shape that
-			// actually occurs: WOF retired `Gillingham` the locality (pop 101,187) and kept `Gillingham` the
-			// neighbourhood 3.2 km away, and the check read the surviving CHILD as covering its own dead parent.
-			// Sixteen of seventeen GB refusals had exactly that shape (#1746).
-			//
-			// An UNRANKED placetype blocks, which is the conservative direction: this check's failure mode is inventing
-			// a place, so a row we cannot rank is treated as covering rather than waved through.
+			// A live row blocks unless it is strictly finer than the dead one.
+			// An unranked placetype also blocks because the failure mode is inventing a place.
 			const liveNear = liveStmt.all(cc, name).some((row) => {
 				if (haversineKm(dLat, dLon, Number(row.latitude), Number(row.longitude)) > CURRENCY_BACKFILL_RADIUS_KM) {
 					return false
 				}
 
-				// Blocks UNLESS the live row is strictly finer. The equal rung must still block — a live `locality`
-				// covers a dead `locality` — and an unranked placetype blocks too, since this check's failure mode
-				// is inventing a place.
 				return isStrictlyFiner(String(row.placetype ?? ""), deadPlacetype) !== true
 			})
 

package/lib/env.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- * Environment variables naming the WOF SQLite artifacts this resolver opens, and the development weights the overlay
+ * Environment variables name the WOF SQLite artifacts this resolver opens and the development weights the overlay
  *   linker materializes. CLI flags (`--resolve-db`, …) override these at the call site.
  */
 

package/lib/exact-match.ts

@@ -3,20 +3,25 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The exact-match tier's name probes — the two case-folded equality lookups that decide whether a
+ *   The exact-match tier's name probes, the two case-folded equality lookups that decide whether a
  *   candidate holds the query text as its own name, an alias, or an official name.
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { aliasBagExactMatch, foldQueryText } from "#fts/index"
+import { aliasBagExactMatch, foldQueryText } from "#fts"
 
 /**
- * Among `ids`, return the subset whose name OR any alias equals `text` case-insensitively — the exact-match tier for
- * ranking. One indexed query over `<schema>.names`. When the extract has no `names` table (a slim DB built with
- * `dropNames`, or a postcode-only extract), fall back to the self-contained `place_search` FTS content: its `alt_names`
- * column is the same alias set joined on the boundary-preserving `ALIAS_SEPARATOR` (#523), so `aliasBagExactMatch`
- * recovers the exact alias tier ("New York City" → New York) that the dropped `names` table used to provide.
+ * Among `ids`, return the subset whose name or any alias equals `text` case-insensitively,
+ * the exact-match tier for ranking.
+ *
+ * One indexed query over `<schema>.names`.
+ * When the extract has no `names` table (a slim database built with `dropNames`, or a postcode-only extract),
+ * fall back to the self-contained `place_search` FTS content.
+ *
+ * Its `alt_names` column is the same alias set joined on the boundary-preserving
+ * `ALIAS_SEPARATOR`, so `aliasBagExactMatch` recovers the exact alias tier
+ * ("New York City" → New York) that the dropped `names` table used to provide.
  */
 export function exactMatchIDs<DB>(
 	db: DatabaseClient<DB>,
@@ -41,7 +46,8 @@ export function exactMatchIDs<DB>(
 
 		return out
 	} catch {
-		// No `names` table on this extract — fall through to the place_search alias bag.
+		// No `names` table on this extract.
+		// Fall through to the place_search alias bag.
 	}
 
 	try {
@@ -52,17 +58,17 @@ export function exactMatchIDs<DB>(
 		const needle = foldQueryText(trimmed)
 
 		for (const r of rows) {
-			if (r.name !== null && foldQueryText(r.name) === needle) {
+			if (r.name && foldQueryText(r.name) === needle) {
 				out.add(r.id)
 			}
 		}
 
-		// Alias pass via the shared bag parser (#523). Separated bags (built since #523) get a true
-		// per-alias equality check, unrestricted — matching the `names`-table branch above, where an
-		// alias match counts as exact regardless of other candidates. Legacy bags (no separator)
-		// fall back to padded containment, conditioned on "no canonical exact in the pool" because their
-		// lost boundaries would otherwise false-promote interior fragments ("York" inside the alias
-		// "New York City") or cross-alias fragments ("York New" across "…York" + "New City…").
+		// Alias pass via the shared bag parser.
+		// Separated bags get a true per-alias equality check, unrestricted, matching the `names`-table
+		// branch above where an alias match counts as exact regardless of other candidates.
+		// Legacy bags without a separator fall back to padded containment, conditioned on "no
+		// canonical exact in the pool" because their lost boundaries would otherwise false-promote
+		// interior fragments ("York" inside the alias "New York City") or cross-alias fragments.
 		const anyCanonicalExact = out.size > 0
 
 		for (const r of rows) {
@@ -71,17 +77,22 @@ export function exactMatchIDs<DB>(
 			}
 		}
 	} catch {
-		// Extract without place_search either → no exact-match tier. Falls back to weighted-sum order.
+		// Extract without place_search either, so there is no exact-match tier.
+		// The caller falls back to weighted-sum order.
 	}
 
 	return out
 }
 
 /**
- * Among `ids` (already known exact matches), the subset holding `text` as an OFFICIAL name (`names.official = 1`, the
- * #940 ingest bit). Same COLLATE NOCASE semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs} so the two probes
- * agree on what "equals the query" means. Fails soft on gazetteers built before #940 (no `official` column) — the
- * sub-tier then behaves exactly as if `officialNameExact` were off.
+ * Among `ids` (already known exact matches), the subset holding `text` as an
+ * official name (`names.official = 1`, the ingest bit).
+ *
+ * Same collate nocase semantics as {@link WOFSQLitePlaceLookup.#exactMatchIDs},
+ * so the two probes agree on what "equals the query" means.
+ * Fails soft on gazetteers built before the `official` column existed.
+ *
+ * The sub-tier then behaves exactly as if `officialNameExact` were off.
  */
 export function officialNameIDs<DB>(
 	db: DatabaseClient<DB>,
@@ -106,7 +117,7 @@ export function officialNameIDs<DB>(
 			out.add(r.id)
 		}
 	} catch {
-		// Pre-#940 gazetteer (no `official` column) or a names-less slim extract — feature inert.
+		// A gazetteer without the `official` column, or a names-less slim extract, leaves the feature inert.
 	}
 
 	return out

package/lib/extracts.ts

@@ -1,36 +1,32 @@
-import { basename } from "path-ts"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { basename, PathBuilder, type PathBuilderLike } from "path-ts"
 
 /**
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Multi-extract support for `WOFSQLitePlaceLookup` — opens multiple WOF SQLite distributions on one
- *   connection via `ATTACH DATABASE`, and routes queries to the right extract based on placetype.
+ *   Multi-extract support for `WOFSQLitePlaceLookup`. It opens multiple WOF SQLite distributions
+ *   on one connection with `attach database`. It routes queries by placetype.
  *
- *   ## The FTS5 syntax rule that drove this design
- *
- *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
- *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
- *   the spike at PR review time; documented as `_EXTRACT_RULE.md` should it ever bite again.
- *
- *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *   SQLite parses a schema-qualified table on the left of `match` as "column place_search of table
+ *   pc", so the working form is schema-qualified in `from` and a bare table name in `match`:
  *
  *   ```sql
- *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ *   select … from pc.place_search where place_search match ?
  * ```
  *
- *   Identical table names across attached extracts (which is what we have — every extract ships its own
- *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
- *   scope.
+ *   Identical table names across attached extracts are fine, because the bare-name `match` resolves
+ *   against `from` scope. Every extract ships its own `place_search` and `place_bbox`.
  */
 
 /**
- * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS <name>` so each extract
- * gets a stable, predictable handle.
+ * Derive a SQL-safe schema name from a WOF distribution filename.
  *
- * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix, then replaces `-` with
- * `_` for SQL identifier safety.
+ * Used by `attach database … AS <name>` so each extract gets a stable, predictable handle.
+ *
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`)
+ * suffix, then replaces `-` with `_` for SQL identifier safety.
  *
  * Examples:
  *
@@ -39,46 +35,56 @@ import { basename } from "path-ts"
  * - `whosonfirst-data-admin-latest.db` → `admin`
  * - `my-custom.db` → `my_custom`
  *
- * Callers can override the derived name explicitly via `ExtractConfig.schemaName` when the filename doesn't follow WOF
- * convention.
+ * Callers can override the derived name explicitly via `ExtractConfig.schemaName`
+ * when the filename doesn't follow WOF convention.
  */
-export function deriveSchemaName(path: string): string {
-	const stem = basename(path)
+export function deriveSchemaName(path: PathBuilderLike): string {
+	const stem = basename(path.toString())
 		.replace(/^whosonfirst-data-/u, "")
 		.replace(/-latest\.db$/u, "")
 		.replace(/\.db$/u, "")
 		.replaceAll(/[^a-zA-Z0-9_]/g, "_")
 
 	if (!stem) {
-		throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`)
+		throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${stringifyJSON(path)}`)
 	}
 
 	return stem
 }
 
 /**
- * Per-extract configuration. The simple form is just a path string — the schema name is derived from it. The object
- * form lets callers override the derived schema name (useful when a filename doesn't follow WOF convention) or attach
- * an extra hint about which placetypes route here.
+ * Per-extract configuration.
+ *
+ * The simple form is just a path string.
+ * The schema name is derived from it.
+ *
+ * The object form lets callers override the derived schema name (useful when a filename
+ * doesn't follow WOF convention) or attach an extra hint about which placetypes route here.
  */
 export interface ExtractConfig {
-	path: string
+	path: PathBuilderLike
 	/**
-	 * Override the auto-derived schema name. Useful when the filename doesn't match WOF convention or when you want a
-	 * memorable handle. Must be a valid SQLite identifier — `[a-zA-Z_][a-zA-Z0-9_]*`.
+	 * Override the auto-derived schema name.
+	 *
+	 * Useful when the filename does not match WOF convention or when you want a memorable handle.
+	 * Must be a valid SQLite identifier matching `[a-zA-Z_][a-zA-Z0-9_]*`.
 	 */
 	schemaName?: string
 	/**
-	 * Optional explicit list of placetypes this extract serves. When set, queries against any listed placetype are routed
-	 * to this extract. When omitted, routing falls back to a name-match heuristic: a extract whose `schemaName` contains
-	 * the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries) is preferred for that placetype.
+	 * Optional explicit list of placetypes this extract serves.
+	 *
+	 * When set, queries against any listed placetype are routed to this extract.
+	 * When omitted, routing falls back to a name-match heuristic: an extract whose `schemaName`
+	 * contains the placetype as a substring (e.g. `postalcode_us` for `postalcode` queries)
+	 * is preferred for that placetype.
 	 */
 	placetypes?: readonly string[]
 }
 
 /**
- * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint. Used internally by
- * `WOFSQLitePlaceLookup` so the routing logic operates on uniform structures.
+ * Resolved post-derivation: paired path + chosen schema name + (possibly empty) placetypes hint.
+ *
+ * Used internally by `WOFSQLitePlaceLookup` so the routing logic operates on uniform structures.
  */
 export interface ResolvedExtract {
 	path: string
@@ -87,19 +93,30 @@ export interface ResolvedExtract {
 }
 
 /**
- * SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`.
+ * SQLite identifier regex matching `[A-Za-z_][A-Za-z0-9_]*`.
  */
 const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u
 
 /**
- * Normalize the user-provided `databasePath` opt (which may be a single string, an array of strings, or an array of
- * `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
+ * Whether a `databasePath` entry is a path or an {@link ExtractConfig}.
  *
- * The first extract becomes `main` regardless of its derived schema name — that's the SQLite convention. Subsequent
- * extracts keep their derived (or override) schema name.
+ * A builder is a `String` object, so `typeof` by itself reads it as an object.
  */
-export function resolveExtracts(input: string | ReadonlyArray<string | ExtractConfig>): ResolvedExtract[] {
-	const list = typeof input === "string" ? [input] : input
+function isPathBuilderLike(value: unknown): value is PathBuilderLike {
+	return typeof value === "string" || value instanceof PathBuilder
+}
+
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array
+ * of strings, or an array of `ExtractConfig` objects) into a uniform `ResolvedExtract[]`.
+ *
+ * The first extract becomes `main` regardless of its derived schema name, following SQLite convention.
+ * Subsequent extracts keep their derived or overridden schema name.
+ */
+export function resolveExtracts(
+	input: PathBuilderLike | ReadonlyArray<PathBuilderLike | ExtractConfig>
+): ResolvedExtract[] {
+	const list = isPathBuilderLike(input) ? [input] : input
 
 	if (!list.length) throw new Error("resolveExtracts: at least one extract is required")
 
@@ -108,24 +125,25 @@ export function resolveExtracts(input: string | ReadonlyArray<string | ExtractCo
 
 	for (let i = 0; i < list.length; i++) {
 		const entry = list[i]!
-		const cfg: ExtractConfig = typeof entry === "string" ? { path: entry } : entry
+		const cfg: ExtractConfig = isPathBuilderLike(entry) ? { path: entry } : entry
 		const derived = cfg.schemaName ?? deriveSchemaName(cfg.path)
 
 		if (!SQLITE_IDENT_RE.test(derived)) {
 			throw new Error(
-				`resolveExtracts: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
-					`(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
+				`resolveExtracts: schema name ${stringifyJSON(derived)} is not a valid SQLite identifier ` +
+					`(derived from path ${stringifyJSON(cfg.path)}). Pass an explicit ` +
 					`{ path, schemaName } to override.`
 			)
 		}
 
-		// The first extract is always main per SQLite semantics — its derived name is informational
-		// only. Subsequent extracts must have unique non-main names.
+		// SQLite always treats the first extract as main.
+		// Its derived name is informational only.
+		// Subsequent extracts must have unique non-main names.
 		const schemaName = i === 0 ? "main" : derived
 
 		if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
 			throw new Error(
-				`resolveExtracts: schema name ${JSON.stringify(schemaName)} collides ` +
+				`resolveExtracts: schema name ${stringifyJSON(schemaName)} collides ` +
 					`(either with "main" or another extract). Pass an explicit { path, schemaName }.`
 			)
 		}
@@ -133,7 +151,7 @@ export function resolveExtracts(input: string | ReadonlyArray<string | ExtractCo
 		seen.add(schemaName)
 
 		out.push({
-			path: cfg.path,
+			path: cfg.path.toString(),
 			schemaName,
 			placetypes: cfg.placetypes ?? [],
 		})
@@ -143,24 +161,11 @@ export function resolveExtracts(input: string | ReadonlyArray<string | ExtractCo
 }
 
 /**
- * Pick the extract to route a query to given the requested placetype(s).
- *
- * Routing rules, in order:
+ * All placetype-matching extracts, in routing order (the country-aware pick chooses among these).
  *
- * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
- * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype (e.g. `postalcode_us` matches `postalcode`),
- *    use it.
- * 3. Otherwise, fall back to `main`.
- *
- * This deliberately doesn't UNION across extracts — BM25 scores aren't comparable across separately- indexed corpora,
- * and the typical mailwoman query has a single placetype anyway. If a caller needs cross-extract results they can issue
- * two `findPlace` calls.
- */
-/**
- * All placetype-matching extracts, in routing order (the country-aware pick chooses among these). Used by the bias
- * path: a country-less postcode query with proximity hints fans out across every matching extract and merges, because
- * single-extract routing would hide the cross-country ambiguity the hints exist to resolve ("48026" lives in
- * postalcode-us AND postalcode-intl).
+ * Used by the bias path: a country-less postcode query with proximity hints fans out across
+ * every matching extract and merges, because single-extract routing would hide the cross-country
+ * ambiguity the hints exist to resolve ("48026" lives in postalcode-us and postalcode-intl).
  */
 export function pickExtractsForPlacetype(
 	extracts: ResolvedExtract[],
@@ -190,16 +195,34 @@ export function pickExtractsForPlacetype(
 	return matches.length ? matches : [extracts[0]!]
 }
 
+/**
+ * Pick the extract to route a query to given the requested placetype(s).
+ *
+ * The resolver applies these routing rules in order:
+ *
+ * 1. If any extract has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main extract's `schemaName` matches the placetype
+ *    (e.g. `postalcode_us` matches `postalcode`), use it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately does not union across extracts.
+ * BM25 scores are not comparable across separately indexed corpora.
+ * A typical mailwoman query has one placetype.
+ *
+ * Callers that need cross-extract results can issue two `findPlace` calls.
+ */
 export function pickExtractForPlacetype(
 	extracts: ResolvedExtract[],
-	placetype: string | undefined,
+	placetype: string | null,
 	opts?: {
 		/**
-		 * #920: the query's country constraint, when the caller has one. With MULTIPLE extracts matching a placetype
-		 * (postalcode-us + postalcode-geonames-tail), first-match routing sent every postcode query to the first extract
-		 * and starved the rest — a FI postcode could never reach the tail extract. When `country` is given and a matching
-		 * extract's probed country set contains it, that extract wins; extracts without the country are skipped; the
-		 * placetype-match order remains the tiebreak when no extract claims the country (or none was probed).
+		 * The query's country constraint, when the caller has one.
+		 *
+		 * When `country` is given and a matching extract's probed country set contains it, that extract wins.
+		 * Extracts without the country are skipped.
+		 *
+		 * The placetype-match order remains the tiebreak when no extract claims
+		 * the country (or none was probed).
 		 */
 		country?: string
 		/**
@@ -221,9 +244,9 @@ export function pickExtractForPlacetype(
 	for (const s of extracts) {
 		if (s.schemaName === "main" || matches.includes(s)) continue
 
-		// Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
-		// placetype to appear at a word boundary in the schema name to avoid false hits like
-		// `region` matching `arboregion`.
+		// A substring match lets `postalcode_us` match `postalcode`.
+		// Conservative, requiring the placetype at a word boundary in the schema name
+		// to avoid false hits like `region` matching `arboregion`.
 		if (
 			s.schemaName === placetype ||
 			s.schemaName.startsWith(`${placetype}_`) ||