@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/candidate/name-roles.ts

@@ -16,17 +16,15 @@ import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Key-count threshold for the gloss anomaly detector (#1730) — the sweep's own boundary: 4,000 places carried >= 50
- * keys, and a legitimate famous place at that count (New York, 176 keys) is separated by the PROMINENCE check, never by
- * this number alone.
+ * Key-count threshold for the gloss anomaly detector.
+ *
+ * A legitimate famous place is separated by the prominence check rather than this number by itself.
  */
 export const GLOSS_KEY_THRESHOLD = 50
 
 /**
- * Placetypes the gloss detector never flags. A country or region legitimately carries a name in every language — that
- * is what an exonym set IS — so key volume discriminates nothing there. The detector's population is the non-admin
- * tail, where a place named by a common noun ("Poisson", "Sunday") accumulating 200+ translations is a
- * machine-translated gloss set, not fame.
+ * Placetypes the gloss detector never flags: a country or region legitimately has a
+ * name in every language, so key volume provides no signal there.
  */
 export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
 	"country",
@@ -40,21 +38,11 @@ export const GLOSS_EXCLUDED_PLACETYPES: ReadonlySet<string> = new Set([
 ])
 
 /**
- * Pass 3c — the #1730 name-role prototype: two independent detectors over the staged rows, WRITE-ONLY in this
- * generation (no ranking consumer; the rank penalty is its own D-rule-conditional step with the `gloss_key` board as
- * regression check). Both stamp `is_primary = 0` rows only — a place's canonical name and the `place_abbr` region
- * abbreviations are never a gloss or a variant.
- *
- * - `gloss` is ANOMALY-based, and stamps only the certain core: key volume at/over the threshold + a non-admin placetype
- *
- *   - NO measured prominence (population absent AND importance unmeasured). Provenance cannot separate a gloss from an
- *     exonym — WOF imported both as `x_preferred` — and prominence is what rescues New York/Paris.
- * - `abbr` is PROVENANCE-based — the #936 signal: a WOF `variant` name in one of the country's official languages (or
- *   English), measured there at a 13× key-collision rate. A source without a `names` table (fixture-scale admin DBs)
- *   skips this detector loudly.
+ * Stamp `name_role` on non-primary rows: `abbr` by provenance, `variant` by
+ * own-name verdict, then `gloss` by key-volume anomaly.
  *
- * Returns the stamp counts plus the census the prototype exists to report: how much of the ≥-threshold key tail carries
- * any role.
+ * @returns The stamp counts plus the census the prototype exists to report:
+ * how much of the ≥-threshold key tail has any role.
  */
 export function stampNameRoles(ctx: {
 	src: DatabaseClient<WOFDatabase>
@@ -85,7 +73,7 @@ export function stampNameRoles(ctx: {
 
 		if (GLOSS_EXCLUDED_PLACETYPES.has(ptNameByID.get(a.ptid) ?? "")) continue
 
-		if (a.pop > 0 || a.imp != null) continue
+		if ((a.pop ?? 0) > 0 || a.imp != null) continue
 		glossSids.push(sid)
 	}
 
@@ -101,9 +89,8 @@ export function stampNameRoles(ctx: {
 	if (hasSourceNames) {
 		out.exec("BEGIN")
 
-		// Two provenance routes into the same stamp: WOF's abbreviation/short name KINDS arrive in the
-		// LANGUAGE column ('abbr'/'short' — 280 rows, measured 2026-08-18, Toledo's 'TO' among them) and
-		// qualify by kind alone; everything else qualifies as a variant in an official language.
+		// WOF's abbreviation/short name kinds qualify by kind only.
+		// Everything else qualifies as a variant in an official language.
 		for (const r of src
 			.prepare("SELECT id, name, language FROM names WHERE privateuse = 'variant' OR language IN ('abbr', 'short')")
 			.iterate()) {
@@ -129,8 +116,7 @@ export function stampNameRoles(ctx: {
 		progress("roles", "source carries no `names` table — abbr detector skipped (gloss still runs)")
 	}
 
-	// Stamp order is precedence: the provenance-based abbr first, then the own-name variant verdict,
-	// then gloss fills what neither claimed.
+	// Stamp order is precedence: abbr first, then the own-name variant verdict, then gloss fills what neither claimed.
 	const roleAbbr = Number(
 		out
 			.prepare(
@@ -141,12 +127,8 @@ export function stampNameRoles(ctx: {
 			.run().changes
 	)
 
-	// Detect aliases that are the holder's own primary name in another variant.
-	// orthography — romanization, spacing/diacritic variant, or abbreviation expansion. The verdict
-	// is per (alias key, primary key) pair, so it runs in JS over the still-unstamped alias rows;
-	// an uncovered script answers no-verdict and stamps nothing (own-name.ts owns the predicate and
-	// its measured threshold). Runs BEFORE gloss on purpose: a surface that IS the place's own name
-	// is not a translation, whatever the key volume says.
+	// Runs before gloss so the place's own name remains its source name.
+	// An uncovered script answers no-verdict.
 	out.exec(
 		"CREATE TEMP TABLE variant_key (spr_id INTEGER NOT NULL, name_key TEXT NOT NULL, PRIMARY KEY (spr_id, name_key)) WITHOUT ROWID"
 	)

package/lib/candidate/own-name.ts

@@ -3,40 +3,36 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The OWN-NAME VARIANT predicate (#1882): is an alias surface the holder's own primary name in
- *   another orthography — a romanization (`Брэст` → `brest`), a spacing/diacritic variant
- *   (`George Town` → `georgetown`), an abbreviation expansion (`St. George's` → `Saint George's`)
- *   — rather than a different name that merely shares the folded key?
+ *   The own-name variant predicate: is an alias surface the holder's own primary name in another
+ *   orthography, whether a romanization (`Брэст` → `brest`), a spacing or diacritic variant
+ *   (`George Town` → `georgetown`), or an abbreviation expansion (`St. George's` → `Saint George's`)?
+ *   The alternative is a different name that merely shares the folded key.
  *
- *   The comparator is `levenshteinSimilarity`, NOT Jaro-Winkler: JW's common-prefix bonus scores
- *   the required NEGATIVE case (`chanchun` vs `cancun`, 0.925) above real positives
- *   (`saint george s` vs `st georges` expanded, 0.914), so no JW threshold separates them.
- *   Measured on the #1882 census contests, edit similarity separates every case with margin:
+ *   The comparator is `levenshteinSimilarity`. Jaro-Winkler's common-prefix bonus scores the required
+ *   negative case (`chanchun` against `cancun`, 0.925) above real positives (`saint george s` against
+ *   `st georges` expanded, 0.914), so no JW threshold separates them. Edit similarity separates every
+ *   measured case with margin.
  *
- *   - IN: `brest`/`brest` 1.0 · `george town`/`georgetown` 0.909 · `saint george s`/`saint georges`
- *       0.929 · `adamovka`/`adamowka` 0.875
- *   - OUT: `lievin`/`levin` 0.833 (Liévin FR vs Levin NZ — different places with near-identical
- *       names; the panel's `41 Weraroa Road, Levin` row needs this side) · `chanchun`/`cancun` 0.75 ·
- *       `augsburg`/`augusta` 0.375 · `west bay`/`west end` 0.625 · `derry`/`londonderry` 0.455
- *       (Derry/Londonderry is a DUAL NAME, not a variant — its own follow-up on #1882)
- *
- *   An unhandled script (Arabic, Hebrew, CJK — the romanizer covers Cyrillic only) answers NULL,
- *   never "different name": absence of a verdict must not stamp anything (the meaning-of-zero rule).
- *   The #1882 census counted 396 demoted Arabic/Hebrew-primary aliases left unclassified by this.
+ *   An unhandled script (Arabic, Hebrew, CJK, since the romanizer covers Cyrillic only) answers NULL,
+ *   never "different name". Absence of a verdict must not stamp anything.
  */
 
 import { levenshteinSimilarity } from "@mailwoman/match/comparators"
 
 /**
- * Edit-similarity floor for the variant verdict. The measured band: nearest admitted pair 0.875
- * (`adamovka`/`adamowka`), nearest refused pair 0.833 (`lievin`/`levin`).
+ * Edit-similarity floor for the variant verdict.
+ *
+ * The measured band: nearest admitted pair 0.875 (`adamovka`/`adamowka`),
+ * nearest refused pair 0.833 (`lievin`/`levin`).
  */
 export const VARIANT_SIMILARITY_MIN = 0.85
 
 /**
- * BGN/PCGN-flavored Cyrillic romanization, folded to the name-key alphabet. Digraph outputs (zh, kh, ts, ch, sh, shch,
- * yu, ya) match the dominant transliteration conventions the gazetteer's Latin aliases actually use; the `w`/`v` and
- * `kh`/`h` style variance between systems is what the edit-similarity threshold absorbs.
+ * BGN/pcgn-flavored Cyrillic romanization, folded to the name-key alphabet.
+ *
+ * Digraph outputs (zh, kh, ts, ch, sh, shch, yu, ya) match the dominant transliteration
+ * conventions the gazetteer's Latin aliases actually use.
+ * The `w`/`v` and `kh`/`h` style variance between systems is what the edit-similarity threshold absorbs.
  */
 const CYRILLIC_TO_LATIN: Record<string, string> = {
 	а: "a",
@@ -80,8 +76,10 @@ const CYRILLIC_TO_LATIN: Record<string, string> = {
 }
 
 /**
- * Leading-word abbreviations expanded BEFORE comparison, so `st georges` meets `saint george s` inside the edit
- * threshold. Whole-word only — `st` inside `stanley` never expands.
+ * Leading-word abbreviations expanded before comparison, so `st georges` meets
+ * `saint george s` inside the edit threshold.
+ *
+ * Whole-word only, so `st` inside `stanley` never expands.
  */
 const NAME_ABBREVIATIONS: ReadonlyArray<[RegExp, string]> = [
 	[/\bst\b/g, "saint"],
@@ -91,7 +89,7 @@ const NAME_ABBREVIATIONS: ReadonlyArray<[RegExp, string]> = [
 ]
 
 /**
- * Expand the whole-word abbreviations above.
+ * Expand the whole-word abbreviations above in a name key.
  */
 export function expandNameAbbreviations(key: string): string {
 	let out = key
@@ -104,8 +102,10 @@ export function expandNameAbbreviations(key: string): string {
 }
 
 /**
- * Romanize a folded name key to the a–z0–9/space alphabet. `null` when characters outside the covered scripts remain —
- * an unhandled script is NO VERDICT, not a mismatch.
+ * Romanize a folded name key to the a–z0–9/space alphabet.
+ *
+ * `null` when characters outside the covered scripts remain.
+ * An unhandled script is no verdict.
  */
 export function romanizeNameKey(key: string): string | null {
 	let out = ""
@@ -124,15 +124,18 @@ export function romanizeNameKey(key: string): string | null {
 }
 
 /**
- * Edit similarity between a holder's primary name key and one of its alias keys, both romanized and
- * abbreviation-expanded. `null` when either side's script is uncovered.
+ * Edit similarity between a holder's primary name key and one of its alias keys,
+ * both romanized and abbreviation-expanded.
+ *
+ * `null` when either side's script is uncovered.
  */
-// repo-health-ignore export-name-affix -- romanizes and expands abbreviations first; `nameSimilarity` compares as given.
+// repo-health-ignore export-name-affix -- romanizes and expands abbreviations first;
+// `nameSimilarity` compares as given.
 export function ownNameSimilarity(primaryKey: string, aliasKey: string): number | null {
 	const primary = romanizeNameKey(primaryKey)
 	const alias = romanizeNameKey(aliasKey)
 
-	if (primary == null || alias == null || !primary || !alias) return null
+	if (!primary || !alias || !primary || !alias) return null
 
 	return levenshteinSimilarity(expandNameAbbreviations(primary), expandNameAbbreviations(alias))
 }

package/lib/candidate/place-attrs.ts

@@ -4,12 +4,11 @@
  * @author Teffen Ellis, et al.
  * @file The per-place record every candidate-staging pass writes its rows from.
  *
- *   Pass 1 reduces each current `spr` row to one {@link PlaceAttrs}; every later pass (alias bags,
+ *   Pass 1 reduces each current `spr` row to one {@link PlaceAttrs}. Every later pass (alias bags,
  *   region abbreviations, country display names, the currency backfill, the extract folds) discovers
- *   ADDITIONAL name keys for a place already in that map and stages a row against the same record.
- *   That is what keeps each candidate row denormalized without re-reading the source, and it is why
- *   a pass needs exactly four things to stage: the key it found, the place, the id the row hangs on,
- *   and whether the key is the place's canonical name.
+ *   additional name keys for a place already in that map and stages a row against the same record.
+ *   That keeps each candidate row denormalized without re-reading the source. A pass therefore needs
+ *   exactly four values: the key, place, row ID, plus a flag for the place's canonical name.
  */
 
 export interface PlaceAttrs {
@@ -23,22 +22,30 @@ export interface PlaceAttrs {
 	mnLon: number
 	mxLat: number
 	mxLon: number
-	pop: number
+	/**
+	 * The place's recorded population, or null when the gazetteer never measured one.
+	 *
+	 * NULL rather than zero.
+	 * `place_population` holds no zero, so an absent row is the only way a place has no number.
+	 * A zero written for those would be an unmeasured count.
+	 */
+	pop: number | null
 	neg: number
 	pkey: string
 	/**
-	 * The place's toponym-fame score, or null when the score source has no measurement for it (#28). A property of the
-	 * PLACE, so it rides {@link StageRow} onto the alias and abbrev rows too — that is how a bare `Moscow` reaches
-	 * Москва's score through the alias row that carries the key.
+	 * The place's toponym-fame score, or null when the score source has no measurement for it.
+	 *
+	 * A property of the place, so it appears on {@link StageRow} and on alias and abbrev rows too.
+	 * That is how a bare `Moscow` reaches Москва's score through the alias row that includes the key.
 	 */
 	imp: number | null
 }
 
 /**
- * Stage one candidate row: a normalized name key, the place it belongs to, the source id the row hangs on, and whether
- * the key is that place's canonical name (`is_primary`).
+ * Stages one candidate row with a normalized name key, place, source ID,
+ * plus a canonical-name flag (`is_primary`).
  *
- * `sid` is passed separately rather than read off the place because a extract fold and the alias pass stage rows for
- * ids the admin `attrs` map never held.
+ * `sid` is passed separately rather than read off the place because an extract fold
+ * and the alias pass stage rows for ids the admin `attrs` map never held.
  */
 export type StageRow = (k: string, a: PlaceAttrs, sid: number, isPrimary: number) => void

package/lib/candidate/schema.ts

@@ -2,17 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Typed schema for the byte-range CANDIDATE gazetteer (`candidate.db`) — the single source of truth
- *   for the columns shared by the BUILDER ({@link buildCandidateTable}) and the READERS (the Node
- *   {@link WOFCandidateTableLookup} + the browser `@mailwoman/resolver-wof-wasm/httpvfs/resolver`). Before this module each
- *   side hand-wrote the column list; a rename in one place broke the other at runtime. Now the
- *   contract is a Kysely `Database` interface (`new DatabaseClient<CandidateDatabase>(...)` for
- *   typed inserts) plus the table DDL as strings — so a column change is a compile error on every
- *   consumer.
- *
- *   `cand_stage` is the transient staging table the builder bulk-loads; `candidate` is the clustered
- *   `WITHOUT ROWID` B-tree it's materialized into (same columns). The reader queries `candidate`.
  */
 
 import { sql, type Kysely } from "kysely"
@@ -22,9 +11,10 @@ import type { CapitalTable } from "#capital-schema"
 import type { NameKey } from "#street/normalize"
 
 /**
- * One candidate row. `name_key` + the four small int keys + `neg_rank` + `spr_id` form the clustered primary key; the
- * rest is denormalized so a resolve is one probe (no join to `spr`). Coordinates + bbox + name are nullable at the SQL
- * level (a postcode extract row may lack a bbox).
+ * One candidate row.
+ *
+ * `name_key`, four small integer keys, `neg_rank`, and `spr_id` form the clustered primary key.
+ * The remaining fields are denormalized so a resolve needs one probe.
  */
 export interface CandidateTable {
 	/**
@@ -36,7 +26,7 @@ export interface CandidateTable {
 	 */
 	country_id: number
 	/**
-	 * The place's region-tier ancestor id, or 0 (carried for the future region 2-step).
+	 * The place's region-tier ancestor id, or 0.
 	 */
 	region_id: number
 	/**
@@ -44,7 +34,10 @@ export interface CandidateTable {
 	 */
 	placetype_id: number
 	/**
-	 * `-log10(population + 1)` — ASC order = highest-population first. 0 for postcodes (no population).
+	 * `-log10(population + 1)`.
+	 *
+	 * The sort uses ascending order to put the highest population first.
+	 * Postcodes use `0`.
 	 */
 	neg_rank: number
 	/**
@@ -64,42 +57,14 @@ export interface CandidateTable {
 	 */
 	is_primary: number | null
 	/**
-	 * Blended place importance in [0, 1] — the toponym-fame prior the bare-city-name class is decided on (#28). NULL
-	 * means the score source had no row for this place: UNMEASURED, never "an importance of zero" (meaning-of-zero).
-	 * Constant across every row of one place — primary, alias and abbrev alike — because it is a property of the PLACE,
-	 * not of the name that reached it, which is what lets a bare `Moscow` inherit Москва's score through the alias row.
-	 *
-	 * **THIS IS THE PRE-SPLIT CONFLATION, AND THE NAME SAYS SO.** It is `place_importance.importance` copied verbatim
-	 * from the score source — the bounded blend `place-importance-schema.ts`'s `blendImportance` writes (the
-	 * concordance's encyclopedia-derived channel clamped around a population-derived base); that module calls the column
-	 * DEPRECATED. It is NOT the split `encyclopedic` channel, and the two must not be conflated in a future build:
-	 * writing the split value here instead was measured on 2026-08-10 and makes the ranking key INERT on three of the
-	 * four rows it exists to fix. The reason is coverage, not principle — the encyclopedia-concordance join in
-	 * `admin-global-priority-importance.db` reaches 133,888 of 702,709 scored places and only eleven countries
-	 * (US/FR/GB/DE/IT/ES/NL/JP/CN/KR/TW). CA, AU and RU have ZERO concordance rows, so Whitby CA, Windsor CA and Epping
-	 * AU carry the population fallback and nothing else. Under the strict split those three become unmeasured, the
-	 * consumer's positive-evidence-only rule leaves them exactly where population put them (first), and the famous GB
-	 * bearer can never overtake them. The conflated column is the only one on which every bearer of a name is scored on a
-	 * single comparable scale, which is the precondition for comparing them at all.
-	 *
-	 * So a consumer reads this as "fame, with population standing in where fame was never measured" — the legacy blended
-	 * semantics — and NOT as "this place has an encyclopedia entry of this importance". When the score source grows a
-	 * real `encyclopedic` column for every country, add a SECOND column rather than redefining this one.
+	 * Blended place importance in [0, 1], NULL when unmeasured (never zero) and copied
+	 * verbatim from the pre-split score source rather than the split `encyclopedic` channel.
 	 */
 	importance: number | null
 	/**
-	 * The NAME'S detected role on this row, or NULL (#1730). Two build-time detectors stamp `is_primary = 0` rows only:
-	 *
-	 * - `'abbr'` — provenance-based: the surface is a WOF `variant` name in one of the place's country's official languages
-	 *   (or English) — the #936 signal, measured at a 13× key-collision rate vs preferred names.
-	 * - `'gloss'` — anomaly-based: the row belongs to a place whose key count crosses the gloss threshold with a non-admin
-	 *   placetype and NO measured prominence (population absent AND importance unmeasured) — the translation-gloss
-	 *   fingerprint (#1730's sweep; `Poisson` → a US fish-name place). Provenance CANNOT separate a gloss from an exonym
-	 *   (WOF imported both as `x_preferred`), which is why this detector is an anomaly test and stamps only the certain
-	 *   core.
-	 *
-	 * NULL = no role detected. The column is WRITE-ONLY in this build generation: no ranking consumer reads it — a rank
-	 * penalty is its own future, D-rule-conditional step with the `gloss_key` board as regression check.
+	 * The name's detected role on this row (`'abbr'`, `'gloss'` or `'variant'`),
+	 * or NULL when no role was detected.
+	 * The column is write-only in this build generation.
 	 */
 	name_role: string | null
 }
@@ -121,13 +86,12 @@ export interface PlacetypeCodeTable {
 }
 
 /**
- * The candidate database schema for `new DatabaseClient<CandidateDatabase>(...)`. Extends the ancestors sidecar
- * (`candidate_ancestor` + `candidate_interval` — see candidate-ancestors-schema.ts for the encoding decision), so the
- * builder's one typed client covers every table in the artifact.
+ * The candidate database schema, extending the ancestors sidecar so one typed
+ * client covers every table in the artifact.
  */
 export interface CandidateDatabase extends CandidateAncestorsDatabase {
 	/**
-	 * The clustered `WITHOUT ROWID` lookup table the reader probes.
+	 * The clustered `without rowid` lookup table the reader probes.
 	 */
 	candidate: CandidateTable
 	/**
@@ -137,15 +101,16 @@ export interface CandidateDatabase extends CandidateAncestorsDatabase {
 	country_codes: CountryCodeTable
 	placetype_codes: PlacetypeCodeTable
 	/**
-	 * The capital-status reference carried in-artifact (#1880's distribution home) — see capital-schema.ts.
+	 * The capital-status reference stored in the artifact.
+	 * See capital-schema.ts.
 	 */
 	capital: CapitalTable
 }
 
 /**
- * The `candidate`/`cand_stage` columns in clustered-key order. The materialization `INSERT INTO candidate SELECT … FROM
- * cand_stage` derives its column list from this, so the two tables can't drift. Keep in sync with
- * {@link CandidateTable}.
+ * The `candidate`/`cand_stage` columns in clustered-key order, from which the
+ * materialization derives its column list.
+ * Keep in sync with {@link CandidateTable}.
  */
 export const CANDIDATE_COLUMNS = [
 	"name_key",
@@ -163,16 +128,14 @@ export const CANDIDATE_COLUMNS = [
 	"max_lon",
 	"population",
 	"is_primary",
-	// Appended, never inserted mid-list: the first six entries ARE the clustered primary key, and the
-	// positional `INSERT INTO cand_stage VALUES (…)` in the builder binds by position.
+	// Appended, never inserted mid-list: the positional `insert into cand_stage values (…)` binds by position.
 	"importance",
 	"name_role",
 ] as const
 
 /**
- * Create the code dictionaries + the transient staging table — called before the build's load passes. `cand_stage`
- * mirrors {@link CandidateTable} but every column is nullable (the loader fills them positionally). Pass a
- * {@link DatabaseClient} (or any `Kysely`) over the candidate DB.
+ * Create the code dictionaries and the transient staging table; `cand_stage` mirrors
+ * {@link CandidateTable} with every column nullable because the loader fills them positionally.
  */
 export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>): Promise<void> {
 	await db.schema
@@ -210,8 +173,9 @@ export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>
 }
 
 /**
- * Create the clustered `WITHOUT ROWID` lookup table — called after staging, before the VACUUM. The first six columns
- * form the clustered primary key (population-ranked via `neg_rank`).
+ * Create the clustered `without rowid` lookup table.
+ *
+ * Its first six columns form the primary key, ranked by population through `neg_rank`.
  */
 export async function createCandidateTable(db: Kysely<CandidateDatabase>): Promise<void> {
 	await db.schema
@@ -241,7 +205,7 @@ export async function createCandidateTable(db: Kysely<CandidateDatabase>): Promi
 			"neg_rank",
 			"spr_id",
 		])
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		// `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
 		.modifyEnd(sql`without rowid`)
 		.execute()
 }