@mailwoman/bdc 9.1.0 → 9.3.0

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

@@ -8,8 +8,8 @@
  *   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.
+ *   "implausible." The four §7-2b acceptance criteria are asserted in `plausibility.test.ts`'s
+ *   `describe("§7-2b criteria")` 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:
  *
@@ -24,7 +24,7 @@
  *   - **Physical evidence's search center**: independent of the above — `claim.point` (or the geocoded
  *     `claim.address`) directly, whenever available. A GEOID-ONLY claim (no point, no address) has NO
  *     coordinate to search from: bdc.db stores no public geoid→centroid resolver (deriving one would
- *     need the same Fabric-adjacent block-centroid machinery the vertical explicitly keeps out of reach
+ *     need the same Fabric-adjacent block-centroid implementation the vertical explicitly keeps out of reach
  *     — §2.2's boundary), so physical evidence is skipped entirely for that shape of claim. This is a
  *     genuine, documented capability gap, not a missing-layer abstain: `coverage_confidence` still
  *     degrades honestly (see below), but no `PlausibilityEvidence` abstain variant fits "no coordinate
@@ -88,11 +88,11 @@
  *   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 (§7-2b Gate 2: "matching filing + nearby plant in covered cells… high"); a tech
+ *   corroboration (§7-2b criterion 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),
- *   and nothing pins it: none of the four §7-2b gates exercises a no-physical-falsifier tech code.
+ *   and nothing pins it: none of the four §7-2b criteria exercises a no-physical-falsifier tech code.
  *
  *   **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
@@ -103,7 +103,7 @@
  *   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
+ *   silently mis-joins a coverage cell. This is TWO-SIDED, not conditioned 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 — comparing each manifest
  *   against the constant, rather than the two manifests against each other, is what makes a single-layer call
@@ -112,14 +112,14 @@
  *   — that gap needs the schema addition, not a runtime assertion.
  */
 
-import type { DatabaseClient } from "@mailwoman/core/kysley/client"
-import { readLayerCoverage, readLayerManifest, type LayerContractDatabase } from "@mailwoman/core/layers"
-import type { POILookup } from "@mailwoman/resolver-wof-sqlite/poi-lookup"
+import { readLayerCoverage, readLayerManifest, type LayerContractHandle } from "@mailwoman/core/layers"
+import type { Evidence } from "@mailwoman/evidence"
+import type { POILookup } from "@mailwoman/resolver-wof-sqlite/poi"
 import { shortCellToInt, type H3Cell, type PointLiteral } from "@mailwoman/spatial"
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
 import { latLngToCell } from "h3-js"
-import type { Kysely } from "kysely"
 
-import { BDC_H3_RESOLUTION, type BDCDatabase } from "../schema.ts"
+import { BDC_H3_RESOLUTION, type BDCDatabase } from "#schema"
 import {
 	BDC_SPEED_BUCKET_100_1000,
 	BDC_SPEED_BUCKET_25_100,
@@ -129,13 +129,13 @@ import {
 	res9ShortCellToRes6Parent,
 	speedBucketForDownloadSpeed,
 	type ProviderFilingSummary,
-} from "./filing-landscape.ts"
-import { nearestInfrastructure, type InfrastructureHit } from "./nearest-infrastructure.ts"
+} from "#sdk/filing-landscape"
+import { nearestInfrastructure, type InfrastructureHit } from "#sdk/nearest-infrastructure"
 import {
 	BroadbandTechnologyCategory,
 	BroadbandTechnologyCategoryToCodeSet,
 	BroadbandTechnologyCode,
-} from "./technologies.ts"
+} from "#sdk/technologies"
 
 /**
  * The three fixed-wireless codes (unlicensed/licensed/licensed-by-rule), read off
@@ -165,10 +165,29 @@ export interface PlausibilityClaim {
 export type PlausibilityAbstainReason = "requires_build_local_layer" | "requires_bdc_layer" | "insufficient_survey_data"
 
 export type PlausibilityEvidence =
-	| { type: "filing"; filing: ProviderFilingSummary; vintage: string; corroborates: boolean }
-	| { type: "physical_plant"; hit: InfrastructureHit }
+	| {
+			kind: "observation"
+			type: "filing"
+			source: "bdc"
+			vintage: string
+			filing: ProviderFilingSummary
+			corroborates: boolean
+	  }
+	| { kind: "observation"; type: "physical_plant"; source: "poi"; vintage: string; hit: InfrastructureHit }
 	| { type: "abstain"; reason: PlausibilityAbstainReason; layer?: string }
 
+/**
+ * The two non-abstain variants are {@link Evidence} observations wearing their original field names, so a caller that
+ * already reads `.filing` keeps working while a caller that wants the shared vocabulary can narrow on `kind`. The
+ * abstain variant deliberately does NOT join the union: an abstain is the ABSENCE of evidence plus a reason, which
+ * `coverage_confidence` already reports, and minting an evidence object for "we could not look" would put a claim where
+ * there is none.
+ */
+export type PlausibilitySharedEvidence =
+	Extract<PlausibilityEvidence, { kind: "observation" }> extends Evidence
+		? Extract<PlausibilityEvidence, { kind: "observation" }>
+		: never
+
 /**
  * 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
@@ -254,7 +273,7 @@ export interface GeocodeLike {
  */
 export interface PlausibilityPOIDeps {
 	lookup: POILookup
-	contractDB: DatabaseClient<LayerContractDatabase>
+	contractDB: LayerContractHandle & Pick<DatabaseClient, "destroy">
 }
 
 export interface PlausibilityDeps {
@@ -295,15 +314,6 @@ const SPEED_BUCKET_RANK: Readonly<Record<string, number>> = {
 	[BDC_SPEED_BUCKET_GIGABIT]: 3,
 }
 
-/**
- * `BDCDatabase extends LayerContractDatabase` structurally, but Kysely's `transaction()` makes `Kysely<DB>` INVARIANT
- * in `DB` — same cast idiom as `filing-landscape.ts`'s own private `asContractDB` (decision 8: reuse, never re-derive;
- * copied rather than imported since the original is module-private).
- */
-function asContractDB(kdb: DatabaseClient<BDCDatabase>): Kysely<LayerContractDatabase> {
-	return kdb as unknown as Kysely<LayerContractDatabase>
-}
-
 /**
  * `true` when `filing` corroborates the claim: same `technology_code`, AND `filing.speed_bucket` ranks at or above the
  * claimed download speed's own bucket. A different tech, or a same-tech but LESSER filing, is `false` — never disproof,
@@ -373,7 +383,7 @@ function combineCoverage(
  */
 async function assertLayerSpineResolution(
 	layer: "bdc" | "poi",
-	contractDB: Kysely<LayerContractDatabase>,
+	contractDB: LayerContractHandle & Pick<DatabaseClient, "destroy">,
 	expectedResolution: number
 ): Promise<void> {
 	const manifest = await readLayerManifest(contractDB)
@@ -430,7 +440,7 @@ export async function plausibilityCheck(claim: PlausibilityClaim, deps: Plausibi
 	// 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)
+		await assertLayerSpineResolution("bdc", deps.bdcDB, BDC_H3_RESOLUTION)
 	}
 
 	if (deps.poi) {
@@ -459,7 +469,9 @@ export async function plausibilityCheck(claim: PlausibilityClaim, deps: Plausibi
 
 			for (const filing of landscape.filings) {
 				evidence.push({
+					kind: "observation",
 					type: "filing",
+					source: "bdc",
 					filing,
 					vintage: landscape.vintage,
 					corroborates: filingCorroborates(filing, claim),
@@ -490,8 +502,10 @@ export async function plausibilityCheck(claim: PlausibilityClaim, deps: Plausibi
 				categoryIDs: [...physicalCategories],
 			})
 
+			const poiVintage = (await readLayerManifest(deps.poi.contractDB)).sourceVintage
+
 			for (const hit of hits) {
-				evidence.push({ type: "physical_plant", hit })
+				evidence.push({ kind: "observation", type: "physical_plant", source: "poi", vintage: poiVintage, hit })
 			}
 
 			const coverageCell = await readLayerCoverage(deps.poi.contractDB, res9ShortCellToRes6Parent(pointCell!))

package/out/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * The FCC Broadband Map credentials the BDC client sends.
+ */
+import { z } from "zod";
+/**
+ * FCC Broadband Map (BDC) public-API credentials (`bdc/lib/sdk/client.ts`) — username + hash_value header auth. Never
+ * log their values.
+ */
+export declare const PrivateBDCEnvSchema: z.ZodObject<{
+    FCC_MAP_USERNAME: z.ZodOptional<z.ZodString>;
+    FCC_MAP_API_KEY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Live BDC credentials over core's. Never log their values.
+ */
+export declare const $private: Record<never, never> & Record<string, never> & {
+    FCC_MAP_USERNAME?: string | undefined;
+    FCC_MAP_API_KEY?: string | undefined;
+};
+//# sourceMappingURL=env.d.ts.map

package/out/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;iBAS9B,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ;;;CAA4C,CAAA"}

package/out/env.js

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

package/out/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../lib/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,IAAI,WAAW,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC;QAC5C,KAAK,EAAE,4BAA4B;QACnC,WAAW,EAAE,yEAAyE;KACtF,CAAC;IACF,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC;QAC3C,KAAK,EAAE,2BAA2B;QAClC,WAAW,EAAE,6EAA6E;KAC1F,CAAC;CACF,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAA"}

package/out/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./schema.ts";
-export * from "./sdk/index.ts";
+export * from "#schema";
+export * from "#sdk/index";
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,YAAY,CAAA"}

package/out/index.js

@@ -1,3 +1,3 @@
-export * from "./schema.js";
-export * from "./sdk/index.js";
+export * from "#schema";
+export * from "#sdk/index";
 //# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,YAAY,CAAA"}

package/out/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,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;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,WAAY,SAAQ,qBAAqB;IACzD,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,YAAY,EAAE,gBAAgB,CAAA;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhF"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../lib/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,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;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,WAAY,SAAQ,qBAAqB;IACzD,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,YAAY,EAAE,gBAAgB,CAAA;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBvF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhF"}

package/out/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AA+EH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAElC;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAuB;IACvE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,kBAAkB,CAAC;SAC/B,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC;SAC9B,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,iBAAiB,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC3D,SAAS,CAAC,+BAA+B,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACzE,SAAS,CAAC,6BAA6B,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvE,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,2BAA2B,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClE,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;SAChC,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA;AAC3G,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAAuB;IACnE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,cAAc,CAAC;SAC3B,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SAC1D,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;SAC/B,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC;SACpC,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAuB;IAChE,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAA;AACvG,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../lib/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AA+EH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAElC;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,EAAuB;IACvE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,kBAAkB,CAAC;SAC/B,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC;SAC9B,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,iBAAiB,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC3D,SAAS,CAAC,+BAA+B,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACzE,SAAS,CAAC,6BAA6B,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvE,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvD,SAAS,CAAC,2BAA2B,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClE,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC;SAChC,OAAO,EAAE,CAAA;IAEX,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA;AAC3G,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAAuB;IACnE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,cAAc,CAAC;SAC3B,SAAS,CAAC,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SAC1D,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC;SAC/B,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAC;SACpC,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAuB;IAChE,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAA;AACvG,CAAC"}

package/out/sdk/build-bdc.d.ts

@@ -8,8 +8,7 @@
  *
  *   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
- *   (no second scan), the same {@link asContractDB} Kysely-invariance cast for the shared
- *   `@mailwoman/core/layers` calls, and the same `writeLayerManifest` → `sealDatabase` tail.
+ *   (no second scan), and the same `writeLayerManifest` → `sealDatabase` tail.
  *
  *   Two differences from that precedent, both deliberate:
  *
@@ -50,11 +49,11 @@
  *      mid-build crash mustn't cost the previously-good artifact, which is exactly the failure mode
  *      the house rule exists for.
  */
-import { DatabaseClient } from "@mailwoman/core/kysley/client";
 import type { FilerDatabase } from "@mailwoman/filer";
 import type { ProviderListRow } from "@mailwoman/filer/sdk";
-import type { ProviderID } from "./common.ts";
-import { type BDCAvailabilityRow } from "./parsing.ts";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { ProviderID } from "#sdk/common";
+import { type BDCAvailabilityRow } from "#sdk/parsing";
 /**
  * The manifest's `attribution` — names the FCC as the source, then copies the Fabric-boundary sentence verbatim from
  * `bdc/README.md`'s "CostQuest Fabric boundary" section (backticks stripped — this is plain prose, not markdown).
@@ -62,8 +61,8 @@ import { type BDCAvailabilityRow } from "./parsing.ts";
 export declare const BDC_ATTRIBUTION: string;
 export interface BuildBDCOptions {
     /**
-     * Injected row source — the test seam (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored and no
-     * filesystem read happens.
+     * Injected row source — the TEST INJECTION POINT (mirrors `BuildPOIOptions.rows`). When given, `csvPaths` is ignored
+     * and no filesystem read happens.
      */
     rows?: Iterable<BDCAvailabilityRow> | AsyncIterable<BDCAvailabilityRow>;
     /**
@@ -95,8 +94,8 @@ export interface BuildBDCOptions {
      * Resolve a 15-char census block GEOID to its centroid. Injected so tests supply a small fixture `Map` lookup instead
      * of touching a real TIGER database; the real (CLI-wired) implementation is
      * {@linkcode createTIGERBlockCentroidLookup}, which reads `tabblock20.GEOID` (uppercase — `TIGERBlockTable`) block
-     * geometry. Returning `undefined` for an unknown geoid is load-bearing: the materialize pass counts it in
-     * `unknownGeoids` and skips the row — it must NEVER guess a cell.
+     * geometry. Returning `undefined` for an unknown geoid is required: the materialize pass counts it in `unknownGeoids`
+     * and skips the row — it must NEVER guess a cell.
      */
     blockCentroids: (geoid: string) => {
         lat: number;
@@ -104,9 +103,9 @@ export interface BuildBDCOptions {
     } | undefined;
     onProgress?: (message: string) => void;
     /**
-     * Provider-list rows ({@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI seam for
-     * populating `bdc_provider` (2a decision 8 / 3a decision 6). When ABSENT (the default), `bdc_provider` stays empty
-     * and the rest of the build is untouched: every code path this option touches is gated behind `if
+     * Provider-list rows ({@link ProviderListRow}, `@mailwoman/filer/sdk`'s `parseProviderList`) — the test/CLI injection
+     * point for populating `bdc_provider` (2a decision 8 / 3a decision 6). When ABSENT (the default), `bdc_provider`
+     * stays empty and the rest of the build is untouched: every code path this option touches is conditioned behind `if
      * (options.providers)`, so omitting it changes nothing. When present, `buildBDCDatabase` groups rows by `providerID`
      * and inserts one `bdc_provider` row per distinct provider — see {@link BuildBDCOptions.filerDB} for how the primary
      * FRN is picked when a provider carries more than one, and `schema.ts`'s `BDCProviderTable` docstring for the full
@@ -173,7 +172,7 @@ export interface BuildBDCResult {
  *
  * `csvPath` is optional and used ONLY to name the offending file in a thrown error (the direct-buffer unit tests call
  * this without one; {@linkcode readAvailabilityRowsFromCSVPaths} always supplies it). The `Number.isSafeInteger` guard
- * below is load-bearing, not defensive dressing: `bdc_stage.provider_id` is `INTEGER NOT NULL`, and a bare
+ * below is required, not defensive dressing: `bdc_stage.provider_id` is `INTEGER NOT NULL`, and a bare
  * `Number.parseInt` on a non-numeric field (a malformed/re-headered/truncated CSV) silently produces `NaN`. `NaN` binds
  * to that NOT NULL column as SQLite `NULL`, `INSERT OR IGNORE` then drops the row without a constraint error, and every
  * dropped row gets counted as `deduped` — the ENTIRE file's rows vanish silently, misreported as ordinary dedup. A
@@ -181,11 +180,18 @@ export interface BuildBDCResult {
  */
 export declare function peekProviderID(csvBuffer: Buffer, csvPath?: string): ProviderID;
 /**
- * Naive (vertex-average, NOT area-weighted) centroid of a GeoJSON `Polygon`/`MultiPolygon`'s EXTERIOR ring(s) only
- * (interior rings/holes are ignored). A known simplification, not an oversight: census blocks are small relative to a
- * res-9 H3 cell (~174m edge), so the vertex-average and a proper area-weighted centroid land in the same cell for all
- * but pathologically elongated or holed block shapes. A precise area-weighted centroid is a reasonable future upgrade
- * if that ever proves wrong in practice — no polygon-centroid library is pulled in for this first cut.
+ * Area-weighted (shoelace) centroid of a GeoJSON `Polygon`/`MultiPolygon`'s EXTERIOR ring(s), area-weighted across
+ * rings for a MultiPolygon. Interior rings/holes are still ignored — a hole moves a block's centroid far less than the
+ * vertex-density skew this replaces, and only 1.0% of measured blocks carry one.
+ *
+ * This REPLACED the first version's vertex-average, whose "same res-9 cell for all but pathological shapes" claim was
+ * falsified by measurement over every real TIGER 2020 block in LA + Orange county (118,360 blocks, 2026-08-11): the
+ * vertex-average landed in a different res-9 cell for 11.6% of blocks, p99 displacement 286 m (past the ~174 m cell
+ * edge), max 3.7 km — the tail is TIGER's elongated rural/mountain blocks, whose boundary vertices cluster on the
+ * squiggly natural edge and drag a vertex-average toward it.
+ *
+ * A degenerate geometry with zero total ring area (a sliver the shoelace annihilates) falls back to the vertex average
+ * — a weaker answer beats none, and the fallback is exactly the old behavior.
  *
  * Returns `undefined` for anything that doesn't parse as one of the two geometry types (including `null` geometry).
  */
@@ -195,16 +201,17 @@ export declare function geometryCentroid(geometryJSON: string | null): {
 } | undefined;
 /**
  * The production `blockCentroids` supplier: opens the TIGER blocks database READ-ONLY and probes `tabblock20.GEOID`
- * (uppercase) per lookup, decoding its GeoJSON `geometry` column via {@linkcode geometryCentroid}. Kept synchronous —
- * `BuildBDCOptions.blockCentroids` is a plain sync function (the same sync-by-interface discipline AGENTS.md documents
- * for the resolver ladder), so this uses `node:sqlite`'s raw `.prepare()`/`.get()` directly rather than Kysely. The
- * connection is left open for the caller's process lifetime (a read-path lookup, not a build) — same lifecycle as the
- * resolver-wof-sqlite lookups.
+ * (uppercase) per lookup, decoding its GeoJSON `geometry` column via {@linkcode geometryCentroid}. The factory awaits
+ * its read-only open; the per-lookup probe and the `BuildBDCOptions.blockCentroids` interface stay synchronous — a
+ * plain sync function (the same sync-by-interface discipline AGENTS.md documents for the resolver ladder), so the
+ * returned closure uses `node:sqlite`'s raw `.prepare()`/`.get()` directly rather than Kysely. The connection is left
+ * open for the caller's process lifetime (a read-path lookup, not a build) — same lifecycle as the resolver-wof-sqlite
+ * lookups.
  */
-export declare function createTIGERBlockCentroidLookup(tigerDBPath: string): (geoid: string) => {
+export declare function createTIGERBlockCentroidLookup(tigerDBPath: string): Promise<(geoid: string) => {
     lat: number;
     lon: number;
-} | undefined;
+} | undefined>;
 /**
  * Build `bdc.db`: stage (raw dedup) → materialize (resolve `h3_cell` per geoid, skip+count unknown geoids) → drop stage
  * → geoid index (index-after-load) → coverage → layer manifest → seal → atomic move-into-place. See the module

package/out/sdk/build-bdc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-bdc.d.ts","sourceRoot":"","sources":["../../sdk/build-bdc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAOH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAY9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAKrD,OAAO,KAAK,EAAO,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAchE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAQ5E;;;GAGG;AACH,eAAO,MAAM,eAAe,QAEqF,CAAA;AAEjH,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAA;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAA;IACtE;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;IACvC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAA;CAC1B;AAsDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CA+B9E;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAkCtG;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC7C,WAAW,EAAE,MAAM,GACjB,CAAC,KAAK,EAAE,MAAM,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS7D;AAmHD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA6RxF"}
+{"version":3,"file":"build-bdc.d.ts","sourceRoot":"","sources":["../../lib/sdk/build-bdc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAcH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAMrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAgBzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAQ5E;;;GAGG;AACH,eAAO,MAAM,eAAe,QAEqF,CAAA;AAEjH,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAA;IACvE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAA;IACtE;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAA;IACvC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAA;CAC1B;AA4CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CA+B9E;AAuCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA8DtG;AAED;;;;;;;;GAQG;AACH,wBAAsB,8BAA8B,CACnD,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAStE;AAsHD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAoSxF"}