@mailwoman/bdc 8.3.0

package/out/sdk/build-bdc.js

@@ -0,0 +1,500 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The `bdc.db` builder (2a Task 8) — ingests parsed FCC BDC availability rows (Task 6's
+ *   {@link BDCAvailabilityRow}) into Task 7's schema (`schema.ts`), producing a sealed layer database.
+ *
+ *   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.
+ *
+ *   Two differences from that precedent, both deliberate:
+ *
+ *   1. **A staging-dedup pass.** BDC's per-provider CSVs can carry exact-duplicate rows (repeat
+ *      filings, overlapping re-downloads); poi's Overture rows never needed this. `bdc_stage` is a
+ *      plain Kysely-built table (not part of the public {@link BDCDatabase} — it never survives to the
+ *      sealed artifact) carrying a composite PRIMARY KEY on the natural key
+ *      `(geoid, provider_id, technology_code, location_id)`. Rows load via a RAW prepared
+ *      `INSERT OR IGNORE` — the AGENTS.md "hot bulk write" carve-out, same discipline as the
+ *      candidate-gazetteer builder — which is the direct replacement for the Redis
+ *      set-membership check Nexus's `sync/commands/bdc/infer-locations.ts` used for this exact
+ *      dedup (dedup semantics only; Nexus's Redis-backed location inference itself has no analog
+ *      here). `h3_cell` is computed only AFTER staging, per distinct geoid, against the deduped set —
+ *      so a duplicate row is never charged twice against `unknownGeoids` or `layer_coverage` either.
+ *      The natural key's `location_id` component means the SAME (geoid, provider_id, technology_code)
+ *      triple legitimately survives staging once per distinct BSL — correct when `includeLocationIDs`
+ *      is true. The default (NULL `location_id`) mode collapses at MATERIALIZE time via `SELECT DISTINCT`
+ *      over every column EXCEPT `location_id` — that is, to one row per distinct (geoid, provider_id,
+ *      technology_code, max_advertised_download_speed, max_advertised_upload_speed, low_latency,
+ *      business_residential_code) TUPLE, NOT one row per (geoid, provider_id, technology_code) triple.
+ *      When every BSL in a block shares identical speeds/flags for a given provider/technology (the
+ *      common case), those two are the same thing and the collapse yields exactly one row per triple.
+ *      But when BSLs at the SAME triple carry DIFFERENT speeds/flags (a real, accepted FCC filing
+ *      pattern — a provider filing different advertised speeds at different addresses in one block),
+ *      the distinct rows survive collapse as multiple NULL-`location_id` rows at that one triple. This
+ *      is deliberate, matches the FCC source data's own granularity, and is NOT a bug to fix — see
+ *      `filing-landscape.ts`'s module docstring for the read-side consequence (the same provider/tech
+ *      can surface in more than one `speed_bucket` for one queried block).
+ *   2. **Temp-path build + move-aside-first swap**, per AGENTS.md's database house rule ("build
+ *      successfully, then move the previous version to a temp directory, and then move the new
+ *      version into place... ensures the database is always in a consistent state, even if the build
+ *      script fails halfway through"): build lands at `${out}.building`, seals there, then
+ *      `${out}` (if present) is renamed to `${out}.prev` BEFORE the sealed build takes its place —
+ *      mirroring `mailwoman/eval-harness/gauntlet/build-regression-db.ts`'s swap. `build-poi.ts`
+ *      instead writes `out` directly (removing any stale file first) and records ITS OWN deviation
+ *      from an even older staging-suffix convention — see that file's docstring. This builder takes
+ *      the opposite fork on purpose: a from-scratch nationwide BDC ingest is long enough that a
+ *      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 { openBuiltDatabase, sealDatabase } 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";
+/**
+ * Rows committed per `BEGIN`/`COMMIT` batch during both the staging load and the materialize pass — matches
+ * `build-poi.ts`'s `STAGE_BATCH_SIZE` discipline.
+ */
+const STAGE_BATCH_SIZE = 10_000;
+/**
+ * The manifest's `attribution` — names the FCC as the source, then copies the Fabric-boundary sentence verbatim from
+ * `bdc/README.md`'s "CostQuest Fabric boundary" section (backticks stripped — this is plain prose, not markdown).
+ */
+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
+ * the AGENTS.md DDL convention (`createTable` takes any string table name — it doesn't need to be a `keyof DB` to
+ * type-check); all of `bdc_stage`'s actual reads/writes below go through raw `.prepare()` on the shared `DatabaseSync`
+ * instead, per the "hot bulk write" carve-out.
+ *
+ * The composite PRIMARY KEY on the natural key is what makes `INSERT OR IGNORE` a dedup: SQLite silently drops any
+ * insert whose key already exists rather than raising the constraint violation.
+ */
+async function createBDCStageTable(db) {
+    await db.schema
+        .createTable("bdc_stage")
+        .addColumn("geoid", "text", (c) => c.notNull())
+        .addColumn("provider_id", "integer", (c) => c.notNull())
+        .addColumn("technology_code", "integer", (c) => c.notNull())
+        .addColumn("location_id", "text", (c) => c.notNull())
+        .addColumn("max_advertised_download_speed", "integer", (c) => c.notNull())
+        .addColumn("max_advertised_upload_speed", "integer", (c) => c.notNull())
+        .addColumn("low_latency", "integer", (c) => c.notNull())
+        .addColumn("business_residential_code", "text", (c) => c.notNull())
+        .addPrimaryKeyConstraint("bdc_stage_pk", ["geoid", "provider_id", "technology_code", "location_id"])
+        .execute();
+}
+/**
+ * Peek the constant `provider_id` column (index 1) off an FCC BDC availability CSV's first data row.
+ *
+ * Production per-provider files carry the SAME `provider_id` in every row (the FCC partitions availability files per
+ * provider) — `parsing.ts`'s `takeAvailabilityLine` already assumes this, taking `providerID` as a parameter rather
+ * than re-slicing column 1 per row. This reads it once, directly off the raw bytes, rather than threading a parallel
+ * `providerID` array alongside `csvPaths` through the public options shape.
+ *
+ * `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
+ * `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
+ * malformed CSV must be loud, never silently absorbed, so this throws instead.
+ */
+export function peekProviderID(csvBuffer, csvPath) {
+    const headerEnd = csvBuffer.indexOf(0x0a);
+    const fileSuffix = csvPath ? ` (${csvPath})` : "";
+    if (headerEnd === -1) {
+        throw new Error(`peekProviderID: no newline found — empty or header-only CSV buffer${fileSuffix}`);
+    }
+    const nextNewline = csvBuffer.indexOf(0x0a, headerEnd + 1);
+    const firstDataLine = csvBuffer
+        .subarray(headerEnd + 1, nextNewline === -1 ? undefined : nextNewline)
+        .toString("ascii");
+    const providerIDField = firstDataLine.split(",")[1];
+    if (!providerIDField) {
+        throw new Error(`peekProviderID: could not read provider_id (column 1) from the first data row${fileSuffix}`);
+    }
+    const providerID = Number.parseInt(providerIDField, 10);
+    if (!Number.isSafeInteger(providerID)) {
+        throw new TypeError(`peekProviderID: provider_id column (1) did not parse to a safe integer — got ${JSON.stringify(providerIDField)}` +
+            `${fileSuffix}. Refusing to silently drop this file's rows: an unguarded NaN binds to bdc_stage.provider_id ` +
+            `(INTEGER NOT NULL) as SQLite NULL, and INSERT OR IGNORE would then discard every row uncounted as ordinary dedup.`);
+    }
+    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`.
+ */
+async function* readAvailabilityRowsFromCSVPaths(csvPaths) {
+    for (const csvPath of csvPaths) {
+        const buffer = await readFile(csvPath);
+        const providerID = peekProviderID(buffer, csvPath);
+        yield* takeAvailabilityLine(buffer, 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.
+ *
+ * Returns `undefined` for anything that doesn't parse as one of the two geometry types (including `null` geometry).
+ */
+export function geometryCentroid(geometryJSON) {
+    if (!geometryJSON)
+        return undefined;
+    let geometry;
+    try {
+        geometry = JSON.parse(geometryJSON);
+    }
+    catch {
+        return undefined;
+    }
+    const exteriorRings = geometry.type === "Polygon"
+        ? [geometry.coordinates[0] ?? []]
+        : geometry.type === "MultiPolygon"
+            ? geometry.coordinates.map((polygon) => polygon[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")
+                continue;
+            sumLon += lon;
+            sumLat += lat;
+            count++;
+        }
+    }
+    if (count === 0)
+        return undefined;
+    return { lat: sumLat / count, lon: sumLon / count };
+}
+/**
+ * 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.
+ */
+export function createTIGERBlockCentroidLookup(tigerDBPath) {
+    const db = openBuiltDatabase(tigerDBPath);
+    const stmt = db.prepare("SELECT geometry FROM tabblock20 WHERE GEOID = ?");
+    return (geoid) => {
+        const row = stmt.get(geoid);
+        return row ? geometryCentroid(row.geometry) : undefined;
+    };
+}
+/**
+ * Rows per `INSERT` batch when populating `bdc_provider`. Far smaller than {@link STAGE_BATCH_SIZE}: that constant
+ * tunes `bdc_availability`'s multi-million-row raw-prepared-statement path, whereas `bdc_provider` is a small
+ * per-provider dictionary (thousands of rows, not millions) inserted through Kysely's typed `insertInto` — this batches
+ * only to stay comfortably under SQLite's bound-parameter ceiling, not for throughput.
+ */
+const PROVIDER_INSERT_BATCH_SIZE = 500;
+/**
+ * Groups `providers` by `providerID`. Task 3's `parseProviderList` yields one {@link ProviderListRow} PER LINE of the
+ * source CSV, preserving cardinality (never folded, never last-wins — see that module's docstring) — so a `provider_id`
+ * appearing on N rows arrives here as N separate rows, exactly as decision 6 requires downstream.
+ */
+async function groupProviderListRows(providers) {
+    const byProviderID = new Map();
+    for await (const row of providers) {
+        const rows = byProviderID.get(row.providerID);
+        if (rows) {
+            rows.push(row);
+        }
+        else {
+            byProviderID.set(row.providerID, [row]);
+        }
+    }
+    return byProviderID;
+}
+/**
+ * Populate `bdc_provider` from `options.providers` (2a decision 8 / 3a decision 6, Task 8) — see `schema.ts`'s
+ * `BDCProviderTable` docstring for the full lossy-denormalization rationale. For each distinct `provider_id`:
+ *
+ * - Exactly one `frn` among its rows → that FRN is primary by construction; no `filerDB` query needed at all.
+ * - More than one distinct `frn` → `readFRNFilingCandidates` (`@mailwoman/filer/sdk`, lazily imported — see below) reads
+ *   each FRN's own most recent IN-FORCE `form-499` filing edge from `filerDB`, `asOf` the given date, and
+ *   `pickPrimaryFRN` picks the winner (decision 6: most recent 499 filing date wins). A `provider_id` whose FRNs carry
+ *   NO 499 filing to rank by inserts `frn: NULL` rather than guessing — `pickPrimaryFRN` throws on empty input, so this
+ *   checks `candidates.length` first, mirroring `filerLookup`'s own `primary_frn: null` handling of the same case.
+ * - `filerDB` is REQUIRED the instant a multi-FRN `provider_id` is encountered; its absence throws immediately, naming
+ *   the offending `provider_id`, rather than silently picking an arbitrary FRN.
+ * - `holding_company` gets the IDENTICAL single-distinct-value shortcut `frn` gets (review fix round 1, IMPORTANT-3):
+ *   exactly one distinct non-null `holdingCompany` across a provider's rows means there's no conflict to resolve, so
+ *   it's populated directly, no rule needed. Two or more distinct values IS the real conflict decision 6 refuses to
+ *   paper over with last-wins — that case inserts NULL, and every value stays recoverable from `filer.db`. A `null`
+ *   `holdingCompany` on some rows doesn't count as a competing value (a row simply not stating it isn't a conflicting
+ *   assertion) — only distinct NON-NULL strings are compared.
+ *
+ * `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 (review fix round 1, IMPORTANT-1).** `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.
+ */
+async function populateBDCProviderTable(kdb, providers, filerDB, asOf) {
+    const byProviderID = await groupProviderListRows(providers);
+    const insertRows = [];
+    let filerSDK;
+    for (const [providerID, rows] of byProviderID) {
+        const distinctFRNs = [...new Set(rows.map((row) => row.frn))];
+        let frn;
+        if (distinctFRNs.length === 1) {
+            frn = distinctFRNs[0];
+        }
+        else {
+            if (!filerDB) {
+                throw new Error(`buildBDCDatabase: provider_id ${providerID} carries ${distinctFRNs.length} distinct FRNs across the ` +
+                    "provider list — resolving the primary FRN (decision 6) requires `filerDB` to be supplied " +
+                    "alongside `providers`");
+            }
+            filerSDK ??= await import("@mailwoman/filer/sdk");
+            const candidates = await filerSDK.readFRNFilingCandidates(filerDB, distinctFRNs, asOf);
+            frn = candidates.length ? filerSDK.pickPrimaryFRN(candidates) : null;
+        }
+        const distinctHoldingCompanies = [
+            ...new Set(rows.map((row) => row.holdingCompany).filter((value) => value !== null)),
+        ];
+        const holdingCompany = distinctHoldingCompanies.length === 1 ? distinctHoldingCompanies[0] : null;
+        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
+            .insertInto("bdc_provider")
+            .values(insertRows.slice(index, index + PROVIDER_INSERT_BATCH_SIZE))
+            .execute();
+    }
+    return insertRows.length;
+}
+/**
+ * Build `bdc.db`: stage (raw dedup) → materialize (resolve `h3_cell` per geoid, skip+count unknown geoids) → drop stage
+ * → geoid index (index-after-load) → coverage → layer manifest → seal → atomic move-into-place. See the module
+ * docstring for the two deliberate deviations from `build-poi.ts`.
+ */
+export async function buildBDCDatabase(options) {
+    const progress = options.onProgress ?? (() => { });
+    if (!options.rows && (!options.csvPaths || !options.csvPaths.length)) {
+        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);
+    }
+    mkdirSync(dirname(options.out), { recursive: true });
+    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 (
+			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;
+        }
+    }
+    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 (found in review, ~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,
+					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, reviewer-verified —
+                    // 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;
+        }
+    }
+    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, Task 8) — entirely additive and gated behind
+    // `options.providers`: when absent, this block never runs and `bdc_provider` stays empty, exactly as before
+    // Task 8 (see `BuildBDCOptions.providers`'s docstring — the default-path byte-identical 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();
+    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,
+    };
+}
+//# sourceMappingURL=build-bdc.js.map

package/out/sdk/build-bdc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-bdc.js","sourceRoot":"","sources":["../../sdk/build-bdc.ts"],"names":[],"mappings":"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"}

package/out/sdk/buildings.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC/NITA Building Type Codes
+ * @see https://www.fcc.gov/sites/default/files/2019-08/Building%20Type%20Code%20List.pdf
+ */
+/**
+ * Code indicating the type of building at the location.
+ *
+ * @category NTIA
+ * @category FCC
+ * @title Building Type Code
+ */
+export declare const BuildingTypeCode: {
+    /**
+     * A single-family home, apartment building, or condominium.
+     *
+     * @title Residential Building
+     */
+    readonly Residential: "R";
+    /**
+     * A office building, retail store, or warehouse.
+     *
+     * @title Non-residential Building
+     */
+    readonly NonResidential: "B";
+    /**
+     * Both residential and non-residential units.
+     *
+     * @title Mixed-use Building
+     */
+    readonly Mixed: "X";
+    /**
+     * A dormitory, nursing home, or prison.
+     *
+     * @title Group Quarters
+     */
+    readonly GroupQuarters: "G";
+    /**
+     * @title Community Anchor Institution
+     * @see {@link https://help.bdc.fcc.gov/hc/en-us/articles/13471550784411-How-to-Identify-a-Community-Anchor-Institution-as-a-Broadband-Serviceable-Location CAI Guide}
+     */
+    readonly CAI: "C";
+    /**
+     * @title Enterprise or business park.
+     */
+    readonly Enterprise: "E";
+    /**
+     * Building type not covered by the above categories.
+     *
+     * @title Other
+     */
+    readonly Other: "O";
+};
+/**
+ * @category NTIA
+ * @category FCC
+ */
+export type BuildingTypeCode = (typeof BuildingTypeCode)[keyof typeof BuildingTypeCode];
+/**
+ * Code indicating the type of building at the location.
+ *
+ * @title Business/Residential Code
+ */
+export declare const BusinessResidentialCode: {
+    /**
+     * @title Business-only service.
+     */
+    readonly Business: "B";
+    /**
+     * @title Residential-only service.
+     */
+    readonly Residential: "R";
+    /**
+     * @title Mixed business and residential service.
+     */
+    readonly Mixed: "X";
+};
+/**
+ * @title Business/Residential Code
+ */
+export type BusinessResidentialCode = (typeof BusinessResidentialCode)[keyof typeof BusinessResidentialCode];
+//# sourceMappingURL=buildings.d.ts.map

package/out/sdk/buildings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildings.d.ts","sourceRoot":"","sources":["../../sdk/buildings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC5B;;;;OAIG;;IAEH;;;;OAIG;;IAEH;;;;OAIG;;IAEH;;;;OAIG;;IAEH;;;OAGG;;IAEH;;OAEG;;IAEH;;;;OAIG;;CAEM,CAAA;AAEV;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAA;AAEvF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;IACnC;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;CAEM,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAA"}