@mailwoman/resolver-wof-sqlite 2.1.0

package/out/fst-autocomplete.js

@@ -0,0 +1,124 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FST-based autocomplete. Prefix walk + BFS expansion to collect ranked place suggestions. O(depth
+ *   × branching) — the FST IS the autocomplete index.
+ *
+ *   Two query shapes are handled (the FST is a trie over normalized WORD tokens):
+ *
+ *   - COMPLETE tokens ("new york") — `walk` lands on a state; collect its accepting entries + BFS a
+ *       couple tokens past it for nearby completions. This is the CLI's "complete a place word"
+ *       path.
+ *   - A PARTIAL last token ("new yor", "chic") — `walk` fails (there is no "yor" edge, only "york"). So
+ *       walk the complete prefix, then complete the partial token by prefix-filtering the
+ *       continuation edges (`token.startsWith(partial)`). This is what a char-level typeahead
+ *       needs; without it "new yor" returns nothing useful. (#587)
+ */
+import { FstMatcher, normalizeTokens } from "./fst-matcher.js";
+/** Max accepting entries collected per BFS branch — keeps one dense branch from starving the search. */
+const PER_BRANCH = 4;
+/**
+ * The top-`k` entries by importance (descending). Avoids sorting/allocating when `entries` is
+ * small.
+ */
+function topByImportance(entries, k) {
+    if (entries.length <= k)
+        return [...entries];
+    return [...entries].sort((a, b) => b.importance - a.importance).slice(0, k);
+}
+/**
+ * Autocomplete from the current prefix. Returns suggestions ranked importance-descending.
+ */
+export function autocomplete(fst, query, opts = {}) {
+    const maxSuggestions = opts.maxSuggestions ?? 10;
+    const maxExpansionDepth = opts.maxExpansionDepth ?? 2;
+    const normalizedTokens = normalizeTokens(query);
+    if (normalizedTokens.length === 0) {
+        return { query, normalizedTokens: [], depth: 0, suggestions: [] };
+    }
+    const seen = new Map();
+    const queue = [];
+    let depth = 0;
+    const match = fst.walk(normalizedTokens);
+    if (match) {
+        // COMPLETE-token prefix landed on a state. Seed at the match state (accepting + continuations).
+        depth = match.depth;
+        for (const entry of fst.accepting(match.stateId))
+            addSuggestion(seen, entry, match.depth, []);
+        for (const cont of fst.continuations(match.stateId)) {
+            queue.push({ stateId: cont.targetState, depth: 1, tokens: [cont.token] });
+        }
+    }
+    else {
+        // PARTIAL last token — walk the complete prefix, complete the partial by prefix-filtering edges.
+        const complete = normalizedTokens.slice(0, -1);
+        const partial = normalizedTokens[normalizedTokens.length - 1];
+        const prefixState = complete.length === 0 ? 0 : (fst.walk(complete)?.stateId ?? undefined);
+        if (prefixState === undefined) {
+            return { query, normalizedTokens, depth: 0, suggestions: [] };
+        }
+        depth = complete.length;
+        for (const cont of fst.continuations(prefixState)) {
+            if (!cont.token.startsWith(partial))
+                continue;
+            // This edge completes the typed partial token — its target is a real match at depth+1.
+            for (const entry of topByImportance(fst.accepting(cont.targetState), PER_BRANCH))
+                addSuggestion(seen, entry, complete.length + 1, [cont.token]);
+            // BFS a little past it too (multi-token completions: "new yor" → "New York Mills").
+            queue.push({ stateId: cont.targetState, depth: 1, tokens: [cont.token] });
+        }
+    }
+    // BFS expansion (shared by both paths) — find nearby completions up to maxExpansionDepth. Each
+    // branch contributes only its top PER_BRANCH places: a state like "new london" has dozens of
+    // accepting entries and would otherwise blow the budget before the BFS ever reaches "new york"
+    // (the "new" state has 311 continuations). Per-branch capping keeps the search broad. (#587)
+    while (queue.length > 0 && seen.size < maxSuggestions * 4) {
+        const item = queue.shift();
+        if (item.depth > maxExpansionDepth)
+            continue;
+        for (const entry of topByImportance(fst.accepting(item.stateId), PER_BRANCH))
+            addSuggestion(seen, entry, depth + item.depth, item.tokens);
+        if (item.depth < maxExpansionDepth) {
+            for (const cont of fst.continuations(item.stateId)) {
+                queue.push({ stateId: cont.targetState, depth: item.depth + 1, tokens: [...item.tokens, cont.token] });
+            }
+        }
+    }
+    let suggestions = [...seen.values()].sort((a, b) => b.importance - a.importance);
+    if (opts.dedupeByName)
+        suggestions = dedupeByName(suggestions);
+    return { query, normalizedTokens, depth, suggestions: suggestions.slice(0, maxSuggestions) };
+}
+function addSuggestion(seen, entry, matchDepth, completionTokens) {
+    const existing = seen.get(entry.wofID);
+    if (existing && existing.matchDepth <= matchDepth)
+        return;
+    seen.set(entry.wofID, {
+        name: entry.name,
+        placetype: entry.placetype,
+        importance: entry.importance,
+        wofID: entry.wofID,
+        parentChain: entry.parentChain,
+        matchDepth,
+        completionTokens: [...completionTokens],
+    });
+}
+/**
+ * Keep one suggestion per name — the highest-importance. Input is already importance-sorted, so the
+ * first occurrence per name wins; order is preserved.
+ */
+function dedupeByName(suggestions) {
+    const seenNames = new Set();
+    const out = [];
+    for (const s of suggestions) {
+        const key = s.name.toLowerCase();
+        if (seenNames.has(key))
+            continue;
+        seenNames.add(key);
+        out.push(s);
+    }
+    return out;
+}
+//# sourceMappingURL=fst-autocomplete.js.map

package/out/fst-autocomplete.js.map

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

package/out/fst-builder.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build an FST (finite-state transducer) from a WOF SQLite database. The FST maps normalized token
+ *   sequences to PlaceEntry arrays, pre-computing the valid interpretations for every prefix of
+ *   every place name in the gazetteer.
+ *
+ *   Build pipeline: open WOF DB → query spr + names → normalize names → insert into trie → attach
+ *   PlaceEntry at terminals → return FstMatcher.
+ */
+import { FstMatcher } from "./fst-matcher.js";
+import type { BuildFstOpts, BuildFstResult, FstProvenance } from "./fst-types.js";
+export declare function buildFstFromWof(opts: BuildFstOpts): {
+    matcher: FstMatcher;
+    provenance: FstProvenance;
+    result: BuildFstResult;
+};
+//# sourceMappingURL=fst-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fst-builder.d.ts","sourceRoot":"","sources":["../fst-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAA2B,MAAM,gBAAgB,CAAA;AAmC1G,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG;IACpD,OAAO,EAAE,UAAU,CAAA;IACnB,UAAU,EAAE,aAAa,CAAA;IACzB,MAAM,EAAE,cAAc,CAAA;CACtB,CA6MA"}

package/out/fst-builder.js

@@ -0,0 +1,219 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build an FST (finite-state transducer) from a WOF SQLite database. The FST maps normalized token
+ *   sequences to PlaceEntry arrays, pre-computing the valid interpretations for every prefix of
+ *   every place name in the gazetteer.
+ *
+ *   Build pipeline: open WOF DB → query spr + names → normalize names → insert into trie → attach
+ *   PlaceEntry at terminals → return FstMatcher.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { FstMatcher, normalizeTokens } from "./fst-matcher.js";
+const DEFAULT_PLACETYPES = [
+    "country",
+    "region",
+    "county",
+    "locality",
+    "localadmin",
+    "borough",
+    "neighbourhood",
+];
+const DEFAULT_COUNTRIES = ["US"];
+const DEFAULT_LANGUAGES = ["eng", ""];
+export function buildFstFromWof(opts) {
+    const countries = opts.countries ?? DEFAULT_COUNTRIES;
+    const placetypes = opts.placetypes ?? DEFAULT_PLACETYPES;
+    const languages = opts.languages ?? DEFAULT_LANGUAGES;
+    const progress = opts.onProgress ?? (() => { });
+    progress("open", opts.dbPath);
+    const db = new DatabaseSync(opts.dbPath, { open: true });
+    // Phase 1: Load all matching SPR rows.
+    progress("spr", `Loading places for countries=[${countries}], placetypes=[${placetypes}]`);
+    const placeholders = (arr) => arr.map(() => "?").join(",");
+    const sprStmt = db.prepare(`SELECT id, name, placetype, parent_id, latitude, longitude
+		 FROM spr
+		 WHERE is_current = 1
+		   AND country IN (${placeholders(countries)})
+		   AND placetype IN (${placeholders(placetypes)})`);
+    const sprRows = sprStmt.all(...countries, ...placetypes);
+    progress("spr", `Loaded ${sprRows.length} places`);
+    // Phase 2: Build a lookup for parent chain resolution.
+    const sprByID = new Map();
+    for (const row of sprRows)
+        sprByID.set(row.id, row);
+    // Also load parent rows that might be outside our placetype filter (e.g., country for region).
+    const parentStmt = db.prepare("SELECT id, name, placetype, parent_id, latitude, longitude FROM spr WHERE id = ?");
+    // Fallback: use ancestors table when parent_id is a sentinel (-1, -4, etc.).
+    let ancestorStmt = null;
+    try {
+        ancestorStmt = db.prepare(`SELECT DISTINCT ancestor_id FROM ancestors
+			 WHERE id = ? AND ancestor_placetype IN ('country', 'region', 'county')
+			 ORDER BY CASE ancestor_placetype
+			   WHEN 'county' THEN 1
+			   WHEN 'region' THEN 2
+			   WHEN 'country' THEN 3
+			 END`);
+    }
+    catch {
+        progress("ancestors", "No ancestors table — sentinel parent_ids will produce empty chains");
+    }
+    function resolveParentChain(id) {
+        const row = sprByID.get(id);
+        if (!row)
+            return [];
+        // If parent_id is a sentinel (≤ 0), use ancestors table.
+        if (row.parent_id <= 0 && ancestorStmt) {
+            const ancestors = ancestorStmt.all(id);
+            return ancestors.map((a) => a.ancestor_id).filter((aid) => aid !== id);
+        }
+        // Normal case: walk parent_id chain.
+        const chain = [];
+        let current = row.parent_id;
+        const seen = new Set([id]);
+        while (current > 0 && !seen.has(current)) {
+            seen.add(current);
+            chain.push(current);
+            let parentRow = sprByID.get(current);
+            if (!parentRow) {
+                const fetched = parentStmt.get(current);
+                if (!fetched)
+                    break;
+                parentRow = fetched;
+                sprByID.set(current, parentRow);
+            }
+            if (parentRow.parent_id > 0 && parentRow.parent_id !== current) {
+                current = parentRow.parent_id;
+            }
+            else {
+                break;
+            }
+        }
+        return chain;
+    }
+    // Phase 3: Load importance data (Wikipedia-based, falls back to population-scaled).
+    // See docs/articles/concepts/importance-vs-population.md for the two-signal contract.
+    progress("importance", "Loading importance data");
+    const importanceMap = new Map();
+    try {
+        const impStmt = db.prepare("SELECT id, importance FROM place_importance");
+        const impRows = impStmt.all();
+        for (const row of impRows)
+            importanceMap.set(row.id, row.importance);
+        progress("importance", `Loaded ${importanceMap.size} importance scores`);
+    }
+    catch {
+        progress("importance", "No place_importance table — falling back to population");
+        try {
+            const popStmt = db.prepare("SELECT id, population FROM place_population");
+            const popRows = popStmt.all();
+            for (const row of popRows) {
+                const normalized = row.population > 0 ? Math.min(1.0, Math.log2(1 + row.population / 1000) / 14) : 0;
+                importanceMap.set(row.id, normalized);
+            }
+        }
+        catch {
+            progress("importance", "No place_population either — using 0 for all");
+        }
+    }
+    // Phase 4: Load names for matching places.
+    progress("names", "Loading name variants");
+    const placeIds = sprRows.map((r) => r.id);
+    const namesByPlace = new Map();
+    const allLanguages = languages.includes("*");
+    for (let i = 0; i < placeIds.length; i += 500) {
+        const chunk = placeIds.slice(i, i + 500);
+        const idPlaceholders = chunk.map(() => "?").join(",");
+        const nameStmt = allLanguages
+            ? db.prepare(`SELECT id, name, language, privateuse FROM names WHERE id IN (${idPlaceholders})`)
+            : db.prepare(`SELECT id, name, language, privateuse FROM names WHERE id IN (${idPlaceholders}) AND language IN (${languages.map(() => "?").join(",")})`);
+        const nameRows = (allLanguages
+            ? nameStmt.all(...chunk)
+            : nameStmt.all(...chunk, ...languages));
+        for (const row of nameRows) {
+            const existing = namesByPlace.get(row.id) ?? [];
+            if (!existing.includes(row.name))
+                existing.push(row.name);
+            namesByPlace.set(row.id, existing);
+        }
+    }
+    progress("names", `Loaded names for ${namesByPlace.size} places`);
+    // Phase 5: Build the trie.
+    progress("trie", "Building trie");
+    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;
+        }
+        // Deduplicate: don't add the same wofID twice at the same state.
+        const existing = nodes[stateId].places;
+        if (!existing.some((p) => p.wofID === entry.wofID && p.placetype === entry.placetype)) {
+            existing.push(entry);
+        }
+    }
+    let insertCount = 0;
+    for (const row of sprRows) {
+        const parentChain = resolveParentChain(row.id);
+        const entry = {
+            wofID: row.id,
+            placetype: row.placetype,
+            name: row.name,
+            parentChain,
+            importance: importanceMap.get(row.id) ?? 0,
+            lat: row.latitude,
+            lon: row.longitude,
+        };
+        // Insert the primary name from spr.
+        const primaryTokens = normalizeTokens(row.name);
+        insertName(primaryTokens, entry);
+        insertCount++;
+        // Insert alt names from the names table.
+        const altNames = namesByPlace.get(row.id) ?? [];
+        for (const altName of altNames) {
+            if (altName === row.name)
+                continue;
+            const altTokens = normalizeTokens(altName);
+            if (altTokens.length > 0 && altTokens.join(" ") !== primaryTokens.join(" ")) {
+                insertName(altTokens, entry);
+                insertCount++;
+            }
+        }
+    }
+    db.close();
+    progress("done", `Built trie: ${nodes.length} states, ${insertCount} name insertions`);
+    const edgeCount = nodes.reduce((sum, n) => sum + n.edges.size, 0);
+    const matcher = FstMatcher.fromNodes(nodes);
+    const provenance = {
+        builtAt: new Date().toISOString(),
+        countries,
+        stateCount: nodes.length,
+        placeCount: sprRows.length,
+        edgeCount,
+        nameInsertions: insertCount,
+        importanceMatches: importanceMap.size,
+        sourceDb: opts.dbPath,
+    };
+    return {
+        matcher,
+        provenance,
+        result: {
+            stateCount: nodes.length,
+            placeCount: sprRows.length,
+            edgeCount,
+            tokenCount: insertCount,
+        },
+    };
+}
+//# sourceMappingURL=fst-builder.js.map

package/out/fst-builder.js.map

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

package/out/fst-deserialize-web.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-compatible FST deserializer. Uses DataView + TextDecoder instead of Node's Buffer so the
+ *   same binary format can be loaded in the browser via fetch(url).then(r => r.arrayBuffer()).
+ *
+ *   This is a read-only counterpart to fst-serialize.ts — serialization stays Node-only (it's a
+ *   build-time operation).
+ */
+import { FstMatcher } from "./fst-matcher.js";
+import type { FstProvenance } from "./fst-types.js";
+export declare function deserializeFstWeb(input: ArrayBuffer | Uint8Array): FstMatcher;
+export declare function readFstProvenanceWeb(input: ArrayBuffer | Uint8Array): FstProvenance | undefined;
+//# sourceMappingURL=fst-deserialize-web.d.ts.map

package/out/fst-deserialize-web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fst-deserialize-web.d.ts","sourceRoot":"","sources":["../fst-deserialize-web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAA2B,MAAM,gBAAgB,CAAA;AAsB5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CA+F7E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAiB/F"}

package/out/fst-deserialize-web.js

@@ -0,0 +1,133 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Browser-compatible FST deserializer. Uses DataView + TextDecoder instead of Node's Buffer so the
+ *   same binary format can be loaded in the browser via fetch(url).then(r => r.arrayBuffer()).
+ *
+ *   This is a read-only counterpart to fst-serialize.ts — serialization stays Node-only (it's a
+ *   build-time operation).
+ */
+import { FstMatcher } from "./fst-matcher.js";
+const HEADER_SIZE = 32;
+const EDGE_ENTRY_SIZE = 8;
+const PLACE_ENTRY_SIZE = 56;
+const MAGIC_BYTES = [0x46, 0x53, 0x54, 0x00]; // "FST\0"
+const MAX_VERSION = 2;
+const PLACETYPE_ORDER = [
+    "country",
+    "region",
+    "county",
+    "locality",
+    "localadmin",
+    "borough",
+    "neighbourhood",
+    "postalcode",
+    "campus",
+    "dependency",
+    "street_affix",
+];
+export function deserializeFstWeb(input) {
+    const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const decoder = new TextDecoder("utf-8");
+    if (bytes.byteLength < HEADER_SIZE)
+        throw new Error("FST buffer too small for header");
+    if (bytes[0] !== MAGIC_BYTES[0] ||
+        bytes[1] !== MAGIC_BYTES[1] ||
+        bytes[2] !== MAGIC_BYTES[2] ||
+        bytes[3] !== MAGIC_BYTES[3]) {
+        throw new Error("FST magic mismatch");
+    }
+    const version = view.getUint16(4, true);
+    if (version < 1 || version > MAX_VERSION) {
+        throw new Error(`FST version ${version} unsupported (expected 1..${MAX_VERSION})`);
+    }
+    const isV2 = version >= 2;
+    const stateCount = view.getUint32(8, true);
+    const edgeCount = view.getUint32(12, true);
+    const _placeCount = view.getUint32(16, true);
+    const stringCount = view.getUint32(20, true);
+    const stringBytes = view.getUint32(24, true);
+    let pos = HEADER_SIZE;
+    // --- String table ---
+    const strOffsets = new Uint32Array(stringCount + 1);
+    for (let i = 0; i <= stringCount; i++) {
+        strOffsets[i] = view.getUint32(pos, true);
+        pos += 4;
+    }
+    const strDataStart = pos;
+    const strings = new Array(stringCount);
+    for (let i = 0; i < stringCount; i++) {
+        const start = strDataStart + strOffsets[i];
+        const end = strDataStart + strOffsets[i + 1];
+        strings[i] = decoder.decode(bytes.subarray(start, end));
+    }
+    pos += stringBytes;
+    // --- State table ---
+    const stateEntrySize = version >= 4 ? 16 : 12;
+    const stateTableStart = pos;
+    const edgeTableStart = stateTableStart + stateCount * stateEntrySize;
+    const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE;
+    const nodes = new Array(stateCount);
+    for (let si = 0; si < stateCount; si++) {
+        const sp = stateTableStart + si * stateEntrySize;
+        const edgeStart = view.getUint32(sp, true);
+        const placeStart = view.getUint32(sp + 4, true);
+        const edgeCountForState = version >= 4 ? view.getUint32(sp + 8, true) : view.getUint16(sp + 8, true);
+        const placeCountForState = version >= 4 ? view.getUint32(sp + 12, true) : view.getUint16(sp + 10, true);
+        const edges = new Map();
+        for (let ei = 0; ei < edgeCountForState; ei++) {
+            const ep = edgeTableStart + (edgeStart + ei) * EDGE_ENTRY_SIZE;
+            const stringIdx = view.getUint32(ep, true);
+            const target = view.getUint32(ep + 4, true);
+            edges.set(strings[stringIdx], target);
+        }
+        const places = new Array(placeCountForState);
+        for (let pi = 0; pi < placeCountForState; pi++) {
+            const pp = placeTableStart + (placeStart + pi) * PLACE_ENTRY_SIZE;
+            const chainLen = view.getUint8(pp + 5);
+            const parentChain = [];
+            for (let ci = 0; ci < chainLen; ci++) {
+                parentChain.push(view.getUint32(pp + 24 + ci * 4, true));
+            }
+            const rawImportance = isV2
+                ? view.getFloat32(pp + 12, true)
+                : Math.min(1.0, Math.log2(1 + view.getUint32(pp + 12, true) / 1000) / 14);
+            places[pi] = {
+                wofID: view.getUint32(pp, true),
+                placetype: PLACETYPE_ORDER[view.getUint8(pp + 4)] ?? "locality",
+                name: strings[view.getUint32(pp + 8, true)],
+                importance: rawImportance,
+                lat: view.getFloat32(pp + 16, true),
+                lon: view.getFloat32(pp + 20, true),
+                parentChain,
+            };
+        }
+        nodes[si] = { edges, places };
+    }
+    return FstMatcher.fromNodes(nodes);
+}
+export function readFstProvenanceWeb(input) {
+    const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const decoder = new TextDecoder("utf-8");
+    if (bytes.byteLength < HEADER_SIZE)
+        return undefined;
+    const version = view.getUint16(4, true);
+    if (version < 3)
+        return undefined;
+    const provenanceOffset = view.getUint32(28, true);
+    if (provenanceOffset === 0 || provenanceOffset >= bytes.byteLength)
+        return undefined;
+    try {
+        const jsonLen = view.getUint32(provenanceOffset, true);
+        const jsonStr = decoder.decode(bytes.subarray(provenanceOffset + 4, provenanceOffset + 4 + jsonLen));
+        return JSON.parse(jsonStr);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=fst-deserialize-web.js.map

package/out/fst-deserialize-web.js.map

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

package/out/fst-matcher.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   In-memory FST matcher. Built by `fst-builder.ts`, queried at runtime for emission priors and CLI
+ *   introspection. The structure is a deterministic trie over normalized tokens with PlaceEntry
+ *   arrays at accepting states.
+ */
+import type { FstContinuation, FstMatchResult, FstQueryResult, PlaceEntry } from "./fst-types.js";
+interface FstNode {
+    edges: Map<string, number>;
+    places: PlaceEntry[];
+}
+export declare class FstMatcher {
+    private nodes;
+    constructor(nodes: FstNode[]);
+    get stateCount(): number;
+    get placeCount(): number;
+    walk(tokens: string[]): FstMatchResult | null;
+    walkFrom(prev: FstMatchResult, token: string): FstMatchResult | null;
+    accepting(stateId: number): PlaceEntry[];
+    continuations(stateId: number): FstContinuation[];
+    query(text: string): FstQueryResult;
+    get nodeCount(): number;
+    /** Expose the internal node array for serialization. */
+    toNodes(): readonly FstNode[];
+    static fromNodes(nodes: FstNode[]): FstMatcher;
+}
+/** Normalize text into FST tokens: lowercase, NFKC, strip punctuation, split on whitespace. */
+export declare function normalizeTokens(text: string): string[];
+export type { FstNode };
+//# sourceMappingURL=fst-matcher.d.ts.map

package/out/fst-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fst-matcher.d.ts","sourceRoot":"","sources":["../fst-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEjG,UAAU,OAAO;IAChB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1B,MAAM,EAAE,UAAU,EAAE,CAAA;CACpB;AAED,qBAAa,UAAU;IACtB,OAAO,CAAC,KAAK,CAAW;gBAEZ,KAAK,EAAE,OAAO,EAAE;IAI5B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,UAAU,IAAI,MAAM,CAIvB;IAED,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,IAAI;IAa7C,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IASpE,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAIxC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE;IAejD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IA8BnC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wDAAwD;IACxD,OAAO,IAAI,SAAS,OAAO,EAAE;IAI7B,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,UAAU;CAG9C;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOtD;AAED,YAAY,EAAE,OAAO,EAAE,CAAA"}