@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/candidate-schema.ts

@@ -1,247 +0,0 @@
-/**
- * @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"
-
-import type { CandidateAncestorsDatabase } from "#candidate-ancestors-schema"
-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).
- */
-export interface CandidateTable {
-	/**
-	 * The shared {@link normalizeLocalityForKey} of the name/alias — the probe key.
-	 */
-	name_key: NameKey
-	/**
-	 * Small int from {@link CountryCodeTable} (shrinks the clustered key).
-	 */
-	country_id: number
-	/**
-	 * The place's region-tier ancestor id, or 0 (carried for the future region 2-step).
-	 */
-	region_id: number
-	/**
-	 * Small int from {@link PlacetypeCodeTable}.
-	 */
-	placetype_id: number
-	/**
-	 * `-log10(population + 1)` — ASC order = highest-population first. 0 for postcodes (no population).
-	 */
-	neg_rank: number
-	/**
-	 * WOF id of the place this row resolves to.
-	 */
-	spr_id: number
-	name: string | null
-	latitude: number | null
-	longitude: number | null
-	min_lat: number | null
-	min_lon: number | null
-	max_lat: number | null
-	max_lon: number | null
-	population: number | null
-	/**
-	 * 1 when the row is the place's canonical name (vs an alias/abbrev).
-	 */
-	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.
-	 */
-	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.
-	 */
-	name_role: string | null
-}
-
-/**
- * `(id → ISO country code)` dictionary.
- */
-export interface CountryCodeTable {
-	id: number
-	code: string
-}
-
-/**
- * `(id → placetype)` dictionary.
- */
-export interface PlacetypeCodeTable {
-	id: number
-	placetype: string
-}
-
-/**
- * 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.
- */
-export interface CandidateDatabase extends CandidateAncestorsDatabase {
-	/**
-	 * The clustered `WITHOUT ROWID` lookup table the reader probes.
-	 */
-	candidate: CandidateTable
-	/**
-	 * Transient staging table (same columns); dropped once `candidate` is materialized.
-	 */
-	cand_stage: CandidateTable
-	country_codes: CountryCodeTable
-	placetype_codes: PlacetypeCodeTable
-	/**
-	 * The capital-status reference carried in-artifact (#1880's distribution home) — 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}.
- */
-export const CANDIDATE_COLUMNS = [
-	"name_key",
-	"country_id",
-	"region_id",
-	"placetype_id",
-	"neg_rank",
-	"spr_id",
-	"name",
-	"latitude",
-	"longitude",
-	"min_lat",
-	"min_lon",
-	"max_lat",
-	"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.
-	"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.
- */
-export async function createCandidateStagingTables(db: Kysely<CandidateDatabase>): Promise<void> {
-	await db.schema
-		.createTable("country_codes")
-		.addColumn("id", "integer", (c) => c.primaryKey())
-		.addColumn("code", "text", (c) => c.unique())
-		.execute()
-
-	await db.schema
-		.createTable("placetype_codes")
-		.addColumn("id", "integer", (c) => c.primaryKey())
-		.addColumn("placetype", "text", (c) => c.unique())
-		.execute()
-
-	await db.schema
-		.createTable("cand_stage")
-		.addColumn("name_key", "text")
-		.addColumn("country_id", "integer")
-		.addColumn("region_id", "integer")
-		.addColumn("placetype_id", "integer")
-		.addColumn("neg_rank", "real")
-		.addColumn("spr_id", "integer")
-		.addColumn("name", "text")
-		.addColumn("latitude", "real")
-		.addColumn("longitude", "real")
-		.addColumn("min_lat", "real")
-		.addColumn("min_lon", "real")
-		.addColumn("max_lat", "real")
-		.addColumn("max_lon", "real")
-		.addColumn("population", "integer")
-		.addColumn("is_primary", "integer")
-		.addColumn("importance", "real")
-		.addColumn("name_role", "text")
-		.execute()
-}
-
-/**
- * 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`).
- */
-export async function createCandidateTable(db: Kysely<CandidateDatabase>): Promise<void> {
-	await db.schema
-		.createTable("candidate")
-		.addColumn("name_key", "text", (c) => c.notNull())
-		.addColumn("country_id", "integer", (c) => c.notNull())
-		.addColumn("region_id", "integer", (c) => c.notNull())
-		.addColumn("placetype_id", "integer", (c) => c.notNull())
-		.addColumn("neg_rank", "real", (c) => c.notNull())
-		.addColumn("spr_id", "integer", (c) => c.notNull())
-		.addColumn("name", "text")
-		.addColumn("latitude", "real")
-		.addColumn("longitude", "real")
-		.addColumn("min_lat", "real")
-		.addColumn("min_lon", "real")
-		.addColumn("max_lat", "real")
-		.addColumn("max_lon", "real")
-		.addColumn("population", "integer")
-		.addColumn("is_primary", "integer")
-		.addColumn("importance", "real")
-		.addColumn("name_role", "text")
-		.addPrimaryKeyConstraint("candidate_pk", [
-			"name_key",
-			"country_id",
-			"region_id",
-			"placetype_id",
-			"neg_rank",
-			"spr_id",
-		])
-		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
-		.modifyEnd(sql`without rowid`)
-		.execute()
-}

package/lib/candidate-scoring.ts

@@ -1,261 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   How a raw `place_search` row becomes a scored `PlaceCandidate`, and how the resulting pool is
- *   ordered — the weighted-sum score and the exact-match tiering that ranks over it.
- */
-
-import { compareReferential, referentialFromPopulation } from "@mailwoman/core/resolver"
-import { haversineKm } from "@mailwoman/spatial"
-import type { DatabaseClient } from "@mailwoman/sqlite/client"
-
-import { exactMatchIDs, officialNameIDs } from "#exact-match"
-import { foldQueryText } from "#fts/index"
-import { populationBoostTerm, type RankingWeights } from "#ranking-weights"
-import type { RawSearchRow } from "#search-fetch"
-import type { FindPlaceQuery, PlaceCandidate, WOFPlacetype } from "#types"
-
-/**
- * Score one raw FTS row into a `PlaceCandidate`: the weighted sum over the negated BM25 baseline, the placetype /
- * country / parent boosts, the length penalty, the proximity and population terms, and the carried fields (referential,
- * encyclopedic, bbox) consumers read. `queryLen` is the query text's length, hoisted out of the per-row loop.
- */
-export function candidateFromSearchRow(
-	row: RawSearchRow,
-	context: {
-		query: FindPlaceQuery
-		placetypes: WOFPlacetype[] | null
-		queryLen: number
-		weights: RankingWeights
-	}
-): PlaceCandidate {
-	const { query, placetypes, queryLen, weights } = context
-
-	// SQLite's bm25() returns a lower-is-better score (negative for matches). Negate so we
-	// start from a higher-is-better baseline.
-	let score = -row.rank
-
-	if (placetypes && placetypes.length && placetypes.includes(row.placetype as WOFPlacetype)) {
-		score += weights.placetypeMatchBoost
-	}
-
-	if (!placetypes && row.placetype === "locality") {
-		score += weights.localityImplicitBoost
-	}
-
-	if (query.country && row.country === query.country) {
-		score += weights.countryMatchBoost
-	}
-
-	if (query.parentID !== undefined) {
-		score += row.parent_id === query.parentID ? weights.directChildBoost : weights.descendantBoost
-	}
-
-	const extraLen = Math.max(0, row.name.length - queryLen - 3)
-	score -= (weights.lengthPenaltyWeight * extraLen) / 10
-
-	// Proximity boost: only applied when the query carries `near` AND the candidate has real
-	// coordinates. The formula decays smoothly with distance so close-but-not-exact hits
-	// still benefit; tunable via proximityBoost + proximityScaleKm.
-	let distanceKm: number | undefined
-	// The best decayed-distance term over `near` + every `bias` point (each point's term is
-	// scaled by its weight; the MAX wins — a candidate near ANY hint is "nearby"). Carried
-	// into the exact-tier prominence sort below when hints are present.
-	let proximityTerm = 0
-
-	if (row.lat !== null && row.lon !== null && !(row.lat === 0 && row.lon === 0)) {
-		const hints: Array<{ lat: number; lon: number; weight: number }> = []
-
-		if (query.near) {
-			hints.push({ lat: query.near.lat, lon: query.near.lon, weight: 1 })
-		}
-
-		for (const b of query.bias ?? []) {
-			hints.push({ lat: b.lat, lon: b.lon, weight: b.weight ?? 1 })
-		}
-
-		let scoreTerm = 0
-
-		for (const h of hints) {
-			const d = haversineKm(h.lat, h.lon, row.lat, row.lon)
-			const decay = h.weight / (1 + d / weights.proximityScaleKm)
-			const prom = decay * weights.biasBoost
-
-			if (prom > proximityTerm) {
-				proximityTerm = prom
-				distanceKm = d
-				scoreTerm = decay * weights.proximityBoost
-			}
-		}
-
-		score += scoreTerm
-	}
-
-	// Population boost: capped at `populationBoost` magnitude at `10^populationScaleLog10`
-	// people. Missing population → no contribution. Never penalizes.
-	const popTerm = populationBoostTerm(row.population, weights)
-	score += popTerm
-
-	// Combined prominence for the exact-tier sort when proximity hints are present: population
-	// and nearness in the SAME additive units, so the map view / the user's location can win a
-	// cross-country postcode tie without a hard filter.
-	const prominence = popTerm + proximityTerm
-
-	const candidate: PlaceCandidate = {
-		id: row.id,
-		prominence,
-		name: row.name,
-		placetype: row.placetype as WOFPlacetype,
-		country: row.country ?? "",
-		lat: row.lat ?? 0,
-		lon: row.lon ?? 0,
-		parent_id: row.parent_id ?? undefined,
-		score,
-	}
-
-	if (distanceKm !== undefined) {
-		candidate.distanceKm = distanceKm
-	}
-
-	if (row.population !== null && row.population > 0) {
-		candidate.population = row.population
-		// The named ranking key (ROAD_TO_V9 §2). DERIVED, not stored — a pure function of the
-		// population already on this row, so it cannot drift from what the ordering uses.
-		candidate.referential = referentialFromPopulation(row.population)
-	}
-
-	// Carried for consumers (annotations / API surfaces). No ranking site reads it.
-	if (row.encyclopedic !== null) {
-		candidate.encyclopedic = row.encyclopedic
-	}
-
-	// Candidate bbox — parity with the WASM lookup (resolver-wof-wasm/lookup.ts), whose
-	// consumers (the demo cascade's region constraint) read it. Without this the Node
-	// backend's region→bbox constraint is dead and disambiguation falls to population
-	// ranking (the Springfield-IL→MO failure the #524 smoke eval caught).
-	if (row.min_latitude != null && row.max_latitude != null && row.min_longitude != null && row.max_longitude != null) {
-		candidate.bbox = {
-			minLat: row.min_latitude,
-			maxLat: row.max_latitude,
-			minLon: row.min_longitude,
-			maxLon: row.max_longitude,
-		}
-	}
-
-	return candidate
-}
-
-/**
- * Order `candidates` IN PLACE — the exact-match tier first when the extract can answer the name probes, otherwise plain
- * weighted-score order. Every candidate is stamped with its `exactMatch` flag on the way through.
- */
-export function rankCandidates<DB>(
-	candidates: PlaceCandidate[],
-	options: {
-		db: DatabaseClient<DB>
-		schemaName: string
-		query: FindPlaceQuery
-		weights: RankingWeights
-	}
-): void {
-	const { db, schemaName, query, weights } = options
-
-	// Exact-match tiering: a candidate whose name OR any alias equals the query text (case-folded)
-	// ranks above any partial match, with the weighted-sum score (incl. population) breaking ties
-	// WITHIN a tier. See the RankingWeights.exactMatchTiering docstring for why this aligns the
-	// population prior rather than overriding it. One cheap indexed lookup over the candidate ids.
-	// Runs even for a SINGLE candidate so `exactMatch` is stamped consistently (parity with the
-	// WASM lookup) — a sole alias hit ("New York City" → New York) must still carry the flag the
-	// demo cascade / #369 re-rank read.
-	if (weights.exactMatchTiering && candidates.length) {
-		const exactIDs = exactMatchIDs(
-			db,
-			schemaName,
-			candidates.map((c) => c.id as number),
-			query.text
-		)
-
-		// Stamp the tier onto every candidate (not just when the tiering sort fires) so a downstream
-		// re-rank — #369's postcode-anchor country pin in `resolveTree` — can keep the country pin from
-		// crossing the exact/partial boundary ("ME" → Maine, not the more-populous Missouri).
-		for (const c of candidates) {
-			c.exactMatch = exactIDs.has(c.id as number)
-		}
-
-		if (exactIDs.size) {
-			// #905: WITHIN the exact tier, population is the PRIMARY key and the weighted score
-			// only breaks population ties. Exactness saturates text relevance, and the bm25
-			// residue inside `score` is length-noise (see the fetch-site comment), so letting it
-			// order the tier is what sent unscoped "Paris" to an Ohio township. The partial tier
-			// keeps score order — text relevance still means something there. This makes the
-			// exactMatchTiering docstring literal: match quality primary, prominence within.
-			//
-			// #912 sub-tier: a NAME-exact candidate (spr.name equals the query) outranks an
-			// ALIAS-exact one ('Paris' the place beats 'Paris Township' held via alias 'Paris').
-			// The place's own name is a stronger identity claim than an alias — aliases exist to
-			// widen recall, not to tie primaries. ME→Maine is untouched: 'ME' name-exact-matches
-			// nothing, so the alias sub-tier still decides there. Population orders within each
-			// sub-tier as before.
-			const needle = foldQueryText(query.text)
-
-			// #936 option 3: an OFFICIAL name (preferred form in an official language of the place's
-			// country, `names.official = 1`) counts as the place's own name for the sub-tier — "Åbo" is
-			// Turku's name, not merely its alias. Floor-conditioned on the holder's population (see the
-			// RankingWeights docstring for the measured 100k boundary). officialIDs ⊆ exactIDs by
-			// construction (official rows are names rows), so only the sub-tier KIND changes.
-			const officialIDs = weights.officialNameExact
-				? officialNameIDs(
-						db,
-						schemaName,
-						candidates
-							.filter((c) => exactIDs.has(c.id as number) && (c.population ?? 0) >= weights.officialNameExactFloor)
-							.map((c) => c.id as number),
-						query.text
-					)
-				: undefined
-
-			const kind = (c: PlaceCandidate): number => {
-				if (!exactIDs.has(c.id as number)) return 0
-
-				if (foldQueryText(String(c.name ?? "")) === needle) return 2
-
-				return officialIDs?.has(c.id as number) ? 2 : 1
-			}
-
-			// With proximity hints (near/bias), prominence (population + nearness, same units)
-			// replaces raw population as the within-tier key — the 48026 rule: the map view or
-			// the user's location breaks a cross-country postcode tie. Without hints, REFERENTIAL
-			// ordering decides.
-			//
-			// ROAD_TO_V9 §2: this is the site that "orders namesakes", so it is the site that has to
-			// say what it orders by. `compareReferential` is referential DESC with raw population as
-			// the tiebreak, which is provably the SAME ORDER as the `(b.population ?? 0) - (a.population ?? 0)`
-			// it replaces — referential is strictly increasing in population below saturation and
-			// constant above it, and the tiebreak restores the order in the saturated tail. Measured
-			// zero-delta, not assumed: see `place-importance-schema.test.ts` and `resolver-referential-ranking.test.ts`.
-			// Encyclopedic importance is not, and must not become, an input here.
-			const hasHints = !!query.near || (query.bias?.length ?? 0) > 0
-
-			candidates.sort((a, b) => {
-				const ax = kind(a)
-				const bx = kind(b)
-
-				if (bx !== ax) return bx - ax
-
-				if (ax >= 1) {
-					if (hasHints) return (b.prominence ?? 0) - (a.prominence ?? 0) || b.score - a.score
-
-					return compareReferential(a, b) || b.score - a.score
-				}
-
-				return b.score - a.score
-			})
-
-			return
-		}
-	}
-
-	candidates.sort((a, b) => b.score - a.score)
-}

package/lib/convention/index.ts

@@ -1,154 +0,0 @@
-/**
- * @copyright Sister Software
- * @license AGPL-3.0
- * @author Teffen Ellis, et al.
- *
- *   The **Geographic Rule Engine** convention model (Direction E, #289 — see
- *   `docs/articles/plan/2026-06-05-geographic-rule-engine.md` and epic #288).
- *
- *   A `Convention` is a declarative resolution profile attached to a Who's-On-First admin polygon.
- *   The engine deep-merges the conventions along a resolved place's ancestor chain — country →
- *   region → … → locality, most-specific winning — and the backend dispatches the named strategies
- *   in `candidateStrategies`, first to return candidates wins.
- *
- *   This module is the backend-agnostic core: the convention TYPES, the deep-merge, and the seed
- *   source. The strategy IMPLEMENTATIONS are SQL-bound and live in `lookup.ts`, registered by
- *   name.
- *
- *   For the existing EU locales (DE/FR/GB/NL) the seed source is empty, so every query resolves to
- *   `WORLD_DEFAULT` and the dispatch is byte-identical to the pre-engine coordinate-first path. JP
- *   / KR / TW add rows here (and #290 swaps the seed map for a build-from-source sqlite-backed
- *   source).
- */
-
-import type { FindPlaceQuery, PlaceCandidate } from "#types"
-
-/**
- * Soft-scoring weights for the `postcode_area_resolution` strategy: `pc·S_pc + name·S_name + pop·S_pop`.
- */
-export interface ScoringWeights {
-	pc: number
-	name: number
-	pop: number
-}
-
-/**
- * A geographically-scoped resolution profile. Namespaced sections grow per phase; #289 ships the dispatch + scoring
- * slice (`candidateStrategies` + `scoringWeights`). Later phases add `fieldMapping` (locale semantics for `locator[]`),
- * `tokenNormalization`, etc.
- */
-export interface Convention {
-	/**
-	 * Ordered strategy names the dispatcher runs; the first to return a non-null result wins.
-	 */
-	candidateStrategies?: string[]
-	/**
-	 * Weights for `postcode_area_resolution`'s soft-score. Partial — a layer may nudge one weight and inherit the rest
-	 * from the layers below it (`resolveConvention` fills any gaps from WORLD_DEFAULT).
-	 */
-	scoringWeights?: Partial<ScoringWeights>
-}
-
-/**
- * A fully-resolved convention: every field present, weights complete. What `resolveConvention` returns and what
- * strategies consume.
- */
-export interface ResolvedConvention {
-	candidateStrategies: string[]
-	scoringWeights: ScoringWeights
-}
-
-/**
- * The base layer every ancestor chain starts from. Reproduces the pre-engine coordinate-first behavior exactly: try
- * `postcode_area_resolution`, else fall back to fuzzy name match; soft-score weights 0.6 / 0.3 / 0.1. Changing these
- * changes EU behavior — don't, without a byte-stability run.
- */
-export const WORLD_DEFAULT: ResolvedConvention = {
-	candidateStrategies: ["postcode_area_resolution", "fallback_fuzzy_name_match"],
-	scoringWeights: { pc: 0.6, name: 0.3, pop: 0.1 },
-}
-
-/**
- * The strategy names the backend registers. The single source of truth shared by the dispatch registry and the
- * build-time validator, so an authored convention that names a non-existent strategy is caught at build (loud) rather
- * than silently skipped at runtime.
- */
-export const BUILTIN_STRATEGY_NAMES = ["postcode_area_resolution", "fallback_fuzzy_name_match"] as const
-
-/**
- * Table name for the convention asset (#290). Carried here so the build script, the runtime source, and the extract
- * auto-detect all agree.
- */
-export const ADDRESS_CONVENTION_TABLE = "address_convention"
-
-/**
- * A named resolution primitive. Returns `null` to abstain (condition unmet / no data) → the dispatcher tries the next
- * strategy; returns an array (possibly empty) to claim the result.
- */
-export type Strategy = (query: FindPlaceQuery, convention: ResolvedConvention) => Promise<PlaceCandidate[] | null>
-
-/**
- * Look up a convention record by WOF polygon id. Returns `undefined` when the polygon has no override.
- */
-export interface ConventionSource {
-	get(wofID: number): Convention | undefined
-}
-
-/**
- * In-memory convention source seeded from a `{ wofID: Convention }` map. Empty for the EU locales (they ride
- * `WORLD_DEFAULT`); JP / KR / TW add rows. #290 replaces this with a sqlite-backed source built from source, same
- * distributable-asset discipline as `postcode-locality-intl.db`.
- */
-export class SeedConventionSource implements ConventionSource {
-	readonly #rows: Map<number, Convention>
-
-	constructor(rows: Record<number, Convention> = {}) {
-		this.#rows = new Map(Object.entries(rows).map(([k, v]) => [Number(k), v]))
-	}
-
-	get(wofID: number): Convention | undefined {
-		return this.#rows.get(wofID)
-	}
-}
-
-/**
- * Deep-merge convention layers, later (more-specific) layers winning per field. `candidateStrategies` is replaced
- * wholesale — a convention names its full ordered list, it does not append. `scoringWeights` is merged key-by-key so a
- * locality can nudge one weight without restating the others.
- */
-export function mergeConventions(base: Convention, ...overrides: Array<Convention | undefined>): Convention {
-	const out: Convention = {
-		candidateStrategies: base.candidateStrategies ? [...base.candidateStrategies] : undefined,
-		scoringWeights: base.scoringWeights ? { ...base.scoringWeights } : undefined,
-	}
-
-	for (const o of overrides) {
-		if (!o) continue
-
-		if (o.candidateStrategies !== undefined) {
-			out.candidateStrategies = [...o.candidateStrategies]
-		}
-
-		if (o.scoringWeights !== undefined) {
-			out.scoringWeights = { ...(out.scoringWeights ?? WORLD_DEFAULT.scoringWeights), ...o.scoringWeights }
-		}
-	}
-
-	return out
-}
-
-/**
- * Resolve the effective convention for a place given its ancestor chain, ordered MOST-GENERAL → MOST-SPECIFIC (country,
- * region, …, locality). Starts from `WORLD_DEFAULT` so every field is defined regardless of which (if any) ancestors
- * carry an override.
- */
-export function resolveConvention(source: ConventionSource, ancestorIDs: readonly number[]): ResolvedConvention {
-	const layers = ancestorIDs.map((id) => source.get(id))
-	const merged = mergeConventions(WORLD_DEFAULT, ...layers)
-
-	return {
-		candidateStrategies: merged.candidateStrategies ?? WORLD_DEFAULT.candidateStrategies,
-		// Fill any weight gaps from the base so strategies always see a complete set.
-		scoringWeights: { ...WORLD_DEFAULT.scoringWeights, ...merged.scoringWeights },
-	}
-}