@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/fst/types.d.ts

@@ -2,63 +2,58 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Types for the FST gazetteer language model. The FST maps token sequences (place names) to
- *   (placetype, wof_id, parent_chain) entries — pre-computing the valid interpretations for each
- *   prefix of every place name in the gazetteer.
+ * @file Types for the FST gazetteer. These types map place-name token sequences to place entries.
  */
 import type { PathBuilderLike } from "path-ts";
+/**
+ * One place that a token sequence in the FST accepts.
+ */
 export interface PlaceEntry {
     wofID: number;
     placetype: PlacetypeID;
     name: string;
     parentChain: number[];
     /**
-     * REFERENTIAL likelihood in [0, 1] — population-anchored (`referentialFromPopulation`), and the ONLY score the
-     * decoder bias is allowed to read (ROAD_TO_V9 §2, ratified 2026-08-06).
-     *
-     * This field was called `importance` through format v4, where it carried whichever score the source database happened
-     * to hold: the population proxy on a database with no `place_importance` table (which is every shipped
-     * `fst-per-locale` binary), the Wikipedia score where the concordance join landed otherwise. The rename is the point
-     * — a v4 artifact's value is a CONFLATION that cannot be told apart after the fact, which is why `fst-freshness.ts`
-     * reports anything below {@link FST_FORMAT_VERSION} as format-stale rather than reading it as referential.
+     * The population-based referential likelihood in [0, 1] that the decoder bias uses.
      */
     referential: number;
     /**
-     * Encyclopedic (Wikipedia) importance in [0, 1], fan-out-guarded per #1497. Carried for consumers that want to
-     * DISPLAY salience; never read by the decoder or by any ranking.
-     *
-     * `undefined` = this place has no encyclopedic signal, or the artifact predates format 5. NEVER conflate either with
-     * 0 — the meaning-of-zero rule; roughly 89% of the 2026-08-05 gazetteer's rows have no Wikipedia article at all.
+     * The encyclopedic importance in [0, 1], for display only.
+     * It is `null` when unavailable.
      */
-    encyclopedic?: number;
+    encyclopedic: number | null;
     lat: number;
     lon: number;
     /**
-     * Surface-ambiguity class (survey #4): how many DISTINCT countries carry a place with THIS entry's accepting surface,
-     * counted over the whole admin DB at build time (clamped to 255). A property of the surface, not the place — the same
-     * place reached via different alias surfaces reports each surface's own count. `undefined` = built without ambiguity
-     * data (pre-2026-07-27 artifacts) — NEVER conflate with 1 (the unambiguous case); the meaning-of-zero rule.
+     * The number of countries with a place of this surface, clamped to 255.
+     * It is `null` when unavailable.
      */
-    crossCountryBranches?: number;
+    crossCountryBranches: number | null;
 }
+/**
+ * The placetypes the FST stores.
+ */
 export type PlacetypeID = "country" | "region" | "county" | "locality" | "localadmin" | "borough" | "neighbourhood" | "postalcode" | "campus" | "dependency" | "street_affix";
-export interface FSTMatchResult {
-    stateID: number;
-    accepted: boolean;
-    depth: number;
-}
+/**
+ * One outgoing edge from an FST state, with the number of places its target state accepts.
+ */
 export interface FSTContinuation {
     token: string;
     targetState: number;
     acceptingCount: number;
 }
+/**
+ * The places a token path accepts and the tokens that can extend it.
+ */
 export interface FSTQueryResult {
     path: string[];
     stateID: number;
     accepting: PlaceEntry[];
     continuations: FSTContinuation[];
 }
+/**
+ * The build metadata stored in an FST binary's provenance trailer.
+ */
 export interface FSTProvenance {
     builtAt: string;
     countries: string[];
@@ -67,56 +62,61 @@ export interface FSTProvenance {
     edgeCount: number;
     nameInsertions: number;
     /**
-     * How many places carried a non-zero REFERENTIAL score at build time. Named `importanceMatches` for stamp
-     * compatibility with every artifact written before the two-score split — renaming the JSON key would make every
-     * existing stamp unreadable, and the number means the same thing it always did on a population-built artifact.
+     * The count of places with a non-zero referential score at build time.
+     *
+     * The key keeps its older name so that existing provenance stamps stay readable.
      */
     importanceMatches: number;
     /**
-     * How many places carried an ENCYCLOPEDIC score at build time. `undefined` on a pre-split build — which is not the
-     * same as 0 (a v5 build against a population-only database), so the freshness report says the two in different
-     * words.
+     * The count of places with an encyclopedic score at build time.
+     *
+     * It is `null` for a build that predates the separate encyclopedic score.
+     * The value `0` means a current build used a database without encyclopedic scores.
      */
-    encyclopedicMatches?: number;
+    encyclopedicMatches: number | null;
     /**
-     * How the builder obtained its two scores — an {@link ImportanceSplitSource}. Recorded so an artifact states, in its
-     * own provenance, whether its encyclopedic channel is real, reconstructed from a legacy conflated column, or absent.
+     * The {@link ImportanceSplitSource} that records whether the encyclopedic score is real,
+     * reconstructed from a legacy column, or absent.
      */
-    importanceSource?: string;
-    sourceDB?: string;
+    importanceSource: string | null;
+    sourceDB: string | null;
     /**
-     * MD5 of the source database's bytes at build time — the artifact's link to the gazetteer it is a projection of.
+     * The MD5 of the source database's bytes at build time.
+     * The freshness check compares it.
      *
-     * `sourceDB` records the PATH, which is exactly the field that cannot change when the bytes behind it do: the admin
-     * DB is a sealed readonly artifact that a rebuild REPLACES in place, so every FST built before the 2026-08-04 swap
-     * still names the current file and none of them was built from it. Compared by `fst-freshness.ts`.
+     * `sourceDB` by itself cannot detect staleness.
+     * A rebuild replaces the admin database at the same path.
      *
-     * `undefined` = built before the stamp existed (every artifact predating 2026-08-05). NEVER conflate that with "built
-     * from a database whose md5 is unknown" — the freshness check reports the two in different words.
+     * The field is `null` for artifacts built before the stamp existed.
+     * An unknown digest has a different value.
      */
-    sourceDBMD5?: string;
+    sourceDBMD5: string | null;
     /**
-     * Byte size of the source database at build time. Not redundant with {@link FSTProvenance.sourceDBMD5}: it survives a
-     * truncated source and it is what makes a staleness warning legible — "5,273,722,880 → 5,372,076,032" names the
-     * rebuild, a hex delta does not.
+     * The byte size of the source database at build time.
+     *
+     * It detects a truncated source and makes a staleness warning readable.
      */
-    sourceDBBytes?: number;
-    modelCardVersion?: string;
+    sourceDBBytes: number | null;
+    modelCardVersion: string | null;
     /**
-     * Degenerate-surface curation policy applied at build time (absent = uncurated build).
+     * The surface-exclusion policy applied at build time.
+     * It is absent for an uncurated build.
      */
-    exclusionPolicy?: string;
+    exclusionPolicy: string | null;
     /**
-     * Name insertions refused by the curation policy.
+     * The count of name insertions the exclusion policy rejected.
      */
-    excludedInsertions?: number;
+    excludedInsertions: number | null;
 }
+/**
+ * Options for building an FST from a WOF admin database.
+ */
 export interface BuildFSTOpts {
     dbPath: PathBuilderLike;
     /**
-     * Pre-computed identity of `dbPath` to stamp into provenance. Omit and the builder reads it via
-     * `readWOFSourceIdentity` (sidecar-cached). Supply it when the digest is already in hand, or when the caller is
-     * building from something whose identity it defines itself.
+     * The precomputed identity of `dbPath` to record in provenance.
+     *
+     * When omitted, the builder reads it with `readWOFSourceIdentity`, which caches it in a sidecar file.
      */
     sourceIdentity?: {
         md5: string;
@@ -126,35 +126,39 @@ export interface BuildFSTOpts {
     placetypes?: PlacetypeID[];
     languages?: string[];
     /**
-     * Degenerate-surface curation (build-time; the ASR-contextual-biasing "prune the bias list" discipline). A name whose
-     * FULL normalized token sequence joins to a member of this set is never inserted — the surface carries no
-     * discriminative value as a bias key (bare function words: "la"; bare street-type words: "boulevard"). The FST is a
-     * bias list, not the gazetteer of record — the resolver's candidate tables are untouched, so excluded places stay
-     * findable; they just stop nudging the decoder on degenerate keys. Keys must be `normalizeTokens(...).join(" ")`.
+     * Surfaces the builder never inserts, such as the bare function word "la"
+     * or the bare street type "boulevard".
+     *
+     * These surfaces do not discriminate between places when used as decoder bias keys.
+     * The resolver's candidate tables still hold the excluded places.
+     * Keys must be `normalizeTokens(...).join(" ")`.
      */
     excludeSurfaces?: ReadonlySet<string>;
     /**
-     * Compositional clause of the same policy: refuse a name whose EVERY normalized token is a member (e.g. "de la") — a
-     * surface made entirely of function words cannot be discriminative. Source this from stopwords only, never
-     * street-type words ("Avenue Road" is a real name; "de la" is not).
+     * Tokens that a name must not consist of entirely, such as "de la".
+     *
+     * Build this set from stopwords only.
+     * A street-type word can be part of a real name, as in "Avenue Road".
      */
     excludeAllTokensOf?: ReadonlySet<string>;
     /**
-     * Recorded verbatim into provenance when either exclusion set is supplied.
+     * The policy label recorded in provenance when either exclusion set is supplied.
      */
     exclusionPolicy?: string;
     /**
-     * Surface-ambiguity classes (survey #4, 2026-07-27): normalized-join surface → the number of DISTINCT countries
-     * (across the WHOLE admin DB, not just this build's country scope) with a place carrying that surface. When supplied,
-     * every inserted place row records the count for ITS accepting surface (`PlaceEntry.crossCountryBranches`) — an entry
-     * accessible under several surfaces records each surface's own count. Serialized into the place row's former `_pad`
-     * byte with presence signaled by header flags bit0, so VERSION stays put and pre-ambiguity artifacts read as "no
-     * data" (never "0 branches" — the meaning-of-zero rule). No decoder consumes it yet; consumers (FST-prior tempering,
-     * the Option-A evidence channel) arrive behind their own measured checks.
+     * Maps each normalized surface to the number of distinct countries in the whole
+     * admin database with a place of that surface.
+     *
+     * When supplied, each inserted place entry records the count for its accepting
+     * surface as `PlaceEntry.crossCountryBranches`.
+     * A place reachable under several surfaces records each surface's own count.
      */
     surfaceCountryCounts?: ReadonlyMap<string, number>;
     onProgress?: (phase: string, detail?: string) => void;
 }
+/**
+ * Counts reported by an FST build.
+ */
 export interface BuildFSTResult {
     stateCount: number;
     placeCount: number;

package/out/fst/types.d.ts.map

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

package/out/fst/types.js

@@ -2,10 +2,7 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Types for the FST gazetteer language model. The FST maps token sequences (place names) to
- *   (placetype, wof_id, parent_chain) entries — pre-computing the valid interpretations for each
- *   prefix of every place name in the gazetteer.
+ * @file Types for the FST gazetteer. These types map place-name token sequences to place entries.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/out/fst/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../lib/fst/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../lib/fst/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/out/{fst/index.js → fst.d.ts}

@@ -10,5 +10,6 @@ export * from "#fst/format";
 export * from "#fst/freshness";
 export * from "#fst/matcher";
 export * from "#fst/serialize";
+export { FST_FORMAT_VERSION } from "#fst/format";
 export * from "#fst/types";
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=fst.d.ts.map

package/out/fst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fst.d.ts","sourceRoot":"","sources":["../lib/fst.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,cAAc,YAAY,CAAA"}

package/out/{fst/index.d.ts → fst.js}

@@ -10,5 +10,6 @@ export * from "#fst/format";
 export * from "#fst/freshness";
 export * from "#fst/matcher";
 export * from "#fst/serialize";
+export { FST_FORMAT_VERSION } from "#fst/format";
 export * from "#fst/types";
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=fst.js.map

package/out/fst.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fst.js","sourceRoot":"","sources":["../lib/fst.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,cAAc,YAAY,CAAA"}

package/out/fts/query.d.ts

@@ -3,37 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Query shaping for the FTS5 lookup: placetype normalization and the MATCH-expression sanitizer.
- *   Both turn a caller's loose input into something SQLite's FTS5 parser accepts without throwing —
- *   an unescaped quote or a bare `*` is a syntax error, not an empty result.
+ * Query shaping for the FTS5 lookup: placetype normalization and the match-expression sanitizer.
  */
 import type { FindPlaceQuery, WOFPlacetype } from "#types";
 export declare function normalizePlacetypes(p: FindPlaceQuery["placetype"]): WOFPlacetype[] | null;
 /**
- * Make an arbitrary user-typed string safe for FTS5 MATCH.
- *
- * FTS5 has its own query syntax (`"phrase"`, `term1 OR term2`, `prefix*`, NEAR/N, etc.). Letting raw user input through
- * means a user typing `Paris's` or `St. (Petersburg)` causes a syntax error.
- *
- * Per-token rules:
- *
- * - Strip all punctuation except trailing `*` from each whitespace-separated token.
- * - **Trailing `*`** is preserved as FTS5 **prefix syntax** — `627*` becomes the literal `627*` (unquoted). The caller
- *   signaled they want a prefix; respect that.
- * - All other tokens are wrapped in `"..."` as a single-word phrase. Conservative — handles apostrophes, parens, accented
- *   input, etc. safely.
- * - Multiple tokens join with implicit AND.
- *
- * Examples:
- *
- * - `"Paris"` → `"Paris"` (phrase)
- * - `"627*"` → `627*` (prefix)
- * - `"St. (Petersburg)"` → `"St" "Petersburg"` (two phrases, AND-joined)
- * - `"Thiron-Gardais"` → `"Thiron" "Gardais"` (intra-token punctuation SPLITS — #945; fusing to `ThironGardais` matched
- *   nothing because the FTS doc tokenizes the hyphenated name as two terms)
- * - `"110 00"` with `fuseTokens` (postcode-typed) → `"110" "00"` per-token fused — the #920 name law
- * - `"Pari* TX"` → `Pari* "TX"` (mixed prefix + phrase)
- * - `"*"` alone → `""` (no body → drop)
+ * Make an arbitrary user-typed string safe for FTS5 match.
  */
 export declare function sanitizeFTSQuery(text: string, opts?: {
     fuseTokens?: boolean;

package/out/fts/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../lib/fts/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAE1D,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG,YAAY,EAAE,GAAG,IAAI,CAIzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAuCtF"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../lib/fts/query.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAE1D,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC,WAAW,CAAC,GAAG,YAAY,EAAE,GAAG,IAAI,CAIzF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAiCtF"}

package/out/fts/query.js

@@ -3,9 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Query shaping for the FTS5 lookup: placetype normalization and the MATCH-expression sanitizer.
- *   Both turn a caller's loose input into something SQLite's FTS5 parser accepts without throwing —
- *   an unescaped quote or a bare `*` is a syntax error, not an empty result.
+ * Query shaping for the FTS5 lookup: placetype normalization and the match-expression sanitizer.
  */
 export function normalizePlacetypes(p) {
     if (!p)
@@ -13,30 +11,7 @@ export function normalizePlacetypes(p) {
     return Array.isArray(p) ? p : [p];
 }
 /**
- * Make an arbitrary user-typed string safe for FTS5 MATCH.
- *
- * FTS5 has its own query syntax (`"phrase"`, `term1 OR term2`, `prefix*`, NEAR/N, etc.). Letting raw user input through
- * means a user typing `Paris's` or `St. (Petersburg)` causes a syntax error.
- *
- * Per-token rules:
- *
- * - Strip all punctuation except trailing `*` from each whitespace-separated token.
- * - **Trailing `*`** is preserved as FTS5 **prefix syntax** — `627*` becomes the literal `627*` (unquoted). The caller
- *   signaled they want a prefix; respect that.
- * - All other tokens are wrapped in `"..."` as a single-word phrase. Conservative — handles apostrophes, parens, accented
- *   input, etc. safely.
- * - Multiple tokens join with implicit AND.
- *
- * Examples:
- *
- * - `"Paris"` → `"Paris"` (phrase)
- * - `"627*"` → `627*` (prefix)
- * - `"St. (Petersburg)"` → `"St" "Petersburg"` (two phrases, AND-joined)
- * - `"Thiron-Gardais"` → `"Thiron" "Gardais"` (intra-token punctuation SPLITS — #945; fusing to `ThironGardais` matched
- *   nothing because the FTS doc tokenizes the hyphenated name as two terms)
- * - `"110 00"` with `fuseTokens` (postcode-typed) → `"110" "00"` per-token fused — the #920 name law
- * - `"Pari* TX"` → `Pari* "TX"` (mixed prefix + phrase)
- * - `"*"` alone → `""` (no body → drop)
+ * Make an arbitrary user-typed string safe for FTS5 match.
  */
 export function sanitizeFTSQuery(text, opts) {
     const out = [];
@@ -45,8 +20,7 @@ export function sanitizeFTSQuery(text, opts) {
         if (!trimmed)
             continue;
         const hasPrefixStar = trimmed.endsWith("*");
-        // #920 name law (postcode-typed queries ONLY): delete intra-token punctuation and FUSE the
-        // remainder — postal names are stored in this collapsed shape ("SW1A" stays one term).
+        // Fused mode deletes intra-token punctuation because postal names are stored in that collapsed shape.
         if (opts?.fuseTokens) {
             const body = trimmed.replaceAll(/[^\p{L}\p{N}]/gu, "");
             if (!body)
@@ -54,19 +28,14 @@ export function sanitizeFTSQuery(text, opts) {
             out.push(hasPrefixStar ? `${body}*` : `"${body.replaceAll('"', '""')}"`);
             continue;
         }
-        // Everything else SPLITS on intra-token punctuation — the behavior the docstring always
-        // promised ("St. (Petersburg)" → two phrases). The old code DELETED punctuation instead,
-        // fusing "Thiron-Gardais" into the unmatchable single term `ThironGardais` while the FTS
-        // doc holds two terms (#945 — the entire hyphenated-name class missed at the raw lookup;
-        // masked for years because pre-splice tokenizers never emitted hyphen-preserved values).
-        const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter((part) => part.length > 0);
+        const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter((part) => part.length);
         if (!parts.length)
             continue;
         for (let i = 0; i < parts.length; i++) {
             const body = parts[i].replaceAll("*", "");
             if (!body)
                 continue;
-            // The caller's trailing `*` applies to the FINAL part ("Thiron-Gard*" → "Thiron" Gard*).
+            // The caller's trailing `*` applies only to the final part.
             out.push(hasPrefixStar && i === parts.length - 1 ? `${body}*` : `"${body.replaceAll('"', '""')}"`);
         }
     }

package/out/fts/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../../lib/fts/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,UAAU,mBAAmB,CAAC,CAA8B;IACjE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAEnB,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAA+B;IAC7E,MAAM,GAAG,GAAa,EAAE,CAAA;IAExB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;QAE/B,IAAI,CAAC,OAAO;YAAE,SAAQ;QACtB,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;QAE3C,2FAA2F;QAC3F,uFAAuF;QACvF,IAAI,IAAI,EAAE,UAAU,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAA;YAEtD,IAAI,CAAC,IAAI;gBAAE,SAAQ;YACnB,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YAExE,SAAQ;QACT,CAAC;QAED,wFAAwF;QACxF,yFAAyF;QACzF,yFAAyF;QACzF,yFAAyF;QACzF,yFAAyF;QACzF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAEhF,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,SAAQ;QAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;YAE1C,IAAI,CAAC,IAAI;gBAAE,SAAQ;YACnB,yFAAyF;YACzF,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACnG,CAAC;IACF,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACrB,CAAC"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../lib/fts/query.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,UAAU,mBAAmB,CAAC,CAA8B;IACjE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAEnB,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAA+B;IAC7E,MAAM,GAAG,GAAa,EAAE,CAAA;IAExB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAA;QAE/B,IAAI,CAAC,OAAO;YAAE,SAAQ;QACtB,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;QAE3C,sGAAsG;QACtG,IAAI,IAAI,EAAE,UAAU,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAA;YAEtD,IAAI,CAAC,IAAI;gBAAE,SAAQ;YACnB,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YAExE,SAAQ;QACT,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAE5E,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,SAAQ;QAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;YAE1C,IAAI,CAAC,IAAI;gBAAE,SAAQ;YACnB,4DAA4D;YAC5D,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACnG,CAAC;IACF,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACrB,CAAC"}

package/out/fts.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { DatabaseClient } from "@mailwoman/sqlite/client";
+/**
+ * The name of the FTS5 virtual table that indexes WOF place names for `match` queries.
+ */
+export declare const PLACE_SEARCH_TABLE = "place_search";
+/**
+ * The separator between aliases in the `alt_names` bag.
+ * It stops a phrase query from matching across two aliases.
+ *
+ * FTS5 assigns positions only to tokens.
+ * Spaces and punctuation are not tokens and would leave the aliases adjacent,
+ * but unicode61 indexes the Private Use Area codepoint U+E000 as a token.
+ *
+ * Query sanitizers strip this character, so no user query can match the separator.
+ */
+export declare const ALIAS_SEPARATOR = "\uE000";
+/**
+ * Folds a query or name for exact-tier comparison by lowercasing, trimming
+ * and collapsing internal whitespace.
+ *
+ * Every exact-tier consumer uses this function, so its output compares equal to
+ * the aliases that {@link aliasBagExactMatch} parses.
+ */
+export declare function foldQueryText(input: string): string;
+/**
+ * Returns whether any alias in an `alt_names` bag exactly equals the folded query.
+ *
+ * A bag without {@link ALIAS_SEPARATOR} is a legacy space-joined bag without alias boundaries.
+ * For such a bag, the function checks word-bounded containment only when no candidate matched strictly.
+ *
+ * Containment by itself would promote fragments such as "York" inside "New York City".
+ *
+ * @param altNames The `alt_names` bag from `place_search`, or null when the row has no aliases.
+ * @param normalizedQuery The query folded by {@link foldQueryText}.
+ * @param anyStrictExact Whether any candidate already matched on its canonical name or region abbreviation.
+ * Only legacy bags use it.
+ */
+export declare function aliasBagExactMatch(altNames: string | null, normalizedQuery: string, anyStrictExact: boolean): boolean;
+/**
+ * The name of the R*Tree virtual table that indexes WOF place bounding boxes for bbox and proximity lookups.
+ */
+export declare const PLACE_BBOX_TABLE = "place_bbox";
+/**
+ * The name of the sparse table that stores `wof:population` per place.
+ *
+ * The lookup uses this value to apply the population ranking boost.
+ *
+ * A place without a row gets no boost and no penalty.
+ */
+export declare const PLACE_POPULATION_TABLE = "place_population";
+/**
+ * The name of the table of per-place `referential` and `encyclopedic` scores,
+ * built by `mailwoman gazetteer importance`.
+ *
+ * The lookup copies `encyclopedic` onto results without ranking by it.
+ * It refuses to read an older table with a single `importance` column.
+ */
+export declare const PLACE_IMPORTANCE_TABLE = "place_importance";
+/**
+ * The indexes a {@link buildPlaceSearchFTS} run built and their row counts.
+ */
+export interface BuildPlaceSearchFTSResult {
+    /**
+     * Whether this call built the FTS5 index.
+     * It is false when an existing index was kept.
+     */
+    created: boolean;
+    /**
+     * The row count of the `place_search` table after the call.
+     */
+    indexedRows: number;
+    /**
+     * Whether this call built the R*Tree bbox index.
+     * It is false when an existing index was kept.
+     */
+    bboxCreated: boolean;
+    /**
+     * The row count of the `place_bbox` R*Tree after the call.
+     */
+    bboxIndexedRows: number;
+    /**
+     * The wall-clock duration of the whole build in milliseconds.
+     */
+    durationMs: number;
+}
+/**
+ * Options for {@link buildPlaceSearchFTS}.
+ */
+export interface BuildPlaceSearchFTSOpts {
+    /**
+     * Whether to drop and rebuild existing `place_search` and `place_bbox` tables,
+     * such as after an `spr` or `names` update.
+     * By default an existing index is kept.
+     */
+    drop?: boolean;
+    /**
+     * Receives each build phase as it begins.
+     * A planet-scale build takes minutes to populate.
+     */
+    onProgress?: (phase: "checking" | "dropping" | "creating" | "populating" | "creating-bbox" | "populating-bbox" | "done", detail?: string) => void;
+}
+/**
+ * Builds the `place_search` FTS5 table and the `place_bbox` R*Tree from a WOF
+ * database's `spr` and `names` tables.
+ *
+ * Without `drop: true`, an existing index is kept.
+ */
+export declare function buildPlaceSearchFTS<DB>(db: DatabaseClient<DB>, opts?: BuildPlaceSearchFTSOpts): BuildPlaceSearchFTSResult;
+/**
+ * Returns whether the connected database has the `place_search` FTS table.
+ */
+export declare function placeSearchFTSExists<DB>(db: DatabaseClient<DB>): boolean;
+/**
+ * Returns whether the connected database has the `place_bbox` R*Tree table.
+ */
+export declare function placeBboxExists<DB>(db: DatabaseClient<DB>): boolean;
+/**
+ * Returns whether the connected database has the `place_population` table.
+ */
+export declare function placePopulationExists<DB>(db: DatabaseClient<DB>): boolean;
+//# sourceMappingURL=fts.d.ts.map

package/out/fts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../lib/fts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9D;;GAEG;AACH,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,WAAW,CAAA;AAIvC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAUrH;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAA;IAEpB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;;OAGG;IACH,UAAU,CAAC,EAAE,CACZ,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,iBAAiB,GAAG,MAAM,EACzG,MAAM,CAAC,EAAE,MAAM,KACX,IAAI,CAAA;CACT;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EACrC,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EACtB,IAAI,GAAE,uBAA4B,GAChC,yBAAyB,CA6G3B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,OAAO,CAExE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,OAAO,CAEnE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,OAAO,CAEzE"}