@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/out/build/population-corrections.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Populations the gazetteer records at a fraction of their size, corrected against the record's own concordance.
+ *
+ *   This file records corrections for review. The build must not rewrite populations from a
+ *   same-name-parent ratio. The detector cannot distinguish a district's mis-recorded namesake
+ *   city from a small village with the district name. Both places are real.
+ *
+ *   Each entry identifies one row that a reviewer checked against a second source.
+ *   The row's own `gn:id` must agree with the coordinates. The GeoNames record must identify the same place.
+ *
+ *   The correction applies to the candidate artifact rather than the admin gazetteer.
+ *   `place_population` in `admin-global-priority.db` still stores the WOF figure, so a reader going
+ *   there sees WOF's value and a reader going to `candidate.db` sees the corroborated number. The
+ *   admin database is a transcription of its source, so correcting it there would make the
+ *   transcription disagree with what it transcribes.
+ */
+/**
+ * One corrected population, with what corroborates it.
+ */
+export interface PopulationCorrection {
+    /**
+     * The GeoNames id from the WOF record's own `concordances` row makes this a
+     * correction rather than a substitution.
+     *
+     * The two sources describe the same place according to WOF.
+     */
+    geonamesID: string;
+    population: number;
+    /**
+     * What the gazetteer recorded, kept so a reader can see the size of the
+     * disagreement without opening the artifact.
+     */
+    recorded: number;
+    /**
+     * The place and the reviewer's reading.
+     */
+    note: string;
+}
+/**
+ * WOF id → the corrected population.
+ *
+ * One entry, because one row has been followed.
+ * A second correction requires the same review.
+ *
+ * Read the row's `gn:id` and confirm the coordinates agree.
+ * Then record the second source's value.
+ */
+export declare const POPULATION_CORRECTIONS: Readonly<Record<number, PopulationCorrection>>;
+//# sourceMappingURL=population-corrections.d.ts.map

package/out/build/population-corrections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"population-corrections.d.ts","sourceRoot":"","sources":["../../lib/build/population-corrections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAWjF,CAAA"}

package/out/build/population-corrections.js

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Populations the gazetteer records at a fraction of their size, corrected against the record's own concordance.
+ *
+ *   This file records corrections for review. The build must not rewrite populations from a
+ *   same-name-parent ratio. The detector cannot distinguish a district's mis-recorded namesake
+ *   city from a small village with the district name. Both places are real.
+ *
+ *   Each entry identifies one row that a reviewer checked against a second source.
+ *   The row's own `gn:id` must agree with the coordinates. The GeoNames record must identify the same place.
+ *
+ *   The correction applies to the candidate artifact rather than the admin gazetteer.
+ *   `place_population` in `admin-global-priority.db` still stores the WOF figure, so a reader going
+ *   there sees WOF's value and a reader going to `candidate.db` sees the corroborated number. The
+ *   admin database is a transcription of its source, so correcting it there would make the
+ *   transcription disagree with what it transcribes.
+ */
+/**
+ * WOF id → the corrected population.
+ *
+ * One entry, because one row has been followed.
+ * A second correction requires the same review.
+ *
+ * Read the row's `gn:id` and confirm the coordinates agree.
+ * Then record the second source's value.
+ */
+export const POPULATION_CORRECTIONS = {
+    102_030_887: {
+        geonamesID: "1278149",
+        population: 1_175_116,
+        recorded: 19_172,
+        note: "Aurangabad (Chhatrapati Sambhaji Nagar), Maharashtra. The WOF record sits at 19.870 / 75.349 and GeoNames " +
+            "1278149 — the id that record's own concordance names — sits at 19.878 / 75.342, about 1 km apart, classed " +
+            "`PPLA2`. WOF's 19,172 against its parent district's 3,701,282 is the 193x ratio that surfaced it; the " +
+            "corroborated figure makes the city 32% of its district rather than 0.5% of it.",
+    },
+};
+//# sourceMappingURL=population-corrections.js.map

package/out/build/population-corrections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"population-corrections.js","sourceRoot":"","sources":["../../lib/build/population-corrections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAyBH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAmD;IACrF,WAAW,EAAE;QACZ,UAAU,EAAE,SAAS;QACrB,UAAU,EAAE,SAAS;QACrB,QAAQ,EAAE,MAAM;QAChB,IAAI,EACH,4GAA4G;YAC5G,4GAA4G;YAC5G,wGAAwG;YACxG,gFAAgF;KACjF;CACD,CAAA"}

package/out/build/slim.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import type { PathBuilderLike } from "path-ts";
+export interface BuildSlimOptions {
+    /**
+     * Input WOF SQLite distributions, each already carrying spr / names / place_population tables.
+     */
+    inputs: readonly PathBuilderLike[];
+    /**
+     * Output path for the slim DB, overwritten if it exists.
+     */
+    output: PathBuilderLike;
+    /**
+     * Country codes to keep (ISO 2-letter); defaults to `["US"]`.
+     */
+    countries?: string[];
+    /**
+     * Cap on the number of localities to keep per country, by descending population.
+     */
+    topLocalitiesPerCountry?: number;
+    /**
+     * Drop the `names` table after the FTS index is built; `place_search` is self-contained
+     * and the resolver never reads `names` at runtime.
+     */
+    dropNames?: boolean;
+    onProgress?: (phase: SlimBuildPhase, detail: string) => void;
+}
+export type SlimBuildPhase = "init" | "schema" | "country" | "region" | "county" | "locality" | "postcode" | "names" | "place_population" | "coincident_roles" | "place_abbr" | "fts" | "vacuum" | "done";
+export interface BuildSlimResult {
+    outputPath: string;
+    outputBytes: number;
+    rowCounts: {
+        spr: number;
+        names: number;
+        placeSearch: number;
+        placeBbox: number;
+        placePopulation: number;
+    };
+}
+export declare function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<BuildSlimResult>;
+//# sourceMappingURL=slim.d.ts.map

package/out/build/slim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slim.d.ts","sourceRoot":"","sources":["../../lib/build/slim.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAK9C,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;IAClC;;OAEG;IACH,MAAM,EAAE,eAAe,CAAA;IACvB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5D;AAED,MAAM,MAAM,cAAc,GACvB,MAAM,GACN,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,UAAU,GACV,OAAO,GACP,kBAAkB,GAClB,kBAAkB,GAClB,YAAY,GACZ,KAAK,GACL,QAAQ,GACR,MAAM,CAAA;AAET,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE;QACV,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,EAAE,MAAM,CAAA;KACvB,CAAA;CACD;AAoCD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4G3F"}

package/out/{build-slim.js → build/slim.js}

@@ -2,52 +2,23 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Build a "slim" Who's On First SQLite distribution that's small enough to ship as a static asset
- *   for the browser-side mailwoman demo (Path B of the demo plan). The full admin distribution is
- *   ~2 GB; the slim variant aims for the ~50–100 MB range by keeping only the places a public demo
- *   will actually query for.
- *
- *   Selection policy (v1, US-focused):
- *
- *   - All countries / regions / counties / boroughs in the configured `countries` set, so the ancestor
- *       chain a locality / postcode reports through `parent_id` stays intact.
- *   - Top-K localities by population (read from the source's pre-built `place_population` aux table) in
- *       those countries.
- *   - All postcodes in those countries — they're small and addressing-relevant.
- *   - All `names` + `place_population` rows for selected place IDs.
- *   - The `coincident_roles` dual-role relation (#402), filtered to surviving spr ids.
- *
- *   No geojson, by design. The upstream WOF GeoJSON bodies live ONLY in the raw `whosonfirst-data-*`
- *   repos; `scripts/build-unified-wof.ts` extracts `wof:population` straight into
- *   `place_population` (and the bbox into `spr`) at ingest and never persists a `geojson` table. So
- *   the source admin DB carries population in `place_population`, and this builder consumes it
- *   directly — there is nothing to extract from, and nothing to drop.
- *
- *   The output DB has the resolver-facing schema: `spr`, `names`, `place_population`, plus the
- *   `place_search` FTS5 / `place_bbox` R*Tree virtual tables rebuilt against the trimmed row set
- *   (both derive purely from `spr` + `names` — see `fts.ts`). That means `WOFSQLitePlaceLookup`
- *   opens the slim DB without any code change — it sees a smaller universe, nothing more.
- *
- *   Multi-extract inputs (e.g. admin + postcode) are processed in sequence; selected rows accumulate
- *   into the single output DB. The postcode extract contributes only postcodes; admin contributes
- *   everything else. Empty / missing input paths are skipped (callers pass `""` when a extract, such
- *   as a custom postcode DB, isn't built yet).
  */
 import { statPath, pathExists } from "@mailwoman/core/fs/readers";
 import { temporaryDirectory } from "@mailwoman/core/fs/temporary";
 import { copyFileTo, removePath } from "@mailwoman/core/fs/writers";
+import { stringifyJSON } from "@mailwoman/core/json";
 import { countRows } from "@mailwoman/sqlite";
 import { DatabaseClient } from "@mailwoman/sqlite/client";
-import { sealDatabase } from "@mailwoman/sqlite/sealed-db";
+import { sealDatabase } from "@mailwoman/sqlite/sealed/db";
 import { sql } from "kysely";
-import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE } from "#fts/index";
+import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE } from "#fts";
 /**
  * Placetypes that we always keep so the ancestor chain a selected locality reports stays valid.
  */
 const ANCESTOR_PLACETYPES = ["country", "region", "county", "borough", "macroregion"];
 /**
- * Tables copied verbatim (schema + filtered rows) from each source DB. Anything else is dropped.
+ * Tables copied verbatim (schema + filtered rows) from each source DB.
+ * Anything else is dropped.
  */
 const COPIED_TABLES = ["spr", "names", PLACE_POPULATION_TABLE];
 /**
@@ -58,9 +29,8 @@ export async function buildSlimWOFDatabase(opts) {
     const countries = (opts.countries ?? ["US"]).map((c) => c.toUpperCase());
     const topLocalities = opts.topLocalitiesPerCountry ?? 1000;
     const progress = opts.onProgress ?? (() => { });
-    // Callers pass `""` for extracts that don't exist yet (e.g. a not-yet-built custom postcode DB).
-    // Skip empties up front; require every remaining path to exist.
-    const inputs = opts.inputs.filter((p) => p.length > 0);
+    // An empty string marks an input that isn't built yet, so empties are skipped and every remaining path must exist.
+    const inputs = opts.inputs.map((input) => input.toString()).filter((p) => p.length);
     if (!inputs.length)
         throw new Error("no input WOF dbs provided");
     for (const input of inputs) {
@@ -71,10 +41,8 @@ export async function buildSlimWOFDatabase(opts) {
     if (await pathExists(opts.output)) {
         await removePath(opts.output);
     }
-    // Open the output DB and create the empty schema. We discover the schema from the FIRST input
-    // (raw sqlite_master read — Kysely doesn't model that) so the output mirrors source column
-    // ordering / types. `CREATE TABLE AS SELECT` flattens types to dynamic, which would break
-    // callers that rely on column-affinity behavior.
+    // The output schema is replayed from the first input's sqlite_master so column ordering
+    // and affinity survive; `create table AS select` would flatten types to dynamic.
     const out = new DatabaseClient(opts.output);
     let result;
     try {
@@ -85,60 +53,46 @@ export async function buildSlimWOFDatabase(opts) {
                 .prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?`)
                 .get(table);
             if (createSQL?.sql) {
-                // Raw DDL by design (introspect-and-replay): we exec the SOURCE DB's own CREATE TABLE
-                // string read from sqlite_master, so a static Kysely builder can't express it. See AGENTS.md.
+                // Raw DDL by design: the source DB's own create-table string cannot be expressed by a static Kysely builder.
                 out.exec(createSQL.sql);
             }
             else if (table === PLACE_POPULATION_TABLE) {
-                // Older source builds may predate the aux table — create it empty so the per-source
-                // copy + ranking have somewhere to land. Sparse-by-design; missing rows are fine.
+                // Older source builds may predate the aux table, so create it empty for the copy and ranking.
                 out.exec(PLACE_POPULATION_DDL);
             }
             else {
                 throw new Error(`source DB ${inputs[0]} is missing required table '${table}'`);
             }
         }
-        // PRIMARY KEY on spr.id + place_population.id come from the schemas we copied; an explicit
-        // index on names.id helps the per-id INSERT SELECT later.
+        // The copied schemas define the primary keys.
+        // This index on `names.id` helps the per-id insert select.
         out.exec(`CREATE INDEX IF NOT EXISTS names_id_idx ON names(id);`);
         // Pull rows from each input.
         for (const inputPath of inputs) {
             await copyFromSource(out, out, inputPath, countries, topLocalities, progress);
         }
-        // Build the resolver virtual tables on the trimmed row set. Both place_search (FTS5) and
-        // place_bbox (R*Tree) derive purely from spr + names — no geojson needed (see fts.ts). The
-        // population aux table is NOT rebuilt here: it was copied verbatim above, and fts.ts only
-        // (re)builds it when a `geojson` table is present, which the slim DB intentionally has not.
+        // `place_search` and `place_bbox` derive purely from `spr` + `names`, and the
+        // population aux table is not rebuilt because it was copied verbatim.
         progress("fts", "building place_search / place_bbox on slim DB");
         buildPlaceSearchFTS(out, {
             drop: true, // schema we copied had no FTS tables, but be explicit
             onProgress: (phase, name) => progress("fts", `${phase} ${name}`),
         });
-        // Materialize region/state ABBREVIATIONS into a standalone `place_abbr (id, abbr)` table BEFORE
-        // `names` is (optionally) dropped. The full DB lets the resolver tier an exact-abbrev match by
-        // querying `names` (`#exactMatchIDs`), but the slim DB drops `names` for size — so the
-        // browser resolver gets its own tiny lookup (~hundreds of rows) to do the same data-driven
-        // exact-abbrev tiering ("VT" → Vermont, not a token-matching foreign region) instead of the
-        // demo's hardcoded region-abbreviation map (since deleted). Sourced from the `language='abbr'` rows
-        // `add-region-abbrevs.ts` wrote, already filtered to surviving spr ids via the names copy. The
-        // table is always created (empty when the source predates the abbrev enrichment) so the
-        // resolver can query it unconditionally.
+        // `place_abbr` is materialized before `names` is dropped and always created,
+        // even empty, so the resolver can query it unconditionally.
         progress("place_abbr", "materializing region abbreviations");
         out.exec(`CREATE TABLE IF NOT EXISTS place_abbr (id INTEGER NOT NULL, abbr TEXT NOT NULL)`);
         out.exec(`INSERT INTO place_abbr (id, abbr) SELECT id, name FROM names WHERE language = 'abbr'`);
         out.exec(`CREATE INDEX IF NOT EXISTS place_abbr_by_abbr ON place_abbr (abbr COLLATE NOCASE)`);
         out.exec(`CREATE INDEX IF NOT EXISTS place_abbr_by_id ON place_abbr (id)`);
-        // Capture the names count BEFORE any drop so the build report stays informative.
         const namesRows = countRows(out, "names");
-        // Optionally drop `names` (+ its index) now that the self-contained FTS5 index no longer needs
-        // it. The resolver never reads `names` at query time, so this is pure size reduction.
+        // The resolver never reads `names` at query time, so dropping it and its index is pure size reduction.
         if (opts.dropNames) {
             progress("vacuum", `dropping names table (${namesRows} rows; FTS5 is self-contained)`);
             out.exec(`DROP INDEX IF EXISTS names_id_idx;`);
             out.exec(`DROP TABLE IF EXISTS names;`);
         }
-        // VACUUM the output so the on-disk file reflects just the trimmed row count. Without it the
-        // file size stays inflated from the in-flight INSERT churn.
+        // Vacuum so the on-disk file reflects the trimmed rows rather than the in-flight insert churn.
         progress("vacuum", "VACUUM (final size reduction)");
         out.exec("VACUUM;");
         const rowCounts = {
@@ -148,9 +102,9 @@ export async function buildSlimWOFDatabase(opts) {
             placeBbox: countRows(out, PLACE_BBOX_TABLE),
             placePopulation: countRows(out, PLACE_POPULATION_TABLE),
         };
-        progress("done", JSON.stringify(rowCounts));
+        progress("done", stringifyJSON(rowCounts));
         result = {
-            outputPath: opts.output,
+            outputPath: opts.output.toString(),
             outputBytes: (await statPath(opts.output)).size,
             rowCounts,
         };
@@ -163,25 +117,17 @@ export async function buildSlimWOFDatabase(opts) {
     return result;
 }
 async function copyFromSource(out, kysely, inputPath, countries, topLocalities, progress) {
-    // ATTACH avoids any "load source into memory" step — SQLite walks both files in place. We need
-    // a fresh temp copy because some WOF distributions ship as read-only filesystem mounts and
-    // ATTACH will still want a writable journal on the side; copying to /tmp dodges that without
-    // mutating the canonical files in /mnt/playpen/mailwoman-data/wof/. ATTACH / DETACH stay raw
-    // — Kysely doesn't model them.
+    // A fresh scratch copy is attached so read-only WOF distributions get the writable
+    // journal they need without mutating the canonical files.
     await using tmpScratch = await temporaryDirectory("mailwoman-slim-src-");
-    const scratchPath = tmpScratch.resolve("src.db");
+    const scratchPath = tmpScratch.path("src.db");
     await copyFileTo(inputPath, scratchPath);
-    out.exec(`ATTACH DATABASE '${scratchPath.replaceAll("'", "''")}' AS src;`);
+    out.exec(`ATTACH DATABASE '${scratchPath.toString().replaceAll("'", "''")}' AS src;`);
     try {
-        // Does this extract carry the pre-built population aux table? The admin source does; a bare
-        // postcode extract might not. The locality ranking + population copy below adapt accordingly.
         const srcHasPopulation = Boolean(out.prepare(`SELECT 1 FROM src.sqlite_master WHERE type = 'table' AND name = '${PLACE_POPULATION_TABLE}'`).get());
-        // The SELECT-INSERT queries below go through Kysely. The cross-schema FROM is the only
-        // "interesting" bit: by declaring `src.spr` / `src.names` / `src.place_population` in
-        // `BuildSchema`, Kysely lets us write `selectFrom("src.spr")` with the same column-type
-        // checking as the regular schema. SQLite parses the dotted identifier as a schema-name
-        // qualifier, so this works directly without any aliasing trick.
-        // 1. Ancestor placetypes (country / region / county / etc.) — always-kept.
+        // The `src.spr` declaration and its peers in `BuildSchema` let Kysely
+        // column-check the cross-schema select.
+        // SQLite reads the dotted identifier as a schema qualifier.
         progress("country", `${inputPath}: ancestor placetypes in (${countries.join(",")})`);
         await kysely
             .insertInto("spr")
@@ -194,9 +140,8 @@ async function copyFromSource(out, kysely, inputPath, countries, topLocalities,
             .where("placetype", "in", [...ANCESTOR_PLACETYPES]))
             .onConflict((oc) => oc.doNothing())
             .execute();
-        // 2. Top-K localities by population. Population lives in the pre-built `place_population`
-        // aux table — left-join it so localities without a population row still qualify (sorted
-        // last). If the extract has no population table, fall back to a deterministic id ordering.
+        // Localities without a population row still qualify.
+        // Without the aux table, fall back to a deterministic id ordering.
         progress("locality", `${inputPath}: top-${topLocalities} localities by population`);
         await kysely
             .insertInto("spr")
@@ -212,7 +157,6 @@ async function copyFromSource(out, kysely, inputPath, countries, topLocalities,
             .limit(topLocalities))
             .onConflict((oc) => oc.doNothing())
             .execute();
-        // 3. All postcodes in scope.
         progress("postcode", `${inputPath}: all postcodes`);
         await kysely
             .insertInto("spr")
@@ -225,14 +169,12 @@ async function copyFromSource(out, kysely, inputPath, countries, topLocalities,
             .where("placetype", "=", "postalcode"))
             .onConflict((oc) => oc.doNothing())
             .execute();
-        // 4. Pull names for the IDs we just selected.
         progress("names", `${inputPath}: names rows for selected IDs`);
         await kysely
             .insertInto("names")
             .expression((eb) => eb.selectFrom("src.names").selectAll().where("id", "in", eb.selectFrom("spr").select("id")))
             .onConflict((oc) => oc.doNothing())
             .execute();
-        // 5. Pull population rows for the selected IDs (sparse — only the places WOF has a count for).
         if (srcHasPopulation) {
             progress("place_population", `${inputPath}: population rows for selected IDs`);
             await kysely
@@ -241,11 +183,8 @@ async function copyFromSource(out, kysely, inputPath, countries, topLocalities,
                 .onConflict((oc) => oc.doNothing())
                 .execute();
         }
-        // 6. Carry the coincident_roles relation (#402) when this source has it (the admin DB), so the
-        // slim/demo DB supports dual-role hierarchy completion (on by default). Filtered to surviving
-        // spr ids → no orphans. Tiny (~hundreds of rows). `ancestors` is intentionally NOT copied (huge
-        // + build-only), so we copy the derived table rather than rebuild it. Raw SQL — conditional +
-        // not in the Kysely build schema.
+        // `ancestors` is intentionally not copied, so the derived `coincident_roles`
+        // table is copied and filtered to surviving spr ids.
         const relationSchema = out
             .prepare(`SELECT sql FROM src.sqlite_master WHERE type = 'table' AND name = 'coincident_roles'`)
             .get();
@@ -261,4 +200,4 @@ async function copyFromSource(out, kysely, inputPath, countries, topLocalities,
         out.exec(`DETACH DATABASE src;`);
     }
 }
-//# sourceMappingURL=build-slim.js.map
+//# sourceMappingURL=slim.js.map

package/out/build/slim.js.map

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

package/out/candidate/alias-bags.d.ts

@@ -2,18 +2,26 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 2 of the candidate build — explode `place_search.alt_names` into distinct alias rows.
+ * @file Pass 2 of the candidate build: explode `place_search.alt_names` into distinct alias rows.
  */
 import type { DatabaseClient } from "@mailwoman/sqlite/client";
-import type { CandidateDatabase } from "#candidate-schema";
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs";
+import type { CandidateDatabase } from "#candidate/schema";
 import type { WOFDatabase } from "#schema";
 /**
- * Pass 2 — explode each place's `place_search.alt_names` bag into distinct-key alias rows (`is_primary = 0`), and count
- * each place's distinct staged keys (primary included) — the gloss detector's key-count signal (#1730).
+ * Pass 2: explode each place's `place_search.alt_names` bag into distinct-key alias rows
+ * (`is_primary = 0`), and count each place's distinct staged keys with the primary included.
+ *
+ * With `regionPlacetypeID` and `ccID` given, a region's alias that is another same-country region's
+ * official name is refused and counted rather than staged (see {@link officialNameHoldersByRegion}).
+ * Without them the pass stages every alias.
  */
-export declare function explodeAliasBags(src: DatabaseClient<WOFDatabase>, out: DatabaseClient<CandidateDatabase>, attrs: Map<number, PlaceAttrs>, stageRow: StageRow): {
+export declare function explodeAliasBags(src: DatabaseClient<WOFDatabase>, out: DatabaseClient<CandidateDatabase>, attrs: Map<number, PlaceAttrs>, stageRow: StageRow, opts?: {
+    regionPlacetypeID?: number;
+    ccID?: (code: string | null) => number;
+}): {
     nAlias: number;
     keyCounts: Map<number, number>;
+    regionOfficialRefused: number;
 };
 //# sourceMappingURL=alias-bags.d.ts.map

package/out/candidate/alias-bags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alias-bags.d.ts","sourceRoot":"","sources":["../../lib/candidate/alias-bags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAG1C;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,cAAc,CAAC,WAAW,CAAC,EAChC,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,EACtC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC9B,QAAQ,EAAE,QAAQ,GAChB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA+BpD"}
+{"version":3,"file":"alias-bags.d.ts","sourceRoot":"","sources":["../../lib/candidate/alias-bags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9D,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAqC1C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,cAAc,CAAC,WAAW,CAAC,EAChC,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,EACtC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,GAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;CAAO,GAC/E;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,qBAAqB,EAAE,MAAM,CAAA;CAAE,CAmDnF"}

package/out/candidate/alias-bags.js

@@ -2,38 +2,81 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 2 of the candidate build — explode `place_search.alt_names` into distinct alias rows.
+ * @file Pass 2 of the candidate build: explode `place_search.alt_names` into distinct alias rows.
  */
-import { ALIAS_SEPARATOR } from "#fts/index";
+import { tableExists } from "@mailwoman/sqlite/introspection";
+import { ALIAS_SEPARATOR } from "#fts";
 import { normalizeLocalityForKey } from "#street/normalize";
 /**
- * Pass 2 — explode each place's `place_search.alt_names` bag into distinct-key alias rows (`is_primary = 0`), and count
- * each place's distinct staged keys (primary included) — the gloss detector's key-count signal (#1730).
+ * The official name of every current region, keyed `${country id}\0${name key}` →
+ * region id, from the source `names` table's `official` bit.
+ *
+ * Empty when the source has no `names` table (a fixture, or an extract shape).
+ *
+ * The positive evidence behind the alias refusal below: a name is refused from a region's
+ * bag only when another region of the same country holds it as its official name.
  */
-export function explodeAliasBags(src, out, attrs, stageRow) {
+function officialNameHoldersByRegion(src, ccID) {
+    const keys = new Map();
+    if (!tableExists(src, "names"))
+        return keys;
+    for (const r of src
+        .prepare(`SELECT n.id AS id, n.name AS name, s.country AS country
+			 FROM names n JOIN spr s ON s.id = n.id
+			 WHERE s.placetype = 'region' AND s.is_current != 0 AND s.is_deprecated = 0 AND n.official = 1`)
+        .iterate()) {
+        const k = normalizeLocalityForKey(String(r.name ?? ""));
+        if (k) {
+            keys.set(`${ccID(r.country)}\0${k}`, Number(r.id));
+        }
+    }
+    return keys;
+}
+/**
+ * Pass 2: explode each place's `place_search.alt_names` bag into distinct-key alias rows
+ * (`is_primary = 0`), and count each place's distinct staged keys with the primary included.
+ *
+ * With `regionPlacetypeID` and `ccID` given, a region's alias that is another same-country region's
+ * official name is refused and counted rather than staged (see {@link officialNameHoldersByRegion}).
+ * Without them the pass stages every alias.
+ */
+export function explodeAliasBags(src, out, attrs, stageRow, opts = {}) {
     let nAlias = 0;
+    let regionOfficialRefused = 0;
     const keyCounts = new Map();
+    const official = typeof opts.regionPlacetypeID === "number" && opts.ccID
+        ? officialNameHoldersByRegion(src, opts.ccID)
+        : new Map();
     out.exec("BEGIN");
     for (const r of src.prepare("SELECT wof_id, alt_names FROM place_search").iterate()) {
-        const a = attrs.get(Number(r.wof_id));
+        const id = Number(r.wof_id);
+        const a = attrs.get(id);
         const alt = r.alt_names;
         if (!a || !alt)
             continue;
         const seen = new Set([a.pkey]);
-        // The writer space-pads each separator and appends a trailing one, so every piece arrives with
-        // surrounding whitespace and the last one is empty. `normalizeLocalityForKey` folds both away,
-        // and the empty tail falls out at the `!k` guard below.
+        const isRegion = a.ptid === opts.regionPlacetypeID;
+        // The writer space-pads each separator and appends a trailing one, so every piece
+        // includes surrounding whitespace and the last one is empty.
+        // `normalizeLocalityForKey` folds both away.
         for (const piece of alt.split(ALIAS_SEPARATOR)) {
             const k = normalizeLocalityForKey(piece);
             if (!k || seen.has(k))
                 continue;
             seen.add(k);
-            stageRow(k, a, Number(r.wof_id), 0);
+            if (isRegion) {
+                const holder = official.get(`${a.cid}\0${k}`);
+                if (typeof holder === "number" && holder !== id) {
+                    regionOfficialRefused++;
+                    continue;
+                }
+            }
+            stageRow(k, a, id, 0);
             nAlias++;
         }
-        keyCounts.set(Number(r.wof_id), seen.size);
+        keyCounts.set(id, seen.size);
     }
     out.exec("COMMIT");
-    return { nAlias, keyCounts };
+    return { nAlias, keyCounts, regionOfficialRefused };
 }
 //# sourceMappingURL=alias-bags.js.map

package/out/candidate/alias-bags.js.map

@@ -1 +1 @@
-{"version":3,"file":"alias-bags.js","sourceRoot":"","sources":["../../lib/candidate/alias-bags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC/B,GAAgC,EAChC,GAAsC,EACtC,KAA8B,EAC9B,QAAkB;IAElB,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC3C,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEjB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACrF,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;QACrC,MAAM,GAAG,GAAG,CAAC,CAAC,SAA0B,CAAA;QAExC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG;YAAE,SAAQ;QACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QAEtC,+FAA+F;QAC/F,+FAA+F;QAC/F,wDAAwD;QACxD,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAA;YAExC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAQ;YAC/B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YACX,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;YAEnC,MAAM,EAAE,CAAA;QACT,CAAC;QAED,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;IAC3C,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAElB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;AAC7B,CAAC"}
+{"version":3,"file":"alias-bags.js","sourceRoot":"","sources":["../../lib/candidate/alias-bags.ts"],"names":[],"mappings":"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"}