@mailwoman/resolver-wof-sqlite 2.1.0

package/out/lookup.js

@@ -0,0 +1,876 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ */
+import { Kysely, sql } from "kysely";
+import { DatabaseSync } from "node:sqlite";
+import { SqliteDialect } from "@mailwoman/core/kysley/dialect";
+import { expandPlacetypeFilter } from "@mailwoman/resolver";
+import { ADDRESS_CONVENTION_TABLE, resolveConvention, SeedConventionSource, } from "./convention.js";
+import { ancestorLineage } from "./ancestry.js";
+import { COINCIDENT_ROLES_TABLE, coincidentRolesExists } from "./coincident-roles.js";
+import { aliasBagExactMatch, buildPlaceSearchFts, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, placeBboxExists, placePopulationExists, placeSearchFtsExists, } from "./fts.js";
+import { bboxAround, haversineKm } from "./geo.js";
+import { pickShardForPlacetype, resolveShards } from "./sharding.js";
+import { SqliteConventionSource } from "./sqlite-convention-source.js";
+const DEFAULT_WEIGHTS = {
+    placetypeMatchBoost: 0.5,
+    localityImplicitBoost: 0.2,
+    countryMatchBoost: 0.3,
+    directChildBoost: 0.5,
+    descendantBoost: 0.2,
+    lengthPenaltyWeight: 0.1,
+    proximityBoost: 0.8,
+    proximityScaleKm: 100,
+    // populationBoost is intentionally large — empirical tuning against real WOF showed BM25 gaps
+    // of 1.5-3.0 between famous places and tiny same-name peers (because the famous ones have
+    // hundreds of alt-name entries that hurt their FTS document score). To consistently surface
+    // "the famous one" for unambiguous queries like "New York" or "Chicago", the population signal
+    // needs to dominate. Callers wanting a more conservative balance can drop this in the
+    // RankingWeights override.
+    //
+    // Note: this resolver uses `place_population` directly. The separate `place_importance` table
+    // (Wikipedia-derived) is consumed by the FST layer, not here. See
+    // docs/articles/concepts/importance-vs-population.md for the two-signal contract.
+    populationBoost: 4.0,
+    populationScaleLog10: 6,
+    // Exact name/alias match outranks partial match before the weighted sum (incl. population) is
+    // consulted — keeps population as an intra-tier prominence tiebreaker, not a cross-tier promoter.
+    // Fixes the 2-letter-region-abbrev bug ("ME" → Maine, not the more-populous Missouri).
+    exactMatchTiering: true,
+};
+/**
+ * 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;
+/**
+ * The coordinate-first candidate table (scripts/build-postcode-locality.py): postcode → containing
+ *
+ * - Nearby localities with WOF alt-name aliases.
+ */
+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.
+ */
+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).
+ */
+const CF_MISMATCH_KM = 50;
+const CF_MISMATCH_DELTA = 0.5;
+/** Case-fold + strip diacritics + collapse punctuation — for the coord-first soft name match. */
+function cfNormalize(s) {
+    return s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "") // combining diacritical marks
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+/** Padded character-trigram set (a leading/trailing space pads short tokens). */
+function trigrams(s) {
+    const t = ` ${s} `;
+    const out = new Set();
+    for (let i = 0; i + 3 <= t.length; i++)
+        out.add(t.slice(i, i + 3));
+    return out;
+}
+/**
+ * Character-trigram Jaccard ∈ [0,1] — tolerant of the swallowed-leading-char fragments ("auen" vs
+ * "plauen") and minor misspellings without a heavyweight edit-distance pass.
+ */
+function trigramJaccard(a, b) {
+    const A = trigrams(a);
+    const B = trigrams(b);
+    if (A.size === 0 || B.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of A)
+        if (B.has(x))
+            inter++;
+    return inter / (A.size + B.size - inter);
+}
+/** Soft name-match score ∈ [0,1]: exact (normalized) name/alias → 1, else best trigram-Jaccard. */
+function softNameScore(text, name, aliases) {
+    const q = cfNormalize(text);
+    if (!q)
+        return 0;
+    let best = 0;
+    for (const raw of [name, ...aliases]) {
+        const n = cfNormalize(raw);
+        if (!n)
+            continue;
+        if (n === q)
+            return 1;
+        best = Math.max(best, trigramJaccard(q, n));
+    }
+    return best;
+}
+export class WofSqlitePlaceLookup {
+    #db;
+    #ownsDb;
+    #kysely;
+    #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.
+     */
+    #hasBboxIndex;
+    /**
+     * Per-shard 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 probe for the `postcode_locality` table (the coordinate-first candidate table, built
+     * by scripts/build-postcode-locality.py). 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;
+    /**
+     * Resolved shard list. Always at least one entry; first is `main`. Multi-shard adds extras with
+     * their own derived (or override) schema names.
+     */
+    #shards;
+    /**
+     * 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;
+    #strategies;
+    #countryWofIdCache = new Map();
+    /** Strategy names already warned about — so an unknown name surfaces once, not once per query. */
+    #warnedUnknownStrategies = new Set();
+    /**
+     * Lazily-built `admin_id → coincident localities` map from the #403 relation (null until first
+     * use).
+     */
+    #coincidentRolesCache = null;
+    /** Per-id memoized ancestor lineages (#404) — a hot chain is queried once. */
+    #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.
+     */
+    #postalCityAliases;
+    constructor(opts, weights) {
+        if (opts.database && opts.databasePath) {
+            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");
+        }
+        if (opts.database) {
+            this.#db = opts.database;
+            this.#ownsDb = false;
+            this.#shards = [{ path: ":memory:", schemaName: "main", placetypes: [] }];
+        }
+        else {
+            const shards = resolveShards(opts.databasePath);
+            this.#shards = shards;
+            this.#db = new DatabaseSync(shards[0].path, { readOnly: false });
+            this.#ownsDb = true;
+            // ATTACH each non-main shard. Schema names were validated by resolveShards, so safe to
+            // interpolate directly (SQLite ATTACH doesn't accept parameters for the schema name).
+            for (const s of shards.slice(1)) {
+                this.#db.exec(`ATTACH DATABASE '${s.path.replace(/'/g, "''")}' AS ${s.schemaName}`);
+            }
+        }
+        // node:sqlite has no .pragma() helper; pragmas are executed as plain SQL.
+        this.#db.exec("PRAGMA busy_timeout = 5000");
+        if (opts.buildFts) {
+            this.#ensureFts();
+        }
+        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
+        // sqlite_master. Cached at construction so findPlace doesn't query sqlite_master per call.
+        this.#hasBboxIndex = new Map();
+        this.#hasPopulationIndex = 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));
+        }
+        // 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
+        // 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
+        // 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;
+        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)
+                : 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
+        // schema-qualified `sqlite_master` view.
+        if (schemaName === "main") {
+            if (tableName === PLACE_BBOX_TABLE)
+                return placeBboxExists(this.#db);
+            if (tableName === PLACE_POPULATION_TABLE)
+                return placePopulationExists(this.#db);
+        }
+        const row = this.#db
+            .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.
+        const convention = this.#conventionFor(query);
+        for (const name of convention.candidateStrategies) {
+            const strategy = this.#strategies.get(name);
+            if (!strategy) {
+                this.#warnUnknownStrategy(name);
+                continue;
+            }
+            const result = await strategy(query, convention);
+            if (result !== null)
+                return result;
+        }
+        return [];
+    }
+    /**
+     * 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.
+     */
+    coincidentLocalitiesFor(adminId) {
+        const id = typeof adminId === "number" ? adminId : Number(adminId);
+        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;
+        }
+        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.
+     */
+    ancestors(id) {
+        const pid = typeof id === "number" ? id : Number(id);
+        if (!Number.isFinite(pid))
+            return [];
+        const cached = this.#ancestorsCache.get(pid);
+        if (cached)
+            return cached;
+        const lineage = ancestorLineage(this.#db, pid).map((r) => ({
+            id: r.id,
+            placetype: r.placetype,
+            name: r.name,
+        }));
+        this.#ancestorsCache.set(pid, lineage);
+        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.
+     */
+    #warnUnknownStrategy(name) {
+        if (this.#warnedUnknownStrategies.has(name))
+            return;
+        this.#warnedUnknownStrategies.add(name);
+        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 candidate set.
+     */
+    #postcodeAreaResolution(query, convention) {
+        if (!(query.postcode && this.#postcodeLocalityShard && this.#isLocalityQuery(query))) {
+            return Promise.resolve(null);
+        }
+        return this.#findLocalityCoordFirst(query, this.#postcodeLocalityShard, 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) {
+        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 <= 3 ? 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.
+        const placetypes = expandPlacetypeFilter(normalizePlacetypes(query.placetype));
+        const ftsQuery = sanitizeFtsQuery(query.text);
+        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
+        // supported in v1 — caller can issue two findPlace calls and merge in TS if needed.)
+        const firstPlacetype = placetypes?.[0];
+        const shard = pickShardForPlacetype(this.#shards, firstPlacetype);
+        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 > 0) {
+            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
+                ? 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`
+            : "";
+        // 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").
+        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}
+			FROM ${sch}.place_search
+			${joinClause}
+			${populationJoin}
+			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);
+        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 > 0 && 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) {
+                if (row.parent_id === query.parentId) {
+                    score += this.#weights.directChildBoost;
+                }
+                else {
+                    score += 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;
+            if (query.near && row.lat !== null && row.lon !== null && !(row.lat === 0 && row.lon === 0)) {
+                distanceKm = haversineKm(query.near.lat, query.near.lon, row.lat, row.lon);
+                score += this.#weights.proximityBoost / (1 + distanceKm / this.#weights.proximityScaleKm);
+            }
+            // Population boost: capped at `populationBoost` magnitude at `10^populationScaleLog10`
+            // people. Missing population → no contribution. Never penalizes.
+            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);
+                score += this.#weights.populationBoost * popFraction;
+            }
+            const candidate = {
+                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,
+                score,
+            };
+            if (distanceKm !== undefined)
+                candidate.distanceKm = distanceKm;
+            if (row.population !== null && row.population > 0)
+                candidate.population = row.population;
+            // 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;
+        });
+        // 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 > 0) {
+            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 > 0 && exactIds.size < candidates.length) {
+                candidates.sort((a, b) => {
+                    const ax = exactIds.has(a.id) ? 1 : 0;
+                    const bx = exactIds.has(b.id) ? 1 : 0;
+                    return bx - ax || b.score - a.score;
+                });
+                return Promise.resolve(candidates.slice(0, limit));
+            }
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        return Promise.resolve(candidates.slice(0, limit));
+    }
+    #isLocalityQuery(query) {
+        const pts = normalizePlacetypes(query.placetype);
+        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.
+     */
+    #conventionFor(query) {
+        const chain = [];
+        if (query.country) {
+            const cid = this.#countryWofId(query.country);
+            if (cid !== null)
+                chain.push(cid);
+        }
+        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.
+     */
+    #countryWofId(code) {
+        const cached = this.#countryWofIdCache.get(code);
+        if (cached !== undefined)
+            return cached;
+        let id = null;
+        try {
+            const row = this.#db
+                .prepare(`SELECT id FROM main.spr WHERE placetype = 'country' AND country = ? AND is_current != 0 LIMIT 1`)
+                .get(code);
+            id = row?.id ?? null;
+        }
+        catch {
+            id = null;
+        }
+        this.#countryWofIdCache.set(code, id);
+        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).
+     */
+    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 = 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);
+        if (pcRows.length === 0)
+            return null;
+        const limit = query.limit ?? 10;
+        // Name-match candidates via the normal FTS path (postcode cleared → no recursion).
+        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.
+        const postalAliasByGeo = new Map();
+        if (this.#postalCityAliases) {
+            for (const a of await this.#postalCityAliases.getDivergentAliases(pc)) {
+                const key = cfNormalize(a.geoLocality);
+                if (!key)
+                    continue;
+                const bag = postalAliasByGeo.get(key);
+                if (bag)
+                    bag.push(a.postalCity);
+                else
+                    postalAliasByGeo.set(key, [a.postalCity]);
+            }
+        }
+        const merged = new Map();
+        for (const c of ftsCands)
+            merged.set(c.id, c);
+        const missing = [...pcInfo.keys()].filter((id) => !merged.has(id));
+        for (const row of this.#fetchLocalitiesById(missing))
+            merged.set(row.id, row);
+        const scored = [];
+        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.
+            const wofAliases = info?.aliases ?? [];
+            const aliases = postalAliasByGeo.size > 0
+                ? [...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;
+            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.
+        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.
+        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.
+            const anchorRow = pcRows
+                .filter((r) => merged.has(r.id))
+                .sort((a, b) => b.containing - a.containing || a.dist - b.dist)[0];
+            const anchor = anchorRow ? merged.get(anchorRow.id) : undefined;
+            if (anchor && top.id !== anchorRow.id) {
+                if (haversineKm(top.lat, top.lon, anchor.lat, anchor.lon) > CF_MISMATCH_KM)
+                    top.mismatch = true;
+            }
+        }
+        return scored.slice(0, limit).map(({ exact, ...c }) => {
+            void exact;
+            return c;
+        });
+    }
+    /** Fetch locality spr rows (from main) for the postcode-injected candidate ids the FTS set missed. */
+    #fetchLocalitiesById(ids) {
+        if (ids.length === 0)
+            return [];
+        const hasPop = this.#hasPopulationIndex.get("main") === true;
+        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,
+				        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);
+        return rows.map((row) => {
+            const c = {
+                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,
+                score: 0,
+            };
+            if (row.population !== null && row.population > 0)
+                c.population = row.population;
+            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 === 0 || !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().replace(/\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;
+    }
+    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();
+    }
+    /** Build the FTS5 virtual table from the `names` + `places` tables. */
+    #ensureFts() {
+        buildPlaceSearchFts(this.#db);
+    }
+    #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-wof-build-fts <path-to-wof.db>` ahead of time (see resolver-wof-sqlite/README.md).");
+        }
+    }
+}
+function normalizePlacetypes(p) {
+    if (!p)
+        return null;
+    return Array.isArray(p) ? p : [p];
+}
+/**
+ * Make an arbitrary user-typed string safe for FTS5 MATCH.
+ *
+ * FTS5 has its own query syntax (`"phrase"`, `term1 OR term2`, `prefix*`, NEAR/N, etc.). Letting
+ * raw user input through means a user typing `Paris's` or `St. (Petersburg)` causes a syntax
+ * error.
+ *
+ * Per-token rules:
+ *
+ * - Strip all punctuation except trailing `*` from each whitespace-separated token.
+ * - **Trailing `*`** is preserved as FTS5 **prefix syntax** — `627*` becomes the literal `627*`
+ *   (unquoted). The caller signaled they want a prefix; respect that.
+ * - All other tokens are wrapped in `"..."` as a single-word phrase. Conservative — handles
+ *   apostrophes, parens, accented input, etc. safely.
+ * - Multiple tokens join with implicit AND.
+ *
+ * Examples:
+ *
+ * - `"Paris"` → `"Paris"` (phrase)
+ * - `"627*"` → `627*` (prefix)
+ * - `"St. (Petersburg)"` → `"St" "Petersburg"` (two phrases, AND-joined)
+ * - `"Pari* TX"` → `Pari* "TX"` (mixed prefix + phrase)
+ * - `"*"` alone → `""` (no body → drop)
+ */
+function sanitizeFtsQuery(text) {
+    const out = [];
+    for (const rawToken of text.normalize("NFKC").split(/\s+/u)) {
+        const trimmed = rawToken.trim();
+        if (!trimmed)
+            continue;
+        const hasPrefixStar = trimmed.endsWith("*");
+        // Strip everything except letters + numbers from the token body. Apostrophes / hyphens /
+        // any embedded `*` all go. The trailing `*` (if any) is reapplied separately below.
+        const body = trimmed.replace(/[^\p{L}\p{N}]/gu, "");
+        if (!body)
+            continue;
+        out.push(hasPrefixStar ? `${body}*` : `"${body.replace(/"/g, '""')}"`);
+    }
+    return out.join(" ");
+}
+// `sql` is imported only because future Kysely-typed queries will use it; silence "unused" linting.
+void sql;
+//# sourceMappingURL=lookup.js.map