@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/out/interpolation.js

@@ -8,7 +8,7 @@
  *   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
+ *   Reads the per-state extract built by `scripts/build-interpolation-extract.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.
@@ -25,43 +25,92 @@
  *   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 { parseJSONStrict } from "@mailwoman/core/objects";
-import { clampFraction, pointAlong } from "@mailwoman/spatial";
-import { haversineKm } from "./geo.js";
-import { hasTable } from "./sqlite-utils.js";
-import { canonicalizeRouteKey, normalizeStreetForKey } from "./street-normalize.js";
+import { parseJSONStrict } from "@mailwoman/core/json";
+import { clampFraction, haversineKm, pointAlong } from "@mailwoman/spatial";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { hasTable, prepareAll } from "#sqlite-utils";
+import { canonicalizeRouteKey, streetKeyVariants } from "#street/normalize";
+/**
+ * Acceptance geometry for the `near` tie-break: the winning postcode group's closest segment must sit within this many
+ * kilometres of `near`, AND the runner-up group must be at least {@link NEAR_DOMINANCE} times farther. Both measured on
+ * the two live failures: Brooklyn's `st pauls place` 11226 segment is ~2 km from the Brooklyn centroid with Great
+ * Neck's 11021 at ~24 km (12×); Fraser's `east 13 mile road` 48026 is ~2 km with Mecosta's namesake ~190 km away. A
+ * near-tie between groups is genuine ambiguity and stays an abstention.
+ */
+const NEAR_MAX_KM = 25;
+/**
+ * See {@link NEAR_MAX_KM}.
+ */
+const NEAR_DOMINANCE = 2;
+/**
+ * The postcode group nearest `near`, under the {@link NEAR_MAX_KM} dominance geometry — or null when no group qualifies
+ * (out of range, or the runner-up is too close to call). A group's distance is its closest segment's first polyline
+ * vertex; a segment whose geometry fails to parse prices as unreachable rather than aborting the tie-break.
+ */
+function nearestPostcodeGroup(pool, near) {
+    const groups = new Map();
+    for (const row of pool) {
+        const key = row.postcode ?? "";
+        let km = Number.POSITIVE_INFINITY;
+        try {
+            const [firstVertex] = parseJSONStrict(row.geometry);
+            if (firstVertex) {
+                km = haversineKm(near.lat, near.lon, firstVertex[1], firstVertex[0]);
+            }
+        }
+        catch {
+            // Unparseable geometry: this row cannot be sited, so it cannot win the tie-break.
+        }
+        const group = groups.get(key);
+        if (group) {
+            group.rows.push(row);
+            group.km = Math.min(group.km, km);
+        }
+        else {
+            groups.set(key, { rows: [row], km });
+        }
+    }
+    const ranked = [...groups.values()].toSorted((a, b) => a.km - b.km);
+    const [winner, runnerUp] = ranked;
+    if (!winner || winner.km > NEAR_MAX_KM)
+        return null;
+    if (runnerUp && runnerUp.km < winner.km * NEAR_DOMINANCE)
+        return null;
+    return winner.rows;
+}
 export class StreetInterpolator {
     #db;
-    #ownsDB;
+    /**
+     * 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();
     #byPostcode;
     #byStreet;
     #radiusCalibration;
     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;
+            this.#db = this.#resources.use(new DatabaseClient(opts.dbPath, { readOnly: 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
+        // Degrade gracefully on an empty/tableless extract (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
+            this.#byPostcode = prepareAll(this.#db, `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
+            this.#byStreet = prepareAll(this.#db, `SELECT ${columns} FROM street_segment
 				 WHERE street_norm = ? AND min_hn <= ? AND max_hn >= ?`);
         }
         // #374 doctrine: the conformal radius multiplier is a property of the calibration set the ARTIFACT was
-        // built against, so it ships in the shard's `interp_calibration` metadata table (street-segment-schema.ts)
+        // built against, so it ships in the extract's `interp_calibration` metadata table (street-segment-schema.ts)
         // and is read here, once, at open time — sync raw `.prepare()` per the sync-by-interface doctrine
-        // (AGENTS.md). Shards predating the table (the pre-2026-07 fleet) yield `undefined`; callers then fall
+        // (AGENTS.md). Extracts predating the table (the pre-2026-07 fleet) yield `undefined`; callers then fall
         // back to their in-code table, byte-identically.
         if (hasTable(this.#db, "interp_calibration")) {
             const row = this.#db.prepare("SELECT radius_multiplier FROM interp_calibration LIMIT 1").get();
@@ -72,9 +121,9 @@ export class StreetInterpolator {
         }
     }
     /**
-     * The artifact's own conformal radius multiplier (#374), read from the shard's `interp_calibration` metadata table at
-     * construction. `undefined` = the shard predates the table (or carries no valid row) — the resolver then applies no
-     * artifact default and callers may supply a legacy fallback.
+     * The artifact's own conformal radius multiplier (#374), read from the extract's `interp_calibration` metadata table
+     * at construction. `undefined` = the extract predates the table (or carries no valid row) — the resolver then applies
+     * no artifact default and callers may supply a legacy fallback.
      */
     get radiusCalibration() {
         return this.#radiusCalibration;
@@ -82,27 +131,36 @@ export class StreetInterpolator {
     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))
+        if (!/^\d+$/.test(numberRaw))
             return null;
         const n = Number(numberRaw);
-        let rows;
-        if (query.postcode) {
+        // Key-variant ladder (see `streetKeyVariants`): the literal key first, then the doubled-type
+        // collapse and the saint↔st register swap. A variant advances the ladder when it produces no
+        // ANSWER, not merely no rows — a wrong-register key can cover the number in far-away towns and
+        // then fail the ambiguity check ("saint pauls place" reaches Nassau's rows; the Brooklyn answer
+        // lives under "st pauls place"), and stopping at rows would eclipse the right variant.
+        for (const variant of streetKeyVariants(query.street)) {
+            const streetNorm = canonicalizeRouteKey(variant);
             // 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;
+            const rows = query.postcode
+                ? this.#byPostcode(query.postcode.trim(), streetNorm, n, n)
+                : this.#byStreet(streetNorm, n, n);
+            const hit = this.#answerFromRows(rows, n, query);
+            if (hit)
+                return hit;
         }
+        return null;
+    }
+    /**
+     * Resolve one key variant's covering rows to an answer, or null when they cannot honestly give one — the
+     * parity/ambiguity/tightest-range pipeline the module doc describes.
+     */
+    #answerFromRows(rows, n, query) {
         if (!rows.length)
             return null;
         // Parity preference: exact side first, then 'mixed' (matches either), then the
@@ -111,8 +169,24 @@ export class StreetInterpolator {
         const exact = rows.filter((r) => r.parity === (wantOdd ? "odd" : "even"));
         const mixed = rows.filter((r) => r.parity === "mixed");
         const preferred = exact.length ? exact : mixed;
-        const pool = preferred.length ? preferred : rows;
+        let pool = preferred.length ? preferred : rows;
         const parityMatched = preferred.length > 0;
+        // No scope given: the covering ranges must agree on ONE postcode or the lookup abstains — a
+        // name spanning towns is ambiguity, not an answer. Counted over the PARITY pool, not all
+        // rows: a section-line boundary road carries a different ZIP per side ("east 13 mile road"
+        // is Fraser 48026 odd / Roseville 48066 even), and the opposite side can never hold the
+        // number it would otherwise veto. When several postcodes survive parity, the caller's
+        // resolved-locality coordinate breaks the tie by segment proximity under the dominance
+        // geometry of {@link NEAR_MAX_KM} — a near-tie stays an abstention.
+        if (!query.postcode) {
+            const postcodes = new Set(pool.map((r) => r.postcode ?? ""));
+            if (postcodes.size > 1) {
+                const scoped = query.near ? nearestPostcodeGroup(pool, query.near) : null;
+                if (!scoped)
+                    return null;
+                pool = scoped;
+            }
+        }
         // Tightest range wins — the most specific claim about where this number lives.
         let best = pool[0];
         for (const candidate of pool) {
@@ -135,10 +209,8 @@ export class StreetInterpolator {
             release: best.release,
         };
     }
-    close() {
-        if (this.#ownsDB) {
-            this.#db.close();
-        }
+    [Symbol.dispose]() {
+        this.#resources[Symbol.dispose]();
     }
 }
 //# sourceMappingURL=interpolation.js.map

package/out/interpolation.js.map

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

package/out/lookup.d.ts

@@ -3,48 +3,49 @@
  * @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 { type Ancestor, type CoincidentLocality } from "@mailwoman/resolver";
-import { type Convention, type ConventionSource } from "./convention.ts";
-import type { WOFPostalCityAliasLookup } from "./postal-city-alias-lookup.ts";
-import { type RankingWeights } from "./ranking-weights.ts";
-import { type ShardConfig } from "./sharding.ts";
-import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "./types.ts";
-export interface WOFSqlitePlaceLookupOpts {
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { type Convention, type ConventionSource } from "#convention/index";
+import { type ExtractConfig } from "#extracts";
+import type { WOFPostalCityAliasLookup } from "#postal/city-alias-lookup";
+import { type RankingWeights } from "#ranking-weights";
+import type { WOFDatabase } from "#schema";
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup } from "#types";
+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.
+     * **Single string** — opens that one DB as the main extract.
      *
      * **Array** — opens the first entry as main, then ATTACHes each subsequent entry as a separate SQLite schema. Schema
      * names are derived from the filename (`whosonfirst-data-postalcode- us-latest.db` → `postalcode_us`); override with
-     * `ShardConfig.schemaName` when the filename doesn't follow WOF convention. See `sharding.ts` for the derivation
+     * `ExtractConfig.schemaName` when the filename doesn't follow WOF convention. See `extracts.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.
+     * Routing: queries with a `placetype` matching a extract's name (or explicit `placetypes` hint) are sent to that
+     * extract; everything else hits main. Cross-extract UNION is NOT done — BM25 isn't comparable across
+     * separately-indexed corpora.
      */
-    databasePath?: string | ReadonlyArray<string | ShardConfig>;
+    databasePath?: string | ReadonlyArray<string | ExtractConfig>;
     /**
-     * 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).
+     * Pre-opened connection — primarily for tests against an inline fixture DB. Mutually exclusive with `databasePath`.
+     * Multi-extract requires `databasePath` (so the lookup owns the ATTACH).
      */
-    database?: DatabaseSync;
+    database?: DatabaseClient<WOFDatabase>;
     /**
      * If true, build the FTS5 `place_search` virtual table on construction if it doesn't already exist. The upstream WOF
      * distribution does NOT ship FTS5, so callers either set this once on first open or pre-build it via the
      * operator-side CLI documented in the README. Default false — the resolver assumes the index already exists and
      * errors loudly if it doesn't.
      *
-     * With multi-shard, `buildFTS: true` builds the index on the **main** shard only. Other shards must be pre-built via
-     * `mailwoman gazetteer build fts` — operator script for predictable cost.
+     * With multi-extract, `buildFTS: true` builds the index on the **main** extract only. Other extracts must be
+     * pre-built via `mailwoman gazetteer build fts` — operator script for predictable cost.
      */
     buildFTS?: boolean;
     /**
@@ -58,13 +59,14 @@ export interface WOFSqlitePlaceLookupOpts {
      * 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.
+     * byte-identical — every alias code path is conditioned on this being non-null, so an unprovided reader changes no
+     * score.
      */
     postalCityAliases?: WOFPostalCityAliasLookup;
 }
-export declare class WOFSqlitePlaceLookup implements PlaceLookup, Disposable {
+export declare class WOFSQLitePlaceLookup implements PlaceLookup, Disposable {
     #private;
-    constructor(opts: WOFSqlitePlaceLookupOpts, weights?: Partial<RankingWeights>);
+    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
@@ -83,9 +85,7 @@ export declare class WOFSqlitePlaceLookup implements PlaceLookup, Disposable {
      * locality/neighbourhood ancestors order correctly instead of sorting last.
      */
     ancestors(id: number | string): Ancestor[];
-    close(): void;
     [Symbol.dispose](): void;
 }
-export { trigramJaccard, trigrams } from "./name-score.ts";
-export type { RankingWeights } from "./ranking-weights.ts";
+export type { RankingWeights } from "#ranking-weights";
 //# sourceMappingURL=lookup.d.ts.map

package/out/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAA;AAG9D,OAAO,EAAyB,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAKnG,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,gBAAgB,EAGrB,MAAM,iBAAiB,CAAA;AAcxB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAC7E,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE3E,OAAO,EAKN,KAAK,WAAW,EAChB,MAAM,eAAe,CAAA;AAEtB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAA;AAS3F,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;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AA8DD,qBAAa,oBAAqB,YAAW,WAAW,EAAE,UAAU;;gBAmEvD,IAAI,EAAE,wBAAwB,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAgIvE,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA6DjE;;;;;OAKG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB,EAAE;IA2DvE;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,EAAE;IAszB1C,KAAK,IAAI,IAAI;IAUb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAkBxB;AAED,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE1D,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../lib/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAyB,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAGnG,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAKzD,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,gBAAgB,EAGrB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAKN,KAAK,aAAa,EAClB,MAAM,WAAW,CAAA;AAalB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AACzE,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAI1C,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAgB,MAAM,QAAQ,CAAA;AAEvF,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,aAAa,CAAC,CAAA;IAC7D;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,WAAW,CAAC,CAAA;IACtC;;;;;;;;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;AAqCD,qBAAa,oBAAqB,YAAW,WAAW,EAAE,UAAU;;gBAsEvD,IAAI,EAAE,wBAAwB,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAqKvE,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA6DjE;;;;;OAKG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,kBAAkB,EAAE;IAYvE;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,EAAE;IAwX1C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAoBxB;AAED,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}