@mailwoman/resolver-wof-sqlite 9.0.0 → 9.2.0

package/place-importance-schema.ts

@@ -0,0 +1,402 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The TWO-SCORE SPLIT (ROAD_TO_V9 §2 R1) — typed schema, table builder, and the two derivations, in
+ *   one module so the read contract and the DDL cannot drift.
+ *
+ *   THE POLICY THIS ENCODES, ratified 2026-08-06: **the importance of a knowledge-base article is not
+ *   the probability that this is the place the user means.** The geocoder ranks by REFERENTIAL
+ *   likelihood; encyclopedic importance is carried as data and is never the ranking key. So the one
+ *   `place_importance.importance` column — which was a Wikipedia score where the concordance join
+ *   landed and a population-derived pseudo-score everywhere else — becomes two named columns that can
+ *   never be confused for one another:
+ *
+ *   - {@link PlaceImportanceTable.referential} — population-anchored, ALWAYS derivable, the ranking
+ *     backbone. {@link referentialFromPopulation} is the normalization the FST builder's population
+ *     fallback has always used; naming it here is the whole change.
+ *   - {@link PlaceImportanceTable.encyclopedic} — the fan-out-guarded Wikipedia join
+ *     (`importance-fanout.ts`, #1497). NULLABLE, and null means ABSENT, never "an importance of
+ *     zero": ~1.5 M of the 1.54 M rows in the 2026-08-05 build have no Wikipedia article at all, and
+ *     a consumer that reads a 0 there would be reading a fact nobody recorded.
+ *
+ *   WHY SAINT-DENIS IS THE TEST. The Seine-Saint-Denis suburb (pop 96,128) carries encyclopedic
+ *   0.1173; the Aude hamlet (pop 418) carries 0.5683 — the encyclopedic signal ranks the hamlet 4.8x
+ *   ABOVE the place every user means. Referentially the suburb wins by 230x on population. One score
+ *   cannot serve both readers, which is why there are two.
+ *
+ *   THE LEGACY COLUMN STAYS, AND IS DERIVED. `importance` is written by {@link blendImportance} — the
+ *   bounded blend the bare-toponym fame consumer (#28) ranks on. It is the CONFLATION, and nothing new
+ *   should read it; new code reads the split columns.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import { referentialFromPopulation } from "@mailwoman/core/resolver"
+import type { Kysely } from "kysely"
+
+import { allRows } from "./sqlite-utils.ts"
+
+//#region Schema
+
+/**
+ * One row of `place_importance`. Keyed by WOF place id.
+ */
+export interface PlaceImportanceTable {
+	id: number
+	/**
+	 * Population-anchored referential likelihood in [0, 1] — see {@link referentialFromPopulation}. NOT NULL because it is
+	 * always derivable: a place with no population row scores 0, which here genuinely means "no population evidence", the
+	 * same state the ranking has always treated as "no boost, never a penalty".
+	 */
+	referential: number
+	/**
+	 * Fan-out-guarded Wikipedia importance in [0, 1], or NULL when this place has no surviving concordance. NULL is
+	 * ABSENCE — never coalesce it to 0 in a consumer, and never rank on it at all.
+	 */
+	encyclopedic: number | null
+	/**
+	 * DEPRECATED — the pre-split conflation, written by {@link blendImportance} so the bare-toponym fame consumer (#28)
+	 * keeps one cross-bearer scale. New code reads {@link PlaceImportanceTable.referential} (to rank) or
+	 * {@link PlaceImportanceTable.encyclopedic} (to display).
+	 */
+	importance: number
+}
+
+/**
+ * The `place_importance` slice of a WOF admin database, for `new DatabaseClient<PlaceImportanceDatabase>(...)`.
+ */
+export interface PlaceImportanceDatabase {
+	place_importance: PlaceImportanceTable
+}
+
+/**
+ * The columns in declaration order. The builder's INSERT derives its column list from this, so a field added to
+ * {@link PlaceImportanceTable} without a matching DDL column is a compile error at the insert site.
+ */
+export const PLACE_IMPORTANCE_COLUMNS = [
+	"id",
+	"referential",
+	"encyclopedic",
+	"importance",
+] as const satisfies readonly (keyof PlaceImportanceTable)[]
+
+/**
+ * Create `place_importance` at the split schema. Drops any existing table first — this is a rebuild-in-place step of
+ * `mailwoman gazetteer importance`, never a migration.
+ */
+export async function createPlaceImportanceTable(db: Kysely<PlaceImportanceDatabase>): Promise<void> {
+	await db.schema.dropTable("place_importance").ifExists().execute()
+
+	await db.schema
+		.createTable("place_importance")
+		.addColumn("id", "integer", (c) => c.primaryKey())
+		.addColumn("referential", "real", (c) => c.notNull())
+		.addColumn("encyclopedic", "real")
+		.addColumn("importance", "real", (c) => c.notNull())
+		.execute()
+}
+
+//#endregion
+
+//#region The referential derivation
+
+/**
+ * Re-exported from `@mailwoman/core/resolver`, which is where the derivation lives so that `@mailwoman/resolver`
+ * (backend-agnostic — it cannot import this package) reads the same number. Re-exported HERE so the schema module stays
+ * the one-stop read for the table: the column and the function that fills it are one hop apart.
+ */
+export {
+	compareReferential,
+	REFERENTIAL_LOG2_SCALE,
+	REFERENTIAL_POPULATION_DIVISOR,
+	REFERENTIAL_SATURATION_POPULATION,
+	referentialFromPopulation,
+} from "@mailwoman/core/resolver"
+
+//#endregion
+
+//#region The legacy blend
+
+/**
+ * The most the encyclopedic channel may raise a place's blended importance above its population-anchored referential
+ * score.
+ *
+ * In referential units 0.25 is 3.5 population doublings (the referential curve divides log2 by 14), so an article can
+ * promote a place as if it were up to ~11x its recorded population — never more. The bound exists because the two
+ * channels' scales CROSS at the article floor: merely having a Wikipedia article scores ~0.25–0.35, which exceeds the
+ * referential score of a mid-size town, so an unbounded blend ranks a 136-person village with an article above a
+ * 16,026-person town without one.
+ *
+ * The value is bracketed by two decided contests, measured on the 2026-08-24 staging build:
+ *
+ * - `> 0.2282`, or bare `Whitby` stops answering Whitby GB (pop 13,130, referential 0.2729, encyclopedic 0.5496) over
+ *   Whitby CA (pop 128,377, referential 0.5011) — the #28 design case the fame prior exists to serve.
+ * - `< 0.2790`, or bare `Tó`/`To` answers Tó PT (pop 136, referential 0.0131, encyclopedic 0.3375) over Tô BF (pop
+ *   16,026, no article) — the `bf-gloss-to-*` board pair.
+ *
+ * 0.25 sits mid-interval with ~0.02 margin to each bound.
+ */
+export const ENCYCLOPEDIC_BOOST_CAP = 0.25
+
+/**
+ * The legacy `importance` blend — one cross-bearer fame scale for the #28 consumer, derived from the two split
+ * channels:
+ *
+ * - No article → the referential score.
+ * - No population evidence (`referential` 0) → the encyclopedic score stands alone: there is nothing to bound the
+ *   article's claim against, and a constant cap would demote every famous place WOF records no population for
+ *   (meaning-of-zero: referential 0 is "unmeasured", not "tiny").
+ * - Both present → the encyclopedic value clamped to at most {@link ENCYCLOPEDIC_BOOST_CAP} above the referential score,
+ *   and never below it. The floor half repairs the downward inversion (the Seine-Saint-Denis suburb's weak article
+ *   scored 0.1173 and REPLACED its referential 0.4716 under the old `COALESCE`, so a 418-person Aude hamlet outranked
+ *   it 4.8x); the cap half repairs the upward one (`Tó`, above).
+ *
+ * Scale of the clamp on the 2026-08-24 staging build: of 628,202 article-bearing rows, 209,738 sit above the cap and
+ * 13,888 sit below their referential floor; the 305,168 article-without-population rows pass through unchanged.
+ */
+export function blendImportance(referential: number, encyclopedic: number | null | undefined): number {
+	if (encyclopedic === null || encyclopedic === undefined) return referential
+
+	if (referential <= 0) return encyclopedic
+
+	return Math.max(referential, Math.min(encyclopedic, referential + ENCYCLOPEDIC_BOOST_CAP))
+}
+
+//#endregion
+
+//#region Reading a database that may or may not carry the split
+
+/**
+ * Where a reader's two scores came from. Recorded into the FST stamp so an artifact says, in its own provenance,
+ * whether its encyclopedic channel is real, reconstructed, or absent.
+ */
+export const IMPORTANCE_SPLIT_SOURCES = {
+	/**
+	 * `place_importance` carries `referential` + `encyclopedic` — the post-split build.
+	 */
+	splitColumns: "split-columns",
+	/**
+	 * `place_importance` carries only the conflated `importance`; the split was RECONSTRUCTED against `place_population`
+	 * (see {@link splitLegacyImportance}).
+	 */
+	legacyReconstructed: "legacy-reconstructed",
+	/**
+	 * No `place_importance` at all — referential from `place_population`, encyclopedic absent for every place.
+	 */
+	populationOnly: "population-only",
+	/**
+	 * Neither table. Every score is 0, and 0 here means the database carries no salience evidence whatsoever.
+	 */
+	none: "none",
+} as const
+
+export type ImportanceSplitSource = (typeof IMPORTANCE_SPLIT_SOURCES)[keyof typeof IMPORTANCE_SPLIT_SOURCES]
+
+/**
+ * The `SELECT` term and `LEFT JOIN` a name lookup needs in order to CARRY `encyclopedic` onto its results, probed
+ * against `schemaName`'s `place_importance`.
+ *
+ * THE PROBE IS A COLUMN, NOT A TABLE, and that is the whole reason this lives here rather than beside a caller's other
+ * table probes. The pre-split table exists and holds a single conflated `importance` column whose value is a Wikipedia
+ * score on some rows and a population proxy on others, with nothing in the row to say which — reading that as
+ * encyclopedic would surface the exact confusion ROAD_TO_V9 §2 exists to end.
+ *
+ * There is deliberately no ORDER BY counterpart, and there should never be one: §2's policy is that this score is
+ * carried and never ranked on. Without the column the select degrades to a literal `NULL` and the join is the empty
+ * string, so a pre-split shard's query plan is byte-identical to what it was before the split. No shipped gazetteer
+ * carries the column yet, so today that degraded form is the only one anything builds.
+ *
+ * Call it ONCE per shard and cache the result — it runs a `PRAGMA`, and the callers are per-keystroke hot.
+ */
+export function encyclopedicClauses(db: DatabaseSync, schemaName: string): { select: string; join: string } {
+	let present: boolean
+
+	try {
+		const rows = allRows<{ name: string }>(db.prepare(`PRAGMA ${schemaName}.table_info(place_importance)`))
+
+		present = rows.some((r) => r.name === "encyclopedic")
+	} catch {
+		present = false
+	}
+
+	if (!present) return { select: "NULL AS encyclopedic", join: "" }
+
+	return {
+		select: "place_importance.encyclopedic AS encyclopedic",
+		join: `LEFT JOIN ${schemaName}.place_importance ON place_importance.id = spr.id`,
+	}
+}
+
+/**
+ * The tolerance {@link splitLegacyImportance} treats as "this value reproduces the population curve". Eight ULP —
+ * comfortably wider than the one-ULP `log2` spread measured between CPython and V8 (see that function's docstring), and
+ * ~1e-15 absolute against scores Nominatim publishes to four decimals.
+ */
+export const LEGACY_FALLBACK_EPSILON = 8 * Number.EPSILON
+
+/**
+ * Split one row of a LEGACY (pre-split) `place_importance` table back into its two components.
+ *
+ * WHY THIS IS RECOVERABLE AT ALL. The legacy builder ran in two passes: Wikipedia scores first, then `INSERT OR IGNORE`
+ * of `min(1, log2(1+pop/1000)/14)` for every place with a population that Wikipedia had missed. So a legacy value is a
+ * fallback row IFF it reproduces {@link referentialFromPopulation} of that place's population — the two passes wrote
+ * different arithmetic, and a score from Nominatim's four-decimal TSV landing on the log2 curve is a measure-zero
+ * event.
+ *
+ * THE COMPARISON IS ULP-TOLERANT, AND THAT IS NOT DEFENSIVE PADDING. The first version compared for exact bit equality,
+ * which is correct — in the runtime that wrote the values. Cross-checking the same rule in CPython returned 166,638
+ * encyclopedic rows against Node's 133,096: `math.log2` and V8's `Math.log2` disagree by one ULP on 33,542 of the 1.5 M
+ * inputs (worked example: wof 85803233, population 21,299 — stored 0.31992193633838988953, CPython
+ * 0.31992193633838994504, delta 5.55e-17). Bit equality would therefore INVENT 33,542 encyclopedic scores for anyone
+ * who ported this rule to another runtime, and invented data is the failure mode this whole module exists to end. The
+ * tolerance is a few ULP of the score's own magnitude; a genuine Wikipedia value that close to the population curve is
+ * not distinguishable from it by any consequence.
+ *
+ * MEASURED, not reasoned (2026-08-06, `wof/fst-staging-2026-08-05/admin-global-priority-importance.db`): 1,543,753 rows
+ * split **1,410,657 fallback / 133,096 encyclopedic**, and the arithmetic closes on itself — 1,410,657 + 108,861
+ * (encyclopedic rows that ALSO have a population) = 1,519,518, which is exactly the count of `place_population` rows
+ * with `population > 0`, i.e. every row the fallback pass could have written. The remaining 24,235 encyclopedic rows
+ * have no population row at all. Under the exact-equality rule, Node found ZERO mismatches within one ULP, so the
+ * tolerance changes no classification on this database — it only makes the answer runtime-independent.
+ *
+ * Referential is NOT read out of the legacy column under any branch — it is always re-derived from population, because
+ * a legacy Wikipedia row overwrote whatever population would have said.
+ */
+export function splitLegacyImportance(
+	legacy: number | undefined,
+	population: number | null | undefined
+): { referential: number; encyclopedic?: number } {
+	const referential = referentialFromPopulation(population)
+
+	if (legacy === undefined) return { referential }
+
+	if (Math.abs(legacy - referential) <= LEGACY_FALLBACK_EPSILON * Math.max(referential, 1)) return { referential }
+
+	return { referential, encyclopedic: legacy }
+}
+
+/**
+ * The two score maps a builder needs, plus the provenance of how they were obtained.
+ */
+export interface ImportanceSplit {
+	/**
+	 * WOF id → referential likelihood. Sparse: absent means 0 (no population evidence).
+	 */
+	referential: Map<number, number>
+	/**
+	 * WOF id → encyclopedic importance. Sparse, and ABSENCE IS ABSENCE — never fill a 0 in.
+	 */
+	encyclopedic: Map<number, number>
+	source: ImportanceSplitSource
+	/**
+	 * Rows the legacy reconstruction attributed to the population fallback (only meaningful under
+	 * {@link IMPORTANCE_SPLIT_SOURCES.legacyReconstructed}).
+	 */
+	legacyFallbackRows: number
+}
+
+/**
+ * Does `table` exist in `db`, and if so which of `columns` does it have?
+ */
+function tableColumns(db: DatabaseSync, table: string): Set<string> {
+	try {
+		const rows = allRows<{ name: string }>(db.prepare(`PRAGMA table_info(${table})`))
+
+		return new Set(rows.map((r) => r.name))
+	} catch {
+		return new Set()
+	}
+}
+
+/**
+ * Load both scores from a WOF admin database, whatever schema generation it is at.
+ *
+ * Handles all four states in {@link IMPORTANCE_SPLIT_SOURCES} so callers never branch on schema themselves — the FST
+ * builder in particular must read the shipped population-only databases, the read-only 2026-08-05 staging database
+ * (legacy conflated column), and post-split builds with one code path.
+ */
+export function loadImportanceSplit(db: DatabaseSync): ImportanceSplit {
+	const referential = new Map<number, number>()
+	const encyclopedic = new Map<number, number>()
+	const population = new Map<number, number>()
+
+	const populationColumns = tableColumns(db, "place_population")
+
+	if (populationColumns.has("population")) {
+		const rows = allRows<{
+			id: number
+			population: number
+		}>(db.prepare("SELECT id, population FROM place_population"))
+
+		for (const row of rows) {
+			population.set(row.id, row.population)
+			const score = referentialFromPopulation(row.population)
+
+			if (score > 0) {
+				referential.set(row.id, score)
+			}
+		}
+	}
+
+	const importanceColumns = tableColumns(db, "place_importance")
+
+	if (importanceColumns.has("referential")) {
+		// Post-split build: the columns ARE the contract. Referential is read verbatim rather than
+		// re-derived, so a build that scored referential differently stays visible instead of being
+		// silently overwritten by this reader's own formula.
+		const rows = allRows<{
+			id: number
+			referential: number
+			encyclopedic: number | null
+		}>(db.prepare("SELECT id, referential, encyclopedic FROM place_importance"))
+
+		for (const row of rows) {
+			if (row.referential > 0) {
+				referential.set(row.id, row.referential)
+			}
+
+			if (row.encyclopedic !== null) {
+				encyclopedic.set(row.id, row.encyclopedic)
+			}
+		}
+
+		return { referential, encyclopedic, source: IMPORTANCE_SPLIT_SOURCES.splitColumns, legacyFallbackRows: 0 }
+	}
+
+	if (importanceColumns.has("importance")) {
+		const rows = allRows<{
+			id: number
+			importance: number
+		}>(db.prepare("SELECT id, importance FROM place_importance"))
+
+		let legacyFallbackRows = 0
+
+		for (const row of rows) {
+			const split = splitLegacyImportance(row.importance, population.get(row.id))
+
+			if (split.encyclopedic === undefined) {
+				legacyFallbackRows++
+			} else {
+				encyclopedic.set(row.id, split.encyclopedic)
+			}
+		}
+
+		return {
+			referential,
+			encyclopedic,
+			source: IMPORTANCE_SPLIT_SOURCES.legacyReconstructed,
+			legacyFallbackRows,
+		}
+	}
+
+	return {
+		referential,
+		encyclopedic,
+		source: referential.size ? IMPORTANCE_SPLIT_SOURCES.populationOnly : IMPORTANCE_SPLIT_SOURCES.none,
+		legacyFallbackRows: 0,
+	}
+}
+
+//#endregion

package/poi-lookup.ts

@@ -31,6 +31,7 @@ import { haversineKm, shortCellToInt, type H3Cell } from "@mailwoman/spatial"
 import { gridDisk, latLngToCell } from "h3-js"
 
 import type { POICategoryCodeTable, POITable } from "./poi-schema.ts"
+import { allRows } from "./sqlite-utils.ts"
 
 /**
  * Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4).
@@ -141,7 +142,7 @@ type POIRow = Pick<
 /**
  * Node reader over `poi.db`. `implements Disposable` so callers can `using lookup = new POILookup(...)` (or call
  * `[Symbol.dispose]()` explicitly), the same precedent as {@link WOFCandidateTableLookup} /
- * {@link WOFSqlitePlaceLookup}.
+ * {@link WOFSQLitePlaceLookup}.
  */
 export class POILookup implements Disposable {
 	#db: DatabaseSync
@@ -175,9 +176,7 @@ export class POILookup implements Disposable {
 
 		// The category dictionary is tiny (poi-taxonomy's category count) — load it once at
 		// construction so `search` never round-trips to it.
-		for (const r of this.#db
-			.prepare("SELECT id, category FROM poi_category_codes")
-			.all() as unknown as POICategoryCodeTable[]) {
+		for (const r of allRows<POICategoryCodeTable>(this.#db.prepare("SELECT id, category FROM poi_category_codes"))) {
 			this.#categoryToID.set(String(r.category), Number(r.id))
 			this.#idToCategory.set(Number(r.id), String(r.category))
 		}
@@ -226,7 +225,7 @@ export class POILookup implements Disposable {
 	 * nearest at any distance — the reach ceiling k-ring hits on sparse brand rows is gone.
 	 */
 	#searchBrand(brandWikidata: string, center: { latitude: number; longitude: number }, limit: number): POISearchHit[] {
-		const rows = this.#brandProbe.all(brandWikidata) as unknown as POIRow[]
+		const rows = allRows<POIRow>(this.#brandProbe, brandWikidata)
 
 		return sortByDistance(rows, center)
 			.filter(
@@ -242,7 +241,7 @@ export class POILookup implements Disposable {
 	#searchKRing(query: POISearchQuery, limit: number): POISearchHit[] {
 		const center = query.center!
 		const maxRings = query.maxRings ?? DEFAULT_MAX_RINGS
-		const categoryIds: number[] = []
+		const categoryIDs: number[] = []
 
 		// `categoryIDs` (the fan-out list) supersedes the single `categoryID`; either way, resolve each id through the
 		// dictionary and drop the ones the db doesn't carry (Overture-taxonomy drift, or an identity id with no rows).
@@ -252,12 +251,12 @@ export class POILookup implements Disposable {
 			const resolved = this.#categoryToID.get(id)
 
 			if (resolved !== undefined) {
-				categoryIds.push(resolved)
+				categoryIDs.push(resolved)
 			}
 		}
 
 		// No resolvable leaf (every id unknown to the dictionary) can't have rows — a clean miss, not a throw.
-		if (!categoryIds.length) return []
+		if (!categoryIDs.length) return []
 
 		const origin = latLngToCell(center.latitude, center.longitude, POI_H3_RESOLUTION) as H3Cell
 		const seenCells = new Set<string>()
@@ -276,8 +275,8 @@ export class POILookup implements Disposable {
 
 				// Fan-out: probe every resolved Overture leaf for this canonical category, unioning the rows. The
 				// post-ring distance sort + `slice(0, limit)` below dedupes the pool down to the nearest `limit`.
-				for (const categoryID of categoryIds) {
-					rows.push(...(this.#categoryCellProbe.all(shortCell, categoryID, limit) as unknown as POIRow[]))
+				for (const categoryID of categoryIDs) {
+					rows.push(...allRows<POIRow>(this.#categoryCellProbe, shortCell, categoryID, limit))
 				}
 			}
 
@@ -301,7 +300,7 @@ export class POILookup implements Disposable {
 
 		if (!matchQuery) return []
 
-		const ftsHits = this.#nameFTSProbe.all(matchQuery, limit) as unknown as Array<{ name_key: string | null }>
+		const ftsHits = allRows<{ name_key: string | null }>(this.#nameFTSProbe, matchQuery, limit)
 		const uniqueKeys: string[] = []
 		const seenKeys = new Set<string>()
 
@@ -350,7 +349,7 @@ export class POILookup implements Disposable {
 		const placeholders = nameKeys.map(() => "?").join(", ")
 		const stmt = this.#db.prepare(`SELECT ${columns} FROM poi WHERE name_key IN (${placeholders})`)
 
-		return stmt.all(...nameKeys) as unknown as POIRow[]
+		return allRows<POIRow>(stmt, ...nameKeys)
 	}
 
 	close(): void {
@@ -406,7 +405,7 @@ function sanitizePOINameQuery(text: string): string {
 		.replaceAll(/["*:]/g, "")
 		.trim()
 		.split(/\s+/u)
-		.filter(Boolean)
+		.filter((token) => token.length > 0)
 		.map((token) => `"${token.replaceAll('"', '""')}"`)
 		.join(" ")
 }

package/poi-schema.ts

@@ -17,6 +17,8 @@ import type { DatabaseSync } from "node:sqlite"
 import type { LayerContractDatabase } from "@mailwoman/core/layers"
 import { sql, type Kysely } from "kysely"
 
+import type { NameKey } from "./street-normalize.ts"
+
 /**
  * One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key.
  */
@@ -39,9 +41,12 @@ export interface POITable {
 	rowid_key: number
 	name: string | null
 	/**
-	 * Lowercased, diacritic-flattened probe key for exact name lookups.
+	 * Probe key for exact name lookups, minted by {@link normalizeLocalityForKey} at build AND at query.
+	 *
+	 * Branded because a `toLowerCase()` approximation of the fold is still a `string`: it binds to the parameter, returns
+	 * fewer rows, and the shortfall reads as a coverage gap in the data rather than a defect in the probe.
 	 */
-	name_key: string | null
+	name_key: NameKey | null
 	brand_wikidata: string | null
 	latitude: number
 	longitude: number
@@ -69,7 +74,7 @@ export interface POIStageTable {
 	neg_rank: number | null
 	rowid_key: number | null
 	name: string | null
-	name_key: string | null
+	name_key: NameKey | null
 	brand_wikidata: string | null
 	latitude: number
 	longitude: number

package/polygon-schema.ts

@@ -0,0 +1,47 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the polygon sidecar (`wof-polygons.db`) — the one table `WOFReverseGeocoder` probes for a
+ *   place's geometry. The interface is the read/write contract and {@link createPolygonsTable} creates the table, so a
+ *   column added to one is a compile error against the other.
+ *
+ *   The sidecar is OPTIONAL to the reverse geocoder: without it every result falls back to a centroid, so the reader
+ *   checks for the table's presence rather than assuming it.
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * One admin polygon, keyed by WOF id.
+ */
+export interface PolygonsTable {
+	id: number
+	/**
+	 * The GeoJSON geometry, JSON-encoded. A row that fails to parse reads as no-polygon, never as an error — a malformed
+	 * geometry must not fail the whole reverse query.
+	 */
+	geom: string
+}
+
+export interface PolygonDatabase {
+	polygons: PolygonsTable
+}
+
+/**
+ * The slice of a Kysely handle the polygon DDL touches. Kysely is invariant in its schema parameter, so naming only
+ * `schema` lets a builder holding a wider handle pass it without a cast.
+ */
+export type PolygonSchemaHandle = Pick<Kysely<PolygonDatabase>, "schema">
+
+/**
+ * Create the `polygons` table — called before the streaming bulk load.
+ */
+export async function createPolygonsTable(db: PolygonSchemaHandle): Promise<void> {
+	await db.schema
+		.createTable("polygons")
+		.addColumn("id", "integer", (column) => column.primaryKey())
+		.addColumn("geom", "text", (column) => column.notNull())
+		.execute()
+}

package/postal-city-alias-lookup.ts

@@ -5,7 +5,7 @@
  *
  *   Node reader over the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`) — the observed
  *   `postal_city → geo_locality` aliases per postcode (`build-postal-city-alias.ts`). Consumed by
- *   {@link WOFSqlitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
+ *   {@link WOFSQLitePlaceLookup}'s coordinate-first locality scorer: a user-typed postal city
  *   ("Antioch", postcode 37013) becomes a name-match alias for the geographic locality the postcode
  *   actually sits in ("Nashville"), so the right place tiers to the top instead of a same-named
  *   town in another state. Opt-in — the lookup is only constructed when a path is supplied, and

package/postal-city-candidate-schema.ts

@@ -20,6 +20,8 @@
 
 import { sql, type Kysely } from "kysely"
 
+import type { NameKey } from "./street-normalize.ts"
+
 /**
  * One postal-city → geo-locality edge, keyed exactly by `(name_key, postcode)`. The probe returns the geographic
  * locality directly; the denormalized name/coord avoid a join back to `candidate`.
@@ -28,7 +30,7 @@ export interface PostalCityCandidateTable {
 	/**
 	 * {@link normalizeLocalityForKey} of the postal-city name — the build/query-consistent probe key.
 	 */
-	name_key: string
+	name_key: NameKey
 	/**
 	 * The postcode the alias is scoped to (the second half of the exact key).
 	 */

package/postcode-point-lookup.ts

@@ -13,7 +13,7 @@
  *   anchor only needs "does this string exist as a postcode, in which countries, near where". A
  *   future WASM build swaps this for an FST-backed resolver behind the same `lookup()` seam.
  *
- *   Why multiple shards instead of the multi-shard `WOFSqlitePlaceLookup`: that resolver routes a
+ *   Why multiple shards instead of the multi-shard `WOFSQLitePlaceLookup`: that resolver routes a
  *   query to ONE shard by placetype, but every postcode shard shares `placetype='postalcode'`, so a
  *   single query could only ever hit one country's shard. The anchor needs the union across
  *   countries to build its country posterior, so it queries each shard directly.