@mailwoman/bdc 9.0.0 → 9.2.0

package/out/sdk/build-bdc.d.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:
  *
@@ -181,11 +180,18 @@ export interface BuildBDCResult {
  */
 export declare function peekProviderID(csvBuffer: Buffer, csvPath?: string): 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 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).
  */

package/out/sdk/build-bdc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-bdc.d.ts","sourceRoot":"","sources":["../../sdk/build-bdc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAOH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAY9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAKrD,OAAO,KAAK,EAAO,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAchE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAQ5E;;;GAGG;AACH,eAAO,MAAM,eAAe,QAEqF,CAAA;AAEjH,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAA;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAA;IACtE;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;IACvC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAA;CAC1B;AAsDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CA+B9E;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAkCtG;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC7C,WAAW,EAAE,MAAM,GACjB,CAAC,KAAK,EAAE,MAAM,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS7D;AAmHD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA6RxF"}
+{"version":3,"file":"build-bdc.d.ts","sourceRoot":"","sources":["../../sdk/build-bdc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAOH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAY9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAKrD,OAAO,KAAK,EAAO,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAchE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAQ5E;;;GAGG;AACH,eAAO,MAAM,eAAe,QAEqF,CAAA;AAEjH,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAA;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAA;IACtE;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;IACvC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAA;CAC1B;AA4CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CA+B9E;AAwDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA8DtG;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC7C,WAAW,EAAE,MAAM,GACjB,CAAC,KAAK,EAAE,MAAM,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS7D;AAmHD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuTxF"}

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,18 @@
  *      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 { 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 { createLayerCoverageTable, createLayerManifestTable, LayerFreshnessPolicy, LayerTier, writeLayerCoverage, writeLayerManifest, } from "@mailwoman/core/layers";
+import { CoverageBasis, createLayerCoverageTable, createLayerManifestTable, LayerFreshnessPolicy, LayerTier, writeLayerCoverage, writeLayerManifest, } 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 { shortCellToInt } from "@mailwoman/spatial";
 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 { readAvailabilityRows } from "./parsing.js";
 /**
  * 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 +72,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
@@ -145,24 +135,54 @@ 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
+ * 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) {
+    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) {
     for (const csvPath of csvPaths) {
-        const buffer = await readFile(csvPath);
-        const providerID = peekProviderID(buffer, csvPath);
-        yield* takeAvailabilityLine(buffer, providerID);
+        const providerID = peekProviderID(await readCSVHead(csvPath), 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 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).
  */
@@ -177,18 +197,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;
@@ -313,185 +356,206 @@ export async function buildBDCDatabase(options) {
         rmSync(buildingPath);
     }
     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 = options.rows ?? readAvailabilityRowsFromCSVPaths(options.csvPaths);
     const db = new DatabaseSync(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(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++;
-        batch++;
-        if (batch >= STAGE_BATCH_SIZE) {
-            db.exec("COMMIT");
-            db.exec("BEGIN");
-            batch = 0;
+        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;
+            }
         }
-    }
-    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 (
+        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 (
 			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)");
+        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;
+            }
+            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;
+            }
         }
-        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;
+        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,
+            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);
+            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 kdb.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 kdb.destroy();
+        }
+        catch {
+            // The handle may already be closed or mid-statement — nothing more to release.
+        }
+        rmSync(buildingPath, { force: true });
+        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,
-    };
+    // 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 result;
 }
 //# sourceMappingURL=build-bdc.js.map