@mailwoman/bdc 9.2.0 → 9.4.0

package/lib/env.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * The FCC Broadband Map credentials the BDC client sends.
+ */
+
+import { $private as corePrivate, liveEnv } from "@mailwoman/core/env"
+import { z } from "zod"
+
+/**
+ * FCC Broadband Map (BDC) public-API credentials (`bdc/lib/sdk/client.ts`) — username + hash_value header auth. Never
+ * log their values.
+ */
+export const PrivateBDCEnvSchema = z.object({
+	FCC_MAP_USERNAME: z.string().optional().meta({
+		title: "FCC Broadband Map username",
+		description: "Username used to authenticate to the FCC Broadband Data Collection API.",
+	}),
+	FCC_MAP_API_KEY: z.string().optional().meta({
+		title: "FCC Broadband Map API key",
+		description: "API key hash used to authenticate to the FCC Broadband Data Collection API.",
+	}),
+})
+
+/**
+ * Live BDC credentials over core's. Never log their values.
+ */
+export const $private = liveEnv(PrivateBDCEnvSchema, corePrivate)

package/lib/index.ts

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

package/{sdk → lib/sdk}/build-bdc.ts

@@ -50,32 +50,33 @@
  *      the house rule exists for.
  */
 
-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 { pathExists, readDirectory, readFileRange } from "@mailwoman/core/fs/readers"
+import { removePathIfPresent, movePath, makeDirectories, removePath } from "@mailwoman/core/fs/writers"
+import { tryParsingJSON } from "@mailwoman/core/json"
 import {
-	CoverageBasis,
 	createLayerCoverageTable,
 	createLayerManifestTable,
 	LayerFreshnessPolicy,
 	LayerTier,
+	sourcePresentCoverageCells,
 	writeLayerCoverage,
 	writeLayerManifest,
 } from "@mailwoman/core/layers"
-import { tryParsingJSON } from "@mailwoman/core/objects"
-import { openBuiltDatabase, sealDatabase, swapDatabaseIntoPlace } from "@mailwoman/core/utils"
 import type { FilerDatabase } from "@mailwoman/filer"
-// `pickPrimaryFRN`/`readFRNFilingCandidates` are loaded via a LAZY `await import("@mailwoman/filer/sdk")`
+// `pickPrimaryFRN`/`readFRNFilingCandidates` are loaded via a LAZY `await import("@mailwoman/filer/filer-lookup")`
 // inside `populateBDCProviderTable`, not a top-level runtime import — see that function's docstring
-//. Only the TYPES are imported here; `import type` is fully erased, so
-// this line has zero runtime cost for every `@mailwoman/bdc` consumer that never populates providers.
-import type { FRN, ProviderListRow } from "@mailwoman/filer/sdk"
+//
+// Only the TYPES are imported here; `import type` is fully erased.
+import type { FRN } from "@mailwoman/filer/frn"
+import type { ProviderListRow } from "@mailwoman/filer/sdk"
 import { shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { beginBatched } from "@mailwoman/sqlite/batched"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { openBuiltClient } from "@mailwoman/sqlite/sealed"
+import { sealDatabase, swapDatabaseIntoPlace } from "@mailwoman/sqlite/sealed-db"
 import { cellToParent, latLngToCell } from "h3-js"
 import type { Insertable, Kysely } from "kysely"
+import { basename, dirname, join } from "path-ts"
 
 import {
 	BDC_COVERAGE_H3_RESOLUTION,
@@ -85,9 +86,9 @@ import {
 	createBDCProviderTable,
 	type BDCDatabase,
 	type BDCProviderTable,
-} from "../schema.ts"
-import type { ProviderID } from "./common.ts"
-import { readAvailabilityRows, type BDCAvailabilityRow } from "./parsing.ts"
+} from "#schema"
+import type { ProviderID } from "#sdk/common"
+import { readAvailabilityRows, type BDCAvailabilityRow } from "#sdk/parsing"
 
 /**
  * Rows committed per `BEGIN`/`COMMIT` batch during both the staging load and the materialize pass — matches
@@ -105,8 +106,8 @@ export const BDC_ATTRIBUTION =
 
 export interface BuildBDCOptions {
 	/**
-	 * Injected row source — the test seam (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored and no
-	 * filesystem read happens.
+	 * Injected row source — the TEST INJECTION POINT (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored
+	 * and no filesystem read happens.
 	 */
 	rows?: Iterable<BDCAvailabilityRow> | AsyncIterable<BDCAvailabilityRow>
 	/**
@@ -138,15 +139,15 @@ export interface BuildBDCOptions {
 	 * Resolve a 15-char census block GEOID to its centroid. Injected so tests supply a small fixture `Map` lookup instead
 	 * of touching a real TIGER database; the real (CLI-wired) implementation is
 	 * {@linkcode createTIGERBlockCentroidLookup}, which reads `tabblock20.GEOID` (uppercase — `TIGERBlockTable`) block
-	 * geometry. Returning `undefined` for an unknown geoid is load-bearing: the materialize pass counts it in
-	 * `unknownGeoids` and skips the row — it must NEVER guess a cell.
+	 * geometry. Returning `undefined` for an unknown geoid is required: the materialize pass counts it in `unknownGeoids`
+	 * and skips the row — it must NEVER guess a cell.
 	 */
 	blockCentroids: (geoid: string) => { lat: number; lon: number } | undefined
 	onProgress?: (message: string) => void
 	/**
-	 * Provider-list rows ({@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI seam for
-	 * populating `bdc_provider` (2a decision 8 / 3a decision 6). When ABSENT (the default), `bdc_provider` stays empty
-	 * and the rest of the build is untouched: every code path this option touches is gated behind `if
+	 * Provider-list rows ({@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI injection
+	 * point for populating `bdc_provider` (2a decision 8 / 3a decision 6). When ABSENT (the default), `bdc_provider`
+	 * stays empty and the rest of the build is untouched: every code path this option touches is conditioned behind `if
 	 * (options.providers)`, so omitting it changes nothing. When present, `buildBDCDatabase` groups rows by `providerID`
 	 * and inserts one `bdc_provider` row per distinct provider — see {@link BuildBDCOptions.filerDB} for how the primary
 	 * FRN is picked when a provider carries more than one, and `schema.ts`'s `BDCProviderTable` docstring for the full
@@ -257,7 +258,7 @@ interface BDCStageRow {
  *
  * `csvPath` is optional and used ONLY to name the offending file in a thrown error (the direct-buffer unit tests call
  * this without one; {@linkcode readAvailabilityRowsFromCSVPaths} always supplies it). The `Number.isSafeInteger` guard
- * below is load-bearing, not defensive dressing: `bdc_stage.provider_id` is `INTEGER NOT NULL`, and a bare
+ * below is required, not defensive dressing: `bdc_stage.provider_id` is `INTEGER NOT NULL`, and a bare
  * `Number.parseInt` on a non-numeric field (a malformed/re-headered/truncated CSV) silently produces `NaN`. `NaN` binds
  * to that NOT NULL column as SQLite `NULL`, `INSERT OR IGNORE` then drops the row without a constraint error, and every
  * dropped row gets counted as `deduped` — the ENTIRE file's rows vanish silently, misreported as ordinary dedup. A
@@ -300,38 +301,21 @@ export function peekProviderID(csvBuffer: Buffer, csvPath?: string): ProviderID
  * 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.
+ * `provider_id` is a constant per file, so establishing it needs the first data row and nothing else; a whole-file read
+ * was resident-loading 920 MB (one state × technology) to read one column of one row.
  */
-async function readCSVHead(csvPath: string): Promise<Buffer> {
-	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()
-	}
-}
+const PROVIDER_ID_PEEK_BYTES = 64 * 1024
 
 /**
  * Peeks each file's `provider_id` off its head ({@linkcode peekProviderID}, passing the path through so a malformed
  * file's error names it), then STREAMS every row via `readAvailabilityRows` — the file is never resident. This is the
- * production counterpart to the test 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`.
+ * production counterpart to the TEST INJECTION POINT's injected `rows` — exercised by `build-bdc.test.ts` only for the
+ * malformed-provider-id rejection path, same as `build-poi.ts`'s Parquet reader.
  */
 async function* readAvailabilityRowsFromCSVPaths(csvPaths: readonly string[]): AsyncIterable<BDCAvailabilityRow> {
 	for (const csvPath of csvPaths) {
-		const providerID = peekProviderID(await readCSVHead(csvPath), csvPath)
+		const providerID = peekProviderID(await readFileRange(csvPath, 0, PROVIDER_ID_PEEK_BYTES), csvPath)
 
 		yield* readAvailabilityRows(csvPath, providerID)
 	}
@@ -355,7 +339,7 @@ interface GeoJSONMultiPolygon {
  * 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
+ * This REPLACED the first version's vertex-average, whose "same res-9 cell for all but pathological shapes" claim was
  * falsified by measurement over every real TIGER 2020 block in LA + Orange county (118,360 blocks, 2026-08-11): the
  * vertex-average landed in a different res-9 cell for 11.6% of blocks, p99 displacement 286 m (past the ~174 m cell
  * edge), max 3.7 km — the tail is TIGER's elongated rural/mountain blocks, whose boundary vertices cluster on the
@@ -432,16 +416,17 @@ export function geometryCentroid(geometryJSON: string | null): { lat: number; lo
 
 /**
  * The production `blockCentroids` supplier: opens the TIGER blocks database READ-ONLY and probes `tabblock20.GEOID`
- * (uppercase) per lookup, decoding its GeoJSON `geometry` column via {@linkcode geometryCentroid}. Kept synchronous —
- * `BuildBDCOptions.blockCentroids` is a plain sync function (the same sync-by-interface discipline AGENTS.md documents
- * for the resolver ladder), so this uses `node:sqlite`'s raw `.prepare()`/`.get()` directly rather than Kysely. The
- * connection is left open for the caller's process lifetime (a read-path lookup, not a build) — same lifecycle as the
- * resolver-wof-sqlite lookups.
+ * (uppercase) per lookup, decoding its GeoJSON `geometry` column via {@linkcode geometryCentroid}. The factory awaits
+ * its read-only open; the per-lookup probe and the `BuildBDCOptions.blockCentroids` interface stay synchronous — a
+ * plain sync function (the same sync-by-interface discipline AGENTS.md documents for the resolver ladder), so the
+ * returned closure uses `node:sqlite`'s raw `.prepare()`/`.get()` directly rather than Kysely. The connection is left
+ * open for the caller's process lifetime (a read-path lookup, not a build) — same lifecycle as the resolver-wof-sqlite
+ * lookups.
  */
-export function createTIGERBlockCentroidLookup(
+export async function createTIGERBlockCentroidLookup(
 	tigerDBPath: string
-): (geoid: string) => { lat: number; lon: number } | undefined {
-	const db = openBuiltDatabase(tigerDBPath)
+): Promise<(geoid: string) => { lat: number; lon: number } | undefined> {
+	const db = await openBuiltClient(tigerDBPath)
 	const stmt = db.prepare("SELECT geometry FROM tabblock20 WHERE GEOID = ?")
 
 	return (geoid: string) => {
@@ -504,15 +489,18 @@ async function groupProviderListRows(
  * `brand_name` is always inserted NULL — the provider list carries no brand-name column at all, so there is nothing to
  * populate it from, primary or otherwise (see the schema docstring).
  *
- * **Lazy `@mailwoman/filer/sdk` import.** `readFRNFilingCandidates`/`pickPrimaryFRN` are loaded via `await
- * import("@mailwoman/filer/sdk")`, memoized in `filerSDK` below, rather than a top-level static import — that barrel
- * re-exports `cluster-filers.ts`, which pulls in `@mailwoman/match`/`record`/`registry`. A top-level import regressed
- * `@mailwoman/bdc`'s import time ~32% for EVERY consumer, including ones that never populate providers at all; the
- * dynamic import here only ever runs when a multi-FRN `provider_id` is actually encountered, so a `providers`-less
- * build (or one whose providers are all single-FRN) pays nothing.
+ * **Lazy `@mailwoman/filer/filer-lookup` import.** `readFRNFilingCandidates`/`pickPrimaryFRN` are loaded via `await
+ * import("@mailwoman/filer/filer-lookup")`, memoized in `filerSDK` below, rather than a top-level static import. The
+ * cost this avoids is smaller than it was: the specifier used to be the `@mailwoman/filer/sdk` BARREL, which `export
+ * *`s `cluster-filers.ts` and so pulls `@mailwoman/match`/`record`/`registry` in behind it — a top-level import of that
+ * barrel regressed `@mailwoman/bdc`'s import time ~32% for EVERY consumer, including ones that never populate
+ * providers. `filer-lookup.ts` alone imports only `@mailwoman/sqlite/client`, `#schema` and `#frn` (measured
+ * 2026-09-01), so the heavy graph is no longer on this path at all. The laziness is kept because it also defers opening
+ * the filer database, and a static import here is now a viable simplification if someone wants to measure it — but it
+ * is no longer load-bearing for import time.
  */
 async function populateBDCProviderTable(
-	kdb: DatabaseClient<BDCDatabase>,
+	db: DatabaseClient<BDCDatabase>,
 	providers: Iterable<ProviderListRow> | AsyncIterable<ProviderListRow>,
 	filerDB: DatabaseClient<FilerDatabase> | undefined,
 	asOf: string
@@ -520,7 +508,7 @@ async function populateBDCProviderTable(
 	const byProviderID = await groupProviderListRows(providers)
 	const insertRows: Insertable<BDCProviderTable>[] = []
 
-	let filerSDK: typeof import("@mailwoman/filer/sdk") | undefined
+	let filerSDK: typeof import("@mailwoman/filer/filer-lookup") | undefined
 
 	for (const [providerID, rows] of byProviderID) {
 		const distinctFRNs = [...new Set(rows.map((row) => row.frn))]
@@ -538,7 +526,7 @@ async function populateBDCProviderTable(
 				)
 			}
 
-			filerSDK ??= await import("@mailwoman/filer/sdk")
+			filerSDK ??= await import("@mailwoman/filer/filer-lookup")
 
 			const candidates = await filerSDK.readFRNFilingCandidates(filerDB, distinctFRNs, asOf)
 
@@ -555,7 +543,7 @@ async function populateBDCProviderTable(
 	}
 
 	for (let index = 0; index < insertRows.length; index += PROVIDER_INSERT_BATCH_SIZE) {
-		await kdb
+		await db
 			.insertInto("bdc_provider")
 			.values(insertRows.slice(index, index + PROVIDER_INSERT_BATCH_SIZE))
 			.execute()
@@ -580,24 +568,24 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 
 	const buildingPath = `${options.out}.building`
 
-	if (existsSync(buildingPath)) {
-		rmSync(buildingPath)
+	if (await pathExists(buildingPath)) {
+		await removePath(buildingPath)
 	}
 
-	mkdirSync(dirname(options.out), { recursive: true })
+	await makeDirectories(dirname(options.out))
 
 	// A crash inside a PRIOR run's swap can leave the slot empty while the previous version sits
 	// parked aside — restore it before building, so a failure in THIS run still leaves an artifact
 	// serving. Both aside spellings: this builder's old `.prev` and swapDatabaseIntoPlace's `.old-<pid>`.
-	if (!existsSync(options.out)) {
+	if (!(await pathExists(options.out))) {
 		const base = basename(options.out)
 
-		const parked = readdirSync(dirname(options.out)).find(
+		const parked = (await readDirectory(dirname(options.out))).find(
 			(name) => name === `${base}.prev` || name.startsWith(`${base}.old-`)
 		)
 
 		if (parked) {
-			renameSync(join(dirname(options.out), parked), options.out)
+			await movePath(join(dirname(options.out), parked), options.out)
 			progress(`restored ${parked} into place (a prior run crashed mid-swap)`)
 		}
 	}
@@ -605,21 +593,20 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 	const rowSource: AsyncIterable<BDCAvailabilityRow> | Iterable<BDCAvailabilityRow> =
 		options.rows ?? readAvailabilityRowsFromCSVPaths(options.csvPaths!)
 
-	const db = new DatabaseSync(buildingPath)
+	const db = new DatabaseClient<BDCDatabase>(buildingPath)
 	// Build-tuning pragmas — identical to build-poi.ts's discipline.
 	db.exec("PRAGMA page_size=8192; PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-2000000;")
-	const kdb = new DatabaseClient<BDCDatabase>({ database: db })
 
 	// Assigned at the end of the try — the tallies live inside its scope; the seal + swap do not.
 	let result: BuildBDCResult
 
 	try {
 		progress("creating manifest/coverage/availability/provider/stage tables")
-		await createLayerManifestTable(kdb)
-		await createLayerCoverageTable(kdb)
-		await createBDCAvailabilityTable(kdb)
-		await createBDCProviderTable(kdb)
-		await createBDCStageTable(kdb)
+		await createLayerManifestTable(db)
+		await createLayerCoverageTable(db)
+		await createBDCAvailabilityTable(db)
+		await createBDCProviderTable(db)
+		await createBDCStageTable(db)
 
 		const insStage = db.prepare(
 			`INSERT OR IGNORE INTO bdc_stage (
@@ -629,10 +616,10 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 		)
 
 		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")
+
+		const stageBatch = beginBatched(db, { rowsPerCommit: STAGE_BATCH_SIZE })
 
 		for await (const row of rowSource) {
 			insStage.run(
@@ -648,16 +635,10 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 
 			staged++
 
-			batch++
-
-			if (batch >= STAGE_BATCH_SIZE) {
-				db.exec("COMMIT")
-				db.exec("BEGIN")
-				batch = 0
-			}
+			stageBatch.rowWritten()
 		}
 
-		db.exec("COMMIT")
+		stageBatch.commit()
 
 		const stagedCountRow = db.prepare("SELECT COUNT(*) AS staged_count FROM bdc_stage").get() as {
 			staged_count: number
@@ -714,8 +695,7 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 			"materializing bdc_availability — resolving block centroids to h3_cell (unknown geoids skipped, never guessed)"
 		)
 
-		db.exec("BEGIN")
-		batch = 0
+		const materializeBatch = beginBatched(db, { rowsPerCommit: STAGE_BATCH_SIZE })
 
 		for (const row of stageStmt.iterate() as IterableIterator<BDCStageRow>) {
 			let resolved = centroidCache.get(row.geoid)
@@ -771,47 +751,36 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 			providers.add(row.provider_id)
 			coverage.set(resolved.coverageCell, (coverage.get(resolved.coverageCell) ?? 0) + 1)
 
-			batch++
-
-			if (batch >= STAGE_BATCH_SIZE) {
-				db.exec("COMMIT")
-				db.exec("BEGIN")
-				batch = 0
-			}
+			materializeBatch.rowWritten()
 		}
 
-		db.exec("COMMIT")
+		materializeBatch.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()
+		await db.schema.dropTable("bdc_stage").execute()
 
 		progress("geoid index (index-after-load — see schema.ts)")
-		await createBDCGeoidIndex(kdb)
+		await createBDCGeoidIndex(db)
 
 		// Coverage is SOURCE-LEVEL, not survey completeness — same convention build-poi.ts documents: a res-6 cell we
 		// have availability rows in is recorded at completeness 1.0. A cell absent from `layer_coverage` means no rows
 		// were observed there at all (the meaning-of-zero rule — missing = unknown, never `{completeness: 0}`).
-		const coverageCells = [...coverage.entries()].map(([h3Cell, observedRows]) => ({
-			h3Cell,
-			completeness: 1,
-			basis: CoverageBasis.SourcePresent,
-			observedRows,
-		}))
+		const coverageCells = sourcePresentCoverageCells(coverage)
 
-		await writeLayerCoverage(kdb, coverageCells)
+		await writeLayerCoverage(db, coverageCells)
 
 		progress("writing layer manifest")
 
-		await writeLayerManifest(kdb, {
+		await writeLayerManifest(db, {
 			name: "bdc",
 			version: options.asOfDate,
 			schemaVersion: 1,
 			tier: LayerTier.Shipped,
-			license: "public-domain",
+			license: "LicenseRef-USGov-Public-Domain",
 			attribution: BDC_ATTRIBUTION,
 			source: "fcc-bdc",
 			sourceVintage: options.asOfDate,
@@ -822,7 +791,7 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 			createdAt: new Date().toISOString(),
 		})
 
-		// bdc_provider population (2a decision 8 / 3a decision 6) — entirely additive and gated behind
+		// bdc_provider population (2a decision 8 / 3a decision 6) — entirely additive and conditioned on
 		// `options.providers`: when absent, this block never runs and `bdc_provider` stays empty (see
 		// `BuildBDCOptions.providers`'s docstring for the default-path guarantee).
 		let providersPopulated = 0
@@ -831,7 +800,7 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 			progress("populating bdc_provider from the provider list (decision 6 — lossy denormalization, see schema.ts)")
 
 			providersPopulated = await populateBDCProviderTable(
-				kdb,
+				db,
 				options.providers,
 				options.filerDB,
 				options.primaryFRNAsOf ?? options.asOfDate
@@ -847,7 +816,7 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 		// same discipline).
 		db.exec("PRAGMA page_size=8192")
 		db.exec("VACUUM")
-		await kdb.destroy()
+		await db.destroy()
 
 		result = {
 			out: options.out,
@@ -862,22 +831,22 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 		// 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()
+			await db.destroy()
 		} catch {
 			// The handle may already be closed or mid-statement — nothing more to release.
 		}
 
-		rmSync(buildingPath, { force: true })
+		await removePathIfPresent(buildingPath)
 
 		throw error
 	}
 
 	progress("seal")
-	sealDatabase(buildingPath)
+	await sealDatabase(buildingPath)
 
 	// Atomic move-into-place via the shared helper (the AGENTS.md database house rule): prior
 	// version aside first, forward rename restored on failure so the slot is never left empty.
-	swapDatabaseIntoPlace(buildingPath, options.out)
+	await swapDatabaseIntoPlace(buildingPath, options.out)
 
 	return result
 }

package/{sdk → lib/sdk}/client.ts

@@ -16,7 +16,7 @@
  *     2. The `username` + `hash_value` PLAIN HEADER PAIR — read carefully off the Nexus original's
  *        `axios.headers` config, this is NOT bearer or basic auth.
  *     3. The request budget: {@linkcode BDC_DEFAULT_REQUESTS_PER_MINUTE} requests per MINUTE, six
- *        seconds apart. See that constant for the sourcing and for why the interval gate is set too.
+ *        seconds apart. See that constant for the sourcing and for why the interval limit is set too.
  *     4. UN-UNWRAPPED response bodies. Every BDC endpoint nests its payload under a `data` key
  *        (`{ data: [...] }`), and callers pluck `.data` themselves at the call site — `filing-dates.ts`
  *        and `list-files.ts` both do. {@linkcode BDCClient.get} deliberately does NOT unwrap, so the
@@ -36,15 +36,14 @@
  *   | undecodable body                  | programmer bug   | `isTransientResourceError(error)` is false |
  */
 
-import { APIClient, type APIClientConfig, type ClockLike, systemClock } from "@mailwoman/core/api"
+import { API_CLIENT_DEFAULTS, APIClient, type APIClientConfig, type ClockLike, systemClock } from "@mailwoman/core/api"
 import { buildDiskStorage } from "@mailwoman/core/api/disk-storage"
-import { $private } from "@mailwoman/core/env"
+import { dataRootPath } from "@mailwoman/core/data-root"
 import { ResourceError } from "@mailwoman/core/errors"
-import { dataRootPath } from "@mailwoman/core/utils"
+
+import { $private } from "#env"
 
 // Re-exported so a caller branching on this client's failures needs exactly one import.
-export { isTransientResourceError } from "@mailwoman/core/api"
-export { ResourceError } from "@mailwoman/core/errors"
 
 /**
  * The FCC BDC public-API base URL every request is resolved against.
@@ -103,21 +102,6 @@ const PERCENT = 100
  */
 const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000
 
-/**
- * Total attempts (including the first) before giving up on a 429/5xx or a network-class failure.
- */
-const DEFAULT_MAX_ATTEMPTS = 3
-
-/**
- * Base delay for the exponential backoff between retry attempts, in milliseconds.
- */
-const DEFAULT_BASE_RETRY_DELAY_MS = 500
-
-/**
- * Per-attempt socket-inactivity timeout for a JSON request, in milliseconds.
- */
-const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
-
 /**
  * Per-attempt socket-inactivity timeout for a zip download, in milliseconds — deliberately far longer than the JSON
  * one. A BDC availability archive is routinely hundreds of megabytes, and Axios applies `timeout` through
@@ -191,9 +175,9 @@ export interface CreateBDCClientOptions {
 	 */
 	downloadTimeoutMs?: number
 	/**
-	 * Axios overrides, merged over this client's own defaults. THE TEST SEAM, replacing the old `fetchImpl` option: every
-	 * test passes an `adapter` here, so no test in this workspace ever performs a live network call. Overriding `headers`
-	 * wholesale would drop the credential pair, so don't.
+	 * Axios overrides, merged over this client's own defaults. THE TEST INJECTION POINT, replacing the old `fetchImpl`
+	 * option: every test passes an `adapter` here, so no test in this workspace ever performs a live network call.
+	 * Overriding `headers` wholesale would drop the credential pair, so don't.
 	 */
 	axios?: APIClientConfig["axios"]
 }
@@ -234,10 +218,10 @@ export interface BDCThrottleStats {
 	 */
 	waits: number
 	/**
-	 * How many times the per-minute BUDGET gate opened a cooldown, counted off `APIClient`'s `cooldown_start` event. With
-	 * the interval gate also configured this is one per budget's worth of requests, and each is a REAL wait, not a
+	 * How many times the per-minute BUDGET limit opened a cooldown, counted off `APIClient`'s `cooldown_start` event.
+	 * With the interval limit also configured this is one per budget's worth of requests, and each is a REAL wait, not a
 	 * zero-length window-rollover marker: the budget's cooldown runs to the end of the minute the window opened in
-	 * (`APIClient.#reserveCooldownSlot`), and the interval gate has by then spent only `(N-1) * 60000/N` ms of it. At
+	 * (`APIClient.#reserveCooldownSlot`), and the interval limit has by then spent only `(N-1) * 60000/N` ms of it. At
 	 * 10/minute that is a 6 s cooldown per 10 requests. Some of {@linkcode BDCThrottleStats.waitingMs} is therefore
 	 * cooldown, not pacing. See {@linkcode createBDCClient} for the full arrival trace.
 	 */
@@ -289,7 +273,7 @@ type UncachedBDCRequestConfig = BDCRequestConfig & {
 /**
  * Build the absolute request URL for `path`, with `params` as its query string.
  *
- * `path` is APPENDED to {@linkcode BDC_API_BASE_URL}, never RESOLVED against it. That distinction is load-bearing: `new
+ * `path` is APPENDED to {@linkcode BDC_API_BASE_URL}, never RESOLVED against it. That distinction is required: `new
  * URL("https://elsewhere.example/x", BDC_API_BASE_URL)` would resolve to `elsewhere.example` and carry the credential
  * header pair there, while string concatenation can only ever produce a path under the BDC origin.
  */
@@ -466,9 +450,9 @@ function formatDuration(ms: number): string {
 /**
  * A {@linkcode ClockLike} that records how long the client spends asleep, plus the reader that snapshots it.
  *
- * The clock is the only seam `APIClient` exposes that every wait passes through — the pacer sleeps on it, the cooldown
- * timer sleeps on it, and the retry backoff sleeps on it — so wrapping it is how the waiting becomes visible without
- * touching `core/api`.
+ * The clock is the only injection point `APIClient` exposes that every wait passes through — the pacer sleeps on it,
+ * the cooldown timer sleeps on it, and the retry backoff sleeps on it — so wrapping it is how the waiting becomes
+ * visible without touching `core/api`.
  *
  * WAITS ARE UNIONED, NOT SUMMED, and that is the whole subtlety here. Under a concurrent fan-out every caller sleeps at
  * once, and each one's wait is longer than the last: 40 concurrent requests at a 6 s interval sleep 6 s, 12 s, … 234 s,
@@ -551,20 +535,20 @@ export function createBDCClient(options: CreateBDCClientOptions = {}): BDCClient
 		username,
 		downloadTimeoutMs: options.downloadTimeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS,
 		readThrottleStats: () => meter.read(cooldowns),
-		// BOTH GATES, on purpose, and the interval is the one that holds the rate.
+		// BOTH LIMITS, on purpose, and the interval is the one that holds the rate.
 		//
 		// `requestsPerMinute` alone does NOT deliver N requests per minute. It is a budget model whose
 		// cooldown is `MS_PER_MINUTE / N` minus the gap since the previous dispatch — so N dispatches go out
 		// back to back and the client then waits 60000/N ms, i.e. N requests every 60/N SECONDS. Measured
 		// against a bare `APIClient` at `requestsPerMinute: 10` with a 20-call fan-out on a virtual clock:
 		// arrivals at `[0 x10, 6000 x10]`, i.e. 20 inside one sliding minute against a budget of 10, and a
-		// sustained 100 requests/minute — ten times the published limit. `minRequestIntervalMs` is the gate
+		// sustained 100 requests/minute — ten times the published limit. `minRequestIntervalMs` is the limit
 		// that actually spaces dispatches, and it is what makes this client honor 10/minute.
 		//
-		// The budget is still declared rather than dropped — and it is NOT free. The two gates compose (both
+		// The budget is still declared rather than dropped — and it is NOT free. The two limits compose (both
 		// must clear), so the budget's cooldown still fires, and it is a REAL wait: `APIClient` measures that
-		// cooldown to the end of the MINUTE the window opened in, while the interval gate has by then spent
-		// only `(N-1) * 60000/N` ms of it. With both gates on 10/minute, arrivals run `0, 6, …, 54 s`; the
+		// cooldown to the end of the MINUTE the window opened in, while the interval limit has by then spent
+		// only `(N-1) * 60000/N` ms of it. With both limits on 10/minute, arrivals run `0, 6, …, 54 s`; the
 		// 10th dispatch opens a `60000 - 54000 = 6000 ms` cooldown; the pacer's grant for #11 is discarded
 		// across that wait (`acquireDispatchSlot` re-acquires rather than holding a stale grant, under-issuing
 		// by one — the safe direction), so #11 lands at 66 s and the pattern repeats. Steady state is 10
@@ -574,12 +558,12 @@ export function createBDCClient(options: CreateBDCClientOptions = {}): BDCClient
 		// Declaring the budget states the intent in the option whose name matches the published limit. If
 		// `requestsPerMinute` is ever corrected in `core/api` to mean what it says, this client already
 		// declares the right budget and the interval becomes a redundant second ceiling rather than the
-		// load-bearing one.
+		// required one.
 		requestsPerMinute,
 		minRequestIntervalMs: Math.ceil(MS_PER_MINUTE / requestsPerMinute),
 		retry: {
-			maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
-			baseDelayMs: options.baseRetryDelayMs ?? DEFAULT_BASE_RETRY_DELAY_MS,
+			maxAttempts: options.maxAttempts ?? API_CLIENT_DEFAULTS.maxAttempts,
+			baseDelayMs: options.baseRetryDelayMs ?? API_CLIENT_DEFAULTS.baseRetryDelayMs,
 		},
 		clock: meter.clock,
 		caching: {
@@ -611,7 +595,7 @@ export function createBDCClient(options: CreateBDCClientOptions = {}): BDCClient
 				username,
 				hash_value: apiKey,
 			},
-			timeout: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+			timeout: options.requestTimeoutMs ?? API_CLIENT_DEFAULTS.requestTimeoutMs,
 			responseType: "json",
 			// `silentJSONParsing` defaults to TRUE, which makes Axios hand back the RAW STRING when a body
 			// fails to parse instead of raising. An upstream serving an HTML error page under a 200 would

package/{sdk → lib/sdk}/common.ts

@@ -8,7 +8,7 @@
 
 import type { Tagged } from "type-fest"
 
-import type { BroadbandTechnologyCode } from "./technologies.ts"
+import type { BroadbandTechnologyCode } from "#sdk/technologies"
 
 /**
  * Unique identifier for an FCC BDC broadband provider.

package/{sdk → lib/sdk}/data-collection.ts

@@ -5,8 +5,8 @@
  * @file FCC Broadband Data Collection System
  */
 
-import type { BuildingTypeCode } from "./buildings.ts"
-import type { BroadbandServicableLocationID } from "./location.ts"
+import type { BuildingTypeCode } from "#sdk/buildings"
+import type { BroadbandServicableLocationID } from "#sdk/location"
 
 /**
  * Snake_case identifier for a US State or Territory.