@mailwoman/bdc 8.3.0

package/README.md

@@ -0,0 +1,7 @@
+# @mailwoman/bdc
+
+FCC Broadband Data Collection (BDC) availability data — fetch, parse, and ingest provider data, and the `bdc.db` layer reader. See the implementation plan at `.superpowers/sdd/2026-07-30-bdc-2a-plan/` for the spec. This workspace is a **data provider** — it reads/ingests raw BDC data and produces a queryable spatial layer; it is not part of the address parser itself.
+
+## CostQuest Fabric boundary
+
+The BDC Fabric (the BSL `location_id` → rooftop point/parcel map) is CostQuest-licensed. 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. All spatial work happens at census-block granularity plus mailwoman's own address spine.

package/index.ts

@@ -0,0 +1,2 @@
+export * from "./schema.ts"
+export * from "./sdk/index.ts"

package/out/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./schema.ts";
+export * from "./sdk/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/out/index.js

@@ -0,0 +1,3 @@
+export * from "./schema.js";
+export * from "./sdk/index.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/out/schema.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for bdc.db — the FCC Broadband Data Collection availability read-side layer (2a
+ *   decisions 4, 8). `bdc_availability` holds, in the default (non-`includeLocationIDs`) build mode, one
+ *   row per DISTINCT (geoid, provider_id, technology_code, max_advertised_download_speed,
+ *   max_advertised_upload_speed, low_latency, business_residential_code) tuple parsed from the FCC's
+ *   per-provider CSV (see `sdk/parsing.ts`) — NOT one row per (block, provider, technology) triple: when
+ *   two Broadband Serviceable Locations in the same block file different speeds/flags for the same
+ *   provider/technology, both rows survive `build-bdc.ts`'s materialize-time collapse (see that file's
+ *   docstring; accepted FCC filing behavior, not a bug). `bdc_provider` is a small dictionary
+ *   keyed on `provider_id`, populated by a later registry-join task — decision 8 keeps FRN/brand/
+ *   holding-company resolution out of 2a's scope. The DB also embeds the layer-contract tables from
+ *   `@mailwoman/core/layers` (manifest tier `shipped`, license `public-domain` — FCC BDC block-level
+ *   availability data, at the granularity this layer ships, is US government public-domain data, not
+ *   redistribution-restricted; the CostQuest Fabric boundary this workspace never crosses is the
+ *   licensing edge, see `bdc/README.md` — spine `h3` res 9 for availability rows, res 6 for coverage
+ *   cells, matching poi.db's convention).
+ *
+ *   Clustering decision (implementer's pick — the brief allows either): a PLAIN rowid table, NOT
+ *   `WITHOUT ROWID`, and NOT a composite `(h3_cell, provider_id, technology_code)` primary key.
+ *   `WITHOUT ROWID` earns its keep on small, PK-probed rows — poi.db's clustered key and
+ *   `layer_coverage`'s per-cell probe both read by their exact PK and nothing else, so folding the row
+ *   into the B-tree removes a second lookup. `bdc_availability` doesn't fit that shape: it's a wider,
+ *   10-column row read two different ways — an h3-range scan ("everything near this cell", the
+ *   coverage/overlay path) and a geoid point lookup (the public spatial join key TIGER and callers
+ *   actually probe by) — never a single composite-key point probe. Clustering the full row under a
+ *   composite PK would also force the bulk loader to sort-then-insert in that exact key order across
+ *   millions of rows spread over per-provider, per-state source files, for a locality win a plain
+ *   index already delivers without constraining ingest order. So: a regular rowid table, an index on
+ *   `h3_cell` bundled into {@link createBDCAvailabilityTable} (every reader depends on it, same as the
+ *   table itself), and {@link createBDCGeoidIndex} as a separate, callable-after-bulk-load secondary
+ *   index for the geoid path — the index-after-load discipline used elsewhere in this repo (see
+ *   poi-schema.ts's name_key/brand indexes).
+ */
+import type { LayerContractDatabase } from "@mailwoman/core/layers";
+import type { Kysely } from "kysely";
+/**
+ * One availability row from the FCC's per-provider BDC CSV. In the default build mode this is one row per DISTINCT
+ * (geoid, provider_id, technology_code, speeds, low_latency, business_residential_code) tuple — NOT one row per (block,
+ * provider, technology) triple; a triple whose BSLs carry differing speed tiers keeps multiple rows here (see
+ * `build-bdc.ts`'s docstring).
+ */
+export interface BDCAvailabilityTable {
+    /**
+     * Res-9 integer short H3 cell of the block centroid (spine).
+     */
+    h3_cell: number;
+    /**
+     * 15-char census block GEOID (public spatial key).
+     */
+    geoid: string;
+    /**
+     * Block-centroid PIP at build time (spine).
+     */
+    wof_id: number | null;
+    provider_id: number;
+    technology_code: number;
+    max_advertised_download_speed: number;
+    max_advertised_upload_speed: number;
+    low_latency: 0 | 1;
+    business_residential_code: string;
+    /**
+     * Opaque BSL join key — NEVER resolved (spec §2.2); null unless `--include-location-ids`.
+     */
+    location_id: string | null;
+}
+/**
+ * Provider dictionary keyed on `provider_id`. Populated by a later registry-join task (2a decision 8) — that task is 3a
+ * Task 8's optional `BuildBDCOptions.providers` (`bdc/sdk/build-bdc.ts`'s `populateBDCProviderTable`); when that option
+ * is omitted (the default), this table stays empty, exactly as it did before Task 8. No FK constraint against
+ * `bdc_availability.provider_id` — SQLite doesn't enforce FKs without `PRAGMA foreign_keys`, and the join happens at
+ * read time, not write time.
+ *
+ * **Decision 6 — this table is an explicitly LOSSY denormalization, not the source of truth.** `provider_id` is the PK
+ * (one row per provider), but the FCC's BDC provider list lets one `provider_id` carry MULTIPLE `frn` values — and
+ * conflicting `holding_company` strings — across its rows (Task 3's `parseProviderList` preserves every one of them;
+ * see `filer/sdk/provider-list.ts`). A single-row-per-provider table cannot express that cardinality. `filer.db`
+ * (`@mailwoman/filer`) is the source of truth: it retains every `provider_id`↔`frn` (and
+ * `provider_id`↔`holding_company_name`) edge, never folded or last-wins. When `bdc.db` is built with
+ * `BuildBDCOptions.providers` supplied:
+ *
+ * - `frn` holds only the PRIMARY FRN — the one carrying the most recent Form 499 filing date, per
+ *   `@mailwoman/filer/sdk`'s `readFRNFilingCandidates` + `pickPrimaryFRN` (imported into `build-bdc.ts`, never
+ *   reimplemented — Task 7's review found and fixed a temporal bug in that exact query, one a fresh implementation
+ *   would reintroduce). Every OTHER FRN that `provider_id` carries is discarded here but stays fully recoverable from
+ *   `filer.db`.
+ * - `holding_company` gets the SAME single-distinct-value shortcut `frn` gets (review fix round 1, IMPORTANT-3): when a
+ *   `provider_id`'s rows carry exactly one distinct non-null `holding_company` string, there is no conflict to resolve,
+ *   so it's populated directly — no rule needed, same as a single-FRN provider needs no `filerDB` query. When they
+ *   carry MORE than one distinct value, that ambiguity is the real conflict decision 6 refuses to paper over with
+ *   last-wins (`holding_company` has no most-recent-filing-date rule the way `frn` does), so it stays NULL and every
+ *   discarded value remains recoverable from `filer.db`'s `holding_company_name` edges — the identical discipline
+ *   `frn`'s primary pick already applies.
+ * - `brand_name` stays NULL unconditionally: the provider list carries no brand-name column at all, primary or otherwise,
+ *   so there is nothing to populate it from.
+ */
+export interface BDCProviderTable {
+    /**
+     * PK.
+     */
+    provider_id: number;
+    frn: string | null;
+    brand_name: string | null;
+    holding_company: string | null;
+}
+export interface BDCDatabase extends LayerContractDatabase {
+    bdc_availability: BDCAvailabilityTable;
+    bdc_provider: BDCProviderTable;
+}
+/**
+ * H3 resolution for `bdc_availability.h3_cell` — the block-centroid spine resolution.
+ */
+export declare const BDC_H3_RESOLUTION = 9;
+/**
+ * H3 resolution for `layer_coverage.h3_cell` in bdc.db — coarser than the availability spine, matching poi.db's res-6
+ * coverage-cell convention.
+ */
+export declare const BDC_COVERAGE_H3_RESOLUTION = 6;
+/**
+ * Create `bdc_availability` as a plain rowid table, plus the `h3_cell` range-scan index (bundled here since every
+ * reader depends on it — see the file header for the clustering rationale). Call {@link createBDCGeoidIndex}
+ * separately, after bulk load, for the geoid point-lookup path.
+ */
+export declare function createBDCAvailabilityTable(db: Kysely<BDCDatabase>): Promise<void>;
+/**
+ * Create `bdc_provider`. A single-column INTEGER PRIMARY KEY is already the SQLite rowid alias, so there's no `WITHOUT
+ * ROWID` win here — that modifier only pays off clustering a composite or non-integer PK.
+ */
+export declare function createBDCProviderTable(db: Kysely<BDCDatabase>): Promise<void>;
+/**
+ * Secondary index for the geoid point-lookup path (the public spatial join key). Call AFTER the bulk materialize
+ * (index-after-load), same discipline as poi.db's secondary indexes.
+ */
+export declare function createBDCGeoidIndex(db: Kysely<BDCDatabase>): Promise<void>;
+//# sourceMappingURL=schema.d.ts.map

package/out/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,6BAA6B,EAAE,MAAM,CAAA;IACrC,2BAA2B,EAAE,MAAM,CAAA;IACnC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAA;IAClB,yBAAyB,EAAE,MAAM,CAAA;IACjC;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,WAAY,SAAQ,qBAAqB;IACzD,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,YAAY,EAAE,gBAAgB,CAAA;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhF"}

package/out/schema.js

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for bdc.db — the FCC Broadband Data Collection availability read-side layer (2a
+ *   decisions 4, 8). `bdc_availability` holds, in the default (non-`includeLocationIDs`) build mode, one
+ *   row per DISTINCT (geoid, provider_id, technology_code, max_advertised_download_speed,
+ *   max_advertised_upload_speed, low_latency, business_residential_code) tuple parsed from the FCC's
+ *   per-provider CSV (see `sdk/parsing.ts`) — NOT one row per (block, provider, technology) triple: when
+ *   two Broadband Serviceable Locations in the same block file different speeds/flags for the same
+ *   provider/technology, both rows survive `build-bdc.ts`'s materialize-time collapse (see that file's
+ *   docstring; accepted FCC filing behavior, not a bug). `bdc_provider` is a small dictionary
+ *   keyed on `provider_id`, populated by a later registry-join task — decision 8 keeps FRN/brand/
+ *   holding-company resolution out of 2a's scope. The DB also embeds the layer-contract tables from
+ *   `@mailwoman/core/layers` (manifest tier `shipped`, license `public-domain` — FCC BDC block-level
+ *   availability data, at the granularity this layer ships, is US government public-domain data, not
+ *   redistribution-restricted; the CostQuest Fabric boundary this workspace never crosses is the
+ *   licensing edge, see `bdc/README.md` — spine `h3` res 9 for availability rows, res 6 for coverage
+ *   cells, matching poi.db's convention).
+ *
+ *   Clustering decision (implementer's pick — the brief allows either): a PLAIN rowid table, NOT
+ *   `WITHOUT ROWID`, and NOT a composite `(h3_cell, provider_id, technology_code)` primary key.
+ *   `WITHOUT ROWID` earns its keep on small, PK-probed rows — poi.db's clustered key and
+ *   `layer_coverage`'s per-cell probe both read by their exact PK and nothing else, so folding the row
+ *   into the B-tree removes a second lookup. `bdc_availability` doesn't fit that shape: it's a wider,
+ *   10-column row read two different ways — an h3-range scan ("everything near this cell", the
+ *   coverage/overlay path) and a geoid point lookup (the public spatial join key TIGER and callers
+ *   actually probe by) — never a single composite-key point probe. Clustering the full row under a
+ *   composite PK would also force the bulk loader to sort-then-insert in that exact key order across
+ *   millions of rows spread over per-provider, per-state source files, for a locality win a plain
+ *   index already delivers without constraining ingest order. So: a regular rowid table, an index on
+ *   `h3_cell` bundled into {@link createBDCAvailabilityTable} (every reader depends on it, same as the
+ *   table itself), and {@link createBDCGeoidIndex} as a separate, callable-after-bulk-load secondary
+ *   index for the geoid path — the index-after-load discipline used elsewhere in this repo (see
+ *   poi-schema.ts's name_key/brand indexes).
+ */
+/**
+ * H3 resolution for `bdc_availability.h3_cell` — the block-centroid spine resolution.
+ */
+export const BDC_H3_RESOLUTION = 9;
+/**
+ * H3 resolution for `layer_coverage.h3_cell` in bdc.db — coarser than the availability spine, matching poi.db's res-6
+ * coverage-cell convention.
+ */
+export const BDC_COVERAGE_H3_RESOLUTION = 6;
+/**
+ * Create `bdc_availability` as a plain rowid table, plus the `h3_cell` range-scan index (bundled here since every
+ * reader depends on it — see the file header for the clustering rationale). Call {@link createBDCGeoidIndex}
+ * separately, after bulk load, for the geoid point-lookup path.
+ */
+export async function createBDCAvailabilityTable(db) {
+    await db.schema
+        .createTable("bdc_availability")
+        .addColumn("h3_cell", "integer", (c) => c.notNull())
+        .addColumn("geoid", "text", (c) => c.notNull())
+        .addColumn("wof_id", "integer")
+        .addColumn("provider_id", "integer", (c) => c.notNull())
+        .addColumn("technology_code", "integer", (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())
+        .addColumn("location_id", "text")
+        .execute();
+    await db.schema.createIndex("bdc_availability_h3_cell").on("bdc_availability").column("h3_cell").execute();
+}
+/**
+ * Create `bdc_provider`. A single-column INTEGER PRIMARY KEY is already the SQLite rowid alias, so there's no `WITHOUT
+ * ROWID` win here — that modifier only pays off clustering a composite or non-integer PK.
+ */
+export async function createBDCProviderTable(db) {
+    await db.schema
+        .createTable("bdc_provider")
+        .addColumn("provider_id", "integer", (c) => c.primaryKey())
+        .addColumn("frn", "text")
+        .addColumn("brand_name", "text")
+        .addColumn("holding_company", "text")
+        .execute();
+}
+/**
+ * Secondary index for the geoid point-lookup path (the public spatial join key). Call AFTER the bulk materialize
+ * (index-after-load), same discipline as poi.db's secondary indexes.
+ */
+export async function createBDCGeoidIndex(db) {
+    await db.schema.createIndex("bdc_availability_geoid").on("bdc_availability").column("geoid").execute();
+}
+//# sourceMappingURL=schema.js.map

package/out/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAiFH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAElC;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAuB;IACvE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,kBAAkB,CAAC;SAC/B,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC;SAC9B,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,iBAAiB,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC3D,SAAS,CAAC,+BAA+B,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACzE,SAAS,CAAC,6BAA6B,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvE,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,2BAA2B,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClE,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;SAChC,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA;AAC3G,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAAuB;IACnE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,cAAc,CAAC;SAC3B,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SAC1D,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;SAC/B,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC;SACpC,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAuB;IAChE,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAA;AACvG,CAAC"}

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

@@ -0,0 +1,214 @@
+/**
+ * @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 { DatabaseClient } from "@mailwoman/core/kysley/client";
+import type { FilerDatabase } from "@mailwoman/filer";
+import type { ProviderListRow } from "@mailwoman/filer/sdk";
+import type { ProviderID } from "./common.ts";
+import { type BDCAvailabilityRow } from "./parsing.ts";
+/**
+ * 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 declare const BDC_ATTRIBUTION: string;
+export interface BuildBDCOptions {
+    /**
+     * Injected row source — the test seam (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored and no
+     * filesystem read happens.
+     */
+    rows?: Iterable<BDCAvailabilityRow> | AsyncIterable<BDCAvailabilityRow>;
+    /**
+     * Per-provider availability CSVs for one state (as extracted by `downloadBDCFile`). Ignored when `rows` is given.
+     * Required unless `rows` is given. Each file's constant `provider_id` column is peeked off its first data row (see
+     * {@linkcode peekProviderID}) rather than threaded through as a parallel array — the FCC's per-provider files already
+     * carry it once per file, redundantly, in column 1.
+     */
+    csvPaths?: string[];
+    /**
+     * Output `bdc.db` path. Built at `${out}.building` and moved into place last — see the module docstring.
+     */
+    out: string;
+    /**
+     * The FCC filing's `as_of_date` (e.g. from Task 5's `resolveLatestVintage`) — becomes the manifest's `sourceVintage`
+     * AND `version` (BDC has no independent layer versioning yet, same deferral `build-poi.ts` makes for `release`).
+     */
+    asOfDate: string;
+    /**
+     * `git rev-parse --short HEAD` — passed in by the command, not read from the repo here.
+     */
+    buildSHA: string;
+    /**
+     * Populate `bdc_availability.location_id` (the opaque BSL join key — spec §2.2, NEVER resolved against the Fabric).
+     * Default `false`: the column stays `NULL` unless a caller explicitly opts in.
+     */
+    includeLocationIDs?: boolean;
+    /**
+     * Resolve a 15-char census block GEOID to its centroid. Injected so tests supply a small fixture `Map` lookup instead
+     * of touching a real TIGER database; the real (CLI-wired) implementation is
+     * {@linkcode createTIGERBlockCentroidLookup}, which reads `tabblock20.GEOID` (uppercase — `TIGERBlockTable`) block
+     * geometry. Returning `undefined` for an unknown geoid is load-bearing: the materialize pass counts it in
+     * `unknownGeoids` and skips the row — it must NEVER guess a cell.
+     */
+    blockCentroids: (geoid: string) => {
+        lat: number;
+        lon: number;
+    } | undefined;
+    onProgress?: (message: string) => void;
+    /**
+     * Provider-list rows (Task 3's {@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI
+     * seam for populating `bdc_provider` (2a decision 8 / 3a decision 6, Task 8). When ABSENT (the default),
+     * `bdc_provider` stays empty and the rest of the build is byte-identical to the pre-Task-8 behavior: every code path
+     * this option touches is gated behind `if (options.providers)`, so omitting it changes nothing. When present,
+     * `buildBDCDatabase` groups rows by `providerID` and inserts one `bdc_provider` row per distinct provider — see
+     * {@link BuildBDCOptions.filerDB} for how the primary FRN is picked when a provider carries more than one, and
+     * `schema.ts`'s `BDCProviderTable` docstring for the full lossy-denormalization rationale (decision 6).
+     */
+    providers?: Iterable<ProviderListRow> | AsyncIterable<ProviderListRow>;
+    /**
+     * Filer.db handle (`@mailwoman/filer`) used to resolve a multi-FRN provider's PRIMARY FRN via
+     * `readFRNFilingCandidates` + `pickPrimaryFRN` (`@mailwoman/filer/sdk`, decision 6) — imported rather than
+     * reimplemented, since Task 7's review found and fixed a temporal bug (the candidate query originally omitted the
+     * `valid_to` half of the half-open predicate) that a fresh implementation here would reintroduce. Only actually
+     * QUERIED for a `provider_id` whose rows carry more than one distinct `frn` — a single-FRN provider needs no lookup,
+     * since its lone FRN is already primary by construction. Required whenever `providers` is given AND at least one
+     * `provider_id` turns out to be multi-FRN; `buildBDCDatabase` throws a descriptive error naming the offending
+     * `provider_id` if it's needed but missing, rather than silently picking an arbitrary FRN.
+     */
+    filerDB?: DatabaseClient<FilerDatabase>;
+    /**
+     * `asOf` date for the primary-FRN candidate query (`readFRNFilingCandidates`'s half-open `valid_from`/`valid_to`
+     * scoping — see `filer/sdk/filer-lookup.ts`). Defaults to {@link BuildBDCOptions.asOfDate} (this bdc.db build's own
+     * vintage) when omitted.
+     */
+    primaryFRNAsOf?: string;
+}
+export interface BuildBDCResult {
+    out: string;
+    /**
+     * Rows materialized into `bdc_availability` (post-dedup, post-unknown-geoid-skip). In the default
+     * (`includeLocationIDs: false`) mode this is per DISTINCT (geoid, provider_id, technology_code, speeds, low_latency,
+     * business_residential_code) tuple, not per BSL — multiple BSLs at the same (geoid, provider_id, technology_code)
+     * triple collapse to one row ONLY when their speeds/flags also match; BSLs at the same triple with differing
+     * speeds/flags survive as separate rows (see the module docstring).
+     */
+    rows: number;
+    /**
+     * Raw rows removed by the staging natural-key dedup (staged attempts minus distinct rows kept).
+     */
+    deduped: number;
+    /**
+     * Distinct `provider_id` values among the materialized rows.
+     */
+    providers: number;
+    /**
+     * Res-6 coverage cells written.
+     */
+    coverageCells: number;
+    /**
+     * Rows whose `geoid` had no resolvable centroid — skipped, never inserted, never guessed at a cell.
+     */
+    unknownGeoids: number;
+    /**
+     * `bdc_provider` rows written — 0 when `options.providers` was not supplied (the default path never touches this
+     * table, see {@link BuildBDCOptions.providers}).
+     */
+    providersPopulated: number;
+}
+/**
+ * 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 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.
+ *
+ * Returns `undefined` for anything that doesn't parse as one of the two geometry types (including `null` geometry).
+ */
+export declare function geometryCentroid(geometryJSON: string | null): {
+    lat: number;
+    lon: number;
+} | undefined;
+/**
+ * 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 declare function createTIGERBlockCentroidLookup(tigerDBPath: string): (geoid: string) => {
+    lat: number;
+    lon: number;
+} | undefined;
+/**
+ * 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 declare function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildBDCResult>;
+//# sourceMappingURL=build-bdc.d.ts.map

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

@@ -0,0 +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;AAW9D,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,CAsCtG;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"}