@mailwoman/bdc 8.3.0

package/out/sdk/index.d.ts

@@ -0,0 +1,15 @@
+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";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../sdk/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA"}

package/out/sdk/index.js

@@ -0,0 +1,15 @@
+export * from "./build-bdc.js";
+export * from "./buildings.js";
+export * from "./client.js";
+export * from "./common.js";
+export * from "./data-collection.js";
+export * from "./download.js";
+export * from "./filing-dates.js";
+export * from "./filing-landscape.js";
+export * from "./list-files.js";
+export * from "./location.js";
+export * from "./nearest-infrastructure.js";
+export * from "./parsing.js";
+export * from "./plausibility.js";
+export * from "./technologies.js";
+//# sourceMappingURL=index.js.map

package/out/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../sdk/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA"}

package/out/sdk/list-files.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 { type BDCFile, type BDCFileCategory, type BDCProviderSubCategory, type BDCStateSubCategory, type BDCSummarySubCategory } 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;
+/**
+ * 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 declare function retrieveAvailabilityFiles(client: BDCClient, { asOfDate, category, subcategory }: RetrieveAvailabilityFilesParams): Promise<BDCFile[]>;
+//# sourceMappingURL=list-files.d.ts.map

package/out/sdk/list-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-files.d.ts","sourceRoot":"","sources":["../../sdk/list-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAGN,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAE1B,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,uCAAuC;IACvD;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,eAAe,CAAC,QAAQ,CAAA;IACzC,WAAW,EAAE,sBAAsB,CAAA;CACnC;AAED,MAAM,WAAW,oCAAoC;IACpD,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,eAAe,CAAC,KAAK,CAAA;IACtC,WAAW,EAAE,mBAAmB,CAAA;CAChC;AAED,MAAM,WAAW,sCAAsC;IACtD,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,eAAe,CAAC,OAAO,CAAA;IACxC,WAAW,EAAE,qBAAqB,CAAA;CAClC;AAED,MAAM,MAAM,+BAA+B,GACxC,uCAAuC,GACvC,oCAAoC,GACpC,sCAAsC,CAAA;AAMzC;;;GAGG;AACH,wBAAsB,yBAAyB,CAC9C,MAAM,EAAE,SAAS,EACjB,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,+BAA+B,GAClE,OAAO,CAAC,OAAO,EAAE,CAAC,CASpB"}

package/out/sdk/list-files.js

@@ -0,0 +1,26 @@
+/**
+ * @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 { compareRevisionAsc, parseRawBDCFile, } from "./common.js";
+/**
+ * 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, { asOfDate, category, subcategory }) {
+    const pathname = `/map/downloads/listAvailabilityData/${encodeURIComponent(asOfDate)}`;
+    const body = await client.get(pathname, {
+        category,
+        subcategory,
+    });
+    return body.data.map(parseRawBDCFile).toSorted(compareRevisionAsc);
+}
+//# sourceMappingURL=list-files.js.map

package/out/sdk/list-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-files.js","sourceRoot":"","sources":["../../sdk/list-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACN,kBAAkB,EAClB,eAAe,GAOf,MAAM,aAAa,CAAA;AAgCpB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC9C,MAAiB,EACjB,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAmC;IAEpE,MAAM,QAAQ,GAAG,uCAAuC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAA;IAEtF,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAmC,QAAQ,EAAE;QACzE,QAAQ;QACR,WAAW;KACX,CAAC,CAAA;IAEF,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAA;AACnE,CAAC"}

package/out/sdk/location.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 declare const BROADBAND_SERVICABLE_LOCATION_INPUT_PATTERN: RegExp;
+/**
+ * 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 declare function isBroadbandServicableLocationID(input: unknown): input is BroadbandServicableLocationID;
+//# sourceMappingURL=location.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../sdk/location.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,2CAA2C,QAAa,CAAA;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,6BAA6B,GAAG,MAAM,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAA;AAE3F;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,6BAA6B,CAEtG"}

package/out/sdk/location.js

@@ -0,0 +1,23 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+/**
+ * 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}$/;
+/**
+ * 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) {
+    return typeof input === "string" && BROADBAND_SERVICABLE_LOCATION_INPUT_PATTERN.test(input);
+}
+//# sourceMappingURL=location.js.map

package/out/sdk/location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.js","sourceRoot":"","sources":["../../sdk/location.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAG,UAAU,CAAA;AAqBrE;;;;;;;GAOG;AACH,MAAM,UAAU,+BAA+B,CAAC,KAAc;IAC7D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,2CAA2C,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAC5F,CAAC"}

package/out/sdk/nearest-infrastructure.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @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 { type CoverageCell, type LayerContractDatabase } from "@mailwoman/core/layers";
+import { type POILookup } from "@mailwoman/resolver-wof-sqlite/poi-lookup";
+import { type PointLiteral } from "@mailwoman/spatial";
+/**
+ * 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 declare 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 declare function nearestInfrastructure(poiLookup: POILookup, contractDB: DatabaseClient<LayerContractDatabase>, options: NearestInfrastructureOptions): Promise<InfrastructureHit[]>;
+//# sourceMappingURL=nearest-infrastructure.d.ts.map

package/out/sdk/nearest-infrastructure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearest-infrastructure.d.ts","sourceRoot":"","sources":["../../sdk/nearest-infrastructure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACzG,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,2CAA2C,CAAA;AAC7F,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAKnF;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,KAAK,CAAA;AAE1D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;CAClC;AAED,MAAM,WAAW,4BAA4B;IAC5C,MAAM,EAAE,YAAY,CAAA;IACpB;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAC1C,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,cAAc,CAAC,qBAAqB,CAAC,EACjD,OAAO,EAAE,4BAA4B,GACnC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkC9B"}

package/out/sdk/nearest-infrastructure.js

@@ -0,0 +1,84 @@
+/**
+ * @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 { readLayerCoverage } from "@mailwoman/core/layers";
+import { POI_H3_RESOLUTION } from "@mailwoman/resolver-wof-sqlite/poi-lookup";
+import { shortCellToInt } from "@mailwoman/spatial";
+import { latLngToCell } from "h3-js";
+import { res9ShortCellToRes6Parent } from "./filing-landscape.js";
+/**
+ * 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;
+/**
+ * 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, contractDB, options) {
+    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 = [];
+    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));
+        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;
+}
+//# sourceMappingURL=nearest-infrastructure.js.map

package/out/sdk/nearest-infrastructure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearest-infrastructure.js","sourceRoot":"","sources":["../../sdk/nearest-infrastructure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,iBAAiB,EAAiD,MAAM,wBAAwB,CAAA;AACzG,OAAO,EAAE,iBAAiB,EAAkB,MAAM,2CAA2C,CAAA;AAC7F,OAAO,EAAE,cAAc,EAAkC,MAAM,oBAAoB,CAAA;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAEpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,EAAE,CAAA;AAiC1D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAC1C,SAAoB,EACpB,UAAiD,EACjD,OAAqC;IAErC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAA;IAExD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC;QAC7B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE;QAC/B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,wCAAwC;KACtE,CAAC,CAAA;IAEF,MAAM,kBAAkB,GAAwB,EAAE,CAAA;IAElD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC7B,8FAA8F;YAC9F,8FAA8F;YAC9F,oFAAoF;YACpF,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAA;QAC5F,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,iBAAiB,CAAW,CAAC,CAAA;QACrG,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAA;QAEvF,kBAAkB,CAAC,IAAI,CAAC;YACvB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,oFAAoF;YACpF,SAAS,EAAE,GAAG,CAAC,SAAU;YACzB,MAAM;YACN,QAAQ;SACR,CAAC,CAAA;IACH,CAAC;IAED,OAAO,kBAAkB,CAAA;AAC1B,CAAC"}

package/out/sdk/parsing.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC BDC availability CSV byte-level parser.
+ *
+ *   Re-homed from Nexus's `sync/fcc/bdc/parsing.ts` (relicense-by-copy, no provenance headers): the same
+ *   byte-scanning generator over the FCC's 12-column availability CSV — see the Nexus `RawBSLAvailabilityRow`
+ *   tuple (`sync/fcc/bdc/block-aggregator.ts`) for the column order this scan assumes: 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. Changed only where the
+ *   pre-registered 2a decisions require: `geoid` (column 10, `block_geoid`) decodes to an ASCII string
+ *   instead of staying a raw `Uint8Array` slice (decision 3), and `location_id` (column 3) stays a string
+ *   instead of `parseInt`ing it, preserving leading zeros (decision 1). `business_residential_code` is
+ *   likewise decoded to its ASCII string here — the Nexus original kept only the field's first raw byte as
+ *   a bare `number`, which this port's `BDCAvailabilityRow` shape doesn't call for.
+ *
+ *   Columns 0-2 (frn, provider_id, brand_name) and 9, 11 (state_usps, h3_res8_id) are scanned over but
+ *   never sliced into the output record: `provider_id` comes from the `providerID` parameter instead (the
+ *   FCC partitions availability files per provider, so the caller already knows it), and FRN/brand/state/H3
+ *   join concerns are out of scope for 2a (decision 8 — provider identity is a 2c registry-join seam).
+ */
+import type { ProviderID } from "./common.ts";
+/**
+ * A single parsed row of FCC BDC availability data.
+ *
+ * @see {@linkcode takeAvailabilityLine}
+ */
+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;
+    /**
+     * Decoded to an ASCII string at the parse boundary (2a decision 3) — joins `TIGERBlockTable.GEOID` (note: uppercase
+     * column on that side).
+     */
+    geoid: string;
+}
+/**
+ * Given a buffer containing FCC BDC availability CSV data, yield each data row (the header row is skipped) as a
+ * {@linkcode BDCAvailabilityRow}.
+ *
+ * A byte-level scan, not a general CSV parser: it tracks comma/newline byte positions directly and only toggles
+ * quote-awareness via a running double-quote count (an odd count means the scanner is currently inside a quoted field,
+ * so a comma there isn't a column delimiter) — matching the Nexus original's approach for this specific, known-shaped
+ * 12-column file rather than reaching for a general CSV library.
+ */
+export declare function takeAvailabilityLine(csvBuffer: Buffer, providerID: ProviderID): Iterable<BDCAvailabilityRow>;
+//# sourceMappingURL=parsing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parsing.d.ts","sourceRoot":"","sources":["../../sdk/parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAgB7C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,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;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;GAQG;AACH,wBAAiB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,QAAQ,CAAC,kBAAkB,CAAC,CAmD7G"}

package/out/sdk/parsing.js

@@ -0,0 +1,87 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file FCC BDC availability CSV byte-level parser.
+ *
+ *   Re-homed from Nexus's `sync/fcc/bdc/parsing.ts` (relicense-by-copy, no provenance headers): the same
+ *   byte-scanning generator over the FCC's 12-column availability CSV — see the Nexus `RawBSLAvailabilityRow`
+ *   tuple (`sync/fcc/bdc/block-aggregator.ts`) for the column order this scan assumes: 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. Changed only where the
+ *   pre-registered 2a decisions require: `geoid` (column 10, `block_geoid`) decodes to an ASCII string
+ *   instead of staying a raw `Uint8Array` slice (decision 3), and `location_id` (column 3) stays a string
+ *   instead of `parseInt`ing it, preserving leading zeros (decision 1). `business_residential_code` is
+ *   likewise decoded to its ASCII string here — the Nexus original kept only the field's first raw byte as
+ *   a bare `number`, which this port's `BDCAvailabilityRow` shape doesn't call for.
+ *
+ *   Columns 0-2 (frn, provider_id, brand_name) and 9, 11 (state_usps, h3_res8_id) are scanned over but
+ *   never sliced into the output record: `provider_id` comes from the `providerID` parameter instead (the
+ *   FCC partitions availability files per provider, so the caller already knows it), and FRN/brand/state/H3
+ *   join concerns are out of scope for 2a (decision 8 — provider identity is a 2c registry-join seam).
+ */
+/**
+ * Byte values this scanner switches on.
+ *
+ * Local to this file — no generic newline-delimited-file utility exists elsewhere in the repo to import. Nexus's
+ * equivalent (`LineDelimitedCharacter`) lived in `@isp.nexus/sdk/files`, a workspace this port doesn't carry over, and
+ * repo convention forbids TS `enum` anyway (`erasableSyntaxOnly`).
+ */
+const CSVByte = {
+    Newline: 10,
+    Comma: 44,
+    DoubleQuote: 34,
+    One: 49,
+};
+/**
+ * Given a buffer containing FCC BDC availability CSV data, yield each data row (the header row is skipped) as a
+ * {@linkcode BDCAvailabilityRow}.
+ *
+ * A byte-level scan, not a general CSV parser: it tracks comma/newline byte positions directly and only toggles
+ * quote-awareness via a running double-quote count (an odd count means the scanner is currently inside a quoted field,
+ * so a comma there isn't a column delimiter) — matching the Nexus original's approach for this specific, known-shaped
+ * 12-column file rather than reaching for a general CSV library.
+ */
+export function* takeAvailabilityLine(csvBuffer, providerID) {
+    // Skip the header row.
+    let byteIndex = csvBuffer.indexOf(CSVByte.Newline) + 1;
+    const contentDelimiters = new Uint32Array(12); // 12 columns
+    contentDelimiters[0] = byteIndex;
+    let delimiterIndex = 1;
+    let doubleQuoteCount = 0;
+    while (byteIndex < csvBuffer.length) {
+        const byte = csvBuffer[byteIndex];
+        if (byte === CSVByte.DoubleQuote) {
+            doubleQuoteCount++;
+        }
+        if (byte === CSVByte.Comma && doubleQuoteCount % 2 === 0) {
+            contentDelimiters[delimiterIndex] = byteIndex;
+            delimiterIndex++;
+        }
+        if (byte === CSVByte.Newline) {
+            contentDelimiters[delimiterIndex] = CSVByte.Newline;
+            const slices = [];
+            // Skip columns 0-2 (frn, provider_id, brand_name) — see the file header for why.
+            for (let i = 3; i < contentDelimiters.length; i++) {
+                const start = contentDelimiters[i] + 1;
+                const end = contentDelimiters[i + 1];
+                slices.push(csvBuffer.subarray(start, end));
+            }
+            const record = {
+                provider_id: providerID,
+                location_id: slices[0].toString("ascii"),
+                technology_code: Number.parseInt(slices[1].toString(), 10),
+                max_advertised_download_speed: Number.parseInt(slices[2].toString(), 10),
+                max_advertised_upload_speed: Number.parseInt(slices[3].toString(), 10),
+                low_latency: slices[4][0] === CSVByte.One ? 1 : 0,
+                business_residential_code: slices[5].toString("ascii"),
+                geoid: slices[7].toString("ascii"),
+            };
+            yield record;
+            delimiterIndex = 1;
+            doubleQuoteCount = 0;
+        }
+        byteIndex++;
+    }
+}
+//# sourceMappingURL=parsing.js.map

package/out/sdk/parsing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsing.js","sourceRoot":"","sources":["../../sdk/parsing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;;GAMG;AACH,MAAM,OAAO,GAAG;IACf,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,WAAW,EAAE,EAAE;IACf,GAAG,EAAE,EAAE;CACE,CAAA;AA0BV;;;;;;;;GAQG;AACH,MAAM,SAAS,CAAC,CAAC,oBAAoB,CAAC,SAAiB,EAAE,UAAsB;IAC9E,uBAAuB;IACvB,IAAI,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACtD,MAAM,iBAAiB,GAAG,IAAI,WAAW,CAAC,EAAE,CAAC,CAAA,CAAC,aAAa;IAC3D,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;IAChC,IAAI,cAAc,GAAG,CAAC,CAAA;IACtB,IAAI,gBAAgB,GAAG,CAAC,CAAA;IAExB,OAAO,SAAS,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAA;QAEjC,IAAI,IAAI,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC;YAClC,gBAAgB,EAAE,CAAA;QACnB,CAAC;QAED,IAAI,IAAI,KAAK,OAAO,CAAC,KAAK,IAAI,gBAAgB,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,iBAAiB,CAAC,cAAc,CAAC,GAAG,SAAS,CAAA;YAE7C,cAAc,EAAE,CAAA;QACjB,CAAC;QAED,IAAI,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;YAC9B,iBAAiB,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,OAAO,CAAA;YACnD,MAAM,MAAM,GAAa,EAAE,CAAA;YAE3B,iFAAiF;YACjF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnD,MAAM,KAAK,GAAG,iBAAiB,CAAC,CAAC,CAAE,GAAG,CAAC,CAAA;gBACvC,MAAM,GAAG,GAAG,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;gBAEpC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;YAC5C,CAAC;YAED,MAAM,MAAM,GAAuB;gBAClC,WAAW,EAAE,UAAU;gBACvB,WAAW,EAAE,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACzC,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;gBAC3D,6BAA6B,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;gBACzE,2BAA2B,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;gBACvE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAClD,yBAAyB,EAAE,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACvD,KAAK,EAAE,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;aACnC,CAAA;YAED,MAAM,MAAM,CAAA;YACZ,cAAc,GAAG,CAAC,CAAA;YAClB,gBAAgB,GAAG,CAAC,CAAA;QACrB,CAAC;QAED,SAAS,EAAE,CAAA;IACZ,CAAC;AACF,CAAC"}