@mailwoman/bdc 9.1.0 → 9.3.0

package/{sdk → lib/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,32 +50,33 @@
  *      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 { DatabaseSync } from "node:sqlite"
-
-import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import { pathExists, readDirectory, readFileRange } from "@mailwoman/core/fs/readers"
+import { removePathIfPresent, movePath, makeDirectories, removePath } from "@mailwoman/core/fs/writers"
+import { tryParsingJSON } from "@mailwoman/core/json"
 import {
 	createLayerCoverageTable,
 	createLayerManifestTable,
 	LayerFreshnessPolicy,
 	LayerTier,
+	sourcePresentCoverageCells,
 	writeLayerCoverage,
 	writeLayerManifest,
-	type LayerContractDatabase,
 } from "@mailwoman/core/layers"
-import { tryParsingJSON } from "@mailwoman/core/objects"
-import { openBuiltDatabase, sealDatabase } from "@mailwoman/core/utils"
 import type { FilerDatabase } from "@mailwoman/filer"
-// `pickPrimaryFRN`/`readFRNFilingCandidates` are loaded via a LAZY `await import("@mailwoman/filer/sdk")`
+// `pickPrimaryFRN`/`readFRNFilingCandidates` are loaded via a LAZY `await import("@mailwoman/filer/filer-lookup")`
 // inside `populateBDCProviderTable`, not a top-level runtime import — see that function's docstring
-//. Only the TYPES are imported here; `import type` is fully erased, so
-// this line has zero runtime cost for every `@mailwoman/bdc` consumer that never populates providers.
-import type { FRN, ProviderListRow } from "@mailwoman/filer/sdk"
+//
+// Only the TYPES are imported here; `import type` is fully erased.
+import type { FRN } from "@mailwoman/filer/frn"
+import type { ProviderListRow } from "@mailwoman/filer/sdk"
 import { shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { beginBatched } from "@mailwoman/sqlite/batched"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { openBuiltClient } from "@mailwoman/sqlite/sealed"
+import { sealDatabase, swapDatabaseIntoPlace } from "@mailwoman/sqlite/sealed-db"
 import { cellToParent, latLngToCell } from "h3-js"
 import type { Insertable, Kysely } from "kysely"
+import { basename, dirname, join } from "path-ts"
 
 import {
 	BDC_COVERAGE_H3_RESOLUTION,
@@ -86,9 +86,9 @@ import {
 	createBDCProviderTable,
 	type BDCDatabase,
 	type BDCProviderTable,
-} from "../schema.ts"
-import type { ProviderID } from "./common.ts"
-import { takeAvailabilityLine, type BDCAvailabilityRow } from "./parsing.ts"
+} from "#schema"
+import type { ProviderID } from "#sdk/common"
+import { readAvailabilityRows, type BDCAvailabilityRow } from "#sdk/parsing"
 
 /**
  * Rows committed per `BEGIN`/`COMMIT` batch during both the staging load and the materialize pass — matches
@@ -106,8 +106,8 @@ export const BDC_ATTRIBUTION =
 
 export interface BuildBDCOptions {
 	/**
-	 * Injected row source — the test seam (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored and no
-	 * filesystem read happens.
+	 * Injected row source — the TEST INJECTION POINT (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored
+	 * and no filesystem read happens.
 	 */
 	rows?: Iterable<BDCAvailabilityRow> | AsyncIterable<BDCAvailabilityRow>
 	/**
@@ -139,15 +139,15 @@ export interface BuildBDCOptions {
 	 * Resolve a 15-char census block GEOID to its centroid. Injected so tests supply a small fixture `Map` lookup instead
 	 * of touching a real TIGER database; the real (CLI-wired) implementation is
 	 * {@linkcode createTIGERBlockCentroidLookup}, which reads `tabblock20.GEOID` (uppercase — `TIGERBlockTable`) block
-	 * geometry. Returning `undefined` for an unknown geoid is load-bearing: the materialize pass counts it in
-	 * `unknownGeoids` and skips the row — it must NEVER guess a cell.
+	 * geometry. Returning `undefined` for an unknown geoid is required: the materialize pass counts it in `unknownGeoids`
+	 * and skips the row — it must NEVER guess a cell.
 	 */
 	blockCentroids: (geoid: string) => { lat: number; lon: number } | undefined
 	onProgress?: (message: string) => void
 	/**
-	 * Provider-list rows ({@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI seam for
-	 * populating `bdc_provider` (2a decision 8 / 3a decision 6). When ABSENT (the default), `bdc_provider` stays empty
-	 * and the rest of the build is untouched: every code path this option touches is gated behind `if
+	 * Provider-list rows ({@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI injection
+	 * point for populating `bdc_provider` (2a decision 8 / 3a decision 6). When ABSENT (the default), `bdc_provider`
+	 * stays empty and the rest of the build is untouched: every code path this option touches is conditioned behind `if
 	 * (options.providers)`, so omitting it changes nothing. When present, `buildBDCDatabase` groups rows by `providerID`
 	 * and inserts one `bdc_provider` row per distinct provider — see {@link BuildBDCOptions.filerDB} for how the primary
 	 * FRN is picked when a provider carries more than one, and `schema.ts`'s `BDCProviderTable` docstring for the full
@@ -206,16 +206,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
@@ -268,7 +258,7 @@ interface BDCStageRow {
  *
  * `csvPath` is optional and used ONLY to name the offending file in a thrown error (the direct-buffer unit tests call
  * this without one; {@linkcode readAvailabilityRowsFromCSVPaths} always supplies it). The `Number.isSafeInteger` guard
- * below is load-bearing, not defensive dressing: `bdc_stage.provider_id` is `INTEGER NOT NULL`, and a bare
+ * below is required, not defensive dressing: `bdc_stage.provider_id` is `INTEGER NOT NULL`, and a bare
  * `Number.parseInt` on a non-numeric field (a malformed/re-headered/truncated CSV) silently produces `NaN`. `NaN` binds
  * to that NOT NULL column as SQLite `NULL`, `INSERT OR IGNORE` then drops the row without a constraint error, and every
  * dropped row gets counted as `deduped` — the ENTIRE file's rows vanish silently, misreported as ordinary dedup. A
@@ -308,17 +298,26 @@ 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
- * 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`.
+ * 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.
+ *
+ * `provider_id` is a constant per file, so establishing it needs the first data row and nothing else; a whole-file read
+ * was resident-loading 920 MB (one state × technology) to read one column of one row.
+ */
+const PROVIDER_ID_PEEK_BYTES = 64 * 1024
+
+/**
+ * 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 INJECTION POINT's injected `rows` — exercised by `build-bdc.test.ts` only for the
+ * malformed-provider-id rejection path, same as `build-poi.ts`'s Parquet reader.
  */
 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 readFileRange(csvPath, 0, PROVIDER_ID_PEEK_BYTES), csvPath)
 
-		yield* takeAvailabilityLine(buffer, providerID)
+		yield* readAvailabilityRows(csvPath, providerID)
 	}
 }
 
@@ -336,11 +335,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 version'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 +364,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
+
+		for (let i = 0; i < ring.length - 1; i++) {
+			const [x1, y1] = ring[i]!
+			const [x2, y2] = ring[i + 1]!
 
-			if (typeof lon !== "number" || typeof lat !== "number") continue
+			if (typeof x1 !== "number" || typeof y1 !== "number" || typeof x2 !== "number" || typeof y2 !== "number") {
+				continue
+			}
 
-			sumLon += lon
-			sumLat += lat
+			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
@@ -382,16 +416,17 @@ export function geometryCentroid(geometryJSON: string | null): { lat: number; lo
 
 /**
  * The production `blockCentroids` supplier: opens the TIGER blocks database READ-ONLY and probes `tabblock20.GEOID`
- * (uppercase) per lookup, decoding its GeoJSON `geometry` column via {@linkcode geometryCentroid}. Kept synchronous —
- * `BuildBDCOptions.blockCentroids` is a plain sync function (the same sync-by-interface discipline AGENTS.md documents
- * for the resolver ladder), so this uses `node:sqlite`'s raw `.prepare()`/`.get()` directly rather than Kysely. The
- * connection is left open for the caller's process lifetime (a read-path lookup, not a build) — same lifecycle as the
- * resolver-wof-sqlite lookups.
+ * (uppercase) per lookup, decoding its GeoJSON `geometry` column via {@linkcode geometryCentroid}. The factory awaits
+ * its read-only open; the per-lookup probe and the `BuildBDCOptions.blockCentroids` interface stay synchronous — a
+ * plain sync function (the same sync-by-interface discipline AGENTS.md documents for the resolver ladder), so the
+ * returned closure uses `node:sqlite`'s raw `.prepare()`/`.get()` directly rather than Kysely. The connection is left
+ * open for the caller's process lifetime (a read-path lookup, not a build) — same lifecycle as the resolver-wof-sqlite
+ * lookups.
  */
-export function createTIGERBlockCentroidLookup(
+export async function createTIGERBlockCentroidLookup(
 	tigerDBPath: string
-): (geoid: string) => { lat: number; lon: number } | undefined {
-	const db = openBuiltDatabase(tigerDBPath)
+): Promise<(geoid: string) => { lat: number; lon: number } | undefined> {
+	const db = await openBuiltClient(tigerDBPath)
 	const stmt = db.prepare("SELECT geometry FROM tabblock20 WHERE GEOID = ?")
 
 	return (geoid: string) => {
@@ -454,15 +489,18 @@ async function groupProviderListRows(
  * `brand_name` is always inserted NULL — the provider list carries no brand-name column at all, so there is nothing to
  * populate it from, primary or otherwise (see the schema docstring).
  *
- * **Lazy `@mailwoman/filer/sdk` import.** `readFRNFilingCandidates`/`pickPrimaryFRN` are loaded via `await
- * import("@mailwoman/filer/sdk")`, memoized in `filerSDK` below, rather than a top-level static import — that barrel
- * re-exports `cluster-filers.ts`, which pulls in `@mailwoman/match`/`record`/`registry`. A top-level import regressed
- * `@mailwoman/bdc`'s import time ~32% for EVERY consumer, including ones that never populate providers at all; the
- * dynamic import here only ever runs when a multi-FRN `provider_id` is actually encountered, so a `providers`-less
- * build (or one whose providers are all single-FRN) pays nothing.
+ * **Lazy `@mailwoman/filer/filer-lookup` import.** `readFRNFilingCandidates`/`pickPrimaryFRN` are loaded via `await
+ * import("@mailwoman/filer/filer-lookup")`, memoized in `filerSDK` below, rather than a top-level static import. The
+ * cost this avoids is smaller than it was: the specifier used to be the `@mailwoman/filer/sdk` BARREL, which `export
+ * *`s `cluster-filers.ts` and so pulls `@mailwoman/match`/`record`/`registry` in behind it — a top-level import of that
+ * barrel regressed `@mailwoman/bdc`'s import time ~32% for EVERY consumer, including ones that never populate
+ * providers. `filer-lookup.ts` alone imports only `@mailwoman/sqlite/client`, `#schema` and `#frn` (measured
+ * 2026-09-01), so the heavy graph is no longer on this path at all. The laziness is kept because it also defers opening
+ * the filer database, and a static import here is now a viable simplification if someone wants to measure it — but it
+ * is no longer load-bearing for import time.
  */
 async function populateBDCProviderTable(
-	kdb: DatabaseClient<BDCDatabase>,
+	db: DatabaseClient<BDCDatabase>,
 	providers: Iterable<ProviderListRow> | AsyncIterable<ProviderListRow>,
 	filerDB: DatabaseClient<FilerDatabase> | undefined,
 	asOf: string
@@ -470,7 +508,7 @@ async function populateBDCProviderTable(
 	const byProviderID = await groupProviderListRows(providers)
 	const insertRows: Insertable<BDCProviderTable>[] = []
 
-	let filerSDK: typeof import("@mailwoman/filer/sdk") | undefined
+	let filerSDK: typeof import("@mailwoman/filer/filer-lookup") | undefined
 
 	for (const [providerID, rows] of byProviderID) {
 		const distinctFRNs = [...new Set(rows.map((row) => row.frn))]
@@ -488,7 +526,7 @@ async function populateBDCProviderTable(
 				)
 			}
 
-			filerSDK ??= await import("@mailwoman/filer/sdk")
+			filerSDK ??= await import("@mailwoman/filer/filer-lookup")
 
 			const candidates = await filerSDK.readFRNFilingCandidates(filerDB, distinctFRNs, asOf)
 
@@ -505,7 +543,7 @@ async function populateBDCProviderTable(
 	}
 
 	for (let index = 0; index < insertRows.length; index += PROVIDER_INSERT_BATCH_SIZE) {
-		await kdb
+		await db
 			.insertInto("bdc_provider")
 			.values(insertRows.slice(index, index + PROVIDER_INSERT_BATCH_SIZE))
 			.execute()
@@ -530,278 +568,285 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 
 	const buildingPath = `${options.out}.building`
 
-	if (existsSync(buildingPath)) {
-		rmSync(buildingPath)
+	if (await pathExists(buildingPath)) {
+		await removePath(buildingPath)
 	}
 
-	mkdirSync(dirname(options.out), { recursive: true })
+	await makeDirectories(dirname(options.out))
+
+	// 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 (!(await pathExists(options.out))) {
+		const base = basename(options.out)
+
+		const parked = (await readDirectory(dirname(options.out))).find(
+			(name) => name === `${base}.prev` || name.startsWith(`${base}.old-`)
+		)
+
+		if (parked) {
+			await movePath(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!)
 
-	const db = new DatabaseSync(buildingPath)
+	const db = new DatabaseClient<BDCDatabase>(buildingPath)
 	// Build-tuning pragmas — identical to build-poi.ts's discipline.
 	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(db)
+		await createLayerCoverageTable(db)
+		await createBDCAvailabilityTable(db)
+		await createBDCProviderTable(db)
+		await createBDCStageTable(db)
+
+		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
 
-		batch++
+		progress("staging rows — raw prepared INSERT OR IGNORE on the natural key (the Redis-dedup replacement)")
 
-		if (batch >= STAGE_BATCH_SIZE) {
-			db.exec("COMMIT")
-			db.exec("BEGIN")
-			batch = 0
-		}
-	}
+		const stageBatch = beginBatched(db, { rowsPerCommit: STAGE_BATCH_SIZE })
 
-	db.exec("COMMIT")
+		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
+			)
 
-	const stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get() as {
-		staged_count: number
-	}
+			staged++
 
-	const deduped = staged - stagedCountRow.staged_count
+			stageBatch.rowWritten()
+		}
 
-	progress(
-		`staged ${stagedCountRow.staged_count.toLocaleString()} distinct row(s), ${deduped.toLocaleString()} deduped`
-	)
+		stageBatch.commit()
 
-	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 stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get() as {
+			staged_count: number
+		}
+
+		const deduped = staged - stagedCountRow.staged_count
+
+		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)
-		}
+		progress(
+			"materializing bdc_availability — resolving block centroids to h3_cell (unknown geoids skipped, never guessed)"
+		)
 
-		if (!resolved) {
-			unknownGeoids++
+		const materializeBatch = beginBatched(db, { rowsPerCommit: STAGE_BATCH_SIZE })
+
+		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)
+			}
 
-			continue
-		}
+			if (!resolved) {
+				unknownGeoids++
 
-		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
-		)
+				continue
+			}
 
-		inserted++
-		providers.add(row.provider_id)
-		coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1)
+			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
+			)
 
-		batch++
+			inserted++
+			providers.add(row.provider_id)
+			coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1)
 
-		if (batch >= STAGE_BATCH_SIZE) {
-			db.exec("COMMIT")
-			db.exec("BEGIN")
-			batch = 0
+			materializeBatch.rowWritten()
 		}
-	}
 
-	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
+		materializeBatch.commit()
+
+		progress(
+			`materialized ${inserted.toLocaleString()} row(s) across ${providers.size} provider(s) ` +
+				`(${unknownGeoids.toLocaleString()} unknown geoid(s) skipped)`
 		)
 
-		progress(`bdc_provider: ${providersPopulated.toLocaleString()} provider(s) populated`)
-	}
+		await db.schema.dropTable("bdc_stage").execute()
+
+		progress("geoid index (index-after-load — see schema.ts)")
+		await createBDCGeoidIndex(db)
+
+		// 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 = sourcePresentCoverageCells(coverage)
+
+		await writeLayerCoverage(db, coverageCells)
+
+		progress("writing layer manifest")
+
+		await writeLayerManifest(db, {
+			name: "bdc",
+			version: options.asOfDate,
+			schemaVersion: 1,
+			tier: LayerTier.Shipped,
+			license: "LicenseRef-USGov-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 conditioned on
+		// `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(
+				db,
+				options.providers,
+				options.filerDB,
+				options.primaryFRNAsOf ?? options.asOfDate
+			)
 
-	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(`bdc_provider: ${providersPopulated.toLocaleString()} provider(s) populated`)
+		}
 
-	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`)
-	}
+		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 db.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 db.destroy()
+		} catch {
+			// The handle may already be closed or mid-statement — nothing more to release.
+		}
 
-	renameSync(buildingPath, options.out)
+		await removePathIfPresent(buildingPath)
 
-	if (existsSync(`${options.out}.prev`)) {
-		rmSync(`${options.out}.prev`)
+		throw error
 	}
 
-	return {
-		out: options.out,
-		rows: inserted,
-		deduped,
-		providers: providers.size,
-		coverageCells: coverageCells.length,
-		unknownGeoids,
-		providersPopulated,
-	}
+	progress("seal")
+	await sealDatabase(buildingPath)
+
+	// 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.
+	await swapDatabaseIntoPlace(buildingPath, options.out)
+
+	return result
 }