@mailwoman/resolver-wof-sqlite 9.2.0 → 9.3.0

package/{build-slim.ts → lib/build-slim.ts}

@@ -29,23 +29,23 @@
  *   (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-shard inputs (e.g. admin + postcode) are processed in sequence; selected rows accumulate
- *   into the single output DB. The postcode shard contributes only postcodes; admin contributes
- *   everything else. Empty / missing input paths are skipped (callers pass `""` when a shard, such
+ *   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 { copyFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
-import { DatabaseSync } from "node:sqlite"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { temporaryDirectory } from "@mailwoman/core/fs/temporary"
+import { copyFileTo, removePath } from "@mailwoman/core/fs/writers"
+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 { SqliteDialect } from "@mailwoman/core/kysley/dialect"
-import { sealDatabase } from "@mailwoman/core/utils"
-import { Kysely, sql } from "kysely"
-
-import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE } from "./fts.ts"
-import type { NamesTable, SprTable } from "./schema.ts"
+import { buildPlaceSearchFTS, PLACE_BBOX_TABLE, PLACE_POPULATION_TABLE, PLACE_SEARCH_TABLE } from "#fts/index"
+import type { NamesTable, SprTable, WOFDatabase } from "#schema"
 
 export interface BuildSlimOptions {
 	/**
@@ -69,7 +69,7 @@ export interface BuildSlimOptions {
 	 * 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 shard rather than re-bloat the hot DB.
+	 * alt-names at runtime should ship a SEPARATE extract rather than re-bloat the hot DB.
 	 */
 	dropNames?: boolean
 	/**
@@ -149,65 +149,59 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 	const topLocalities = opts.topLocalitiesPerCountry ?? 1000
 	const progress = opts.onProgress ?? (() => {})
 
-	// Callers pass `""` for shards that don't exist yet (e.g. a not-yet-built custom postcode DB).
+	// 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)
 
 	if (!inputs.length) throw new Error("no input WOF dbs provided")
 
 	for (const input of inputs) {
-		if (!existsSync(input)) throw new Error(`input WOF db not found: ${input}`)
+		if (!(await pathExists(input))) throw new Error(`input WOF db not found: ${input}`)
 	}
 
 	progress("init", `${inputs.length} input(s) → ${opts.output}`)
 
-	if (existsSync(opts.output)) {
-		rmSync(opts.output)
+	if (await pathExists(opts.output)) {
+		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.
-	const out = new DatabaseSync(opts.output)
+	const out = new DatabaseClient<BuildSchema>(opts.output)
 	let result: BuildSlimResult
 
 	try {
-		const firstSource = new DatabaseSync(inputs[0]!, { readOnly: true })
-
-		try {
-			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 (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.
-					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.
-					out.exec(PLACE_POPULATION_DDL)
-				} else {
-					throw new Error(`source DB ${inputs[0]} is missing required table '${table}'`)
-				}
+		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 (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.
+				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.
+				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.
-			out.exec(`CREATE INDEX IF NOT EXISTS names_id_idx ON names(id);`)
-		} finally {
-			firstSource.close()
 		}
 
-		const kysely = new Kysely<BuildSchema>({ dialect: new SqliteDialect({ database: out }) })
+		// 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.
+		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, kysely, inputPath, countries, topLocalities, progress)
+			await copyFromSource(out, out, inputPath, countries, topLocalities, progress)
 		}
 
 		// Build the resolver virtual tables on the trimmed row set. Both place_search (FTS5) and
@@ -264,21 +258,21 @@ export async function buildSlimWOFDatabase(opts: BuildSlimOptions): Promise<Buil
 
 		result = {
 			outputPath: opts.output,
-			outputBytes: statSync(opts.output).size,
+			outputBytes: (await statPath(opts.output)).size,
 			rowCounts,
 		}
 	} finally {
-		out.close()
+		await out.destroy()
 	}
 
 	// The sealed-artifact invariant: a built DB is a read-only asset from the moment it exists.
-	sealDatabase(opts.output)
+	await sealDatabase(opts.output)
 
 	return result
 }
 
 async function copyFromSource(
-	out: DatabaseSync,
+	out: DatabaseClient<BuildSchema>,
 	kysely: Kysely<BuildSchema>,
 	inputPath: string,
 	countries: string[],
@@ -290,134 +284,125 @@ async function copyFromSource(
 	// 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.
-	const tmpScratch = mkdtempSync(join(tmpdir(), "mailwoman-slim-src-"))
-	const scratchPath = join(tmpScratch, "src.db")
-	copyFileSync(inputPath, scratchPath)
+	await using tmpScratch = await temporaryDirectory("mailwoman-slim-src-")
+	const scratchPath = tmpScratch.resolve("src.db")
 
-	try {
-		out.exec(`ATTACH DATABASE '${scratchPath.replaceAll("'", "''")}' AS src;`)
-
-		try {
-			// Does this shard carry the pre-built population aux table? The admin source does; a bare
-			// postcode shard 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()
-			)
+	await copyFileTo(inputPath, scratchPath)
 
-			// 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.
+	out.exec(`ATTACH DATABASE '${scratchPath.replaceAll("'", "''")}' AS src;`)
 
-			// 1. Ancestor placetypes (country / region / county / etc.) — always-kept.
-			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()
+	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.
+
+		// 1. Ancestor placetypes (country / region / county / etc.) — always-kept.
+		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()
+
+		// 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.
+		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()
+
+		// 3. All postcodes in scope.
+		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()
 
-			// 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 shard has no population table, fall back to a deterministic id ordering.
-			progress("locality", `${inputPath}: top-${topLocalities} localities by population`)
+		// 4. Pull names for the IDs we just selected.
+		progress("names", `${inputPath}: names rows for selected IDs`)
 
-			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()
+		await kysely
+			.insertInto("names")
+			.expression((eb) => eb.selectFrom("src.names").selectAll().where("id", "in", eb.selectFrom("spr").select("id")))
+			.onConflict((oc) => oc.doNothing())
+			.execute()
 
-			// 3. All postcodes in scope.
-			progress("postcode", `${inputPath}: all postcodes`)
+		// 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`)
 
 			await kysely
-				.insertInto("spr")
+				.insertInto("place_population")
 				.expression((eb) =>
-					eb
-						.selectFrom("src.spr")
-						.selectAll()
-						.where("is_current", "!=", 0)
-						.where("is_deprecated", "=", 0)
-						.where("country", "in", countries)
-						.where("placetype", "=", "postalcode")
+					eb.selectFrom("src.place_population").selectAll().where("id", "in", eb.selectFrom("spr").select("id"))
 				)
 				.onConflict((oc) => oc.doNothing())
 				.execute()
+		}
 
-			// 4. Pull names for the IDs we just selected.
-			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()
-
-			// 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`)
-
-				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()
-			}
-
-			// 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.
-			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)`
-				)
+		// 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.
+		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;`)
+			out.exec(`CREATE INDEX IF NOT EXISTS coincident_roles_by_admin ON coincident_roles (admin_id)`)
 		}
 	} finally {
-		rmSync(tmpScratch, { recursive: true, force: true })
+		out.exec(`DETACH DATABASE src;`)
 	}
 }
-
-function countRows(db: DatabaseSync, table: string): number {
-	const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n?: number } | undefined
-
-	return Number(row?.n ?? 0)
-}

package/{candidate → lib/candidate}/alias-bags.ts

@@ -5,19 +5,21 @@
  * @file Pass 2 of the candidate build — explode `place_search.alt_names` into distinct alias rows.
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { ALIAS_SEPARATOR } from "../fts.ts"
-import { normalizeLocalityForKey } from "../street-normalize.ts"
-import type { PlaceAttrs, StageRow } from "./place-attrs.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import { ALIAS_SEPARATOR } from "#fts/index"
+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).
  */
 export function explodeAliasBags(
-	src: DatabaseSync,
-	out: DatabaseSync,
+	src: DatabaseClient<WOFDatabase>,
+	out: DatabaseClient<CandidateDatabase>,
 	attrs: Map<number, PlaceAttrs>,
 	stageRow: StageRow
 ): { nAlias: number; keyCounts: Map<number, number> } {

package/{candidate → lib/candidate}/ancestors-sidecar.ts

@@ -5,11 +5,9 @@
  * @file Pass 3b of the candidate build — the containment sidecar (closure rows + interval labels).
  */
 
-import type { DatabaseSync } from "node:sqlite"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import type { DatabaseClient } from "@mailwoman/core/kysley/client"
-
-import { placetypeDepth } from "../ancestry.ts"
+import { placetypeDepth } from "#ancestry/index"
 import {
 	CANDIDATE_ANCESTOR_COLUMNS,
 	CANDIDATE_ANCESTOR_TABLE,
@@ -17,9 +15,10 @@ import {
 	createCandidateAncestorTable,
 	createCandidateIntervalTable,
 	MAX_ANCESTOR_DEPTH,
-} from "../candidate-ancestors-schema.ts"
-import type { CandidateDatabase } from "../candidate-schema.ts"
-import type { PlaceAttrs } from "./place-attrs.ts"
+} from "#candidate-ancestors-schema"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { WOFDatabase } from "#schema"
 
 /**
  * Pass 3b — the ancestors sidecar: closure rows + interval labels (candidate-ancestors-schema.ts owns the encoding
@@ -27,14 +26,13 @@ import type { PlaceAttrs } from "./place-attrs.ts"
  * denormalizing each edge with the parent's name/key from `attrs`, streamed `ORDER BY id` so the clustered `(spr_id,
  * depth)` insert is sorted — the contiguous-leaves discipline of the candidate table itself.
  *
- * Excluded by policy: self rows, and placetypes outside the containment ladder (continent, empire, …: `placetypeDepth`
- * 0) — they discriminate nothing a consumer of this sidecar checks. An edge to a parent with no current `spr` row has
- * no name to denormalize; it is dropped and counted rather than stored blind.
+ * Excluded by policy: self rows, and placetypes outside the containment ladder (continent, empire, …: `placetypeDepth` 0)
+ * — they discriminate nothing a consumer of this sidecar checks. An edge to a parent with no current `spr` row has no
+ * name to denormalize; it is dropped and counted rather than stored blind.
  */
 export async function buildAncestorsSidecar(ctx: {
-	src: DatabaseSync
-	out: DatabaseSync
-	kdb: DatabaseClient<CandidateDatabase>
+	src: DatabaseClient<WOFDatabase>
+	out: DatabaseClient<CandidateDatabase>
 	attrs: Map<number, PlaceAttrs>
 	ptID: (pt: string | null) => number
 	progress: (phase: string, message: string) => void
@@ -42,8 +40,8 @@ export async function buildAncestorsSidecar(ctx: {
 	const { src, out, attrs, ptID, progress } = ctx
 
 	progress("ancestors", "building containment sidecar (closure rows + interval labels)")
-	await createCandidateAncestorTable(ctx.kdb)
-	await createCandidateIntervalTable(ctx.kdb)
+	await createCandidateAncestorTable(ctx.out)
+	await createCandidateIntervalTable(ctx.out)
 
 	const insAncestor = out.prepare(
 		`INSERT INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`

package/{candidate → lib/candidate}/country-display-names.ts

@@ -7,8 +7,8 @@
 
 import { enumerateCountryDisplayNames } from "@mailwoman/codex/country"
 
-import { normalizeLocalityForKey } from "../street-normalize.ts"
-import type { PlaceAttrs, StageRow } from "./place-attrs.ts"
+import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
  * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).

package/{candidate/shard-fold.ts → lib/candidate/extract-fold.ts}

@@ -2,40 +2,43 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 4 of the candidate build — fold a postcode or locality shard into the staging table.
+ * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
  */
 
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { tableExists } from "@mailwoman/sqlite/introspection"
 
-import { normalizeLocalityForKey } from "../street-normalize.ts"
-import type { PlaceAttrs, StageRow } from "./place-attrs.ts"
+import type { CandidateDatabase } from "#candidate-schema"
+import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { WOFDatabase } from "#schema"
+import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Fold ONE shard (`spr` rows at `shardPlacetype` carrying real coordinates) in, then pass 4b: the alias names hanging
- * off that same shard's `names` table.
+ * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
+ * hanging off that same extract's `names` table.
  *
  * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
  * above it, and nothing downstream reads anything it produces except the two counters it returns.
  */
-export function foldShard(ctx: {
+export function foldExtract(ctx: {
 	/**
-	 * The staging connection. The shard itself is opened read-only here and closed before returning.
+	 * The staging connection. The extract itself is opened read-only here and closed before returning.
 	 */
-	out: DatabaseSync
-	shardPath: string
-	shardPlacetype: "postalcode" | "locality"
+	out: DatabaseClient<CandidateDatabase>
+	extractPath: string
+	extractPlacetype: "postalcode" | "locality"
 	ccID: (code: string | null) => number
 	ptID: (pt: string | null) => number
 	stageRow: StageRow
 	progress: (phase: string, message: string) => void
 }): { primaries: number; aliases: number } {
-	const { out, shardPath, shardPlacetype, ccID, ptID, stageRow, progress } = ctx
+	const { out, extractPath, extractPlacetype, ccID, ptID, stageRow, progress } = ctx
 
-	progress(shardPlacetype === "postalcode" ? "postcodes" : "localities", `reading ${shardPath}`)
+	progress(extractPlacetype === "postalcode" ? "postcodes" : "localities", `reading ${extractPath}`)
 
-	const pc = new DatabaseSync(shardPath, { readOnly: true })
-	const pcPtid = ptID(shardPlacetype)
-	// Per-shard, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
+	using pc = new DatabaseClient<WOFDatabase>(extractPath, { readOnly: true })
+	const pcPtid = ptID(extractPlacetype)
+	// Per-extract, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
 	// below has nothing to join against unless this primary loop records what it staged.
 	const pcAttrs = new Map<number, PlaceAttrs>()
 	let primaries = 0
@@ -49,7 +52,7 @@ export function foldShard(ctx: {
 				min_latitude AS mnlat, min_longitude AS mnlon, max_latitude AS mxlat, max_longitude AS mxlon
 			 FROM spr WHERE placetype = ? AND latitude != 0 AND longitude != 0`
 		)
-		.iterate(shardPlacetype)) {
+		.iterate(extractPlacetype)) {
 		const name = String(r.name ?? "")
 		const key = normalizeLocalityForKey(name)
 
@@ -91,18 +94,18 @@ export function foldShard(ctx: {
 	// --- pass 4b: postcode ALIAS names (#1495) ---
 	//
 	// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
-	// the shard's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
+	// the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
 	// downstream of `names` picked them up EXCEPT this build: `fts.ts` unions `spr.name` with every
 	// `names` row into `place_search.alt_names`, so the FTS backend resolved "Brooklyn" → 11201
 	// while the candidate backend — whose every row IS an exact-tier row — had no key for it at
 	// all. Pass 2 does the equivalent fold for admin places, but reads the ADMIN `place_search`,
-	// and `attrs` holds admin ids only, so a postcode shard could never reach it.
+	// and `attrs` holds admin ids only, so a postcode extract could never reach it.
 	//
 	// Same discipline as pass 2: `is_primary = 0` (so `rankByPrimaryPreference` treats it as an
 	// alias, not a canonical postcode name), the row stays denormalized onto the POSTCODE's own
 	// spr_id/coords/bbox, and the display `name` stays the postcode — resolving "brooklyn" answers
 	// with place 11201, it does not rename the place to its delivery city.
-	const hasNames = pc.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='names'").get() !== undefined
+	const hasNames = tableExists(pc, "names")
 
 	if (hasNames) {
 		out.exec("BEGIN")
@@ -125,13 +128,11 @@ export function foldShard(ctx: {
 
 		out.exec("COMMIT")
 	} else {
-		// Never a silent zero: real shards come from `createUnifiedSchema`, which always creates
-		// `names`. A shard without it has no alias surface to lose, but say so rather than reporting
+		// Never a silent zero: real extracts come from `createUnifiedSchema`, which always creates
+		// `names`. A extract without it has no alias surface to lose, but say so rather than reporting
 		// "0 aliases" from a table that was never read.
-		progress("postcode-aliases", `${shardPath} has no \`names\` table — no delivery-city aliases to fold`)
+		progress("postcode-aliases", `${extractPath} has no \`names\` table — no delivery-city aliases to fold`)
 	}
 
-	pc.close()
-
 	return { primaries, aliases }
 }