@mailwoman/bdc 8.6.0 → 9.0.0

package/sdk/build-bdc.ts

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The `bdc.db` builder (2a Task 8) — ingests parsed FCC BDC availability rows (Task 6's
- *   {@link BDCAvailabilityRow}) into Task 7's schema (`schema.ts`), producing a sealed layer database.
+ *   The `bdc.db` builder — ingests parsed FCC BDC availability rows ({@link BDCAvailabilityRow})
+ *   into the schema declared in `schema.ts`, producing a sealed layer database.
  *
  *   Mirrors `mailwoman/gazetteer-pipeline/poi/build-poi.ts`'s shape closely: the same build-tuning
  *   pragmas, the same single-pass `Map<number, number>` coverage aggregation taken during the load
@@ -66,11 +66,12 @@ import {
 	writeLayerManifest,
 	type LayerContractDatabase,
 } from "@mailwoman/core/layers"
+import { tryParsingJSON } from "@mailwoman/core/objects"
 import { openBuiltDatabase, sealDatabase } from "@mailwoman/core/utils"
 import type { FilerDatabase } from "@mailwoman/filer"
 // `pickPrimaryFRN`/`readFRNFilingCandidates` are loaded via a LAZY `await import("@mailwoman/filer/sdk")`
 // inside `populateBDCProviderTable`, not a top-level runtime import — see that function's docstring
-// (review fix round 1, IMPORTANT-1). Only the TYPES are imported here; `import type` is fully erased, so
+//. 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"
 import { shortCellToInt, type H3Cell } from "@mailwoman/spatial"
@@ -121,8 +122,8 @@ export interface BuildBDCOptions {
 	 */
 	out: string
 	/**
-	 * The FCC filing's `as_of_date` (e.g. from Task 5's `resolveLatestVintage`) — becomes the manifest's `sourceVintage`
-	 * AND `version` (BDC has no independent layer versioning yet, same deferral `build-poi.ts` makes for `release`).
+	 * The FCC filing's `as_of_date` (e.g. from `resolveLatestVintage`) — becomes the manifest's `sourceVintage` AND
+	 * `version` (BDC has no independent layer versioning yet, same deferral `build-poi.ts` makes for `release`).
 	 */
 	asOfDate: string
 	/**
@@ -144,24 +145,24 @@ export interface BuildBDCOptions {
 	blockCentroids: (geoid: string) => { lat: number; lon: number } | undefined
 	onProgress?: (message: string) => void
 	/**
-	 * Provider-list rows (Task 3's {@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI
-	 * seam for populating `bdc_provider` (2a decision 8 / 3a decision 6, Task 8). When ABSENT (the default),
-	 * `bdc_provider` stays empty and the rest of the build is byte-identical to the pre-Task-8 behavior: every code path
-	 * this option touches is gated behind `if (options.providers)`, so omitting it changes nothing. When present,
-	 * `buildBDCDatabase` groups rows by `providerID` and inserts one `bdc_provider` row per distinct provider — see
-	 * {@link BuildBDCOptions.filerDB} for how the primary FRN is picked when a provider carries more than one, and
-	 * `schema.ts`'s `BDCProviderTable` docstring for the full lossy-denormalization rationale (decision 6).
+	 * 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
+	 * (options.providers)`, so omitting it changes nothing. When present, `buildBDCDatabase` groups rows by `providerID`
+	 * and inserts one `bdc_provider` row per distinct provider — see {@link BuildBDCOptions.filerDB} for how the primary
+	 * FRN is picked when a provider carries more than one, and `schema.ts`'s `BDCProviderTable` docstring for the full
+	 * lossy-denormalization rationale (decision 6).
 	 */
 	providers?: Iterable<ProviderListRow> | AsyncIterable<ProviderListRow>
 	/**
 	 * Filer.db handle (`@mailwoman/filer`) used to resolve a multi-FRN provider's PRIMARY FRN via
 	 * `readFRNFilingCandidates` + `pickPrimaryFRN` (`@mailwoman/filer/sdk`, decision 6) — imported rather than
-	 * reimplemented, since Task 7's review found and fixed a temporal bug (the candidate query originally omitted the
-	 * `valid_to` half of the half-open predicate) that a fresh implementation here would reintroduce. Only actually
-	 * QUERIED for a `provider_id` whose rows carry more than one distinct `frn` — a single-FRN provider needs no lookup,
-	 * since its lone FRN is already primary by construction. Required whenever `providers` is given AND at least one
-	 * `provider_id` turns out to be multi-FRN; `buildBDCDatabase` throws a descriptive error naming the offending
-	 * `provider_id` if it's needed but missing, rather than silently picking an arbitrary FRN.
+	 * reimplemented, because the candidate query needs BOTH halves of the half-open `valid_from`/`valid_to` predicate and
+	 * a second implementation here would be a second place to drop the `valid_to` half. Only actually QUERIED for a
+	 * `provider_id` whose rows carry more than one distinct `frn` — a single-FRN provider needs no lookup, since its lone
+	 * FRN is already primary by construction. Required whenever `providers` is given AND at least one `provider_id` turns
+	 * out to be multi-FRN; `buildBDCDatabase` throws a descriptive error naming the offending `provider_id` if it's
+	 * needed but missing, rather than silently picking an arbitrary FRN.
 	 */
 	filerDB?: DatabaseClient<FilerDatabase>
 	/**
@@ -346,13 +347,9 @@ interface GeoJSONMultiPolygon {
 export function geometryCentroid(geometryJSON: string | null): { lat: number; lon: number } | undefined {
 	if (!geometryJSON) return undefined
 
-	let geometry: GeoJSONPolygon | GeoJSONMultiPolygon
+	const geometry = tryParsingJSON<GeoJSONPolygon | GeoJSONMultiPolygon>(geometryJSON)
 
-	try {
-		geometry = JSON.parse(geometryJSON)
-	} catch {
-		return undefined
-	}
+	if (!geometry) return undefined
 
 	const exteriorRings: number[][][] =
 		geometry.type === "Polygon"
@@ -413,8 +410,8 @@ export function createTIGERBlockCentroidLookup(
 const PROVIDER_INSERT_BATCH_SIZE = 500
 
 /**
- * Groups `providers` by `providerID`. Task 3's `parseProviderList` yields one {@link ProviderListRow} PER LINE of the
- * source CSV, preserving cardinality (never folded, never last-wins — see that module's docstring) — so a `provider_id`
+ * Groups `providers` by `providerID`. `parseProviderList` yields one {@link ProviderListRow} PER LINE of the source
+ * CSV, preserving cardinality (never folded, never last-wins — see that module's docstring) — so a `provider_id`
  * appearing on N rows arrives here as N separate rows, exactly as decision 6 requires downstream.
  */
 async function groupProviderListRows(
@@ -436,7 +433,7 @@ async function groupProviderListRows(
 }
 
 /**
- * Populate `bdc_provider` from `options.providers` (2a decision 8 / 3a decision 6, Task 8) — see `schema.ts`'s
+ * Populate `bdc_provider` from `options.providers` (2a decision 8 / 3a decision 6) — see `schema.ts`'s
  * `BDCProviderTable` docstring for the full lossy-denormalization rationale. For each distinct `provider_id`:
  *
  * - Exactly one `frn` among its rows → that FRN is primary by construction; no `filerDB` query needed at all.
@@ -447,22 +444,22 @@ async function groupProviderListRows(
  *   checks `candidates.length` first, mirroring `filerLookup`'s own `primary_frn: null` handling of the same case.
  * - `filerDB` is REQUIRED the instant a multi-FRN `provider_id` is encountered; its absence throws immediately, naming
  *   the offending `provider_id`, rather than silently picking an arbitrary FRN.
- * - `holding_company` gets the IDENTICAL single-distinct-value shortcut `frn` gets (review fix round 1, IMPORTANT-3):
- *   exactly one distinct non-null `holdingCompany` across a provider's rows means there's no conflict to resolve, so
- *   it's populated directly, no rule needed. Two or more distinct values IS the real conflict decision 6 refuses to
- *   paper over with last-wins — that case inserts NULL, and every value stays recoverable from `filer.db`. A `null`
- *   `holdingCompany` on some rows doesn't count as a competing value (a row simply not stating it isn't a conflicting
- *   assertion) — only distinct NON-NULL strings are compared.
+ * - `holding_company` gets the IDENTICAL single-distinct-value shortcut `frn` gets: exactly one distinct non-null
+ *   `holdingCompany` across a provider's rows means there's no conflict to resolve, so it's populated directly, no rule
+ *   needed. Two or more distinct values IS the real conflict decision 6 refuses to paper over with last-wins — that
+ *   case inserts NULL, and every value stays recoverable from `filer.db`. A `null` `holdingCompany` on some rows
+ *   doesn't count as a competing value (a row simply not stating it isn't a conflicting assertion) — only distinct
+ *   NON-NULL strings are compared.
  *
  * `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 (review fix round 1, IMPORTANT-1).** `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/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.
  */
 async function populateBDCProviderTable(
 	kdb: DatabaseClient<BDCDatabase>,
@@ -625,7 +622,7 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 	// all survive the staging dedup as distinct staged rows. In `includeLocationIDs` mode that's correct: every BSL
 	// is a real, distinct row the caller asked to keep. In the default (NULL `location_id`) mode, when those BSLs
 	// ALSO share identical speeds/flags, they'd otherwise materialize as byte-identical rows, inflating `result.rows`
-	// and `layer_coverage.observed_rows` by the BSL count (found in review, ~100x at real scale) — `SELECT DISTINCT`
+	// and `layer_coverage.observed_rows` by the BSL count (~100x at real scale) — `SELECT DISTINCT`
 	// over every column EXCEPT `location_id` collapses those byte-identical BSL duplicates down to one row.
 	// IMPORTANT — this is NOT a guarantee of one row per (geoid, provider_id, technology_code) triple: BSLs at the
 	// same triple with DIFFERING speeds/flags are NOT the same tuple, so `SELECT DISTINCT` does not merge them —
@@ -661,8 +658,8 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 						// Coverage cell MUST be derived as the res-9 cell's H3 hierarchy parent — NOT a second,
 						// independent `latLngToCell(centroid, 6)` call. H3's cell hierarchy is not geometrically
 						// exact: a point's directly-indexed res-6 cell and its res-9 cell's `cellToParent(…, 6)`
-						// disagree for a real fraction of points (~6% empirically over CONUS, reviewer-verified —
-						// hexagon/pentagon boundary artifacts). Deriving both `h3_cell` and the coverage cell from
+						// disagree for a real fraction of points (~6% empirically over CONUS — hexagon/pentagon
+						// boundary artifacts). Deriving both `h3_cell` and the coverage cell from
 						// the SAME full res-9 index is what lets `filing-landscape.ts`'s reader reconstruct this
 						// exact coverage cell from nothing but the stored `h3_cell` (its `res9ShortCellToRes6Parent`
 						// applies `cellToParent` to the reconstructed res-9 cell) — builder and reader must derive
@@ -754,9 +751,9 @@ export async function buildBDCDatabase(options: BuildBDCOptions): Promise<BuildB
 		createdAt: new Date().toISOString(),
 	})
 
-	// bdc_provider population (2a decision 8 / 3a decision 6, Task 8) — entirely additive and gated behind
-	// `options.providers`: when absent, this block never runs and `bdc_provider` stays empty, exactly as before
-	// Task 8 (see `BuildBDCOptions.providers`'s docstring — the default-path byte-identical guarantee).
+	// bdc_provider population (2a decision 8 / 3a decision 6) — entirely additive and gated behind
+	// `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
 
 	if (options.providers) {

package/sdk/common.ts

@@ -170,8 +170,8 @@ export interface RawBDCFile {
 	 * 2-digit state or territory FIPS code.
 	 *
 	 * Loosely typed as `string` for now. The Nexus original was `AdminLevel1Code` (via `@isp.nexus/tiger`); this port
-	 * drops that dependency, same as `data-collection.ts`'s `FCCStateID`. Task 2c tightens this against
-	 * `@mailwoman/tiger` if a downstream dictionary needs the literal union.
+	 * drops that dependency, same as `data-collection.ts`'s `FCCStateID`. Tighten it against `@mailwoman/tiger` if a
+	 * downstream dictionary ever needs the literal union.
 	 *
 	 * Nullable in live data for rows not scoped to a specific state (e.g. Provider-category rows). Guarded in
 	 * {@linkcode parseRawBDCFile} — a null value parses to an empty `stateCode` string.
@@ -180,7 +180,7 @@ export interface RawBDCFile {
 	/**
 	 * State or territory name.
 	 *
-	 * Loosely typed as `string` — the Nexus original was `StateName` (via `@isp.nexus/tiger`). Same task-2c deferral as
+	 * Loosely typed as `string` — the Nexus original was `StateName` (via `@isp.nexus/tiger`). Same deferral as
 	 * `state_fips` above.
 	 */
 	state_name: string
@@ -234,8 +234,8 @@ export interface BDCFile {
 	/**
 	 * The state or territory FIPS code.
 	 *
-	 * Loosely typed as `string` — see {@linkcode RawBDCFile} for the task-2c deferral. Empty string when the raw
-	 * `state_fips` was `null`.
+	 * Loosely typed as `string` — see {@linkcode RawBDCFile} for the deferral. Empty string when the raw `state_fips` was
+	 * `null`.
 	 */
 	stateCode: string
 	/**

package/sdk/data-collection.ts

@@ -12,8 +12,8 @@ import type { BroadbandServicableLocationID } from "./location.ts"
  * Snake_case identifier for a US State or Territory.
  *
  * Loosely typed as `string` for now. The Nexus original derived this from `StateName` (via `@isp.nexus/tiger`); this
- * port drops that dependency since 2a doesn't consume the literal union anywhere. Task 2c tightens this against
- * `@mailwoman/tiger`'s `StateName` if a downstream dictionary needs it.
+ * port drops that dependency since nothing here consumes the literal union. Tighten it against `@mailwoman/tiger`'s
+ * `StateName` if a downstream dictionary ever needs it.
  *
  * @category FCC
  * @title FCC State Identifier

package/sdk/download.ts

@@ -6,14 +6,14 @@
  *
  *   Re-homed from Nexus's `sync/fcc/bdc/download-file.ts` (relicense-by-copy, no provenance headers),
  *   trimmed hard: the Nexus original downloaded AND cached the `.zip`, extracted it, THEN wrote a Parquet
- *   file with a row-count integrity check. All Parquet machinery is dropped here — 2a's `bdc.db` is
- *   SQLite, not Parquet-backed (see Task 7+) — and the `.zip` itself isn't cached either; only the
+ *   file with a row-count integrity check. All Parquet machinery is dropped here — `bdc.db` is
+ *   SQLite, not Parquet-backed (`bdc/schema.ts`) — and the `.zip` itself isn't cached either; only the
  *   extracted CSV is written to `destinationDir`, and its presence alone is the cache check.
  *
  *   The zip-extraction library also changes: the Nexus original's `extractSingleFileZip` used `adm-zip`
  *   (a repo-wide Nexus dependency). No unzip dependency exists anywhere in this repo — every workspace
- *   `package.json` was checked, `tiger/` and `osm/` included — so `yauzl-promise` is added to `bdc` alone
- *   (noted in this task's commit body per the brief).
+ *   `package.json` was checked, `tiger/` and `osm/` included — so `yauzl-promise` is a `bdc`-only
+ *   dependency.
  */
 
 import * as fs from "node:fs/promises"

package/sdk/filing-landscape.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `filing_landscape` reader (2a Task 9) — the FOUR PRE-REGISTERED ACCEPTANCE GATES this whole phase
+ *   `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.
  *
  *   Coverage check (the meaning-of-zero rule): a queried block counts as SURVEYED only when its res-6
@@ -18,31 +18,24 @@
  *     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}.
+ *   The res-6 parent is reconstructed from the STORED res-9 cell (`@mailwoman/spatial`'s `expandH3Cell`
+ *   back to a full index, then `cellToParent`) rather than recomputed from the block centroid. See
+ *   {@link res9ShortCellToRes6Parent}.
  *
- *   This same formula is exactly what `build-bdc.ts` MUST use (and does, after fix round 1) to derive the
+ *   This same formula is exactly what `build-bdc.ts` MUST use (and does) 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
+ *   reader deriving the res-6 parent differently is a self-contradiction waiting to happen: a
+ *   genuinely-surveyed block (real rows, real `layer_coverage` entry) reads back as
+ *   `unknown_block_count` while its own rows still populate `filings`. `filings` is scoped to units that
+ *   PASS the coverage check (see the `surveyedUnits` accumulator below) precisely so that can't happen: 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 { expandH3Cell, shortCellToInt, type H3Cell, type H3CellShort } from "@mailwoman/spatial"
 import { cellToParent } from "h3-js"
 import { sql, type Kysely } from "kysely"
 
@@ -155,13 +148,12 @@ function asContractDB(kdb: DatabaseClient<BDCDatabase>): Kysely<LayerContractDat
 }
 
 /**
- * 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).
+ * 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 shortHex = h3CellShortInt.toString(16).padStart(13, "0")
-	const fullCell = `8${BDC_H3_RESOLUTION.toString(16)}${shortHex}` as H3Cell
+	const fullCell = expandH3Cell(h3CellShortInt.toString(16) as H3CellShort, BDC_H3_RESOLUTION)
 	const parentCell = cellToParent(fullCell, BDC_COVERAGE_H3_RESOLUTION) as H3Cell
 
 	return shortCellToInt(parentCell)

package/sdk/list-files.ts

@@ -7,7 +7,7 @@
  *   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
+ *   {@linkcode BDCClient}. Raw entries are parsed via `parseRawBDCFile` and returned sorted
  *   ascending by revision (`compareRevisionAsc`) rather than in API order.
  */
 

package/sdk/nearest-infrastructure.ts

@@ -4,15 +4,14 @@
  * @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.
+ *   categories (`telecom_exchange`/`tower_comms` — `@mailwoman/poi-taxonomy` categories, populated by the
+ *   `--source osm` extractor) that a caller can join against ANY layer's own `layer_coverage`
+ *   survey-completeness table (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):
+ *   Two shapes below are not the obvious ones, and both are forced by what `poi-lookup.ts` and
+ *   `@mailwoman/core/layers` actually expose:
  *
  *   - **`poiLookup` is an already-open {@link POILookup}, not a `POILookupOpts` this function
  *     constructs itself.** `POILookup`'s constructor eagerly loads the poi-taxonomy category dictionary
@@ -22,14 +21,14 @@
  *     `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`
+ *   - **`nearestInfrastructure` is `async`, not sync.** `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
+ *   why the res-6 parent is reconstructed from the STORED res-9 cell rather than recomputed from the
+ *   centroid) 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.

package/sdk/plausibility.ts

@@ -3,13 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `plausibilityCheck` (2b task 5, spec §3.2/§4) — the heart of the BDC plausibility vertical. Composes
- *   `filingLandscape` (2a) + `nearestInfrastructure` (2b task 4) into ONE evidence bundle over a single
- *   broadband-service claim, under the registry-backed doctrine's positive-evidence-only invariant (spec
- *   §4): a BDC filing or a nearby infrastructure hit can RAISE confidence; their absence can only ever
- *   read as "unknown" or "no supporting evidence found, coverage permitting" — NEVER as "implausible."
- *   The four §7-2b acceptance gates land in Task 6 as their own test file; this module is designed for
- *   them but doesn't assert them itself.
+ *   `plausibilityCheck` (spec §3.2/§4) — the heart of the BDC plausibility vertical. Composes
+ *   `filingLandscape` (`bdc/sdk/filing-landscape.ts`) + `nearestInfrastructure` into ONE evidence bundle
+ *   over a single broadband-service claim, under the registry-backed doctrine's positive-evidence-only
+ *   invariant (spec §4): a BDC filing or a nearby infrastructure hit can RAISE confidence; their absence
+ *   can only ever read as "unknown" or "no supporting evidence found, coverage permitting" — NEVER as
+ *   "implausible." The four §7-2b acceptance gates are asserted in `plausibility.test.ts`'s
+ *   `describe("§7-2b gates")` block; this module is designed for them but doesn't assert them itself.
  *
  *   **Claim resolution (decision 4).** A claim's spatial key resolves two INDEPENDENT ways:
  *
@@ -88,25 +88,26 @@
  *   filing coverage alone — it degrades to filing-covered → `"low"`, filing-unknown/absent →
  *   `"insufficient_survey_data"`. Rationale: spec §4 frames physical co-presence as the vertical's
  *   distinguishing "falsifier that only fires positively" and reserves `"high"` for genuine two-channel
- *   corroboration (Gate 2 in Task 6: "matching filing + nearby plant in covered cells… high"); a tech
+ *   corroboration (§7-2b Gate 2: "matching filing + nearby plant in covered cells… high"); a tech
  *   that structurally can never offer a second channel should not be able to claim the same top
  *   confidence a fiber claim earns by actually having one available. This reading is more conservative
- *   than the alternative (treating the missing axis as inert and reporting `"high"` off filing alone) —
- *   flagged here for review since Task 6's four gates don't exercise a no-physical-falsifier tech code.
+ *   than the alternative (treating the missing axis as inert and reporting `"high"` off filing alone),
+ *   and nothing pins it: none of the four §7-2b gates exercises a no-physical-falsifier tech code.
  *
- *   **Ledger note (task 4 review; extended task 5 fix round 1, finding 2) — the per-layer coverage-resolution sanity
- *   check.** Neither bdc.db's nor poi.db's `layer_manifest` records the COVERAGE-cell h3 resolution (6) that
- *   `res9ShortCellToRes6Parent` hardcodes on both sides — only each layer's ROW-spine resolution (9,
- *   `spineKeys.h3.resolution`) is ever recorded. A real fix needs a layer-contract schema addition (out
- *   of scope for this task; the same follow-up task 4's report already ticketed). What IS practical and
+ *   **The per-layer coverage-resolution sanity check.** Neither bdc.db's nor poi.db's `layer_manifest`
+ *   records the COVERAGE-cell h3 resolution (6) that `res9ShortCellToRes6Parent` hardcodes on both sides
+ *   — only each layer's ROW-spine resolution (9, `spineKeys.h3.resolution`) is ever recorded. Closing
+ *   that gap properly needs an addition to the layer contract itself (`@mailwoman/core/layers`), which
+ *   does not exist yet. What IS practical and
  *   cheap: each manifest is a single-row table already read at most once per call here, so whenever a layer is
  *   WIRED — `bdcDB`, `poi`, or both, checked independently — {@link assertLayerSpineResolution} compares that one
  *   layer's recorded `spineKeys.h3.resolution` directly against the `BDC_H3_RESOLUTION` constant `pointCell` is
  *   actually derived from, and throws on a mismatch, catching a layer built at a different spine resolution before it
  *   silently mis-joins a coverage cell. This is TWO-SIDED, not gated on both layers being present together: a
  *   poi-only call still checks poi's own recorded resolution, since `readLayerCoverage`'s poi-side join key (below)
- *   is derived from `BDC_H3_RESOLUTION` regardless of whether `bdcDB` is wired at all (the original one-sided version
- *   compared the two manifests to each other, so it silently skipped poi entirely whenever `bdcDB` was absent). It
+ *   is derived from `BDC_H3_RESOLUTION` regardless of whether `bdcDB` is wired at all — comparing each manifest
+ *   against the constant, rather than the two manifests against each other, is what makes a single-layer call
+ *   checkable at all. It
  *   can NOT catch a layer whose row spine is 9 but whose COVERAGE cells were derived at some OTHER resolution than 6
  *   — that gap needs the schema addition, not a runtime assertion.
  */
@@ -169,12 +170,12 @@ export type PlausibilityEvidence =
 	| { type: "abstain"; reason: PlausibilityAbstainReason; layer?: string }
 
 /**
- * One evidence channel's survey-completeness state for THIS claim, WITH the reason a non-`"covered"` state applies —
- * task 5 fix round 1 (review finding 1): `coverage_confidence` alone folds several genuinely different situations into
- * the same `"low"`/`"insufficient_survey_data"` verdict (a tech with no physical falsifier at all vs. a real poi survey
- * gap vs. a geoid-only claim with no coordinate to search from), and Task 6's gates need to attribute WHICH one
- * applies. `"not_applicable"` and `"no_coordinate"` are only ever produced for the physical axis; the filing axis only
- * ever reaches `"covered"`, `"layer_missing"`, or `"cell_unsurveyed"`.
+ * One evidence channel's survey-completeness state for THIS claim, WITH the reason a non-`"covered"` state applies.
+ * `coverage_confidence` alone folds several genuinely different situations into the same
+ * `"low"`/`"insufficient_survey_data"` verdict (a tech with no physical falsifier at all vs. a real poi survey gap vs.
+ * a geoid-only claim with no coordinate to search from); this axis state is what tells them apart. `"not_applicable"`
+ * and `"no_coordinate"` are only ever produced for the physical axis; the filing axis only ever reaches `"covered"`,
+ * `"layer_missing"`, or `"cell_unsurveyed"`.
  */
 export type PlausibilityCoverageAxisState =
 	| "covered"
@@ -203,7 +204,7 @@ export type PlausibilityCoverageAxisState =
 
 /**
  * Per-axis attribution for {@link PlausibilityBundle.coverage_confidence} — see {@link PlausibilityCoverageAxisState}.
- * Added alongside `coverage_confidence` (kept as-is for compatibility) rather than replacing it.
+ * Reported alongside `coverage_confidence`, never in place of it: the coarse field stays the stable public surface.
  */
 export interface PlausibilityCoverageDetail {
 	filing: PlausibilityCoverageAxisState
@@ -215,8 +216,8 @@ export interface PlausibilityBundle {
 	evidence_found: PlausibilityEvidence[]
 	coverage_confidence: "high" | "low" | "insufficient_survey_data"
 	/**
-	 * Per-axis WHY behind `coverage_confidence` — task 5 fix round 1 (finding 1). ALWAYS present, mirroring
-	 * `block_resolution`'s always-present discipline.
+	 * Per-axis WHY behind `coverage_confidence`. ALWAYS present, mirroring `block_resolution`'s always-present
+	 * discipline.
 	 */
 	coverage_detail: PlausibilityCoverageDetail
 	/**
@@ -245,7 +246,7 @@ export interface GeocodeLike {
 }
 
 /**
- * The already-open infra layer this scorer composes against Task 4's `nearestInfrastructure`. The caller owns BOTH
+ * The already-open infra layer this scorer composes against {@link nearestInfrastructure}. The caller owns BOTH
  * handles' open/dispose lifecycle (mirrors `nearestInfrastructure`'s own `using poiLookup = new POILookup(...)`
  * precedent). `contractDB` is used two ways: passed straight through to `nearestInfrastructure` (per-hit coverage), and
  * read directly here (the whole-cell coverage check this module needs for `coverage_confidence`, independent of whether
@@ -263,10 +264,9 @@ export interface PlausibilityDeps {
 }
 
 /**
- * Tech → physical-plant category mapping (exported per the task brief). Fiber implies the three
- * infrastructure-extension categories a fiber network plausibly touches; the three fixed-wireless codes imply a comms
- * tower; every other code maps to `[]` — no physical falsifier is claimed for it (see
- * {@link physicalCategoriesForTechnology}).
+ * Tech → physical-plant category mapping. Fiber implies the three infrastructure-extension categories a fiber network
+ * plausibly touches; the three fixed-wireless codes imply a comms tower; every other code maps to `[]` — no physical
+ * falsifier is claimed for it (see {@link physicalCategoriesForTechnology}).
  */
 export const PLAUSIBILITY_TECH_PHYSICAL_CATEGORIES: Readonly<Record<number, readonly string[]>> = {
 	[BroadbandTechnologyCode.OpticalCarrierFiber]: ["telecom_exchange", "telecom_cabinet", "data_center"],
@@ -359,18 +359,17 @@ function combineCoverage(
 }
 
 /**
- * See the module docstring's "ledger note" section. Throws when a WIRED layer's manifest disagrees with
+ * See the module docstring's coverage-resolution note. Throws when a WIRED layer's manifest disagrees with
  * `BDC_H3_RESOLUTION` — the single constant `plausibilityCheck` actually uses at runtime to derive both the
  * filing-lookup cell (bdc side, via `pointCell`) and the coverage-cell join key `readLayerCoverage` is read against
  * (poi side, via `res9ShortCellToRes6Parent(pointCell)`).
  *
- * Task 5 fix round 1 (review finding 2): checked independently PER LAYER, whenever THAT layer is wired, rather than
- * only when both `bdcDB` and `poi` are wired together. The original one-sided assertion compared the two manifests to
- * EACH OTHER, which meant a poi-only call (no `bdcDB`) never checked poi's recorded resolution at all — even though
- * `pointCell` (computed unconditionally from `BDC_H3_RESOLUTION`) still drives the poi coverage-cell read below.
- * Comparing each layer directly against the constant is also strictly stronger than the retired manifest-vs-manifest
- * check: it catches a layer built under a since-changed `BDC_H3_RESOLUTION` even when the OTHER layer is absent
- * entirely, not just a disagreement between two present layers.
+ * Checked independently PER LAYER, whenever THAT layer is wired — not only when `bdcDB` and `poi` are wired together. A
+ * poi-only call still needs poi's own recorded resolution checked, because `pointCell` is computed unconditionally from
+ * `BDC_H3_RESOLUTION` and still drives the poi coverage-cell read below. Comparing each layer directly against the
+ * constant, rather than the two manifests against each other, is also strictly stronger: it catches a layer built under
+ * a since-changed `BDC_H3_RESOLUTION` even when the OTHER layer is absent entirely, not just a disagreement between two
+ * present layers.
  */
 async function assertLayerSpineResolution(
 	layer: "bdc" | "poi",
@@ -427,9 +426,9 @@ export async function plausibilityCheck(claim: PlausibilityClaim, deps: Plausibi
 		? shortCellToInt(latLngToCell(point.coordinates[1], point.coordinates[0], BDC_H3_RESOLUTION) as H3Cell)
 		: undefined
 
-	// Ledger note (task 4 review; task 5 fix round 1 finding 2): cheap, one-time per-layer sanity check — see the
-	// module docstring. Runs independently per WIRED layer, not only when both are present — a poi-only call still
-	// joins poi's coverage table against a BDC_H3_RESOLUTION-derived cell (below) and must not do so unchecked.
+	// Cheap, one-time per-layer sanity check — see the module docstring's coverage-resolution note. Runs
+	// independently per WIRED layer, not only when both are present: a poi-only call still joins poi's coverage
+	// table against a BDC_H3_RESOLUTION-derived cell (below) and must not do so unchecked.
 	if (deps.bdcDB) {
 		await assertLayerSpineResolution("bdc", asContractDB(deps.bdcDB), BDC_H3_RESOLUTION)
 	}
@@ -482,9 +481,8 @@ export async function plausibilityCheck(claim: PlausibilityClaim, deps: Plausibi
 		} else if (!point) {
 			// Geoid-only claim, no coordinate resolvable — see the module docstring's claim-resolution note. A real
 			// capability gap, not a missing-layer abstain: no evidence entry is fabricated, but the axis still
-			// degrades honestly for coverage_confidence (and now names ITS OWN reason in `coverage_detail`, distinct
-			// from `"layer_missing"`, rather than folding into the same generic "unknown" — task 5 fix round 1
-			// finding 1).
+			// degrades honestly for coverage_confidence, naming ITS OWN reason in `coverage_detail` rather than
+			// folding into the same generic "unknown" as `"layer_missing"`.
 			physicalCoverage = "no_coordinate"
 		} else {
 			const hits = await nearestInfrastructure(deps.poi.lookup, deps.poi.contractDB, {