@mailwoman/resolver-wof-sqlite 7.2.0 → 7.3.0

package/candidate-lookup.ts

@@ -0,0 +1,382 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node-side {@link PlaceLookup} over the byte-range CANDIDATE table (`build-candidate.ts`) — the
+ *   SAME gazetteer the browser demo resolves against ({@link WOFCandidateTableLookup} in
+ *   `docs/src/shared/httpvfs-resolver.ts`), but reading a LOCAL `candidate.db` via `node:sqlite`
+ *   instead of sql.js-httpvfs. This is what makes the server/CLI resolver match the demo: one
+ *   lookup surface, one artifact, one ranking.
+ *
+ *   The query is a single contiguous probe on the `WITHOUT ROWID` B-tree keyed `(name_key,
+ *   country_id, region_id, placetype_id, neg_rank, spr_id)`. `name_key` is the SHARED
+ *   {@link normalizeLocalityForKey} (build- and query-consistent), each row is denormalized (display
+ *   `name`, centroid, bbox), and population rank is precomputed into `neg_rank` — so the result is
+ *   POPULATION-FIRST and COUNTRY-AGNOSTIC (when no `country` filter is given), exactly like the
+ *   demo. That's the deliberate divergence from {@link WOFSqlitePlaceLookup}'s FTS/bm25 ranking: a
+ *   bare "Moscow" resolves to the 10.4 M-pop Russian city, not whichever same-name US township bm25
+ *   floats to the top.
+ *
+ *   Disambiguation rides the same mechanism the cascade already uses: a parsed region resolves to its
+ *   stored bbox and the locality query is point-in-bbox-filtered on the candidate centroid (the
+ *   `bbox` field on {@link FindPlaceQuery}).
+ */
+
+import { DatabaseSync } from "node:sqlite"
+
+import { expandPlacetypeFilter } from "@mailwoman/resolver"
+
+import { CANDIDATE_FTS_TABLE } from "./candidate-fts.ts"
+import type { CandidateTable, CountryCodeTable, PlacetypeCodeTable } from "./candidate-schema.ts"
+import { haversineKm } from "./geo.ts"
+import { trigramJaccard } from "./lookup.ts"
+import { POSTAL_CITY_CANDIDATE_TABLE, type PostalCityCandidateTable } from "./postal-city-candidate-schema.ts"
+import { hasTable } from "./sqlite-utils.ts"
+import { normalizeLocalityForKey, stripLocalityQualifier } from "./street-normalize.ts"
+import type { FindPlaceQuery, PlaceCandidate, PlaceLookup, WOFPlacetype } from "./types.ts"
+
+export interface WOFCandidateTableLookupOpts {
+	/** Path to a `candidate.db` built by `build-candidate.ts`. Opened read-only. */
+	databasePath?: string
+	/** Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`. */
+	database?: DatabaseSync
+}
+
+/**
+ * The candidate columns this lookup probes — a typed projection of the SHARED {@link CandidateTable}, so a column rename
+ * in `build-candidate` (the writer) is a compile error here (the reader).
+ */
+type CandidateRow = Pick<
+	CandidateTable,
+	| "spr_id"
+	| "name"
+	| "country_id"
+	| "placetype_id"
+	| "latitude"
+	| "longitude"
+	| "min_lat"
+	| "min_lon"
+	| "max_lat"
+	| "max_lon"
+	| "neg_rank"
+>
+
+/**
+ * FTS5-trigram over-fetch before the trigram-Jaccard re-rank, and the minimum similarity to count as a fuzzy hit (below
+ * it the trigram overlap is noise, e.g. unrelated same-trigram names). Tunable.
+ */
+const FUZZY_FETCH = 40
+const FUZZY_MIN = 0.34
+
+/**
+ * Unpadded character-trigrams of `s`, OR'd into an FTS5 trigram MATCH query (each quoted so FTS treats it as a literal
+ * term). Returns "" when `s` is shorter than a trigram or yields no clean grams — the caller then skips the fuzzy
+ * probe.
+ */
+function ftsTrigramQuery(s: string): string {
+	const grams = new Set<string>()
+
+	for (let i = 0; i + 3 <= s.length; i++) {
+		const g = s.slice(i, i + 3)
+
+		if (/^[\p{L}\p{N} ]{3}$/u.test(g)) {
+			grams.add(g)
+		}
+	}
+
+	return [...grams].map((g) => `"${g}"`).join(" OR ")
+}
+
+/**
+ * Node {@link PlaceLookup} over `candidate.db`. Drop-in for {@link WOFSqlitePlaceLookup} in `createWOFResolver(backend)`
+ * — same `findPlace` contract, population-first ranking.
+ */
+export class WOFCandidateTableLookup implements PlaceLookup {
+	#db: DatabaseSync
+	#ownsDB: boolean
+	readonly #countryToID = new Map<string, number>()
+	readonly #idToCountry = new Map<number, string>()
+	readonly #placetypeToID = new Map<string, number>()
+	readonly #idToPlacetype = new Map<number, string>()
+	/**
+	 * Prepared `(name_key, postcode)` probe for the #741 postal-city side-index — `undefined` when the
+	 * `postal_city_candidate` table isn't present, so a candidate.db built without it is byte-stable.
+	 */
+	readonly #postalCityProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	/**
+	 * Prepared FTS5-trigram MATCH probe for the typo-tolerant fallback — `undefined` when the `candidate_fts` index isn't
+	 * present, so a candidate.db built without it is byte-stable (the fuzzy path is skipped, exactly like today).
+	 */
+	readonly #ftsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+	/**
+	 * Prepared UNFILTERED existence probe (`name_key` present anywhere, ignoring country/placetype/bbox). Gates the fuzzy
+	 * fallback: fuzzy is a TYPO corrector, so it engages only when the name doesn't exist in the gazetteer at all. A name
+	 * that DOES exist but missed under the active filter is a filter miss (e.g. a placer misroute "Vienna, Austria"→IT),
+	 * not a spelling miss — fuzzing it would scrape an unrelated same-country place and defeat the cascade's
+	 * country-agnostic retry. Prepared only alongside `#ftsProbe`.
+	 */
+	readonly #nameKeyExistsProbe: ReturnType<DatabaseSync["prepare"]> | undefined
+
+	constructor(opts: WOFCandidateTableLookupOpts) {
+		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("WOFCandidateTableLookup needs `databasePath` or `database`")
+		}
+
+		// The code tables are tiny (country/placetype dictionaries) — load them once at construction so
+		// `findPlace` is a single B-tree probe with no dictionary round-trip.
+		for (const r of this.#db.prepare("SELECT id, code FROM country_codes").all() as unknown as CountryCodeTable[]) {
+			const code = String(r.code).toUpperCase()
+			this.#countryToID.set(code, Number(r.id))
+			this.#idToCountry.set(Number(r.id), code)
+		}
+
+		for (const r of this.#db
+			.prepare("SELECT id, placetype FROM placetype_codes")
+			.all() as unknown as PlacetypeCodeTable[]) {
+			this.#placetypeToID.set(String(r.placetype), Number(r.id))
+			this.#idToPlacetype.set(Number(r.id), String(r.placetype))
+		}
+
+		// #741 postal-city side-index: prepare the exact probe only if the table is present. Absent →
+		// `#postalCityProbe` stays undefined → findPlace skips the postal-city path → byte-stable.
+		if (hasTable(this.#db, POSTAL_CITY_CANDIDATE_TABLE)) {
+			this.#postalCityProbe = this.#db.prepare(
+				`SELECT spr_id, name, latitude, longitude FROM ${POSTAL_CITY_CANDIDATE_TABLE} WHERE name_key = ? AND postcode = ? LIMIT 1`
+			)
+		}
+
+		// FTS5-trigram fuzzy fallback: prepare the MATCH probe only if the index is present (the unified
+		// gazetteer carries it; an older candidate.db doesn't → the fuzzy path is skipped, byte-stable).
+		if (hasTable(this.#db, CANDIDATE_FTS_TABLE)) {
+			this.#ftsProbe = this.#db.prepare(
+				`SELECT name_key FROM ${CANDIDATE_FTS_TABLE} WHERE ${CANDIDATE_FTS_TABLE} MATCH ? ORDER BY bm25(${CANDIDATE_FTS_TABLE}) LIMIT ?`
+			)
+			this.#nameKeyExistsProbe = this.#db.prepare("SELECT 1 FROM candidate WHERE name_key = ? LIMIT 1")
+		}
+	}
+
+	/** Does this query want a locality-tier place? Postal-city aliases (#741) are all localities. */
+	#wantsLocality(placetype: FindPlaceQuery["placetype"]): boolean {
+		if (!placetype) return true
+		const want = Array.isArray(placetype) ? placetype : [placetype]
+
+		return expandPlacetypeFilter(want as readonly string[]).includes("locality")
+	}
+
+	async findPlace(query: FindPlaceQuery): Promise<PlaceCandidate[]> {
+		let text = (query.text ?? "").trim()
+
+		if (!text) return []
+
+		// #920 name law, candidate-key edition: postcode rows are keyed by their whitespace-stripped
+		// form at build (the GeoNames fold normalizes '624 66' → '62466'), so a postcode-typed query
+		// strips internal whitespace before keying. Postcode-only — locality names keep their spaces.
+		if ([query.placetype].flat().includes("postalcode")) {
+			text = text.replace(/\s+/g, "")
+		}
+		const nameKey = normalizeLocalityForKey(text)
+
+		if (!nameKey) return []
+
+		// #741: postcode-keyed postal-city alias. An exact `(name_key, postcode)` hit resolves a
+		// user-typed POSTAL city ("Antioch", 37013) to the geographic locality the postcode sits in
+		// ("Nashville"), bypassing the population/region ranking that can't see the postcode. Gated on
+		// the side-index being present, a postcode in the query, and a locality-tier request — so the
+		// common (no-postcode / non-locality) path is untouched. A hit short-circuits: the postcode is
+		// an exact, high-confidence disambiguator, so we return the single geographic locality.
+		if (query.postcode && this.#postalCityProbe && this.#wantsLocality(query.placetype)) {
+			const hit = this.#postalCityProbe.get(nameKey, query.postcode.trim()) as
+				| Pick<PostalCityCandidateTable, "spr_id" | "name" | "latitude" | "longitude">
+				| undefined
+
+			if (hit) {
+				return [
+					{
+						id: Number(hit.spr_id),
+						name: String(hit.name ?? ""),
+						placetype: "locality" as WOFPlacetype,
+						country: query.country?.toUpperCase() ?? "",
+						lat: Number(hit.latitude),
+						lon: Number(hit.longitude),
+						score: 1,
+						exactMatch: true,
+					},
+				]
+			}
+		}
+
+		const limit = Math.max(1, query.limit ?? 10)
+
+		// Filter conds shared by the exact-key + strip-fallback probes (everything but name_key).
+		const filters: string[] = []
+		const filterParams: Array<string | number> = []
+
+		if (query.country) {
+			const cid = this.#countryToID.get(query.country.toUpperCase())
+
+			if (cid === undefined) return [] // a country the candidate table doesn't carry
+			filters.push("country_id = ?")
+			filterParams.push(cid)
+		}
+
+		if (query.placetype) {
+			// Shared placetype-equivalence expansion (a `locality` query must also reach borough /
+			// localadmin). `postalcode` maps to no admin placetype here → empty → no rows.
+			const want = Array.isArray(query.placetype) ? query.placetype : [query.placetype]
+			const ids = expandPlacetypeFilter(want as readonly string[])
+				.map((t) => this.#placetypeToID.get(t))
+				.filter((v): v is number => v !== undefined)
+
+			if (ids.length === 0) return []
+			filters.push(`placetype_id IN (${ids.map(() => "?").join(",")})`)
+			filterParams.push(...ids)
+		}
+
+		if (query.bbox) {
+			const b = query.bbox
+			filters.push("latitude BETWEEN ? AND ? AND longitude BETWEEN ? AND ?")
+			filterParams.push(b.minLat, b.maxLat, b.minLon, b.maxLon)
+		}
+
+		const probe = (nk: string): CandidateRow[] => {
+			const conds = ["name_key = ?", ...filters]
+			const sql =
+				"SELECT spr_id, name, country_id, placetype_id, latitude, longitude, min_lat, min_lon, max_lat, max_lon, neg_rank " +
+				`FROM candidate WHERE ${conds.join(" AND ")} ORDER BY neg_rank ASC LIMIT ?`
+
+			return this.#db.prepare(sql).all(nk, ...filterParams, limit) as unknown as CandidateRow[]
+		}
+
+		let rows = probe(nameKey)
+
+		if (rows.length === 0) {
+			// Query-side qualifier-strip fallback: an OA locality with a qualifier the gazetteer's
+			// canonical name omits ("Lenk im Simmental" → "Lenk", "Roche VD"). Tried ONLY on an exact
+			// miss; the cascade's region bbox disambiguates any base-name ambiguity.
+			const strippedKey = normalizeLocalityForKey(stripLocalityQualifier(text))
+
+			if (strippedKey && strippedKey !== nameKey) {
+				rows = probe(strippedKey)
+			}
+		}
+
+		// Typo-tolerant fallback (the unified gazetteer's fuzzy mode): an exact + strip miss may be a
+		// misspelling the normalized key can't reach. FTS5-trigram fetches a loose set; we re-rank by
+		// trigram-Jaccard (the admin backend's measure) and probe the best name_keys, so a typo resolves
+		// the same on either backend. The country/placetype/bbox filters still apply via `probe`. Skipped
+		// when the index is absent (byte-stable for an older candidate.db).
+		//
+		// Gate: only when the name doesn't exist in the gazetteer AT ALL (unfiltered). A name that exists
+		// but missed under the active country/placetype/bbox filter is a FILTER miss, not a spelling miss
+		// — fuzzing it scrapes an unrelated same-filter place ("Vienna, Austria" misrouted to IT would
+		// pull a tiny Italian name_key near Siena) and masks the cascade's country-agnostic retry that
+		// correctly lands population-first Vienna AT. The exact/strip probes already covered the real name.
+		if (rows.length === 0 && this.#ftsProbe && this.#nameKeyExistsProbe && !this.#nameKeyExistsProbe.get(nameKey)) {
+			const match = ftsTrigramQuery(nameKey)
+
+			if (match) {
+				const hits = this.#ftsProbe.all(match, FUZZY_FETCH) as unknown as Array<{ name_key: string }>
+				const ranked = hits
+					.map((h) => ({ nk: String(h.name_key), s: trigramJaccard(nameKey, String(h.name_key)) }))
+					.filter((h) => h.s >= FUZZY_MIN)
+					.sort((a, b) => b.s - a.s)
+				const seen = new Set<string>()
+
+				for (const h of ranked) {
+					if (seen.has(h.nk)) continue
+					seen.add(h.nk)
+					rows.push(...probe(h.nk))
+
+					if (rows.length >= limit) break
+				}
+				rows = rows.slice(0, limit)
+			}
+		}
+
+		const candidates = rows.map((row): PlaceCandidate => {
+			const hasBbox = row.min_lat != null && row.max_lat != null && row.min_lon != null && row.max_lon != null
+
+			return {
+				id: Number(row.spr_id),
+				name: String(row.name ?? ""),
+				placetype: (this.#idToPlacetype.get(Number(row.placetype_id)) ?? "") as WOFPlacetype,
+				// Surfaced so the cascade can country-gate a postcode by the resolved locality (an ambiguous
+				// international postcode like 10115 = Berlin DE AND New York US must not out-resolve the city).
+				country: this.#idToCountry.get(Number(row.country_id)) ?? "",
+				lat: Number(row.latitude),
+				lon: Number(row.longitude),
+				score: -Number(row.neg_rank),
+				// Every candidate row IS an exact normalized-name (or alias/abbrev) match — the cascade's
+				// exact tier accepts alias-exact hits ("New York City" → New York) the same as canonical.
+				exactMatch: true,
+				...(hasBbox
+					? {
+							bbox: {
+								minLat: Number(row.min_lat),
+								maxLat: Number(row.max_lat),
+								minLon: Number(row.min_lon),
+								maxLon: Number(row.max_lon),
+							},
+						}
+					: {}),
+			}
+		})
+
+		// Proximity re-rank (#938): with bias hints (the demo's map viewport / user location), re-sort the
+		// exact-match candidates by the SAME prominence the FTS server uses (lookup.ts) — population and
+		// nearness in one additive scale — so an in-view namesake wins a tie without a hard filter. Byte-
+		// identical to the plain population order when no bias is passed. `score` here is -neg_rank =
+		// log10(population + 1), so popTerm is the server formula read straight off it. Constants MIRROR
+		// lookup.ts's DEFAULT_WEIGHTS (biasBoost 4, populationBoost 4, populationScaleLog10 6,
+		// proximityScaleKm 100) — the #861 server↔demo parity contract; keep them in lockstep.
+		if (query.bias && query.bias.length > 0) {
+			const BIAS_BOOST = 4.0
+			const POP_BOOST = 4.0
+			const POP_SCALE_LOG10 = 6
+			// SHARPER than lookup.ts's 100 km on purpose: this backend's `score` is log-population ALONE
+			// (no bm25 document term), so the population signal is weaker relative to the bias and the
+			// gentle 100 km decay let a 230 km-distant alias-exact township ("Paris Township", OH) edge
+			// out a global city ("Paris", FR) from a nearby view. A ~30 km scale keeps the boost to
+			// candidates the user is actually LOOKING at — an in-view namesake still wins (Dublin, OH from
+			// an Ohio view), a distant one no longer does (Paris stays FR from a Michigan view).
+			const PROX_SCALE_KM = 30
+			const prominence = (c: PlaceCandidate): number => {
+				const popTerm = POP_BOOST * Math.min(1, Math.max(0, c.score) / POP_SCALE_LOG10)
+				let proxTerm = 0
+
+				if (!(c.lat === 0 && c.lon === 0)) {
+					for (const b of query.bias!) {
+						const d = haversineKm(b.lat, b.lon, c.lat, c.lon)
+						const term = (BIAS_BOOST * (b.weight ?? 1)) / (1 + d / PROX_SCALE_KM)
+
+						if (term > proxTerm) {
+							proxTerm = term
+						}
+					}
+				}
+
+				return popTerm + proxTerm
+			}
+			// Stable within equal prominence (preserves the population order the B-tree already gave).
+			candidates
+				.map((c, i) => ({ c, i, p: prominence(c) }))
+				.sort((a, b) => b.p - a.p || a.i - b.i)
+				.forEach((x, j) => (candidates[j] = x.c))
+		}
+
+		return candidates
+	}
+
+	close(): void {
+		if (this.#ownsDB) {
+			this.#db.close()
+		}
+	}
+}

package/candidate-schema.ts

@@ -0,0 +1,166 @@
+/**
+ * @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 `httpvfs-resolver.ts`). 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"
+
+/**
+ * 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 shard row may lack a bbox).
+ */
+export interface CandidateTable {
+	/** The shared {@link normalizeLocalityForKey} of the name/alias — the probe key. */
+	name_key: string
+	/** 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
+}
+
+/** `(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>(...)`. */
+export interface CandidateDatabase {
+	/** 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 `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",
+] 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")
+		.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")
+		.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()
+}