@mailwoman/resolver-wof-sqlite 10.0.0 → 10.2.0

package/lib/build/slim.ts

@@ -2,62 +2,33 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Build a "slim" Who's On First SQLite distribution that's small enough to ship as a static asset
- *   for the browser-side mailwoman demo (Path B of the demo plan). The full admin distribution is
- *   ~2 GB; the slim variant aims for the ~50–100 MB range by keeping only the places a public demo
- *   will actually query for.
- *
- *   Selection policy (v1, US-focused):
- *
- *   - All countries / regions / counties / boroughs in the configured `countries` set, so the ancestor
- *       chain a locality / postcode reports through `parent_id` stays intact.
- *   - Top-K localities by population (read from the source's pre-built `place_population` aux table) in
- *       those countries.
- *   - All postcodes in those countries — they're small and addressing-relevant.
- *   - All `names` + `place_population` rows for selected place IDs.
- *   - The `coincident_roles` dual-role relation (#402), filtered to surviving spr ids.
- *
- *   No geojson, by design. The upstream WOF GeoJSON bodies live ONLY in the raw `whosonfirst-data-*`
- *   repos; `scripts/build-unified-wof.ts` extracts `wof:population` straight into
- *   `place_population` (and the bbox into `spr`) at ingest and never persists a `geojson` table. So
- *   the source admin DB carries population in `place_population`, and this builder consumes it
- *   directly — there is nothing to extract from, and nothing to drop.
- *
- *   The output DB has the resolver-facing schema: `spr`, `names`, `place_population`, plus the
- *   `place_search` FTS5 / `place_bbox` R*Tree virtual tables rebuilt against the trimmed row set
- *   (both derive purely from `spr` + `names` — see `fts.ts`). That means `WOFSQLitePlaceLookup`
- *   opens the slim DB without any code change — it sees a smaller universe, nothing more.
- *
- *   Multi-extract inputs (e.g. admin + postcode) are processed in sequence; selected rows accumulate
- *   into the single output DB. The postcode extract contributes only postcodes; admin contributes
- *   everything else. Empty / missing input paths are skipped (callers pass `""` when a extract, such
- *   as a custom postcode DB, isn't built yet).
  */
 
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 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 { 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/index"
+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 should already have spr / names / place_population tables.
+	 * Input WOF SQLite distributions, each already carrying spr / names / place_population tables.
 	 */
-	inputs: string[]
+	inputs: readonly PathBuilderLike[]
 	/**
-	 * Output path for the slim DB. Will be overwritten if it exists.
+	 * Output path for the slim DB, overwritten if it exists.
 	 */
-	output: string
+	output: PathBuilderLike
 	/**
-	 * Country codes to keep (ISO 2-letter). Defaults to `["US"]`.
+	 * Country codes to keep (ISO 2-letter); defaults to `["US"]`.
 	 */
 	countries?: string[]
 	/**
@@ -65,16 +36,11 @@ export interface BuildSlimOptions {
 	 */
 	topLocalitiesPerCountry?: number
 	/**
-	 * Drop the `names` table after the FTS index is built (default false). `place_search` is a self-contained FTS5 (no
-	 * external `content=`), so once it's built `names` is only the build-time source — the resolver queries
-	 * `place_search` + `spr` + `place_population` + `coincident_roles` and never reads `names` at runtime. Dropping it is
-	 * the single biggest size win (~2/3 of the file for a multi-locale build; see #359). A future consumer that needs raw
-	 * alt-names at runtime should ship a SEPARATE extract rather than re-bloat the hot DB.
+	 * 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
-	/**
-	 * Optional progress callback for CLI / test introspection.
-	 */
+
 	onProgress?: (phase: SlimBuildPhase, detail: string) => void
 }
 
@@ -112,7 +78,8 @@ export interface BuildSlimResult {
 const ANCESTOR_PLACETYPES = ["country", "region", "county", "borough", "macroregion"] as const
 
 /**
- * Tables copied verbatim (schema + filtered rows) from each source DB. Anything else is dropped.
+ * Tables copied verbatim (schema + filtered rows) from each source DB.
+ * Anything else is dropped.
  */
 const COPIED_TABLES = ["spr", "names", PLACE_POPULATION_TABLE] as const
 
@@ -121,19 +88,14 @@ const COPIED_TABLES = ["spr", "names", PLACE_POPULATION_TABLE] as const
  */
 const PLACE_POPULATION_DDL = `CREATE TABLE ${PLACE_POPULATION_TABLE} (id INTEGER PRIMARY KEY, population INTEGER NOT NULL DEFAULT 0)`
 
-/**
- * Minimal row shape for the population aux table — id + population, nothing else.
- */
 interface PlacePopulationTable {
 	id: number
 	population: number
 }
 
 /**
- * Kysely schema for the build phase. Mirrors the resolver-facing tables, plus the ATTACHed `src.*` tables so the
- * row-copying queries can name the source schema in `selectFrom` without falling back to raw SQL. ATTACH itself is
- * still raw — Kysely doesn't model it — but everything downstream (the SELECT-INSERT step that does the actual
- * filtering work) goes through the builder.
+ * Kysely schema for the build phase, including the ATTACHed `src.*` tables
+ * so row-copying queries can name the source schema.
  */
 interface BuildSchema {
 	spr: SprTable
@@ -149,9 +111,8 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 	const topLocalities = opts.topLocalitiesPerCountry ?? 1000
 	const progress = opts.onProgress ?? (() => {})
 
-	// Callers pass `""` for extracts that don't exist yet (e.g. a not-yet-built custom postcode DB).
-	// Skip empties up front; require every remaining path to exist.
-	const inputs = opts.inputs.filter((p) => p.length > 0)
+	// 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")
 
@@ -165,10 +126,8 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 		await removePath(opts.output)
 	}
 
-	// Open the output DB and create the empty schema. We discover the schema from the FIRST input
-	// (raw sqlite_master read — Kysely doesn't model that) so the output mirrors source column
-	// ordering / types. `CREATE TABLE AS SELECT` flattens types to dynamic, which would break
-	// callers that rely on column-affinity behavior.
+	// 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
 
@@ -183,20 +142,18 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 				.get(table) as { sql?: string } | undefined
 
 			if (createSQL?.sql) {
-				// Raw DDL by design (introspect-and-replay): we exec the SOURCE DB's own CREATE TABLE
-				// string read from sqlite_master, so a static Kysely builder can't express it. See AGENTS.md.
+				// 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 — create it empty so the per-source
-				// copy + ranking have somewhere to land. Sparse-by-design; missing rows are fine.
+				// 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}'`)
 			}
 		}
 
-		// PRIMARY KEY on spr.id + place_population.id come from the schemas we copied; an explicit
-		// index on names.id helps the per-id INSERT SELECT later.
+		// 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.
@@ -204,10 +161,8 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 			await copyFromSource(out, out, inputPath, countries, topLocalities, progress)
 		}
 
-		// Build the resolver virtual tables on the trimmed row set. Both place_search (FTS5) and
-		// place_bbox (R*Tree) derive purely from spr + names — no geojson needed (see fts.ts). The
-		// population aux table is NOT rebuilt here: it was copied verbatim above, and fts.ts only
-		// (re)builds it when a `geojson` table is present, which the slim DB intentionally has not.
+		// `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, {
@@ -215,34 +170,24 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 			onProgress: (phase, name) => progress("fts", `${phase} ${name}`),
 		})
 
-		// Materialize region/state ABBREVIATIONS into a standalone `place_abbr (id, abbr)` table BEFORE
-		// `names` is (optionally) dropped. The full DB lets the resolver tier an exact-abbrev match by
-		// querying `names` (`#exactMatchIDs`), but the slim DB drops `names` for size — so the
-		// browser resolver gets its own tiny lookup (~hundreds of rows) to do the same data-driven
-		// exact-abbrev tiering ("VT" → Vermont, not a token-matching foreign region) instead of the
-		// demo's hardcoded region-abbreviation map (since deleted). Sourced from the `language='abbr'` rows
-		// `add-region-abbrevs.ts` wrote, already filtered to surviving spr ids via the names copy. The
-		// table is always created (empty when the source predates the abbrev enrichment) so the
-		// resolver can query it unconditionally.
+		// `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)`)
 
-		// Capture the names count BEFORE any drop so the build report stays informative.
 		const namesRows = countRows(out, "names")
 
-		// Optionally drop `names` (+ its index) now that the self-contained FTS5 index no longer needs
-		// it. The resolver never reads `names` at query time, so this is pure size reduction.
+		// 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 the output so the on-disk file reflects just the trimmed row count. Without it the
-		// file size stays inflated from the in-flight INSERT churn.
+		// 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;")
 
@@ -254,10 +199,10 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 			placePopulation: countRows(out, PLACE_POPULATION_TABLE),
 		}
 
-		progress("done", JSON.stringify(rowCounts))
+		progress("done", stringifyJSON(rowCounts))
 
 		result = {
-			outputPath: opts.output,
+			outputPath: opts.output.toString(),
 			outputBytes: (await statPath(opts.output)).size,
 			rowCounts,
 		}
@@ -279,32 +224,24 @@ async function copyFromSource(
 	topLocalities: number,
 	progress: NonNullable<BuildSlimOptions["onProgress"]>
 ): Promise<void> {
-	// ATTACH avoids any "load source into memory" step — SQLite walks both files in place. We need
-	// a fresh temp copy because some WOF distributions ship as read-only filesystem mounts and
-	// ATTACH will still want a writable journal on the side; copying to /tmp dodges that without
-	// mutating the canonical files in /mnt/playpen/mailwoman-data/wof/. ATTACH / DETACH stay raw
-	// — Kysely doesn't model them.
+	// 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.resolve("src.db")
+	const scratchPath = tmpScratch.path("src.db")
 
 	await copyFileTo(inputPath, scratchPath)
 
-	out.exec(`ATTACH DATABASE '${scratchPath.replaceAll("'", "''")}' AS src;`)
+	out.exec(`ATTACH DATABASE '${scratchPath.toString().replaceAll("'", "''")}' AS src;`)
 
 	try {
-		// Does this extract carry the pre-built population aux table? The admin source does; a bare
-		// postcode extract might not. The locality ranking + population copy below adapt accordingly.
 		const srcHasPopulation = Boolean(
 			out.prepare(`SELECT 1 FROM src.sqlite_master WHERE type = 'table' AND name = '${PLACE_POPULATION_TABLE}'`).get()
 		)
 
-		// The SELECT-INSERT queries below go through Kysely. The cross-schema FROM is the only
-		// "interesting" bit: by declaring `src.spr` / `src.names` / `src.place_population` in
-		// `BuildSchema`, Kysely lets us write `selectFrom("src.spr")` with the same column-type
-		// checking as the regular schema. SQLite parses the dotted identifier as a schema-name
-		// qualifier, so this works directly without any aliasing trick.
+		// 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.
 
-		// 1. Ancestor placetypes (country / region / county / etc.) — always-kept.
 		progress("country", `${inputPath}: ancestor placetypes in (${countries.join(",")})`)
 
 		await kysely
@@ -321,9 +258,8 @@ async function copyFromSource(
 			.onConflict((oc) => oc.doNothing())
 			.execute()
 
-		// 2. Top-K localities by population. Population lives in the pre-built `place_population`
-		// aux table — left-join it so localities without a population row still qualify (sorted
-		// last). If the extract has no population table, fall back to a deterministic id ordering.
+		// 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
@@ -343,7 +279,6 @@ async function copyFromSource(
 			.onConflict((oc) => oc.doNothing())
 			.execute()
 
-		// 3. All postcodes in scope.
 		progress("postcode", `${inputPath}: all postcodes`)
 
 		await kysely
@@ -360,7 +295,6 @@ async function copyFromSource(
 			.onConflict((oc) => oc.doNothing())
 			.execute()
 
-		// 4. Pull names for the IDs we just selected.
 		progress("names", `${inputPath}: names rows for selected IDs`)
 
 		await kysely
@@ -369,7 +303,6 @@ async function copyFromSource(
 			.onConflict((oc) => oc.doNothing())
 			.execute()
 
-		// 5. Pull population rows for the selected IDs (sparse — only the places WOF has a count for).
 		if (srcHasPopulation) {
 			progress("place_population", `${inputPath}: population rows for selected IDs`)
 
@@ -382,11 +315,8 @@ async function copyFromSource(
 				.execute()
 		}
 
-		// 6. Carry the coincident_roles relation (#402) when this source has it (the admin DB), so the
-		// slim/demo DB supports dual-role hierarchy completion (on by default). Filtered to surviving
-		// spr ids → no orphans. Tiny (~hundreds of rows). `ancestors` is intentionally NOT copied (huge
-		// + build-only), so we copy the derived table rather than rebuild it. Raw SQL — conditional +
-		// not in the Kysely build schema.
+		// `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

package/lib/candidate/alias-bags.ts

@@ -2,7 +2,7 @@
  * @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"
@@ -10,19 +10,18 @@ import { tableExists } from "@mailwoman/sqlite/introspection"
 
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
 import type { CandidateDatabase } from "#candidate/schema"
-import { ALIAS_SEPARATOR } from "#fts/index"
+import { ALIAS_SEPARATOR } from "#fts"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * 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 carries no `names` table (a fixture, or an extract shape).
+ * The official name of every current region, keyed `${country id}\0${name key}` →
+ * region id, from the source `names` table's `official` bit.
  *
- * This is the positive evidence behind the one 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. Three such pairs exist in the admin artifact —
- * `新竹市` on Hsinchu County (the city's official name), `嘉義市` on Chiayi County, `충청남도` on Sejong — and each let the more
- * populous holder of the variant outrank the place the name officially is, so a `新竹市` region node resolved the county
- * and every district scoped to the city contradicted it.
+ * 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>,
@@ -50,12 +49,12 @@ function officialNameHoldersByRegion(
 }
 
 /**
- * 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).
+ * 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.
+ * 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>,
@@ -84,9 +83,9 @@ export function explodeAliasBags(
 		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)
 

package/lib/candidate/ancestors/schema.ts

@@ -3,80 +3,78 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for the candidate gazetteer's ANCESTORS sidecar (`candidate_ancestor` +
+ *   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}.
  *
- *   ENCODING: closure-lite rows, denormalized — one row per (place, ancestor) edge carrying the
- *   parent's placetype, display name and folded key — rather than a fixed-slot id chain on the
- *   candidate row. Decided by the two consumers:
+ *   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 answers with ids, and every id then needs a name lookup the
- *      artifact has no per-id table for — up to 8 indirections where the closure row has zero.
- *   2. The account layer needs EVERY candidate under a `name_key` enumerable WITH its chain from
+ *   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.
  *
- *   Denormalizing the parent onto the edge is the same discipline as the candidate table itself:
- *   this artifact is read over HTTP byte ranges, where a join to a dimension table scatters page
- *   fetches, and a `WITHOUT ROWID` B-tree clustered on `(spr_id, depth)` keeps a whole chain in
- *   1-2 pages. The repeated parent strings are the price of the zero-join read, paid at build time.
+ *   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), increasing outward to the
- *   country — the same nearest-first order `ancestry.ts` serves for the FTS backend, so the two
- *   backends' `ancestors()` agree by construction. The order within a place is deterministic:
+ *   `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}
+ *   {@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` carries pre/post-order labels over the CANONICAL-PARENT FOREST, assigned
- *   at build time: `a` contains `d` ⟺ `a.pre <= d.pre AND d.post <= a.post` — O(1) in either
- *   direction with no chain scan and no knowledge of either side's tier — and the descendants of
- *   `a` are the contiguous range `pre BETWEEN a.pre AND a.post`. Interval labels are classically
- *   avoided for their relabel-on-update cost; this database is a sealed read-only artifact rebuilt
- *   whole, which is exactly the regime where that cost is void.
- *
- *   THE DAG CAVEAT, and the recorded choice: WOF places can carry more than one parent (multiple
- *   hierarchies, ambiguous boundaries). `candidate_ancestor` keeps EVERY parent — the closure rows
- *   are the complete containment record. A single interval pair can only encode a tree, so the
- *   interval forest links each place to ONE canonical parent: its depth-1 edge — the finest
- *   containment tier, lowest ancestor id — the same MIN-stability convention the candidate table's
- *   `region_id` stamp uses. A containment question about a NON-canonical hierarchy must consult the
- *   closure rows; the interval answer for it is `false`, which is why interval verdicts are
- *   "contained along the canonical hierarchy", never "not contained at all".
- *
- *   ABSENCE SEMANTICS (meaning-of-zero): a place with no `candidate_interval` row has no recorded
+ *   `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.
+ *   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.
+// 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; anything past it is source noise the build drops (and counts) rather than
- * stores.
+ * 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`.
+ * 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.
+ * 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"
 
@@ -102,19 +100,24 @@ export interface CandidateAncestorTable {
 	 */
 	parent_placetype_id: number
 	/**
-	 * The ancestor's canonical display name — what {@link Ancestor.name} serves, matching the FTS backend's register.
+	 * 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.
+	 * 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.
+ * 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
@@ -123,8 +126,10 @@ export interface CandidateIntervalTable {
 }
 
 /**
- * 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.
+ * 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
@@ -132,8 +137,12 @@ export interface CandidateAncestorsDatabase {
 }
 
 /**
- * The `candidate_ancestor` columns in clustered-key order — the first two ARE the primary key, and the builder's
- * positional `INSERT` binds by this order. Keep in sync with {@link CandidateAncestorTable}.
+ * 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",
@@ -145,8 +154,10 @@ export const CANDIDATE_ANCESTOR_COLUMNS = [
 ] 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.
+ * 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
@@ -158,13 +169,15 @@ export async function createCandidateAncestorTable(db: Kysely<CandidateDatabase>
 		.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.
+		// `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.
+ * 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
@@ -177,7 +190,8 @@ export async function createCandidateIntervalTable(db: Kysely<CandidateDatabase>
 }
 
 /**
- * One place's interval label — the shape both sides of a containment comparison read.
+ * One place's interval label.
+ * The shape both sides of a containment comparison read.
  */
 export interface IntervalLabel {
 	pre: number
@@ -185,10 +199,12 @@ export interface IntervalLabel {
 }
 
 /**
- * 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.
+ * 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