@mailwoman/resolver-wof-sqlite 7.1.0 → 7.2.1

package/poi-lookup.ts

@@ -0,0 +1,319 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node reader for `poi.db` (spec §3.4) — the res-9 k-ring reader over the clustered `poi`
+ *   `WITHOUT ROWID` B-tree Task 1's schema (`poi-schema.ts`) builds. Three search modes share one
+ *   artifact:
+ *
+ *   - **Category**: `latLngToCell(center, 9)` → `gridDisk` ring-by-ring expansion, probing each
+ *     cell's clustered `(h3_cell, category_id, neg_rank, …)` range. Rings accumulate until `limit`
+ *     rows are on hand after a completed ring, or `maxRings` is exhausted; the pool is sorted by
+ *     haversine distance from `center` after every ring.
+ *   - **Brand**: the same k-ring walk, but probing on `brand_wikidata` instead — category
+ *     unconstrained, so a chain's rows surface regardless of how they were categorized.
+ *   - **Name**: FTS5 `MATCH` against the `poi_search` virtual table, hydrated back to full rows by
+ *     `name_key`. No center required; if one is given, hits are still distance-sorted.
+ *
+ *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing that turns a raw H3
+ *   cell into the integer `poi.h3_cell` stores is `@mailwoman/spatial`'s `shortenH3Cell` — that math
+ *   is NEVER reimplemented here (see AGENTS.md on `@mailwoman/spatial` being the one true home for
+ *   it).
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { haversineKm, shortenH3Cell, type H3Cell } from "@mailwoman/spatial"
+import { gridDisk, latLngToCell } from "h3-js"
+
+import type { POICategoryCodeTable, POITable } from "./poi-schema.ts"
+
+/** Resolution the `poi` table's `h3_cell` column is keyed at — matches the builder (spec §3.4). */
+export const POI_H3_RESOLUTION = 9
+
+/** Ring budget default: 12 res-9 k-rings ≈ ~4 km. */
+const DEFAULT_MAX_RINGS = 12
+
+/** Row-count default when a query doesn't specify `limit`. */
+const DEFAULT_LIMIT = 20
+
+export interface POISearchQuery {
+	/** Poi-taxonomy category id (string side of the dictionary). Ignored when `brandWikidata` is also set — brand wins. */
+	categoryID?: string
+	/** Wikidata QID for brand-exact search. */
+	brandWikidata?: string
+	/** Free-text name (FTS5). */
+	name?: string
+	/** Search center. Required for category/brand queries (k-ring expansion). */
+	center?: { latitude: number; longitude: number }
+	/**
+	 * Ring budget: how many res-9 k-rings to expand before giving up (default 12 ≈ ~4 km). Counts ring 0, so k reaches
+	 * `maxRings - 1`.
+	 */
+	maxRings?: number
+	limit?: number
+}
+
+export interface POISearchHit {
+	name: string | null
+	categoryID: string | null
+	brandWikidata: string | null
+	latitude: number
+	longitude: number
+	country: string
+	confidence: number
+	distanceM?: number
+}
+
+export interface POILookupOpts {
+	/** Path to a `poi.db` built by the (future) POI builder. Opened read-only. */
+	databasePath?: string
+	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	database?: DatabaseSync
+}
+
+/** The `poi` columns every search mode hydrates — a typed projection of the SHARED {@link POITable}. */
+type POIRow = Pick<
+	POITable,
+	"name" | "category_id" | "brand_wikidata" | "latitude" | "longitude" | "country" | "confidence" | "name_key"
+>
+
+/**
+ * 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}.
+ */
+export class POILookup implements Disposable {
+	#db: DatabaseSync
+	#ownsDB: boolean
+	readonly #categoryToID = new Map<string, number>()
+	readonly #idToCategory = new Map<number, string>()
+
+	/** `(h3_cell, category_id)` → the cell's category-clustered range, most-confident-first. */
+	readonly #categoryCellProbe: ReturnType<DatabaseSync["prepare"]>
+	/** `(h3_cell, brand_wikidata)` → the cell's brand-matched rows (category unconstrained). */
+	readonly #brandCellProbe: ReturnType<DatabaseSync["prepare"]>
+	/** FTS5 `MATCH` over `poi_search`, returning candidate `name_key`s to hydrate. */
+	readonly #nameFTSProbe: ReturnType<DatabaseSync["prepare"]>
+
+	constructor(opts: POILookupOpts) {
+		if (opts.database) {
+			this.#db = opts.database
+			this.#ownsDB = false
+		} else if (opts.databasePath) {
+			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
+			this.#ownsDB = true
+		} else {
+			throw new Error("POILookup needs `databasePath` or `database`")
+		}
+
+		// 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[]) {
+			this.#categoryToID.set(String(r.category), Number(r.id))
+			this.#idToCategory.set(Number(r.id), String(r.category))
+		}
+
+		const columns = "name, category_id, brand_wikidata, latitude, longitude, country, confidence, name_key"
+
+		this.#categoryCellProbe = this.#db.prepare(
+			`SELECT ${columns} FROM poi WHERE h3_cell = ? AND category_id = ? ORDER BY neg_rank ASC LIMIT ?`
+		)
+		this.#brandCellProbe = this.#db.prepare(
+			`SELECT ${columns} FROM poi WHERE h3_cell = ? AND brand_wikidata = ? ORDER BY neg_rank ASC LIMIT ?`
+		)
+		this.#nameFTSProbe = this.#db.prepare(
+			"SELECT name_key FROM poi_search WHERE poi_search MATCH ? ORDER BY bm25(poi_search) LIMIT ?"
+		)
+	}
+
+	search(query: POISearchQuery): POISearchHit[] {
+		const limit = Math.max(1, query.limit ?? DEFAULT_LIMIT)
+
+		if (query.name) {
+			return this.#searchByName(query.name, limit, query.center)
+		}
+
+		if (query.categoryID || query.brandWikidata) {
+			if (!query.center) {
+				throw new Error("POILookup.search: category/brand search requires a `center`")
+			}
+
+			return this.#searchKRing(query, limit)
+		}
+
+		return []
+	}
+
+	/** Category or brand path: k-ring expansion from `query.center`'s res-9 cell, probing each new ring's cells. */
+	#searchKRing(query: POISearchQuery, limit: number): POISearchHit[] {
+		const center = query.center!
+		const maxRings = query.maxRings ?? DEFAULT_MAX_RINGS
+		let categoryId: number | undefined
+
+		// brandWikidata wins over categoryID when both are set — see POISearchQuery.categoryID.
+		if (!query.brandWikidata) {
+			categoryId = this.#categoryToID.get(query.categoryID!)
+
+			// An unknown category (not in the dictionary) can't have rows — a clean miss, not a throw.
+			if (categoryId === undefined) return []
+		}
+
+		const origin = latLngToCell(center.latitude, center.longitude, POI_H3_RESOLUTION) as H3Cell
+		const seenCells = new Set<string>()
+		let rows: POIRow[] = []
+
+		// `ring` starts at 0 (the origin cell itself), so this loop's k reaches `maxRings - 1`.
+		for (let ring = 0; ring < maxRings; ring++) {
+			// gridDisk(origin, ring) returns the WHOLE disk out to `ring`; diffing against what's
+			// already been probed derives just this ring's new cells.
+			const diskCells = gridDisk(origin, ring) as string[]
+			const newCells = diskCells.filter((cell) => !seenCells.has(cell))
+
+			for (const cell of newCells) {
+				seenCells.add(cell)
+				const shortCell = h3CellToInt(cell as H3Cell)
+
+				const hits = query.brandWikidata
+					? (this.#brandCellProbe.all(shortCell, query.brandWikidata, limit) as unknown as POIRow[])
+					: (this.#categoryCellProbe.all(shortCell, categoryId!, limit) as unknown as POIRow[])
+
+				rows.push(...hits)
+			}
+
+			rows = sortByDistance(rows, center)
+
+			if (rows.length >= limit) break
+		}
+
+		return rows.slice(0, limit).map((row) => toHit(row, this.#idToCategory, center))
+	}
+
+	/**
+	 * Name path: FTS5 MATCH → hydrate by name_key. No center required; distance-sorts if one is given anyway.
+	 *
+	 * Hydration is ONE batched `WHERE name_key IN (...)` query over the FTS hits' unique `name_key`s, not a per-hit probe
+	 * — with up to `limit` FTS hits, a per-hit probe was up to `limit` full table scans before `createPOINameKeyIndex`
+	 * (poi-schema.ts) + this batching.
+	 */
+	#searchByName(name: string, limit: number, center?: { latitude: number; longitude: number }): POISearchHit[] {
+		const matchQuery = sanitizePOINameQuery(name)
+
+		if (!matchQuery) return []
+
+		const ftsHits = this.#nameFTSProbe.all(matchQuery, limit) as unknown as Array<{ name_key: string | null }>
+		const uniqueKeys: string[] = []
+		const seenKeys = new Set<string>()
+
+		for (const hit of ftsHits) {
+			if (!hit.name_key || seenKeys.has(hit.name_key)) continue
+			seenKeys.add(hit.name_key)
+			uniqueKeys.push(hit.name_key)
+		}
+
+		if (uniqueKeys.length === 0) return []
+
+		const hydrated = this.#hydrateByNameKeys(uniqueKeys)
+		const rowsByKey = new Map<string, POIRow[]>()
+
+		for (const row of hydrated) {
+			if (row.name_key === null) continue
+			const bucket = rowsByKey.get(row.name_key)
+
+			if (bucket) {
+				bucket.push(row)
+			} else {
+				rowsByKey.set(row.name_key, [row])
+			}
+		}
+
+		let rows: POIRow[] = []
+
+		for (const key of uniqueKeys) {
+			rows.push(...(rowsByKey.get(key) ?? []))
+		}
+
+		if (center) {
+			rows = sortByDistance(rows, center)
+		}
+
+		return rows.slice(0, limit).map((row) => toHit(row, this.#idToCategory, center))
+	}
+
+	/**
+	 * Batched hydration for the FTS name path: `WHERE name_key IN (?, ?, …)`, one query for the whole batch instead of
+	 * one probe per FTS hit. This is a cold path (name search only) with variable arity per call, so the statement is
+	 * prepared fresh each time rather than cached.
+	 */
+	#hydrateByNameKeys(nameKeys: string[]): POIRow[] {
+		const columns = "name, category_id, brand_wikidata, latitude, longitude, country, confidence, name_key"
+		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[]
+	}
+
+	close(): void {
+		if (this.#ownsDB) {
+			this.#db.close()
+		}
+	}
+
+	[Symbol.dispose](): void {
+		this.close()
+	}
+}
+
+/** `poi.h3_cell` is the SHORTENED (48-bit) cell — never the full h3-js cell string. */
+function h3CellToInt(cell: H3Cell): number {
+	return Number(BigInt(`0x${shortenH3Cell(cell)}`))
+}
+
+function sortByDistance(rows: POIRow[], center: { latitude: number; longitude: number }): POIRow[] {
+	return [...rows].sort(
+		(a, b) =>
+			haversineKm(center.latitude, center.longitude, a.latitude, a.longitude) -
+			haversineKm(center.latitude, center.longitude, b.latitude, b.longitude)
+	)
+}
+
+function toHit(
+	row: POIRow,
+	idToCategory: ReadonlyMap<number, string>,
+	center?: { latitude: number; longitude: number }
+): POISearchHit {
+	return {
+		name: row.name,
+		categoryID: row.category_id !== 0 ? (idToCategory.get(row.category_id) ?? null) : null,
+		brandWikidata: row.brand_wikidata,
+		latitude: row.latitude,
+		longitude: row.longitude,
+		country: row.country,
+		confidence: row.confidence,
+		...(center
+			? { distanceM: haversineKm(center.latitude, center.longitude, row.latitude, row.longitude) * 1000 }
+			: {}),
+	}
+}
+
+/**
+ * Sanitize free text into an FTS5-safe MATCH query: strip the characters FTS5 would otherwise read as syntax (`"`
+ * phrase delimiters, `*` prefix wildcards, `:` column-filter separators), then phrase-quote each whitespace-separated
+ * token (AND-joined).
+ *
+ * `resolver-wof-sqlite` already has this discipline — `lookup.ts`'s `sanitizeFTSQuery` — but that function is
+ * module-private there (not re-exported from `fts.ts` or the package's `index.ts`), so this replicates the same
+ * discipline locally rather than reaching across the module boundary for a private helper.
+ */
+function sanitizePOINameQuery(text: string): string {
+	return text
+		.replace(/["*:]/g, "")
+		.trim()
+		.split(/\s+/u)
+		.filter(Boolean)
+		.map((token) => `"${token.replace(/"/g, '""')}"`)
+		.join(" ")
+}

package/poi-schema.ts

@@ -0,0 +1,147 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for poi.db — spatial layer #1 (spec §3.4). One clustered `WITHOUT ROWID` B-tree
+ *   keyed `(h3_cell, category_id, neg_rank, rowid_key)` so "everything near this res-9 cell" is a
+ *   contiguous key range (the byte-range/httpvfs access pattern, same discipline as the candidate
+ *   gazetteer). Rows carry denormalized name/brand/coords; category ids are small ints via the
+ *   `poi_category_codes` dictionary (poi-taxonomy category ids are the string side). The DB also
+ *   embeds the layer-contract tables from `@mailwoman/core/layers` — the builder writes the
+ *   manifest (tier `shipped`, spine `h3` res 9) and per-res-6-cell coverage.
+ */
+
+import type { DatabaseSync } from "node:sqlite"
+
+import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import { sql, type Kysely } from "kysely"
+
+/** One POI row. Clustered PK: h3_cell → category_id → neg_rank → rowid_key. */
+export interface POITable {
+	/** 48-bit short H3 cell at res 9 (`latLngToCell` → `shortenH3Cell`). */
+	h3_cell: number
+	/** Small int from {@link POICategoryCodeTable}; 0 = uncategorized. */
+	category_id: number
+	/** `-log10(confidence + epsilon)` so ASC = most-confident-first within a cell+category. */
+	neg_rank: number
+	/** Uniquifier within the clustered key (builder-assigned monotonic int). */
+	rowid_key: number
+	name: string | null
+	/** Lowercased, diacritic-flattened probe key for exact name lookups. */
+	name_key: string | null
+	brand_wikidata: string | null
+	latitude: number
+	longitude: number
+	/** ISO 3166-1 alpha-2 (from the Overture partition). */
+	country: string
+	/** Overture existence confidence (already filtered ≥ 0.85 at build). */
+	confidence: number
+	/** GERS id — nullable METADATA ONLY, never a key (the #470 rule). */
+	gers_id: string | null
+}
+
+/**
+ * Staging mirror — every column nullable except the coords (the loader fills positionally; the materialize SELECT
+ * enforces completeness).
+ */
+export interface POIStageTable {
+	h3_cell: number | null
+	category_id: number | null
+	neg_rank: number | null
+	rowid_key: number | null
+	name: string | null
+	name_key: string | null
+	brand_wikidata: string | null
+	latitude: number
+	longitude: number
+	country: string | null
+	confidence: number | null
+	gers_id: string | null
+}
+
+/** `(id → poi-taxonomy category id)` dictionary, e.g. `3 → "cafe"`. */
+export interface POICategoryCodeTable {
+	id: number
+	category: string
+}
+
+export interface POIDatabase extends LayerContractDatabase {
+	poi: POITable
+	poi_stage: POIStageTable
+	poi_category_codes: POICategoryCodeTable
+}
+
+/** Clustered-key-order column list shared by builder + `INSERT INTO poi SELECT … FROM poi_stage`. */
+export const POI_COLUMNS = [
+	"h3_cell",
+	"category_id",
+	"neg_rank",
+	"rowid_key",
+	"name",
+	"name_key",
+	"brand_wikidata",
+	"latitude",
+	"longitude",
+	"country",
+	"confidence",
+	"gers_id",
+] as const
+
+export async function createPOIStagingTables(db: Kysely<POIDatabase>): Promise<void> {
+	await db.schema
+		.createTable("poi_category_codes")
+		.addColumn("id", "integer", (c) => c.primaryKey())
+		.addColumn("category", "text", (c) => c.unique())
+		.execute()
+	await db.schema
+		.createTable("poi_stage")
+		.addColumn("h3_cell", "integer")
+		.addColumn("category_id", "integer")
+		.addColumn("neg_rank", "real")
+		.addColumn("rowid_key", "integer")
+		.addColumn("name", "text")
+		.addColumn("name_key", "text")
+		.addColumn("brand_wikidata", "text")
+		.addColumn("latitude", "real")
+		.addColumn("longitude", "real")
+		.addColumn("country", "text")
+		.addColumn("confidence", "real")
+		.addColumn("gers_id", "text")
+		.execute()
+}
+
+export async function createPOITable(db: Kysely<POIDatabase>): Promise<void> {
+	await db.schema
+		.createTable("poi")
+		.addColumn("h3_cell", "integer", (c) => c.notNull())
+		.addColumn("category_id", "integer", (c) => c.notNull())
+		.addColumn("neg_rank", "real", (c) => c.notNull())
+		.addColumn("rowid_key", "integer", (c) => c.notNull())
+		.addColumn("name", "text")
+		.addColumn("name_key", "text")
+		.addColumn("brand_wikidata", "text")
+		.addColumn("latitude", "real", (c) => c.notNull())
+		.addColumn("longitude", "real", (c) => c.notNull())
+		.addColumn("country", "text", (c) => c.notNull())
+		.addColumn("confidence", "real", (c) => c.notNull())
+		.addColumn("gers_id", "text")
+		.addPrimaryKeyConstraint("poi_pk", ["h3_cell", "category_id", "neg_rank", "rowid_key"])
+		// `WITHOUT ROWID` has no first-class builder; the raw modifier is the idiomatic fallback.
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/** Secondary index for the FTS-hydration path. Builders call this AFTER the bulk materialize (index-after-load). */
+export async function createPOINameKeyIndex(db: Kysely<POIDatabase>): Promise<void> {
+	await db.schema.createIndex("poi_name_key").on("poi").column("name_key").execute()
+}
+
+export const POI_FTS_TABLE = "poi_search"
+
+/** FTS5 stays raw SQL by project rule (Kysely can't express virtual tables). Content-keyed by name_key. */
+export function createPOISearchFTS(db: DatabaseSync): void {
+	db.exec(
+		`CREATE VIRTUAL TABLE ${POI_FTS_TABLE} USING fts5(name, name_key UNINDEXED, h3_cell UNINDEXED, tokenize = 'unicode61')`
+	)
+}

package/postal-city-alias-lookup.ts

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   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
+ *   ("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
+ *   absent it the resolver is byte-identical.
+ *
+ *   The reader returns RAW divergent rows for a postcode; normalization + name-matching against the
+ *   candidate localities is the scorer's job (it owns the case/diacritic fold the soft name score
+ *   uses), keeping one normalizer in one place.
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+
+import type { PostalCityAliasDatabase } from "./postal-city-alias-schema.ts"
+
+export interface WOFPostalCityAliasLookupOpts {
+	/** Path to a `postal-city-alias-<cc>.db` built by `build-postal-city-alias.ts`. Opened read-only. */
+	databasePath?: string
+	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	database?: DatabaseSync
+}
+
+/** One divergent alias edge: the postal-system name and the geographic locality it maps to. */
+export interface PostalCityAlias {
+	/** The postal-system surface (what a user types). */
+	postalCity: string
+	/** The geographic locality name the postcode sits in (≈ the gazetteer's canonical name). */
+	geoLocality: string
+	/** Observed usage count — the evidence weight. */
+	n: number
+}
+
+/**
+ * Reader over `postal_city_alias`. The only query is a postcode-scoped probe for DIVERGENT rows (where the postal name
+ * differs from the geographic name — the rows that carry alias signal), issued via the typed Kysely query builder
+ * against {@link PostalCityAliasDatabase}.
+ */
+export class WOFPostalCityAliasLookup {
+	#db: DatabaseSync
+	#kdb: DatabaseClient<PostalCityAliasDatabase>
+	#ownsDB: boolean
+
+	constructor(opts: WOFPostalCityAliasLookupOpts) {
+		if (opts.database) {
+			this.#db = opts.database
+			this.#ownsDB = false
+		} else if (opts.databasePath) {
+			this.#db = new DatabaseSync(opts.databasePath, { readOnly: true })
+			this.#ownsDB = true
+		} else {
+			throw new Error("WOFPostalCityAliasLookup needs `databasePath` or `database`")
+		}
+		// `#kdb` wraps `#db` for the typed query; close() owns the raw handle directly (sync).
+		this.#kdb = new DatabaseClient<PostalCityAliasDatabase>({ database: this.#db })
+	}
+
+	/**
+	 * Divergent postal-city aliases for a postcode (empty when the postcode isn't in the table). The scorer groups these
+	 * by normalized `geoLocality` and appends the `postalCity` surfaces to the matching candidate locality's alias set.
+	 */
+	async getDivergentAliases(postcode: string): Promise<PostalCityAlias[]> {
+		const pc = postcode.trim()
+
+		if (!pc) return []
+		const rows = await this.#kdb
+			.selectFrom("postal_city_alias")
+			.select(["postal_city", "geo_locality", "n"])
+			.where("postcode", "=", pc)
+			.where("divergent", "=", 1)
+			.execute()
+
+		return rows.map((r) => ({ postalCity: String(r.postal_city), geoLocality: String(r.geo_locality), n: Number(r.n) }))
+	}
+
+	close(): void {
+		if (this.#ownsDB) {
+			this.#db.close()
+		}
+	}
+}

package/postal-city-alias-schema.ts

@@ -0,0 +1,75 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the POSTAL-CITY ALIAS table (`postal-city-alias-<cc>.db`, built by
+ *   `scripts/build-postal-city-alias.ts`) — the single source of truth for the columns shared by
+ *   the BUILDER and the READER ({@link WOFPostalCityAliasLookup}). Like {@link CandidateTable}, the
+ *   contract is a Kysely `Database` interface plus the table DDL as a string, so a column rename in
+ *   the builder is a compile error in the reader.
+ *
+ *   Provenance discipline (provenance-first): this is a SIBLING table to the PIP-derived
+ *   `postcode_locality` data, never mixed into it — one table, one provenance class. Each row is an
+ *   OBSERVED `(postcode, postal_city, geo_locality)` aggregate from Overture's `postal_city` field
+ *   with a usage count `n`; `divergent = 1` exactly when `postal_city != geo_locality` (the alias
+ *   signal — the only rows the resolver consumes).
+ */
+
+import type { Kysely } from "kysely"
+
+/**
+ * One observed postal-city aggregate. The natural key is `(postcode, postal_city, geo_locality)`; the builder enforces
+ * a `MIN_COUNT` floor on `n`, so every row is a non-trivial usage.
+ */
+export interface PostalCityAliasTable {
+	/** The postcode the aggregate is scoped to (the resolver probes by this). */
+	postcode: string
+	/** What the postal system calls the place (the surface a user is likely to type). */
+	postal_city: string
+	/** The geographic locality name the postcode actually sits in (≈ the gazetteer's canonical name). */
+	geo_locality: string
+	/** Observed row count — the evidence weight behind this alias. */
+	n: number
+	/** 1 when `postal_city != geo_locality` (the alias signal); 0 when they agree. */
+	divergent: number
+	/** Provenance: the dataset this aggregate came from (e.g. `overture:US`). */
+	source: string
+	/** The pinned data release the aggregate was computed from. */
+	release: string
+}
+
+/** The postal-city-alias database schema for `new DatabaseClient<PostalCityAliasDatabase>(...)`. */
+export interface PostalCityAliasDatabase {
+	postal_city_alias: PostalCityAliasTable
+}
+
+/** The `postal_city_alias` column order — the builder's INSERT derives its column list from this. */
+export const POSTAL_CITY_ALIAS_COLUMNS = [
+	"postcode",
+	"postal_city",
+	"geo_locality",
+	"n",
+	"divergent",
+	"source",
+	"release",
+] as const
+
+/**
+ * Create the `postal_city_alias` table + its two probe indexes. Kept here (not only in the builder) so tests can stand
+ * up a fixture DB with the exact production shape. Pass a {@link DatabaseClient} (or any `Kysely`) over the alias DB.
+ */
+export async function createPostalCityAliasTable(db: Kysely<PostalCityAliasDatabase>): Promise<void> {
+	await db.schema
+		.createTable("postal_city_alias")
+		.addColumn("postcode", "text", (c) => c.notNull())
+		.addColumn("postal_city", "text", (c) => c.notNull())
+		.addColumn("geo_locality", "text", (c) => c.notNull())
+		.addColumn("n", "integer", (c) => c.notNull())
+		.addColumn("divergent", "integer", (c) => c.notNull())
+		.addColumn("source", "text", (c) => c.notNull())
+		.addColumn("release", "text", (c) => c.notNull())
+		.execute()
+	await db.schema.createIndex("idx_pca_postcode").on("postal_city_alias").column("postcode").execute()
+	await db.schema.createIndex("idx_pca_pair").on("postal_city_alias").columns(["postal_city", "geo_locality"]).execute()
+}