@mailwoman/resolver-wof-sqlite 2.1.0

package/out/index.js

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export { WofSqlitePlaceLookup } from "./lookup.js";
+export { WofCandidateTableLookup } from "./candidate-lookup.js";
+export { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable } from "./address-point-schema.js";
+export { WofPostalCityAliasLookup, } from "./postal-city-alias-lookup.js";
+export { POSTAL_CITY_CANDIDATE_COLUMNS, POSTAL_CITY_CANDIDATE_TABLE, createPostalCityCandidateTable, } from "./postal-city-candidate-schema.js";
+export { ADDRESS_CONVENTION_TABLE, BUILTIN_STRATEGY_NAMES, SeedConventionSource, WORLD_DEFAULT, mergeConventions, resolveConvention, } from "./convention.js";
+export { SqliteConventionSource } from "./sqlite-convention-source.js";
+export { WofPostcodeLookup } from "./postcode-point-lookup.js";
+export { PLACE_BBOX_TABLE, PLACE_SEARCH_TABLE, buildPlaceSearchFts, placeBboxExists, placeSearchFtsExists, } from "./fts.js";
+export { bboxAround, geometryContains, haversineKm, pointInPolygonRings, pointInRing, } from "./geo.js";
+export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth } from "./ancestry.js";
+export { WofReverseGeocoder, } from "./reverse.js";
+export { AddressPointInterpolator } from "./address-point-interpolation.js";
+export { AddressPointSqliteLookup } from "./address-point.js";
+export { StreetInterpolator, } from "./interpolation.js";
+export { deriveSchemaName, pickShardForPlacetype, resolveShards, } from "./sharding.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,OAAO,EAAE,oBAAoB,EAAsD,MAAM,aAAa,CAAA;AAEtG,OAAO,EAAE,uBAAuB,EAAoC,MAAM,uBAAuB,CAAA;AAEjG,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AAErH,OAAO,EACN,wBAAwB,GAGxB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACN,6BAA6B,EAC7B,2BAA2B,EAC3B,8BAA8B,GAC9B,MAAM,mCAAmC,CAAA;AAG1C,OAAO,EACN,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,GAMjB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AAEtE,OAAO,EAAE,iBAAiB,EAAsB,MAAM,4BAA4B,CAAA;AAElF,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GAGpB,MAAM,UAAU,CAAA;AAEjB,OAAO,EACN,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACnB,WAAW,GAMX,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAyB,MAAM,eAAe,CAAA;AAEvG,OAAO,EACN,kBAAkB,GAKlB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EACN,kBAAkB,GAIlB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,GAGb,MAAM,eAAe,CAAA"}

package/out/interpolation.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   House-number interpolation (#483): when the exact address-point tier (#476, `address-point.ts`)
+ *   misses, estimate the coordinate from TIGER street-segment ranges — parity-aware range match,
+ *   then linear interpolation along the segment polyline. Design:
+ *   `docs/articles/plan/2026-06-11-interpolation-design.md`.
+ *
+ *   Reads the per-state shard built by `scripts/build-interpolation-shard.ts` (`street_segment`: one
+ *   row per TIGER edge SIDE — independent left/right ranges, ZIPs, parity). Query-side
+ *   normalization is THE shared normalizer (`street-normalize.ts`) — identical to build-side, by
+ *   construction.
+ *
+ *   Every answer is honest about being an estimate: `interpolated: true`, `parityMatched` (false when
+ *   only the opposite side's range contained the number — usually the right block, wrong side of
+ *   the street), and `uncertaintyM` (half the matched segment's length — the #483 issue's honest
+ *   default). Scoping is postcode-first (a given ZIP that scopes to nothing is a MISS — the
+ *   statewide retry was measured and rejected, see `find()`); without a postcode the statewide name
+ *   match must agree on a single postcode or the lookup ABSTAINS (a common street name spanning
+ *   towns is ambiguity, not an answer).
+ *
+ *   Standalone in this slice — core tier wiring (`resolution_tier: "interpolated"` after the
+ *   exact-point fall-through) is a noted follow-up on #483, so the `find()` shape mirrors
+ *   `AddressPointLookup.find()` to keep that wiring mechanical.
+ */
+import { DatabaseSync } from "node:sqlite";
+import type { InterpolationLookup } from "@mailwoman/resolver";
+/**
+ * How an interpolated answer was computed (#483 Method 2):
+ *
+ * - `address_point` — bracketed/extrapolated between REAL neighbor points from the #476 shard
+ *   (`AddressPointInterpolator`), replacing TIGER's uniform-spacing assumption with occupancy.
+ * - `tiger_range` — linear position within a TIGER segment's theoretical house-number range
+ *   (`StreetInterpolator`), the fallback for streets too sparse to bracket.
+ */
+export type InterpolationMethod = "address_point" | "tiger_range";
+/** One interpolated coordinate estimate. Never an exact situs point — see `uncertaintyM`. */
+export interface InterpolatedHit {
+    lat: number;
+    lon: number;
+    /** Always true — the tier's honesty flag, mirrored into `resolution_tier` when wired. */
+    interpolated: true;
+    /** Which rung answered — see {@link InterpolationMethod}. */
+    method: InterpolationMethod;
+    /**
+     * `tiger_range` only. True when the matched segment side's parity agrees with the house number
+     * (or the side is `mixed`). False = opposite-side fallback: usually the right block, wrong side
+     * of the street.
+     */
+    parityMatched?: boolean;
+    /**
+     * `address_point` only. `both` = the query number sits between two known neighbor numbers;
+     * `single` = neighbors exist on one side only (extrapolated, larger `uncertaintyM`).
+     */
+    bracket?: "both" | "single";
+    /**
+     * Honest uncertainty radius in meters: half the matched segment's polyline length
+     * (`tiger_range`), half the bracket span (`address_point`/`both`), or the explicitly larger
+     * extrapolation penalty (`address_point`/`single`).
+     */
+    uncertaintyM: number;
+    /** Provenance, e.g. `"tiger:edges"`. */
+    source: string;
+    /** Pinned data vintage, e.g. `"TIGER2023"`. */
+    release: string;
+}
+export interface InterpolationQuery {
+    street: string;
+    number: string;
+    /** ZIP scope — strongly preferred; without it common street names abstain (see module doc). */
+    postcode?: string;
+}
+export declare class StreetInterpolator implements InterpolationLookup {
+    #private;
+    constructor(opts: {
+        dbPath?: string;
+        database?: DatabaseSync;
+    });
+    find(query: InterpolationQuery): InterpolatedHit | null;
+    close(): void;
+}
+//# sourceMappingURL=interpolation.d.ts.map

package/out/interpolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.d.ts","sourceRoot":"","sources":["../interpolation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAM9D;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,aAAa,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,yFAAyF;IACzF,YAAY,EAAE,IAAI,CAAA;IAClB,6DAA6D;IAC7D,MAAM,EAAE,mBAAmB,CAAA;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC3B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAcD,qBAAa,kBAAmB,YAAW,mBAAmB;;gBAMjD,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;KAAE;IAyB9D,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,GAAG,IAAI;IAmDvD,KAAK,IAAI,IAAI;CAGb"}

package/out/interpolation.js

@@ -0,0 +1,150 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   House-number interpolation (#483): when the exact address-point tier (#476, `address-point.ts`)
+ *   misses, estimate the coordinate from TIGER street-segment ranges — parity-aware range match,
+ *   then linear interpolation along the segment polyline. Design:
+ *   `docs/articles/plan/2026-06-11-interpolation-design.md`.
+ *
+ *   Reads the per-state shard built by `scripts/build-interpolation-shard.ts` (`street_segment`: one
+ *   row per TIGER edge SIDE — independent left/right ranges, ZIPs, parity). Query-side
+ *   normalization is THE shared normalizer (`street-normalize.ts`) — identical to build-side, by
+ *   construction.
+ *
+ *   Every answer is honest about being an estimate: `interpolated: true`, `parityMatched` (false when
+ *   only the opposite side's range contained the number — usually the right block, wrong side of
+ *   the street), and `uncertaintyM` (half the matched segment's length — the #483 issue's honest
+ *   default). Scoping is postcode-first (a given ZIP that scopes to nothing is a MISS — the
+ *   statewide retry was measured and rejected, see `find()`); without a postcode the statewide name
+ *   match must agree on a single postcode or the lookup ABSTAINS (a common street name spanning
+ *   towns is ambiguity, not an answer).
+ *
+ *   Standalone in this slice — core tier wiring (`resolution_tier: "interpolated"` after the
+ *   exact-point fall-through) is a noted follow-up on #483, so the `find()` shape mirrors
+ *   `AddressPointLookup.find()` to keep that wiring mechanical.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { haversineKm } from "./geo.js";
+import { hasTable } from "./sqlite-utils.js";
+import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.js";
+export class StreetInterpolator {
+    #db;
+    #ownsDb;
+    #byPostcode;
+    #byStreet;
+    constructor(opts) {
+        if (opts.database) {
+            this.#db = opts.database;
+            this.#ownsDb = false;
+        }
+        else if (opts.dbPath) {
+            this.#db = new DatabaseSync(opts.dbPath, { readOnly: true });
+            this.#ownsDb = true;
+        }
+        else {
+            throw new Error("StreetInterpolator: one of dbPath or database is required");
+        }
+        // Degrade gracefully on an empty/tableless shard (interrupted build, stray 0-byte file): with no
+        // `street_segment` table this interpolator is a no-op miss, not a crash that loses the state (#568).
+        if (hasTable(this.#db, "street_segment")) {
+            const columns = `from_hn, to_hn, min_hn, max_hn, parity, postcode, geometry, source, release`;
+            this.#byPostcode = this.#db.prepare(`SELECT ${columns} FROM street_segment
+				 WHERE postcode = ? AND street_norm = ? AND min_hn <= ? AND max_hn >= ?`);
+            this.#byStreet = this.#db.prepare(`SELECT ${columns} FROM street_segment
+				 WHERE street_norm = ? AND min_hn <= ? AND max_hn >= ?`);
+        }
+    }
+    find(query) {
+        if (!this.#byPostcode || !this.#byStreet)
+            return null;
+        const streetNorm = canonicalizeRouteKey(normalizeStreetForKey(query.street));
+        const numberRaw = query.number.trim();
+        // Strictly-numeric house numbers only — this tier estimates, it doesn't guess at
+        // hyphenated/alphanumeric schemes the ranges don't model.
+        if (!streetNorm || !/^\d+$/.test(numberRaw))
+            return null;
+        const n = Number(numberRaw);
+        let rows;
+        if (query.postcode) {
+            // A given ZIP that scopes to nothing is a MISS, not a statewide guess: the retry was
+            // measured (2026-06-11 VT eval) at +2.3pp coverage for a poisoned tail (p99 1.0 → 20.8
+            // km, max 204 km — a unique name statewide can live in a far-away town).
+            rows = this.#byPostcode.all(query.postcode.trim(), streetNorm, n, n);
+        }
+        else {
+            // No scope given: a name matching ranges across several ZIPs is ambiguous — abstain.
+            rows = this.#byStreet.all(streetNorm, n, n);
+            const postcodes = new Set(rows.map((r) => r.postcode ?? ""));
+            if (postcodes.size > 1)
+                return null;
+        }
+        if (rows.length === 0)
+            return null;
+        // Parity preference: exact side first, then 'mixed' (matches either), then the
+        // opposite side as a flagged fallback.
+        const wantOdd = n % 2 === 1;
+        const exact = rows.filter((r) => r.parity === (wantOdd ? "odd" : "even"));
+        const mixed = rows.filter((r) => r.parity === "mixed");
+        const preferred = exact.length > 0 ? exact : mixed;
+        const pool = preferred.length > 0 ? preferred : rows;
+        const parityMatched = preferred.length > 0;
+        // Tightest range wins — the most specific claim about where this number lives.
+        const best = pool.reduce((a, b) => (b.max_hn - b.min_hn < a.max_hn - a.min_hn ? b : a));
+        const polyline = JSON.parse(best.geometry);
+        const span = best.to_hn - best.from_hn;
+        const t = span === 0 ? 0.5 : clamp01((n - best.from_hn) / span);
+        const [lon, lat, lengthKm] = pointAlong(polyline, t);
+        return {
+            lat,
+            lon,
+            interpolated: true,
+            method: "tiger_range",
+            parityMatched,
+            uncertaintyM: Math.round((lengthKm * 1000) / 2),
+            source: best.source,
+            release: best.release,
+        };
+    }
+    close() {
+        if (this.#ownsDb)
+            this.#db.close();
+    }
+}
+function clamp01(t) {
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+/**
+ * Point at fraction `t` of the polyline's total arc length (haversine), plus the total length in
+ * km. `t` is assumed clamped to [0, 1].
+ */
+function pointAlong(polyline, t) {
+    const legs = [];
+    let total = 0;
+    for (let i = 1; i < polyline.length; i++) {
+        const [aLon, aLat] = polyline[i - 1];
+        const [bLon, bLat] = polyline[i];
+        const d = haversineKm(aLat, aLon, bLat, bLon);
+        legs.push(d);
+        total += d;
+    }
+    if (total === 0) {
+        const [lon, lat] = polyline[0];
+        return [lon, lat, 0];
+    }
+    let remaining = t * total;
+    for (let i = 0; i < legs.length; i++) {
+        const leg = legs[i];
+        if (remaining <= leg || i === legs.length - 1) {
+            const f = leg === 0 ? 0 : clamp01(remaining / leg);
+            const [aLon, aLat] = polyline[i];
+            const [bLon, bLat] = polyline[i + 1];
+            return [aLon + (bLon - aLon) * f, aLat + (bLat - aLat) * f, total];
+        }
+        remaining -= leg;
+    }
+    const [lon, lat] = polyline[polyline.length - 1];
+    return [lon, lat, total];
+}
+//# sourceMappingURL=interpolation.js.map

package/out/interpolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolation.js","sourceRoot":"","sources":["../interpolation.ts"],"names":[],"mappings":"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"}

package/out/lookup.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @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 { DatabaseSync } from "node:sqlite";
+import { type Ancestor, type CoincidentLocality } from "@mailwoman/resolver";
+import { type Convention, type ConventionSource } from "./convention.js";
+import type { WofPostalCityAliasLookup } from "./postal-city-alias-lookup.js";
+import { type ShardConfig } from "./sharding.js";
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "./types.js";
+export interface WofSqlitePlaceLookupOpts {
+    /**
+     * Path to the WOF SQLite distribution on disk. Mutually exclusive with `database`.
+     *
+     * **Single string** — opens that one DB as the main shard.
+     *
+     * **Array** — opens the first entry as main, then ATTACHes each subsequent entry as a separate
+     * SQLite schema. Schema names are derived from the filename (`whosonfirst-data-postalcode-
+     * us-latest.db` → `postalcode_us`); override with `ShardConfig.schemaName` when the filename
+     * doesn't follow WOF convention. See `sharding.ts` for the derivation rules.
+     *
+     * Routing: queries with a `placetype` matching a shard's name (or explicit `placetypes` hint) are
+     * sent to that shard; everything else hits main. Cross-shard UNION is NOT done — BM25 isn't
+     * comparable across separately-indexed corpora.
+     */
+    databasePath?: string | ReadonlyArray<string | ShardConfig>;
+    /**
+     * Pre-opened DatabaseSync — primarily for tests against an inline fixture DB. Mutually exclusive
+     * with `databasePath`. Multi-shard requires `databasePath` (so the lookup owns the ATTACH).
+     */
+    database?: DatabaseSync;
+    /**
+     * If true, build the FTS5 `place_search` virtual table on construction if it doesn't already
+     * exist. The upstream WOF distribution does NOT ship FTS5, so callers either set this once on
+     * first open or pre-build it via the operator-side CLI documented in the README. Default false —
+     * the resolver assumes the index already exists and errors loudly if it doesn't.
+     *
+     * With multi-shard, `buildFts: true` builds the index on the **main** shard only. Other shards
+     * must be pre-built via `mailwoman-wof-build-fts` — operator script for predictable cost.
+     */
+    buildFts?: boolean;
+    /**
+     * Geographic Rule Engine convention source (Direction E, #289). Per-WOF-polygon resolution
+     * profiles, either as a ready `ConventionSource` or a plain `{ wofId: Convention }` seed map.
+     * Default empty — every query rides `WORLD_DEFAULT` (the EU coordinate-first behavior). JP/KR/TW
+     * add rows; #290 wires a build-from-source sqlite-backed source here.
+     */
+    conventions?: ConventionSource | Record<number, Convention>;
+    /**
+     * Opt-in postal-city alias reader (#475). When supplied, the coordinate-first locality scorer
+     * treats an observed `postal_city` ("Antioch", postcode 37013) as a name-match alias for the
+     * geographic locality the postcode sits in ("Nashville"), recovering the chronic postal-vs-
+     * geographic-city mismatch. Absent (the default), the resolver is byte-identical — every alias
+     * code path is gated on this being non-null, so an unprovided reader changes no score.
+     */
+    postalCityAliases?: WofPostalCityAliasLookup;
+}
+/**
+ * Ranking weights for `findPlace`. Tweakable per-instance but defaults match the values declared in
+ * the Phase 4.2 plan doc.
+ */
+export interface RankingWeights {
+    /** Boost when the candidate's placetype matches an explicit `placetype` filter. */
+    placetypeMatchBoost: number;
+    /** Boost when the candidate is a locality and no explicit placetype was requested. */
+    localityImplicitBoost: number;
+    /** Boost when the candidate's country matches an explicit `country` filter. */
+    countryMatchBoost: number;
+    /** Boost when the candidate is a direct child of the requested `parentId`. */
+    directChildBoost: number;
+    /** Boost when the candidate is a transitive descendant of the requested `parentId`. */
+    descendantBoost: number;
+    /** Multiplier on the length-penalty term (penalizes much-longer-than-query names). */
+    lengthPenaltyWeight: number;
+    /**
+     * Magnitude of the proximity boost when the query carries `near`. The contribution is
+     * `proximityBoost / (1 + distanceKm / proximityScaleKm)` — at distance 0 the boost is full
+     * magnitude, at `proximityScaleKm` it's half, decaying further with distance. Default tuned so
+     * proximity can overcome a typical FTS rank tie but not dominate a strong text match.
+     */
+    proximityBoost: number;
+    /** Distance (km) at which the proximity boost halves. Tune to the typical query radius. */
+    proximityScaleKm: number;
+    /**
+     * Magnitude of the population boost when the candidate has a known `wof:population`. The
+     * contribution is `populationBoost * log10(1 + population) / populationScaleLog10`, capped at
+     * `populationBoost`. WOF only carries population for ~15% of localities (mostly larger ones);
+     * places without it get +0 (never a penalty). Default tuned so the famous Springfield, IL (pop
+     * ~112k) gets ~0.42 boost — enough to nudge past tiny same-name peers.
+     */
+    populationBoost: number;
+    /**
+     * Population (in log10) at which the boost reaches its full magnitude. Default 6 — i.e. a
+     * population of 1,000,000 gives `populationBoost` exactly. Larger populations cap at the same
+     * value (no compounding effect for megacities).
+     */
+    populationScaleLog10: number;
+    /**
+     * Tier candidates with an EXACT name/alias match above candidates that only match partially,
+     * BEFORE the weighted-sum score is consulted. Default true.
+     *
+     * Why this is needed (and why it ALIGNS with — rather than overrides — the population/importance
+     * signal): the weighted sum adds population as a large additive boost (`populationBoost`, up to
+     * +4) so that famous places surface for unambiguous full-name queries. But population is a
+     * _prominence prior_ — its job is to break ties among candidates that match the query EQUALLY
+     * WELL (e.g. "Springfield" → Springfield IL over Springfield MA, both exact name matches). It was
+     * never meant to promote a place that matches the query WORSE. For a 2-letter region abbreviation
+     * that backfires: querying "ME" returns Maine (which has the exact alias `ME`) AND Missouri/
+     * Michigan/etc. (which do not), and Missouri's larger population (+4) overcomes Maine's bm25 edge
+     * — so "Portland, ME" resolves its region to Missouri and the locality then cascades to the wrong
+     * state. Tiering restores the intended ordering: **match quality is the primary key, prominence
+     * (population) the secondary key WITHIN a tier.** Springfield-IL-over-MA still works (both exact
+     * → same tier → population decides); ME→Maine now works (only Maine is exact → higher tier →
+     * population never gets to override it). See
+     * docs/articles/evals/2026-05-30-resolver-exact-match.md.
+     *
+     * Note: tiering re-ranks within the over-fetched candidate window (`limit * 4`); a pathological
+     * exact match that falls outside that window is not rescued. For the region-abbrev case the
+     * window is comfortably sufficient (a handful of states match a 2-letter query).
+     */
+    exactMatchTiering: boolean;
+}
+export declare class WofSqlitePlaceLookup implements PlaceLookup, Disposable {
+    #private;
+    constructor(opts: WofSqlitePlaceLookupOpts, weights?: Partial<RankingWeights>);
+    findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]>;
+    /**
+     * 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: number | string): CoincidentLocality[];
+    /**
+     * 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: number | string): Ancestor[];
+    close(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=lookup.d.ts.map

package/out/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAA;AAI9D,OAAO,EAAyB,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACnG,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,gBAAgB,EAGrB,MAAM,iBAAiB,CAAA;AAcxB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAE7E,OAAO,EAA4D,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAE1G,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAA;AAE3F,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,WAAW,CAAC,CAAA;IAC3D;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC3D;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,mFAAmF;IACnF,mBAAmB,EAAE,MAAM,CAAA;IAC3B,sFAAsF;IACtF,qBAAqB,EAAE,MAAM,CAAA;IAC7B,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAA;IACzB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAA;IACxB,uFAAuF;IACvF,eAAe,EAAE,MAAM,CAAA;IACvB,sFAAsF;IACtF,mBAAmB,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB,2FAA2F;IAC3F,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,EAAE,OAAO,CAAA;CAC1B;AA4HD,qBAAa,oBAAqB,YAAW,WAAW,EAAE,UAAU;;gBAwDvD,IAAI,EAAE,wBAAwB,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAyFvE,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAoBjE;;;;;;OAMG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB,EAAE;IAgDvE;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,EAAE;IA8e1C,KAAK,IAAI,IAAI;IASb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAgBxB"}