@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/build/slim.ts

@@ -0,0 +1,338 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { temporaryDirectory } from "@mailwoman/core/fs/temporary"
+import { copyFileTo, removePath } from "@mailwoman/core/fs/writers"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { countRows } from "@mailwoman/sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { sealDatabase } from "@mailwoman/sqlite/sealed/db"
+import { sql } from "kysely"
+import type { Kysely } from "kysely"
+import type { PathBuilderLike } from "path-ts"
+
+import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE } from "#fts"
+import type { NamesTable, SprTable, WOFDatabase } from "#schema"
+
+export interface BuildSlimOptions {
+	/**
+	 * Input WOF SQLite distributions, each already carrying spr / names / place_population tables.
+	 */
+	inputs: readonly PathBuilderLike[]
+	/**
+	 * Output path for the slim DB, overwritten if it exists.
+	 */
+	output: PathBuilderLike
+	/**
+	 * Country codes to keep (ISO 2-letter); defaults to `["US"]`.
+	 */
+	countries?: string[]
+	/**
+	 * Cap on the number of localities to keep per country, by descending population.
+	 */
+	topLocalitiesPerCountry?: number
+	/**
+	 * Drop the `names` table after the FTS index is built; `place_search` is self-contained
+	 * and the resolver never reads `names` at runtime.
+	 */
+	dropNames?: boolean
+
+	onProgress?: (phase: SlimBuildPhase, detail: string) => void
+}
+
+export type SlimBuildPhase =
+	| "init"
+	| "schema"
+	| "country"
+	| "region"
+	| "county"
+	| "locality"
+	| "postcode"
+	| "names"
+	| "place_population"
+	| "coincident_roles"
+	| "place_abbr"
+	| "fts"
+	| "vacuum"
+	| "done"
+
+export interface BuildSlimResult {
+	outputPath: string
+	outputBytes: number
+	rowCounts: {
+		spr: number
+		names: number
+		placeSearch: number
+		placeBbox: number
+		placePopulation: number
+	}
+}
+
+/**
+ * Placetypes that we always keep so the ancestor chain a selected locality reports stays valid.
+ */
+const ANCESTOR_PLACETYPES = ["country", "region", "county", "borough", "macroregion"] as const
+
+/**
+ * Tables copied verbatim (schema + filtered rows) from each source DB.
+ * Anything else is dropped.
+ */
+const COPIED_TABLES = ["spr", "names", PLACE_POPULATION_TABLE] as const
+
+/**
+ * Fallback DDL for `place_population` when the first source predates the aux table (defensive).
+ */
+const PLACE_POPULATION_DDL = `CREATE TABLE ${PLACE_POPULATION_TABLE} (id INTEGER PRIMARY KEY, population INTEGER NOT NULL DEFAULT 0)`
+
+interface PlacePopulationTable {
+	id: number
+	population: number
+}
+
+/**
+ * Kysely schema for the build phase, including the ATTACHed `src.*` tables
+ * so row-copying queries can name the source schema.
+ */
+interface BuildSchema {
+	spr: SprTable
+	names: NamesTable
+	place_population: PlacePopulationTable
+	"src.spr": SprTable
+	"src.names": NamesTable
+	"src.place_population": PlacePopulationTable
+}
+
+export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<BuildSlimResult> {
+	const countries = (opts.countries ?? ["US"]).map((c) => c.toUpperCase())
+	const topLocalities = opts.topLocalitiesPerCountry ?? 1000
+	const progress = opts.onProgress ?? (() => {})
+
+	// An empty string marks an input that isn't built yet, so empties are skipped and every remaining path must exist.
+	const inputs = opts.inputs.map((input) => input.toString()).filter((p) => p.length)
+
+	if (!inputs.length) throw new Error("no input WOF dbs provided")
+
+	for (const input of inputs) {
+		if (!(await pathExists(input))) throw new Error(`input WOF db not found: ${input}`)
+	}
+
+	progress("init", `${inputs.length} input(s) → ${opts.output}`)
+
+	if (await pathExists(opts.output)) {
+		await removePath(opts.output)
+	}
+
+	// The output schema is replayed from the first input's sqlite_master so column ordering
+	// and affinity survive; `create table AS select` would flatten types to dynamic.
+	const out = new DatabaseClient<BuildSchema>(opts.output)
+	let result: BuildSlimResult
+
+	try {
+		using firstSource = new DatabaseClient<WOFDatabase>(inputs[0]!, { readOnly: true })
+
+		progress("schema", "copying spr / names / place_population schemas from first input")
+
+		for (const table of COPIED_TABLES) {
+			const createSQL = firstSource
+				.prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?`)
+				.get(table) as { sql?: string } | undefined
+
+			if (createSQL?.sql) {
+				// Raw DDL by design: the source DB's own create-table string cannot be expressed by a static Kysely builder.
+				out.exec(createSQL.sql)
+			} else if (table === PLACE_POPULATION_TABLE) {
+				// Older source builds may predate the aux table, so create it empty for the copy and ranking.
+				out.exec(PLACE_POPULATION_DDL)
+			} else {
+				throw new Error(`source DB ${inputs[0]} is missing required table '${table}'`)
+			}
+		}
+
+		// The copied schemas define the primary keys.
+		// This index on `names.id` helps the per-id insert select.
+		out.exec(`CREATE INDEX IF NOT EXISTS names_id_idx ON names(id);`)
+
+		// Pull rows from each input.
+		for (const inputPath of inputs) {
+			await copyFromSource(out, out, inputPath, countries, topLocalities, progress)
+		}
+
+		// `place_search` and `place_bbox` derive purely from `spr` + `names`, and the
+		// population aux table is not rebuilt because it was copied verbatim.
+		progress("fts", "building place_search / place_bbox on slim DB")
+
+		buildPlaceSearchFTS(out, {
+			drop: true, // schema we copied had no FTS tables, but be explicit
+			onProgress: (phase, name) => progress("fts", `${phase} ${name}`),
+		})
+
+		// `place_abbr` is materialized before `names` is dropped and always created,
+		// even empty, so the resolver can query it unconditionally.
+		progress("place_abbr", "materializing region abbreviations")
+		out.exec(`CREATE TABLE IF NOT EXISTS place_abbr (id INTEGER NOT NULL, abbr TEXT NOT NULL)`)
+		out.exec(`INSERT INTO place_abbr (id, abbr) SELECT id, name FROM names WHERE language = 'abbr'`)
+		out.exec(`CREATE INDEX IF NOT EXISTS place_abbr_by_abbr ON place_abbr (abbr COLLATE NOCASE)`)
+		out.exec(`CREATE INDEX IF NOT EXISTS place_abbr_by_id ON place_abbr (id)`)
+
+		const namesRows = countRows(out, "names")
+
+		// The resolver never reads `names` at query time, so dropping it and its index is pure size reduction.
+		if (opts.dropNames) {
+			progress("vacuum", `dropping names table (${namesRows} rows; FTS5 is self-contained)`)
+			out.exec(`DROP INDEX IF EXISTS names_id_idx;`)
+			out.exec(`DROP TABLE IF EXISTS names;`)
+		}
+
+		// Vacuum so the on-disk file reflects the trimmed rows rather than the in-flight insert churn.
+		progress("vacuum", "VACUUM (final size reduction)")
+		out.exec("VACUUM;")
+
+		const rowCounts = {
+			spr: countRows(out, "spr"),
+			names: namesRows,
+			placeSearch: countRows(out, PLACE_SEARCH_TABLE),
+			placeBbox: countRows(out, PLACE_BBOX_TABLE),
+			placePopulation: countRows(out, PLACE_POPULATION_TABLE),
+		}
+
+		progress("done", stringifyJSON(rowCounts))
+
+		result = {
+			outputPath: opts.output.toString(),
+			outputBytes: (await statPath(opts.output)).size,
+			rowCounts,
+		}
+	} finally {
+		await out.destroy()
+	}
+
+	// The sealed-artifact invariant: a built DB is a read-only asset from the moment it exists.
+	await sealDatabase(opts.output)
+
+	return result
+}
+
+async function copyFromSource(
+	out: DatabaseClient<BuildSchema>,
+	kysely: Kysely<BuildSchema>,
+	inputPath: string,
+	countries: string[],
+	topLocalities: number,
+	progress: NonNullable<BuildSlimOptions["onProgress"]>
+): Promise<void> {
+	// A fresh scratch copy is attached so read-only WOF distributions get the writable
+	// journal they need without mutating the canonical files.
+	await using tmpScratch = await temporaryDirectory("mailwoman-slim-src-")
+	const scratchPath = tmpScratch.path("src.db")
+
+	await copyFileTo(inputPath, scratchPath)
+
+	out.exec(`ATTACH DATABASE '${scratchPath.toString().replaceAll("'", "''")}' AS src;`)
+
+	try {
+		const srcHasPopulation = Boolean(
+			out.prepare(`SELECT 1 FROM src.sqlite_master WHERE type = 'table' AND name = '${PLACE_POPULATION_TABLE}'`).get()
+		)
+
+		// The `src.spr` declaration and its peers in `BuildSchema` let Kysely
+		// column-check the cross-schema select.
+		// SQLite reads the dotted identifier as a schema qualifier.
+
+		progress("country", `${inputPath}: ancestor placetypes in (${countries.join(",")})`)
+
+		await kysely
+			.insertInto("spr")
+			.expression((eb) =>
+				eb
+					.selectFrom("src.spr")
+					.selectAll()
+					.where("is_current", "!=", 0)
+					.where("is_deprecated", "=", 0)
+					.where("country", "in", countries)
+					.where("placetype", "in", [...ANCESTOR_PLACETYPES])
+			)
+			.onConflict((oc) => oc.doNothing())
+			.execute()
+
+		// Localities without a population row still qualify.
+		// Without the aux table, fall back to a deterministic id ordering.
+		progress("locality", `${inputPath}: top-${topLocalities} localities by population`)
+
+		await kysely
+			.insertInto("spr")
+			.expression((eb) =>
+				eb
+					.selectFrom("src.spr as s")
+					.$if(srcHasPopulation, (qb) => qb.leftJoin("src.place_population as p", "p.id", "s.id"))
+					.selectAll("s")
+					.where("s.is_current", "!=", 0)
+					.where("s.is_deprecated", "=", 0)
+					.where("s.country", "in", countries)
+					.where("s.placetype", "=", "locality")
+					.orderBy(srcHasPopulation ? sql<number>`COALESCE(p.population, 0)` : sql<number>`s.id`, "desc")
+					.limit(topLocalities)
+			)
+			.onConflict((oc) => oc.doNothing())
+			.execute()
+
+		progress("postcode", `${inputPath}: all postcodes`)
+
+		await kysely
+			.insertInto("spr")
+			.expression((eb) =>
+				eb
+					.selectFrom("src.spr")
+					.selectAll()
+					.where("is_current", "!=", 0)
+					.where("is_deprecated", "=", 0)
+					.where("country", "in", countries)
+					.where("placetype", "=", "postalcode")
+			)
+			.onConflict((oc) => oc.doNothing())
+			.execute()
+
+		progress("names", `${inputPath}: names rows for selected IDs`)
+
+		await kysely
+			.insertInto("names")
+			.expression((eb) => eb.selectFrom("src.names").selectAll().where("id", "in", eb.selectFrom("spr").select("id")))
+			.onConflict((oc) => oc.doNothing())
+			.execute()
+
+		if (srcHasPopulation) {
+			progress("place_population", `${inputPath}: population rows for selected IDs`)
+
+			await kysely
+				.insertInto("place_population")
+				.expression((eb) =>
+					eb.selectFrom("src.place_population").selectAll().where("id", "in", eb.selectFrom("spr").select("id"))
+				)
+				.onConflict((oc) => oc.doNothing())
+				.execute()
+		}
+
+		// `ancestors` is intentionally not copied, so the derived `coincident_roles`
+		// table is copied and filtered to surviving spr ids.
+		const relationSchema = out
+			.prepare(`SELECT sql FROM src.sqlite_master WHERE type = 'table' AND name = 'coincident_roles'`)
+			.get() as { sql?: string } | undefined
+
+		if (relationSchema?.sql) {
+			progress("coincident_roles", `${inputPath}: copying dual-role relation`)
+			out.exec(relationSchema.sql.replace(/CREATE TABLE/i, "CREATE TABLE IF NOT EXISTS"))
+
+			out.exec(
+				`INSERT OR IGNORE INTO coincident_roles SELECT * FROM src.coincident_roles
+					WHERE admin_id IN (SELECT id FROM spr) AND locality_id IN (SELECT id FROM spr)`
+			)
+
+			out.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON coincident_roles (admin_id)`)
+		}
+	} finally {
+		out.exec(`DETACH DATABASE src;`)
+	}
+}

package/lib/candidate/alias-bags.ts

@@ -2,55 +2,115 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 2 of the candidate build — explode `place_search.alt_names` into distinct alias rows.
+ * @file Pass 2 of the candidate build: explode `place_search.alt_names` into distinct alias rows.
  */
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import type { CandidateDatabase } from "#candidate-schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
-import { ALIAS_SEPARATOR } from "#fts/index"
+import type { CandidateDatabase } from "#candidate/schema"
+import { ALIAS_SEPARATOR } from "#fts"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Pass 2 — explode each place's `place_search.alt_names` bag into distinct-key alias rows (`is_primary = 0`), and count
- * each place's distinct staged keys (primary included) — the gloss detector's key-count signal (#1730).
+ * The official name of every current region, keyed `${country id}\0${name key}` →
+ * region id, from the source `names` table's `official` bit.
+ *
+ * Empty when the source has no `names` table (a fixture, or an extract shape).
+ *
+ * The positive evidence behind the alias refusal below: a name is refused from a region's
+ * bag only when another region of the same country holds it as its official name.
+ */
+function officialNameHoldersByRegion(
+	src: DatabaseClient<WOFDatabase>,
+	ccID: (code: string | null) => number
+): Map<string, number> {
+	const keys = new Map<string, number>()
+
+	if (!tableExists(src, "names")) return keys
+
+	for (const r of src
+		.prepare(
+			`SELECT n.id AS id, n.name AS name, s.country AS country
+			 FROM names n JOIN spr s ON s.id = n.id
+			 WHERE s.placetype = 'region' AND s.is_current != 0 AND s.is_deprecated = 0 AND n.official = 1`
+		)
+		.iterate()) {
+		const k = normalizeLocalityForKey(String(r.name ?? ""))
+
+		if (k) {
+			keys.set(`${ccID(r.country as string | null)}\0${k}`, Number(r.id))
+		}
+	}
+
+	return keys
+}
+
+/**
+ * Pass 2: explode each place's `place_search.alt_names` bag into distinct-key alias rows
+ * (`is_primary = 0`), and count each place's distinct staged keys with the primary included.
+ *
+ * With `regionPlacetypeID` and `ccID` given, a region's alias that is another same-country region's
+ * official name is refused and counted rather than staged (see {@link officialNameHoldersByRegion}).
+ * Without them the pass stages every alias.
  */
 export function explodeAliasBags(
 	src: DatabaseClient<WOFDatabase>,
 	out: DatabaseClient<CandidateDatabase>,
 	attrs: Map<number, PlaceAttrs>,
-	stageRow: StageRow
-): { nAlias: number; keyCounts: Map<number, number> } {
+	stageRow: StageRow,
+	opts: { regionPlacetypeID?: number; ccID?: (code: string | null) => number } = {}
+): { nAlias: number; keyCounts: Map<number, number>; regionOfficialRefused: number } {
 	let nAlias = 0
+	let regionOfficialRefused = 0
 	const keyCounts = new Map<number, number>()
+
+	const official =
+		typeof opts.regionPlacetypeID === "number" && opts.ccID
+			? officialNameHoldersByRegion(src, opts.ccID)
+			: new Map<string, number>()
+
 	out.exec("BEGIN")
 
 	for (const r of src.prepare("SELECT wof_id, alt_names FROM place_search").iterate()) {
-		const a = attrs.get(Number(r.wof_id))
+		const id = Number(r.wof_id)
+		const a = attrs.get(id)
 		const alt = r.alt_names as string | null
 
 		if (!a || !alt) continue
 		const seen = new Set<string>([a.pkey])
+		const isRegion = a.ptid === opts.regionPlacetypeID
 
-		// The writer space-pads each separator and appends a trailing one, so every piece arrives with
-		// surrounding whitespace and the last one is empty. `normalizeLocalityForKey` folds both away,
-		// and the empty tail falls out at the `!k` guard below.
+		// The writer space-pads each separator and appends a trailing one, so every piece
+		// includes surrounding whitespace and the last one is empty.
+		// `normalizeLocalityForKey` folds both away.
 		for (const piece of alt.split(ALIAS_SEPARATOR)) {
 			const k = normalizeLocalityForKey(piece)
 
 			if (!k || seen.has(k)) continue
 			seen.add(k)
-			stageRow(k, a, Number(r.wof_id), 0)
+
+			if (isRegion) {
+				const holder = official.get(`${a.cid}\0${k}`)
+
+				if (typeof holder === "number" && holder !== id) {
+					regionOfficialRefused++
+
+					continue
+				}
+			}
+
+			stageRow(k, a, id, 0)
 
 			nAlias++
 		}
 
-		keyCounts.set(Number(r.wof_id), seen.size)
+		keyCounts.set(id, seen.size)
 	}
 
 	out.exec("COMMIT")
 
-	return { nAlias, keyCounts }
+	return { nAlias, keyCounts, regionOfficialRefused }
 }

package/lib/candidate/ancestors/schema.ts

@@ -0,0 +1,211 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the candidate gazetteer's ancestors sidecar (`candidate_ancestor` +
+ *   `candidate_interval`) — the containment lineage the candidate table itself cannot answer, built
+ *   into the same `candidate.db` by `build-candidate.ts` and read by
+ *   {@link WOFCandidateTableLookup.ancestors}.
+ *
+ *   The sidecar stores denormalized closure rows. Each row represents one (place, ancestor) edge. The row includes the
+ *   parent's placetype, display name and folded key. The two consumers determine this layout:
+ *
+ *   1. The admin-coherence check needs the winner's chain as (placetype, name) pairs in one probe.
+ *      A fixed-slot `[id.8]` chain returns ids. Each id would then need a name lookup, but the artifact has no
+ *      per-id table. That design requires up to 8 indirections. The closure row requires none.
+ *   2. The account layer needs every candidate under a `name_key` enumerable with its chain from
+ *      one artifact probe ("present-but-outranked, discriminated by containment"). That is the
+ *      candidate probe (contiguous) followed by one `spr_id`-clustered closure probe per candidate
+ *      — each a handful of adjacent pages.
+ *
+ *   The artifact is read over HTTP byte ranges. A join to a dimension table scatters page fetches. A `without rowid`
+ *   B-tree clustered on `(spr_id, depth)` keeps a whole chain in 1–2 pages. The builder repeats parent strings to
+ *   avoid joins during reads.
+ *
+ *   `depth` is 1 for the nearest ancestor (deepest containment tier) and increases outward to the
+ *   country. This matches the nearest-first order that `ancestry.ts` serves for the FTS backend. Both backends'
+ *   `ancestors()` results therefore use the same order. The order within a place is deterministic:
+ *   containment depth descending (`placetypeDepth`), then ancestor id ascending, capped at
+ *   {@link MAX_ANCESTOR_DEPTH}. `parent_name_key` is the shared {@link normalizeLocalityForKey}
+ *   fold — the same fold `candidate.name_key` is built with, so a chain entry and a candidate key
+ *   compare under one normalizer.
+ *
+ *   `candidate_interval` stores pre/post-order labels over the canonical-parent forest. The builder assigns them
+ *   during construction. The predicate `a.pre <= d.pre and d.post <= a.post` tests whether `a` contains `d` in O(1)
+ *   time. It needs no chain scan or tier information. Descendants of `a` occupy the contiguous range
+ *   `pre between a.pre and a.post`. Interval labels add relabeling work to updates. This database is sealed and
+ *   read-only, so the builder can regenerate all labels together.
+ *
+ *   WOF places can have multiple parents because boundaries can be ambiguous or participate in multiple
+ *   hierarchies. `candidate_ancestor` stores every parent. Its closure rows hold the complete containment record.
+ *   One interval pair encodes only a tree. The interval forest therefore links each place to one canonical parent:
+ *   the depth-1 edge with the finest containment tier and lowest ancestor id. This follows the same MIN-based
+ *   stability convention as the candidate table's `region_id` stamp. A containment query about another hierarchy
+ *   must consult the closure rows. The interval result answers only whether a place is contained along the canonical
+ *   hierarchy.
+ *
+ *   absence semantics (meaning-of-zero): a place with no `candidate_interval` row has no recorded
+ *   ancestry in the source (extract-fed postcodes and localities, isolated places, cycle-skipped
+ *   rows). Absence is unverifiable, never a containment verdict.
+ */
+
+import { sql, type Kysely } from "kysely"
+
+// Type-only and circular on purpose (candidate-schema extends CandidateAncestorsDatabase): Kysely's DB
+// parameter is invariant, so the DDL functions must take the full database type their caller holds.
+// Erased at runtime.
+import type { CandidateDatabase } from "#candidate/schema"
+import type { NameKey } from "#street/normalize"
+
+/**
+ * The deepest chain the sidecar stores per place.
+ *
+ * WOF containment within the resolvable placetypes (country … microhood) never legitimately exceeds this.
+ * The build drops and counts anything past it as source noise rather than storing it.
+ */
+export const MAX_ANCESTOR_DEPTH = 8
+
+/**
+ * The closure-row table's name — probed with `hasTable` by the reader, so an artifact
+ * predating the sidecar degrades to "no ancestors capability" rather than `no such table`.
+ */
+export const CANDIDATE_ANCESTOR_TABLE = "candidate_ancestor"
+
+/**
+ * The interval-label table's name — the closure table's seal-time sibling.
+ * Existence-restricted the same way.
+ */
+export const CANDIDATE_INTERVAL_TABLE = "candidate_interval"
+
+/**
+ * One (place, ancestor) edge, denormalized so a chain read is a single clustered probe (no join).
+ */
+export interface CandidateAncestorTable {
+	/**
+	 * WOF id of the place whose chain this row belongs to — the same `spr_id` the candidate table resolves to.
+	 */
+	spr_id: number
+	/**
+	 * 1 = nearest ancestor, increasing outward to the country. Deterministic within a place (containment depth
+	 * descending, then ancestor id ascending), so `(spr_id, depth)` is a stable primary key across rebuilds.
+	 */
+	depth: number
+	/**
+	 * WOF id of the ancestor.
+	 */
+	parent_spr_id: number
+	/**
+	 * Small int from the shared `placetype_codes` dictionary (the same one the candidate table uses).
+	 */
+	parent_placetype_id: number
+	/**
+	 * The ancestor's canonical display name.
+	 *
+	 * What {@link Ancestor.name} serves, matching the FTS backend's register.
+	 */
+	parent_name: string
+	/**
+	 * The shared {@link normalizeLocalityForKey} fold of `parent_name` — comparable against
+	 * `candidate.name_key` and against a query-side fold under one normalizer, by construction.
+	 */
+	parent_name_key: NameKey
+}
+
+/**
+ * Pre/post-order labels over the canonical-parent forest — one row per place with
+ * recorded ancestry (see the module docstring for absence semantics).
+ *
+ * `pre < post` always.
+ * Labels are unique across the artifact.
+ */
+export interface CandidateIntervalTable {
+	spr_id: number
+	pre: number
+	post: number
+}
+
+/**
+ * The sidecar tables, for a `Kysely` view over the candidate DB.
+ *
+ * `CandidateDatabase` (candidate-schema.ts) extends this, so the builder's
+ * one typed client sees both families.
+ */
+export interface CandidateAncestorsDatabase {
+	candidate_ancestor: CandidateAncestorTable
+	candidate_interval: CandidateIntervalTable
+}
+
+/**
+ * The `candidate_ancestor` columns in clustered-key order.
+ *
+ * The first two columns form the primary key.
+ * The builder's positional `insert` binds values in this order.
+ *
+ * Keep in sync with {@link CandidateAncestorTable}.
+ */
+export const CANDIDATE_ANCESTOR_COLUMNS = [
+	"spr_id",
+	"depth",
+	"parent_spr_id",
+	"parent_placetype_id",
+	"parent_name",
+	"parent_name_key",
+] as const
+
+/**
+ * Create the clustered closure table.
+ *
+ * The builder inserts in `(spr_id, depth)` order so the B-tree leaves are contiguous
+ * per place — the byte-range read discipline.
+ */
+export async function createCandidateAncestorTable(db: Kysely<CandidateDatabase>): Promise<void> {
+	await db.schema
+		.createTable(CANDIDATE_ANCESTOR_TABLE)
+		.addColumn("spr_id", "integer", (c) => c.notNull())
+		.addColumn("depth", "integer", (c) => c.notNull())
+		.addColumn("parent_spr_id", "integer", (c) => c.notNull())
+		.addColumn("parent_placetype_id", "integer", (c) => c.notNull())
+		.addColumn("parent_name", "text", (c) => c.notNull())
+		.addColumn("parent_name_key", "text", (c) => c.notNull())
+		.addPrimaryKeyConstraint("candidate_ancestor_pk", ["spr_id", "depth"])
+		// `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * Create the interval-label table.
+ *
+ * Small rows probed by primary key — the `without rowid` win case.
+ */
+export async function createCandidateIntervalTable(db: Kysely<CandidateDatabase>): Promise<void> {
+	await db.schema
+		.createTable(CANDIDATE_INTERVAL_TABLE)
+		.addColumn("spr_id", "integer", (c) => c.primaryKey())
+		.addColumn("pre", "integer", (c) => c.notNull())
+		.addColumn("post", "integer", (c) => c.notNull())
+		.modifyEnd(sql`without rowid`)
+		.execute()
+}
+
+/**
+ * One place's interval label.
+ * The shape both sides of a containment comparison read.
+ */
+export interface IntervalLabel {
+	pre: number
+	post: number
+}
+
+/**
+ * Does `outer` contain `inner` along the canonical hierarchy?
+ *
+ * Reflexive: a place contains itself (containment degenerates to identity,
+ * the same reading the admin-coherence check gives a self-match).
+ * The shared function for every consumer of the labels — a re-derived comparison risks
+ * disagreeing at exactly the strict/inclusive boundary this line settles.
+ */
+export function intervalContains(outer: IntervalLabel, inner: IntervalLabel): boolean {
+	return outer.pre <= inner.pre && inner.post <= outer.post
+}