@mailwoman/bdc 9.0.0 → 9.2.0

package/sdk/build-bdc.ts

@@ -8,8 +8,7 @@
  *
  *   Mirrors `mailwoman/gazetteer-pipeline/poi/build-poi.ts`'s shape closely: the same build-tuning
  *   pragmas, the same single-pass `Map<number, number>` coverage aggregation taken during the load
- *   (no second scan), the same {@link asContractDB} Kysely-invariance cast for the shared
- *   `@mailwoman/core/layers` calls, and the same `writeLayerManifest` → `sealDatabase` tail.
+ *   (no second scan), and the same `writeLayerManifest` → `sealDatabase` tail.
  *
  *   Two differences from that precedent, both deliberate:
  *
@@ -51,23 +50,23 @@
  *      the house rule exists for.
  */
 
-import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs"
-import { readFile } from "node:fs/promises"
-import { dirname } from "node:path"
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs"
+import { open } from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
 import { DatabaseSync } from "node:sqlite"
 
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 import {
+	CoverageBasis,
 	createLayerCoverageTable,
 	createLayerManifestTable,
 	LayerFreshnessPolicy,
 	LayerTier,
 	writeLayerCoverage,
 	writeLayerManifest,
-	type LayerContractDatabase,
 } from "@mailwoman/core/layers"
 import { tryParsingJSON } from "@mailwoman/core/objects"
-import { openBuiltDatabase, sealDatabase } from "@mailwoman/core/utils"
+import { openBuiltDatabase, sealDatabase, swapDatabaseIntoPlace } from "@mailwoman/core/utils"
 import type { FilerDatabase } from "@mailwoman/filer"
 // `pickPrimaryFRN`/`readFRNFilingCandidates` are loaded via a LAZY `await import("@mailwoman/filer/sdk")`
 // inside `populateBDCProviderTable`, not a top-level runtime import — see that function's docstring
@@ -88,7 +87,7 @@ import {
 	type BDCProviderTable,
 } from "../schema.ts"
 import type { ProviderID } from "./common.ts"
-import { takeAvailabilityLine, type BDCAvailabilityRow } from "./parsing.ts"
+import { readAvailabilityRows, type BDCAvailabilityRow } from "./parsing.ts"
 
 /**
  * Rows committed per `BEGIN`/`COMMIT` batch during both the staging load and the materialize pass — matches
@@ -206,16 +205,6 @@ export interface BuildBDCResult {
 	providersPopulated: number
 }
 
-/**
- * `BDCDatabase extends LayerContractDatabase` structurally, but Kysely's `transaction()` makes `Kysely<DB>` INVARIANT
- * in `DB` — narrows a `DatabaseClient<BDCDatabase>` handle back down for the `@mailwoman/core/layers` calls. Exact
- * precedent: `build-poi.ts`'s own `asContractDB`; see that file for the full rationale (tried widening the shared
- * package's signatures first — breaks THEIR internal `insertInto`/`selectFrom` calls instead).
- */
-function asContractDB(kdb: DatabaseClient<BDCDatabase>): DatabaseClient<LayerContractDatabase> {
-	return kdb as unknown as DatabaseClient<LayerContractDatabase>
-}
-
 /**
  * Create the build-only `bdc_stage` table — deliberately NOT part of the public {@link BDCDatabase} interface (it's
  * dropped before the artifact seals, so it never appears in the shipped schema). Built via Kysely's schema builder per
@@ -308,17 +297,43 @@ export function peekProviderID(csvBuffer: Buffer, csvPath?: string): ProviderID
 }
 
 /**
- * Reads each of `csvPaths` fully into memory, peeks its `provider_id` ({@linkcode peekProviderID}, passing the path
- * through so a malformed file's error names it), then yields every row via `takeAvailabilityLine`. This is the
+ * Bytes read to peek the `provider_id`. Only the header row plus the first data row are needed and an FCC availability
+ * row is ~110 bytes, so this is three orders of magnitude of slack. A file shorter than this simply reads short —
+ * {@linkcode peekProviderID} already reports a header-only or empty file by message.
+ */
+const PROVIDER_ID_PEEK_BYTES = 64 * 1024
+
+/**
+ * Read the head of a CSV, for {@linkcode peekProviderID}.
+ *
+ * The point is what it does NOT do. `provider_id` is a constant per file, so establishing it needs the first data row
+ * and nothing else; `readFile(csvPath)` was resident-loading the entire file to read one column of one row. The
+ * measured file that motivated this is 920 MB for a single state × technology.
+ */
+async function readCSVHead(csvPath: string): Promise<Buffer> {
+	const handle = await open(csvPath)
+
+	try {
+		const buffer = Buffer.allocUnsafe(PROVIDER_ID_PEEK_BYTES)
+		const { bytesRead } = await handle.read(buffer, 0, PROVIDER_ID_PEEK_BYTES, 0)
+
+		return buffer.subarray(0, bytesRead)
+	} finally {
+		await handle.close()
+	}
+}
+
+/**
+ * Peeks each file's `provider_id` off its head ({@linkcode peekProviderID}, passing the path through so a malformed
+ * file's error names it), then STREAMS every row via `readAvailabilityRows` — the file is never resident. This is the
  * production counterpart to the test seam's injected `rows` — exercised by `build-bdc.test.ts` only for the
  * malformed-provider-id rejection path, same as `build-poi.ts`'s `readParquetRows`.
  */
 async function* readAvailabilityRowsFromCSVPaths(csvPaths: readonly string[]): AsyncIterable<BDCAvailabilityRow> {
 	for (const csvPath of csvPaths) {
-		const buffer = await readFile(csvPath)
-		const providerID = peekProviderID(buffer, csvPath)
+		const providerID = peekProviderID(await readCSVHead(csvPath), csvPath)
 
-		yield* takeAvailabilityLine(buffer, providerID)
+		yield* readAvailabilityRows(csvPath, providerID)
 	}
 }
 
@@ -336,11 +351,18 @@ interface GeoJSONMultiPolygon {
 }
 
 /**
- * Naive (vertex-average, NOT area-weighted) centroid of a GeoJSON `Polygon`/`MultiPolygon`'s EXTERIOR ring(s) only
- * (interior rings/holes are ignored). A known simplification, not an oversight: census blocks are small relative to a
- * res-9 H3 cell (~174m edge), so the vertex-average and a proper area-weighted centroid land in the same cell for all
- * but pathologically elongated or holed block shapes. A precise area-weighted centroid is a reasonable future upgrade
- * if that ever proves wrong in practice — no polygon-centroid library is pulled in for this first cut.
+ * Area-weighted (shoelace) centroid of a GeoJSON `Polygon`/`MultiPolygon`'s EXTERIOR ring(s), area-weighted across
+ * rings for a MultiPolygon. Interior rings/holes are still ignored — a hole moves a block's centroid far less than the
+ * vertex-density skew this replaces, and only 1.0% of measured blocks carry one.
+ *
+ * This REPLACED the first cut's vertex-average, whose "same res-9 cell for all but pathological shapes" claim was
+ * falsified by measurement over every real TIGER 2020 block in LA + Orange county (118,360 blocks, 2026-08-11): the
+ * vertex-average landed in a different res-9 cell for 11.6% of blocks, p99 displacement 286 m (past the ~174 m cell
+ * edge), max 3.7 km — the tail is TIGER's elongated rural/mountain blocks, whose boundary vertices cluster on the
+ * squiggly natural edge and drag a vertex-average toward it.
+ *
+ * A degenerate geometry with zero total ring area (a sliver the shoelace annihilates) falls back to the vertex average
+ * — a weaker answer beats none, and the fallback is exactly the old behavior.
  *
  * Returns `undefined` for anything that doesn't parse as one of the two geometry types (including `null` geometry).
  */
@@ -358,21 +380,49 @@ export function geometryCentroid(geometryJSON: string | null): { lat: number; lo
 				? geometry.coordinates.map((polygon) => polygon[0] ?? [])
 				: []
 
+	let totalArea = 0
+	let weightedLon = 0
+	let weightedLat = 0
 	let sumLon = 0
 	let sumLat = 0
 	let count = 0
 
 	for (const ring of exteriorRings) {
-		for (const point of ring) {
-			const [lon, lat] = point
+		let ringArea = 0
+		let ringLon = 0
+		let ringLat = 0
 
-			if (typeof lon !== "number" || typeof lat !== "number") continue
+		for (let i = 0; i < ring.length - 1; i++) {
+			const [x1, y1] = ring[i]!
+			const [x2, y2] = ring[i + 1]!
 
-			sumLon += lon
-			sumLat += lat
+			if (typeof x1 !== "number" || typeof y1 !== "number" || typeof x2 !== "number" || typeof y2 !== "number") {
+				continue
+			}
+
+			const cross = x1 * y2 - x2 * y1
+			ringArea += cross
+			ringLon += (x1 + x2) * cross
+			ringLat += (y1 + y2) * cross
+			// The vertex-average fallback accumulates alongside — one pass, both answers.
+			sumLon += x1
+			sumLat += y1
 
 			count++
 		}
+
+		ringArea /= 2
+
+		if (ringArea === 0) continue
+
+		const weight = Math.abs(ringArea)
+		totalArea += weight
+		weightedLon += (ringLon / (6 * ringArea)) * weight
+		weightedLat += (ringLat / (6 * ringArea)) * weight
+	}
+
+	if (totalArea > 0) {
+		return { lat: weightedLat / totalArea, lon: weightedLon / totalArea }
 	}
 
 	if (count === 0) return undefined
@@ -536,6 +586,22 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 
 	mkdirSync(dirname(options.out), { recursive: true })
 
+	// A crash inside a PRIOR run's swap can leave the slot empty while the previous version sits
+	// parked aside — restore it before building, so a failure in THIS run still leaves an artifact
+	// serving. Both aside spellings: this builder's old `.prev` and swapDatabaseIntoPlace's `.old-<pid>`.
+	if (!existsSync(options.out)) {
+		const base = basename(options.out)
+
+		const parked = readdirSync(dirname(options.out)).find(
+			(name) => name === `${base}.prev` || name.startsWith(`${base}.old-`)
+		)
+
+		if (parked) {
+			renameSync(join(dirname(options.out), parked), options.out)
+			progress(`restored ${parked} into place (a prior run crashed mid-swap)`)
+		}
+	}
+
 	const rowSource: AsyncIterable<BDCAvailabilityRow> | Iterable<BDCAvailabilityRow> =
 		options.rows ?? readAvailabilityRowsFromCSVPaths(options.csvPaths!)
 
@@ -544,264 +610,274 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 	db.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;")
 	const kdb = new DatabaseClient<BDCDatabase>({ database: db })
 
-	progress("creating manifest/coverage/availability/provider/stage tables")
-	await createLayerManifestTable(asContractDB(kdb))
-	await createLayerCoverageTable(asContractDB(kdb))
-	await createBDCAvailabilityTable(kdb)
-	await createBDCProviderTable(kdb)
-	await createBDCStageTable(kdb)
+	// Assigned at the end of the try — the tallies live inside its scope; the seal + swap do not.
+	let result: BuildBDCResult
 
-	const insStage = db.prepare(
-		`INSERT OR IGNORE INTO bdc_stage (
+	try {
+		progress("creating manifest/coverage/availability/provider/stage tables")
+		await createLayerManifestTable(kdb)
+		await createLayerCoverageTable(kdb)
+		await createBDCAvailabilityTable(kdb)
+		await createBDCProviderTable(kdb)
+		await createBDCStageTable(kdb)
+
+		const insStage = db.prepare(
+			`INSERT OR IGNORE INTO bdc_stage (
 			geoid, provider_id, technology_code, location_id,
 			max_advertised_download_speed, max_advertised_upload_speed, low_latency, business_residential_code
 		) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
-	)
-
-	let staged = 0
-	let batch = 0
-
-	progress("staging rows — raw prepared INSERT OR IGNORE on the natural key (the Redis-dedup replacement)")
-	db.exec("BEGIN")
-
-	for await (const row of rowSource) {
-		insStage.run(
-			row.geoid,
-			row.provider_id,
-			row.technology_code,
-			row.location_id,
-			row.max_advertised_download_speed,
-			row.max_advertised_upload_speed,
-			row.low_latency,
-			row.business_residential_code
 		)
 
-		staged++
+		let staged = 0
+		let batch = 0
+
+		progress("staging rows — raw prepared INSERT OR IGNORE on the natural key (the Redis-dedup replacement)")
+		db.exec("BEGIN")
+
+		for await (const row of rowSource) {
+			insStage.run(
+				row.geoid,
+				row.provider_id,
+				row.technology_code,
+				row.location_id,
+				row.max_advertised_download_speed,
+				row.max_advertised_upload_speed,
+				row.low_latency,
+				row.business_residential_code
+			)
 
-		batch++
+			staged++
 
-		if (batch >= STAGE_BATCH_SIZE) {
-			db.exec("COMMIT")
-			db.exec("BEGIN")
-			batch = 0
-		}
-	}
+			batch++
 
-	db.exec("COMMIT")
+			if (batch >= STAGE_BATCH_SIZE) {
+				db.exec("COMMIT")
+				db.exec("BEGIN")
+				batch = 0
+			}
+		}
 
-	const stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get() as {
-		staged_count: number
-	}
+		db.exec("COMMIT")
 
-	const deduped = staged - stagedCountRow.staged_count
+		const stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get() as {
+			staged_count: number
+		}
 
-	progress(
-		`staged ${stagedCountRow.staged_count.toLocaleString()} distinct row(s), ${deduped.toLocaleString()} deduped`
-	)
+		const deduped = staged - stagedCountRow.staged_count
 
-	const centroidCache = new Map<string, { h3Cell: number; coverageCell: number } | null>()
-	/**
-	 * Res-6 short-cell int → observed row count, aggregated during materialize (one pass, no second scan) — matches
-	 * `build-poi.ts`'s `coverage` Map.
-	 */
-	const coverage = new Map<number, number>()
-	const providers = new Set<number>()
-	let unknownGeoids = 0
-	let inserted = 0
+		progress(
+			`staged ${stagedCountRow.staged_count.toLocaleString()} distinct row(s), ${deduped.toLocaleString()} deduped`
+		)
 
-	const insAvailability = db.prepare(
-		`INSERT INTO bdc_availability (
+		const centroidCache = new Map<string, { h3Cell: number; coverageCell: number } | null>()
+		/**
+		 * Res-6 short-cell int → observed row count, aggregated during materialize (one pass, no second scan) — matches
+		 * `build-poi.ts`'s `coverage` Map.
+		 */
+		const coverage = new Map<number, number>()
+		const providers = new Set<number>()
+		let unknownGeoids = 0
+		let inserted = 0
+
+		const insAvailability = db.prepare(
+			`INSERT INTO bdc_availability (
 			h3_cell, geoid, wof_id, provider_id, technology_code,
 			max_advertised_download_speed, max_advertised_upload_speed, low_latency, business_residential_code, location_id
 		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
-	)
-
-	// The FCC's per-provider CSVs are per-BSL: the SAME (geoid, provider_id, technology_code, speeds, low_latency,
-	// business_residential_code) tuple can repeat once per Broadband Serviceable Location within that block (a
-	// dense urban block can carry ~100 BSLs) — `bdc_stage`'s natural key includes `location_id`, so those BSL rows
-	// all survive the staging dedup as distinct staged rows. In `includeLocationIDs` mode that's correct: every BSL
-	// is a real, distinct row the caller asked to keep. In the default (NULL `location_id`) mode, when those BSLs
-	// ALSO share identical speeds/flags, they'd otherwise materialize as byte-identical rows, inflating `result.rows`
-	// and `layer_coverage.observed_rows` by the BSL count (~100x at real scale) — `SELECT DISTINCT`
-	// over every column EXCEPT `location_id` collapses those byte-identical BSL duplicates down to one row.
-	// IMPORTANT — this is NOT a guarantee of one row per (geoid, provider_id, technology_code) triple: BSLs at the
-	// same triple with DIFFERING speeds/flags are NOT the same tuple, so `SELECT DISTINCT` does not merge them —
-	// they survive as multiple NULL-`location_id` rows at that one triple. Accepted, not a bug; see the module
-	// docstring and `filing-landscape.ts`'s docstring for the read-side consequence.
-	const stageStmt = options.includeLocationIDs
-		? db.prepare(
-				`SELECT geoid, provider_id, technology_code, location_id,
+		)
+
+		// The FCC's per-provider CSVs are per-BSL: the SAME (geoid, provider_id, technology_code, speeds, low_latency,
+		// business_residential_code) tuple can repeat once per Broadband Serviceable Location within that block (a
+		// dense urban block can carry ~100 BSLs) — `bdc_stage`'s natural key includes `location_id`, so those BSL rows
+		// all survive the staging dedup as distinct staged rows. In `includeLocationIDs` mode that's correct: every BSL
+		// is a real, distinct row the caller asked to keep. In the default (NULL `location_id`) mode, when those BSLs
+		// ALSO share identical speeds/flags, they'd otherwise materialize as byte-identical rows, inflating `result.rows`
+		// and `layer_coverage.observed_rows` by the BSL count (~100x at real scale) — `SELECT DISTINCT`
+		// over every column EXCEPT `location_id` collapses those byte-identical BSL duplicates down to one row.
+		// IMPORTANT — this is NOT a guarantee of one row per (geoid, provider_id, technology_code) triple: BSLs at the
+		// same triple with DIFFERING speeds/flags are NOT the same tuple, so `SELECT DISTINCT` does not merge them —
+		// they survive as multiple NULL-`location_id` rows at that one triple. Accepted, not a bug; see the module
+		// docstring and `filing-landscape.ts`'s docstring for the read-side consequence.
+		const stageStmt = options.includeLocationIDs
+			? db.prepare(
+					`SELECT geoid, provider_id, technology_code, location_id,
 					max_advertised_download_speed, max_advertised_upload_speed, low_latency, business_residential_code
 				 FROM bdc_stage`
-			)
-		: db.prepare(
-				`SELECT DISTINCT geoid, provider_id, technology_code,
+				)
+			: db.prepare(
+					`SELECT DISTINCT geoid, provider_id, technology_code,
 					max_advertised_download_speed, max_advertised_upload_speed, low_latency, business_residential_code
 				 FROM bdc_stage`
+				)
+
+		progress(
+			"materializing bdc_availability — resolving block centroids to h3_cell (unknown geoids skipped, never guessed)"
+		)
+
+		db.exec("BEGIN")
+		batch = 0
+
+		for (const row of stageStmt.iterate() as IterableIterator<BDCStageRow>) {
+			let resolved = centroidCache.get(row.geoid)
+
+			if (resolved === undefined) {
+				const centroid = options.blockCentroids(row.geoid)
+
+				resolved = centroid
+					? (() => {
+							// Coverage cell MUST be derived as the res-9 cell's H3 hierarchy parent — NOT a second,
+							// independent `latLngToCell(centroid, 6)` call. H3's cell hierarchy is not geometrically
+							// exact: a point's directly-indexed res-6 cell and its res-9 cell's `cellToParent(…, 6)`
+							// disagree for a real fraction of points (~6% empirically over CONUS — hexagon/pentagon
+							// boundary artifacts). Deriving both `h3_cell` and the coverage cell from
+							// the SAME full res-9 index is what lets `filing-landscape.ts`'s reader reconstruct this
+							// exact coverage cell from nothing but the stored `h3_cell` (its `res9ShortCellToRes6Parent`
+							// applies `cellToParent` to the reconstructed res-9 cell) — builder and reader must derive
+							// the res-6 parent identically, or a genuinely-surveyed block can read back as unknown.
+							const fullRes9Cell = latLngToCell(centroid.lat, centroid.lon, BDC_H3_RESOLUTION) as H3Cell
+
+							return {
+								h3Cell: shortCellToInt(fullRes9Cell),
+								coverageCell: shortCellToInt(cellToParent(fullRes9Cell, BDC_COVERAGE_H3_RESOLUTION) as H3Cell),
+							}
+						})()
+					: null
+
+				centroidCache.set(row.geoid, resolved)
+			}
+
+			if (!resolved) {
+				unknownGeoids++
+
+				continue
+			}
+
+			insAvailability.run(
+				resolved.h3Cell,
+				row.geoid,
+				// wof_id stays NULL here — WOF point-in-polygon resolution against the block centroid is a later
+				// registry-join task, the same decision-8 scoping schema.ts documents for `bdc_provider`.
+				null,
+				row.provider_id,
+				row.technology_code,
+				row.max_advertised_download_speed,
+				row.max_advertised_upload_speed,
+				row.low_latency,
+				row.business_residential_code,
+				options.includeLocationIDs ? (row.location_id ?? null) : null
 			)
 
-	progress(
-		"materializing bdc_availability — resolving block centroids to h3_cell (unknown geoids skipped, never guessed)"
-	)
-
-	db.exec("BEGIN")
-	batch = 0
-
-	for (const row of stageStmt.iterate() as IterableIterator<BDCStageRow>) {
-		let resolved = centroidCache.get(row.geoid)
-
-		if (resolved === undefined) {
-			const centroid = options.blockCentroids(row.geoid)
-
-			resolved = centroid
-				? (() => {
-						// Coverage cell MUST be derived as the res-9 cell's H3 hierarchy parent — NOT a second,
-						// independent `latLngToCell(centroid, 6)` call. H3's cell hierarchy is not geometrically
-						// exact: a point's directly-indexed res-6 cell and its res-9 cell's `cellToParent(…, 6)`
-						// disagree for a real fraction of points (~6% empirically over CONUS — hexagon/pentagon
-						// boundary artifacts). Deriving both `h3_cell` and the coverage cell from
-						// the SAME full res-9 index is what lets `filing-landscape.ts`'s reader reconstruct this
-						// exact coverage cell from nothing but the stored `h3_cell` (its `res9ShortCellToRes6Parent`
-						// applies `cellToParent` to the reconstructed res-9 cell) — builder and reader must derive
-						// the res-6 parent identically, or a genuinely-surveyed block can read back as unknown.
-						const fullRes9Cell = latLngToCell(centroid.lat, centroid.lon, BDC_H3_RESOLUTION) as H3Cell
-
-						return {
-							h3Cell: shortCellToInt(fullRes9Cell),
-							coverageCell: shortCellToInt(cellToParent(fullRes9Cell, BDC_COVERAGE_H3_RESOLUTION) as H3Cell),
-						}
-					})()
-				: null
-
-			centroidCache.set(row.geoid, resolved)
-		}
+			inserted++
+			providers.add(row.provider_id)
+			coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1)
 
-		if (!resolved) {
-			unknownGeoids++
+			batch++
 
-			continue
+			if (batch >= STAGE_BATCH_SIZE) {
+				db.exec("COMMIT")
+				db.exec("BEGIN")
+				batch = 0
+			}
 		}
 
-		insAvailability.run(
-			resolved.h3Cell,
-			row.geoid,
-			// wof_id stays NULL here — WOF point-in-polygon resolution against the block centroid is a later
-			// registry-join task, the same decision-8 scoping schema.ts documents for `bdc_provider`.
-			null,
-			row.provider_id,
-			row.technology_code,
-			row.max_advertised_download_speed,
-			row.max_advertised_upload_speed,
-			row.low_latency,
-			row.business_residential_code,
-			options.includeLocationIDs ? (row.location_id ?? null) : null
+		db.exec("COMMIT")
+
+		progress(
+			`materialized ${inserted.toLocaleString()} row(s) across ${providers.size} provider(s) ` +
+				`(${unknownGeoids.toLocaleString()} unknown geoid(s) skipped)`
 		)
 
-		inserted++
-		providers.add(row.provider_id)
-		coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1)
+		await kdb.schema.dropTable("bdc_stage").execute()
+
+		progress("geoid index (index-after-load — see schema.ts)")
+		await createBDCGeoidIndex(kdb)
+
+		// Coverage is SOURCE-LEVEL, not survey completeness — same convention build-poi.ts documents: a res-6 cell we
+		// have availability rows in is recorded at completeness 1.0. A cell absent from `layer_coverage` means no rows
+		// were observed there at all (the meaning-of-zero rule — missing = unknown, never `{completeness: 0}`).
+		const coverageCells = [...coverage.entries()].map(([h3Cell, observedRows]) => ({
+			h3Cell,
+			completeness: 1,
+			basis: CoverageBasis.SourcePresent,
+			observedRows,
+		}))
+
+		await writeLayerCoverage(kdb, coverageCells)
+
+		progress("writing layer manifest")
+
+		await writeLayerManifest(kdb, {
+			name: "bdc",
+			version: options.asOfDate,
+			schemaVersion: 1,
+			tier: LayerTier.Shipped,
+			license: "public-domain",
+			attribution: BDC_ATTRIBUTION,
+			source: "fcc-bdc",
+			sourceVintage: options.asOfDate,
+			buildCmd: "mailwoman gazetteer build bdc",
+			buildSHA: options.buildSHA,
+			freshnessPolicy: LayerFreshnessPolicy.VersionedRefresh,
+			spineKeys: { h3: { column: "h3_cell", resolution: BDC_H3_RESOLUTION }, wofID: "wof_id" },
+			createdAt: new Date().toISOString(),
+		})
+
+		// bdc_provider population (2a decision 8 / 3a decision 6) — entirely additive and gated behind
+		// `options.providers`: when absent, this block never runs and `bdc_provider` stays empty (see
+		// `BuildBDCOptions.providers`'s docstring for the default-path guarantee).
+		let providersPopulated = 0
+
+		if (options.providers) {
+			progress("populating bdc_provider from the provider list (decision 6 — lossy denormalization, see schema.ts)")
+
+			providersPopulated = await populateBDCProviderTable(
+				kdb,
+				options.providers,
+				options.filerDB,
+				options.primaryFRNAsOf ?? options.asOfDate
+			)
 
-		batch++
+			progress(`bdc_provider: ${providersPopulated.toLocaleString()} provider(s) populated`)
+		}
 
-		if (batch >= STAGE_BATCH_SIZE) {
-			db.exec("COMMIT")
-			db.exec("BEGIN")
-			batch = 0
+		progress("finalize: ANALYZE + VACUUM")
+		db.exec("ANALYZE")
+		// page_size MUST be set right before VACUUM — node:sqlite initializes the file at the 4096 default on
+		// `new DatabaseSync`, so the earlier pragma is a no-op until a VACUUM rebuilds at the new size (build-poi.ts's
+		// same discipline).
+		db.exec("PRAGMA page_size=8192")
+		db.exec("VACUUM")
+		await kdb.destroy()
+
+		result = {
+			out: options.out,
+			rows: inserted,
+			deduped,
+			providers: providers.size,
+			coverageCells: coverageCells.length,
+			unknownGeoids,
+			providersPopulated,
+		}
+	} catch (error) {
+		// A mid-build throw must not leak the handle or orphan the staging file. The original error
+		// always wins over anything the cleanup itself throws.
+		try {
+			await kdb.destroy()
+		} catch {
+			// The handle may already be closed or mid-statement — nothing more to release.
 		}
-	}
 
-	db.exec("COMMIT")
-
-	progress(
-		`materialized ${inserted.toLocaleString()} row(s) across ${providers.size} provider(s) ` +
-			`(${unknownGeoids.toLocaleString()} unknown geoid(s) skipped)`
-	)
-
-	await kdb.schema.dropTable("bdc_stage").execute()
-
-	progress("geoid index (index-after-load — see schema.ts)")
-	await createBDCGeoidIndex(kdb)
-
-	// Coverage is SOURCE-LEVEL, not survey completeness — same convention build-poi.ts documents: a res-6 cell we
-	// have availability rows in is recorded at completeness 1.0. A cell absent from `layer_coverage` means no rows
-	// were observed there at all (the meaning-of-zero rule — missing = unknown, never `{completeness: 0}`).
-	const coverageCells = [...coverage.entries()].map(([h3Cell, observedRows]) => ({
-		h3Cell,
-		completeness: 1,
-		observedRows,
-	}))
-
-	await writeLayerCoverage(asContractDB(kdb), coverageCells)
-
-	progress("writing layer manifest")
-
-	await writeLayerManifest(asContractDB(kdb), {
-		name: "bdc",
-		version: options.asOfDate,
-		schemaVersion: 1,
-		tier: LayerTier.Shipped,
-		license: "public-domain",
-		attribution: BDC_ATTRIBUTION,
-		source: "fcc-bdc",
-		sourceVintage: options.asOfDate,
-		buildCmd: "mailwoman gazetteer build bdc",
-		buildSHA: options.buildSHA,
-		freshnessPolicy: LayerFreshnessPolicy.VersionedRefresh,
-		spineKeys: { h3: { column: "h3_cell", resolution: BDC_H3_RESOLUTION }, wofID: "wof_id" },
-		createdAt: new Date().toISOString(),
-	})
-
-	// bdc_provider population (2a decision 8 / 3a decision 6) — entirely additive and gated behind
-	// `options.providers`: when absent, this block never runs and `bdc_provider` stays empty (see
-	// `BuildBDCOptions.providers`'s docstring for the default-path guarantee).
-	let providersPopulated = 0
-
-	if (options.providers) {
-		progress("populating bdc_provider from the provider list (decision 6 — lossy denormalization, see schema.ts)")
-
-		providersPopulated = await populateBDCProviderTable(
-			kdb,
-			options.providers,
-			options.filerDB,
-			options.primaryFRNAsOf ?? options.asOfDate
-		)
+		rmSync(buildingPath, { force: true })
 
-		progress(`bdc_provider: ${providersPopulated.toLocaleString()} provider(s) populated`)
+		throw error
 	}
 
-	progress("finalize: ANALYZE + VACUUM")
-	db.exec("ANALYZE")
-	// page_size MUST be set right before VACUUM — node:sqlite initializes the file at the 4096 default on
-	// `new DatabaseSync`, so the earlier pragma is a no-op until a VACUUM rebuilds at the new size (build-poi.ts's
-	// same discipline).
-	db.exec("PRAGMA page_size=8192")
-	db.exec("VACUUM")
-	await kdb.destroy()
-
 	progress("seal")
 	sealDatabase(buildingPath)
 
-	// Atomic move-into-place — the previous version is moved ASIDE FIRST, per the AGENTS.md database house rule
-	// ("build successfully, then move the previous version to a temp directory, and then move the new version into
-	// place"). Mirrors `mailwoman/eval-harness/gauntlet/build-regression-db.ts`'s `${output}.prev` swap. Deliberate
-	// deviation from `build-poi.ts`'s direct-write — see the module docstring.
-	if (existsSync(options.out)) {
-		renameSync(options.out, `${options.out}.prev`)
-	}
-
-	renameSync(buildingPath, options.out)
-
-	if (existsSync(`${options.out}.prev`)) {
-		rmSync(`${options.out}.prev`)
-	}
+	// Atomic move-into-place via the shared helper (the AGENTS.md database house rule): prior
+	// version aside first, forward rename restored on failure so the slot is never left empty.
+	swapDatabaseIntoPlace(buildingPath, options.out)
 
-	return {
-		out: options.out,
-		rows: inserted,
-		deduped,
-		providers: providers.size,
-		coverageCells: coverageCells.length,
-		unknownGeoids,
-		providersPopulated,
-	}
+	return result
 }