@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/ancestry/index.d.ts

@@ -1,45 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The shared ancestor-lineage walk over the WOF `ancestors` table — one place's containment chain
- *   joined with `spr` for canonical names + centroids, ordered NEAREST-FIRST (deepest placetype
- *   first, country last).
- *
- *   Factored out of `WOFSQLitePlaceLookup.ancestors()` (#404) so the reverse geocoder (`reverse.ts`,
- *   #484) reuses the SAME walk instead of growing a second one. The placetype-specificity ordering
- *   lives here as `PLACETYPE_DEPTH` — a single TS map instead of the previous SQL CASE, and
- *   extended below `localadmin` (locality/borough/neighbourhood/microhood now rank correctly
- *   instead of sorting last; forward resolution rarely saw those as ANCESTOR placetypes, reverse
- *   geocoding always does).
- */
-import type { DatabaseClient } from "@mailwoman/sqlite/client";
-/**
- * WOF placetype → containment depth, coarsest = 1. Higher = finer. Placetypes we never resolve (continent, empire, …)
- * map to 0 and sort last. NOT the same table as the FST's `PLACETYPE_ORDER` (fst-serialize.ts) — that one is a
- * serialization order, this one is containment depth.
- */
-export declare const PLACETYPE_DEPTH: Readonly<Record<string, number>>;
-/**
- * Containment depth for a placetype — 0 (sorts coarsest) when unknown.
- */
-export declare function placetypeDepth(placetype: string): number;
-/**
- * One ancestor row, enriched with the `spr` columns both consumers need.
- */
-export interface AncestorPlaceRow {
-    id: number;
-    placetype: string;
-    name: string;
-    country: string;
-    lat: number;
-    lon: number;
-}
-/**
- * The ancestor lineage of `id` — self excluded, nearest-first. Returns `[]` when the place has no recorded ancestry.
- * NOT memoized here; `WOFSQLitePlaceLookup` keeps its own per-id cache.
- */
-export declare function ancestorLineage<DB>(db: DatabaseClient<DB>, id: number, schemaName?: string): AncestorPlaceRow[];
-export * from "#ancestry/backfill";
-//# sourceMappingURL=index.d.ts.map

package/out/ancestry/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/ancestry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAY5D,CAAA;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,SAAS,GAAG,gBAAgB,EAAE,CAc/G;AAED,cAAc,oBAAoB,CAAA"}

package/out/ancestry/index.js

@@ -1,55 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The shared ancestor-lineage walk over the WOF `ancestors` table — one place's containment chain
- *   joined with `spr` for canonical names + centroids, ordered NEAREST-FIRST (deepest placetype
- *   first, country last).
- *
- *   Factored out of `WOFSQLitePlaceLookup.ancestors()` (#404) so the reverse geocoder (`reverse.ts`,
- *   #484) reuses the SAME walk instead of growing a second one. The placetype-specificity ordering
- *   lives here as `PLACETYPE_DEPTH` — a single TS map instead of the previous SQL CASE, and
- *   extended below `localadmin` (locality/borough/neighbourhood/microhood now rank correctly
- *   instead of sorting last; forward resolution rarely saw those as ANCESTOR placetypes, reverse
- *   geocoding always does).
- */
-import { allRows } from "@mailwoman/core/utils";
-/**
- * WOF placetype → containment depth, coarsest = 1. Higher = finer. Placetypes we never resolve (continent, empire, …)
- * map to 0 and sort last. NOT the same table as the FST's `PLACETYPE_ORDER` (fst-serialize.ts) — that one is a
- * serialization order, this one is containment depth.
- */
-export const PLACETYPE_DEPTH = {
-    country: 1,
-    macroregion: 2,
-    region: 3,
-    macrocounty: 4,
-    county: 5,
-    localadmin: 6,
-    locality: 7,
-    borough: 8,
-    macrohood: 9,
-    neighbourhood: 10,
-    microhood: 11,
-};
-/**
- * Containment depth for a placetype — 0 (sorts coarsest) when unknown.
- */
-export function placetypeDepth(placetype) {
-    return PLACETYPE_DEPTH[placetype] ?? 0;
-}
-/**
- * The ancestor lineage of `id` — self excluded, nearest-first. Returns `[]` when the place has no recorded ancestry.
- * NOT memoized here; `WOFSQLitePlaceLookup` keeps its own per-id cache.
- */
-export function ancestorLineage(db, id, schemaName = "main") {
-    const rows = allRows(db.prepare(`SELECT a.ancestor_id AS id, a.ancestor_placetype AS placetype, s.name AS name,
-				s.country AS country, s.latitude AS lat, s.longitude AS lon
-			FROM ${schemaName}.ancestors a JOIN ${schemaName}.spr s ON s.id = a.ancestor_id
-			WHERE a.id = ? AND a.ancestor_id != a.id`), id);
-    rows.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype));
-    return rows;
-}
-export * from "#ancestry/backfill";
-//# sourceMappingURL=index.js.map

package/out/ancestry/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/ancestry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAG/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAChE,OAAO,EAAE,CAAC;IACV,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,aAAa,EAAE,EAAE;IACjB,SAAS,EAAE,EAAE;CACb,CAAA;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC/C,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAcD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAK,EAAsB,EAAE,EAAU,EAAE,UAAU,GAAG,MAAM;IAC1F,MAAM,IAAI,GAAG,OAAO,CACnB,EAAE,CAAC,OAAO,CACT;;UAEO,UAAU,qBAAqB,UAAU;4CACP,CACzC,EACD,EAAE,CACF,CAAA;IAED,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;IAE9E,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,cAAc,oBAAoB,CAAA"}

package/out/convention/index.d.ts

@@ -1,106 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
- *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
- *
- *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
- *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
- *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
- *   in `candidateStrategies`, first to return candidates wins.
- *
- *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
- *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
- *   name.
- *
- *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
- *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
- *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
- *   source).
- */
-import type { FindPlaceQuery, PlaceCandidate } from "#types";
-/**
- * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
- */
-export interface ScoringWeights {
-    pc: number;
-    name: number;
-    pop: number;
-}
-/**
- * A geographically-scoped resolution profile. Namespaced sections grow per phase; #289 ships the dispatch + scoring
- * slice (`candidateStrategies` + `scoringWeights`). Later phases add `fieldMapping` (locale semantics for `locator[]`),
- * `tokenNormalization`, etc.
- */
-export interface Convention {
-    /**
-     * Ordered strategy names the dispatcher runs; the first to return a non-null result wins.
-     */
-    candidateStrategies?: string[];
-    /**
-     * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and inherit the rest
-     * from the layers below it (`resolveConvention` fills any gaps from WORLD_DEFAULT).
-     */
-    scoringWeights?: Partial<ScoringWeights>;
-}
-/**
- * A fully-resolved convention: every field present, weights complete. What `resolveConvention` returns and what
- * strategies consume.
- */
-export interface ResolvedConvention {
-    candidateStrategies: string[];
-    scoringWeights: ScoringWeights;
-}
-/**
- * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first behavior exactly: try
- * `postcode_area_resolution`, else fall back to fuzzy name match; soft-score weights 0.6 / 0.3 / 0.1. Changing these
- * changes EU behavior — don't, without a byte-stability run.
- */
-export declare const WORLD_DEFAULT: ResolvedConvention;
-/**
- * The strategy names the backend registers. The single source of truth shared by the dispatch registry and the
- * build-time validator, so an authored convention that names a non-existent strategy is caught at build (loud) rather
- * than silently skipped at runtime.
- */
-export declare const BUILTIN_STRATEGY_NAMES: readonly ["postcode_area_resolution", "fallback_fuzzy_name_match"];
-/**
- * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the extract
- * auto-detect all agree.
- */
-export declare const ADDRESS_CONVENTION_TABLE = "address_convention";
-/**
- * A named resolution primitive. Returns `null` to abstain (condition unmet / no data) → the dispatcher tries the next
- * strategy; returns an array (possibly empty) to claim the result.
- */
-export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>;
-/**
- * Look up a convention record by WOF polygon id. Returns `undefined` when the polygon has no override.
- */
-export interface ConventionSource {
-    get(wofID: number): Convention | undefined;
-}
-/**
- * In-memory convention source seeded from a `{ wofID: Convention }` map. Empty for the EU locales (they ride
- * `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed source built from source, same
- * distributable-asset discipline as `postcode-locality-intl.db`.
- */
-export declare class SeedConventionSource implements ConventionSource {
-    #private;
-    constructor(rows?: Record<number, Convention>);
-    get(wofID: number): Convention | undefined;
-}
-/**
- * Deep-merge convention layers, later (more-specific) layers winning per field. `candidateStrategies` is replaced
- * wholesale — a convention names its full ordered list, it does not append. `scoringWeights` is merged key-by-key so a
- * locality can nudge one weight without restating the others.
- */
-export declare function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention;
-/**
- * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL → MOST-SPECIFIC (country,
- * region, …, locality). Starts from `WORLD_DEFAULT` so every field is defined regardless of which (if any) ancestors
- * carry an override.
- */
-export declare function resolveConvention(source: ConventionSource, ancestorIDs: readonly number[]): ResolvedConvention;
-//# sourceMappingURL=index.d.ts.map

package/out/convention/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/convention/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC9B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,cAAc,EAAE,cAAc,CAAA;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,kBAG3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,YAAI,0BAA0B,EAAE,2BAA2B,CAAU,CAAA;AAExG;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uBAAuB,CAAA;AAE5D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,CAAA;AAElH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;CAC1C;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;;IAG5D,YAAY,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAM,EAEhD;IAED,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEzC;CACD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,SAAS,EAAE,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,UAAU,CAmB1G;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAS9G"}

package/out/convention/index.js

@@ -1,93 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
- *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
- *
- *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
- *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
- *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
- *   in `candidateStrategies`, first to return candidates wins.
- *
- *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
- *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
- *   name.
- *
- *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
- *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
- *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
- *   source).
- */
-/**
- * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first behavior exactly: try
- * `postcode_area_resolution`, else fall back to fuzzy name match; soft-score weights 0.6 / 0.3 / 0.1. Changing these
- * changes EU behavior — don't, without a byte-stability run.
- */
-export const WORLD_DEFAULT = {
-    candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
-    scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
-};
-/**
- * The strategy names the backend registers. The single source of truth shared by the dispatch registry and the
- * build-time validator, so an authored convention that names a non-existent strategy is caught at build (loud) rather
- * than silently skipped at runtime.
- */
-export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"];
-/**
- * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the extract
- * auto-detect all agree.
- */
-export const ADDRESS_CONVENTION_TABLE = "address_convention";
-/**
- * In-memory convention source seeded from a `{ wofID: Convention }` map. Empty for the EU locales (they ride
- * `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed source built from source, same
- * distributable-asset discipline as `postcode-locality-intl.db`.
- */
-export class SeedConventionSource {
-    #rows;
-    constructor(rows = {}) {
-        this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]));
-    }
-    get(wofID) {
-        return this.#rows.get(wofID);
-    }
-}
-/**
- * Deep-merge convention layers, later (more-specific) layers winning per field. `candidateStrategies` is replaced
- * wholesale — a convention names its full ordered list, it does not append. `scoringWeights` is merged key-by-key so a
- * locality can nudge one weight without restating the others.
- */
-export function mergeConventions(base, ...overrides) {
-    const out = {
-        candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
-        scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
-    };
-    for (const o of overrides) {
-        if (!o)
-            continue;
-        if (o.candidateStrategies !== undefined) {
-            out.candidateStrategies = [...o.candidateStrategies];
-        }
-        if (o.scoringWeights !== undefined) {
-            out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights };
-        }
-    }
-    return out;
-}
-/**
- * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL → MOST-SPECIFIC (country,
- * region, …, locality). Starts from `WORLD_DEFAULT` so every field is defined regardless of which (if any) ancestors
- * carry an override.
- */
-export function resolveConvention(source, ancestorIDs) {
-    const layers = ancestorIDs.map((id) => source.get(id));
-    const merged = mergeConventions(WORLD_DEFAULT, ...layers);
-    return {
-        candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
-        // Fill any weight gaps from the base so strategies always see a complete set.
-        scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
-    };
-}
-//# sourceMappingURL=index.js.map

package/out/convention/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/convention/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAuCH;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAuB;IAChD,mBAAmB,EAAE,CAAC,0BAA0B,EAAE,2BAA2B,CAAC;IAC9E,cAAc,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;CAChD,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,0BAA0B,EAAE,2BAA2B,CAAU,CAAA;AAExG;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAAoB,CAAA;AAe5D;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACvB,KAAK,CAAyB;IAEvC,YAAY,IAAI,GAA+B,EAAE;QAChD,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3E,CAAC;IAED,GAAG,CAAC,KAAa;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,GAAG,SAAwC;IAC7F,MAAM,GAAG,GAAe;QACvB,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,SAAS;QACzF,cAAc,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,SAAS;KAC5E,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC;YAAE,SAAQ;QAEhB,IAAI,CAAC,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YACzC,GAAG,CAAC,mBAAmB,GAAG,CAAC,GAAG,CAAC,CAAC,mBAAmB,CAAC,CAAA;QACrD,CAAC;QAED,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACpC,GAAG,CAAC,cAAc,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,aAAa,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC,CAAC,cAAc,EAAE,CAAA;QACtG,CAAC;IACF,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAwB,EAAE,WAA8B;IACzF,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,MAAM,MAAM,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,MAAM,CAAC,CAAA;IAEzD,OAAO;QACN,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,IAAI,aAAa,CAAC,mBAAmB;QACpF,8EAA8E;QAC9E,cAAc,EAAE,EAAE,GAAG,aAAa,CAAC,cAAc,EAAE,GAAG,MAAM,CAAC,cAAc,EAAE;KAC7E,CAAA;AACF,CAAC"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/fst/index.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,cAAc,YAAY,CAAA"}

package/out/fst/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/fst/index.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,cAAc,YAAY,CAAA"}

package/out/fts/index.d.ts

@@ -1,184 +0,0 @@
-/**
- * @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 gazetteer 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 { DatabaseClient } from "@mailwoman/sqlite/client";
-/**
- * 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";
-/**
- * The query/name fold every exact-tier comparison uses: lowercase, trim, collapse internal whitespace. The `alt_names`
- * bag is compared alias-by-alias against a query folded THIS way, so the fold lives beside the bag parser — every
- * consumer (the Node resolver's exact tier, the WASM resolver, the name-exact sub-tier sort) folds through this one
- * function.
- */
-export declare function foldQueryText(input: string): string;
-/**
- * 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 unrestricted: 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, conditioned on `anyStrictExact` — unrestricted 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";
-/**
- * Name of the auxiliary table holding the two salience scores per place — `referential` (population-anchored, the
- * ranking backbone) and `encyclopedic` (the Wikipedia join, NULL when there is no article). Built by `mailwoman
- * gazetteer importance`; schema and derivations in `place-importance-schema.ts`.
- *
- * The lookup reads ONLY `encyclopedic` from it, and only to CARRY the value onto the result — referential is derived
- * from the population already joined, and no ORDER BY anywhere touches this table (ROAD_TO_V9 §2). Sparse and
- * schema-versioned: a pre-split gazetteer has this table with a single conflated `importance` column instead, which the
- * lookup's column probe deliberately refuses to read.
- */
-export declare const PLACE_IMPORTANCE_TABLE = "place_importance";
-/**
- * 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>(db: DatabaseClient<DB>, 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>(db: DatabaseClient<DB>): boolean;
-/**
- * Returns true iff the `place_bbox` R*Tree table exists. Used for opt-in proximity lookup checks.
- */
-export declare function placeBboxExists<DB>(db: DatabaseClient<DB>): boolean;
-/**
- * Returns true iff the `place_population` table exists. Used for opt-in population-ranking checks.
- */
-export declare function placePopulationExists<DB>(db: DatabaseClient<DB>): boolean;
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/fts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9D;;GAEG;AACH,eAAO,MAAM,kBAAkB,iBAAiB,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,eAAe,WAAW,CAAA;AAOvC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAUrH;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;OAEG;IACH,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,EACrC,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,EACtB,IAAI,GAAE,uBAA4B,GAChC,yBAAyB,CAsI3B;AAED;;;GAGG;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"}