@mailwoman/bdc 9.1.0 → 9.3.0

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,11 +36,12 @@
  *   | 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"
@@ -103,21 +104,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 +177,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 +220,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 +275,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 +452,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 +537,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 +560,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 +597,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.

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

@@ -5,13 +5,14 @@
  * @file FCC BDC availability-file download + zip extraction.
  */
 
-import * as fs from "node:fs/promises"
-import * as path from "node:path"
-
+import { tryStat } from "@mailwoman/core/fs/readers"
+import { makeDirectories, writeLocalFile } from "@mailwoman/core/fs/writers"
 import { extractSingleFileZip } from "@mailwoman/core/fs/zip"
+import type { PathBuilderLike } from "path-ts"
+import { resolvePath } from "path-ts/resolve"
 
-import type { BDCClient } from "./client.ts"
-import { BDCFilingDataType, type BDCFile } from "./common.ts"
+import type { BDCClient } from "#sdk/client"
+import { BDCFilingDataType, type BDCFile } from "#sdk/common"
 
 /**
  * Download and cache an FCC BDC availability file, extracting its zip-wrapped CSV to `destinationDir`.
@@ -28,15 +29,18 @@ import { BDCFilingDataType, type BDCFile } from "./common.ts"
  *
  * @returns The path of the extracted (and now cached) CSV file.
  */
-export async function downloadBDCFile(client: BDCClient, file: BDCFile, destinationDir: string): Promise<string> {
-	const csvPath = path.join(destinationDir, `${file.fileName}.csv`)
+export async function downloadBDCFile(
+	client: BDCClient,
+	file: BDCFile,
+	destinationDir: PathBuilderLike
+): Promise<string> {
+	const csvPath = resolvePath(destinationDir, `${file.fileName}.csv`)
 
-	const alreadyCached = await fs
-		.access(csvPath)
-		.then(() => true)
-		.catch(() => false)
+	const alreadyCached = await tryStat(csvPath)
 
-	if (alreadyCached) return csvPath
+	if (alreadyCached) {
+		return csvPath.toString()
+	}
 
 	const zippedArrayBuffer = await client.getArrayBuffer(
 		`/map/downloads/downloadFile/${BDCFilingDataType.Availability}/${file.fileID}`
@@ -44,8 +48,8 @@ export async function downloadBDCFile(client: BDCClient, file: BDCFile, destinat
 
 	const csvBuffer = await extractSingleFileZip(Buffer.from(zippedArrayBuffer))
 
-	await fs.mkdir(destinationDir, { recursive: true })
-	await fs.writeFile(csvPath, csvBuffer)
+	await makeDirectories(destinationDir.toString())
+	await writeLocalFile(csvBuffer, csvPath.toString())
 
-	return csvPath
+	return csvPath.toString()
 }

package/{sdk → lib/sdk}/filing-dates.ts

@@ -9,7 +9,7 @@
  *   {@linkcode BDCClient}.
  *
  *   CACHING MOVED TO THE CLIENT. Both the Nexus original (one `<filingType>-dates.json` per filing
- *   type) and this port's first cut (`dataRootPath("bdc", "cache", "filing-dates.json")`, unfiltered)
+ *   type) and this port's first version (`dataRootPath("bdc", "cache", "filing-dates.json")`, unfiltered)
  *   hand-rolled a JSON file cache here. `BDCClient` is built on `APIClient` and now carries an on-disk
  *   response cache of its own, so the hand-rolled one was the exact duplication that migration exists to
  *   remove — and it was worse than what replaced it: it had NO expiry, so a machine that resolved a
@@ -18,8 +18,8 @@
  *   per-request cache bypass with the same meaning it always had.
  */
 
-import type { BDCClient } from "./client.ts"
-import type { BDCFilingDataType } from "./common.ts"
+import type { BDCClient } from "#sdk/client"
+import type { BDCFilingDataType } from "#sdk/common"
 
 /**
  * One entry from the FCC BDC's `/map/listAsOfDates` endpoint.

package/{sdk → lib/sdk}/filing-landscape.ts

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `filing_landscape` reader — the FOUR PRE-REGISTERED ACCEPTANCE GATES this whole phase
- *   is judged by. See `filing-landscape.test.ts` for the gate tests; this module is only the reader.
+ *   `filing_landscape` reader — the FOUR PRE-REGISTERED ACCEPTANCE CRITERIA this whole phase
+ *   is judged by. See `filing-landscape.test.ts` for the criterion tests; this module is only the reader.
  *
  *   Coverage check (the meaning-of-zero rule): a queried block counts as SURVEYED only when its res-6
  *   coverage cell is present in `layer_coverage` (via `readLayerCoverage`) — `undefined` means the area
@@ -33,13 +33,12 @@
  *   block excluded from `surveyed_block_count` never contributes to `filings` either.
  */
 
-import type { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { readLayerCoverage, readLayerManifest, type LayerContractDatabase } from "@mailwoman/core/layers"
-import { expandH3Cell, shortCellToInt, type H3Cell, type H3CellShort } from "@mailwoman/spatial"
-import { cellToParent } from "h3-js"
-import { sql, type Kysely } from "kysely"
+import { readLayerCoverage, readLayerManifest } from "@mailwoman/core/layers"
+import { shortCellToParentInt } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+import { sql } from "kysely"
 
-import { BDC_COVERAGE_H3_RESOLUTION, BDC_H3_RESOLUTION, type BDCDatabase } from "../schema.ts"
+import { BDC_COVERAGE_H3_RESOLUTION, BDC_H3_RESOLUTION, type BDCDatabase } from "#schema"
 
 /**
  * Exactly one of `geoids` or `h3Cells` is required — `filingLandscape` throws otherwise.
@@ -139,24 +138,13 @@ const speedBucketCaseSQL = sql<string>`CASE
 	ELSE ${BDC_SPEED_BUCKET_GIGABIT}
 END`
 
-/**
- * `BDCDatabase extends LayerContractDatabase` structurally, but Kysely's `transaction()` makes `Kysely<DB>` INVARIANT
- * in `DB` — same narrowing cast as `build-bdc.ts`'s `asContractDB`.
- */
-function asContractDB(kdb: DatabaseClient<BDCDatabase>): Kysely<LayerContractDatabase> {
-	return kdb as unknown as Kysely<LayerContractDatabase>
-}
-
 /**
  * Reconstruct the res-6 ancestor of a res-9 short-cell int WITHOUT a centroid — see the module docstring for why the
  * centroid is the wrong input. Exported so tests can assert this agrees, cell-for-cell, with `build-bdc.ts`'s own
  * coverage-cell derivation (the two MUST share this derivation — see that file's docstring).
  */
 export function res9ShortCellToRes6Parent(h3CellShortInt: number): number {
-	const fullCell = expandH3Cell(h3CellShortInt.toString(16) as H3CellShort, BDC_H3_RESOLUTION)
-	const parentCell = cellToParent(fullCell, BDC_COVERAGE_H3_RESOLUTION) as H3Cell
-
-	return shortCellToInt(parentCell)
+	return shortCellToParentInt(h3CellShortInt, BDC_H3_RESOLUTION, BDC_COVERAGE_H3_RESOLUTION)
 }
 
 /**
@@ -183,8 +171,8 @@ export async function filingLandscape(
 	}
 
 	// Read (and validate) the manifest FIRST — a broken/missing manifest must throw before any block is
-	// classified, never fall through to an "unstamped" answer (gate 4).
-	const manifest = await readLayerManifest(asContractDB(db))
+	// classified, never fall through to an "unstamped" answer (criterion 4).
+	const manifest = await readLayerManifest(db)
 
 	const requestedUnits: ReadonlyArray<string | number> = query.geoids ?? query.h3Cells!
 	const unitColumn = query.geoids ? ("geoid" as const) : ("h3_cell" as const)
@@ -214,7 +202,7 @@ export async function filingLandscape(
 	let surveyedBlockCount = 0
 	let unknownBlockCount = 0
 	// Only units that PASS the coverage check feed the census below — a unit with rows but no coverage evidence
-	// (a corrupted/inconsistent db — see filing-landscape.test.ts's "coverage row deleted" gate) is `unknown`, and
+	// (a corrupted/inconsistent db — see filing-landscape.test.ts's "coverage row deleted" case) is `unknown`, and
 	// its rows must not leak into `filings` either: `surveyed_block_count` and the blocks backing `filings` must
 	// always agree, or a caller cross-referencing the two gets a contradiction (an "unknown" block whose filings
 	// still show up looks exactly like the false-negative bug this reader exists to prevent).
@@ -230,7 +218,7 @@ export async function filingLandscape(
 		}
 
 		const res6Parent = res9ShortCellToRes6Parent(candidateCell)
-		const coverage = await readLayerCoverage(asContractDB(db), res6Parent)
+		const coverage = await readLayerCoverage(db, res6Parent)
 
 		if (coverage === undefined) {
 			unknownBlockCount++

package/lib/sdk/index.ts

@@ -0,0 +1,14 @@
+export * from "#sdk/build-bdc"
+export * from "#sdk/buildings"
+export * from "#sdk/client"
+export * from "#sdk/common"
+export * from "#sdk/data-collection"
+export * from "#sdk/download"
+export * from "#sdk/filing-dates"
+export * from "#sdk/filing-landscape"
+export * from "#sdk/list-files"
+export * from "#sdk/location"
+export * from "#sdk/nearest-infrastructure"
+export * from "#sdk/parsing"
+export * from "#sdk/plausibility"
+export * from "#sdk/technologies"

package/{sdk → lib/sdk}/list-files.ts

@@ -11,7 +11,7 @@
  *   ascending by revision (`compareRevisionAsc`) rather than in API order.
  */
 
-import type { BDCClient } from "./client.ts"
+import type { BDCClient } from "#sdk/client"
 import {
 	compareRevisionAsc,
 	parseRawBDCFile,
@@ -21,7 +21,7 @@ import {
 	type BDCStateSubCategory,
 	type BDCSummarySubCategory,
 	type RawBDCFile,
-} from "./common.ts"
+} from "#sdk/common"
 
 export interface RetrieveProviderAvailabilityFilesParams {
 	/**

package/{sdk → lib/sdk}/nearest-infrastructure.ts

@@ -34,13 +34,13 @@
  *   spines agree without this module hardcoding a resolution of its own.
  */
 
-import type { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { readLayerCoverage, type CoverageCell, type LayerContractDatabase } from "@mailwoman/core/layers"
-import { POI_H3_RESOLUTION, type POILookup } from "@mailwoman/resolver-wof-sqlite/poi-lookup"
+import { readLayerCoverage, type CoverageCell, type LayerContractHandle } from "@mailwoman/core/layers"
+import { POI_H3_RESOLUTION, type POILookup } from "@mailwoman/resolver-wof-sqlite/poi"
 import { shortCellToInt, type H3Cell, type PointLiteral } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { latLngToCell } from "h3-js"
 
-import { res9ShortCellToRes6Parent } from "./filing-landscape.ts"
+import { res9ShortCellToRes6Parent } from "#sdk/filing-landscape"
 
 /**
  * Ring budget default for {@link nearestInfrastructure} — wider than `POILookup`'s own internal `DEFAULT_MAX_RINGS`
@@ -89,7 +89,7 @@ export interface NearestInfrastructureOptions {
  */
 export async function nearestInfrastructure(
 	poiLookup: POILookup,
-	contractDB: DatabaseClient<LayerContractDatabase>,
+	contractDB: LayerContractHandle & Pick<DatabaseClient, "destroy">,
 	options: NearestInfrastructureOptions
 ): Promise<InfrastructureHit[]> {
 	const [longitude, latitude] = options.center.coordinates

package/lib/sdk/parsing.ts

@@ -0,0 +1,157 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC BDC availability CSV row reader.
+ *
+ *   Streams the FCC's 12-column availability CSV through `CSVSpliterator` in `array` mode and projects the
+ *   seven columns 2a keeps. Columns 0-2 (`frn`, `provider_id`, `brand_name`) and 9, 11 (`state_usps`,
+ *   `h3_res8_id`) are read past and never emitted: `provider_id` comes from the {@linkcode ProviderID}
+ *   parameter instead (the FCC partitions availability files per provider, so the caller already knows it),
+ *   and FRN/brand/state/H3 join concerns are a 2c registry-join boundary.
+ *
+ *   Two projection decisions are required and pre-registered. `location_id` (column 3) stays a STRING —
+ *   the FCC's values are zero-padded 10-digit strings and `parseInt` would lose the leading zeros (decision
+ *   1). `geoid` (column 10) is a string joining `TIGERBlockTable.GEOID` (decision 3).
+ *
+ *   ## Why the source is a resource, not a Buffer
+ *
+ *   This read is STREAMING because the files do not fit the alternative. One state × one technology —
+ *   `bdc_48_FibertothePremises_fixed_broadband_D25` — is 920 MB and 10,369,043 rows, and a national run
+ *   spans every state × every technology. The previous byte scanner took a `Buffer`, so its caller opened
+ *   with `readFile(csvPath)` and held the whole file resident per file.
+ *
+ *   ## Why quoting is not optional here
+ *
+ *   Measured on that same file: 421,555 rows carry one embedded comma inside a quoted `brand_name` and 327
+ *   carry two ("FiberFirst, LLC", "Valor Telecommunications of Texas, LP"). A delimiter scan blind to quotes
+ *   shifts every column right of `brand_name` on 4% of rows — measured exactly, a quote-blind
+ *   `String.split(",")` mismatches 81,095 of 2,000,000 real rows. `enableQuoteHandling` also keeps an
+ *   embedded NEWLINE inside its row — no row in that file needs it (the 12/13/14-field line counts sum
+ *   exactly to `wc -l`, so no record is split across lines), but the guarantee is what makes the reader safe
+ *   on a file nobody has measured yet.
+ *
+ *   ## What this costs
+ *
+ *   Measured on the full 920 MB / 10,369,042-row file, projecting these 7 of 12 columns, identical checksums
+ *   across every arm. One arm per process — arms sharing a process mis-rank, because the JIT warms across
+ *   them:
+ *
+ *   ```
+ *   hand-rolled byte scan, whole buffer   778 ns/row   peak RSS 978 MB
+ *   spliterator 6.2.0, streaming        2,435 ns/row   peak RSS 112 MB
+ *   spliterator patched, streaming        860 ns/row   peak RSS 100 MB
+ *   ```
+ *
+ *   The 6.2.0 row is why this looked like a regression when it landed: CSVSpliterator decoded once per
+ *   COLUMN, and `TextDecoder`'s per-call overhead dominates at column sizes. Fixed upstream in
+ *   sister-software/spliterator#6 by decoding the row once — so the streaming path now runs within 10% of a
+ *   whole-buffer byte scan while holding 9.8x less memory. **Requires a spliterator release carrying that
+ *   fix**; on 6.2.0 this reader is correct and roughly 3x slower.
+ *
+ *   Do not route around it by hand-rolling a splitter here again. The staging insert this feeds measures 615
+ *   ns/row, so the parse does sit on the critical path — but a local fast-and-quote-blind parser is exactly
+ *   the trade that produced the scanner this replaced, and the quote-blind version is 4% wrong.
+ */
+
+import type { AsyncDataResource } from "spliterator"
+import { CSVSpliterator } from "spliterator"
+
+import type { ProviderID } from "#sdk/common"
+
+/**
+ * Column positions in the FCC's 12-column availability CSV. Named rather than sliced by offset so a reader can check
+ * them against the header row without counting commas:
+ *
+ * `frn,provider_id,brand_name,location_id,technology,max_advertised_download_speed,`
+ * `max_advertised_upload_speed,low_latency,business_residential_code,state_usps,block_geoid,h3_res8_id`
+ */
+const Column = {
+	LocationID: 3,
+	Technology: 4,
+	MaxAdvertisedDownloadSpeed: 5,
+	MaxAdvertisedUploadSpeed: 6,
+	LowLatency: 7,
+	BusinessResidentialCode: 8,
+	BlockGeoID: 10,
+} as const
+
+/**
+ * A single parsed row of FCC BDC availability data.
+ *
+ * @see {@linkcode readAvailabilityRows}
+ */
+export interface BDCAvailabilityRow {
+	provider_id: number
+	/**
+	 * Kept as a string — the FCC's `location_id` values are zero-padded 10-digit strings; `parseInt`ing would lose
+	 * leading zeros (2a decision 1).
+	 */
+	location_id: string
+	technology_code: number
+	max_advertised_download_speed: number
+	max_advertised_upload_speed: number
+	low_latency: 0 | 1
+	business_residential_code: string
+	/**
+	 * Joins `TIGERBlockTable.GEOID` (note: uppercase column on that side) — 2a decision 3.
+	 */
+	geoid: string
+}
+
+/**
+ * Project one already-split CSV row onto {@linkcode BDCAvailabilityRow}.
+ *
+ * Separate from the iteration so the sync and async readers cannot drift in what they emit — the one-function
+ * discipline. Not exported: a caller with a split row wants {@linkcode readAvailabilityRowsSync}.
+ */
+function projectRow(columns: readonly string[], providerID: ProviderID): BDCAvailabilityRow {
+	return {
+		provider_id: providerID,
+		location_id: columns[Column.LocationID] ?? "",
+		technology_code: Number.parseInt(columns[Column.Technology] ?? "", 10),
+		max_advertised_download_speed: Number.parseInt(columns[Column.MaxAdvertisedDownloadSpeed] ?? "", 10),
+		max_advertised_upload_speed: Number.parseInt(columns[Column.MaxAdvertisedUploadSpeed] ?? "", 10),
+		low_latency: columns[Column.LowLatency] === "1" ? 1 : 0,
+		business_residential_code: columns[Column.BusinessResidentialCode] ?? "",
+		geoid: columns[Column.BlockGeoID] ?? "",
+	}
+}
+
+/**
+ * Shared reader options. `header: true` consumes the first row as the header even in `array` mode;
+ * `enableQuoteHandling` is what makes the 421,882 quoted-brand rows keep their column alignment. `crlf` already
+ * defaults to `true` for CSV (RFC 4180), so a CRLF file does not leak `\r` into the last column.
+ */
+const READER_OPTIONS = { mode: "array", enableQuoteHandling: true } as const
+
+/**
+ * Stream an FCC BDC availability CSV, yielding every data row. The header row is consumed, never emitted.
+ *
+ * `source` is anything `spliterator` can open asynchronously — a path string, a `path-ts` builder, a URL, a file
+ * handle, or an async chunk iterator. Prefer handing it the path and letting it own the read: that is what keeps a 920
+ * MB file off the heap.
+ */
+export async function* readAvailabilityRows(
+	source: AsyncDataResource,
+	providerID: ProviderID
+): AsyncIterable<BDCAvailabilityRow> {
+	for await (const columns of CSVSpliterator.fromAsync<string[]>(source, READER_OPTIONS)) {
+		yield projectRow(columns, providerID)
+	}
+}
+
+/**
+ * Synchronous sibling for an in-memory buffer — fixtures and tests, never the build path.
+ *
+ * Kept because a test that must assert on a literal CSV should not have to stand up a stream to do it. If you are
+ * reaching for this against a file on disk, reach for {@linkcode readAvailabilityRows} instead.
+ */
+export function* readAvailabilityRowsSync(
+	csvBuffer: Buffer | string,
+	providerID: ProviderID
+): Iterable<BDCAvailabilityRow> {
+	for (const columns of CSVSpliterator.from<string[]>(csvBuffer, READER_OPTIONS)) {
+		yield projectRow(columns, providerID)
+	}
+}