@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/out/capital-schema.js

@@ -3,26 +3,27 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The `capital` table (#1880's distribution home): the capital-status reference carried INSIDE
- *   `candidate.db`, so an npm consumer who pulled the artifact can run `capital_tier` without the
- *   repo's `data/gazetteer/capitals-v1.json` — which published packages do not ship. One row per
- *   reference entry (241 national capitals + 3,463 admin-1 seats at the 2026-08-24 build); the
- *   loader reads the WHOLE table once into a `CapitalIndex` at session construction, so there is no
- *   per-probe query and no index beyond the rowid.
+ *   The `capital` table: the capital-status reference included inside `candidate.db`, so an npm
+ *   consumer who pulled the artifact can run `capital_tier` without the repo's
+ *   `data/gazetteer/capitals-v1.json`, which published packages do not ship. One row per reference
+ *   entry. The loader reads the whole table once into a `CapitalIndex` at session construction, so
+ *   there is no per-probe query and no index beyond the rowid.
  *
- *   `keys` holds the entry's folded name set as a JSON array — the name-membership conjunct that
- *   keeps the coordinate radius from promoting a capital's same-name neighbours (`capitals.ts`).
+ *   `keys` holds the entry's folded name set as a JSON array, the name-membership conjunct that keeps
+ *   the coordinate radius from promoting a capital's same-name neighbors (`capitals.ts`).
  */
 import { tryParsingJSON } from "@mailwoman/core/json";
 import { hasTable } from "#sqlite-utils";
 /**
- * The table name the builder writes and the reader probes — one word, singular, matching the artifact's other reference
- * tables (`candidate`, `country_codes`).
+ * The table name the builder writes and the reader probes, one word and singular,
+ * matching the artifact's other reference tables (`candidate`, `country_codes`).
  */
 export const CAPITAL_TABLE = "capital";
 /**
- * Create the table on a build in progress. Async because Kysely's schema-builder is; called from the candidate build's
- * DDL phase alongside the other typed builders.
+ * Create the table on a build in progress.
+ *
+ * Async because Kysely's schema-builder is.
+ * Called from the candidate build's DDL phase alongside the other typed builders.
  */
 export async function createCapitalTable(db) {
     await db.schema
@@ -35,9 +36,10 @@ export async function createCapitalTable(db) {
         .execute();
 }
 /**
- * Read the whole reference out of an artifact, or `null` when the artifact predates the table — the caller then falls
- * back to its next source rather than treating an old artifact as "no capitals" (the meaning-of-zero rule: a missing
- * table is UNMEASURED, an empty one is a finding).
+ * Read the whole reference out of an artifact, or `null` when the artifact predates the table.
+ *
+ * The caller then falls back to its next source rather than treating an old artifact as "no
+ * capitals" (the meaning-of-zero rule: a missing table is unmeasured, an empty one is a finding).
  */
 export function readCapitalPoints(db) {
     if (!hasTable(db, CAPITAL_TABLE))

package/out/capital-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"capital-schema.js","sourceRoot":"","sources":["../lib/capital-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAKrD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAA;AAiBtC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAuC,EAAc;IAC5F,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,aAAa,CAAC;SAC1B,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAK,EAAsB;IAC3D,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;QAAE,OAAO,IAAI,CAAA;IAE7C,MAAM,MAAM,GAAmB,EAAE,CAAA;IAEjC,KAAK,MAAM,GAAG,IAAI,EAAE,CAAC,OAAO,CAAC,yDAAyD,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAClH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAE/B,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,QAAQ;YAAE,SAAQ;QAExD,MAAM,IAAI,GAAG,cAAc,CAAW,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;QAEvD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,SAAQ;QAElC,MAAM,CAAC,IAAI,CAAC;YACX,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;YAC5B,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAC9B,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;YAChC,KAAK;YACL,CAAC,EAAE,IAAI;SACP,CAAC,CAAA;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"capital-schema.js","sourceRoot":"","sources":["../lib/capital-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAKrD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAA;AAmBtC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAuC,EAAc;IAC5F,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,aAAa,CAAC;SAC1B,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC7C,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAK,EAAsB;IAC3D,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;QAAE,OAAO,IAAI,CAAA;IAE7C,MAAM,MAAM,GAAmB,EAAE,CAAA;IAEjC,KAAK,MAAM,GAAG,IAAI,EAAE,CAAC,OAAO,CAAC,yDAAyD,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAClH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAE/B,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,QAAQ;YAAE,SAAQ;QAExD,MAAM,IAAI,GAAG,cAAc,CAAW,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;QAEvD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,SAAQ;QAElC,MAAM,CAAC,IAAI,CAAC;YACX,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;YAC5B,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAC9B,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;YAChC,KAAK;YACL,CAAC,EAAE,IAAI;SACP,CAAC,CAAA;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC"}

package/out/capitals.d.ts

@@ -3,24 +3,21 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The CAPITAL-STATUS reference index (#1880) — answers, for one resolved candidate, "is this
- *   place the national capital or an admin-1 seat of its country?". The consumer is the resolver's
+ *   The capital-status reference index answers whether a resolved candidate is its country's national capital or admin-1 seat.
+ *   The consumer is the resolver's
  *   bounded capital promotion (`@mailwoman/resolver`'s `promoteCapitals`, applied after the fame
- *   key on the bare-toponym class); this module only matches, it never ranks. PURE and
- *   platform-free (the #861 parity discipline).
+ *   key on the bare-toponym class). This module only matches and never ranks. It is pure and
+ *   platform-free.
  *
- *   Matching is an IDENTITY test with three conjuncts: same country, within
- *   {@link CAPITAL_MATCH_RADIUS_KM} of the reference point, and the candidate's own folded name a
- *   member of the reference entry's folded name set (name + romanization + the source's alternate
- *   names, so exonym rows — "Vienna" for Wien — still match). All three are required. The
- *   iteration-1 board run matched on country + coordinate alone, and the 25 km radius promoted
- *   capital-ADJACENT namesakes instead of capitals: North Salt Lake beside the Utah seat, a Gujarat
- *   Indiranagar beside Gandhinagar, Via delle Parti beside Perugia. The name set is what makes the
+ *   A match requires the same country and a distance within {@link CAPITAL_MATCH_RADIUS_KM} of the reference point.
+ *   The candidate's folded name must also appear in the reference entry's folded name set (name + romanization + the source's alternate
+ *   names, so exonym rows such as "Vienna" for Wien still match). The name set is what makes the
  *   radius a centroid-drift allowance rather than a catchment.
  */
 /**
- * Capital status of one candidate: national capital, admin-1 seat, or neither. Numeric so the resolver's promotion can
- * compare levels.
+ * Capital status of one candidate: national capital, admin-1 seat, or neither.
+ *
+ * Numeric so the resolver's promotion can compare levels.
  */
 export declare const CAPITAL_LEVEL: {
     readonly none: 0;
@@ -29,13 +26,14 @@ export declare const CAPITAL_LEVEL: {
 };
 export type CapitalLevel = (typeof CAPITAL_LEVEL)[keyof typeof CAPITAL_LEVEL];
 /**
- * How far a candidate row may sit from the reference point and still read as the same place — a centroid-convention
- * allowance (GeoNames point vs WOF centroid on a metro-scale city), not a catchment: the name-membership conjunct is
- * what excludes neighbours inside the radius.
+ * How far a candidate row may sit from the reference point and still read as the same place.
+ *
+ * A centroid-convention allowance for a GeoNames point against a WOF centroid on a metro-scale city.
+ * The name-membership conjunct excludes neighbors inside the radius.
  */
 export declare const CAPITAL_MATCH_RADIUS_KM = 25;
 /**
- * One reference entry, as `data/gazetteer/capitals-v1.json` carries it (`entries[]`).
+ * One reference entry, as recorded in `data/gazetteer/capitals-v1.json` (`entries[]`).
  */
 export interface CapitalPoint {
     /**
@@ -46,24 +44,28 @@ export interface CapitalPoint {
     longitude: number;
     level: "national" | "admin1";
     /**
-     * Folded name keys (name + romanization + alternate names, `normalizeLocalityForKey` fold) — the membership set for
-     * the name conjunct.
+     * Folded name keys (name + romanization + alternate names, `normalizeLocalityForKey` fold).
+     * The membership set for the name conjunct.
      */
     k: string[];
 }
 /**
- * Country-bucketed capital points with the three-conjunct identity probe. Construct from the parsed reference file's
- * `entries` — the loader that reads the file off disk lives with the path owners (`mailwoman`'s resolver backend),
- * keeping this module platform-free.
+ * Country-bucketed capital points with the three-conjunct identity probe.
+ *
+ * Construct from the parsed reference file's `entries`.
+ * The loader that reads the file off disk lives with the path owners
+ * (`mailwoman`'s resolver backend), keeping this module platform-free.
  */
 export declare class CapitalIndex {
     #private;
     constructor(entries: Iterable<CapitalPoint>);
     /**
-     * The highest capital level whose entry passes all three conjuncts for this place. `none` — never a throw — for a
-     * missing name, country, or coordinate, an unknown country, or no matching entry.
+     * The highest capital level whose entry passes all three conjuncts for this place.
+     *
+     * `none`, never a throw, for a missing name, country, or coordinate,
+     * an unknown country, or no matching entry.
      */
-    levelOfPlace(name: string | null | undefined, country: string | null | undefined, latitude: number | null | undefined, longitude: number | null | undefined): CapitalLevel;
+    levelOfPlace(name: string | null, country: string | null, latitude: number | null, longitude: number | null | undefined): CapitalLevel;
     get size(): number;
 }
 //# sourceMappingURL=capitals.d.ts.map

package/out/capitals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capitals.d.ts","sourceRoot":"","sources":["../lib/capitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;;GAGG;AACH,eAAO,MAAM,aAAa;aACzB,IAAI,EAAE,CAAC;aACP,MAAM,EAAE,CAAC;aACT,QAAQ,EAAE,CAAC;CACF,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAA;AAE7E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAA;IAC5B;;;OAGG;IACH,CAAC,EAAE,MAAM,EAAE,CAAA;CACX;AAcD;;;;GAIG;AACH,qBAAa,YAAY;;IAGxB,YAAY,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAmB1C;IAED;;;OAGG;IACH,YAAY,CACX,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,YAAY,CAwBd;IAED,IAAI,IAAI,IAAI,MAAM,CAQjB;CACD"}
+{"version":3,"file":"capitals.d.ts","sourceRoot":"","sources":["../lib/capitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;;;GAIG;AACH,eAAO,MAAM,aAAa;aACzB,IAAI,EAAE,CAAC;aACP,MAAM,EAAE,CAAC;aACT,QAAQ,EAAE,CAAC;CACF,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAA;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAA;IAC5B;;;OAGG;IACH,CAAC,EAAE,MAAM,EAAE,CAAA;CACX;AAcD;;;;;;GAMG;AACH,qBAAa,YAAY;;IAGxB,YAAY,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAmB1C;IAED;;;;;OAKG;IACH,YAAY,CACX,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,YAAY,CAwBd;IAED,IAAI,IAAI,IAAI,MAAM,CAQjB;CACD"}

package/out/capitals.js

@@ -3,26 +3,23 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The CAPITAL-STATUS reference index (#1880) — answers, for one resolved candidate, "is this
- *   place the national capital or an admin-1 seat of its country?". The consumer is the resolver's
+ *   The capital-status reference index answers whether a resolved candidate is its country's national capital or admin-1 seat.
+ *   The consumer is the resolver's
  *   bounded capital promotion (`@mailwoman/resolver`'s `promoteCapitals`, applied after the fame
- *   key on the bare-toponym class); this module only matches, it never ranks. PURE and
- *   platform-free (the #861 parity discipline).
+ *   key on the bare-toponym class). This module only matches and never ranks. It is pure and
+ *   platform-free.
  *
- *   Matching is an IDENTITY test with three conjuncts: same country, within
- *   {@link CAPITAL_MATCH_RADIUS_KM} of the reference point, and the candidate's own folded name a
- *   member of the reference entry's folded name set (name + romanization + the source's alternate
- *   names, so exonym rows — "Vienna" for Wien — still match). All three are required. The
- *   iteration-1 board run matched on country + coordinate alone, and the 25 km radius promoted
- *   capital-ADJACENT namesakes instead of capitals: North Salt Lake beside the Utah seat, a Gujarat
- *   Indiranagar beside Gandhinagar, Via delle Parti beside Perugia. The name set is what makes the
+ *   A match requires the same country and a distance within {@link CAPITAL_MATCH_RADIUS_KM} of the reference point.
+ *   The candidate's folded name must also appear in the reference entry's folded name set (name + romanization + the source's alternate
+ *   names, so exonym rows such as "Vienna" for Wien still match). The name set is what makes the
  *   radius a centroid-drift allowance rather than a catchment.
  */
 import { haversineKm } from "@mailwoman/spatial";
 import { normalizeLocalityForKey } from "#street/normalize";
 /**
- * Capital status of one candidate: national capital, admin-1 seat, or neither. Numeric so the resolver's promotion can
- * compare levels.
+ * Capital status of one candidate: national capital, admin-1 seat, or neither.
+ *
+ * Numeric so the resolver's promotion can compare levels.
  */
 export const CAPITAL_LEVEL = {
     none: 0,
@@ -30,9 +27,10 @@ export const CAPITAL_LEVEL = {
     national: 2,
 };
 /**
- * How far a candidate row may sit from the reference point and still read as the same place — a centroid-convention
- * allowance (GeoNames point vs WOF centroid on a metro-scale city), not a catchment: the name-membership conjunct is
- * what excludes neighbours inside the radius.
+ * How far a candidate row may sit from the reference point and still read as the same place.
+ *
+ * A centroid-convention allowance for a GeoNames point against a WOF centroid on a metro-scale city.
+ * The name-membership conjunct excludes neighbors inside the radius.
  */
 export const CAPITAL_MATCH_RADIUS_KM = 25;
 const LEVEL_OF = {
@@ -40,9 +38,11 @@ const LEVEL_OF = {
     admin1: CAPITAL_LEVEL.admin1,
 };
 /**
- * Country-bucketed capital points with the three-conjunct identity probe. Construct from the parsed reference file's
- * `entries` — the loader that reads the file off disk lives with the path owners (`mailwoman`'s resolver backend),
- * keeping this module platform-free.
+ * Country-bucketed capital points with the three-conjunct identity probe.
+ *
+ * Construct from the parsed reference file's `entries`.
+ * The loader that reads the file off disk lives with the path owners
+ * (`mailwoman`'s resolver backend), keeping this module platform-free.
  */
 export class CapitalIndex {
     #byCountry = new Map();
@@ -65,8 +65,10 @@ export class CapitalIndex {
         }
     }
     /**
-     * The highest capital level whose entry passes all three conjuncts for this place. `none` — never a throw — for a
-     * missing name, country, or coordinate, an unknown country, or no matching entry.
+     * The highest capital level whose entry passes all three conjuncts for this place.
+     *
+     * `none`, never a throw, for a missing name, country, or coordinate,
+     * an unknown country, or no matching entry.
      */
     levelOfPlace(name, country, latitude, longitude) {
         if (!name || !country || typeof latitude !== "number" || typeof longitude !== "number")

package/out/capitals.js.map

@@ -1 +1 @@
-{"version":3,"file":"capitals.js","sourceRoot":"","sources":["../lib/capitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;CACF,CAAA;AAIV;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AAoBzC,MAAM,QAAQ,GAAgD;IAC7D,QAAQ,EAAE,aAAa,CAAC,QAAQ;IAChC,MAAM,EAAE,aAAa,CAAC,MAAM;CAC5B,CAAA;AASD;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACf,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAA;IAEvD,YAAY,OAA+B;QAC1C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAA;YAE3C,MAAM,KAAK,GAAiB;gBAC3B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC5B,IAAI,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;aACtB,CAAA;YAED,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YAE3C,IAAI,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACnB,CAAC;iBAAM,CAAC;gBACP,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;YACtC,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,YAAY,CACX,IAA+B,EAC/B,OAAkC,EAClC,QAAmC,EACnC,SAAoC;QAEpC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,SAAS,KAAK,QAAQ;YAAE,OAAO,aAAa,CAAC,IAAI,CAAA;QAEjH,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;QAEzD,IAAI,CAAC,MAAM;YAAE,OAAO,aAAa,CAAC,IAAI,CAAA;QAEtC,MAAM,GAAG,GAAG,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAA;QAEjD,IAAI,CAAC,GAAG;YAAE,OAAO,aAAa,CAAC,IAAI,CAAA;QAEnC,IAAI,IAAI,GAAiB,aAAa,CAAC,IAAI,CAAA;QAE3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC5B,IACC,KAAK,CAAC,KAAK,GAAG,IAAI;gBAClB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBACnB,WAAW,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,uBAAuB,EAC3F,CAAC;gBACF,IAAI,GAAG,KAAK,CAAC,KAAK,CAAA;YACnB,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,IAAI,IAAI;QACP,IAAI,CAAC,GAAG,CAAC,CAAA;QAET,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,CAAC,IAAI,MAAM,CAAC,MAAM,CAAA;QACnB,CAAC;QAED,OAAO,CAAC,CAAA;IACT,CAAC;CACD"}
+{"version":3,"file":"capitals.js","sourceRoot":"","sources":["../lib/capitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;CACF,CAAA;AAIV;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AAoBzC,MAAM,QAAQ,GAAgD;IAC7D,QAAQ,EAAE,aAAa,CAAC,QAAQ;IAChC,MAAM,EAAE,aAAa,CAAC,MAAM;CAC5B,CAAA;AASD;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACf,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAA;IAEvD,YAAY,OAA+B;QAC1C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAA;YAE3C,MAAM,KAAK,GAAiB;gBAC3B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC5B,IAAI,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;aACtB,CAAA;YAED,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YAE3C,IAAI,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACnB,CAAC;iBAAM,CAAC;gBACP,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;YACtC,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACH,YAAY,CACX,IAAmB,EACnB,OAAsB,EACtB,QAAuB,EACvB,SAAoC;QAEpC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,SAAS,KAAK,QAAQ;YAAE,OAAO,aAAa,CAAC,IAAI,CAAA;QAEjH,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;QAEzD,IAAI,CAAC,MAAM;YAAE,OAAO,aAAa,CAAC,IAAI,CAAA;QAEtC,MAAM,GAAG,GAAG,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAA;QAEjD,IAAI,CAAC,GAAG;YAAE,OAAO,aAAa,CAAC,IAAI,CAAA;QAEnC,IAAI,IAAI,GAAiB,aAAa,CAAC,IAAI,CAAA;QAE3C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC5B,IACC,KAAK,CAAC,KAAK,GAAG,IAAI;gBAClB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBACnB,WAAW,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,uBAAuB,EAC3F,CAAC;gBACF,IAAI,GAAG,KAAK,CAAC,KAAK,CAAA;YACnB,CAAC;QACF,CAAC;QAED,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,IAAI,IAAI;QACP,IAAI,CAAC,GAAG,CAAC,CAAA;QAET,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,CAAC,IAAI,MAAM,CAAC,MAAM,CAAA;QACnB,CAAC;QAED,OAAO,CAAC,CAAA;IACT,CAAC;CACD"}

package/out/coincident-roles.d.ts

@@ -3,50 +3,50 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
- *   unified gazetteer.
+ *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
  *
- *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
- *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
- *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
- *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
- *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
- *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
- *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
- *   distance math.
+ *   Many places occupy multiple admin tiers under one name: German city-states (Berlin, Hamburg,
+ *   Bremen), Italian provinces whose names match their capital (Milano, Varese), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals (Utrecht,
+ *   Groningen), and Shanghai. When an address surfaces only the admin role because the parser
+ *   dropped the locality span, the resolver has no locality to place. The hierarchy-completion step
+ *   consults this relation. The table preserves the gazetteer's own structure, so the runtime is an
+ *   O(1) membership lookup with no distance math.
  *
- *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
- *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
- *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
- *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
- *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
- *   filter.
+ *   V1 is region-tier only (admin.placetype = `region`), the ~124 places matching the census across
+ *   nine countries. County-tier same-name coincidences are excluded because they are dominated by
+ *   French cantons and JP counties, admin subdivisions whose names match a seat town that do not hit the
+ *   parser-drops-locality failure. Consolidated city-counties (US SF, Denver) are a separate
+ *   follow-up needing a relative-size filter.
  *
- *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
- *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
- *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
- *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
- *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
- *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
- *   never enters the resolver hot path.
+ *   A pair `(admin, locality)` is recorded when the names match case-insensitively, the locality descends from the admin in `ancestors`,
+ *   and their centroids fall within a
+ *   relative tolerance of `toleranceFraction × admin-bbox-diagonal`, floored at `minToleranceKm`.
+ *   The relative term lets a large Italian province admit a city tens of km from its centroid while
+ *   a tiny city-state stays tight. The floor catches city-states whose bbox is small (Bremen's
+ *   centroids sit 9.3 km apart). The tolerance lives only here at build time and never enters the
+ *   resolver hot path.
  *
- *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
- *   uniform (see #405). It's a coarse classification, not critical.
+ *   `relationship_type` is recorded for debuggability and deferred per-type behavior. V1 completion
+ *   is uniform. It is a coarse classification.
  *
- *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). Run incrementally
- *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
- *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ *   This mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). It runs
+ *   incrementally against an existing `admin-global-priority.db` via
+ *   `build-coincident-roles-cli.ts`, and it should also be wired as a post-step of the main
+ *   `scripts/build-unified-wof.ts`.
  */
 import type { CoincidentLocality } from "@mailwoman/core/resolver";
 import type { DatabaseClient } from "@mailwoman/sqlite/client";
 import type { WOFDatabase } from "#schema";
 /**
- * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
- * gazetteer build, read by the resolver when a coincident locality has to be chosen.
+ * Table of places that hold more than one admin role.
+ * A locality that is also its county seat.
+ *
+ * Written by the gazetteer build, read by the resolver when a coincident locality has to be chosen.
  */
 export declare const COINCIDENT_ROLES_TABLE = "coincident_roles";
 /**
- * A place that plays multiple admin roles — one row of the relation, keyed by `admin_id`.
+ * A place that plays multiple admin roles, one row of the relation keyed by `admin_id`.
  */
 export interface CoincidentRole {
     localityID: number;
@@ -57,19 +57,27 @@ export interface CoincidentRole {
 }
 export interface BuildCoincidentRolesOpts {
     /**
-     * Drop + rebuild the table if it already exists. Default true (the build is cheap + idempotent).
+     * Drop + rebuild the table if it already exists.
+     *
+     * @defaultValue `true` (the build is cheap + idempotent)
      */
     drop?: boolean;
     /**
-     * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`. Default 0.15.
+     * Relative tolerance: a pair is kept when centroid distance ≤ `toleranceFraction × bbox-diagonal`.
+     *
+     * @defaultValue `0.15`
      */
     toleranceFraction?: number;
     /**
-     * Floor (km) under the relative tolerance, so small-bbox city-states still qualify. Default 12.
+     * Floor (km) under the relative tolerance, so small-bbox city-states still qualify.
+     *
+     * @defaultValue `12`
      */
     minToleranceKm?: number;
     /**
-     * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only). Default 2.
+     * Centroid distance (km) below which a region-tier pair is classed `city-state` (metadata only).
+     *
+     * @defaultValue `2`
      */
     cityStateMaxKm?: number;
     onProgress?: (phase: string, detail?: string) => void;
@@ -81,23 +89,32 @@ export interface BuildCoincidentRolesResult {
     durationMs: number;
 }
 /**
- * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
- * touches `spr`/`names`/`ancestors`. Idempotent.
+ * Derive the coincident-roles relation into `db`.
+ *
+ * Additive, only creating or replacing the `coincident_roles` table.
+ * It never touches `spr`, `names`, or `ancestors`.
+ * Idempotent.
  */
 export declare function buildCoincidentRoles(db: DatabaseClient<WOFDatabase>, opts?: BuildCoincidentRolesOpts): BuildCoincidentRolesResult;
 /**
- * True iff the relation table exists. Used by the resolver to decide whether completion can run.
+ * True iff the relation table exists.
+ *
+ * Used by the resolver to decide whether completion can run.
  */
 export declare function coincidentRolesExists<DB>(db: DatabaseClient<DB>): boolean;
 /**
- * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each admin may map to
- * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
- * map when the table is absent.
+ * Load the relation into an in-memory map keyed by `admin_id` for an O(1) runtime lookup.
+ *
+ * Each admin may map to multiple same-name descendants.
+ * The consumer disambiguates by minimum distance, then population, then abstains.
+ * Returns an empty map when the table is absent.
  */
 export declare function loadCoincidentRoles<DB>(db: DatabaseClient<DB>): Map<number, CoincidentRole[]>;
 /**
- * The relation joined with `spr`, as an in-memory map keyed by `admin_id` — the resolver-facing view of
- * {@link loadCoincidentRoles}, carrying the canonical name and coordinates each coincident locality resolves to.
+ * The relation joined with `spr`, as an in-memory map keyed by `admin_id`.
+ *
+ * The resolver-facing view of {@link loadCoincidentRoles}, carrying the canonical name
+ * and coordinates each coincident locality resolves to.
  * Returns an empty map when the relation table is absent.
  */
 export declare function loadCoincidentLocalities<DB>(db: DatabaseClient<DB>): Map<number, CoincidentLocality[]>;

package/out/coincident-roles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coincident-roles.d.ts","sourceRoot":"","sources":["../lib/coincident-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAGlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,YAAY,GAAG,cAAc,GAAG,qBAAqB,CAAA;IACvE,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,EAAE,MAAM,CAAA;CAClB;AAkBD;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,EAC/B,IAAI,GAAE,wBAA6B,GACjC,0BAA0B,CA8F5B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,OAAO,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAsC7F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAiDtG"}
+{"version":3,"file":"coincident-roles.d.ts","sourceRoot":"","sources":["../lib/coincident-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAGlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAA;AAExD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,YAAY,GAAG,cAAc,GAAG,qBAAqB,CAAA;IACvE,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACrD;AAED,MAAM,WAAW,0BAA0B;IAC1C,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,UAAU,EAAE,MAAM,CAAA;CAClB;AAkBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,EAC/B,IAAI,GAAE,wBAA6B,GACjC,0BAA0B,CAgG5B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,OAAO,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAsC7F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CA4DtG"}

package/out/coincident-roles.js

@@ -3,51 +3,54 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `buildCoincidentRoles` — derives the **coincident-roles relation** (#403, epic #402) into the
- *   unified gazetteer.
+ *   `buildCoincidentRoles` derives the coincident-roles relation into the unified gazetteer.
  *
- *   Many places occupy MULTIPLE admin tiers under one name: German city-states (Berlin/Hamburg/Bremen
- *   = city == state), Italian provinces named after their capital (Milano, Varese…), Spanish
- *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals
- *   (Utrecht/Groningen), Shanghai. When an address surfaces only the admin role (the parser drops
- *   the locality span), the resolver has no locality to place. The hierarchy-completion step (#405)
- *   repairs that by consulting THIS relation; the table replaces #387's hardcoded 15 km constant
- *   with the gazetteer's own structure, so the runtime is an O(1) membership lookup with no
- *   distance math.
+ *   Many places occupy multiple admin tiers under one name: German city-states (Berlin, Hamburg,
+ *   Bremen), Italian provinces whose names match their capital (Milano, Varese), Spanish
+ *   provinces-after-capitals, UK unitary authorities, JP prefectures, NL province-capitals (Utrecht,
+ *   Groningen), and Shanghai. When an address surfaces only the admin role because the parser
+ *   dropped the locality span, the resolver has no locality to place. The hierarchy-completion step
+ *   consults this relation. The table preserves the gazetteer's own structure, so the runtime is an
+ *   O(1) membership lookup with no distance math.
  *
- *   V1 is REGION-tier only (admin.placetype = `region`): the ~124 places matching the census across 9
- *   countries (IT/ES/GB/JP/KR/FR/DE/NL/CN). County-tier same-name coincidences are deliberately
- *   excluded — they're dominated by French cantons and JP counties (admin subdivisions named after
- *   a seat town, not dual-role cities) that don't hit the parser-drops-locality failure; genuine
- *   consolidated city-counties (US SF/Denver) are a separate follow-up needing a relative-size
- *   filter.
+ *   V1 is region-tier only (admin.placetype = `region`), the ~124 places matching the census across
+ *   nine countries. County-tier same-name coincidences are excluded because they are dominated by
+ *   French cantons and JP counties, admin subdivisions whose names match a seat town that do not hit the
+ *   parser-drops-locality failure. Consolidated city-counties (US SF, Denver) are a separate
+ *   follow-up needing a relative-size filter.
  *
- *   A pair `(admin, locality)` is recorded when all hold: same `name` (case-insensitive), the
- *   locality is a `descendant` of the admin (via the `ancestors` table), and their centroids are
- *   within a RELATIVE tolerance — `toleranceFraction × admin-bbox-diagonal`, floored at
- *   `minToleranceKm`. The relative term lets a large Italian province admit a city ~tens of km from
- *   its centroid while a tiny city-state stays tight; the floor catches city-states whose bbox is
- *   small (Bremen's centroids sit 9.3 km apart). The tolerance lives ONLY here at build time — it
- *   never enters the resolver hot path.
+ *   A pair `(admin, locality)` is recorded when the names match case-insensitively, the locality descends from the admin in `ancestors`,
+ *   and their centroids fall within a
+ *   relative tolerance of `toleranceFraction × admin-bbox-diagonal`, floored at `minToleranceKm`.
+ *   The relative term lets a large Italian province admit a city tens of km from its centroid while
+ *   a tiny city-state stays tight. The floor catches city-states whose bbox is small (Bremen's
+ *   centroids sit 9.3 km apart). The tolerance lives only here at build time and never enters the
+ *   resolver hot path.
  *
- *   `relationship_type` is recorded for debuggability / deferred per-type behavior; v1 completion is
- *   uniform (see #405). It's a coarse classification, not critical.
+ *   `relationship_type` is recorded for debuggability and deferred per-type behavior. V1 completion
+ *   is uniform. It is a coarse classification.
  *
- *   Mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). Run incrementally
- *   against an existing `admin-global-priority.db` via `build-coincident-roles-cli.ts`; should also
- *   be wired as a post-step of the main `scripts/build-unified-wof.ts`.
+ *   This mirrors the derived-table builder pattern in `fts.ts` (`buildPlaceSearchFTS`). It runs
+ *   incrementally against an existing `admin-global-priority.db` via
+ *   `build-coincident-roles-cli.ts`, and it should also be wired as a post-step of the main
+ *   `scripts/build-unified-wof.ts`.
  */
 import { allRows } from "@mailwoman/core/utils";
 import { haversineKm } from "@mailwoman/spatial";
 import { tableExists } from "@mailwoman/sqlite/introspection";
 /**
- * Table of places that hold more than one admin role — a locality that is also its county seat. Written by the
- * gazetteer build, read by the resolver when a coincident locality has to be chosen.
+ * Table of places that hold more than one admin role.
+ * A locality that is also its county seat.
+ *
+ * Written by the gazetteer build, read by the resolver when a coincident locality has to be chosen.
  */
 export const COINCIDENT_ROLES_TABLE = "coincident_roles";
 /**
- * Derive the coincident-roles relation into `db`. Additive — only creates/replaces the `coincident_roles` table; never
- * touches `spr`/`names`/`ancestors`. Idempotent.
+ * Derive the coincident-roles relation into `db`.
+ *
+ * Additive, only creating or replacing the `coincident_roles` table.
+ * It never touches `spr`, `names`, or `ancestors`.
+ * Idempotent.
  */
 export function buildCoincidentRoles(db, opts = {}) {
     const start = Date.now();
@@ -61,10 +64,9 @@ export function buildCoincidentRoles(db, opts = {}) {
         db.exec(`DROP TABLE ${COINCIDENT_ROLES_TABLE}`);
     }
     onProgress("creating", COINCIDENT_ROLES_TABLE);
-    // Raw DDL by design: this is a sync builder consumed by a sync CLI (build-coincident-roles-cli) and
-    // 6 sync unit tests, so routing one table through async Kysely would cascade async through all of
-    // them for no real gain. See AGENTS.md "Database / inline SQL". (The SELECT + INSERT loop below are
-    // likewise the raw hot path.)
+    // Raw DDL by design: this is a sync builder consumed by a sync CLI and six sync unit tests,
+    // so routing one table through async Kysely would cascade async through all of them.
+    // See agents.md "Database / inline SQL".
     db.exec(`
 		CREATE TABLE IF NOT EXISTS ${COINCIDENT_ROLES_TABLE} (
 			admin_id INTEGER NOT NULL,
@@ -77,9 +79,11 @@ export function buildCoincidentRoles(db, opts = {}) {
 		)
 	`);
     onProgress("scanning");
-    // Admin (region/county tier) ⋈ same-name DESCENDANT locality. `place_population` is optional (LEFT
-    // JOIN → 0 when absent). The relative-tolerance filter + relationship classification happen in JS so
-    // the SQL stays a plain join. `spr` exposes the bbox columns we need for the diagonal.
+    // Admin (region or county tier) joined to a same-name descendant locality.
+    // `place_population` is optional, so the left join yields 0 when absent.
+    // JavaScript applies the relative-tolerance filter and classifies the relationship.
+    // SQL stays a plain join.
+    // `spr` exposes the bbox columns needed for the diagonal.
     const candidates = allRows(db.prepare(`SELECT r.id AS admin_id, r.placetype AS admin_placetype, r.country AS country, l.id AS locality_id,
 				r.latitude AS rlat, r.longitude AS rlon, l.latitude AS llat, l.longitude AS llon,
 				r.min_latitude, r.min_longitude, r.max_latitude, r.max_longitude,
@@ -105,11 +109,12 @@ export function buildCoincidentRoles(db, opts = {}) {
             const tolerance = Math.max(toleranceFraction * diag, minToleranceKm);
             if (dist > tolerance)
                 continue;
-            // v1 is region-tier only: a place is a `city-state` when its centroid coincides with the
-            // region's (Berlin/Hamburg), else `capital-seat` (a region named after its principal city, e.g.
-            // Milano province → Milano comune). `consolidated-county` is reserved for a future county-tier
-            // pass (US SF/Denver) — excluded from v1 because county-tier same-name coincidences are
-            // dominated by French cantons / JP counties that don't hit the parser-drops-locality failure.
+            // v1 is region-tier only: a place is `city-state` when its centroid coincides with the
+            // region's (Berlin, Hamburg), otherwise `capital-seat` (a region whose name matches its
+            // principal city, such as Milano province and Milano comune). `consolidated-county` is
+            // reserved for a future county-tier pass (US SF, Denver), excluded from v1 because
+            // county-tier same-name coincidences are dominated by French cantons and JP counties
+            // that do not hit the parser-drops-locality failure.
             const relationshipType = dist <= cityStateMaxKm ? "city-state" : "capital-seat";
             insert.run(c.admin_id, c.locality_id, relationshipType, c.admin_placetype, dist, c.pop);
             rowCount++;
@@ -126,15 +131,19 @@ export function buildCoincidentRoles(db, opts = {}) {
     return { created: true, rowCount, byCountry, durationMs: Date.now() - start };
 }
 /**
- * True iff the relation table exists. Used by the resolver to decide whether completion can run.
+ * True iff the relation table exists.
+ *
+ * Used by the resolver to decide whether completion can run.
  */
 export function coincidentRolesExists(db) {
     return tableExists(db, COINCIDENT_ROLES_TABLE);
 }
 /**
- * Load the relation into an in-memory map keyed by `admin_id` for O(1) runtime lookup (#405). Each admin may map to
- * MULTIPLE same-name descendants; the consumer disambiguates (min distance → population → abstain). Returns an empty
- * map when the table is absent.
+ * Load the relation into an in-memory map keyed by `admin_id` for an O(1) runtime lookup.
+ *
+ * Each admin may map to multiple same-name descendants.
+ * The consumer disambiguates by minimum distance, then population, then abstains.
+ * Returns an empty map when the table is absent.
  */
 export function loadCoincidentRoles(db) {
     const map = new Map();
@@ -161,8 +170,10 @@ export function loadCoincidentRoles(db) {
     return map;
 }
 /**
- * The relation joined with `spr`, as an in-memory map keyed by `admin_id` — the resolver-facing view of
- * {@link loadCoincidentRoles}, carrying the canonical name and coordinates each coincident locality resolves to.
+ * The relation joined with `spr`, as an in-memory map keyed by `admin_id`.
+ *
+ * The resolver-facing view of {@link loadCoincidentRoles}, carrying the canonical name
+ * and coordinates each coincident locality resolves to.
  * Returns an empty map when the relation table is absent.
  */
 export function loadCoincidentLocalities(db) {
@@ -185,6 +196,17 @@ export function loadCoincidentLocalities(db) {
                 relationshipType: r.relationshipType,
                 population: r.population,
                 distanceKm: r.distanceKm,
+                parent_id: null,
+                prominence: null,
+                referential: null,
+                encyclopedic: null,
+                importance: null,
+                exactMatch: null,
+                mismatch: null,
+                resolutionQuality: null,
+                containedByQualifier: null,
+                regionScopeMiss: null,
+                variantAliasExempted: null,
             };
             const list = map.get(r.adminID);
             if (list) {