@mailwoman/resolver-wof-sqlite 2.1.0

package/out/sharding.js

@@ -0,0 +1,129 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Multi-shard support for `WofSqlitePlaceLookup` — opens multiple WOF SQLite distributions on one
+ *   connection via `ATTACH DATABASE`, and routes queries to the right shard based on placetype.
+ *
+ *   ## The FTS5 syntax rule that drove this design
+ *
+ *   The naive `SELECT … FROM pc.place_search WHERE pc.place_search MATCH ?` fails — SQLite parses the
+ *   schema-qualified table on the left of MATCH as "column place_search of table pc". Discovered in
+ *   the spike at PR review time; documented as `_SHARD_RULE.md` should it ever bite again.
+ *
+ *   The working form: schema-qualified in FROM, bare table name in MATCH:
+ *
+ *   ```sql
+ *   SELECT … FROM pc.place_search WHERE place_search MATCH ?
+ * ```
+ *
+ *   Identical table names across attached shards (which is what we have — every shard ships its own
+ *   `place_search` + `place_bbox`) are fine because the bare-name MATCH resolves against FROM
+ *   scope.
+ */
+import { basename } from "node:path";
+/**
+ * Derive a SQL-safe schema name from a WOF distribution filename. Used by `ATTACH DATABASE … AS
+ * <name>` so each shard gets a stable, predictable handle.
+ *
+ * Convention strips the `whosonfirst-data-` prefix and the `-latest.db` (or just `.db`) suffix,
+ * then replaces `-` with `_` for SQL identifier safety.
+ *
+ * Examples:
+ *
+ * - `whosonfirst-data-admin-us-latest.db` → `admin_us`
+ * - `whosonfirst-data-postalcode-us-latest.db` → `postalcode_us`
+ * - `whosonfirst-data-admin-latest.db` → `admin`
+ * - `my-custom.db` → `my_custom`
+ *
+ * Callers can override the derived name explicitly via `ShardConfig.schemaName` when the filename
+ * doesn't follow WOF convention.
+ */
+export function deriveSchemaName(path) {
+    const stem = basename(path)
+        .replace(/^whosonfirst-data-/u, "")
+        .replace(/-latest\.db$/u, "")
+        .replace(/\.db$/u, "")
+        .replace(/[^a-zA-Z0-9_]/g, "_");
+    if (!stem) {
+        throw new Error(`deriveSchemaName: could not derive a SQL schema name from path ${JSON.stringify(path)}`);
+    }
+    return stem;
+}
+/** SQLite identifier regex — `[A-Za-z_][A-Za-z0-9_]*`. */
+const SQLITE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * Normalize the user-provided `databasePath` opt (which may be a single string, an array of
+ * strings, or an array of `ShardConfig` objects) into a uniform `ResolvedShard[]`.
+ *
+ * The first shard becomes `main` regardless of its derived schema name — that's the SQLite
+ * convention. Subsequent shards keep their derived (or override) schema name.
+ */
+export function resolveShards(input) {
+    const list = typeof input === "string" ? [input] : input;
+    if (list.length === 0)
+        throw new Error("resolveShards: at least one shard is required");
+    const seen = new Set();
+    const out = [];
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        const cfg = typeof entry === "string" ? { path: entry } : entry;
+        const derived = cfg.schemaName ?? deriveSchemaName(cfg.path);
+        if (!SQLITE_IDENT_RE.test(derived)) {
+            throw new Error(`resolveShards: schema name ${JSON.stringify(derived)} is not a valid SQLite identifier ` +
+                `(derived from path ${JSON.stringify(cfg.path)}). Pass an explicit ` +
+                `{ path, schemaName } to override.`);
+        }
+        // The first shard is always main per SQLite semantics — its derived name is informational
+        // only. Subsequent shards must have unique non-main names.
+        const schemaName = i === 0 ? "main" : derived;
+        if (i > 0 && (schemaName === "main" || seen.has(schemaName))) {
+            throw new Error(`resolveShards: schema name ${JSON.stringify(schemaName)} collides ` +
+                `(either with "main" or another shard). Pass an explicit { path, schemaName }.`);
+        }
+        seen.add(schemaName);
+        out.push({
+            path: cfg.path,
+            schemaName,
+            placetypes: cfg.placetypes ?? [],
+        });
+    }
+    return out;
+}
+/**
+ * Pick the shard to route a query to given the requested placetype(s).
+ *
+ * Routing rules, in order:
+ *
+ * 1. If any shard has explicit `placetypes` that includes the requested placetype, use it.
+ * 2. Otherwise, if a non-main shard's `schemaName` matches the placetype (e.g. `postalcode_us` matches
+ *    `postalcode`), use it.
+ * 3. Otherwise, fall back to `main`.
+ *
+ * This deliberately doesn't UNION across shards — BM25 scores aren't comparable across separately-
+ * indexed corpora, and the typical mailwoman query has a single placetype anyway. If a caller needs
+ * cross-shard results they can issue two `findPlace` calls.
+ */
+export function pickShardForPlacetype(shards, placetype) {
+    if (!placetype)
+        return shards[0];
+    for (const s of shards) {
+        if (s.placetypes.includes(placetype))
+            return s;
+    }
+    for (const s of shards) {
+        if (s.schemaName === "main")
+            continue;
+        // Substring match: `postalcode_us` matches `postalcode`. Conservative — requires the
+        // placetype to appear at a word boundary in the schema name to avoid false hits like
+        // `region` matching `arboregion`.
+        if (s.schemaName === placetype ||
+            s.schemaName.startsWith(`${placetype}_`) ||
+            s.schemaName.endsWith(`_${placetype}`)) {
+            return s;
+        }
+    }
+    return shards[0];
+}
+//# sourceMappingURL=sharding.js.map

package/out/sharding.js.map

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

package/out/sqlite-convention-source.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `SqliteConventionSource` — a `ConventionSource` backed by the build-from-source convention asset
+ *   (#290, Direction E). Conventions live in a read-only, provenance-stamped `address_convention`
+ *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
+ *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
+ *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
+ *   value in memory `feedback-no-load-bearing-trivia`).
+ *
+ *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
+ *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
+ *   swallowed.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import { type Convention, type ConventionSource } from "./convention.js";
+export declare class SqliteConventionSource implements ConventionSource {
+    #private;
+    /**
+     * @param db An open handle to a DB that has the convention asset attached (or is it).
+     * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed
+     *   shard name — `WofSqlitePlaceLookup` auto-detects which shard carries the table).
+     */
+    constructor(db: DatabaseSync, schema: string);
+    get(wofId: number): Convention | undefined;
+}
+//# sourceMappingURL=sqlite-convention-source.d.ts.map

package/out/sqlite-convention-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-convention-source.d.ts","sourceRoot":"","sources":["../sqlite-convention-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAElG,qBAAa,sBAAuB,YAAW,gBAAgB;;IAM9D;;;;OAIG;gBACS,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM;IAK5C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAiB1C"}

package/out/sqlite-convention-source.js

@@ -0,0 +1,53 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `SqliteConventionSource` — a `ConventionSource` backed by the build-from-source convention asset
+ *   (#290, Direction E). Conventions live in a read-only, provenance-stamped `address_convention`
+ *   table keyed by WOF polygon id; this source queries them ON DEMAND by id (one indexed lookup,
+ *   memoized) rather than paging the whole table into memory as a code constant — the deliberate
+ *   counter to the Pelias "giant dictionary in RAM, no provenance" pattern (see the operator design
+ *   value in memory `feedback-no-load-bearing-trivia`).
+ *
+ *   The asset is the queryable, distributable artifact; the strategy IMPLEMENTATIONS stay in code. An
+ *   unknown strategy NAME is surfaced loudly at dispatch (see `lookup.ts`), not silently
+ *   swallowed.
+ */
+import { ADDRESS_CONVENTION_TABLE } from "./convention.js";
+export class SqliteConventionSource {
+    #db;
+    #schema;
+    /** Memoize per-id lookups (including misses, as `null`) so a hot ancestor chain is queried once. */
+    #cache = new Map();
+    /**
+     * @param db An open handle to a DB that has the convention asset attached (or is it).
+     * @param schema The schema name the `address_convention` table lives under (`main` or an ATTACHed
+     *   shard name — `WofSqlitePlaceLookup` auto-detects which shard carries the table).
+     */
+    constructor(db, schema) {
+        this.#db = db;
+        this.#schema = schema;
+    }
+    get(wofId) {
+        const cached = this.#cache.get(wofId);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        let value = null;
+        try {
+            const row = this.#db
+                .prepare(`SELECT convention FROM ${this.#schema}.${ADDRESS_CONVENTION_TABLE} WHERE wof_id = ?`)
+                .get(wofId);
+            if (row?.convention)
+                value = JSON.parse(row.convention);
+        }
+        catch {
+            // Malformed JSON or a missing table → treat as no override (the chain falls back to
+            // WORLD_DEFAULT). The build script validates structure, so this is purely defensive.
+            value = null;
+        }
+        this.#cache.set(wofId, value);
+        return value ?? undefined;
+    }
+}
+//# sourceMappingURL=sqlite-convention-source.js.map

package/out/sqlite-convention-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-convention-source.js","sourceRoot":"","sources":["../sqlite-convention-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,wBAAwB,EAA0C,MAAM,iBAAiB,CAAA;AAElG,MAAM,OAAO,sBAAsB;IACzB,GAAG,CAAc;IACjB,OAAO,CAAQ;IACxB,oGAAoG;IAC3F,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAA;IAEtD;;;;OAIG;IACH,YAAY,EAAgB,EAAE,MAAc;QAC3C,IAAI,CAAC,GAAG,GAAG,EAAE,CAAA;QACb,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,GAAG,CAAC,KAAa;QAChB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACrC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,IAAI,SAAS,CAAA;QACpD,IAAI,KAAK,GAAsB,IAAI,CAAA;QACnC,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;iBAClB,OAAO,CAAC,0BAA0B,IAAI,CAAC,OAAO,IAAI,wBAAwB,mBAAmB,CAAC;iBAC9F,GAAG,CAAC,KAAK,CAAuC,CAAA;YAClD,IAAI,GAAG,EAAE,UAAU;gBAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAe,CAAA;QACtE,CAAC;QAAC,MAAM,CAAC;YACR,oFAAoF;YACpF,qFAAqF;YACrF,KAAK,GAAG,IAAI,CAAA;QACb,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAC7B,OAAO,KAAK,IAAI,SAAS,CAAA;IAC1B,CAAC;CACD"}

package/out/sqlite-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Small shared helpers for the SQLite-backed lookups.
+ */
+import type { DatabaseSync } from "node:sqlite";
+/**
+ * True when `name` is a table in the open database. The street-level lookups use this to degrade
+ * gracefully on an empty/tableless shard — an interrupted `build-*-shard.ts`, or a stray 0-byte
+ * file (e.g. `sqlite3 <missing>.db "…"` CREATES one) — rather than throwing `no such table` at
+ * construction and taking down a whole state's geocode (#568). A missing table makes the lookup a
+ * no-op miss.
+ */
+export declare function hasTable(db: DatabaseSync, name: string): boolean;
+//# sourceMappingURL=sqlite-utils.d.ts.map

package/out/sqlite-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-utils.d.ts","sourceRoot":"","sources":["../sqlite-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOhE"}

package/out/sqlite-utils.js

@@ -0,0 +1,24 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Small shared helpers for the SQLite-backed lookups.
+ */
+/**
+ * True when `name` is a table in the open database. The street-level lookups use this to degrade
+ * gracefully on an empty/tableless shard — an interrupted `build-*-shard.ts`, or a stray 0-byte
+ * file (e.g. `sqlite3 <missing>.db "…"` CREATES one) — rather than throwing `no such table` at
+ * construction and taking down a whole state's geocode (#568). A missing table makes the lookup a
+ * no-op miss.
+ */
+export function hasTable(db, name) {
+    try {
+        const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(name);
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sqlite-utils.js.map

package/out/sqlite-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-utils.js","sourceRoot":"","sources":["../sqlite-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAgB,EAAE,IAAY;IACtD,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,uEAAuE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACzG,OAAO,GAAG,KAAK,SAAS,CAAA;IACzB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC"}

package/out/street-morphology-fst-builder.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build a street-morphology FST from libpostal's street_types dictionaries. The morphology FST maps
+ *   street-typing affixes (Street/Avenue/rue/Calle/Straße/...) to a single synthetic placetype
+ *   `"street_affix"` — distinct from the admin FST in source data, intent, and binary artifact.
+ *
+ *   The morphology FST closes the inference-time vacuum identified by the v0.6.1 postmortem: street
+ *   tokens have no admin-FST anchor, so synth-street training pushed the model toward over-emitting
+ *   `dependent_locality` on subcomponents. With the morphology FST, the neural decoder gets
+ *   positive evidence for street-typing affixes and the adjacent name tokens, plus negative
+ *   evidence away from `dependent_locality` on the same neighbours.
+ *
+ *   Design rationale + the four-layer street-supplement architecture lives in
+ *   `docs/articles/concepts/street-supplement-architecture.md`.
+ *
+ *   Source: `core/data/libpostal/dictionaries/{locale}/street_types.txt`. Each line is pipe-delimited
+ *   surface forms with the canonical form first: avenue|av|ave|aven|avenu|avn|avnu|avnue
+ *
+ *   Output: an `FstMatcher` ready to serialize via `serializeFst` to e.g.
+ *   `fst-street-morphology.bin`.
+ */
+import { FstMatcher } from "./fst-matcher.js";
+import type { FstProvenance } from "./fst-types.js";
+export interface BuildStreetMorphologyFstOpts {
+    /** Path to the `core/data/libpostal/dictionaries` directory containing per-locale subfolders. */
+    dictionariesDir: string;
+    /**
+     * Optional locale filter — only ingest these locale subfolders. Defaults to all that have a
+     * `street_types.txt`.
+     */
+    locales?: string[];
+    /**
+     * Minimum length (in characters, post-normalization) of variant surface forms to insert into the
+     * trie. Defaults to 3.
+     *
+     * Rationale: libpostal's street_types dictionaries contain 1-2 character abbreviations (`a`, `b`,
+     * `av`, `bd`, `br`, ...) that collide with non-affix tokens at parse time — notably US state
+     * abbreviations (`OR`, `CA`, `ND`, `NY`), single-letter unit designators, and arbitrary short
+     * tokens. Empirically these collisions push the morphology prior to mis-tag state abbreviations
+     * as `street_suffix`. A minimum length of 3 retains useful forms (`ave`, `blvd`, `rue`, `str`)
+     * while filtering out the noise.
+     */
+    minVariantLength?: number;
+    /** Optional progress callback. */
+    onProgress?: (phase: string, detail?: string) => void;
+}
+export interface BuildStreetMorphologyFstResult {
+    matcher: FstMatcher;
+    provenance: FstProvenance;
+    canonicalCount: number;
+    variantCount: number;
+    insertCount: number;
+    locales: string[];
+}
+export declare function buildStreetMorphologyFst(opts: BuildStreetMorphologyFstOpts): BuildStreetMorphologyFstResult;
+//# sourceMappingURL=street-morphology-fst-builder.d.ts.map

package/out/street-morphology-fst-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-morphology-fst-builder.d.ts","sourceRoot":"","sources":["../street-morphology-fst-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,gBAAgB,CAAA;AAW/D,MAAM,WAAW,4BAA4B;IAC5C,iGAAiG;IACjG,eAAe,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kCAAkC;IAClC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,8BAA8B;IAC9C,OAAO,EAAE,UAAU,CAAA;IACnB,UAAU,EAAE,aAAa,CAAA;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,EAAE,CAAA;CACjB;AAmBD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,4BAA4B,GAAG,8BAA8B,CAwH3G"}

package/out/street-morphology-fst-builder.js

@@ -0,0 +1,174 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build a street-morphology FST from libpostal's street_types dictionaries. The morphology FST maps
+ *   street-typing affixes (Street/Avenue/rue/Calle/Straße/...) to a single synthetic placetype
+ *   `"street_affix"` — distinct from the admin FST in source data, intent, and binary artifact.
+ *
+ *   The morphology FST closes the inference-time vacuum identified by the v0.6.1 postmortem: street
+ *   tokens have no admin-FST anchor, so synth-street training pushed the model toward over-emitting
+ *   `dependent_locality` on subcomponents. With the morphology FST, the neural decoder gets
+ *   positive evidence for street-typing affixes and the adjacent name tokens, plus negative
+ *   evidence away from `dependent_locality` on the same neighbours.
+ *
+ *   Design rationale + the four-layer street-supplement architecture lives in
+ *   `docs/articles/concepts/street-supplement-architecture.md`.
+ *
+ *   Source: `core/data/libpostal/dictionaries/{locale}/street_types.txt`. Each line is pipe-delimited
+ *   surface forms with the canonical form first: avenue|av|ave|aven|avenu|avn|avnu|avnue
+ *
+ *   Output: an `FstMatcher` ready to serialize via `serializeFst` to e.g.
+ *   `fst-street-morphology.bin`.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { FstMatcher, normalizeTokens } from "./fst-matcher.js";
+/**
+ * Reserved synthetic wofID base for street-morphology entries. 32-bit unsigned, well above any
+ * realistic WOF allocation. Reusing the same base across rebuilds keeps IDs stable for any consumer
+ * that caches them. See [[project-schema-storage-decision]] for the reserved range policy.
+ */
+const STREET_AFFIX_WOFID_BASE = 1_900_000_000;
+const STREET_TYPES_FILENAME = "street_types.txt";
+/**
+ * Parse one `street_types.txt` line into `{ canonical, variants }`. Canonical is the first token
+ * (pre-`|`); variants are all whitespace-stripped non-empty tokens including the canonical.
+ *
+ * Lines with no `|` are treated as a single-form entry where canonical == variant.
+ */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#"))
+        return null;
+    const parts = trimmed
+        .split("|")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (parts.length === 0)
+        return null;
+    return { canonical: parts[0], variants: parts };
+}
+export function buildStreetMorphologyFst(opts) {
+    const progress = opts.onProgress ?? (() => { });
+    const minVariantLength = opts.minVariantLength ?? 3;
+    // Discover locales — either provided explicitly, or all directories containing street_types.txt.
+    let locales;
+    if (opts.locales && opts.locales.length > 0) {
+        locales = opts.locales;
+    }
+    else {
+        locales = readdirSync(opts.dictionariesDir).filter((entry) => {
+            const localePath = join(opts.dictionariesDir, entry);
+            if (!statSync(localePath).isDirectory())
+                return false;
+            try {
+                statSync(join(localePath, STREET_TYPES_FILENAME));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    progress("discover", `Found ${locales.length} locales with ${STREET_TYPES_FILENAME}`);
+    // Collect canonical → set-of-variants across all locales. Same canonical form may appear in
+    // multiple locales (e.g. "avenue" in en/fr); we union the variant sets.
+    const canonicalToVariants = new Map();
+    for (const locale of locales) {
+        const filePath = join(opts.dictionariesDir, locale, STREET_TYPES_FILENAME);
+        const content = readFileSync(filePath, "utf8");
+        for (const line of content.split("\n")) {
+            const parsed = parseLine(line);
+            if (!parsed)
+                continue;
+            const existing = canonicalToVariants.get(parsed.canonical) ?? new Set();
+            for (const variant of parsed.variants)
+                existing.add(variant);
+            canonicalToVariants.set(parsed.canonical, existing);
+        }
+    }
+    progress("collect", `Collected ${canonicalToVariants.size} canonical affixes`);
+    // Assign stable synthetic wofIDs. Sort canonicals for determinism.
+    const sortedCanonicals = [...canonicalToVariants.keys()].sort();
+    const canonicalToWofID = new Map();
+    for (let i = 0; i < sortedCanonicals.length; i++) {
+        canonicalToWofID.set(sortedCanonicals[i], STREET_AFFIX_WOFID_BASE + i);
+    }
+    // Build the trie. Each variant is inserted as a token sequence pointing to its canonical's
+    // PlaceEntry — so all variants of "avenue" (av/ave/aven/...) lead to the same terminal entry.
+    const nodes = [{ edges: new Map(), places: [] }];
+    function insertName(tokens, entry) {
+        if (tokens.length === 0)
+            return;
+        let stateId = 0;
+        for (const t of tokens) {
+            const node = nodes[stateId];
+            let next = node.edges.get(t);
+            if (next === undefined) {
+                next = nodes.length;
+                nodes.push({ edges: new Map(), places: [] });
+                node.edges.set(t, next);
+            }
+            stateId = next;
+        }
+        const existing = nodes[stateId].places;
+        if (!existing.some((p) => p.wofID === entry.wofID && p.placetype === entry.placetype)) {
+            existing.push(entry);
+        }
+    }
+    let insertCount = 0;
+    let variantCount = 0;
+    for (const canonical of sortedCanonicals) {
+        const variants = canonicalToVariants.get(canonical);
+        const wofID = canonicalToWofID.get(canonical);
+        const entry = {
+            wofID,
+            placetype: "street_affix",
+            name: canonical,
+            parentChain: [],
+            // Fixed importance: street affixes are structurally unambiguous (Avenue is almost never
+            // anything but street-typing). The morphology prior caps bias separately; this value
+            // just feeds the cap formula `importance * cap`.
+            importance: 1.0,
+            lat: 0,
+            lon: 0,
+        };
+        for (const variant of variants) {
+            const tokens = normalizeTokens(variant);
+            if (tokens.length === 0)
+                continue;
+            // Filter out collision-prone short surface forms — see `minVariantLength` docstring.
+            // We measure against the joined token form (no spaces) since FST keys are token sequences.
+            const joined = tokens.join("");
+            if (joined.length < minVariantLength)
+                continue;
+            insertName(tokens, entry);
+            insertCount++;
+            variantCount++;
+        }
+    }
+    progress("trie", `Built trie: ${nodes.length} states, ${insertCount} variant insertions`);
+    const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0);
+    const matcher = FstMatcher.fromNodes(nodes);
+    const provenance = {
+        builtAt: new Date().toISOString(),
+        countries: locales, // Reuse `countries` slot for locale provenance — semantics differ from admin FST.
+        stateCount: nodes.length,
+        placeCount: sortedCanonicals.length,
+        edgeCount,
+        nameInsertions: insertCount,
+        importanceMatches: 0, // No importance scoring for morphology — fixed at 1.0.
+        sourceDb: opts.dictionariesDir,
+    };
+    return {
+        matcher,
+        provenance,
+        canonicalCount: sortedCanonicals.length,
+        variantCount,
+        insertCount,
+        locales,
+    };
+}
+//# sourceMappingURL=street-morphology-fst-builder.js.map

package/out/street-morphology-fst-builder.js.map

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

package/out/street-normalize.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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 shard
+ *   builder (`scripts/build-address-point-shard.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.
+ */
+/**
+ * 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): string;
+/** Normalize a locality name for address-point keying (fold only — no street semantics). */
+export declare function normalizeLocalityForKey(locality: string): string;
+/**
+ * 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-shard builder (`scripts/build-interpolation-shard.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 shard 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: string): string;
+//# sourceMappingURL=street-normalize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"street-normalize.d.ts","sourceRoot":"","sources":["../street-normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAuDH;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA6C5D;AAED,4FAA4F;AAC5F,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI/D"}