@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/candidate/country-display-names.js

@@ -2,31 +2,19 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 1b of the candidate build — fold ICU's country display names onto the country rows.
  */
 import { enumerateCountryDisplayNames } from "@mailwoman/codex/country";
 import { normalizeLocalityForKey } from "#street/normalize";
 /**
- * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).
+ * Stages each country name that `Intl.DisplayNames` renders in the codex display-name
+ * locales as a non-primary key on that country's candidate row.
  *
- * A bare `格鲁吉亚` (Georgia the country) resolved to NOTHING while `佐治亚州` (Georgia the US state) resolved correctly, and
- * the model gave both the same wrong `locality` tag — so the tag was never the variable. Measured 2026-08-15: 140 of
- * 237 country rows are synthetic and carry a canonical English name and nothing else; WOF holds no Chinese country
- * names at all; and the GeoNames alias fold filters through a Latin-script regex, so neither existing source could ever
- * supply them.
+ * The row's display name is unchanged, so a query such as `格鲁吉亚` resolves to the existing Georgia row.
+ * When several country rows share an ISO code, the most populous one receives the keys.
  *
- * `Intl.DisplayNames` already knows every one — ~280 regions, ~5,244 surfaces, from the same ICU the runtime uses for
- * every other locale-sensitive operation. No download, no vendored corpus, no snapshot to drift.
- *
- * `is_primary = 0`: these are NAMES THE WORLD USES, not the country's canonical name. The display `name` stays whatever
- * the gazetteer already had, so resolving `格鲁吉亚` answers with the Georgia country row rather than renaming it.
- *
- * Returns the row count so the caller can report it — a zero means ICU supplied nothing, which is a different fact from
- * the pass not having run.
+ * @returns The number of rows staged.
  */
 export function stageCountryDisplayNames(ctx) {
-    // One country row per ISO2. Where a code has several (historic rows surviving the is_current filter), the most
-    // populous wins — the same tiebreak the ranking uses everywhere else.
     const countryByISO2 = new Map();
     for (const [sid, a] of ctx.attrs) {
         if (a.ptid !== ctx.countryPtID)
@@ -35,7 +23,7 @@ export function stageCountryDisplayNames(ctx) {
         if (!iso2 || iso2 === "??")
             continue;
         const held = countryByISO2.get(iso2);
-        if (!held || a.pop > held.a.pop) {
+        if (!held || (a.pop ?? 0) > (held.a.pop ?? 0)) {
             countryByISO2.set(iso2, { sid, a });
         }
     }
@@ -46,8 +34,6 @@ export function stageCountryDisplayNames(ctx) {
         if (!target)
             continue;
         const k = normalizeLocalityForKey(name);
-        // The country's own key is already staged as its primary; INSERT OR IGNORE at materialization dedupes the
-        // rest, so this only skips the obvious self-alias.
         if (!k || k === target.a.pkey)
             continue;
         ctx.stageRow(k, target.a, target.sid, 0);

package/out/candidate/country-display-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"country-display-names.js","sourceRoot":"","sources":["../../lib/candidate/country-display-names.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAMxC;IACA,+GAA+G;IAC/G,sEAAsE;IACtE,MAAM,aAAa,GAAG,IAAI,GAAG,EAA0C,CAAA;IAEvE,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,WAAW;YAAE,SAAQ;QAExC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,SAAQ;QAEpC,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;YACjC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QACpC,CAAC;IACF,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEpB,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,4BAA4B,EAAE,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEtC,IAAI,CAAC,MAAM;YAAE,SAAQ;QAErB,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAEvC,0GAA0G;QAC1G,mDAAmD;QACnD,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;YAAE,SAAQ;QAEvC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAExC,MAAM,EAAE,CAAA;IACT,CAAC;IAED,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAErB,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"country-display-names.js","sourceRoot":"","sources":["../../lib/candidate/country-display-names.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAMxC;IACA,MAAM,aAAa,GAAG,IAAI,GAAG,EAA0C,CAAA;IAEvE,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,WAAW;YAAE,SAAQ;QAExC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,SAAQ;QAEpC,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC;YAC/C,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QACpC,CAAC;IACF,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEpB,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,4BAA4B,EAAE,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEtC,IAAI,CAAC,MAAM;YAAE,SAAQ;QAErB,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAEvC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;YAAE,SAAQ;QAEvC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAExC,MAAM,EAAE,CAAA;IACT,CAAC;IAED,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAErB,OAAO,MAAM,CAAA;AACd,CAAC"}

package/out/candidate/extract-fold.d.ts

@@ -2,34 +2,26 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
  */
 import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { PathBuilderLike } from "path-ts";
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs";
 import type { CandidateDatabase } from "#candidate/schema";
 /**
- * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
- * hanging off that same extract's `names` table.
+ * Stages one postcode or locality extract's located `spr` rows and their `names`
+ * aliases into the candidate table.
  *
- * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
- * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
- * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
- * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
+ * When `attrs` is given and the extract's `ancestors` table places a row in a known region,
+ * the row also gets that region's scope and the region's ancestor chain.
+ * The stored ancestors then agree with the row's scope.
  */
 export declare function foldExtract(ctx: {
-    /**
-     * The staging connection. The extract itself is opened read-only here and closed before returning.
-     */
     out: DatabaseClient<CandidateDatabase>;
-    extractPath: string;
+    extractPath: PathBuilderLike;
     extractPlacetype: "postalcode" | "locality";
     ccID: (code: string | null) => number;
     ptID: (pt: string | null) => number;
     stageRow: StageRow;
-    /**
-     * The admin places pass 1 staged — what an extract's region ancestry is resolved against. Absent, no extract row
-     * takes a region scope (the postcode extracts, which carry none).
-     */
     attrs?: Map<number, PlaceAttrs>;
     progress: (phase: string, message: string) => void;
 }): {

package/out/candidate/extract-fold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-fold.d.ts","sourceRoot":"","sources":["../../lib/candidate/extract-fold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAIzD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAmC1D;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAChC;;OAEG;IACH,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,YAAY,GAAG,UAAU,CAAA;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACrC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACnC,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAClD,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAkJ/E"}
+{"version":3,"file":"extract-fold.d.ts","sourceRoot":"","sources":["../../lib/candidate/extract-fold.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AA0B1D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAChC,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IACtC,WAAW,EAAE,eAAe,CAAA;IAC5B,gBAAgB,EAAE,YAAY,GAAG,UAAU,CAAA;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACrC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACnC,QAAQ,EAAE,QAAQ,CAAA;IAElB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAClD,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAqH/E"}

package/out/candidate/extract-fold.js

@@ -2,21 +2,11 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
  */
 import { DatabaseClient } from "@mailwoman/sqlite/client";
 import { tableExists } from "@mailwoman/sqlite/introspection";
 import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate/ancestors/schema";
 import { normalizeLocalityForKey } from "#street/normalize";
-/**
- * The extract's own region-tier ancestry, when it carries any: extract id → the admin region's id. A locality extract
- * derived from a national register (the Taiwanese 鄉鎮市區 from the civil-affairs address points) knows which 縣市 each row
- * belongs to, and writes that as an `ancestors` row against the admin region's WOF id. Without it a folded row has no
- * region scope, so a `parentID`-scoped probe misses it and the cascade widens to whatever namesake carries the key.
- *
- * Only a region the admin build staged (`attrs`) counts: an id the admin does not know cannot be denormalized into a
- * closure row, and a scope nothing can match would be a silent zero rather than an absence.
- */
 function extractRegionAncestry(pc, attrs) {
     const regionOf = new Map();
     if (!tableExists(pc, "ancestors")) {
@@ -33,28 +23,21 @@ function extractRegionAncestry(pc, attrs) {
     return regionOf;
 }
 /**
- * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
- * hanging off that same extract's `names` table.
+ * Stages one postcode or locality extract's located `spr` rows and their `names`
+ * aliases into the candidate table.
  *
- * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
- * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
- * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
- * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
+ * When `attrs` is given and the extract's `ancestors` table places a row in a known region,
+ * the row also gets that region's scope and the region's ancestor chain.
+ * The stored ancestors then agree with the row's scope.
  */
 export function foldExtract(ctx) {
     const { out, extractPath, extractPlacetype, ccID, ptID, stageRow, progress } = ctx;
     progress(extractPlacetype === "postalcode" ? "postcodes" : "localities", `reading ${extractPath}`);
     using pc = new DatabaseClient(extractPath, { readOnly: true });
     const pcPtid = ptID(extractPlacetype);
-    // Per-extract, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
-    // below has nothing to join against unless this primary loop records what it staged.
     const pcAttrs = new Map();
     const regionOf = ctx.attrs ? extractRegionAncestry(pc, ctx.attrs) : new Map();
     const insAncestor = out.prepare(`INSERT OR IGNORE INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`);
-    // The region's own closure rows, as the sidecar pass wrote them. A scoped row inherits the whole chain above its
-    // region — macroregion, country — not the region alone: the widened-scope refusal reads a pick's stamped ancestors
-    // against the parent the walk resolved, and a 縣市 that resolves to its macroregion record (`桃園市`, which WOF names
-    // only at that tier) would otherwise contradict a lineage that stops at the region.
     const regionChain = out.prepare(`SELECT depth, parent_spr_id, parent_placetype_id, parent_name, parent_name_key FROM ${CANDIDATE_ANCESTOR_TABLE} WHERE spr_id = ? ORDER BY depth`);
     let primaries = 0;
     let aliases = 0;
@@ -74,9 +57,6 @@ export function foldExtract(ctx) {
         const lon = r.longitude;
         const id = Number(r.id);
         const rid = regionOf.get(id) ?? 0;
-        // region_id from the extract's own ancestry when it names one, else 0 (a postcode is unique by
-        // name+country — no same-name disambiguation); neg_rank 0 (no population). bbox = the row's own
-        // min/max (falls back to the centroid point).
         const a = {
             cid: ccID(r.country),
             rid,
@@ -91,9 +71,6 @@ export function foldExtract(ctx) {
             pop: 0,
             neg: 0,
             pkey: key,
-            // A postcode has no toponym fame — nobody writes an encyclopedia article about SW1A 2AA — and
-            // the score source carries no `postalcode` rows to join against anyway. NULL is the truthful
-            // value: unmeasured, so the ranking key leaves postcode rows exactly where they were.
             imp: null,
         };
         pcAttrs.set(id, a);
@@ -111,20 +88,6 @@ export function foldExtract(ctx) {
         primaries++;
     }
     out.exec("COMMIT");
-    // Fold postcode aliases into the staged candidate names.
-    //
-    // The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
-    // the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
-    // downstream of `names` picked them up EXCEPT this build: `fts.ts` unions `spr.name` with every
-    // `names` row into `place_search.alt_names`, so the FTS backend resolved "Brooklyn" → 11201
-    // while the candidate backend — whose every row IS an exact-tier row — had no key for it at
-    // all. Pass 2 does the equivalent fold for admin places, but reads the ADMIN `place_search`,
-    // and `attrs` holds admin ids only, so a postcode extract could never reach it.
-    //
-    // Same discipline as pass 2: `is_primary = 0` (so `rankByPrimaryPreference` treats it as an
-    // alias, not a canonical postcode name), the row stays denormalized onto the POSTCODE's own
-    // spr_id/coords/bbox, and the display `name` stays the postcode — resolving "brooklyn" answers
-    // with place 11201, it does not rename the place to its delivery city.
     const hasNames = tableExists(pc, "names");
     if (hasNames) {
         out.exec("BEGIN");
@@ -133,8 +96,6 @@ export function foldExtract(ctx) {
             if (!a)
                 continue;
             const k = normalizeLocalityForKey(String(r.name ?? ""));
-            // The postcode's own key is already staged as the primary; `INSERT OR IGNORE` at
-            // materialization dedupes repeats, so this only skips the obvious self-alias.
             if (!k || k === a.pkey)
                 continue;
             stageRow(k, a, Number(r.id), 0);
@@ -143,9 +104,6 @@ export function foldExtract(ctx) {
         out.exec("COMMIT");
     }
     else {
-        // Never a silent zero: real extracts come from `createUnifiedSchema`, which always creates
-        // `names`. A extract without it has no alias surface to lose, but say so rather than reporting
-        // "0 aliases" from a table that was never read.
         progress("postcode-aliases", `${extractPath} has no \`names\` table — no delivery-city aliases to fold`);
     }
     return { primaries, aliases, scoped, ancestorRows };

package/out/candidate/extract-fold.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract-fold.js","sourceRoot":"","sources":["../../lib/candidate/extract-fold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAE7D,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAA;AAIlG,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAAC,EAA+B,EAAE,KAA8B;IAC7F,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE1C,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,WAAW,CAAC,EAAE,CAAC;QACnC,OAAO,QAAQ,CAAA;IAChB,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE;SAChB,OAAO,CACP,2GAA2G,CAC3G;SACA,OAAO,EAAE,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;QAEjC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAA;QAChC,CAAC;IACF,CAAC;IAED,OAAO,QAAQ,CAAA;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,GAgB3B;IACA,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAA;IAElF,QAAQ,CAAC,gBAAgB,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,EAAE,WAAW,WAAW,EAAE,CAAC,CAAA;IAElG,MAAM,EAAE,GAAG,IAAI,cAAc,CAAc,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAA;IACrC,gGAAgG;IAChG,qFAAqF;IACrF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAkB,CAAA;IAE7F,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAC9B,yBAAyB,wBAAwB,YAAY,0BAA0B,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACpH,CAAA;IAED,iHAAiH;IACjH,mHAAmH;IACnH,iHAAiH;IACjH,oFAAoF;IACpF,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAC9B,uFAAuF,wBAAwB,kCAAkC,CACjJ,CAAA;IAED,IAAI,SAAS,GAAG,CAAC,CAAA;IACjB,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,IAAI,YAAY,GAAG,CAAC,CAAA;IAEpB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEjB,KAAK,MAAM,CAAC,IAAI,EAAE;SAChB,OAAO,CACP;;sEAEmE,CACnE;SACA,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;QACjC,MAAM,GAAG,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAEzC,IAAI,CAAC,GAAG;YAAE,SAAQ;QAElB,MAAM,GAAG,GAAG,CAAC,CAAC,QAAkB,CAAA;QAChC,MAAM,GAAG,GAAG,CAAC,CAAC,SAAmB,CAAA;QACjC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;QAEjC,+FAA+F;QAC/F,gGAAgG;QAChG,8CAA8C;QAC9C,MAAM,CAAC,GAAe;YACrB,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,OAAwB,CAAC;YACrC,GAAG;YACH,IAAI,EAAE,MAAM;YACZ,IAAI;YACJ,GAAG;YACH,GAAG;YACH,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,CAAC;YACN,IAAI,EAAE,GAAG;YACT,8FAA8F;YAC9F,6FAA6F;YAC7F,sFAAsF;YACtF,GAAG,EAAE,IAAI;SACT,CAAA;QAED,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;QAClB,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;QAEvB,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,GAAG,CAAC,KAAM,CAAC,GAAG,CAAC,GAAG,CAAE,CAAA;YAEnC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;YAElE,MAAM,EAAE,CAAA;YAER,YAAY,EAAE,CAAA;YAEd,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,WAAW,CAAC,GAAG,CACd,EAAE,EACF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EACtB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,EAC1B,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAChC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,EAC9B,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,CAClC,CAAA;gBAED,YAAY,EAAE,CAAA;YACf,CAAC;QACF,CAAC;QAED,SAAS,EAAE,CAAA;IACZ,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAElB,yDAAyD;IACzD,EAAE;IACF,8FAA8F;IAC9F,+FAA+F;IAC/F,gGAAgG;IAChG,4FAA4F;IAC5F,4FAA4F;IAC5F,6FAA6F;IAC7F,gFAAgF;IAChF,EAAE;IACF,4FAA4F;IAC5F,4FAA4F;IAC5F,+FAA+F;IAC/F,uEAAuE;IACvE,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IAEzC,IAAI,QAAQ,EAAE,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAEjB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACpE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YAEnC,IAAI,CAAC,CAAC;gBAAE,SAAQ;YAEhB,MAAM,CAAC,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAA;YAEvD,iFAAiF;YACjF,8EAA8E;YAC9E,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI;gBAAE,SAAQ;YAEhC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YAE/B,OAAO,EAAE,CAAA;QACV,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACnB,CAAC;SAAM,CAAC;QACP,2FAA2F;QAC3F,+FAA+F;QAC/F,gDAAgD;QAChD,QAAQ,CAAC,kBAAkB,EAAE,GAAG,WAAW,4DAA4D,CAAC,CAAA;IACzG,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;AACpD,CAAC"}
+{"version":3,"file":"extract-fold.js","sourceRoot":"","sources":["../../lib/candidate/extract-fold.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAG7D,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAA;AAIlG,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,SAAS,qBAAqB,CAAC,EAA+B,EAAE,KAA8B;IAC7F,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE1C,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,WAAW,CAAC,EAAE,CAAC;QACnC,OAAO,QAAQ,CAAA;IAChB,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE;SAChB,OAAO,CACP,2GAA2G,CAC3G;SACA,OAAO,EAAE,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;QAEjC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAA;QAChC,CAAC;IACF,CAAC;IAED,OAAO,QAAQ,CAAA;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAU3B;IACA,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAA;IAElF,QAAQ,CAAC,gBAAgB,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,EAAE,WAAW,WAAW,EAAE,CAAC,CAAA;IAElG,MAAM,EAAE,GAAG,IAAI,cAAc,CAAc,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAA;IAErC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAkB,CAAA;IAE7F,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAC9B,yBAAyB,wBAAwB,YAAY,0BAA0B,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACpH,CAAA;IAED,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAC9B,uFAAuF,wBAAwB,kCAAkC,CACjJ,CAAA;IAED,IAAI,SAAS,GAAG,CAAC,CAAA;IACjB,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,IAAI,YAAY,GAAG,CAAC,CAAA;IAEpB,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEjB,KAAK,MAAM,CAAC,IAAI,EAAE;SAChB,OAAO,CACP;;sEAEmE,CACnE;SACA,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAA;QACjC,MAAM,GAAG,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAEzC,IAAI,CAAC,GAAG;YAAE,SAAQ;QAElB,MAAM,GAAG,GAAG,CAAC,CAAC,QAAkB,CAAA;QAChC,MAAM,GAAG,GAAG,CAAC,CAAC,SAAmB,CAAA;QACjC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;QAEjC,MAAM,CAAC,GAAe;YACrB,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,OAAwB,CAAC;YACrC,GAAG;YACH,IAAI,EAAE,MAAM;YACZ,IAAI;YACJ,GAAG;YACH,GAAG;YACH,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,KAAK,EAAG,CAAC,CAAC,KAAgB,IAAI,GAAG;YACjC,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,CAAC;YACN,IAAI,EAAE,GAAG;YAET,GAAG,EAAE,IAAI;SACT,CAAA;QAED,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;QAClB,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;QAEvB,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,GAAG,CAAC,KAAM,CAAC,GAAG,CAAC,GAAG,CAAE,CAAA;YAEnC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;YAElE,MAAM,EAAE,CAAA;YAER,YAAY,EAAE,CAAA;YAEd,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,WAAW,CAAC,GAAG,CACd,EAAE,EACF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EACtB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,EAC1B,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAChC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,EAC9B,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,CAClC,CAAA;gBAED,YAAY,EAAE,CAAA;YACf,CAAC;QACF,CAAC;QAED,SAAS,EAAE,CAAA;IACZ,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAElB,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IAEzC,IAAI,QAAQ,EAAE,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAEjB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACpE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YAEnC,IAAI,CAAC,CAAC;gBAAE,SAAQ;YAEhB,MAAM,CAAC,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAA;YAEvD,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI;gBAAE,SAAQ;YAEhC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;YAE/B,OAAO,EAAE,CAAA;QACV,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACnB,CAAC;SAAM,CAAC;QACP,QAAQ,CAAC,kBAAkB,EAAE,GAAG,WAAW,4DAA4D,CAAC,CAAA;IACzG,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;AACpD,CAAC"}

package/out/candidate/fts.d.ts

@@ -3,35 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FTS5-TRIGRAM fuzzy index over the candidate gazetteer's `name_key` — the typo-tolerant fallback
- *   the exact `name_key` B-tree probe structurally can't do (a misspelling breaks the normalized
- *   key, so the contiguous-probe lookup returns nothing). It indexes the NORMALIZED key (not the
- *   raw `name`), so a diacritic-stripped query (`munchen`) trigram-matches the stored `munchen`
- *   rather than missing a raw `München`. The trigram tokenizer makes MATCH a substring/fuzzy
- *   operation; the reader ({@link WOFCandidateTableLookup}) OR's the query's trigrams to fetch a
- *   loose set, then re-ranks it with a WORD-level similarity. The trigram index is the candidate
- *   GENERATOR, not the scorer — trigram Jaccard scores a true transposition correction BELOW a wrong
- *   answer, because shared generic suffixes count as evidence and transpositions count against it.
- *   The receipts are on `candidate-lookup.ts`'s `FUZZY_FETCH` and `WORD_FUZZY_MIN`.
- *
- *   This is what unifies the two gazetteers: the candidate B-tree stays the common,
- *   byte-range-optimal fast path (the browser's contiguous probe), and FTS5 is consulted ONLY on an
- *   exact+strip miss — so its scattered postings cost is rare/amortized, and one DB serves both the
- *   browser and the server.
- *
- *   Raw SQL on purpose: Kysely can't express `CREATE VIRTUAL TABLE … USING fts5` (the repo's
- *   FTS5-stays-raw rule). Indexing DISTINCT `name_key` keeps the index to unique normalized forms
- *   (a name_key fans out to many candidate rows — placetypes, regions, aliases — but the fuzzy
- *   fallback only needs to recover the name_key, then re-probes the B-tree for its rows).
+ *   FTS5-trigram fuzzy index over the candidate gazetteer's normalized `name_key`; raw SQL on purpose, since Kysely cannot express `create virtual table … using fts5`.
  */
 import type { DatabaseClient } from "@mailwoman/sqlite/client";
 /**
- * Name of the FTS5 trigram virtual table this module owns. The reader conditions its fuzzy fallback on it.
+ * Name of the FTS5 trigram virtual table this module owns, on which the reader
+ * conditions its fuzzy fallback.
  */
 export declare const CANDIDATE_FTS_TABLE = "candidate_fts";
 /**
- * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. Call after the candidate
- * B-tree is populated (build pipeline) or against an existing candidate DB (migration).
+ * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. call
+ * after the candidate B-tree is populated or against an existing candidate DB.
  */
 export declare function createCandidateFTS<DB>(db: DatabaseClient<DB>): void;
 //# sourceMappingURL=fts.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../../lib/candidate/fts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D;;GAEG;AACH,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAElD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,IAAI,CAOnE"}
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../../lib/candidate/fts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AAElD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,IAAI,CAOnE"}

package/out/candidate/fts.js

@@ -3,34 +3,16 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   FTS5-TRIGRAM fuzzy index over the candidate gazetteer's `name_key` — the typo-tolerant fallback
- *   the exact `name_key` B-tree probe structurally can't do (a misspelling breaks the normalized
- *   key, so the contiguous-probe lookup returns nothing). It indexes the NORMALIZED key (not the
- *   raw `name`), so a diacritic-stripped query (`munchen`) trigram-matches the stored `munchen`
- *   rather than missing a raw `München`. The trigram tokenizer makes MATCH a substring/fuzzy
- *   operation; the reader ({@link WOFCandidateTableLookup}) OR's the query's trigrams to fetch a
- *   loose set, then re-ranks it with a WORD-level similarity. The trigram index is the candidate
- *   GENERATOR, not the scorer — trigram Jaccard scores a true transposition correction BELOW a wrong
- *   answer, because shared generic suffixes count as evidence and transpositions count against it.
- *   The receipts are on `candidate-lookup.ts`'s `FUZZY_FETCH` and `WORD_FUZZY_MIN`.
- *
- *   This is what unifies the two gazetteers: the candidate B-tree stays the common,
- *   byte-range-optimal fast path (the browser's contiguous probe), and FTS5 is consulted ONLY on an
- *   exact+strip miss — so its scattered postings cost is rare/amortized, and one DB serves both the
- *   browser and the server.
- *
- *   Raw SQL on purpose: Kysely can't express `CREATE VIRTUAL TABLE … USING fts5` (the repo's
- *   FTS5-stays-raw rule). Indexing DISTINCT `name_key` keeps the index to unique normalized forms
- *   (a name_key fans out to many candidate rows — placetypes, regions, aliases — but the fuzzy
- *   fallback only needs to recover the name_key, then re-probes the B-tree for its rows).
+ *   FTS5-trigram fuzzy index over the candidate gazetteer's normalized `name_key`; raw SQL on purpose, since Kysely cannot express `create virtual table … using fts5`.
  */
 /**
- * Name of the FTS5 trigram virtual table this module owns. The reader conditions its fuzzy fallback on it.
+ * Name of the FTS5 trigram virtual table this module owns, on which the reader
+ * conditions its fuzzy fallback.
  */
 export const CANDIDATE_FTS_TABLE = "candidate_fts";
 /**
- * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. Call after the candidate
- * B-tree is populated (build pipeline) or against an existing candidate DB (migration).
+ * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. call
+ * after the candidate B-tree is populated or against an existing candidate DB.
  */
 export function createCandidateFTS(db) {
     db.exec(`DROP TABLE IF EXISTS ${CANDIDATE_FTS_TABLE}`);

package/out/candidate/fts.js.map

@@ -1 +1 @@
-{"version":3,"file":"fts.js","sourceRoot":"","sources":["../../lib/candidate/fts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAA;AAElD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAK,EAAsB;IAC5D,EAAE,CAAC,IAAI,CAAC,wBAAwB,mBAAmB,EAAE,CAAC,CAAA;IACtD,EAAE,CAAC,IAAI,CAAC,wBAAwB,mBAAmB,2CAA2C,CAAC,CAAA;IAE/F,EAAE,CAAC,IAAI,CACN,eAAe,mBAAmB,+EAA+E,CACjH,CAAA;AACF,CAAC"}
+{"version":3,"file":"fts.js","sourceRoot":"","sources":["../../lib/candidate/fts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAA;AAElD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAK,EAAsB;IAC5D,EAAE,CAAC,IAAI,CAAC,wBAAwB,mBAAmB,EAAE,CAAC,CAAA;IACtD,EAAE,CAAC,IAAI,CAAC,wBAAwB,mBAAmB,2CAA2C,CAAC,CAAA;IAE/F,EAAE,CAAC,IAAI,CACN,eAAe,mBAAmB,+EAA+E,CACjH,CAAA;AACF,CAAC"}

package/out/candidate/importance.d.ts

@@ -3,65 +3,48 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The score side of the candidate build (#28) — load a WOF admin database's `place_importance` into
- *   a lookup the candidate builder can probe per place, so every candidate row can carry the
+ *   The score side of the candidate build: load a WOF admin database's `place_importance` into a
+ *   lookup the candidate builder probes per place, so every candidate row can include the
  *   toponym-fame prior a bare city name is decided on.
  *
- *   ## Why this joins on the NAME and not on the id
+ *   The join key is `(name_key, country, placetype)`, the same {@link normalizeLocalityForKey} the
+ *   candidate build uses for its probe key, so the two sides fold identically. An id join is wrong
+ *   here, because the score source (`admin-global-priority-importance.db`) and the candidate build's
+ *   admin source are different snapshots whose ids disagree. An id join silently drops rows and
+ *   leaves the ranking inert on the queries the prior exists for.
  *
- *   The obvious join is `candidate.spr_id = place_importance.id`, and it is wrong here. The score
- *   source (`admin-global-priority-importance.db`) and the candidate build's admin source are
- *   DIFFERENT SNAPSHOTS, and they disagree about ids for exactly the rows that matter: Whitby,
- *   Ontario is `8143502164401` in the shipped `candidate.db` and `8000001156384` in the score source
- *   — the Overture-sourced rows were re-keyed between the two. An id join silently drops every one of
- *   them, which means it drops precisely the FOREIGN HOMONYMS the fame prior exists to demote, and it
- *   drops them invisibly: the build succeeds, the column is populated, and the ranking is inert on
- *   the queries it was built for.
+ *   The key by itself is not enough. `(warwick, US, locality)` covers eleven different places.
+ *   The group's maximum would give every Warwick in America the fame of Warwick, Rhode Island.
+ *   The join picks the nearest centroid when it falls within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+ *   Two artifacts describing the same settlement put its centroid
+ *   in almost the same place. Two towns with the same name in one country do not.
  *
- *   So the join key is `(name_key, country, placetype)` — the same {@link normalizeLocalityForKey} the
- *   candidate build uses for its probe key, so the two sides fold identically by construction.
+ *   `place_importance.importance` lands in the column verbatim, the pre-split conflation that is
+ *   encyclopedia-derived where the concordance matched and a population-derived proxy everywhere
+ *   else. See {@link CandidateTable.importance} for why the split `encyclopedic` channel is not what
+ *   is written here.
  *
- *   ## Why the key alone is not enough
- *
- *   `(warwick, US, locality)` names ELEVEN different places. Taking the group's max would give every
- *   Warwick in America the fame of Warwick, Rhode Island, which is the fan-out defect
- *   `importance-fanout.ts` documents one layer up, re-introduced at the join. So the group is
- *   disambiguated GEOGRAPHICALLY: the nearest centroid wins, and only within
- *   {@link IMPORTANCE_JOIN_RADIUS_KM}. Two artifacts describing the same settlement put its centroid in
- *   almost the same place; two same-named towns in one country do not.
- *
- *   ## What lands in the column
- *
- *   `place_importance.importance` VERBATIM — the pre-split conflation (encyclopedia-derived where
- *   the concordance matched, a population-derived proxy everywhere else). See
- *   {@link CandidateTable.importance} for why the split `encyclopedic` channel is deliberately NOT
- *   what is written here, with the measurement that settled it.
- *
- *   A place with no match gets NULL. NULL is UNMEASURED, never zero — the consumer
- *   (`resolver/toponym-prior.ts`) leaves an unmeasured candidate exactly where population put it.
+ *   A place with no match gets NULL. NULL means the place's fame is unmeasured.
+ *   The consumer (`resolver/toponym-prior.ts`) leaves an unmeasured candidate at the position
+ *   population assigned it.
  */
+import type { PathBuilderLike } from "path-ts";
 /**
  * How far apart two artifacts may put the same place's centroid and still be read as the same place.
  *
- * MEASURED, not guessed (2026-08-10, `admin-global-priority.db` × `admin-global-priority-importance.db`; 4,476,245
- * current locality-tier places against 676,790 scored ones, 1,020,099 of which matched a scored group by `(name_key,
- * country, placetype)`). The nearest-centroid distance is **exactly 0.00 km for 577,080 of them (56.6%)** — the two
- * snapshots agree to the bit — and 656,755 (64.4%) are inside 500 m.
+ * Measured from two admin snapshots.
+ * The nearest-centroid distances separate into a mode where the two snapshots agree
+ * and a background rate of two different towns wearing one name in one country.
  *
- * What sets the radius is where that mode ENDS, and the per-kilometre density states. It falls from 1,076 places/km
- * over 3–5 km to a trough of **441 places/km over 7–10 km**, then climbs back and flattens onto a plateau of 760–780
- * places/km from 30 km out to 100 km and beyond. That plateau is the background rate of two DIFFERENT towns wearing one
- * name in one country, and it does not decay with distance because there is no reason it should. 10 km is the floor
- * between the two populations. Admitting it scores 679,163 places (66.6% of the matched set); pushing the radius to 25
- * km buys 8,722 more, and by then better than half of each additional kilometre is the wrong town.
+ * The background rate does not decay with distance.
+ * Ten kilometers separates the two populations.
  *
- * The four-row bare-GB board is insensitive across this whole range — 5 km and 25 km were both measured and select
- * identical rows — so the value is chosen by what the join MEANS, not by what it scores. The radius is the definition
- * of "this is the same place"; widening it past the floor starts handing one town's fame to another.
+ * That distance matches the join's purpose.
+ * A radius above the floor starts handing one town's fame to another.
  */
 export declare const IMPORTANCE_JOIN_RADIUS_KM = 10;
 /**
- * One scored place from the source: where it is, and what it scored.
+ * One scored place from the source, with its coordinates and importance score.
  */
 interface ScoredPlace {
     lat: number;
@@ -69,8 +52,10 @@ interface ScoredPlace {
     importance: number;
 }
 /**
- * What {@link loadImportanceIndex} measured while reading the source. Reported by the builder so a run says how much of
- * the gazetteer it actually scored, rather than leaving the caller to infer it from a column full of nulls.
+ * What {@link loadImportanceIndex} measured while reading the source.
+ *
+ * Reported by the builder so a run reports how much of the gazetteer it actually scored,
+ * rather than leaving the caller to infer it from a column full of nulls.
  */
 export interface ImportanceIndexStats {
     /**
@@ -82,7 +67,8 @@ export interface ImportanceIndexStats {
      */
     keys: number;
     /**
-     * Places whose name folded to the empty key and could never be joined (non-Latin punctuation-only names, blanks).
+     * Places whose name folded to the empty key and could never be joined
+     * (non-Latin punctuation-only names, blanks).
      */
     unkeyable: number;
 }
@@ -97,36 +83,45 @@ export declare class ImportanceIndex {
      */
     matched: number;
     /**
-     * Places {@link find} REFUSED — the key matched a scored group, but the nearest member of it was outside the radius,
+     * Places {@link find} refused.
+     *
+     * The key matched a scored group, but the nearest member was outside the radius,
      * so it is a different place wearing the same name.
      *
-     * This is the number worth watching across rebuilds. A jump means the score source and the admin source have drifted
-     * apart and the join is being asked to guess; it does not mean the radius is too tight.
+     * This is the number worth watching across rebuilds.
+     * A jump means the score source and the admin source have drifted apart
+     * and the join is being asked to guess.
+     * It does not mean the radius is too tight.
      */
     refused: number;
     constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats);
     /**
-     * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country` and `placetype`, or
-     * null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+     * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country`
+     * and `placetype`, or null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+     *
+     * Null is unmeasured.
+     * Keep the value null.
+     * Do not substitute zero or a population-derived value here.
      *
-     * Null is UNMEASURED. Never substitute a zero, and never fall back to a population-derived value here — the source
-     * column already carries that fallback where it has one, and inventing a second one would make an absence
-     * indistinguishable from a measurement.
+     * The source column already contains a population-derived fallback where one exists.
+     * A second fallback would make an absence indistinguishable from a measurement.
      */
     find(name: string, country: string | null, placetype: string | null, lat: number, lon: number): number | null;
 }
 /**
- * Read `place_importance` (joined to `spr` for the name/country/placetype/centroid) out of a WOF admin database into an
- * {@link ImportanceIndex}.
+ * Read `place_importance` from a WOF admin database and join it to `spr`.
+ *
+ * The join retrieves each place's name, country, placetype, plus its centroid.
+ * These fields populate an {@link ImportanceIndex}.
+ *
+ * Only current, non-deprecated places are indexed.
+ * A superseded row's score belongs to a place the gazetteer no longer contains.
  *
- * Only CURRENT, non-deprecated places are indexed — a superseded row's score belongs to a place the gazetteer no longer
- * carries, and letting it win the nearest-centroid contest would hand a live place a dead one's fame.
+ * If that row won the nearest-centroid contest, a live place would inherit the superseded place's fame.
  *
- * The whole table is held in memory on purpose. The 2026-08-10 source holds 676,790 scored places in 544,823 groups,
- * and the build probes it once for every one of its ~4.8 M places; the alternative is a prepared statement per place
- * against a 3.7 GB database. Measured end to end, loading the index plus probing all 4.48 M locality-tier places takes
- * 25 s.
+ * The whole table is held in memory on purpose, because the build probes it once for every place
+ * and the alternative is a prepared statement per place against a multi-gigabyte database.
  */
-export declare function loadImportanceIndex(databasePath: string): ImportanceIndex;
+export declare function loadImportanceIndex(databasePath: PathBuilderLike): ImportanceIndex;
 export {};
 //# sourceMappingURL=importance.d.ts.map

package/out/candidate/importance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"importance.d.ts","sourceRoot":"","sources":["../../lib/candidate/importance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAQH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAE3C;;GAEG;AACH,UAAU,WAAW;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAUD;;GAEG;AACH,qBAAa,eAAe;;IAE3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC;;OAEG;IACH,OAAO,SAAI;IACX;;;;;;OAMG;IACH,OAAO,SAAI;IAEX,YAAY,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAG1E;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8B5G;CACD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAwCzE"}
+{"version":3,"file":"importance.d.ts","sourceRoot":"","sources":["../../lib/candidate/importance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAK9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAE3C;;GAEG;AACH,UAAU,WAAW;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAYD;;GAEG;AACH,qBAAa,eAAe;;IAE3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC;;OAEG;IACH,OAAO,SAAI;IACX;;;;;;;;;;OAUG;IACH,OAAO,SAAI;IAEX,YAAY,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAG1E;IAED;;;;;;;;;;OAUG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8B5G;CACD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,eAAe,GAAG,eAAe,CAwClF"}