@mailwoman/resolver-wof-sqlite 9.1.0 → 9.3.0

package/out/{ancestry-backfill.d.ts → ancestry/backfill.d.ts}

@@ -44,7 +44,9 @@
  *   test: each (id, ancestor_id) is inserted at most once, so a second run over the same DB adds
  *   nothing.
  */
-import type { DatabaseSync } from "node:sqlite";
+import type { DatabaseClient } from "@mailwoman/sqlite/client";
+import { type PathBuilderLike } from "path-ts";
+import type { WOFDatabase } from "#schema";
 export interface AncestryBackfillResult {
     /**
      * Places that gained at least one ancestor row.
@@ -61,12 +63,12 @@ export interface AncestryBackfillResult {
     noGeojson: number;
 }
 /**
- * Discover the `data` directories under a WOF repos root that hold sharded geojson, e.g.
+ * Discover the `data` directories under a WOF repos root that hold attached geojson, e.g.
  * `<root>/whosonfirst-data/whosonfirst-data-admin-us/data`. Resolves an id to its geojson via these roots. Accepts both
  * the nested lab layout (a `whosonfirst-data` group dir holding the admin repos) and a flat layout (admin repos
  * directly under the root); searches at most two directory levels deep.
  */
-export declare function discoverAdminDataRoots(reposRoot: string): string[];
+export declare function discoverAdminDataRoots(reposRoot: PathBuilderLike): Promise<string[]>;
 /**
  * Insert missing ancestor rows for every place whose ancestry chain dead-ended before reaching a country, by reading
  * `wof:hierarchy` from its source geojson under `geojsonRoots` (see {@link discoverAdminDataRoots}). Runs inside a
@@ -79,7 +81,7 @@ export declare function discoverAdminDataRoots(reposRoot: string): string[];
  * ~40-minute one (their ancestry comes from the parent_id closure, not this backfill). Correctness-preserving — the
  * skipped rows would have `noGeojson`-skipped anyway. Omit `maxID` (default) for the legacy WOF-only DBs.
  */
-export declare function backfillAncestorsFromHierarchy(db: DatabaseSync, geojsonRoots: readonly string[], opts?: {
+export declare function backfillAncestorsFromHierarchy(db: DatabaseClient<WOFDatabase>, geojsonRoots: readonly string[], opts?: {
     maxID?: number;
 }): Promise<AncestryBackfillResult>;
-//# sourceMappingURL=ancestry-backfill.d.ts.map
+//# sourceMappingURL=backfill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../../lib/ancestry/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAO1C,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4B1F;AAYD;;;;;;;;;;;GAWG;AACH,wBAAsB,8BAA8B,CACnD,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,EAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3B,OAAO,CAAC,sBAAsB,CAAC,CAkHjC"}

package/out/{ancestry-backfill.js → ancestry/backfill.js}

@@ -44,30 +44,27 @@
  *   test: each (id, ancestor_id) is inserted at most once, so a second run over the same DB adds
  *   nothing.
  */
-import { readdirSync } from "node:fs";
-import { DatabaseClient } from "@mailwoman/core/kysley/client";
+import { readDirectoryEntries } from "@mailwoman/core/fs/readers";
 import { readWOFFeature } from "@mailwoman/core/resources/whosonfirst";
-import { join } from "path-ts";
+import { join, resolvePath } from "path-ts";
 /**
  * Genuinely top-level placetypes — they never have (or need) an ancestor, so skip them.
  */
 const TOP_PLACETYPES = new Set(["country", "continent", "empire", "ocean", "marinearea", "planet"]);
 /**
- * Discover the `data` directories under a WOF repos root that hold sharded geojson, e.g.
+ * Discover the `data` directories under a WOF repos root that hold attached geojson, e.g.
  * `<root>/whosonfirst-data/whosonfirst-data-admin-us/data`. Resolves an id to its geojson via these roots. Accepts both
  * the nested lab layout (a `whosonfirst-data` group dir holding the admin repos) and a flat layout (admin repos
  * directly under the root); searches at most two directory levels deep.
  */
-export function discoverAdminDataRoots(reposRoot) {
+export async function discoverAdminDataRoots(reposRoot) {
     const roots = [];
-    const visit = (dir, depth) => {
+    const visit = async (dir, depth) => {
         if (depth > 2)
             return;
         let names;
         try {
-            names = readdirSync(dir, { withFileTypes: true })
-                .filter((e) => e.isDirectory())
-                .map((e) => e.name);
+            names = (await readDirectoryEntries(dir)).filter((e) => e.isDirectory()).map((e) => e.name);
         }
         catch {
             return;
@@ -78,11 +75,11 @@ export function discoverAdminDataRoots(reposRoot) {
                 roots.push(child);
             }
             else if (name.startsWith("whosonfirst-data")) {
-                visit(child, depth + 1);
+                await visit(child, depth + 1);
             }
         }
     };
-    visit(reposRoot, 0);
+    await visit(resolvePath(reposRoot), 0);
     return roots;
 }
 // `<placetype>_id` key → ancestor placetype. WOF hierarchy keys are e.g. region_id, county_id. Self
@@ -108,12 +105,11 @@ function placetypeFromKey(key) {
  */
 export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}) {
     const maxID = opts.maxID ?? Number.MAX_SAFE_INTEGER;
-    const kdb = new DatabaseClient({ database: db });
     // "No country-tier ancestor" is the dead-end signal at any depth — see the module docstring. The
     // earlier "<= 1 ancestor row" test only caught the dead end's origin, never the children that
     // inherit it (a child of a repaired -4 place has two rows: itself and that parent) (#1445).
     // The id bound is stated first so SQLite prunes by the PK index before the NOT EXISTS runs at all.
-    const candidateBase = kdb
+    const candidateBase = db
         .selectFrom("spr")
         .where("id", "<", maxID)
         .where((eb) => eb.not(eb.exists(eb
@@ -129,7 +125,7 @@ export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}
     // caps a statement at 32,766 bound variables and the wide-coverage build has 67,521 candidates
     // (measured 2026-08-04).
     const alreadyPresent = new Map();
-    for (const row of await kdb
+    for (const row of await db
         .selectFrom("ancestors")
         .select(["id", "ancestor_id"])
         .where("id", "in", candidateBase.select("spr.id"))
@@ -149,7 +145,7 @@ export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}
     for (const { id, placetype } of candidates) {
         if (placetype && TOP_PLACETYPES.has(placetype))
             continue;
-        const gj = readWOFFeature(id, geojsonRoots);
+        const gj = await readWOFFeature(id, geojsonRoots);
         const hierarchy = gj?.properties?.["wof:hierarchy"];
         if (!hierarchy || !hierarchy.length) {
             if (!gj) {
@@ -193,4 +189,4 @@ export async function backfillAncestorsFromHierarchy(db, geojsonRoots, opts = {}
     db.exec("COMMIT");
     return { placesFixed, rowsAdded, noGeojson };
 }
-//# sourceMappingURL=ancestry-backfill.js.map
+//# sourceMappingURL=backfill.js.map

package/out/ancestry/backfill.js.map

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

package/out/{ancestry.d.ts → ancestry/index.d.ts}

@@ -7,14 +7,14 @@
  *   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`,
+ *   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 { DatabaseSync } from "node:sqlite";
+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
@@ -38,7 +38,8 @@ export interface AncestorPlaceRow {
 }
 /**
  * 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.
+ * NOT memoized here; `WOFSQLitePlaceLookup` keeps its own per-id cache.
  */
-export declare function ancestorLineage(db: DatabaseSync, id: number, schemaName?: string): AncestorPlaceRow[];
-//# sourceMappingURL=ancestry.d.ts.map
+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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/ancestry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAI9D;;;;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.js → ancestry/index.js}

@@ -7,13 +7,14 @@
  *   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`,
+ *   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 "#sqlite-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
@@ -40,16 +41,15 @@ export function placetypeDepth(placetype) {
 }
 /**
  * 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.
+ * NOT memoized here; `WOFSQLitePlaceLookup` keeps its own per-id cache.
  */
 export function ancestorLineage(db, id, schemaName = "main") {
-    const rows = db
-        .prepare(`SELECT a.ancestor_id AS id, a.ancestor_placetype AS placetype, s.name AS name,
+    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`)
-        .all(id);
+			WHERE a.id = ? AND a.ancestor_id != a.id`), id);
     rows.sort((a, b) => placetypeDepth(b.placetype) - placetypeDepth(a.placetype));
     return rows;
 }
-//# sourceMappingURL=ancestry.js.map
+export * from "#ancestry/backfill";
+//# sourceMappingURL=index.js.map

package/out/ancestry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/ancestry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC;;;;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/build-candidate.d.ts

@@ -22,7 +22,7 @@
  *
  *   The name_key normalizer is the SHARED {@link normalizeLocalityForKey} — the query side (the demo
  *   resolver {@link WOFCandidateTableLookup}) MUST use the same function, the one-normalizer
- *   discipline the address-point shard uses, so build/query stay consistent by construction.
+ *   discipline the address-point extract uses, so build/query stay consistent by construction.
  *
  *   Measured (2026-06-20, vs the 2.6 GB full-DB FTS): ~5 M rows; ~12 range fetches per 8-query
  *   session (the full DB needs 243); US locality 96.8% (region bbox), EU coord parity 88.6%.
@@ -32,7 +32,16 @@
  *   `candidate-importance.ts`, which owns that join and explains why the id would be wrong). It is
  *   optional: without {@link BuildCandidateOptions.importance} the column is NULL on every row, which
  *   the consumer reads as unmeasured and ignores.
+ *
+ *   The build also materializes the ANCESTORS SIDECAR (`candidate_ancestor` closure rows +
+ *   `candidate_interval` pre/post labels) from the source `ancestors` table — the containment
+ *   lineage behind {@link WOFCandidateTableLookup.ancestors} and the admin-coherence check.
+ *   `candidate-ancestors-schema.ts` owns the encoding decision and the DAG/absence semantics.
  */
+import type { CapitalPoint } from "#capitals";
+export { stageCountryDisplayNames } from "#candidate/country-display-names";
+export { GLOSS_EXCLUDED_PLACETYPES, GLOSS_KEY_THRESHOLD } from "#candidate/name-roles";
+export type { PlaceAttrs } from "#candidate/place-attrs";
 export interface BuildCandidateOptions {
     /**
      * Source unified admin DB — needs spr, place_population, place_search, place_abbr, ancestors.
@@ -43,14 +52,28 @@ export interface BuildCandidateOptions {
      */
     output: string;
     /**
-     * Optional postcode shards (`spr` rows with `placetype='postalcode'` + real coords, e.g. postalcode-us.db) — folded
+     * The capital-status reference entries (#1880) to carry in-artifact — the parsed `data/gazetteer/capitals-v1.json`
+     * entries, passed by the CALLER because this module publishes to npm and must not read repo-root paths. Absent → the
+     * `capital` table is not created, and the session loader falls back to the repo file where one exists.
+     */
+    capitals?: readonly CapitalPoint[];
+    /**
+     * Optional postcode extracts (`spr` rows with `placetype='postalcode'` + real coords, e.g. postalcode-us.db) — folded
      * in as `postalcode` candidate rows so `findPlace(postalcode)` resolves a ZIP directly (the demo's primary postcode
      * path; the postcode-*.bin anchor stays the fallback). Matches the slim wof-hot.db, which took one such postcode DB.
      *
-     * Each shard's `names` table is folded in too (#1495) — that's where the GeoNames delivery-city names live
+     * Each extract's `names` table is folded in too (#1495) — that's where the GeoNames delivery-city names live
      * ("Brooklyn" for 11201), and they were previously reachable only through FTS.
      */
     postcodes?: string[];
+    /**
+     * Optional LOCALITY extracts (`spr` rows with `placetype='locality'` + real coords, e.g. localities-nz-linz.db — the
+     * #1564 NZ suburb tier) — folded through the same extract loop as the postcode extracts, staged as `locality`
+     * candidate rows with no region scope and UNMEASURED population (`neg_rank 0`: a extract row ranks behind any
+     * populated namesake and wins only where its key is the answer). Each extract's `names` table folds as aliases,
+     * `is_primary = 0`, same as the delivery-city pass.
+     */
+    localities?: string[];
     /**
      * Optional WOF admin database carrying a `place_importance` table — the source of the `importance` column (#28), the
      * toponym-fame prior that decides the bare-city-name class. Joined by `(name_key, country, placetype)` + nearest
@@ -63,10 +86,36 @@ export interface BuildCandidateOptions {
      * population-derived stand-in written into a column that means fame.
      */
     importance?: string;
+    /**
+     * Cross-source currency backfill (#1737). WOF carries deprecated-with-no-successor records for real, populated
+     * settlements (Rochester Kent, Aldershot, Telford — 120 GB localities alone), and the currency filter correctly drops
+     * them, leaving holes no ranking can fill. When this option is set, pass 1c resurrects a dead locality ONLY under
+     * three conditions, positive evidence throughout: no live same-name row of any placetype near the dead record (a
+     * distant same-name row is a NAMESAKE and does not block — Rochester, Northumberland pop 318 must not veto Rochester,
+     * Kent); an independent GeoNames P-class attestation of the same folded name within
+     * {@link CURRENCY_BACKFILL_RADIUS_KM}; and the attestor at or above {@link CURRENCY_BACKFILL_POP_FLOOR}. The staged
+     * row keeps the real WOF id, name, centroid and bbox — GeoNames only ATTESTS the place and supplies the population
+     * that lets it stand in prominence races. `countries` are judged only where `<cc>.txt` exists under `geonamesDir`;
+     * absent dumps are skipped loudly.
+     */
+    currencyBackfill?: {
+        geonamesDir: string;
+        countries: readonly string[];
+        /**
+         * The dead placetypes the resurrection judges; `resurrectCurrencyHoles`'s default (`locality`) when absent. The
+         * `localadmin` widening #1746 named is admitted here once its census is read.
+         */
+        deadPlacetypes?: readonly string[];
+    };
     /**
      * Optional progress callback for CLI / test introspection.
      */
     onProgress?: (phase: string, message: string) => void;
+    /**
+     * Key-count threshold for the gloss anomaly detector — {@link GLOSS_KEY_THRESHOLD} unless a test passes a
+     * fixture-scale value. The production number is the #1730 sweep's own threshold (4,000 places at >= 50 keys).
+     */
+    glossKeyThreshold?: number;
 }
 export interface BuildCandidateResult {
     rows: number;
@@ -76,11 +125,26 @@ export interface BuildCandidateResult {
     abbrevs: number;
     postcodes: number;
     /**
-     * Delivery-city (and other `names`-table) aliases folded onto postcode rows — #1495. Zero here means the shards
-     * carried no alias names, NOT that the pass was skipped: a shard with no `names` table reports that separately
+     * Delivery-city (and other `names`-table) aliases folded onto postcode rows — #1495. Zero here means the extracts
+     * carried no alias names, NOT that the pass was skipped: a extract with no `names` table reports that separately
      * through `onProgress`.
      */
     postcodeAliases: number;
+    /**
+     * Closure rows in the `candidate_ancestor` sidecar (see candidate-ancestors-schema.ts). Zero means the source
+     * `ancestors` table contributed nothing within the resolvable placetypes — a finding, reported rather than implied.
+     */
+    ancestorRows: number;
+    /**
+     * Places carrying at least one closure row.
+     */
+    ancestorPlaces: number;
+    /**
+     * Places that received a pre/post interval label — the canonical-parent forest's node count. Places outside it (no
+     * recorded ancestry, extract rows, cycle-skipped) have NO label: containment against them is unverifiable, never
+     * false.
+     */
+    intervalPlaces: number;
     /**
      * Places that took an `importance` score from the join (#28).
      *
@@ -90,12 +154,29 @@ export interface BuildCandidateResult {
     importanceScored?: number;
     /**
      * Places whose `(name_key, country, placetype)` matched a scored group but whose nearest scored centroid was outside
-     * {@link IMPORTANCE_JOIN_GATE_KM} — a different town wearing the same name, refused rather than scored.
+     * {@link IMPORTANCE_JOIN_RADIUS_KM} — a different town wearing the same name, refused rather than scored.
      *
      * Worth watching across rebuilds: a jump here means the score source and the admin source have drifted apart, and the
      * join is being asked to guess.
      */
-    importanceGated?: number;
+    importanceFiltered?: number;
+    /**
+     * Alias rows stamped `name_role = 'gloss'` — the anomaly detector's certain core (#1730).
+     */
+    roleGloss: number;
+    /**
+     * Alias rows stamped `name_role = 'abbr'` — the variant-in-official-language provenance signal (#1730/#936).
+     */
+    roleAbbr: number;
+    /**
+     * Admin places whose staged key count reached {@link GLOSS_KEY_THRESHOLD} — the sweep's tail, reported so the stamped
+     * fraction has its denominator.
+     */
+    keyTailPlaces: number;
+    /**
+     * Of {@link BuildCandidateResult.keyTailPlaces}, how many carry at least one stamped role row.
+     */
+    keyTailWithRole: number;
 }
 export declare function buildCandidateTable(opts: BuildCandidateOptions): Promise<BuildCandidateResult>;
 //# sourceMappingURL=build-candidate.d.ts.map

package/out/build-candidate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-candidate.d.ts","sourceRoot":"","sources":["../build-candidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsBH,MAAM,WAAW,qBAAqB;IACrC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACxB;AAwBD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8apG"}
+{"version":3,"file":"build-candidate.d.ts","sourceRoot":"","sources":["../lib/build-candidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAsBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAO7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAA;AAC3E,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AACtF,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,MAAM,WAAW,qBAAqB;IACrC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAClC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE;QAClB,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;QAC5B;;;WAGG;QACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAClC,CAAA;IACD;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACrD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;CACvB;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwZpG"}