@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/lookup.ts

@@ -3,21 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `WOFSQLitePlaceLookup` — the resolver implementation backed by `node:sqlite` + a Kysely-typed
- *   query layer where the queries are non-trivial, and raw SQL where they aren't (FTS5 MATCH, the
- *   FTS index build).
- *
- *   See `docs/plan/phases/PHASE_4_2_wof_sqlite.md` for the design rationale.
+ * `WOFSQLitePlaceLookup` — the resolver implementation backed by `node:sqlite` plus a Kysely-typed query layer where the queries are non-trivial and raw SQL where they are not.
  */
 
 import { expandPlacetypeFilter } from "@mailwoman/codex/placetype-map"
 import type { Ancestor, CoincidentLocality } from "@mailwoman/core/resolver"
 import { allRows } from "@mailwoman/core/utils"
 import { haversineKm } from "@mailwoman/spatial"
-import type { SQLInputValue } from "@mailwoman/sqlite/client"
-import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { DatabaseClient, SQLInputValue } from "@mailwoman/sqlite/client"
+import { SQLiteLookup } from "@mailwoman/sqlite/lookup"
+import type { PathBuilderLike } from "path-ts"
 
-import { ancestorLineage } from "#ancestry/index"
+import { ancestorLineage } from "#ancestry"
 import { candidateFromSearchRow, rankCandidates } from "#candidate/scoring"
 import { loadCoincidentLocalities } from "#coincident-roles"
 import {
@@ -28,7 +25,7 @@ import {
 	type ConventionSource,
 	type ResolvedConvention,
 	type Strategy,
-} from "#convention/index"
+} from "#convention"
 import {
 	pickExtractForPlacetype,
 	pickExtractsForPlacetype,
@@ -44,7 +41,7 @@ import {
 	placeBboxExists,
 	placePopulationExists,
 	placeSearchFTSExists,
-} from "#fts/index"
+} from "#fts"
 import { normalizePlacetypes, sanitizeFTSQuery } from "#fts/query"
 import { cfNormalize, softNameScore } from "#name-score"
 import { encyclopedicClauses } from "#place-importance-schema"
@@ -57,61 +54,39 @@ import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "
 
 export interface WOFSQLitePlaceLookupOpts {
 	/**
-	 * Path to the WOF SQLite distribution on disk. Mutually exclusive with `database`.
-	 *
-	 * **Single string** — opens that one DB as the main extract.
-	 *
-	 * **Array** — opens the first entry as main, then ATTACHes each subsequent entry as a separate SQLite schema. Schema
-	 * names are derived from the filename (`whosonfirst-data-postalcode- us-latest.db` → `postalcode_us`); override with
-	 * `ExtractConfig.schemaName` when the filename doesn't follow WOF convention. See `extracts.ts` for the derivation
-	 * rules.
-	 *
-	 * Routing: queries with a `placetype` matching a extract's name (or explicit `placetypes` hint) are sent to that
-	 * extract; everything else hits main. Cross-extract UNION is NOT done — BM25 isn't comparable across
-	 * separately-indexed corpora.
+	 * Path to the WOF SQLite distribution on disk, mutually exclusive with `database`;
+	 * an array opens the first entry as main and ATTACHes the rest.
 	 */
-	databasePath?: string | ReadonlyArray<string | ExtractConfig>
+	databasePath?: PathBuilderLike | ReadonlyArray<PathBuilderLike | ExtractConfig>
 	/**
-	 * Pre-opened connection — primarily for tests against an inline fixture DB. Mutually exclusive with `databasePath`.
-	 * Multi-extract requires `databasePath` (so the lookup owns the ATTACH).
+	 * Pre-opened connection, mutually exclusive with `databasePath`; multi-extract requires `databasePath`.
 	 */
 	database?: DatabaseClient<WOFDatabase>
 	/**
-	 * If true, build the FTS5 `place_search` virtual table on construction if it doesn't already exist. The upstream WOF
-	 * distribution does NOT ship FTS5, so callers either set this once on first open or pre-build it via the
-	 * operator-side CLI documented in the README. Default false — the resolver assumes the index already exists and
-	 * errors loudly if it doesn't.
+	 * When true, build the FTS5 `place_search` virtual table on construction if
+	 * it is missing, on the main extract only.
 	 *
-	 * With multi-extract, `buildFTS: true` builds the index on the **main** extract only. Other extracts must be
-	 * pre-built via `mailwoman gazetteer build fts` — operator script for predictable cost.
+	 * @defaultValue `false`
 	 */
 	buildFTS?: boolean
 	/**
-	 * Geographic Rule Engine convention source (Direction E, #289). Per-WOF-polygon resolution profiles, either as a
-	 * ready `ConventionSource` or a plain `{ wofID: Convention }` seed map. Default empty — every query rides
-	 * `WORLD_DEFAULT` (the EU coordinate-first behavior). JP/KR/TW add rows; #290 wires a build-from-source sqlite-backed
-	 * source here.
+	 * Geographic Rule Engine convention source, either a ready `ConventionSource`
+	 * or a `{ wofID: Convention }` seed map.
+	 *
+	 * @defaultValue `[]`. An empty list resolves every query to `WORLD_DEFAULT`.
 	 */
 	conventions?: ConventionSource | Record<number, Convention>
 	/**
-	 * Opt-in postal-city alias reader (#475). When supplied, the coordinate-first locality scorer treats an observed
-	 * `postal_city` ("Antioch", postcode 37013) as a name-match alias for the geographic locality the postcode sits in
-	 * ("Nashville"), recovering the chronic postal-vs- geographic-city mismatch. Absent (the default), the resolver is
-	 * byte-identical — every alias code path is conditioned on this being non-null, so an unprovided reader changes no
-	 * score.
+	 * Opt-in postal-city alias reader.
+	 *
+	 * Absent, every alias code path is skipped and the resolver is byte-identical.
 	 */
 	postalCityAliases?: WOFPostalCityAliasLookup
 }
 
 /**
- * The coordinate-first candidate table (scripts/build-postcode-locality.ts): postcode → containing
- *
- * - Nearby localities with WOF alt-name aliases.
- */
-/**
- * The placetypes `pickExtractsForPlacetype`'s substring rule can route by name. Not every WOF placetype — only the ones
- * a purpose-built extract is ever named for — so the diagnostic below can say "this name routes nowhere" without
- * claiming to enumerate the gazetteer.
+ * The placetypes `pickExtractsForPlacetype`'s substring rule can route by name,
+ * a subset of the WOF placetypes.
  */
 const KNOWN_ROUTED_PLACETYPES: ReadonlyArray<string> = [
 	"postalcode",
@@ -125,86 +100,71 @@ const KNOWN_ROUTED_PLACETYPES: ReadonlyArray<string> = [
 const POSTCODE_LOCALITY_TABLE = "postcode_locality"
 
 /**
- * Tunables for the coordinate-first locality soft-score `Score = pc·S_pc + name·S_name + pop·S_pop` (each S in [0,1]).
- * The pc/name/pop WEIGHTS now come from the resolved convention's `scoringWeights` (`WORLD_DEFAULT` = 0.6/0.3/0.1 — the
- * EU values), so a locale can retune them as data. PC_DECAY_KM sets how fast S_pc falls with distance.
+ * Tunables for the coordinate-first locality soft-score
+ * `Score = pc·S_pc + name·S_name + pop·S_pop` (each S in [0,1]).
  */
 const CF_PC_DECAY_KM = 8
 /**
- * The chosen locality must be within this distance of the postcode's containing locality, else the postcode and the
- * parsed city name are judged to disagree (a transposed / wrong-for-the-city postcode) and the `mismatch` flag fires.
- * Generous enough that a city-state Ortsteil (~15km from the city centroid) and an abutting town (~few km) are NOT
- * flagged, tight enough to catch a wrong city (hundreds of km).
+ * The chosen locality must be within this distance of the postcode's containing
+ * locality or the `mismatch` flag fires.
  */
 const CF_MISMATCH_KM = 50
 
-export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
-	readonly #db: DatabaseClient<WOFDatabase>
-	/**
-	 * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
-	 * ownership is membership rather than a flag a later branch has to check.
-	 */
-	readonly #resources = new DisposableStack()
+export class WOFSQLitePlaceLookup extends SQLiteLookup<WOFDatabase> implements PlaceLookup {
 	readonly #weights: RankingWeights
 	/**
-	 * Cached at construction so we don't `sqlite_master` query on every findPlace call. Bbox + near- with-radius queries
-	 * fall back to no-filter when this is false, preserving compatibility with DBs that were FTS-built before the R*Tree
-	 * shipped.
+	 * Cached at construction.
 	 *
-	 * Per-extract: a extract is only considered to have the bbox index if its own R*Tree table exists.
+	 * An extract is considered to have the bbox index only if its own R*Tree table exists.
 	 */
 	readonly #hasBboxIndex: Map<string, boolean>
 	/**
-	 * Per-extract probe for the `place_population` aux table. When false, the LEFT JOIN is omitted from the SELECT and
-	 * population boost is 0 for every row — preserves compatibility with DBs built before this feature shipped.
+	 * Per-extract probe for the `place_population` aux table.
+	 *
+	 * When false, the left join is omitted and the population boost is 0 for every row.
 	 */
 	readonly #hasPopulationIndex: Map<string, boolean>
 	/**
-	 * Per-extract SELECT term + LEFT JOIN for the two-score split's `encyclopedic` carry (ROAD_TO_V9 §2 R1), probed and
-	 * built once at construction. Degrades to `NULL AS encyclopedic` with no join on a pre-split extract — every shipped
-	 * extract today. See {@link encyclopedicClauses} for why the probe is a column and not a table.
+	 * Per-extract select term and left join for the two-score split's `encyclopedic` value,
+	 * probed and built once at construction.
 	 */
 	readonly #encyclopedicClauses: Map<string, { select: string; join: string }>
 	/**
-	 * Per-extract probe for the `postcode_locality` table (the coordinate-first candidate table, built by
-	 * scripts/build-postcode-locality.ts). Cached at construction; null'd out when absent so the coord-first path
-	 * silently no-ops on a deployment that didn't ship the table.
+	 * Per-extract probe for the `postcode_locality` table, cached at construction
+	 * and null when absent so the coord-first path no-ops.
 	 */
 	readonly #postcodeLocalityExtract: string | null
 	/**
-	 * Resolved extract list. Always at least one entry; first is `main`. Multi-extract adds extras with their own derived
-	 * (or override) schema names.
+	 * Resolved extract list, always at least one entry with `main` first.
 	 */
 	readonly #extracts: ResolvedExtract[]
 	/**
-	 * #920: per-schema probed country sets for country-aware extract routing (non-main extracts only).
+	 * Per-schema probed country sets for country-aware extract routing, non-main extracts only.
 	 */
 	readonly #extractCountries: Map<string, ReadonlySet<string>>
 	/**
-	 * The Geographic Rule Engine (Direction E, #289). `#conventionSource` supplies per-WOF-polygon resolution profiles;
-	 * `#strategies` is the named-primitive registry the merged convention dispatches. Empty source → every query resolves
-	 * to `WORLD_DEFAULT` → byte-identical to the pre-engine coordinate-first path. `#countryWOFIdCache` memoizes the
-	 * country-code → country-WOF-id lookup that seeds the convention ancestor chain (one query per country, then
-	 * cached).
+	 * `#conventionSource` supplies per-WOF-polygon profiles for the Geographic Rule Engine.
+	 *
+	 * `#strategies` maps primitive names to strategies.
+	 * `#countryWOFIdCache` memoizes country-code to country-WOF-id lookups.
 	 */
 	readonly #conventionSource: ConventionSource
 	readonly #strategies: Map<string, Strategy>
 	readonly #countryWOFIdCache = new Map<string, number | null>()
 	/**
-	 * Strategy names already warned about — so an unknown name surfaces once, not once per query.
+	 * Strategy names already warned about, so an unknown name surfaces once.
 	 */
 	readonly #warnedUnknownStrategies = new Set<string>()
 	/**
-	 * Lazily-built `admin_id → coincident localities` map from the #403 relation (null until first use).
+	 * Lazily-built `admin_id → coincident localities` map, null until first use.
 	 */
 	#coincidentRolesCache: Map<number, CoincidentLocality[]> | null = null
 	/**
-	 * Per-id memoized ancestor lineages (#404) — a hot chain is queried once.
+	 * Per-id memoized ancestor lineages, queried once per chain.
 	 */
 	readonly #ancestorsCache = new Map<number, Ancestor[]>()
 	/**
-	 * Opt-in postal-city alias reader (#475). `null` unless `opts.postalCityAliases` was supplied — every alias code path
-	 * is conditioned on this, so the default resolver is byte-identical.
+	 * Opt-in postal-city alias reader, `null` unless supplied, so every alias path is skipped by default.
 	 */
 	readonly #postalCityAliases: WOFPostalCityAliasLookup | null
 
@@ -217,29 +177,26 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 			throw new Error("WOFSQLitePlaceLookup: one of `database` or `databasePath` is required")
 		}
 
-		if (opts.database) {
-			this.#db = opts.database
-			this.#extracts = [{ path: ":memory:", schemaName: "main", placetypes: [] }]
-		} else {
-			const extracts = resolveExtracts(opts.databasePath!)
-			this.#extracts = extracts
-			// Read-only by default — shipped gazetteer extracts are sealed 0444 and Docker `:ro` mounts
-			// forbid write-mode opens, so a writable open fails there. The only code path that writes to
-			// the main extract is `#ensureFTS()` (FTS5 index build), conditioned on `opts.buildFTS`; open writable
-			// ONLY when that build was explicitly requested. Every read query (FTS5 MATCH, the aux-table
-			// SELECTs, ATTACH, and the `busy_timeout` PRAGMA) works read-only. See the docker read-only
-			// mount limitation (#1213).
-			this.#db = this.#resources.use(new DatabaseClient<WOFDatabase>(extracts[0]!.path, { readOnly: !opts.buildFTS }))
-
-			// ATTACH each non-main extract. Schema names were validated by resolveExtracts, so safe to
-			// interpolate directly (SQLite ATTACH doesn't accept parameters for the schema name).
-			for (const s of extracts.slice(1)) {
-				this.#db.exec(`ATTACH DATABASE '${s.path.replaceAll("'", "''")}' AS ${s.schemaName}`)
-			}
+		const extracts: ResolvedExtract[] = opts.database
+			? [{ path: ":memory:", schemaName: "main", placetypes: [] }]
+			: resolveExtracts(opts.databasePath!)
+
+		// Read-only by default: shipped extracts are sealed 0444 and Docker `:ro`
+		// mounts forbid a write-mode open.
+		// Only `buildFTS` opens writable.
+		super(opts.database ? { database: opts.database } : { databasePath: extracts[0]!.path }, {
+			readOnly: !opts.buildFTS,
+		})
+
+		this.#extracts = extracts
+
+		// Schema names were validated by resolveExtracts, so interpolating them is safe.
+		// SQLite attach accepts no parameter for a schema name.
+		for (const s of extracts.slice(1)) {
+			this.database.exec(`ATTACH DATABASE '${s.path.replaceAll("'", "''")}' AS ${s.schemaName}`)
 		}
 
-		// node:sqlite has no .pragma() helper; pragmas are executed as plain SQL.
-		this.#db.exec("PRAGMA busy_timeout = 5000")
+		this.database.exec("PRAGMA busy_timeout = 5000")
 
 		if (opts.buildFTS) {
 			this.#ensureFTS()
@@ -249,8 +206,6 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 
 		this.#weights = { ...DEFAULT_WEIGHTS, ...weights }
 
-		// Probe each extract's aux-table presence — driven by per-extract table existence in
-		// sqlite_master. Cached at construction so findPlace doesn't query sqlite_master per call.
 		this.#hasBboxIndex = new Map()
 		this.#hasPopulationIndex = new Map()
 		this.#encyclopedicClauses = new Map()
@@ -258,25 +213,12 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		for (const s of this.#extracts) {
 			this.#hasBboxIndex.set(s.schemaName, this.#extractHasTable(s.schemaName, PLACE_BBOX_TABLE))
 			this.#hasPopulationIndex.set(s.schemaName, this.#extractHasTable(s.schemaName, PLACE_POPULATION_TABLE))
-			this.#encyclopedicClauses.set(s.schemaName, encyclopedicClauses(this.#db, s.schemaName))
+			this.#encyclopedicClauses.set(s.schemaName, encyclopedicClauses(this.database, s.schemaName))
 		}
 
-		// Every lookup path here reaches `place_search`, and a extract without it fails in one of two ways
-		// that are both hard to read: an unroutable name returns zero hits (indistinguishable from "this
-		// country has no places") and a routable one throws mid-query from deep inside a SELECT. The
-		// unroutable half is the worse of the two — a extract reaches routing only through the name
-		// `deriveSchemaName` derives from its FILENAME, so a file spelled one letter off the placetype it
-		// serves answers with nothing while holding every row that was asked for.
-		//
-		// Two independent things bring a extract under the guard, and it needs both. Carrying `spr` is a
-		// CLAIM to be a place extract. Carrying a name that routes is an INVITATION to be queried as one, and
-		// it is made by the filename alone — so a database with no tables at all still gets picked, still
-		// answers no query, and still dies inside a SELECT. Testing only the claim lets an empty or
-		// truncated file past construction; testing only the name would exempt a correctly-named build
-		// input. A extract needs to fail neither test to be exempt.
-		//
-		// Exempt by design: `postcode-locality-<cc>.db` carries a relation table and nothing else, matches
-		// no routed placetype, and is part of the documented default extract list.
+		// An extract is guarded when its path identifies a routed placetype
+		// or it contains `spr`, and must then contain `place_search`; testing only one of
+		// those would let an empty file through or exempt a build input.
 		for (const s of this.#extracts) {
 			if (s.schemaName === "main") continue
 
@@ -304,42 +246,31 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 			)
 		}
 
-		// #920 country-aware extract routing: probe each NON-MAIN extract's country set once at
-		// construction (they're small, purpose-built extracts — postcode/locality slices; main is the
-		// multi-GB admin DB and is the fallback anyway, so it is deliberately NOT scanned). Feeds
-		// pickExtractForPlacetype so two postcode extracts (postalcode-us + postalcode-geonames-tail)
-		// route by the query's country instead of first-match starving the second extract.
+		// Probe each non-main extract's country set once at construction so two postcode
+		// extracts route by the query's country instead of first-match starving the second.
 		this.#extractCountries = new Map()
 
 		for (const sh of this.#extracts) {
 			if (sh.schemaName === "main") continue
 
 			try {
-				const rows = this.#db
+				const rows = this.database
 					.prepare(`SELECT DISTINCT country FROM ${sh.schemaName}.spr WHERE country != ''`)
 					.all() as Array<{ country: string }>
 
 				this.#extractCountries.set(sh.schemaName, new Set(rows.map((r) => r.country)))
 			} catch {
-				// A extract without spr (or an attach oddity) just doesn't participate in country routing.
+				// An extract without spr (or an attach oddity) just doesn't participate in country routing.
 			}
 		}
 
-		// The postcode_locality table can live on any attached extract (typically its own
-		// `postcode-locality-<cc>.db`). Find the first extract that has it; null = coord-first disabled.
 		this.#postcodeLocalityExtract =
 			this.#extracts.find((s) => this.#extractHasTable(s.schemaName, POSTCODE_LOCALITY_TABLE))?.schemaName ?? null
 
-		// Opt-in postal-city alias reader (#475). Construction-time present-or-not is the check: null
-		// keeps the coordinate-first scorer byte-identical to pre-#475.
 		this.#postalCityAliases = opts.postalCityAliases ?? null
 
-		// The Geographic Rule Engine convention source. Precedence: an explicit `opts.conventions`
-		// (a ready source or a seed map) wins; else the build-from-source convention asset if one is
-		// attached (auto-detected, like the postcode_locality extract — adding conventions.db to
-		// databasePath enables it; queried on demand, not paged into memory); else empty, so EU rides
-		// WORLD_DEFAULT. The registry binds strategy NAMES to the SQL-bound primitives — adding a
-		// strategy is registering it here.
+		// Precedence: explicit `opts.conventions` wins, else an attached build-from-source
+		// convention asset, else empty so EU uses `WORLD_DEFAULT`.
 		const conventionExtract =
 			this.#extracts.find((s) => this.#extractHasTable(s.schemaName, ADDRESS_CONVENTION_TABLE))?.schemaName ?? null
 
@@ -348,7 +279,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 				? opts.conventions
 				: new SeedConventionSource(opts.conventions as Record<number, Convention>)
 			: conventionExtract
-				? new SqliteConventionSource(this.#db, conventionExtract)
+				? new SqliteConventionSource(this.database, conventionExtract)
 				: new SeedConventionSource()
 
 		this.#strategies = new Map<string, Strategy>([
@@ -358,15 +289,15 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	#extractHasTable(schemaName: string, tableName: string): boolean {
-		// For main, the existing helpers work directly. For attached extracts we have to ask via the
-		// schema-qualified `sqlite_master` view.
+		// Main uses the existing helpers.
+		// Attached extracts need the schema-qualified `sqlite_master`.
 		if (schemaName === "main") {
-			if (tableName === PLACE_BBOX_TABLE) return placeBboxExists(this.#db)
+			if (tableName === PLACE_BBOX_TABLE) return placeBboxExists(this.database)
 
-			if (tableName === PLACE_POPULATION_TABLE) return placePopulationExists(this.#db)
+			if (tableName === PLACE_POPULATION_TABLE) return placePopulationExists(this.database)
 		}
 
-		const row = this.#db
+		const row = this.database
 			.prepare(`SELECT name FROM ${schemaName}.sqlite_master WHERE type = 'table' AND name = ?`)
 			.get(tableName) as { name: string } | undefined
 
@@ -374,15 +305,11 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	async findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]> {
-		// Geographic Rule Engine dispatch (#289). Resolve the effective convention for this query
-		// (WORLD_DEFAULT for the EU locales — the seed source is empty) and run its candidate strategies
-		// in order; the first to return a non-null result wins. The default list,
-		// [postcode_area_resolution, fallback_fuzzy_name_match], reproduces the pre-engine coordinate-
-		// first → FTS fall-through exactly. Unknown strategy names are skipped, so a convention may name
-		// a primitive a future phase will register.
+		// Run the effective convention's candidate strategies in order.
+		// The first non-null result wins and unknown strategy names are skipped.
 		const convention = this.#conventionFor(query)
 
-		let outcome: PlaceCandidate[] = []
+		let found: PlaceCandidate[] = []
 
 		for (const name of convention.candidateStrategies) {
 			const strategy = this.#strategies.get(name)
@@ -395,23 +322,17 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 
 			const result = await strategy(query, convention)
 
-			if (result !== null) {
-				outcome = result
+			if (result) {
+				found = result
 
 				break
 			}
 		}
 
-		if (outcome.length) return outcome
+		if (found.length) return found
 
-		// #924: NL postcode retry ladder. The WOF NL postalcode repo stores full codes UNSPACED
-		// ('1012LG') plus 4-digit stems ('1012'), while Dutch addresses carry the spaced form
-		// ('1012 LG') — two FTS tokens that can never match the one-token doc (the #920 name law,
-		// resurfacing in a WOF-built extract). On a postcode-typed NL-shape miss, retry ONCE with the
-		// whitespace-joined form (block-level precision when the full-code row exists), then the
-		// 4-digit stem (area-level). Country-restricted to NL — the same digits+letters shape elsewhere
-		// must not silently coarsen to a different system's code. Each retry only fires when its
-		// text differs from the current one, so the ladder terminates by construction.
+		// On a postcode-typed NL-shape miss, retry with the whitespace-joined form then the 4-digit stem,
+		// restricted to NL so the same shape elsewhere cannot coarsen to another system's code.
 		if (
 			query.country?.toUpperCase() === "NL" &&
 			(normalizePlacetypes(query.placetype)?.includes("postalcode") ?? false) &&
@@ -431,14 +352,11 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 			if (stem !== trimmed) return this.findPlace({ ...query, text: stem })
 		}
 
-		return outcome
+		return found
 	}
 
 	/**
-	 * Dual-role localities coincident with an admin id, from the precomputed `coincident_roles` relation (#403). Backs
-	 * {@link ResolveOpts.hierarchyCompletion} (#405): O(1) once the relation is loaded. Returns `[]` when the relation
-	 * table is absent (older DB) or the admin isn't a dual-role place, so completion degrades gracefully. The relation +
-	 * `spr` join is loaded once and memoized.
+	 * Dual-role localities coincident with an admin id, or `[]` when the relation table is absent.
 	 */
 	coincidentLocalitiesFor(adminID: number | string): CoincidentLocality[] {
 		const id = typeof adminID === "number" ? adminID : Number(adminID)
@@ -446,20 +364,15 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		if (!Number.isFinite(id)) return []
 
 		if (!this.#coincidentRolesCache) {
-			this.#coincidentRolesCache = loadCoincidentLocalities(this.#db)
+			this.#coincidentRolesCache = loadCoincidentLocalities(this.database)
 		}
 
 		return this.#coincidentRolesCache.get(id) ?? []
 	}
 
 	/**
-	 * The ancestor lineage of a place — its containment chain joined with `spr` for canonical names, ordered
-	 * NEAREST-FIRST (localadmin → county → region → … → country). Backs {@link ResolveOpts.includeAncestors} (#404). Self
-	 * is excluded; memoized per id. Returns `[]` when the place has no recorded ancestry.
-	 *
-	 * The walk itself lives in `ancestry.ts` (shared with the reverse geocoder, #484); the ordering is its
-	 * `PLACETYPE_DEPTH` table — same ranking as the previous inline SQL CASE, extended below `localadmin` so
-	 * locality/neighbourhood ancestors order correctly instead of sorting last.
+	 * The ancestor lineage of a place, ordered nearest-first with self excluded,
+	 * or `[]` when it has no recorded ancestry.
 	 */
 	ancestors(id: number | string): Ancestor[] {
 		const pid = typeof id === "number" ? id : Number(id)
@@ -469,7 +382,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 
 		if (cached) return cached
 
-		const lineage: Ancestor[] = ancestorLineage(this.#db, pid).map((r) => ({
+		const lineage: Ancestor[] = ancestorLineage(this.database, pid).map((r) => ({
 			id: r.id,
 			placetype: r.placetype,
 			name: r.name,
@@ -481,10 +394,8 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Surface an unknown strategy name LOUDLY (once per name) rather than swallowing it silently — an invisible no-op is
-	 * exactly the hidden-dependency failure mode we avoid (see the provenance-first design value). We warn rather than
-	 * throw so a convention asset built against a newer code revision (one that adds a strategy) degrades gracefully on
-	 * an older build instead of taking down resolution.
+	 * Warn once per unknown strategy name rather than throwing, so a convention built
+	 * against a newer revision degrades instead of stopping resolution.
 	 */
 	#warnUnknownStrategy(name: string): void {
 		if (this.#warnedUnknownStrategies.has(name)) return
@@ -498,10 +409,8 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Strategy `postcode_area_resolution` — the coordinate-first locality path, strictly conditioned (a sibling postcode
-	 * AND a postcode_locality table AND a locality query). Returns `null` — so the dispatcher falls through to the next
-	 * strategy — when the condition is unmet or the postcode isn't in the table; otherwise the soft-scored postcode∪name
-	 * candidate set.
+	 * The coordinate-first locality strategy, returning `null` when its postcode,
+	 * table, or locality conditions are unmet.
 	 */
 	#postcodeAreaResolution(query: FindPlaceQuery, convention: ResolvedConvention): Promise<PlaceCandidate[] | null> {
 		if (!(query.postcode && this.#postcodeLocalityExtract && this.#isLocalityQuery(query))) {
@@ -512,34 +421,30 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Strategy `fallback_fuzzy_name_match` — the BM25 FTS name-match over the gazetteer, the universal fallback. Always
-	 * returns an array (never null), so it terminates the dispatch chain.
+	 * The BM25 FTS name-match fallback, always returning an array so it terminates the dispatch chain.
 	 */
 	async #fuzzyNameMatch(query: FindPlaceQuery, forceExtract?: ResolvedExtract): Promise<PlaceCandidate[]> {
 		const limit = query.limit ?? 10
 
-		// Expand the placetype filter through the shared equivalence table (core/resolver): a
-		// `locality` query must also reach `borough` / `localadmin` rows — Brooklyn-the-borough
-		// (pop 2.5M) is a borough, not a locality, and a strict filter made it unreachable so the
-		// fuzzy "Brooklyn Park, MN" won instead. Order-preserving: the FIRST entry stays the
-		// requested placetype, which is what extract routing keys off below.
+		// Expand the placetype filter through the shared equivalence table so a `locality`
+		// query also reaches `borough` and `localadmin` rows.
 		const placetypes = expandPlacetypeFilter(normalizePlacetypes(query.placetype)) as WOFPlacetype[] | null
-		// Postcode-typed queries keep the #920 fused name-law shape; everything else splits on
-		// intra-token punctuation so hyphenated names reach the FTS as their real terms (#945).
+		// Postcode-typed queries keep the fused name-law shape.
+		// Everything else splits on intra-token punctuation so hyphenated names
+		// reach the FTS as their real terms.
 		const ftsQuery = sanitizeFTSQuery(query.text, { fuseTokens: placetypes?.includes("postalcode") ?? false })
 
 		if (!ftsQuery) return []
 
-		// Pick the extract for this query. Multi-extract routing is placetype-driven; a query without
-		// `placetype` always goes to main. (Mixed-placetype queries with multiple extracts aren't
-		// supported in v1 — caller can issue two findPlace calls and merge in TS if needed.)
+		// Multi-extract routing uses placetype.
+		// Queries without `placetype` go to main.
+		// Mixed-placetype spread across extracts is unsupported.
 		const firstPlacetype = placetypes?.[0]
 
-		// Bias fan-out (#58/proximity-bias): a country-less query WITH proximity hints must see the
-		// cross-extract ambiguity the hints exist to resolve — "48026" lives in postalcode-us AND
-		// postalcode-intl, and single-extract routing would hide one side. Query every matching extract
-		// (self-recursion with a extract pin), merge by id, and re-sort by the same (exact, prominence)
-		// keys the per-extract tier sort used. Bounded: hints + no country + >1 matching extract only.
+		// A country-less query with proximity hints queries every matching extract
+		// so cross-extract ambiguity is visible.
+		// The bound requires hints and an absent country.
+		// It also requires more than one matching extract.
 		const hasBiasHints = !!query.near || (query.bias?.length ?? 0) > 0
 
 		if (!forceExtract && hasBiasHints && !query.country) {
@@ -575,16 +480,16 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 
 		const extract =
 			forceExtract ??
-			pickExtractForPlacetype(this.#extracts, firstPlacetype, {
+			pickExtractForPlacetype(this.#extracts, firstPlacetype ?? null, {
 				country: query.country,
 				countriesBySchema: this.#extractCountries,
 			})
 
-		// bare schema name; safe to interpolate (validated at construction)
+		// Validated at construction, so bare interpolation is safe.
 		const sch = extract.schemaName
 
 		const rawRows = fetchSearchRows({
-			db: this.#db,
+			db: this.database,
 			schemaName: sch,
 			query,
 			placetypes,
@@ -606,7 +511,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		const candidates = rawRows.map((row) => candidateFromSearchRow(row, scoring))
 
 		rankCandidates(candidates, {
-			db: this.#db,
+			db: this.database,
 			schemaName: sch,
 			query,
 			weights: this.#weights,
@@ -622,11 +527,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Resolve the effective convention for a query (the Geographic Rule Engine entry point). The ancestor chain is keyed
-	 * by WOF polygon id; for #289 it carries just the country level — resolved from `query.country` via the cached
-	 * code→WOF-id lookup — so the EU locales, which have no override rows, resolve to `WORLD_DEFAULT` and dispatch is
-	 * byte-identical to the pre-engine path. E4 (JP) extends the chain with the resolved locality's `ancestors` row, so a
-	 * region/locality-level convention (e.g. Sapporo's grid) deep-merges over the country one.
+	 * Resolve the effective convention for a query, keyed by the country's WOF polygon id.
 	 */
 	#conventionFor(query: FindPlaceQuery): ResolvedConvention {
 		const chain: number[] = []
@@ -643,8 +544,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Country ISO code → its WOF polygon id (the coarsest convention key). Cached — one indexed `spr` query per distinct
-	 * country, then memoized (including a not-found `null`) so findPlace never pays for it twice.
+	 * Country ISO code to its WOF polygon id, memoized including the not-found `null`.
 	 */
 	#countryWOFId(code: string): number | null {
 		const cached = this.#countryWOFIdCache.get(code)
@@ -653,7 +553,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		let id: number | null
 
 		try {
-			const row = this.#db
+			const row = this.database
 				.prepare(`SELECT id FROM main.spr WHERE placetype = 'country' AND country = ? AND is_current != 0 LIMIT 1`)
 				.get(code) as { id: number } | undefined
 
@@ -668,12 +568,9 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Coordinate-first locality resolution. The postcode_locality table maps the sibling postcode to the locality whose
-	 * polygon contains the postcode centroid (+ a few nearby ones for the abutting- postcode case). We union those
-	 * COORDINATE candidates with the FTS NAME candidates and soft-score the union `0.6·S_pc + 0.3·S_name + 0.1·S_pop` —
-	 * so a small town the name-match never finds is recovered by the postcode, while an unambiguous name (Berlin) still
-	 * wins on name + population. Returns null when the postcode isn't in the table (→ caller falls back to the FTS
-	 * path).
+	 * Coordinate-first locality resolution: union the postcode's containing
+	 * and nearby localities with the FTS name candidates and soft-score them,
+	 * returning null when the postcode is not in the table.
 	 */
 	async #findLocalityCoordFirst(
 		query: FindPlaceQuery,
@@ -686,7 +583,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		const pcParams: SQLInputValue[] = query.country ? [pc, query.country] : [pc]
 
 		const pcRows = allRows<{ id: number; aliases: string | null; dist: number; containing: number }>(
-			this.#db.prepare(
+			this.database.prepare(
 				`SELECT locality_id AS id, aliases, distance_km AS dist, is_containing AS containing
 				 FROM ${sch}.${POSTCODE_LOCALITY_TABLE} WHERE ${pcWhere}`
 			),
@@ -696,7 +593,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		if (!pcRows.length) return null
 
 		const limit = query.limit ?? 10
-		// Name-match candidates via the normal FTS path (postcode cleared → no recursion).
+		// Name-match candidates via the normal FTS path with the postcode cleared, so this cannot recurse.
 		const ftsCands = await this.findPlace({ ...query, postcode: undefined, limit: Math.max(limit, 10) })
 
 		const pcInfo = new Map<number, { dist: number; containing: boolean; aliases: string[] }>()
@@ -705,10 +602,8 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 			pcInfo.set(r.id, { dist: r.dist, containing: r.containing === 1, aliases: r.aliases ? r.aliases.split("|") : [] })
 		}
 
-		// #475 (opt-in): observed postal-city aliases for this postcode, keyed by the geographic
-		// locality name they map to. A user-typed postal city ("Antioch", 37013) becomes a name-match
-		// alias for the geographic locality the postcode sits in ("Nashville"). Empty when the reader
-		// isn't supplied → the scoring loop below is byte-identical to pre-#475.
+		// Observed postal-city aliases for this postcode keyed by geographic locality name,
+		// empty when the reader is not supplied.
 		const postalAliasByGeo = new Map<string, string[]>()
 
 		if (this.#postalCityAliases) {
@@ -743,9 +638,8 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		for (const cand of merged.values()) {
 			const info = pcInfo.get(cand.id as number)
 			const sPc = info ? (info.containing ? 1 : Math.exp(-info.dist / CF_PC_DECAY_KM)) : 0
-			// Fold any postal-city aliases for this candidate's geographic name into the soft name match
-			// (#475). `postalAliasByGeo` is empty unless the opt-in reader was supplied, so when off this
-			// reduces to the original `info?.aliases ?? []` and the score is unchanged.
+			// Fold postal-city aliases into the soft name match.
+			// The map is empty unless the opt-in reader was supplied, so scoring is unchanged when off.
 			const wofAliases = info?.aliases ?? []
 
 			const aliases = postalAliasByGeo.size
@@ -753,30 +647,23 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 				: wofAliases
 
 			const sName = softNameScore(query.text, cand.name, aliases)
-			const sPop = populationScaleTerm(cand.population, this.#weights)
+			const sPop = populationScaleTerm(cand.population ?? null, this.#weights)
 			scored.push({ ...cand, score: w.pc * sPc + w.name * sName + w.pop * sPop, exact: sName >= 1 })
 		}
 
-		// Exact-name tiering (same philosophy as the FTS path): an EXACT name/alias match tiers above
-		// coordinate-only candidates, with the soft-score breaking ties WITHIN a tier. This keeps an
-		// unambiguous city ("Berlin", exact + huge population) ahead of the fine-grained Ortsteil its
-		// postcode centroid lands in, while a small town the name-match never finds (no exact tier) is
-		// still recovered by its postcode's containing locality.
+		// An exact name or alias match tiers above coordinate-only candidates,
+		// with the soft score breaking ties within a tier.
 		scored.sort((a, b) => Number(b.exact) - Number(a.exact) || b.score - a.score)
 
-		// Conflict flag: if the chosen locality is NOT the postcode's containing locality and sits far
-		// from it, the postcode and the city name disagree (a transposed / wrong-for-the-city postcode).
-		// We keep the name-chosen locality but flag it — the falsehood signal a BM25 geocoder can't give.
+		// When the chosen locality is not the postcode's containing locality and sits far
+		// from it, flag `mismatch` rather than overriding the name.
 		const top = scored[0]
 
 		if (top) {
-			// The postcode's geographic anchor: among the postcode's candidate localities that actually
-			// resolved (some — e.g. unnamed Ortsteile — are in the postcode table but not the admin DB),
-			// prefer the containing one, else the nearest. Postcodes whose centroid falls just outside
-			// every locality polygon still anchor to the closest town.
+			// Among the postcode's candidate localities that resolved, prefer the containing one, else the nearest.
 			const anchorRow = pcRows
 				.filter((r) => merged.has(r.id))
-				// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array; toSorted would double-allocate on a hot path
+				// oxlint-disable-next-line unicorn/no-array-sort -- sorts a freshly-built array. toSorted would double-allocate on a hot path
 				.sort((a, b) => b.containing - a.containing || a.dist - b.dist)[0]
 
 			const anchor = anchorRow ? merged.get(anchorRow.id) : undefined
@@ -798,7 +685,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 	}
 
 	/**
-	 * Fetch locality spr rows (from main) for the postcode-injected candidate ids the FTS set missed.
+	 * Fetch locality spr rows from main for the postcode-injected candidate ids the FTS set missed.
 	 */
 	#fetchLocalitiesByID(ids: number[]): PlaceCandidate[] {
 		if (!ids.length) return []
@@ -808,7 +695,7 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		const ph = ids.map(() => "?").join(", ")
 
 		const rows = allRows<RawSearchRow>(
-			this.#db.prepare(
+			this.database.prepare(
 				`SELECT s.id AS id, s.name AS name, s.country AS country, s.parent_id AS parent_id,
 				        s.latitude AS lat, s.longitude AS lon, s.placetype AS placetype, ${popSelect}
 				 FROM main.spr s ${popJoin}
@@ -818,45 +705,43 @@ export class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
 		)
 
 		return rows.map((row) => {
-			const c: PlaceCandidate = {
+			return {
 				id: row.id,
 				name: row.name,
 				placetype: row.placetype as WOFPlacetype,
 				country: row.country ?? "",
 				lat: row.lat ?? 0,
 				lon: row.lon ?? 0,
-				parent_id: row.parent_id ?? undefined,
+				parent_id: row.parent_id ?? null,
 				score: 0,
-			}
-
-			if (row.population !== null && row.population > 0) {
-				c.population = row.population
-			}
-
-			return c
+				population: row.population !== null && row.population > 0 ? row.population : null,
+				distanceKm: null,
+				exactMatch: null,
+				prominence: null,
+				referential: null,
+				encyclopedic: null,
+				importance: null,
+				bbox: null,
+				mismatch: null,
+				containedByQualifier: null,
+				regionScopeMiss: null,
+				variantAliasExempted: null,
+			} satisfies PlaceCandidate
 		})
 	}
 
-	[Symbol.dispose](): void {
-		// Only when we opened it. A caller who passed a pre-opened client keeps using it after this returns — the FTS
-		// build this lookup performed lives on their connection, and closing it would take that with us.
-		this.#resources[Symbol.dispose]()
-	}
-
 	/**
-	 * Build the FTS5 virtual table from the `names` + `places` tables.
+	 * Build the FTS5 virtual table from the `names` and `places` tables.
 	 */
 	#ensureFTS(): void {
-		buildPlaceSearchFTS(this.#db)
+		buildPlaceSearchFTS(this.database)
 	}
 
 	#assertFTSExists(): void {
-		if (!placeSearchFTSExists(this.#db)) {
+		if (!placeSearchFTSExists(this.database)) {
 			throw new Error(
 				"WOFSQLitePlaceLookup: `place_search` FTS5 table is missing. Pass `buildFTS: true` to build it on open, or run `mailwoman gazetteer build fts <path-to-wof.db>` ahead of time (see resolver-wof-sqlite/README.md)."
 			)
 		}
 	}
 }
-
-export type { RankingWeights } from "#ranking-weights"