@mailwoman/bdc 8.3.0

package/sdk/filing-dates.ts

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC BDC filing-date discovery + vintage resolution.
+ *
+ *   Re-homed from Nexus's `sync/fcc/bdc/filing-dates.ts` (relicense-by-copy, no provenance
+ *   headers): the `$BCDClient`-bound `retrieveFilingDates()` → a plain function taking a
+ *   {@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)
+ *   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
+ *   vintage once would never see the next one FCC published without an explicit `skipCache`. The
+ *   client's cache has a TTL chosen against the filing cadence, and `skipCache` now maps onto a
+ *   per-request cache bypass with the same meaning it always had.
+ */
+
+import type { BDCClient } from "./client.ts"
+import type { BDCFilingDataType } from "./common.ts"
+
+/**
+ * One entry from the FCC BDC's `/map/listAsOfDates` endpoint.
+ */
+export interface FCCAsOfDateEntry {
+	data_type: BDCFilingDataType
+	/**
+	 * @format date
+	 */
+	as_of_date: string
+}
+
+interface ListAsOfDatesResponseBody {
+	data: FCCAsOfDateEntry[]
+}
+
+export interface RetrieveFilingDatesParams {
+	/**
+	 * Which filing type's dates to return — the full cached/fetched set is filtered down to this type.
+	 */
+	filingType: BDCFilingDataType
+	/**
+	 * Bypass the client's response cache and always fetch fresh from the API. Defaults to `false`.
+	 */
+	skipCache?: boolean
+}
+
+/**
+ * Retrieve the FCC BDC's available filing `as_of_date`s for a given filing type.
+ *
+ * One `listAsOfDates` call answers every filing type — the full unfiltered response is what the client caches, and this
+ * filters it down on read — so asking for a second filing type inside the TTL costs no request at all. At ten requests
+ * per minute that is worth six seconds each time.
+ */
+export async function retrieveFilingDates(
+	client: BDCClient,
+	{ filingType, skipCache = false }: RetrieveFilingDatesParams
+): Promise<FCCAsOfDateEntry[]> {
+	const body = await client.get<ListAsOfDatesResponseBody>("/map/listAsOfDates", undefined, { skipCache })
+
+	return body.data.filter((entry) => entry.data_type === filingType)
+}
+
+/**
+ * Pick the latest (most recent) `as_of_date` among `entries` for the given `dataType`.
+ *
+ * Comparison is by parsed `Date` value, not string ordering — the FCC's `as_of_date` values are `date`-formatted
+ * (`YYYY-MM-DD`), which happens to sort correctly as strings too, but comparing as dates is the honest contract.
+ */
+export function resolveLatestVintage(entries: readonly FCCAsOfDateEntry[], dataType: BDCFilingDataType): string {
+	const matching = entries.filter((entry) => entry.data_type === dataType)
+
+	if (!matching.length) {
+		throw new Error(`resolveLatestVintage: no filing-date entries found for data_type "${dataType}"`)
+	}
+
+	let latest = matching[0]!
+
+	for (const entry of matching) {
+		if (new Date(entry.as_of_date).getTime() > new Date(latest.as_of_date).getTime()) {
+			latest = entry
+		}
+	}
+
+	return latest.as_of_date
+}

package/sdk/filing-landscape.ts

@@ -0,0 +1,287 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `filing_landscape` reader (2a Task 9) — 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.
+ *
+ *   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
+ *   was never surveyed, and the block is reported in `unknown_block_count`, NEVER folded into a
+ *   zero-filing claim.
+ *
+ *   - For a `geoids` query, the candidate res-9 cell is read off the block's OWN `bdc_availability`
+ *     rows — a geoid with zero rows has no derivable cell at all (never guessed, matching the builder's
+ *     "unknown geoid" discipline in `build-bdc.ts`), so it falls straight to unknown.
+ *   - For an `h3Cells` query, the caller supplies the res-9 cell directly, so coverage can be checked
+ *     even for a cell with no filing rows of its own — a genuine "surveyed, zero providers here" result,
+ *     the meaning-of-zero rule's POSITIVE case (covered but empty is not the same as never surveyed).
+ *
+ *   Res-9 → res-6 parent reconstruction is deliberately NOT `@mailwoman/spatial`'s `expandH3Cell` — that
+ *   helper's left-shift reconstruction only round-trips a short cell that was shortened AT resolution
+ *   15 (the address-id spine); fed a resolution-9 short cell it silently produces a full index
+ *   `cellToParent` rejects (`Cell arguments had incompatible resolutions`), verified empirically while
+ *   building this reader. The correct reconstruction for a short cell captured at a KNOWN resolution R
+ *   is a straight concatenation, not a shift: a full 64-bit H3 cell index is always
+ *   `"8" + <resolution nibble> + <52 bits of base-cell + digit path, trailing padding included>`, and
+ *   the 48-bit "short" form (`shortCellToInt`/`shortenH3Cell`) already carries exactly those low 52 bits
+ *   verbatim — so `"8" + R.toString(16) + shortHex.padStart(13, "0")` reassembles the identical full
+ *   index `latLngToCell` would have produced at resolution R. See {@link res9ShortCellToRes6Parent}.
+ *
+ *   This same formula is exactly what `build-bdc.ts` MUST use (and does, after fix round 1) to derive the
+ *   coverage cell it writes at build time — H3's cell hierarchy is not geometrically exact, so a
+ *   `latLngToCell(centroid, 6)` computed independently of the stored res-9 cell disagrees with
+ *   `cellToParent(res9Cell, 6)` for a real fraction of points (verified ~6% over CONUS). Builder and
+ *   reader deriving the res-6 parent differently was a real bug (fix round 1): a genuinely-surveyed block
+ *   (real rows, real `layer_coverage` entry) could read back as `unknown_block_count` while its own rows
+ *   still populated `filings` — a self-contradiction. `filings` is now scoped to units that PASS the
+ *   coverage check (see the `surveyedUnits` accumulator below) precisely so that can't happen again: a
+ *   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 { shortCellToInt, type H3Cell } from "@mailwoman/spatial"
+import { cellToParent } from "h3-js"
+import { sql, type Kysely } from "kysely"
+
+import { BDC_COVERAGE_H3_RESOLUTION, BDC_H3_RESOLUTION, type BDCDatabase } from "../schema.ts"
+
+/**
+ * Exactly one of `geoids` or `h3Cells` is required — `filingLandscape` throws otherwise.
+ */
+export interface FilingLandscapeQuery {
+	geoids?: string[]
+	h3Cells?: number[]
+}
+
+/**
+ * One provider/technology/speed-bucket group's block count within the query — `block_count` is the number of DISTINCT
+ * queried blocks carrying this exact combination, never a raw row count. A block can carry multiple `bdc_availability`
+ * rows for the SAME (provider_id, technology_code) pair even in the DEFAULT (non-`includeLocationIDs`) build mode:
+ * `build-bdc.ts`'s materialize-time collapse merges to one row per distinct (geoid, provider_id, technology_code,
+ * speeds, low_latency, business_residential_code) tuple, not one row per (geoid, provider_id, technology_code) triple —
+ * so Broadband Serviceable Locations at the same triple with DIFFERING speeds/flags survive as separate rows and can
+ * land in different `speed_bucket`s here (see that file's docstring). This `block_count`'s DISTINCT is exactly what
+ * keeps that from double-counting the block itself when it does.
+ */
+export interface ProviderFilingSummary {
+	provider_id: number
+	technology_code: number
+	speed_bucket: string
+	block_count: number
+}
+
+/**
+ * The queried landscape: ALWAYS vintage-stamped (from `layer_manifest.sourceVintage`) and ALWAYS reports its unknown
+ * blocks — `unknown_block_count` is reported, never zeroed, and never evidence of "no providers file here."
+ */
+export interface FilingLandscape {
+	vintage: string
+	surveyed_block_count: number
+	unknown_block_count: number
+	filings: ProviderFilingSummary[]
+}
+
+/**
+ * `speed_bucket` label for a block whose `max_advertised_download_speed` is below
+ * {@link BDC_SPEED_BUCKET_THRESHOLD_25_MBPS} Mbps.
+ */
+export const BDC_SPEED_BUCKET_UNDER_25 = "under-25"
+
+/**
+ * `speed_bucket` label for `BDC_SPEED_BUCKET_THRESHOLD_25_MBPS <= speed < BDC_SPEED_BUCKET_THRESHOLD_100_MBPS`.
+ */
+export const BDC_SPEED_BUCKET_25_100 = "25-100"
+
+/**
+ * `speed_bucket` label for `BDC_SPEED_BUCKET_THRESHOLD_100_MBPS <= speed < BDC_SPEED_BUCKET_THRESHOLD_GIGABIT_MBPS`.
+ */
+export const BDC_SPEED_BUCKET_100_1000 = "100-1000"
+
+/**
+ * `speed_bucket` label for a block whose `max_advertised_download_speed` is at or above
+ * {@link BDC_SPEED_BUCKET_THRESHOLD_GIGABIT_MBPS} Mbps.
+ */
+export const BDC_SPEED_BUCKET_GIGABIT = "gigabit"
+
+/**
+ * Upper-exclusive Mbps boundary between {@link BDC_SPEED_BUCKET_UNDER_25} and {@link BDC_SPEED_BUCKET_25_100}.
+ */
+export const BDC_SPEED_BUCKET_THRESHOLD_25_MBPS = 25
+
+/**
+ * Upper-exclusive Mbps boundary between {@link BDC_SPEED_BUCKET_25_100} and {@link BDC_SPEED_BUCKET_100_1000}.
+ */
+export const BDC_SPEED_BUCKET_THRESHOLD_100_MBPS = 100
+
+/**
+ * Mbps boundary at/above which a block is bucketed {@link BDC_SPEED_BUCKET_GIGABIT}.
+ */
+export const BDC_SPEED_BUCKET_THRESHOLD_GIGABIT_MBPS = 1000
+
+/**
+ * Pure mirror of the SQL `CASE` expression below ({@link speedBucketCaseSQL}) — same thresholds, same labels, exported
+ * so the boundary logic can be asserted directly without a database round trip.
+ */
+export function speedBucketForDownloadSpeed(maxAdvertisedDownloadSpeed: number): string {
+	if (maxAdvertisedDownloadSpeed < BDC_SPEED_BUCKET_THRESHOLD_25_MBPS) return BDC_SPEED_BUCKET_UNDER_25
+
+	if (maxAdvertisedDownloadSpeed < BDC_SPEED_BUCKET_THRESHOLD_100_MBPS) return BDC_SPEED_BUCKET_25_100
+
+	if (maxAdvertisedDownloadSpeed < BDC_SPEED_BUCKET_THRESHOLD_GIGABIT_MBPS) return BDC_SPEED_BUCKET_100_1000
+
+	return BDC_SPEED_BUCKET_GIGABIT
+}
+
+/**
+ * The same bucketing as {@link speedBucketForDownloadSpeed}, expressed as a `CASE` over `max_advertised_download_speed`
+ * so the GROUP BY below can group directly on the bucket.
+ */
+const speedBucketCaseSQL = sql<string>`CASE
+	WHEN max_advertised_download_speed < ${BDC_SPEED_BUCKET_THRESHOLD_25_MBPS} THEN ${BDC_SPEED_BUCKET_UNDER_25}
+	WHEN max_advertised_download_speed < ${BDC_SPEED_BUCKET_THRESHOLD_100_MBPS} THEN ${BDC_SPEED_BUCKET_25_100}
+	WHEN max_advertised_download_speed < ${BDC_SPEED_BUCKET_THRESHOLD_GIGABIT_MBPS} THEN ${BDC_SPEED_BUCKET_100_1000}
+	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 this
+ * isn't `@mailwoman/spatial`'s `expandH3Cell`. Exported so tests can assert this agrees, cell-for-cell, with
+ * `build-bdc.ts`'s own coverage-cell derivation (the two MUST share this exact formula — see that file's docstring).
+ */
+export function res9ShortCellToRes6Parent(h3CellShortInt: number): number {
+	const shortHex = h3CellShortInt.toString(16).padStart(13, "0")
+	const fullCell = `8${BDC_H3_RESOLUTION.toString(16)}${shortHex}` as H3Cell
+	const parentCell = cellToParent(fullCell, BDC_COVERAGE_H3_RESOLUTION) as H3Cell
+
+	return shortCellToInt(parentCell)
+}
+
+/**
+ * Read the provider/technology/speed-bucket filing census over a set of queried blocks (by `geoid` or by `h3Cell`,
+ * never both). Always vintage-stamped; always throws on a broken manifest rather than answering unstamped; a queried
+ * block with no coverage evidence is reported in `unknown_block_count` and never folded into a zero-filing claim.
+ */
+export async function filingLandscape(
+	db: DatabaseClient<BDCDatabase>,
+	query: FilingLandscapeQuery
+): Promise<FilingLandscape> {
+	const queryModeCount = (query.geoids ? 1 : 0) + (query.h3Cells ? 1 : 0)
+
+	if (queryModeCount !== 1) {
+		throw new Error("filingLandscape: exactly one of `geoids` or `h3Cells` is required")
+	}
+
+	// `[]` is truthy, so it passes the XOR check above undetected — without this guard an empty array sails
+	// straight through to a vacuous all-zero landscape (surveyed_block_count: 0, unknown_block_count: 0, no
+	// filings), which reads exactly like a real "nothing queried" answer instead of the malformed-query error
+	// it should be. Checked before the manifest read so a bad query fails fast without even opening the db further.
+	if (!(query.geoids ?? query.h3Cells)!.length) {
+		throw new Error("filingLandscape: `geoids`/`h3Cells` must not be an empty array")
+	}
+
+	// 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))
+
+	const requestedUnits: ReadonlyArray<string | number> = query.geoids ?? query.h3Cells!
+	const unitColumn = query.geoids ? ("geoid" as const) : ("h3_cell" as const)
+
+	// Candidate res-9 cell per requested unit. `h3Cells` queries already carry the cell directly;
+	// `geoids` queries can only derive one from the block's OWN rows — a geoid with none has no
+	// candidate at all (never guessed), so it falls straight to unknown below.
+	const candidateCellByUnit = new Map<string | number, number>()
+
+	if (query.geoids) {
+		const rows = await db
+			.selectFrom("bdc_availability")
+			.select(["geoid", "h3_cell"])
+			.where("geoid", "in", query.geoids)
+			.groupBy(["geoid", "h3_cell"])
+			.execute()
+
+		for (const row of rows) {
+			candidateCellByUnit.set(row.geoid, row.h3_cell)
+		}
+	} else {
+		for (const cell of query.h3Cells!) {
+			candidateCellByUnit.set(cell, cell)
+		}
+	}
+
+	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
+	// 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).
+	const surveyedUnits: Array<string | number> = []
+
+	for (const unit of requestedUnits) {
+		const candidateCell = candidateCellByUnit.get(unit)
+
+		if (candidateCell === undefined) {
+			unknownBlockCount++
+
+			continue
+		}
+
+		const res6Parent = res9ShortCellToRes6Parent(candidateCell)
+		const coverage = await readLayerCoverage(asContractDB(db), res6Parent)
+
+		if (coverage === undefined) {
+			unknownBlockCount++
+		} else {
+			surveyedBlockCount++
+			surveyedUnits.push(unit)
+		}
+	}
+
+	let filings: ProviderFilingSummary[] = []
+
+	if (surveyedUnits.length) {
+		let filingsQuery = db
+			.selectFrom("bdc_availability")
+			.select([
+				"provider_id",
+				"technology_code",
+				speedBucketCaseSQL.as("speed_bucket"),
+				(eb) => eb.fn.count<number>(unitColumn).distinct().as("block_count"),
+			])
+			.groupBy(["provider_id", "technology_code", speedBucketCaseSQL])
+			.orderBy("provider_id")
+			.orderBy("technology_code")
+			.orderBy(speedBucketCaseSQL)
+
+		filingsQuery = query.geoids
+			? filingsQuery.where("geoid", "in", surveyedUnits as string[])
+			: filingsQuery.where("h3_cell", "in", surveyedUnits as number[])
+
+		const filingsRows = await filingsQuery.execute()
+
+		filings = filingsRows.map((row) => ({
+			provider_id: row.provider_id,
+			technology_code: row.technology_code,
+			speed_bucket: row.speed_bucket,
+			block_count: row.block_count,
+		}))
+	}
+
+	return {
+		vintage: manifest.sourceVintage,
+		surveyed_block_count: surveyedBlockCount,
+		unknown_block_count: unknownBlockCount,
+		filings,
+	}
+}

package/sdk/index.ts

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

package/sdk/list-files.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC BDC availability-file listing.
+ *
+ *   Re-homed from Nexus's `sync/fcc/bdc/list-files.ts` (relicense-by-copy, no provenance headers):
+ *   the `URLRoutePattern`-compiled route → a plain template literal (this port has no routing
+ *   dependency), the `$BCDClient`-bound `retrieveAvailabilityFiles()` → a plain function taking a
+ *   {@linkcode BDCClient}. Raw entries are parsed via Task 4's `parseRawBDCFile` and returned sorted
+ *   ascending by revision (`compareRevisionAsc`) rather than in API order.
+ */
+
+import type { BDCClient } from "./client.ts"
+import {
+	compareRevisionAsc,
+	parseRawBDCFile,
+	type BDCFile,
+	type BDCFileCategory,
+	type BDCProviderSubCategory,
+	type BDCStateSubCategory,
+	type BDCSummarySubCategory,
+	type RawBDCFile,
+} from "./common.ts"
+
+export interface RetrieveProviderAvailabilityFilesParams {
+	/**
+	 * The filing's `as_of_date`, e.g. from {@linkcode file://./filing-dates.ts#resolveLatestVintage}.
+	 */
+	asOfDate: string
+	category: typeof BDCFileCategory.Provider
+	subcategory: BDCProviderSubCategory
+}
+
+export interface RetrieveStateAvailabilityFilesParams {
+	asOfDate: string
+	category: typeof BDCFileCategory.State
+	subcategory: BDCStateSubCategory
+}
+
+export interface RetrieveSummaryAvailabilityFilesParams {
+	asOfDate: string
+	category: typeof BDCFileCategory.Summary
+	subcategory: BDCSummarySubCategory
+}
+
+export type RetrieveAvailabilityFilesParams =
+	| RetrieveProviderAvailabilityFilesParams
+	| RetrieveStateAvailabilityFilesParams
+	| RetrieveSummaryAvailabilityFilesParams
+
+interface ListAvailabilityDataResponseBody {
+	data: RawBDCFile[]
+}
+
+/**
+ * List the BDC availability files for a given `as_of_date`/category/subcategory, parsed into {@linkcode BDCFile}
+ * records and sorted ascending by revision date ({@linkcode compareRevisionAsc}).
+ */
+export async function retrieveAvailabilityFiles(
+	client: BDCClient,
+	{ asOfDate, category, subcategory }: RetrieveAvailabilityFilesParams
+): Promise<BDCFile[]> {
+	const pathname = `/map/downloads/listAvailabilityData/${encodeURIComponent(asOfDate)}`
+
+	const body = await client.get<ListAvailabilityDataResponseBody>(pathname, {
+		category,
+		subcategory,
+	})
+
+	return body.data.map(parseRawBDCFile).toSorted(compareRevisionAsc)
+}

package/sdk/location.ts

@@ -0,0 +1,45 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { Tagged } from "type-fest"
+
+/**
+ * Matches a 10-digit FCC Broadband Serviceable Location ID, leading zeros included.
+ *
+ * @see {@linkcode isBroadbandServicableLocationID} for the type-predicate that uses this.
+ */
+export const BROADBAND_SERVICABLE_LOCATION_INPUT_PATTERN = /^\d{10}$/
+
+/**
+ * Unique ID for the Fabric location.
+ *
+ * The BSL ID remains persistent version to version when newer evidence indicates the position of the serviceable
+ * location or the presence of a serviceable location on a single location parcel is not significantly changed as
+ * compared to the prior version.
+ *
+ * - While IDs persist across Fabric versions does not mean that the latitude and longitude are unchanged.
+ * - An ID will remain consistent across versions when a different building is selected on a single parcel.
+ *
+ * Typed as a `string`, not a `number` — the FCC's own IDs are 10-digit zero-padded strings, and leading zeros make
+ * integer storage lossy.
+ *
+ * @type string
+ * @title Broadband Servicable Location ID
+ * @pattern ^\d{10}$
+ */
+export type BroadbandServicableLocationID = Tagged<string, "BroadbandServicableLocationID">
+
+/**
+ * Type-predicate for checking if a value appears to be a valid Broadband Servicable Location ID.
+ *
+ * Accepts only a 10-digit string. A `number` input is always rejected, even if its digits would otherwise match —
+ * numeric storage would silently drop meaningful leading zeros.
+ *
+ * @internal
+ */
+export function isBroadbandServicableLocationID(input: unknown): input is BroadbandServicableLocationID {
+	return typeof input === "string" && BROADBAND_SERVICABLE_LOCATION_INPUT_PATTERN.test(input)
+}

package/sdk/nearest-infrastructure.ts

@@ -0,0 +1,129 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `nearestInfrastructure` — a coverage-paired k-nearest read over the telecom-infrastructure POI
+ *   categories (`telecom_exchange`/`tower_comms`, poi-taxonomy task 1 + the `--source osm` extractor,
+ *   2b tasks 1–2) that a caller can join against ANY layer's own `layer_coverage` survey-completeness
+ *   table (2b task 4, decision 7). Typical caller: a BDC filing scorer that wants "what's the nearest
+ *   real infrastructure to this claimed Broadband Serviceable Location, and does OUR layer even have
+ *   survey evidence for that area" in one call.
+ *
+ *   Two deviations from the task brief's literal sketch, both forced by what `poi-lookup.ts` and
+ *   `@mailwoman/core/layers` actually expose (documented per the brief's "implementer picks and
+ *   documents" instruction):
+ *
+ *   - **`poiLookup` is an already-open {@link POILookup}, not a `POILookupOpts` this function
+ *     constructs itself.** `POILookup`'s constructor eagerly loads the poi-taxonomy category dictionary
+ *     and prepares three statements (see `poi-lookup.ts`) — reconstructing that per call would mean
+ *     re-opening the SQLite handle and re-running the dictionary `SELECT` on every single
+ *     `nearestInfrastructure` invocation. A scorer calling this once per filing candidate wants to open
+ *     `poi.db` ONCE and reuse the same `POILookup` — this wrapper takes that shape: the caller owns
+ *     `POILookup`'s open/dispose lifecycle (`using poiLookup = new POILookup(...)`), we just call
+ *     `.search()` on it.
+ *   - **`nearestInfrastructure` is `async`, not the brief's sync sketch.** `readLayerCoverage`
+ *     (`@mailwoman/core/layers`) is `Promise`-returning — every layer-contract read in this codebase is
+ *     (`readLayerManifest`, `filingLandscape` itself) — so pairing each POI hit with its coverage cell
+ *     means awaiting one `readLayerCoverage` call per hit. A sync signature can't await that.
+ *
+ *   {@link res9ShortCellToRes6Parent} (exported by `filing-landscape.ts`; see that file's docstring for
+ *   why the res-9 → res-6 reconstruction is a straight concatenation, not `@mailwoman/spatial`'s
+ *   `expandH3Cell`) turns each hit's res-9 cell into the res-6 cell every layer in this repo aggregates
+ *   coverage at (poi.db's own convention; `bdc.db`'s `BDC_COVERAGE_H3_RESOLUTION` matches it
+ *   deliberately — see `schema.ts`). `POI_H3_RESOLUTION` (`poi-lookup.ts`) is ALSO 9, so the two layers'
+ *   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 { shortCellToInt, type H3Cell, type PointLiteral } from "@mailwoman/spatial"
+import { latLngToCell } from "h3-js"
+
+import { res9ShortCellToRes6Parent } from "./filing-landscape.ts"
+
+/**
+ * Ring budget default for {@link nearestInfrastructure} — wider than `POILookup`'s own internal `DEFAULT_MAX_RINGS`
+ * (16, ≈5.4 km) because telecom infrastructure (central offices, comm towers) is sparser per-area than poi.db's dense
+ * categories (cafes, etc.): 32 res-9 rings ≈ 11 km, a BDC-block-scale search radius that gives real infrastructure room
+ * to be found without over-restricting callers who DO want a tighter budget via `options.maxRings`.
+ */
+export const NEAREST_INFRASTRUCTURE_DEFAULT_MAX_RINGS = 32
+
+/**
+ * One k-nearest telecom-infrastructure hit, paired with the res-6 coverage cell it falls in. `coverage: undefined`
+ * means `contractDB`'s layer has never surveyed that area (the meaning-of-zero rule; see `@mailwoman/core/layers`) —
+ * never conflate it with a covered-but-empty cell.
+ */
+export interface InfrastructureHit {
+	categoryID: string
+	name: string | null
+	distanceM: number
+	/**
+	 * Res-9 short H3 cell of the hit ITSELF — not the (coarser) coverage cell; see `coverage.h3Cell` for that.
+	 */
+	h3Cell: number
+	coverage: CoverageCell | undefined
+}
+
+export interface NearestInfrastructureOptions {
+	center: PointLiteral
+	/**
+	 * Poi-taxonomy category ids to search — fans out to `POILookup.search`'s `categoryIDs` (union across every resolved
+	 * leaf, nearest-first). Typically `["telecom_exchange", "tower_comms"]`.
+	 */
+	categoryIDs: string[]
+	limit?: number
+	/**
+	 * Ring budget. Default {@link NEAREST_INFRASTRUCTURE_DEFAULT_MAX_RINGS} (32) — NOT `POILookup`'s own internal default
+	 * (16); see this module's docstring.
+	 */
+	maxRings?: number
+}
+
+/**
+ * K-nearest telecom-infrastructure POIs from `options.center`, each paired with the coverage cell it falls in per
+ * `contractDB`'s own `layer_coverage` table. Never throws on a sparse result — no infrastructure within `maxRings`, or
+ * every `categoryIDs` entry unresolvable against `poiLookup`'s dictionary — returns `[]`, the same discipline
+ * `POILookup.search` itself follows.
+ */
+export async function nearestInfrastructure(
+	poiLookup: POILookup,
+	contractDB: DatabaseClient<LayerContractDatabase>,
+	options: NearestInfrastructureOptions
+): Promise<InfrastructureHit[]> {
+	const [longitude, latitude] = options.center.coordinates
+
+	const hits = poiLookup.search({
+		categoryIDs: options.categoryIDs,
+		center: { latitude, longitude },
+		limit: options.limit,
+		maxRings: options.maxRings ?? NEAREST_INFRASTRUCTURE_DEFAULT_MAX_RINGS,
+	})
+
+	const infrastructureHits: InfrastructureHit[] = []
+
+	for (const hit of hits) {
+		if (hit.categoryID === null) {
+			// `categoryIDs` above always constrains the k-ring probe to real (non-zero) category ids (see
+			// POILookup#searchKRing), so a hit here always carries the category it was found under — this
+			// can't happen without a corrupted poi.db. Guard rather than silently coerce to "".
+			throw new Error(`nearestInfrastructure: hit ${JSON.stringify(hit.name)} has no categoryID`)
+		}
+
+		const h3Cell = shortCellToInt(latLngToCell(hit.latitude, hit.longitude, POI_H3_RESOLUTION) as H3Cell)
+		const coverage = await readLayerCoverage(contractDB, res9ShortCellToRes6Parent(h3Cell))
+
+		infrastructureHits.push({
+			categoryID: hit.categoryID,
+			name: hit.name,
+			// `center` is always supplied above, so POILookup.search always attaches distanceM.
+			distanceM: hit.distanceM!,
+			h3Cell,
+			coverage,
+		})
+	}
+
+	return infrastructureHits
+}