@mailwoman/resolver-wof-sqlite 2.1.0

package/out/fts.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FTS5 index lifecycle for the WOF SQLite distribution.
+ *
+ *   Shared by `WofSqlitePlaceLookup` (lazy build via `buildFts: true`) and the operator-side
+ *   `mailwoman-wof-build-fts` CLI (ahead-of-time build to avoid first-open latency in production).
+ *
+ *   Upstream WOF SQLite distributions do NOT ship FTS5. The index lives in a `place_search` virtual
+ *   table whose rows mirror `(spr.id, spr.name, GROUP_CONCAT(names.name))` — one current,
+ *   non-deprecated place per row, with all alternate names concatenated into a single search-token
+ *   bag.
+ */
+import type { DatabaseSync } from "node:sqlite";
+/**
+ * Name of the FTS5 virtual table this module owns. Centralized so `WofSqlitePlaceLookup` and the
+ * CLI can't drift apart.
+ */
+export declare const PLACE_SEARCH_TABLE = "place_search";
+/**
+ * Boundary-preserving separator between aliases in the `alt_names` bag (#523): U+E000, the first
+ * Private Use Area codepoint, written as an escape so the source stays plain ASCII.
+ *
+ * Why a PUA codepoint and not punctuation: the goal is to stop a phrase query from matching ACROSS
+ * two adjacent aliases' concatenation boundary ("York" + "New City" must not phrase-match `"york
+ * new"`). FTS5 assigns token positions to TOKENS only — separator characters never consume a
+ * position — so any character the tokenizer treats as a boundary leaves the two aliases' tokens
+ * adjacent and the false phrase match intact. The separator must therefore be an INDEXED TOKEN that
+ * sits between the aliases and breaks positional adjacency.
+ *
+ * Empirical probe (node:sqlite, `tokenize = 'unicode61 remove_diacritics 2'` — the exact config
+ * below). Bag = the aliases "York" and "New City" joined by each candidate separator; query = the
+ * cross-boundary phrase `MATCH '"york new"'`:
+ *
+ * - `' '` (the pre-#523 join, no separator) — false HIT
+ * - `' ; '` (punctuation) — false HIT
+ * - `' \u2016 '` (double vertical line) — false HIT
+ * - `' \x1F '` (ASCII unit separator) — false HIT
+ * - `' \uE000 '` (PUA, this constant) — NO match, while `'"york"'` and `'"new city"'` still match the
+ *   bag individually under every variant above.
+ *
+ * U+E000 works because unicode61 classifies it (category Co — neither space nor punctuation) as a
+ * token character, so the standalone `\uE000` between aliases is indexed as its own token and the
+ * aliases' tokens are no longer positionally adjacent. The remaining requirements also hold:
+ *
+ * - **Unreachable from queries**: `sanitizeFtsQuery` (Node + WASM resolvers) strips everything
+ *   outside `\p{L}\p{N}` from token bodies, and U+E000 is neither — no user query can ever address
+ *   the separator token. The demo's `sanitizeFts` strips it explicitly.
+ * - **Never in place names**: PUA codepoints are unassigned by definition; real-world WOF names don't
+ *   carry them. Defensively, the INSERT below also strips any embedded U+E000 from source names so
+ *   a poisoned row can't forge an alias boundary.
+ * - **Survives GROUP_CONCAT**: verified — `GROUP_CONCAT(name, ' ' || char(57344) || ' ')` emits the
+ *   codepoint intact (`57344` = 0xE000).
+ * - **Cost**: one extra token per alias boundary in the FTS document. Marginal BM25 length-norm
+ *   impact, on a column whose length stats are already the known #189 problem.
+ *
+ * Interaction with #189 (split `alt_names` into its own FTS table for independent BM25 length
+ * stats): the separator SURVIVES that split as proposed — #189 still GROUP_CONCATs all aliases into
+ * one `place_search_alt` row per place, so both the separator and the bag-parsing exact check
+ * (`aliasBagExactMatch`) carry over unchanged, just pointed at the new table. Only if #189 were
+ * instead built as one-row-per-alias would both become moot (per-alias rows give exact equality and
+ * phrase isolation for free). Sequencing: if #189 lands before the next slim-DB artifact rebuild,
+ * fold both into ONE rebuild rather than shipping two FTS schema bumps.
+ */
+export declare const ALIAS_SEPARATOR = "\uE000";
+/**
+ * Does any alias in an `alt_names` bag exactly equal the (already-normalized) query? The single
+ * shared implementation of the exact-tier alias check for every consumer of the bag — the Node
+ * resolver's `#exactMatchIds` fallback, the WASM resolver, and the demo's httpvfs resolver — so the
+ * bag format and its parsers can't drift.
+ *
+ * Two formats exist in the wild:
+ *
+ * - **Separated bags** (built since #523): aliases joined with {@link ALIAS_SEPARATOR}, plus a
+ *   trailing separator so even a single-alias bag self-identifies as separator-formatted. Split +
+ *   per-alias equality — a true exact-alias check, matching the semantics of the full `names` table
+ *   (`names.name = ? COLLATE NOCASE`), so it runs UNGATED: an alias match is an exact match whether
+ *   or not another candidate matched on its canonical name.
+ * - **Legacy bags** (pre-#523 artifacts, e.g. an already-deployed slim DB): aliases space-joined,
+ *   boundaries lost. Falls back to the historical padded-containment check, gated on
+ *   `anyStrictExact` — ungated containment would false-promote interior fragments ("York" inside
+ *   the alias "New York City") and cross-boundary fragments ("York New" across "…York" + "New…").
+ *   Delete this branch once every shipped artifact carries the separator.
+ *
+ * @param altNames The `alt_names` bag from `place_search` (null when the row has no aliases).
+ * @param normalizedQuery The query, pre-normalized: lowercased, trimmed, internal whitespace
+ *   collapsed (every consumer already normalizes this way).
+ * @param anyStrictExact Whether ANY candidate in the pool already matched strictly (canonical name
+ *   or region abbreviation). Only consulted for legacy bags.
+ */
+export declare function aliasBagExactMatch(altNames: string | null, normalizedQuery: string, anyStrictExact: boolean): boolean;
+/**
+ * Name of the R*Tree virtual table that indexes WOF places' bounding boxes for proximity / bbox
+ * lookups. Built alongside `place_search` by the CLI and `buildFts: true`. Pure SQLite — no
+ * extensions needed, the `rtree` virtual-table module ships with the core library.
+ */
+export declare const PLACE_BBOX_TABLE = "place_bbox";
+/**
+ * Name of the auxiliary table holding `wof:population` per place. Powers the population-weighted
+ * ranking boost. Sparse — WOF only populates this field for ~15% of localities (and mostly larger
+ * ones); missing means no boost, never a penalty. Built upstream by `scripts/build-unified-wof.ts`
+ * at ingest (and copied through by `build-slim`) — this module consumes it, never builds it.
+ *
+ * Schema: `(id INTEGER PRIMARY KEY, population INTEGER NOT NULL)`. Plain table, not virtual.
+ */
+export declare const PLACE_POPULATION_TABLE = "place_population";
+/**
+ * Counters for a single `buildPlaceSearchFts` run. Exposed so callers (CLI, lazy-build) can render
+ * progress to the user.
+ */
+export interface BuildPlaceSearchFtsResult {
+    /** Whether the FTS5 index was created (true) or already existed and was left alone (false). */
+    created: boolean;
+    /** Number of rows in the `place_search` table after the call. */
+    indexedRows: number;
+    /** Whether the R*Tree bbox index was created (true) or already existed (false). */
+    bboxCreated: boolean;
+    /** Number of rows in the `place_bbox` R*Tree after the call. */
+    bboxIndexedRows: number;
+    /** Wall-clock duration of the build step, in milliseconds. */
+    durationMs: number;
+}
+export interface BuildPlaceSearchFtsOpts {
+    /**
+     * Drop the existing `place_search` AND `place_bbox` tables before building. Default false — if
+     * either already exists the corresponding build step is skipped. Set true when you want to
+     * rebuild against an updated `spr` / `names` snapshot.
+     */
+    drop?: boolean;
+    /**
+     * Optional progress callback invoked after each phase. Useful for CLI output on the planet-scale
+     * builds where the INSERT step can take minutes.
+     */
+    onProgress?: (phase: "checking" | "dropping" | "creating" | "populating" | "creating-bbox" | "populating-bbox" | "done", detail?: string) => void;
+}
+/**
+ * Build (or rebuild, with `drop: true`) the `place_search` FTS5 virtual table AND the `place_bbox`
+ * R*Tree virtual table from the existing `spr` + `names` tables in a WOF SQLite distribution.
+ *
+ * The FTS5 index is used for name-based MATCH queries; the R*Tree is used for bbox + proximity
+ * filtering. Both are pure SQLite — no extensions required.
+ *
+ * Returns a `BuildPlaceSearchFtsResult` summary. Idempotent when `drop: false` — re-running against
+ * an already-indexed DB skips whichever indexes already exist.
+ */
+export declare function buildPlaceSearchFts(db: DatabaseSync, opts?: BuildPlaceSearchFtsOpts): BuildPlaceSearchFtsResult;
+/**
+ * Returns true iff the `place_search` table exists in the connected DB. Used by
+ * `WofSqlitePlaceLookup` for its "FTS missing — pass buildFts:true or run the CLI" guard.
+ */
+export declare function placeSearchFtsExists(db: DatabaseSync): boolean;
+/** Returns true iff the `place_bbox` R*Tree table exists. Used for opt-in proximity lookup checks. */
+export declare function placeBboxExists(db: DatabaseSync): boolean;
+/** Returns true iff the `place_population` table exists. Used for opt-in population-ranking checks. */
+export declare function placePopulationExists(db: DatabaseSync): boolean;
+//# sourceMappingURL=fts.d.ts.map

package/out/fts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../fts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,eAAe,WAAW,CAAA;AAKvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAQrH;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC,+FAA+F;IAC/F,OAAO,EAAE,OAAO,CAAA;IAChB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,mFAAmF;IACnF,WAAW,EAAE,OAAO,CAAA;IACpB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAA;IACvB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;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;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,GAAE,uBAA4B,GAAG,yBAAyB,CAuHnH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAE9D;AAED,sGAAsG;AACtG,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAEzD;AAED,uGAAuG;AACvG,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAE/D"}

package/out/fts.js

@@ -0,0 +1,261 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FTS5 index lifecycle for the WOF SQLite distribution.
+ *
+ *   Shared by `WofSqlitePlaceLookup` (lazy build via `buildFts: true`) and the operator-side
+ *   `mailwoman-wof-build-fts` CLI (ahead-of-time build to avoid first-open latency in production).
+ *
+ *   Upstream WOF SQLite distributions do NOT ship FTS5. The index lives in a `place_search` virtual
+ *   table whose rows mirror `(spr.id, spr.name, GROUP_CONCAT(names.name))` — one current,
+ *   non-deprecated place per row, with all alternate names concatenated into a single search-token
+ *   bag.
+ */
+/**
+ * Name of the FTS5 virtual table this module owns. Centralized so `WofSqlitePlaceLookup` and the
+ * CLI can't drift apart.
+ */
+export const PLACE_SEARCH_TABLE = "place_search";
+/**
+ * Boundary-preserving separator between aliases in the `alt_names` bag (#523): U+E000, the first
+ * Private Use Area codepoint, written as an escape so the source stays plain ASCII.
+ *
+ * Why a PUA codepoint and not punctuation: the goal is to stop a phrase query from matching ACROSS
+ * two adjacent aliases' concatenation boundary ("York" + "New City" must not phrase-match `"york
+ * new"`). FTS5 assigns token positions to TOKENS only — separator characters never consume a
+ * position — so any character the tokenizer treats as a boundary leaves the two aliases' tokens
+ * adjacent and the false phrase match intact. The separator must therefore be an INDEXED TOKEN that
+ * sits between the aliases and breaks positional adjacency.
+ *
+ * Empirical probe (node:sqlite, `tokenize = 'unicode61 remove_diacritics 2'` — the exact config
+ * below). Bag = the aliases "York" and "New City" joined by each candidate separator; query = the
+ * cross-boundary phrase `MATCH '"york new"'`:
+ *
+ * - `' '` (the pre-#523 join, no separator) — false HIT
+ * - `' ; '` (punctuation) — false HIT
+ * - `' \u2016 '` (double vertical line) — false HIT
+ * - `' \x1F '` (ASCII unit separator) — false HIT
+ * - `' \uE000 '` (PUA, this constant) — NO match, while `'"york"'` and `'"new city"'` still match the
+ *   bag individually under every variant above.
+ *
+ * U+E000 works because unicode61 classifies it (category Co — neither space nor punctuation) as a
+ * token character, so the standalone `\uE000` between aliases is indexed as its own token and the
+ * aliases' tokens are no longer positionally adjacent. The remaining requirements also hold:
+ *
+ * - **Unreachable from queries**: `sanitizeFtsQuery` (Node + WASM resolvers) strips everything
+ *   outside `\p{L}\p{N}` from token bodies, and U+E000 is neither — no user query can ever address
+ *   the separator token. The demo's `sanitizeFts` strips it explicitly.
+ * - **Never in place names**: PUA codepoints are unassigned by definition; real-world WOF names don't
+ *   carry them. Defensively, the INSERT below also strips any embedded U+E000 from source names so
+ *   a poisoned row can't forge an alias boundary.
+ * - **Survives GROUP_CONCAT**: verified — `GROUP_CONCAT(name, ' ' || char(57344) || ' ')` emits the
+ *   codepoint intact (`57344` = 0xE000).
+ * - **Cost**: one extra token per alias boundary in the FTS document. Marginal BM25 length-norm
+ *   impact, on a column whose length stats are already the known #189 problem.
+ *
+ * Interaction with #189 (split `alt_names` into its own FTS table for independent BM25 length
+ * stats): the separator SURVIVES that split as proposed — #189 still GROUP_CONCATs all aliases into
+ * one `place_search_alt` row per place, so both the separator and the bag-parsing exact check
+ * (`aliasBagExactMatch`) carry over unchanged, just pointed at the new table. Only if #189 were
+ * instead built as one-row-per-alias would both become moot (per-alias rows give exact equality and
+ * phrase isolation for free). Sequencing: if #189 lands before the next slim-DB artifact rebuild,
+ * fold both into ONE rebuild rather than shipping two FTS schema bumps.
+ */
+export const ALIAS_SEPARATOR = "\uE000";
+/** `char()` argument for {@link ALIAS_SEPARATOR} in SQL — keeps the SQL text plain ASCII. */
+const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0);
+/**
+ * Does any alias in an `alt_names` bag exactly equal the (already-normalized) query? The single
+ * shared implementation of the exact-tier alias check for every consumer of the bag — the Node
+ * resolver's `#exactMatchIds` fallback, the WASM resolver, and the demo's httpvfs resolver — so the
+ * bag format and its parsers can't drift.
+ *
+ * Two formats exist in the wild:
+ *
+ * - **Separated bags** (built since #523): aliases joined with {@link ALIAS_SEPARATOR}, plus a
+ *   trailing separator so even a single-alias bag self-identifies as separator-formatted. Split +
+ *   per-alias equality — a true exact-alias check, matching the semantics of the full `names` table
+ *   (`names.name = ? COLLATE NOCASE`), so it runs UNGATED: an alias match is an exact match whether
+ *   or not another candidate matched on its canonical name.
+ * - **Legacy bags** (pre-#523 artifacts, e.g. an already-deployed slim DB): aliases space-joined,
+ *   boundaries lost. Falls back to the historical padded-containment check, gated on
+ *   `anyStrictExact` — ungated containment would false-promote interior fragments ("York" inside
+ *   the alias "New York City") and cross-boundary fragments ("York New" across "…York" + "New…").
+ *   Delete this branch once every shipped artifact carries the separator.
+ *
+ * @param altNames The `alt_names` bag from `place_search` (null when the row has no aliases).
+ * @param normalizedQuery The query, pre-normalized: lowercased, trimmed, internal whitespace
+ *   collapsed (every consumer already normalizes this way).
+ * @param anyStrictExact Whether ANY candidate in the pool already matched strictly (canonical name
+ *   or region abbreviation). Only consulted for legacy bags.
+ */
+export function aliasBagExactMatch(altNames, normalizedQuery, anyStrictExact) {
+    if (altNames === null || altNames === "" || !normalizedQuery)
+        return false;
+    const norm = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
+    if (altNames.includes(ALIAS_SEPARATOR)) {
+        return altNames.split(ALIAS_SEPARATOR).some((alias) => norm(alias) === normalizedQuery);
+    }
+    if (anyStrictExact)
+        return false;
+    return ` ${norm(altNames)} `.includes(` ${normalizedQuery} `);
+}
+/**
+ * Name of the R*Tree virtual table that indexes WOF places' bounding boxes for proximity / bbox
+ * lookups. Built alongside `place_search` by the CLI and `buildFts: true`. Pure SQLite — no
+ * extensions needed, the `rtree` virtual-table module ships with the core library.
+ */
+export const PLACE_BBOX_TABLE = "place_bbox";
+/**
+ * Name of the auxiliary table holding `wof:population` per place. Powers the population-weighted
+ * ranking boost. Sparse — WOF only populates this field for ~15% of localities (and mostly larger
+ * ones); missing means no boost, never a penalty. Built upstream by `scripts/build-unified-wof.ts`
+ * at ingest (and copied through by `build-slim`) — this module consumes it, never builds it.
+ *
+ * Schema: `(id INTEGER PRIMARY KEY, population INTEGER NOT NULL)`. Plain table, not virtual.
+ */
+export const PLACE_POPULATION_TABLE = "place_population";
+/**
+ * Build (or rebuild, with `drop: true`) the `place_search` FTS5 virtual table AND the `place_bbox`
+ * R*Tree virtual table from the existing `spr` + `names` tables in a WOF SQLite distribution.
+ *
+ * The FTS5 index is used for name-based MATCH queries; the R*Tree is used for bbox + proximity
+ * filtering. Both are pure SQLite — no extensions required.
+ *
+ * Returns a `BuildPlaceSearchFtsResult` summary. Idempotent when `drop: false` — re-running against
+ * an already-indexed DB skips whichever indexes already exist.
+ */
+export function buildPlaceSearchFts(db, opts = {}) {
+    const start = Date.now();
+    const onProgress = opts.onProgress ?? (() => { });
+    onProgress("checking");
+    const ftsExisting = tableExists(db, PLACE_SEARCH_TABLE);
+    const bboxExisting = tableExists(db, PLACE_BBOX_TABLE);
+    // ─── FTS5 phase ──────────────────────────────────────────────────
+    let ftsCreated = false;
+    if (ftsExisting && opts.drop) {
+        onProgress("dropping", PLACE_SEARCH_TABLE);
+        db.exec(`DROP TABLE ${PLACE_SEARCH_TABLE}`);
+    }
+    if (!ftsExisting || opts.drop) {
+        onProgress("creating");
+        db.exec(`
+			CREATE VIRTUAL TABLE ${PLACE_SEARCH_TABLE} USING fts5(
+				wof_id UNINDEXED,
+				name,
+				alt_names,
+				tokenize = 'unicode61 remove_diacritics 2'
+			);
+		`);
+        onProgress("populating");
+        // Excludes only definitively-not-current places. WOF's `is_current` carries TWO conventions:
+        // `-1` (modern Who's On First) and `1` (legacy Mapzen-era), both meaning "currently valid".
+        // Only `0` means "no longer current". Filtering on `= -1` strict (as Phase 4.2 did) excluded
+        // ~42% of admin-US and ~68% of postcode-US — see #91 for the diagnostic + magnitude.
+        //
+        // Aliases join on the boundary-preserving ALIAS_SEPARATOR token (#523) — space-padded so each
+        // alias still tokenizes normally — and any U+E000 embedded in a source name is defensively
+        // flattened to a space so it can't forge a boundary. A TRAILING separator marks the bag as
+        // separator-formatted even when it holds a single alias, so `aliasBagExactMatch` never
+        // mistakes a new bag for a legacy (pre-#523) one. See the ALIAS_SEPARATOR docs for the
+        // probe + rationale.
+        db.exec(`
+			INSERT INTO ${PLACE_SEARCH_TABLE} (wof_id, name, alt_names)
+			SELECT
+				spr.id,
+				spr.name,
+				COALESCE((
+					SELECT GROUP_CONCAT(
+						REPLACE(name, char(${ALIAS_SEPARATOR_CODEPOINT}), ' '),
+						' ' || char(${ALIAS_SEPARATOR_CODEPOINT}) || ' '
+					) || ' ' || char(${ALIAS_SEPARATOR_CODEPOINT})
+					FROM names WHERE names.id = spr.id
+				), '')
+			FROM spr
+			WHERE spr.is_current != 0
+				AND spr.is_deprecated = 0
+				AND spr.name IS NOT NULL;
+		`);
+        ftsCreated = true;
+    }
+    const ftsCountRow = db.prepare(`SELECT COUNT(*) AS n FROM ${PLACE_SEARCH_TABLE}`).get();
+    // ─── R*Tree phase ────────────────────────────────────────────────
+    let bboxCreated = false;
+    if (bboxExisting && opts.drop) {
+        onProgress("dropping", PLACE_BBOX_TABLE);
+        db.exec(`DROP TABLE ${PLACE_BBOX_TABLE}`);
+    }
+    if (!bboxExisting || opts.drop) {
+        onProgress("creating-bbox");
+        // R*Tree requires INTEGER PRIMARY KEY (id) + paired min/max for each indexed dimension.
+        // `rtree` (not `rtree_i32`) keeps coordinates as REAL — what we want for WGS-84.
+        db.exec(`
+			CREATE VIRTUAL TABLE ${PLACE_BBOX_TABLE} USING rtree(
+				id,
+				min_lat, max_lat,
+				min_lon, max_lon
+			);
+		`);
+        onProgress("populating-bbox");
+        // Only index places that have non-zero coordinates AND a real bbox. WOF stores both the
+        // centroid (latitude/longitude) and the bounding box (min_*/max_*). A subset of rows have
+        // all-zero coordinates — likely placeholders for deprecated / unmapped entries; the
+        // is_current / is_deprecated filter mostly catches them, but we double-check at insert.
+        db.exec(`
+			INSERT INTO ${PLACE_BBOX_TABLE} (id, min_lat, max_lat, min_lon, max_lon)
+			SELECT
+				spr.id,
+				spr.min_latitude,
+				spr.max_latitude,
+				spr.min_longitude,
+				spr.max_longitude
+			FROM spr
+			WHERE spr.is_current != 0
+				AND spr.is_deprecated = 0
+				AND spr.min_latitude IS NOT NULL
+				AND spr.max_latitude IS NOT NULL
+				AND spr.min_longitude IS NOT NULL
+				AND spr.max_longitude IS NOT NULL
+				AND NOT (spr.min_latitude = 0 AND spr.max_latitude = 0
+				     AND spr.min_longitude = 0 AND spr.max_longitude = 0);
+		`);
+        bboxCreated = true;
+    }
+    const bboxCountRow = db.prepare(`SELECT COUNT(*) AS n FROM ${PLACE_BBOX_TABLE}`).get();
+    // NOTE: `place_population` is NOT built here. `scripts/build-unified-wof.ts` extracts
+    // `wof:population` straight into that table at ingest (the canonical source carries no `geojson`
+    // table), and `build-slim` copies it through. This function only owns the two FTS-derived virtual
+    // tables, both of which build from `spr` + `names` alone. `placePopulationExists` lets callers
+    // check for the pre-built table.
+    onProgress("done", `${ftsCountRow.n} FTS rows + ${bboxCountRow.n} bbox rows ` +
+        `(${ftsCreated ? "built" : "preexisting"} / ${bboxCreated ? "built" : "preexisting"})`);
+    return {
+        created: ftsCreated,
+        indexedRows: ftsCountRow.n,
+        bboxCreated,
+        bboxIndexedRows: bboxCountRow.n,
+        durationMs: Date.now() - start,
+    };
+}
+/**
+ * Returns true iff the `place_search` table exists in the connected DB. Used by
+ * `WofSqlitePlaceLookup` for its "FTS missing — pass buildFts:true or run the CLI" guard.
+ */
+export function placeSearchFtsExists(db) {
+    return tableExists(db, PLACE_SEARCH_TABLE);
+}
+/** Returns true iff the `place_bbox` R*Tree table exists. Used for opt-in proximity lookup checks. */
+export function placeBboxExists(db) {
+    return tableExists(db, PLACE_BBOX_TABLE);
+}
+/** Returns true iff the `place_population` table exists. Used for opt-in population-ranking checks. */
+export function placePopulationExists(db) {
+    return tableExists(db, PLACE_POPULATION_TABLE);
+}
+function tableExists(db, name) {
+    const row = db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`).get(name);
+    return Boolean(row);
+}
+//# sourceMappingURL=fts.js.map

package/out/fts.js.map

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

package/out/geo.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Geographic helpers for the resolver — haversine distance, bbox math, and point-in-polygon.
+ *
+ *   We deliberately don't pull SpatiaLite (or turf) for this. SQLite's built-in `rtree` virtual table
+ *   gives us bbox filtering at the SQL level; haversine distance is a 12-line TS function and
+ *   ray-cast PIP a ~30-line one — both plenty fast for the post-fetch passes (we operate on ≤ a few
+ *   hundred candidates per query, not the whole 142k-row corpus).
+ *
+ *   The PIP implementation here is the CANONICAL port of the even-odd ray cast that previously lived
+ *   only in Python (`scripts/eval/pip-containment.py`, with a second copy in
+ *   `scripts/build-postcode-locality.py`). Keep the three in sync if the algorithm ever changes —
+ *   the eval-side Python copies grade the same containment truth this one resolves with.
+ *
+ *   The R*Tree index name + schema are centralized in `fts.ts` (alongside the FTS5 build).
+ */
+export { haversineKm } from "@mailwoman/spatial";
+/**
+ * Approximate bbox around a point — `radiusKm` in each direction. Used to translate a `near: {lat,
+ * lon}` + `maxDistanceKm` filter into an R*Tree bbox query.
+ *
+ * The math is the spherical-Earth equirectangular approximation: 1° latitude ≈ 111 km globally, 1°
+ * longitude ≈ 111 km × cos(latitude). Accurate enough for filtering (we re-check with exact
+ * haversine post-fetch), and it stays cheap.
+ */
+export interface Bbox {
+    minLat: number;
+    maxLat: number;
+    minLon: number;
+    maxLon: number;
+}
+export declare function bboxAround(lat: number, lon: number, radiusKm: number): Bbox;
+/**
+ * A GeoJSON position — `[lon, lat]`, possibly with extra dimensions we ignore. WOF geometries are
+ * 2-D throughout, but the type stays open so a 3-D source doesn't break parsing.
+ */
+export type GeojsonPosition = [number, number, ...number[]];
+/** The two areal GeoJSON geometry types PIP can test, plus an open fallback (Point etc.). */
+export interface GeojsonPolygon {
+    type: "Polygon";
+    /** `[outerRing, hole1, hole2, …]` — each ring a closed list of positions. */
+    coordinates: GeojsonPosition[][];
+}
+export interface GeojsonMultiPolygon {
+    type: "MultiPolygon";
+    coordinates: GeojsonPosition[][][];
+}
+export type GeojsonGeometry = GeojsonPolygon | GeojsonMultiPolygon | {
+    type: string;
+    coordinates?: unknown;
+};
+/**
+ * Ray-cast a point against ONE linear ring. Standard even-odd crossing count: shoot a ray along
+ * +lon and toggle on every edge crossing. Points exactly on an edge are implementation-defined
+ * (either side is acceptable for geocoding — admin boundaries are DP-simplified anyway).
+ */
+export declare function pointInRing(lon: number, lat: number, ring: readonly GeojsonPosition[]): boolean;
+/**
+ * Even-odd containment over a polygon's ring list (`[outer, hole1, …]`) — being inside an odd
+ * number of rings means inside the polygon, which handles holes without ring-orientation rules.
+ */
+export declare function pointInPolygonRings(lon: number, lat: number, rings: readonly GeojsonPosition[][]): boolean;
+/**
+ * Does an areal GeoJSON geometry contain the point?
+ *
+ * - `true` / `false` — a Polygon or MultiPolygon was tested.
+ * - `null` — the geometry isn't areal (Point, LineString, …) and CANNOT contain; callers treat this
+ *   the same as "no polygon on record" (the approximate-fallback path), never as a rejection.
+ */
+export declare function geometryContains(geometry: GeojsonGeometry | null | undefined, lon: number, lat: number): boolean | null;
+//# sourceMappingURL=geo.d.ts.map

package/out/geo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAOhD;;;;;;;GAOG;AACH,MAAM,WAAW,IAAI;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAW3E;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAA;AAE3D,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,SAAS,CAAA;IACf,6EAA6E;IAC7E,WAAW,EAAE,eAAe,EAAE,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,cAAc,CAAA;IACpB,WAAW,EAAE,eAAe,EAAE,EAAE,EAAE,CAAA;CAClC;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAE5G;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAa/F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,eAAe,EAAE,EAAE,GAAG,OAAO,CAM1G;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACT,OAAO,GAAG,IAAI,CAShB"}

package/out/geo.js

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Geographic helpers for the resolver — haversine distance, bbox math, and point-in-polygon.
+ *
+ *   We deliberately don't pull SpatiaLite (or turf) for this. SQLite's built-in `rtree` virtual table
+ *   gives us bbox filtering at the SQL level; haversine distance is a 12-line TS function and
+ *   ray-cast PIP a ~30-line one — both plenty fast for the post-fetch passes (we operate on ≤ a few
+ *   hundred candidates per query, not the whole 142k-row corpus).
+ *
+ *   The PIP implementation here is the CANONICAL port of the even-odd ray cast that previously lived
+ *   only in Python (`scripts/eval/pip-containment.py`, with a second copy in
+ *   `scripts/build-postcode-locality.py`). Keep the three in sync if the algorithm ever changes —
+ *   the eval-side Python copies grade the same containment truth this one resolves with.
+ *
+ *   The R*Tree index name + schema are centralized in `fts.ts` (alongside the FTS5 build).
+ */
+// haversineKm is the canonical implementation in @mailwoman/spatial; re-exported so this package's
+// readers keep importing it from "./geo.js" (the spatial dep is transitive via @mailwoman/resolver).
+export { haversineKm } from "@mailwoman/spatial";
+/** WGS-84 degrees → radians. */
+function toRad(deg) {
+    return (deg * Math.PI) / 180;
+}
+export function bboxAround(lat, lon, radiusKm) {
+    const latDelta = radiusKm / 111;
+    // Guard against cos(±90°) = 0 (and tiny values near the poles) by clamping to a minimum.
+    const cosLat = Math.max(Math.cos(toRad(lat)), 1e-6);
+    const lonDelta = radiusKm / (111 * cosLat);
+    return {
+        minLat: lat - latDelta,
+        maxLat: lat + latDelta,
+        minLon: lon - lonDelta,
+        maxLon: lon + lonDelta,
+    };
+}
+/**
+ * Ray-cast a point against ONE linear ring. Standard even-odd crossing count: shoot a ray along
+ * +lon and toggle on every edge crossing. Points exactly on an edge are implementation-defined
+ * (either side is acceptable for geocoding — admin boundaries are DP-simplified anyway).
+ */
+export function pointInRing(lon, lat, ring) {
+    let inside = false;
+    const n = ring.length;
+    for (let i = 0, j = n - 1; i < n; j = i++) {
+        const xi = ring[i][0];
+        const yi = ring[i][1];
+        const xj = ring[j][0];
+        const yj = ring[j][1];
+        if (yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi) {
+            inside = !inside;
+        }
+    }
+    return inside;
+}
+/**
+ * Even-odd containment over a polygon's ring list (`[outer, hole1, …]`) — being inside an odd
+ * number of rings means inside the polygon, which handles holes without ring-orientation rules.
+ */
+export function pointInPolygonRings(lon, lat, rings) {
+    let inside = false;
+    for (const ring of rings) {
+        if (pointInRing(lon, lat, ring))
+            inside = !inside;
+    }
+    return inside;
+}
+/**
+ * Does an areal GeoJSON geometry contain the point?
+ *
+ * - `true` / `false` — a Polygon or MultiPolygon was tested.
+ * - `null` — the geometry isn't areal (Point, LineString, …) and CANNOT contain; callers treat this
+ *   the same as "no polygon on record" (the approximate-fallback path), never as a rejection.
+ */
+export function geometryContains(geometry, lon, lat) {
+    if (!geometry)
+        return null;
+    if (geometry.type === "Polygon") {
+        return pointInPolygonRings(lon, lat, geometry.coordinates);
+    }
+    if (geometry.type === "MultiPolygon") {
+        return geometry.coordinates.some((rings) => pointInPolygonRings(lon, lat, rings));
+    }
+    return null;
+}
+//# sourceMappingURL=geo.js.map

package/out/geo.js.map

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

package/out/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export type { FindPlaceQuery, GeoBbox, GeoPoint, PlaceCandidate, PlaceLookup, WofPlacetype } from "./types.js";
+export type { AncestorsTable, CoincidentRolesTable, ConcordancesTable, GeojsonTable, NamesTable, PlaceAbbrTable, PlacePopulationTable, PlaceSearchTable, SprTable, WofDatabase, } from "./schema.js";
+export { WofSqlitePlaceLookup, type RankingWeights, type WofSqlitePlaceLookupOpts } from "./lookup.js";
+export { WofCandidateTableLookup, type WofCandidateTableLookupOpts } from "./candidate-lookup.js";
+export { ADDRESS_POINT_COLUMNS, createAddressPointIndexes, createAddressPointTable } from "./address-point-schema.js";
+export type { AddressPointDatabase, AddressPointTable } from "./address-point-schema.js";
+export { WofPostalCityAliasLookup, type PostalCityAlias, type WofPostalCityAliasLookupOpts, } from "./postal-city-alias-lookup.js";
+export type { PostalCityAliasDatabase, PostalCityAliasTable } from "./postal-city-alias-schema.js";
+export { POSTAL_CITY_CANDIDATE_COLUMNS, POSTAL_CITY_CANDIDATE_TABLE, createPostalCityCandidateTable, } from "./postal-city-candidate-schema.js";
+export type { PostalCityCandidateDatabase, PostalCityCandidateTable } from "./postal-city-candidate-schema.js";
+export { ADDRESS_CONVENTION_TABLE, BUILTIN_STRATEGY_NAMES, SeedConventionSource, WORLD_DEFAULT, mergeConventions, resolveConvention, type Convention, type ConventionSource, type ResolvedConvention, type ScoringWeights, type Strategy, } from "./convention.js";
+export { SqliteConventionSource } from "./sqlite-convention-source.js";
+export { WofPostcodeLookup, type PostcodePlace } from "./postcode-point-lookup.js";
+export { PLACE_BBOX_TABLE, PLACE_SEARCH_TABLE, buildPlaceSearchFts, placeBboxExists, placeSearchFtsExists, type BuildPlaceSearchFtsOpts, type BuildPlaceSearchFtsResult, } from "./fts.js";
+export { bboxAround, geometryContains, haversineKm, pointInPolygonRings, pointInRing, type Bbox, type GeojsonGeometry, type GeojsonMultiPolygon, type GeojsonPolygon, type GeojsonPosition, } from "./geo.js";
+export { PLACETYPE_DEPTH, ancestorLineage, placetypeDepth, type AncestorPlaceRow } from "./ancestry.js";
+export { WofReverseGeocoder, type ContainmentKind, type ReverseGeocodeOpts, type ReverseGeocodeResult, type WofReverseGeocoderOpts, } from "./reverse.js";
+export { AddressPointInterpolator } from "./address-point-interpolation.js";
+export { AddressPointSqliteLookup } from "./address-point.js";
+export { StreetInterpolator, type InterpolatedHit, type InterpolationMethod, type InterpolationQuery, } from "./interpolation.js";
+export { deriveSchemaName, pickShardForPlacetype, resolveShards, type ResolvedShard, type ShardConfig, } from "./sharding.js";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9G,YAAY,EACX,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,QAAQ,EACR,WAAW,GACX,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAEtG,OAAO,EAAE,uBAAuB,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAEjG,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AACrH,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AACxF,OAAO,EACN,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,4BAA4B,GACjC,MAAM,+BAA+B,CAAA;AACtC,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAClG,OAAO,EACN,6BAA6B,EAC7B,2BAA2B,EAC3B,8BAA8B,GAC9B,MAAM,mCAAmC,CAAA;AAC1C,YAAY,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAA;AAE9G,OAAO,EACN,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,QAAQ,GACb,MAAM,iBAAiB,CAAA;AAExB,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AAEtE,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAElF,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,GAC9B,MAAM,UAAU,CAAA;AAEjB,OAAO,EACN,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,GACpB,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEvG,OAAO,EACN,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,GAC3B,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EACN,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACvB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,WAAW,GAChB,MAAM,eAAe,CAAA"}