@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/out/{street-name-lookup.js → street/name-lookup.js}

@@ -8,7 +8,7 @@
  *   Reads a street-name index (the FR instance = BAN `street-centroids-fr.db`, a `street_centroid`
  *   table of `street_norm × locality_base × postcode` rows) and answers "does this street surface
  *   exist as a name" for the k-best rerank. Sync-by-interface, `readOnly`, prepared statements,
- *   graceful-degrade on a tableless shard — the same reader discipline as `AddressPointSqliteLookup`.
+ *   graceful-degrade on a tableless extract — the same reader discipline as `AddressPointSqliteLookup`.
  *
  *   THE FOLD CONTRACT: the surface is folded with {@link foldStreetSurface} (the shared function),
  *   and the DB's `street_norm` column MUST have been built with that SAME fold or every hyphenated /
@@ -18,20 +18,9 @@
  *   then this class is correct-by-construction against a fixture built with the contract fold, and
  *   the production rebuild is a tracked BAN-sdk follow-up.
  */
-import { DatabaseSync } from "node:sqlite";
 import { foldStreetSurface } from "@mailwoman/resolver";
-function hasTable(db, table) {
-    const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(table);
-    return row !== undefined;
-}
-function hasColumn(db, table, column) {
-    // `table` is a caller-controlled identifier (default `street_centroid`), not user input — safe to interpolate.
-    for (const row of db.prepare(`PRAGMA table_info(${table})`).all()) {
-        if (row.name === column)
-            return true;
-    }
-    return false;
-}
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { hasColumn, hasTable } from "#sqlite-utils";
 /**
  * A {@link StreetLocalityEvidence} backed by a street-name SQLite index. Positive evidence only: any doubt (missing
  * table, read miss) returns `false`, so the rerank fails open to the model's ranking.
@@ -44,12 +33,12 @@ export class SQLiteStreetNameLookup {
     #byNamePostcode;
     constructor(dbPath, opts = {}) {
         this.countries = new Set([...(opts.countries ?? ["FR"])].map((c) => c.toUpperCase()));
-        this.#db = new DatabaseSync(dbPath, { readOnly: true });
+        this.#db = new DatabaseClient(dbPath, { readOnly: true });
         const table = opts.table ?? "street_centroid";
-        // Degrade gracefully on an empty/tableless shard — a no-op miss, never a crash (#568 discipline).
+        // Degrade gracefully on an empty/tableless extract — a no-op miss, never a crash (#568 discipline).
         if (hasTable(this.#db, table)) {
             // Prefer the #727 phase-4c `name_key` column (foldStreetSurface, indexed by `idx_sc_name` for a direct seek);
-            // fall back to `street_norm` on a pre-rebuild shard (a skip-scan, but correct). The fold used to build
+            // fall back to `street_norm` on a pre-rebuild extract (a skip-scan, but correct). The fold used to build
             // `name_key` MUST match `foldStreetSurface` here (the fold-parity contract).
             const keyCol = hasColumn(this.#db, table, "name_key") ? "name_key" : "street_norm";
             this.#byName = this.#db.prepare(`SELECT 1 FROM ${table} WHERE ${keyCol} = ? LIMIT 1`);
@@ -75,11 +64,8 @@ export class SQLiteStreetNameLookup {
         }
         return this.#byName.get(norm) !== undefined;
     }
-    /**
-     * Close the underlying handle.
-     */
-    close() {
-        this.#db.close();
+    [Symbol.dispose]() {
+        this.#db[Symbol.dispose]();
     }
 }
-//# sourceMappingURL=street-name-lookup.js.map
+//# sourceMappingURL=name-lookup.js.map

package/out/street/name-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-lookup.js","sourceRoot":"","sources":["../../lib/street/name-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAyD,MAAM,qBAAqB,CAAA;AAC9G,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAGzD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAanD;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IACzB,SAAS,CAAqB;IAC9B,GAAG,CAA6B;IAChC,OAAO,CAAmD;IAC1D,eAAe,CAAmD;IAClE,eAAe,CAAmD;IAE3E,YAAY,MAAc,EAAE,OAAmC,EAAE;QAChE,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAA;QACrF,IAAI,CAAC,GAAG,GAAG,IAAI,cAAc,CAAc,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;QACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,iBAAiB,CAAA;QAE7C,oGAAoG;QACpG,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;YAC/B,8GAA8G;YAC9G,yGAAyG;YACzG,6EAA6E;YAC7E,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,CAAA;YAClF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,KAAK,UAAU,MAAM,cAAc,CAAC,CAAA;YAErF,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CACtC,iBAAiB,KAAK,UAAU,MAAM,oCAAoC,CAC1E,CAAA;YAED,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,KAAK,UAAU,MAAM,+BAA+B,CAAC,CAAA;QAC/G,CAAC;IACF,CAAC;IAED,aAAa,CAAC,aAAqB,EAAE,KAA2B;QAC/D,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAA;QAC/B,MAAM,IAAI,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAA;QAE7C,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAA;QAEvB,oHAAoH;QACpH,iHAAiH;QACjH,IACC,KAAK,EAAE,QAAQ;YACf,IAAI,CAAC,eAAe;YACpB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,SAAS,EAC9E,CAAC;YACF,OAAO,IAAI,CAAA;QACZ,CAAC;QAED,IAAI,KAAK,EAAE,QAAQ,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,SAAS,EAAE,CAAC;YAC7G,OAAO,IAAI,CAAA;QACZ,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,CAAA;IAC5C,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACf,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAA;IAC3B,CAAC;CACD"}

package/out/street/normalize.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   THE street normalizer for the address-point tier (#476). One function, used by BOTH the extract
+ *   builder (`scripts/build-address-point-extract.ts`) and the lookup tier (`address-point.ts`) —
+ *   never two implementations (the PLACETYPE_ORDER lesson: parallel copies silently corrupt).
+ *
+ *   Normalization contract (deliberately aggressive — both sides apply the same function, so
+ *   collisions only need to be _consistent_, not linguistically perfect):
+ *
+ *   1. Lowercase, NFKD-fold diacritics, collapse whitespace, strip punctuation (periods, commas,
+ *        apostrophes).
+ *   2. Expand USPS directional abbreviations at the FIRST and LAST token position (`n` → `north`, `se` →
+ *        `southeast`) — Overture sources abbreviate inconsistently.
+ *   3. Canonicalize a trailing USPS street-type token via the codex suffix table to its canonical full
+ *        form (`st`/`str`/`street` → `street`).
+ *
+ *   Numbered streets are left as digits (`5th` stays `5th`); a SPELLED ordinal before a street suffix
+ *   folds to its digit form (`tenth street` → `10th street`, #723) so the grid-city ordinal
+ *   cross-streets the source data spells with digits become reachable.
+ */
+import type { Tagged } from "type-fest";
+/**
+ * A place name folded by {@link normalizeLocalityForKey} — the value stored in, and required to probe, every
+ * `name_key`-style column: the candidate gazetteer, the postal-city side-index, the street-centroid extract, an
+ * ancestor chain's `parent_name_key`, and the address-point locality scope.
+ *
+ * The brand is here because the fold is applied at BUILD time and is therefore mandatory at QUERY time, while a
+ * near-miss approximation of it (`toLowerCase()`, `trim()`) is still a `string`: it binds to the parameter, returns
+ * fewer rows, and the shortfall reads as a coverage gap in the data rather than a defect in the probe. Requiring the
+ * brand at the boundary turns that silent under-match into a compile error. Mint one only by calling the fold.
+ */
+export type NameKey = Tagged<string, "NameKey">;
+/**
+ * A street name folded by {@link normalizeStreetForKey} / {@link normalizeStreetForKeyLocale} — the value stored in a
+ * `street_norm` address-point column and required to probe it.
+ *
+ * Distinct from {@link RouteKey}: the route fold is a FURTHER canonicalization applied to some columns and not others,
+ * so the two are not interchangeable even though both are folded streets.
+ */
+export type StreetKey = Tagged<string, "StreetKey">;
+/**
+ * A street key that has additionally passed {@link canonicalizeRouteKey} — the numbered-route canonical form.
+ *
+ * A separate brand from {@link StreetKey} because it identifies a DIFFERENT set of columns, and the two folds disagree
+ * exactly on the rows that motivate the route fold: binding a plain street key to a route-folded column silently misses
+ * every row whose source spelled the route differently, which is the miss class the fold exists to close.
+ */
+export type RouteKey = Tagged<string, "RouteKey">;
+/**
+ * Normalize a street name for address-point keying. Same function at build time and lookup time — see module docstring
+ * for the contract.
+ */
+export declare function normalizeStreetForKey(street: string): StreetKey;
+/**
+ * Street-name locale for the address-point key. The US path is the full USPS pipeline ({@link normalizeStreetForKey});
+ * the international paths fold + apply a SMALL, consistent per-locale type-token canonicalization. Same discipline as
+ * the US normalizer: build side and probe side call the identical function, so the key only needs to be CONSISTENT, not
+ * linguistically perfect — a folded "rue du chevaleret" keys the same on both sides whether or not we reorder the
+ * article, so no salient-token / multi-key index is built yet (deferred until probing shows the normalizer can't absorb
+ * the false-negatives).
+ */
+export type StreetLocale = "us" | "en" | "fr" | "de" | "nl" | "pl" | "vn" | "id";
+/**
+ * Country → street-locale registry surface for the acquisition SDKs (BAN, OSM). Each SDK keeps its own map — membership
+ * is a per-register decision — and this factory owns the lookup discipline: throw for an unsupported country rather
+ * than silently folding with the wrong rules, because a extract built with the wrong normalizer keys every street
+ * incorrectly and looks fine until a probe misses. `label` is the SDK's own registration instructions, appended to the
+ * error verbatim.
+ */
+export declare function createStreetLocaleRegistry(registry: ReadonlyMap<string, StreetLocale>, label: string): {
+    localeFor: (countryCode: string) => StreetLocale;
+    supported: () => string[];
+};
+/**
+ * Normalize a street name for the address-point key in a non-US locale. Same function build-side and probe-side (the
+ * one-function discipline). US delegates to {@link normalizeStreetForKey}.
+ *
+ * - **en** — the shared English address-key pipeline (directionals + suffix aliases), currently identical to US.
+ * - **fr** — fold + expand leading type abbreviations and Saint/Sainte (token map).
+ * - **de** — fold + ß→ss + canonicalize the GLUED `-str(.)` suffix to `-strasse` ("Lindenstr." → "lindenstrasse",
+ *   "Lindenstraße" → "lindenstrasse"); an already-full "-strasse" is left intact.
+ * - **nl** — fold + canonicalize the glued `-str` suffix to `-straat` ("Kerkstr." → "kerkstraat").
+ * - **pl** — fold + ł→l (Ł does not NFKD-decompose, so the generic fold keeps it and an undiacritized query would miss;
+ *   every other Polish diacritic is a combining form the fold already strips) + STRIP the leading type token — see
+ *   {@link PL_LEADING_TYPE} for the measured reason expansion was wrong for this source.
+ * - **vn** — fold + đ→d AND ð→d (both non-decomposing, and OSM mixes the two codepoints inside single values — see the
+ *   branch comment). Deliberately NO type-abbreviation map yet: the common abbreviation is the single letter "Đ." for
+ *   Đường, and expanding a bare folded "d" token would rewrite initials — measure the miss rate on the built extract
+ *   before adding anything.
+ * - **id** — fold + expand leading type abbreviations (jl/jln→jalan, gg→gang); Indonesian street surfaces are otherwise
+ *   ASCII-clean.
+ */
+export declare function normalizeStreetForKeyLocale(street: string, locale: StreetLocale): StreetKey;
+/**
+ * Normalize a locality name for address-point keying (fold only — no street semantics).
+ */
+export declare function normalizeLocalityForKey(locality: string): NameKey;
+/**
+ * Surface-driven street-locale ROUTER for bilingual extracts — the Québec finishing move on the CA rooftop extract.
+ *
+ * A country registers ONE street locale, but Canada's street surfaces are two languages: under the `en` rules a French
+ * surface passes through mostly unchanged (both sides fold identically, so those rows stay reachable), and what breaks
+ * is abbreviation variance — the `en` rules cannot fold "boul"/"Ste-" to the full French word, so an abbreviated query
+ * misses a full-word row and vice versa. Routing on the SURFACE (not the province) also carries bilingual NB and the
+ * French street names outside Québec for free.
+ *
+ * ONE function, called by the extract BUILDER and the query PROBE alike — the #861 discipline: routing is part of the
+ * fold contract, and two transcriptions of this predicate would diverge exactly where it matters. Only an `en` base
+ * re-routes: a `fr`/`de`/`nl` extract already speaks its own rules, and the US pipeline stays untouched.
+ *
+ * Measured basis (CA extract, 2026-08-19): 183,963 distinct surfaces, 43,762 French-lead; 29,682 fold differently under
+ * fr-vs-en (888,265 rows), and the non-French half of those are English surfaces this router keeps on `en` unchanged.
+ */
+export declare function streetLocaleForSurface(street: string, base: StreetLocale): StreetLocale;
+/**
+ * Strip a trailing French arrondissement designator from a FOLDED commune key ("paris 8e arrondissement" → "paris",
+ * "lyon 1er arrondissement" → "lyon", "marseille 10e arrondissement" → "marseille"). Paris, Lyon and Marseille are the
+ * only French communes subdivided into _arrondissements municipaux_; a national register (BAN) names each row per
+ * arrondissement, but a query names the base commune ("Place Bellecour, Lyon", never "…, Lyon 2e"). Applied on BOTH
+ * sides of the #1042 street-centroid key — build-side (deriving the `locality_base` column) and query-side (folding the
+ * probe commune) — so the two agree by construction (the one-function discipline). The {@link NameKey} parameter is the
+ * enforcement of "must already be folded": stripping an arrondissement off an unfolded surface yields a key neither
+ * side stores. A no-op for every other commune, and the strip leaves a fold fixed point, so the result is still a
+ * {@link NameKey}. Returns the input unchanged if the strip would empty it.
+ */
+export declare function stripArrondissement(localityNorm: NameKey): NameKey;
+/**
+ * Strip a locality QUALIFIER for a query-side fallback — when an OA locality's exact normalized name misses the
+ * gazetteer's canonical name, retry with the qualifier removed. OA address data carries disambiguating qualifiers the
+ * gazetteer's canonical name omits: Austrian `Kraubath/Mur` and `Hart b.Graz` → `Hart`; Swiss `Lenk im Simmental` →
+ * `Lenk`, `Roche VD` → `Roche`; Danish `Odense S`, `Hurup Thy`. A FALLBACK ONLY — the exact name is tried first, and
+ * the region-bbox disambiguation resolves any base-name ambiguity downstream. The candidate table is unchanged (this is
+ * purely query-side); feed the result back through {@link normalizeLocalityForKey}. Returns "" when nothing was stripped
+ * (no point re-probing the identical key).
+ *
+ * Measured (`scripts/eval/candidate-recall.ts --strip-fallback`, EU OA holdouts): recovers AT 74.1→88.2% (+14.1pp), DK
+ * 91.5→96.2%, CH 90.4→92.6%; +1.3pp overall (diluted by the already-100% locales). Conservative by design — only the
+ * qualifier forms above; FI/PT/SI misses are untouched.
+ */
+export declare function stripLocalityQualifier(locality: string): string;
+/**
+ * Fold numbered-route designators to a canonical key, applied AFTER {@link normalizeStreetForKey}. Sources disagree
+ * systematically on how they spell a route: TIGER says `State Rte 100` / `US Hwy 5` where E911/Overture say `VT ROUTE
+ * 100` / `US ROUTE 5` — the dominant street-name miss class in the #483 interpolation eval (rural addresses live on
+ * routes). `us <designator> N…` folds to `us route N…`; `state <designator> N…` and `<2-letter-prefix> <designator> N…`
+ * (the state abbreviation form) fold to `state route N…`. Only digit-leading route numbers fold — `State Street` and
+ * friends never match.
+ *
+ * Used by BOTH the segment-extract builder (`scripts/build-interpolation-extract.ts`) and the interpolation lookup —
+ * same one-function discipline as {@link normalizeStreetForKey}. The address-point tier (#476) does NOT apply it yet:
+ * adopting it there requires a extract rebuild (noted on #483).
+ *
+ * A same-numbered US and state route stay DISTINCT keys (`us route 5` vs `state route 5`); only the BARE `route N` form
+ * is ambiguous (designator unknown) and it stays unfolded — a bare-route query therefore misses rather than guessing a
+ * designator.
+ */
+export declare function canonicalizeRouteKey(streetNorm: StreetKey): RouteKey;
+/**
+ * Ordered lookup-key variants for a US/EN street span — the primary normalized key first, then the null-only recovery
+ * forms a reader may probe when the primary misses. Two register mismatches motivate them, both measured on live
+ * queries (2026-08-14):
+ *
+ * - **Doubled type** — a user types the type twice ("Saint Pauls PL St"), and the normalizer canonicalizes only the LAST
+ *   type token, leaving `saint pauls pl street`, which matches nothing anywhere. The signature is visible in the key
+ *   itself: a canonical type word in last position DIRECTLY after an uncanonicalized type abbreviation. The variant
+ *   drops the trailing word and canonicalizes what remains (`saint pauls place`). A street genuinely named with two
+ *   types keys identically on both sides and is caught by the primary probe first.
+ * - **Saint↔St register split** — the artifacts preserve each SOURCE's spelling (NYC situs keys `st pauls place`, Nassau
+ *   keys `saint pauls place`), and a query arrives in whichever register the user typed. A leading `saint` or `st`
+ *   token is swapped for its sibling; leading position only — a leading `st` is always the hagionym in US street names,
+ *   and interior tokens ("Mount Saint Helens Dr") are out of scope until measured.
+ *
+ * Deduplicated and ordered most-literal-first, so probing the list in order preserves the primary key's precedence.
+ */
+export declare function streetKeyVariants(street: string, locale?: StreetLocale): StreetKey[];
+//# sourceMappingURL=normalize.d.ts.map

package/out/street/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../lib/street/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AA4DjD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAkE/D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAEhF;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAC3C,KAAK,EAAE,MAAM,GACX;IAAE,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,MAAM,EAAE,CAAA;CAAE,CAajF;AAgDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,CAoE3F;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjE;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,YAAY,CAEvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAIlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+C/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,SAAS,GAAG,QAAQ,CASpE;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,YAAmB,GAAG,SAAS,EAAE,CA8C1F"}