@mailwoman/bdc 9.1.0 → 9.3.0

package/out/sdk/build-bdc.js

@@ -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:
  *
@@ -50,18 +49,19 @@
  *      mid-build crash mustn't cost the previously-good artifact, which is exactly the failure mode
  *      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 { createLayerCoverageTable, createLayerManifestTable, LayerFreshnessPolicy, LayerTier, writeLayerCoverage, writeLayerManifest, } from "@mailwoman/core/layers";
-import { tryParsingJSON } from "@mailwoman/core/objects";
-import { openBuiltDatabase, sealDatabase } from "@mailwoman/core/utils";
+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, } from "@mailwoman/core/layers";
 import { shortCellToInt } 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 { BDC_COVERAGE_H3_RESOLUTION, BDC_H3_RESOLUTION, createBDCAvailabilityTable, createBDCGeoidIndex, createBDCProviderTable, } from "../schema.js";
-import { takeAvailabilityLine } from "./parsing.js";
+import { basename, dirname, join } from "path-ts";
+import { BDC_COVERAGE_H3_RESOLUTION, BDC_H3_RESOLUTION, createBDCAvailabilityTable, createBDCGeoidIndex, createBDCProviderTable, } from "#schema";
+import { readAvailabilityRows } from "#sdk/parsing";
 /**
  * Rows committed per `BEGIN`/`COMMIT` batch during both the staging load and the materialize pass — matches
  * `build-poi.ts`'s `STAGE_BATCH_SIZE` discipline.
@@ -73,15 +73,6 @@ const STAGE_BATCH_SIZE = 10_000;
  */
 export const BDC_ATTRIBUTION = "FCC Broadband Data Collection. This workspace never ingests, ships, or derives data from the Fabric: " +
     "location_id is carried only as an opaque join key that a licensed user may join against their own Fabric copy.";
-/**
- * `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) {
-    return kdb;
-}
 /**
  * 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
@@ -116,7 +107,7 @@ async function createBDCStageTable(db) {
  *
  * `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
@@ -145,24 +136,39 @@ export function peekProviderID(csvBuffer, csvPath) {
     return 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) {
     for (const csvPath of csvPaths) {
-        const buffer = await readFile(csvPath);
-        const providerID = peekProviderID(buffer, csvPath);
-        yield* takeAvailabilityLine(buffer, providerID);
+        const providerID = peekProviderID(await readFileRange(csvPath, 0, PROVIDER_ID_PEEK_BYTES), csvPath);
+        yield* readAvailabilityRows(csvPath, providerID);
     }
 }
 /**
- * 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).
  */
@@ -177,18 +183,41 @@ export function geometryCentroid(geometryJSON) {
         : geometry.type === "MultiPolygon"
             ? 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;
-            if (typeof lon !== "number" || typeof lat !== "number")
+        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 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;
@@ -196,14 +225,15 @@ export function geometryCentroid(geometryJSON) {
 }
 /**
  * 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(tigerDBPath) {
-    const db = openBuiltDatabase(tigerDBPath);
+export async function createTIGERBlockCentroidLookup(tigerDBPath) {
+    const db = await openBuiltClient(tigerDBPath);
     const stmt = db.prepare("SELECT geometry FROM tabblock20 WHERE GEOID = ?");
     return (geoid) => {
         const row = stmt.get(geoid);
@@ -257,14 +287,17 @@ async function groupProviderListRows(providers) {
  * `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, providers, filerDB, asOf) {
+async function populateBDCProviderTable(db, providers, filerDB, asOf) {
     const byProviderID = await groupProviderListRows(providers);
     const insertRows = [];
     let filerSDK;
@@ -280,7 +313,7 @@ async function populateBDCProviderTable(kdb, providers, filerDB, asOf) {
                     "provider list — resolving the primary FRN (decision 6) requires `filerDB` to be supplied " +
                     "alongside `providers`");
             }
-            filerSDK ??= await import("@mailwoman/filer/sdk");
+            filerSDK ??= await import("@mailwoman/filer/filer-lookup");
             const candidates = await filerSDK.readFRNFilingCandidates(filerDB, distinctFRNs, asOf);
             frn = candidates.length ? filerSDK.pickPrimaryFRN(candidates) : null;
         }
@@ -291,7 +324,7 @@ async function populateBDCProviderTable(kdb, providers, filerDB, asOf) {
         insertRows.push({ provider_id: providerID, frn, brand_name: null, holding_company: holdingCompany });
     }
     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();
@@ -309,189 +342,192 @@ export async function buildBDCDatabase(options) {
         throw new Error("buildBDCDatabase: pass either `rows` (test/injected source) or `csvPaths` (per-provider availability CSVs)");
     }
     const buildingPath = `${options.out}.building`;
-    if (existsSync(buildingPath)) {
-        rmSync(buildingPath);
+    if (await pathExists(buildingPath)) {
+        await removePath(buildingPath);
+    }
+    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)`);
+        }
     }
-    mkdirSync(dirname(options.out), { recursive: true });
     const rowSource = options.rows ?? readAvailabilityRowsFromCSVPaths(options.csvPaths);
-    const db = new DatabaseSync(buildingPath);
+    const db = new DatabaseClient(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({ 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);
-    const insStage = db.prepare(`INSERT OR IGNORE INTO bdc_stage (
+    // Assigned at the end of the try — the tallies live inside its scope; the seal + swap do not.
+    let result;
+    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++;
-        batch++;
-        if (batch >= STAGE_BATCH_SIZE) {
-            db.exec("COMMIT");
-            db.exec("BEGIN");
-            batch = 0;
+        let staged = 0;
+        progress("staging rows — raw prepared INSERT OR IGNORE on the natural key (the Redis-dedup replacement)");
+        const stageBatch = beginBatched(db, { rowsPerCommit: STAGE_BATCH_SIZE });
+        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++;
+            stageBatch.rowWritten();
         }
-    }
-    db.exec("COMMIT");
-    const stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get();
-    const deduped = staged - stagedCountRow.staged_count;
-    progress(`staged ${stagedCountRow.staged_count.toLocaleString()} distinct row(s), ${deduped.toLocaleString()} deduped`);
-    const centroidCache = new Map();
-    /**
-     * 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();
-    const providers = new Set();
-    let unknownGeoids = 0;
-    let inserted = 0;
-    const insAvailability = db.prepare(`INSERT INTO bdc_availability (
+        stageBatch.commit();
+        const stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get();
+        const deduped = staged - stagedCountRow.staged_count;
+        progress(`staged ${stagedCountRow.staged_count.toLocaleString()} distinct row(s), ${deduped.toLocaleString()} deduped`);
+        const centroidCache = new Map();
+        /**
+         * 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();
+        const providers = new Set();
+        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()) {
-        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);
-                    return {
-                        h3Cell: shortCellToInt(fullRes9Cell),
-                        coverageCell: shortCellToInt(cellToParent(fullRes9Cell, BDC_COVERAGE_H3_RESOLUTION)),
-                    };
-                })()
-                : null;
-            centroidCache.set(row.geoid, resolved);
-        }
-        if (!resolved) {
-            unknownGeoids++;
-            continue;
+        progress("materializing bdc_availability — resolving block centroids to h3_cell (unknown geoids skipped, never guessed)");
+        const materializeBatch = beginBatched(db, { rowsPerCommit: STAGE_BATCH_SIZE });
+        for (const row of stageStmt.iterate()) {
+            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);
+                        return {
+                            h3Cell: shortCellToInt(fullRes9Cell),
+                            coverageCell: shortCellToInt(cellToParent(fullRes9Cell, BDC_COVERAGE_H3_RESOLUTION)),
+                        };
+                    })()
+                    : 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);
+            inserted++;
+            providers.add(row.provider_id);
+            coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1);
+            materializeBatch.rowWritten();
         }
-        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);
-        inserted++;
-        providers.add(row.provider_id);
-        coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1);
-        batch++;
-        if (batch >= STAGE_BATCH_SIZE) {
-            db.exec("COMMIT");
-            db.exec("BEGIN");
-            batch = 0;
+        materializeBatch.commit();
+        progress(`materialized ${inserted.toLocaleString()} row(s) across ${providers.size} provider(s) ` +
+            `(${unknownGeoids.toLocaleString()} unknown geoid(s) skipped)`);
+        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(`bdc_provider: ${providersPopulated.toLocaleString()} provider(s) populated`);
         }
+        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,
+        };
     }
-    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);
-        progress(`bdc_provider: ${providersPopulated.toLocaleString()} provider(s) populated`);
+    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.
+        }
+        await removePathIfPresent(buildingPath);
+        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`);
-    }
-    return {
-        out: options.out,
-        rows: inserted,
-        deduped,
-        providers: providers.size,
-        coverageCells: coverageCells.length,
-        unknownGeoids,
-        providersPopulated,
-    };
+    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;
 }
 //# sourceMappingURL=build-bdc.js.map