@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/out/lookup.js

@@ -3,53 +3,46 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `WOFSqlitePlaceLookup` — the resolver implementation backed by `node:sqlite` + a Kysely-typed
+ *   `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.
  */
-import { DatabaseSync } from "node:sqlite";
-import { SqliteDialect } from "@mailwoman/core/kysley/dialect";
 import { expandPlacetypeFilter } from "@mailwoman/resolver";
-import { Kysely } from "kysely";
-import { ancestorLineage } from "./ancestry.js";
-import { COINCIDENT_ROLES_TABLE, coincidentRolesExists } from "./coincident-roles.js";
-import { ADDRESS_CONVENTION_TABLE, resolveConvention, SeedConventionSource, } from "./convention.js";
-import { normalizePlacetypes, sanitizeFTSQuery } from "./fts-query.js";
-import { aliasBagExactMatch, buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, placeBboxExists, placePopulationExists, placeSearchFTSExists, } from "./fts.js";
-import { bboxAround, haversineKm } from "./geo.js";
-import { cfNormalize, softNameScore, trigramJaccard } from "./name-score.js";
-import { compareReferential, encyclopedicClauses, referentialFromPopulation } from "./place-importance-schema.js";
-import { DEFAULT_WEIGHTS } from "./ranking-weights.js";
-import { pickShardForPlacetype, pickShardsForPlacetype, resolveShards, } from "./sharding.js";
-import { SqliteConventionSource } from "./sqlite-convention-source.js";
-/**
- * Query length at or below which the FTS window is widened. A two- or three-character query is almost always a region
- * abbreviation, where the exact match can otherwise fall outside the window behind higher-bm25 partial hits — "NY"
- * losing to "New York".
- */
-const SHORT_QUERY_MAX_LENGTH = 3;
-/**
- * Over-fetch floor for SHORT (≤3-char) queries — region abbreviations like "NY"/"VT". An exact-abbrev holder's BM25 is
- * poor (long multilingual alt-name document), so the normal `limit * 4` window can drop it before `exactMatchTiering`
- * promotes it. 200 comfortably covers every same-abbrev region across the 12-country gazetteer (a 2-letter token
- * matches a few dozen regions at most) while staying a cheap region-placetype fetch. See the `#fuzzyNameMatch`
- * over-fetch comment.
- */
-const SHORT_QUERY_OVERFETCH = 200;
-/**
- * How many rows the population-ordered companion fetch (#905) adds to the candidate pool. Small on purpose: its only
- * job is to guarantee the FAMOUS holders of a name enter the pool at all — for "Paris"-class floods the bm25 window is
- * saturated by thousands of tiny same-name rows and no boost inside the bm25-based ORDER BY can rescue a candidate
- * whose bm25 is length-poisoned by ~15 points (see the fetch-site comment).
- */
-const POPULATION_FETCH_LIMIT = 15;
+import { haversineKm } from "@mailwoman/spatial";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { ancestorLineage } from "#ancestry/index";
+import { candidateFromSearchRow, rankCandidates } from "#candidate-scoring";
+import { loadCoincidentLocalities } from "#coincident-roles";
+import { ADDRESS_CONVENTION_TABLE, resolveConvention, SeedConventionSource, } from "#convention/index";
+import { pickExtractForPlacetype, pickExtractsForPlacetype, resolveExtracts, } from "#extracts";
+import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE, placeBboxExists, placePopulationExists, placeSearchFTSExists, } from "#fts/index";
+import { normalizePlacetypes, sanitizeFTSQuery } from "#fts/query";
+import { cfNormalize, softNameScore } from "#name-score";
+import { encyclopedicClauses } from "#place-importance-schema";
+import { DEFAULT_WEIGHTS, populationScaleTerm } from "#ranking-weights";
+import { fetchSearchRows } from "#search-fetch";
+import { SqliteConventionSource } from "#sqlite-convention-source";
+import { allRows } from "#sqlite-utils";
 /**
  * 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.
+ */
+const KNOWN_ROUTED_PLACETYPES = [
+    "postalcode",
+    "locality",
+    "region",
+    "county",
+    "country",
+    "venue",
+];
 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]).
@@ -64,46 +57,48 @@ const CF_PC_DECAY_KM = 8;
  * flagged, tight enough to catch a wrong city (hundreds of km).
  */
 const CF_MISMATCH_KM = 50;
-const CF_MISMATCH_DELTA = 0.5;
-export class WOFSqlitePlaceLookup {
+export class WOFSQLitePlaceLookup {
     #db;
-    #ownsDB;
-    #kysely;
+    /**
+     * 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();
     #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.
      *
-     * Per-shard: a shard is only considered to have the bbox index if its own R*Tree table exists.
+     * Per-extract: a extract is only considered to have the bbox index if its own R*Tree table exists.
      */
     #hasBboxIndex;
     /**
-     * Per-shard probe for the `place_population` aux table. When false, the LEFT JOIN is omitted from the SELECT and
+     * 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.
      */
     #hasPopulationIndex;
     /**
-     * Per-shard 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 shard — every shipped
-     * shard today. See {@link encyclopedicClauses} for why the probe is a column and not a table.
+     * 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.
      */
     #encyclopedicClauses;
     /**
-     * Per-shard probe for the `postcode_locality` table (the coordinate-first candidate table, built by
+     * 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.
      */
-    #postcodeLocalityShard;
+    #postcodeLocalityExtract;
     /**
-     * Resolved shard list. Always at least one entry; first is `main`. Multi-shard adds extras with their own derived (or
-     * override) schema names.
+     * Resolved extract list. Always at least one entry; first is `main`. Multi-extract adds extras with their own derived
+     * (or override) schema names.
      */
-    #shards;
+    #extracts;
     /**
-     * #920: per-schema probed country sets for country-aware shard routing (non-main shards only).
+     * #920: per-schema probed country sets for country-aware extract routing (non-main extracts only).
      */
-    #shardCountries;
+    #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
@@ -128,35 +123,33 @@ export class WOFSqlitePlaceLookup {
     #ancestorsCache = new Map();
     /**
      * Opt-in postal-city alias reader (#475). `null` unless `opts.postalCityAliases` was supplied — every alias code path
-     * is gated on this, so the default resolver is byte-identical.
+     * is conditioned on this, so the default resolver is byte-identical.
      */
     #postalCityAliases;
     constructor(opts, weights) {
         if (opts.database && opts.databasePath) {
-            throw new Error("WOFSqlitePlaceLookup: pass either `database` or `databasePath`, not both");
+            throw new Error("WOFSQLitePlaceLookup: pass either `database` or `databasePath`, not both");
         }
         if (!opts.database && !opts.databasePath) {
-            throw new Error("WOFSqlitePlaceLookup: one of `database` or `databasePath` is required");
+            throw new Error("WOFSQLitePlaceLookup: one of `database` or `databasePath` is required");
         }
         if (opts.database) {
             this.#db = opts.database;
-            this.#ownsDB = false;
-            this.#shards = [{ path: ":memory:", schemaName: "main", placetypes: [] }];
+            this.#extracts = [{ path: ":memory:", schemaName: "main", placetypes: [] }];
         }
         else {
-            const shards = resolveShards(opts.databasePath);
-            this.#shards = shards;
-            // Read-only by default — shipped gazetteer shards are sealed 0444 and Docker `:ro` mounts
+            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 shard is `#ensureFTS()` (FTS5 index build), gated on `opts.buildFTS`; open writable
+            // 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 = new DatabaseSync(shards[0].path, { readOnly: !opts.buildFTS });
-            this.#ownsDB = true;
-            // ATTACH each non-main shard. Schema names were validated by resolveShards, so safe to
+            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 shards.slice(1)) {
+            for (const s of extracts.slice(1)) {
                 this.#db.exec(`ATTACH DATABASE '${s.path.replaceAll("'", "''")}' AS ${s.schemaName}`);
             }
         }
@@ -168,67 +161,100 @@ export class WOFSqlitePlaceLookup {
         else {
             this.#assertFTSExists();
         }
-        this.#kysely = new Kysely({
-            dialect: new SqliteDialect({ database: this.#db }),
-        });
         this.#weights = { ...DEFAULT_WEIGHTS, ...weights };
-        // Probe each shard's aux-table presence — driven by per-shard table existence in
+        // 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.#shards) {
-            this.#hasBboxIndex.set(s.schemaName, this.#shardHasTable(s.schemaName, PLACE_BBOX_TABLE));
-            this.#hasPopulationIndex.set(s.schemaName, this.#shardHasTable(s.schemaName, PLACE_POPULATION_TABLE));
+        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));
         }
-        // #920 country-aware shard routing: probe each NON-MAIN shard's country set once at
-        // construction (they're small, purpose-built shards — postcode/locality slices; main is the
+        // 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.
+        for (const s of this.#extracts) {
+            if (s.schemaName === "main")
+                continue;
+            const routes = KNOWN_ROUTED_PLACETYPES.some((pt) => s.schemaName === pt || s.schemaName.startsWith(`${pt}_`) || s.schemaName.endsWith(`_${pt}`));
+            const claimsPlaceExtract = this.#extractHasTable(s.schemaName, "spr");
+            if (!routes && !claimsPlaceExtract)
+                continue;
+            if (this.#extractHasTable(s.schemaName, PLACE_SEARCH_TABLE))
+                continue;
+            throw new Error(`WOFSQLitePlaceLookup: ${s.path} ` +
+                (claimsPlaceExtract
+                    ? `carries "spr" but no "${PLACE_SEARCH_TABLE}" table, so it cannot serve a lookup.`
+                    : `is named for a routed placetype but carries neither "spr" nor "${PLACE_SEARCH_TABLE}", so every ` +
+                        `query routed to it would die mid-SELECT. An empty or truncated file reads exactly like this.`) +
+                ` Build it with the FTS index, or leave it out — it is usable as a BUILD input either way.` +
+                (routes
+                    ? ""
+                    : ` 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
-        // pickShardForPlacetype so two postcode shards (postalcode-us + postalcode-geonames-tail)
-        // route by the query's country instead of first-match starving the second shard.
-        this.#shardCountries = new Map();
-        for (const sh of this.#shards) {
+        // pickExtractForPlacetype so two postcode extracts (postalcode-us + postalcode-geonames-tail)
+        // route by the query's country instead of first-match starving the second extract.
+        this.#extractCountries = new Map();
+        for (const sh of this.#extracts) {
             if (sh.schemaName === "main")
                 continue;
             try {
                 const rows = this.#db
                     .prepare(`SELECT DISTINCT country FROM ${sh.schemaName}.spr WHERE country != ''`)
                     .all();
-                this.#shardCountries.set(sh.schemaName, new Set(rows.map((r) => r.country)));
+                this.#extractCountries.set(sh.schemaName, new Set(rows.map((r) => r.country)));
             }
             catch {
-                // A shard without spr (or an attach oddity) just doesn't participate in country routing.
+                // A extract without spr (or an attach oddity) just doesn't participate in country routing.
             }
         }
-        // The postcode_locality table can live on any attached shard (typically its own
-        // `postcode-locality-<cc>.db`). Find the first shard that has it; null = coord-first disabled.
-        this.#postcodeLocalityShard =
-            this.#shards.find((s) => this.#shardHasTable(s.schemaName, POSTCODE_LOCALITY_TABLE))?.schemaName ?? null;
-        // Opt-in postal-city alias reader (#475). Construction-time present-or-not is the gate: null
+        // 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 shard — adding conventions.db to
+        // 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.
-        const conventionShard = this.#shards.find((s) => this.#shardHasTable(s.schemaName, ADDRESS_CONVENTION_TABLE))?.schemaName ?? null;
+        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)
-            : conventionShard
-                ? new SqliteConventionSource(this.#db, conventionShard)
+            : conventionExtract
+                ? new SqliteConventionSource(this.#db, conventionExtract)
                 : new SeedConventionSource();
         this.#strategies = new Map([
             ["postcode_area_resolution", (q, c) => this.#postcodeAreaResolution(q, c)],
             ["fallback_fuzzy_name_match", (q) => this.#fuzzyNameMatch(q)],
         ]);
     }
-    #shardHasTable(schemaName, tableName) {
-        // For main, the existing helpers work directly. For attached shards we have to ask via the
+    #extractHasTable(schemaName, tableName) {
+        // For main, the existing helpers work directly. For attached extracts we have to ask via the
         // schema-qualified `sqlite_master` view.
         if (schemaName === "main") {
             if (tableName === PLACE_BBOX_TABLE)
@@ -267,9 +293,9 @@ export class WOFSqlitePlaceLookup {
         // #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 shard). On a postcode-typed NL-shape miss, retry ONCE with the
+        // 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-gated to NL — the same digits+letters shape elsewhere
+        // 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 (query.country?.toUpperCase() === "NL" &&
@@ -299,38 +325,7 @@ export class WOFSqlitePlaceLookup {
         if (!Number.isFinite(id))
             return [];
         if (!this.#coincidentRolesCache) {
-            const map = new Map();
-            if (coincidentRolesExists(this.#db)) {
-                const rows = this.#db
-                    .prepare(`SELECT cr.admin_id AS adminID, s.id AS id, s.name AS name, s.country AS country,
-							s.latitude AS lat, s.longitude AS lon,
-							cr.relationship_type AS relationshipType, cr.locality_population AS population,
-							cr.distance_km AS distanceKm
-						FROM ${COINCIDENT_ROLES_TABLE} cr JOIN spr s ON s.id = cr.locality_id`)
-                    .all();
-                for (const r of rows) {
-                    const candidate = {
-                        id: r.id,
-                        name: r.name,
-                        placetype: "locality",
-                        country: r.country,
-                        lat: r.lat,
-                        lon: r.lon,
-                        score: 0,
-                        relationshipType: r.relationshipType,
-                        population: r.population,
-                        distanceKm: r.distanceKm,
-                    };
-                    const list = map.get(r.adminID);
-                    if (list) {
-                        list.push(candidate);
-                    }
-                    else {
-                        map.set(r.adminID, [candidate]);
-                    }
-                }
-            }
-            this.#coincidentRolesCache = map;
+            this.#coincidentRolesCache = loadCoincidentLocalities(this.#db);
         }
         return this.#coincidentRolesCache.get(id) ?? [];
     }
@@ -368,61 +363,51 @@ export class WOFSqlitePlaceLookup {
         if (this.#warnedUnknownStrategies.has(name))
             return;
         this.#warnedUnknownStrategies.add(name);
-        console.warn(`WOFSqlitePlaceLookup: a convention names strategy "${name}", which this build does not register ` +
+        console.warn(`WOFSQLitePlaceLookup: a convention names strategy "${name}", which this build does not register ` +
             `(known: ${[...this.#strategies.keys()].join(", ")}). Skipping it. If the convention asset was built ` +
             `against a newer code revision, rebuild the asset for this one.`);
     }
     /**
-     * Strategy `postcode_area_resolution` — the coordinate-first locality path, strictly gated (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 gate is unmet or the postcode isn't in the table; otherwise the soft-scored postcode∪name
+     * 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.
      */
     #postcodeAreaResolution(query, convention) {
-        if (!(query.postcode && this.#postcodeLocalityShard && this.#isLocalityQuery(query))) {
+        if (!(query.postcode && this.#postcodeLocalityExtract && this.#isLocalityQuery(query))) {
             return Promise.resolve(null);
         }
-        return this.#findLocalityCoordFirst(query, this.#postcodeLocalityShard, convention);
+        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.
      */
-    async #fuzzyNameMatch(query, forceShard) {
+    async #fuzzyNameMatch(query, forceExtract) {
         const limit = query.limit ?? 10;
-        // Over-fetch so post-scoring + exact-match tiering have room to re-rank. SHORT queries (a 2–3-char
-        // region abbreviation like "NY"/"VT") are the danger case the `exactMatchTiering` docstring flags:
-        // the exact-abbrev holder's BM25 is poor (its long multilingual alt-name document tanks the score),
-        // so under the normal `limit * 4` window it drops OUT of the candidate pool BEFORE tiering can
-        // promote it — "NY" then resolves to a token-matching foreign region (Highland, GB) instead of New
-        // York. Widen the window for short queries so the exact match is always present to be tiered.
-        // (Cross-country abbrev collisions — "VT" is BOTH Vermont and Viterbo — still need a country/
-        // postcode signal to disambiguate; this only rescues the window-drop class, not genuine ambiguity.
-        // With a `country` hint every abbrev resolves; bare + no-context lifts 7→10/15 US states.)
-        const ftsLimit = query.text.trim().length <= SHORT_QUERY_MAX_LENGTH ? Math.max(limit * 4, SHORT_QUERY_OVERFETCH) : limit * 4;
         // 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 shard routing keys off below.
+        // requested placetype, which is what extract routing keys off below.
         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).
         const ftsQuery = sanitizeFTSQuery(query.text, { fuseTokens: placetypes?.includes("postalcode") ?? false });
         if (!ftsQuery)
             return [];
-        // Pick the shard for this query. Multi-shard routing is placetype-driven; a query without
-        // `placetype` always goes to main. (Mixed-placetype queries with multiple shards aren't
+        // 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.)
         const firstPlacetype = placetypes?.[0];
         // Bias fan-out (#58/proximity-bias): a country-less query WITH proximity hints must see the
-        // cross-shard ambiguity the hints exist to resolve — "48026" lives in postalcode-us AND
-        // postalcode-intl, and single-shard routing would hide one side. Query every matching shard
-        // (self-recursion with a shard pin), merge by id, and re-sort by the same (exact, prominence)
-        // keys the per-shard tier sort used. Bounded: hints + no country + >1 matching shard only.
+        // 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.
         const hasBiasHints = !!query.near || (query.bias?.length ?? 0) > 0;
-        if (!forceShard && hasBiasHints && !query.country) {
-            const matching = pickShardsForPlacetype(this.#shards, firstPlacetype);
+        if (!forceExtract && hasBiasHints && !query.country) {
+            const matching = pickExtractsForPlacetype(this.#extracts, firstPlacetype);
             if (matching.length > 1) {
                 const pools = [];
                 for (const sh of matching) {
@@ -441,317 +426,38 @@ export class WOFSqlitePlaceLookup {
                 return merged.slice(0, limit);
             }
         }
-        const shard = forceShard ??
-            pickShardForPlacetype(this.#shards, firstPlacetype, {
+        const extract = forceExtract ??
+            pickExtractForPlacetype(this.#extracts, firstPlacetype, {
                 country: query.country,
-                countriesBySchema: this.#shardCountries,
+                countriesBySchema: this.#extractCountries,
             });
-        const sch = shard.schemaName; // bare schema name; safe to interpolate (validated at construction)
-        // Filter out historical / superseded / deprecated places by default — they live in the same
-        // spr table but should never win a contemporary lookup. `is_current = 0` is the only WOF
-        // value that means "not current"; both `-1` (modern) and `1` (legacy) mean current. See #91.
-        // Note: with schema-qualified FROM the bare `place_search` reference in MATCH resolves to
-        // the FROM table — required by FTS5 parser, see sharding.ts header comment.
-        const where = ["place_search MATCH ?", "spr.is_current != 0", "spr.is_deprecated = 0"];
-        const params = [ftsQuery];
-        if (placetypes && placetypes.length) {
-            where.push(`spr.placetype IN (${placetypes.map(() => "?").join(", ")})`);
-            params.push(...placetypes);
-        }
-        if (query.country) {
-            where.push("spr.country = ?");
-            params.push(query.country);
-        }
-        if (query.parentID !== undefined) {
-            where.push(`(spr.parent_id = ? OR spr.id IN (SELECT id FROM ${sch}.ancestors WHERE ancestor_id = ?))`);
-            params.push(query.parentID, query.parentID);
-        }
-        // Bbox + near-with-radius are SQL-level filters via the R*Tree. We only emit the JOIN when
-        // the active shard has the R*Tree; missing-but-requested is silently treated as no-bbox-
-        // filter so legacy DBs / shards-without-bbox don't crash.
-        const shardHasBbox = this.#hasBboxIndex.get(sch) === true;
-        const useBboxJoin = (query.bbox || query.near?.maxDistanceKm !== undefined) && shardHasBbox;
-        let joinClause = `JOIN ${sch}.spr ON spr.id = place_search.wof_id`;
-        if (useBboxJoin) {
-            joinClause += ` JOIN ${sch}.${PLACE_BBOX_TABLE} bbox ON bbox.id = spr.id`;
-            // AABB intersection — both bbox sides must overlap. R*Tree handles this in O(log n).
-            const filterBox = query.bbox || bboxAround(query.near.lat, query.near.lon, query.near.maxDistanceKm);
-            where.push("bbox.min_lat <= ? AND bbox.max_lat >= ?", "bbox.min_lon <= ? AND bbox.max_lon >= ?");
-            params.push(filterBox.maxLat, filterBox.minLat, filterBox.maxLon, filterBox.minLon);
-        }
-        // LEFT JOIN the population aux table when present. Missing-on-this-shard means the SELECT
-        // just doesn't include the population column; the post-scoring loop treats it as 0.
-        const shardHasPopulation = this.#hasPopulationIndex.get(sch) === true;
-        const populationSelect = shardHasPopulation
-            ? `${PLACE_POPULATION_TABLE}.population AS population`
-            : `NULL AS population`;
-        const populationJoin = shardHasPopulation
-            ? `LEFT JOIN ${sch}.${PLACE_POPULATION_TABLE} ON ${PLACE_POPULATION_TABLE}.id = spr.id`
-            : "";
-        // The encyclopedic score is CARRIED, never ranked on (ROAD_TO_V9 §2, ratified 2026-08-06) — it
-        // appears in the SELECT and in no ORDER BY, here or in the companion fetch below. Gated on the
-        // split column, so a pre-split shard emits a literal NULL and builds no join at all.
-        const { select: encyclopedicSelect, join: encyclopedicJoin } = this.#encyclopedicClauses.get(sch);
-        // Push the population boost into the ORDER BY when the index is available, so famous places
-        // (whose long alt-name lists hurt BM25) actually make it into the over-fetch window. The TS
-        // post-scoring will still compute the same boost for the final score; this just ensures the
-        // candidate set is right.
-        //
-        // Formula: rank_adjusted = bm25 - populationBoost * min(1.0, log10(1 + pop) / scaleLog10)
-        // Lower rank_adjusted = better (matches SQLite's bm25 convention of "more negative = better").
-        //
-        // #905 — do NOT reach for bm25 column weights here. Measured falsification (2026-07-02): FTS5's
-        // bm25 length normalization is polluted by the row's TOTAL document size, so identical 1-token
-        // `name` docs read −16.0 (empty alt_names) vs −0.43 (2.7 KB alt_names) EVEN with the alt_names
-        // column weighted to zero — no weighting isolates name relevance in this schema. The famous-
-        // holder guarantee lives in the population-ordered companion fetch below instead, and the
-        // exact tier breaks ties by population in the post-scoring sort.
-        const orderByExpr = shardHasPopulation
-            ? `(bm25(place_search) - ? * MIN(1.0, COALESCE(log10(1.0 + ${PLACE_POPULATION_TABLE}.population), 0) / ?))`
-            : "bm25(place_search)";
-        // Schema-qualified FROM with bare-name MATCH — required syntax for FTS5 on attached schemas.
-        // See sharding.ts header for the gotcha that drove this design.
-        const stmt = this.#db.prepare(`
-			SELECT
-				spr.id AS id,
-				spr.name,
-				spr.placetype,
-				spr.country,
-				spr.parent_id,
-				bm25(place_search) AS rank,
-				spr.latitude AS lat,
-				spr.longitude AS lon,
-				spr.min_latitude, spr.max_latitude, spr.min_longitude, spr.max_longitude,
-				${populationSelect},
-				${encyclopedicSelect}
-			FROM ${sch}.place_search
-			${joinClause}
-			${populationJoin}
-			${encyclopedicJoin}
-			WHERE ${where.join(" AND ")}
-			ORDER BY ${orderByExpr} ASC
-			LIMIT ?
-		`);
-        if (shardHasPopulation) {
-            params.push(this.#weights.populationBoost, this.#weights.populationScaleLog10);
-        }
-        params.push(ftsLimit);
-        const rawRows = stmt.all(...params);
-        // #905 companion fetch: the same MATCH, ordered by population alone. For name floods
-        // ("Paris" matches thousands of gap-fill villages) the bm25-based window above cannot admit
-        // the famous holder — its bm25 is length-poisoned by the row's alias bulk (measured ~15 pts,
-        // vs a +4.0 boost cap), so FR Paris never even reaches post-scoring. This fetch makes the
-        // prominent holders of a name pool-complete BY CONSTRUCTION; the exact-tier sort below
-        // decides whether they win. Skipped without a population index (nothing to order by).
-        if (shardHasPopulation) {
-            const popStmt = this.#db.prepare(`
-				SELECT
-					spr.id AS id,
-					spr.name,
-					spr.placetype,
-					spr.country,
-					spr.parent_id,
-					bm25(place_search) AS rank,
-					spr.latitude AS lat,
-					spr.longitude AS lon,
-					spr.min_latitude, spr.max_latitude, spr.min_longitude, spr.max_longitude,
-					${populationSelect},
-					${encyclopedicSelect}
-				FROM ${sch}.place_search
-				${joinClause}
-				${populationJoin}
-				${encyclopedicJoin}
-				WHERE ${where.join(" AND ")}
-				ORDER BY COALESCE(${PLACE_POPULATION_TABLE}.population, 0) DESC
-				LIMIT ?
-			`);
-            const popParams = params.slice(0, -3); // drop the two boost params + ftsLimit
-            const seen = new Set(rawRows.map((r) => r.id));
-            for (const row of popStmt.all(...popParams, POPULATION_FETCH_LIMIT)) {
-                if (!seen.has(row.id)) {
-                    rawRows.push(row);
-                }
-            }
-        }
-        const queryLen = query.text.length;
-        const candidates = rawRows.map((row) => {
-            // SQLite's bm25() returns a lower-is-better score (negative for matches). Negate so we
-            // start from a higher-is-better baseline.
-            let score = -row.rank;
-            if (placetypes && placetypes.length && placetypes.includes(row.placetype)) {
-                score += this.#weights.placetypeMatchBoost;
-            }
-            if (!placetypes && row.placetype === "locality") {
-                score += this.#weights.localityImplicitBoost;
-            }
-            if (query.country && row.country === query.country) {
-                score += this.#weights.countryMatchBoost;
-            }
-            if (query.parentID !== undefined) {
-                score += row.parent_id === query.parentID ? this.#weights.directChildBoost : this.#weights.descendantBoost;
-            }
-            const extraLen = Math.max(0, row.name.length - queryLen - 3);
-            score -= (this.#weights.lengthPenaltyWeight * extraLen) / 10;
-            // Proximity boost: only applied when the query carries `near` AND the candidate has real
-            // coordinates. The formula decays smoothly with distance so close-but-not-exact hits
-            // still benefit; tunable via proximityBoost + proximityScaleKm.
-            let distanceKm;
-            // The best decayed-distance term over `near` + every `bias` point (each point's term is
-            // scaled by its weight; the MAX wins — a candidate near ANY hint is "nearby"). Carried
-            // into the exact-tier prominence sort below when hints are present.
-            let proximityTerm = 0;
-            if (row.lat !== null && row.lon !== null && !(row.lat === 0 && row.lon === 0)) {
-                const hints = [];
-                if (query.near) {
-                    hints.push({ lat: query.near.lat, lon: query.near.lon, weight: 1 });
-                }
-                for (const b of query.bias ?? []) {
-                    hints.push({ lat: b.lat, lon: b.lon, weight: b.weight ?? 1 });
-                }
-                let scoreTerm = 0;
-                for (const h of hints) {
-                    const d = haversineKm(h.lat, h.lon, row.lat, row.lon);
-                    const decay = h.weight / (1 + d / this.#weights.proximityScaleKm);
-                    const prom = decay * this.#weights.biasBoost;
-                    if (prom > proximityTerm) {
-                        proximityTerm = prom;
-                        distanceKm = d;
-                        scoreTerm = decay * this.#weights.proximityBoost;
-                    }
-                }
-                score += scoreTerm;
-            }
-            // Population boost: capped at `populationBoost` magnitude at `10^populationScaleLog10`
-            // people. Missing population → no contribution. Never penalizes.
-            let popTerm = 0;
-            if (row.population !== null && row.population > 0 && this.#weights.populationScaleLog10 > 0) {
-                const popLog = Math.log10(1 + row.population);
-                const popFraction = Math.min(1, popLog / this.#weights.populationScaleLog10);
-                popTerm = this.#weights.populationBoost * popFraction;
-                score += popTerm;
-            }
-            // Combined prominence for the exact-tier sort when proximity hints are present: population
-            // and nearness in the SAME additive units, so the map view / the user's location can win a
-            // cross-country postcode tie without a hard filter.
-            const prominence = popTerm + proximityTerm;
-            const candidate = {
-                id: row.id,
-                prominence,
-                name: row.name,
-                placetype: row.placetype,
-                country: row.country ?? "",
-                lat: row.lat ?? 0,
-                lon: row.lon ?? 0,
-                parent_id: row.parent_id ?? undefined,
-                score,
-            };
-            if (distanceKm !== undefined) {
-                candidate.distanceKm = distanceKm;
-            }
-            if (row.population !== null && row.population > 0) {
-                candidate.population = row.population;
-                // The named ranking key (ROAD_TO_V9 §2). DERIVED, not stored — a pure function of the
-                // population already on this row, so it cannot drift from what the ordering uses.
-                candidate.referential = referentialFromPopulation(row.population);
-            }
-            // Carried for consumers (annotations / API surfaces). No ranking site reads it.
-            if (row.encyclopedic !== null) {
-                candidate.encyclopedic = row.encyclopedic;
-            }
-            // Candidate bbox — parity with the WASM lookup (resolver-wof-wasm/lookup.ts), whose
-            // consumers (the demo cascade's region constraint) read it. Without this the Node
-            // backend's region→bbox constraint is dead and disambiguation falls to population
-            // ranking (the Springfield-IL→MO failure the #524 smoke eval caught).
-            if (row.min_latitude != null &&
-                row.max_latitude != null &&
-                row.min_longitude != null &&
-                row.max_longitude != null) {
-                candidate.bbox = {
-                    minLat: row.min_latitude,
-                    maxLat: row.max_latitude,
-                    minLon: row.min_longitude,
-                    maxLon: row.max_longitude,
-                };
-            }
-            return candidate;
+        // bare schema name; safe to interpolate (validated at construction)
+        const sch = extract.schemaName;
+        const rawRows = fetchSearchRows({
+            db: this.#db,
+            schemaName: sch,
+            query,
+            placetypes,
+            ftsQuery,
+            limit,
+            hasBboxIndex: this.#hasBboxIndex,
+            hasPopulationIndex: this.#hasPopulationIndex,
+            encyclopedicClauses: this.#encyclopedicClauses,
+            weights: this.#weights,
+        });
+        const scoring = {
+            query,
+            placetypes,
+            queryLen: query.text.length,
+            weights: this.#weights,
+        };
+        const candidates = rawRows.map((row) => candidateFromSearchRow(row, scoring));
+        rankCandidates(candidates, {
+            db: this.#db,
+            schemaName: sch,
+            query,
+            weights: this.#weights,
         });
-        // Exact-match tiering: a candidate whose name OR any alias equals the query text (case-folded)
-        // ranks above any partial match, with the weighted-sum score (incl. population) breaking ties
-        // WITHIN a tier. See the RankingWeights.exactMatchTiering docstring for why this aligns the
-        // population prior rather than overriding it. One cheap indexed lookup over the candidate ids.
-        // Runs even for a SINGLE candidate so `exactMatch` is stamped consistently (parity with the
-        // WASM lookup) — a sole alias hit ("New York City" → New York) must still carry the flag the
-        // demo cascade / #369 re-rank read.
-        if (this.#weights.exactMatchTiering && candidates.length) {
-            const exactIds = this.#exactMatchIds(sch, candidates.map((c) => c.id), query.text);
-            // Stamp the tier onto every candidate (not just when the tiering sort fires) so a downstream
-            // re-rank — #369's postcode-anchor country pin in `resolveTree` — can keep the country pin from
-            // crossing the exact/partial boundary ("ME" → Maine, not the more-populous Missouri).
-            for (const c of candidates) {
-                c.exactMatch = exactIds.has(c.id);
-            }
-            if (exactIds.size) {
-                // #905: WITHIN the exact tier, population is the PRIMARY key and the weighted score
-                // only breaks population ties. Exactness saturates text relevance, and the bm25
-                // residue inside `score` is length-noise (see the fetch-site comment), so letting it
-                // order the tier is what sent unscoped "Paris" to an Ohio township. The partial tier
-                // keeps score order — text relevance still means something there. This makes the
-                // exactMatchTiering docstring literal: match quality primary, prominence within.
-                //
-                // #912 sub-tier: a NAME-exact candidate (spr.name equals the query) outranks an
-                // ALIAS-exact one ('Paris' the place beats 'Paris Township' held via alias 'Paris').
-                // The place's own name is a stronger identity claim than an alias — aliases exist to
-                // widen recall, not to tie primaries. ME→Maine is untouched: 'ME' name-exact-matches
-                // nothing, so the alias sub-tier still decides there. Population orders within each
-                // sub-tier as before.
-                const norm = (v) => v.toLowerCase().trim().replaceAll(/\s+/g, " ");
-                const needle = norm(query.text);
-                // #936 option 3: an OFFICIAL name (preferred form in an official language of the place's
-                // country, `names.official = 1`) counts as the place's own name for the sub-tier — "Åbo" is
-                // Turku's name, not merely its alias. Floor-gated on the holder's population (see the
-                // RankingWeights docstring for the measured 100k boundary). officialIds ⊆ exactIds by
-                // construction (official rows are names rows), so only the sub-tier KIND changes.
-                const officialIds = this.#weights.officialNameExact
-                    ? this.#officialNameIds(sch, candidates
-                        .filter((c) => exactIds.has(c.id) && (c.population ?? 0) >= this.#weights.officialNameExactFloor)
-                        .map((c) => c.id), query.text)
-                    : undefined;
-                const kind = (c) => {
-                    if (!exactIds.has(c.id))
-                        return 0;
-                    if (norm(String(c.name ?? "")) === needle)
-                        return 2;
-                    return officialIds?.has(c.id) ? 2 : 1;
-                };
-                // With proximity hints (near/bias), prominence (population + nearness, same units)
-                // replaces raw population as the within-tier key — the 48026 rule: the map view or
-                // the user's location breaks a cross-country postcode tie. Without hints, REFERENTIAL
-                // ordering decides.
-                //
-                // ROAD_TO_V9 §2: this is the site that "orders namesakes", so it is the site that has to
-                // say what it orders by. `compareReferential` is referential DESC with raw population as
-                // the tiebreak, which is provably the SAME ORDER as the `(b.population ?? 0) - (a.population ?? 0)`
-                // it replaces — referential is strictly increasing in population below saturation and
-                // constant above it, and the tiebreak restores the order in the saturated tail. Measured
-                // zero-delta, not assumed: see `place-importance-schema.test.ts` and `resolver-referential-ranking.test.ts`.
-                // Encyclopedic importance is not, and must not become, an input here.
-                const hasHints = !!query.near || (query.bias?.length ?? 0) > 0;
-                candidates.sort((a, b) => {
-                    const ax = kind(a);
-                    const bx = kind(b);
-                    if (bx !== ax)
-                        return bx - ax;
-                    if (ax >= 1) {
-                        if (hasHints)
-                            return (b.prominence ?? 0) - (a.prominence ?? 0) || b.score - a.score;
-                        return compareReferential(a, b) || b.score - a.score;
-                    }
-                    return b.score - a.score;
-                });
-                return candidates.slice(0, limit);
-            }
-        }
-        candidates.sort((a, b) => b.score - a.score);
         return candidates.slice(0, limit);
     }
     #isLocalityQuery(query) {
@@ -809,10 +515,8 @@ export class WOFSqlitePlaceLookup {
         const pc = query.postcode.trim();
         const pcWhere = query.country ? "postcode = ? AND country = ?" : "postcode = ?";
         const pcParams = query.country ? [pc, query.country] : [pc];
-        const pcRows = this.#db
-            .prepare(`SELECT locality_id AS id, aliases, distance_km AS dist, is_containing AS containing
-				 FROM ${sch}.${POSTCODE_LOCALITY_TABLE} WHERE ${pcWhere}`)
-            .all(...pcParams);
+        const pcRows = allRows(this.#db.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;
@@ -861,7 +565,7 @@ export class WOFSqlitePlaceLookup {
                 ? [...wofAliases, ...(postalAliasByGeo.get(cfNormalize(cand.name)) ?? [])]
                 : wofAliases;
             const sName = softNameScore(query.text, cand.name, aliases);
-            const sPop = cand.population && cand.population > 0 ? Math.min(1, Math.log10(1 + cand.population) / 6) : 0;
+            const sPop = populationScaleTerm(cand.population, 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
@@ -905,12 +609,10 @@ 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 = 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.#db.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`)
-            .all(...ids);
+				 WHERE s.id IN (${ph}) AND s.is_current != 0`), ...ids);
         return rows.map((row) => {
             const c = {
                 id: row.id,
@@ -928,95 +630,10 @@ export class WOFSqlitePlaceLookup {
             return c;
         });
     }
-    /**
-     * 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 shard has no `names` table (a slim DB built with
-     * `dropNames`, or a postcode-only shard), 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.
-     */
-    #exactMatchIds(schemaName, ids, text) {
-        const out = new Set();
-        const trimmed = text.trim();
-        if (!ids.length || !trimmed)
-            return out;
-        const placeholders = ids.map(() => "?").join(", ");
-        try {
-            const rows = this.#db
-                .prepare(`SELECT DISTINCT id FROM ${schemaName}.names WHERE id IN (${placeholders}) AND name = ? COLLATE NOCASE`)
-                .all(...ids, trimmed);
-            for (const r of rows) {
-                out.add(r.id);
-            }
-            return out;
-        }
-        catch {
-            // No `names` table on this shard — fall through to the place_search alias bag.
-        }
-        try {
-            const rows = this.#db
-                .prepare(`SELECT wof_id AS id, name, alt_names FROM ${schemaName}.place_search WHERE wof_id IN (${placeholders})`)
-                .all(...ids);
-            const norm = (s) => s.toLowerCase().trim().replaceAll(/\s+/g, " ");
-            const needle = norm(trimmed);
-            for (const r of rows) {
-                if (r.name !== null && norm(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, ungated — 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, gated 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…").
-            const anyCanonicalExact = out.size > 0;
-            for (const r of rows) {
-                if (aliasBagExactMatch(r.alt_names, needle, anyCanonicalExact)) {
-                    out.add(r.id);
-                }
-            }
-        }
-        catch {
-            // Shard without place_search either → no exact-match tier. 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.
-     */
-    #officialNameIds(schemaName, ids, text) {
-        const out = new Set();
-        const trimmed = text.trim();
-        if (!ids.length || !trimmed)
-            return out;
-        const placeholders = ids.map(() => "?").join(", ");
-        try {
-            const rows = this.#db
-                .prepare(`SELECT DISTINCT id FROM ${schemaName}.names WHERE id IN (${placeholders}) AND official = 1 AND name = ? COLLATE NOCASE`)
-                .all(...ids, trimmed);
-            for (const r of rows) {
-                out.add(r.id);
-            }
-        }
-        catch {
-            // Pre-#940 gazetteer (no `official` column) or a names-less slim shard — feature inert.
-        }
-        return out;
-    }
-    close() {
-        // Destroying the Kysely instance closes the underlying connection IF we own it. If the caller
-        // passed in a pre-opened DatabaseSync (test fixture), respect their ownership.
-        void this.#kysely.destroy();
-        if (this.#ownsDB) {
-            this.#db.close();
-        }
-    }
     [Symbol.dispose]() {
-        this.close();
+        // 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.
@@ -1026,9 +643,8 @@ export class WOFSqlitePlaceLookup {
     }
     #assertFTSExists() {
         if (!placeSearchFTSExists(this.#db)) {
-            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).");
+            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 { trigramJaccard, trigrams } from "./name-score.js";
 //# sourceMappingURL=lookup.js.map