@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/lookup.js

@@ -3,22 +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 { allRows } from "@mailwoman/core/utils";
 import { haversineKm } from "@mailwoman/spatial";
-import { DatabaseClient } from "@mailwoman/sqlite/client";
-import { ancestorLineage } from "#ancestry/index";
+import { SQLiteLookup } from "@mailwoman/sqlite/lookup";
+import { ancestorLineage } from "#ancestry";
 import { candidateFromSearchRow, rankCandidates } from "#candidate/scoring";
 import { loadCoincidentLocalities } from "#coincident-roles";
-import { ADDRESS_CONVENTION_TABLE, resolveConvention, SeedConventionSource, } from "#convention/index";
+import { ADDRESS_CONVENTION_TABLE, resolveConvention, SeedConventionSource, } from "#convention";
 import { pickExtractForPlacetype, pickExtractsForPlacetype, resolveExtracts, } from "#extracts";
-import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE, placeBboxExists, placePopulationExists, placeSearchFTSExists, } from "#fts/index";
+import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE, placeBboxExists, placePopulationExists, placeSearchFTSExists, } from "#fts";
 import { normalizePlacetypes, sanitizeFTSQuery } from "#fts/query";
 import { cfNormalize, softNameScore } from "#name-score";
 import { encyclopedicClauses } from "#place-importance-schema";
@@ -26,14 +22,8 @@ import { DEFAULT_WEIGHTS, populationScaleTerm } from "#ranking-weights";
 import { fetchSearchRows } from "#search-fetch";
 import { SqliteConventionSource } from "#sqlite/convention-source";
 /**
- * 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 = [
     "postalcode",
@@ -45,85 +35,70 @@ const KNOWN_ROUTED_PLACETYPES = [
 ];
 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 {
-    #db;
-    /**
-     * 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.
-     */
-    #resources = new DisposableStack();
+export class WOFSQLitePlaceLookup extends SQLiteLookup {
     #weights;
     /**
-     * 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.
      */
     #hasBboxIndex;
     /**
-     * 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.
      */
     #hasPopulationIndex;
     /**
-     * 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.
      */
     #encyclopedicClauses;
     /**
-     * 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.
      */
     #postcodeLocalityExtract;
     /**
-     * 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.
      */
     #extracts;
     /**
-     * #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.
      */
     #extractCountries;
     /**
-     * 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.
      */
     #conventionSource;
     #strategies;
     #countryWOFIdCache = new Map();
     /**
-     * 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.
      */
     #warnedUnknownStrategies = new Set();
     /**
-     * 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 = null;
     /**
-     * Per-id memoized ancestor lineages (#404) — a hot chain is queried once.
+     * Per-id memoized ancestor lineages, queried once per chain.
      */
     #ancestorsCache = new Map();
     /**
-     * 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.
      */
     #postalCityAliases;
     constructor(opts, weights) {
@@ -133,28 +108,22 @@ export class WOFSQLitePlaceLookup {
         if (!opts.database && !opts.databasePath) {
             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(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 = 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();
         }
@@ -162,32 +131,17 @@ export class WOFSQLitePlaceLookup {
             this.#assertFTSExists();
         }
         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();
         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;
@@ -208,45 +162,34 @@ export class WOFSQLitePlaceLookup {
                     : ` Its schema name "${s.schemaName}" also matches no routed placetype (${KNOWN_ROUTED_PLACETYPES.join(", ")}), ` +
                         `so it would never have been queried even with the table — check the filename's spelling.`));
         }
-        // #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();
                 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;
         this.#conventionSource = opts.conventions
             ? "get" in opts.conventions && typeof opts.conventions.get === "function"
                 ? opts.conventions
                 : new SeedConventionSource(opts.conventions)
             : conventionExtract
-                ? new SqliteConventionSource(this.#db, conventionExtract)
+                ? new SqliteConventionSource(this.database, conventionExtract)
                 : new SeedConventionSource();
         this.#strategies = new Map([
             ["postcode_area_resolution", (q, c) => this.#postcodeAreaResolution(q, c)],
@@ -254,28 +197,24 @@ export class WOFSQLitePlaceLookup {
         ]);
     }
     #extractHasTable(schemaName, tableName) {
-        // 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);
+                return placeBboxExists(this.database);
             if (tableName === PLACE_POPULATION_TABLE)
-                return placePopulationExists(this.#db);
+                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);
         return Boolean(row);
     }
     async findPlace(query) {
-        // 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 = [];
+        let found = [];
         for (const name of convention.candidateStrategies) {
             const strategy = this.#strategies.get(name);
             if (!strategy) {
@@ -283,21 +222,15 @@ export class WOFSQLitePlaceLookup {
                 continue;
             }
             const result = await strategy(query, convention);
-            if (result !== null) {
-                outcome = result;
+            if (result) {
+                found = result;
                 break;
             }
         }
-        if (outcome.length)
-            return outcome;
-        // #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.
+        if (found.length)
+            return found;
+        // 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) &&
             /^\d{4}\s?[A-Za-z]{2}$/.test(query.text.trim())) {
@@ -312,31 +245,23 @@ export class WOFSQLitePlaceLookup {
             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) {
         const id = typeof adminID === "number" ? adminID : Number(adminID);
         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) {
         const pid = typeof id === "number" ? id : Number(id);
@@ -345,7 +270,7 @@ export class WOFSQLitePlaceLookup {
         const cached = this.#ancestorsCache.get(pid);
         if (cached)
             return cached;
-        const lineage = ancestorLineage(this.#db, pid).map((r) => ({
+        const lineage = ancestorLineage(this.database, pid).map((r) => ({
             id: r.id,
             placetype: r.placetype,
             name: r.name,
@@ -354,10 +279,8 @@ export class WOFSQLitePlaceLookup {
         return lineage;
     }
     /**
-     * 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) {
         if (this.#warnedUnknownStrategies.has(name))
@@ -368,10 +291,8 @@ export class WOFSQLitePlaceLookup {
             `against a newer code revision, rebuild the asset for this one.`);
     }
     /**
-     * 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, convention) {
         if (!(query.postcode && this.#postcodeLocalityExtract && this.#isLocalityQuery(query))) {
@@ -380,31 +301,27 @@ export class WOFSQLitePlaceLookup {
         return this.#findLocalityCoordFirst(query, this.#postcodeLocalityExtract, convention);
     }
     /**
-     * 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, forceExtract) {
         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));
-        // 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) {
             const matching = pickExtractsForPlacetype(this.#extracts, firstPlacetype);
@@ -427,14 +344,14 @@ export class WOFSQLitePlaceLookup {
             }
         }
         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,
@@ -453,7 +370,7 @@ export class WOFSQLitePlaceLookup {
         };
         const candidates = rawRows.map((row) => candidateFromSearchRow(row, scoring));
         rankCandidates(candidates, {
-            db: this.#db,
+            db: this.database,
             schemaName: sch,
             query,
             weights: this.#weights,
@@ -465,11 +382,7 @@ export class WOFSQLitePlaceLookup {
         return !pts || pts.includes("locality");
     }
     /**
-     * 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) {
         const chain = [];
@@ -482,8 +395,7 @@ export class WOFSQLitePlaceLookup {
         return resolveConvention(this.#conventionSource, chain);
     }
     /**
-     * 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) {
         const cached = this.#countryWOFIdCache.get(code);
@@ -491,7 +403,7 @@ export class WOFSQLitePlaceLookup {
             return cached;
         let id;
         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);
             id = row?.id ?? null;
@@ -503,33 +415,28 @@ export class WOFSQLitePlaceLookup {
         return id;
     }
     /**
-     * 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, sch, convention) {
         const w = convention.scoringWeights;
         const pc = query.postcode.trim();
         const pcWhere = query.country ? "postcode = ? AND country = ?" : "postcode = ?";
         const pcParams = query.country ? [pc, query.country] : [pc];
-        const pcRows = allRows(this.#db.prepare(`SELECT locality_id AS id, aliases, distance_km AS dist, is_containing AS containing
+        const pcRows = allRows(this.database.prepare(`SELECT locality_id AS id, aliases, distance_km AS dist, is_containing AS containing
 				 FROM ${sch}.${POSTCODE_LOCALITY_TABLE} WHERE ${pcWhere}`), ...pcParams);
         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();
         for (const r of pcRows) {
             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();
         if (this.#postalCityAliases) {
             for (const a of await this.#postalCityAliases.getDivergentAliases(pc)) {
@@ -557,35 +464,27 @@ export class WOFSQLitePlaceLookup {
         for (const cand of merged.values()) {
             const info = pcInfo.get(cand.id);
             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
                 ? [...wofAliases, ...(postalAliasByGeo.get(cfNormalize(cand.name)) ?? [])]
                 : 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;
             if (anchor &&
@@ -600,7 +499,7 @@ export class WOFSQLitePlaceLookup {
         });
     }
     /**
-     * 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) {
         if (!ids.length)
@@ -609,40 +508,43 @@ export class WOFSQLitePlaceLookup {
         const popSelect = hasPop ? `pp.population AS population` : `NULL AS population`;
         const popJoin = hasPop ? `LEFT JOIN main.${PLACE_POPULATION_TABLE} pp ON pp.id = s.id` : "";
         const ph = ids.map(() => "?").join(", ");
-        const rows = allRows(this.#db.prepare(`SELECT s.id AS id, s.name AS name, s.country AS country, s.parent_id AS parent_id,
+        const rows = allRows(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}
 				 WHERE s.id IN (${ph}) AND s.is_current != 0`), ...ids);
         return rows.map((row) => {
-            const c = {
+            return {
                 id: row.id,
                 name: row.name,
                 placetype: row.placetype,
                 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,
+                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,
             };
-            if (row.population !== null && row.population > 0) {
-                c.population = row.population;
-            }
-            return c;
         });
     }
-    [Symbol.dispose]() {
-        // 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() {
-        buildPlaceSearchFTS(this.#db);
+        buildPlaceSearchFTS(this.database);
     }
     #assertFTSExists() {
-        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).");
         }
     }