@mailwoman/mcp 8.2.0 → 8.4.0

package/cli.ts

@@ -6,14 +6,30 @@
  *
  *   `mailwoman-mcp` — boot the MCP server over stdio. Wires the real `MCPToolDeps` (`tools.ts`) from the mailwoman
  *   library: `createRuntimePipeline` for parse/POI-intent, `geocode-core`'s `geocodeAddress` for geocode,
- *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, and `@mailwoman/core/layers` for the layer
- *   manifest tool.
+ *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, `@mailwoman/core/layers` for the layer
+ *   manifest tool, and `@mailwoman/bdc`'s `filingLandscape`/`plausibilityCheck` for the two BDC tools.
  *
  *   Deps are LAZY: nothing here loads the neural weights or opens a gazetteer db at startup — an MCP client
  *   connects, lists tools, and may never call one (or may call `mailwoman_overpass_export`/`mailwoman_layer_manifest`,
  *   neither of which needs the classifier at all). The shared classifier+resolver are built once, on the FIRST call
  *   to any tool that needs them, and cached for the process lifetime.
  *
+ *   **Graceful layer-absent guards (2b task 7, decision 6).** Both BDC-backed tools treat a missing/unreadable
+ *   database file as absence, never a raw `node:sqlite` throw ("unable to open database file"): `bdcFilingLandscape`
+ *   requires bdc.db unconditionally, so a missing file becomes one friendly thrown `Error` naming the layer;
+ *   `plausibilityCheck`'s `bdcDB`/`poi` deps are each OPTIONAL, so a missing/absent `bdc_database_path`/
+ *   `poi_database_path` degrades to the SAME typed-abstain evidence entry (`{type:"abstain",
+ *   reason:"requires_bdc_layer"|"requires_build_local_layer"}`) the scorer already produces for an omitted dep. The
+ *   guards themselves (`assertBDCDatabaseExists`, `openBDCDatabaseIfPresent`, `openPlausibilityPOIDeps`) live in
+ *   `./layer-guards.ts`, NOT here — they're pure, transport-independent logic with no need for the stdio connection
+ *   this file opens at import time (which is exactly why THIS file can't be unit-tested directly; see
+ *   `layer-guards.test.ts` for their branch coverage).
+ *
+ *   `mailwoman_filer_lookup` (3a task 7) follows the SAME "requires the layer unconditionally" discipline as
+ *   `mailwoman_bdc_filing_landscape` (`assertFilerDatabaseExists` + `openFilerDatabaseIfPresent`, mirroring
+ *   `assertBDCDatabaseExists` + the BDC open) — `filerLookup` itself has no optional-dep abstain shape (gate 4 makes
+ *   it throw rather than answer unstamped), so a missing filer.db becomes one friendly thrown Error naming the layer.
+ *
  *   ```sh
  *   mailwoman-mcp                       # geocode/poi_search degrade gracefully with no poi.db wired
  *   mailwoman-mcp --poi-db poi.db       # mailwoman_poi_search additionally executes against poi.db
@@ -24,8 +40,10 @@ import { existsSync } from "node:fs"
 import { DatabaseSync } from "node:sqlite"
 import { parseArgs } from "node:util"
 
+import { filingLandscape, plausibilityCheck, type BDCDatabase } from "@mailwoman/bdc"
 import { DatabaseClient } from "@mailwoman/core/kysley/client"
 import { readLayerManifest, type LayerContractDatabase } from "@mailwoman/core/layers"
+import { filerLookup, toFRN, type FRN } from "@mailwoman/filer/sdk"
 import { NeuralAddressClassifier } from "@mailwoman/neural"
 import { getPOICategory } from "@mailwoman/poi-taxonomy"
 import { createWOFResolver, type Resolver } from "@mailwoman/resolver"
@@ -39,6 +57,13 @@ import {
 	wofShardPaths,
 } from "mailwoman/resolver-backend"
 
+import {
+	assertBDCDatabaseExists,
+	assertFilerDatabaseExists,
+	openBDCDatabaseIfPresent,
+	openFilerDatabaseIfPresent,
+	openPlausibilityPOIDeps,
+} from "./layer-guards.ts"
 import { createMCPServer } from "./server.ts"
 import type { MCPToolDeps } from "./tools.ts"
 
@@ -117,6 +142,18 @@ async function getPoiPipeline(dbPath: string | undefined): Promise<Pipeline> {
 	return pipeline
 }
 
+/**
+ * `plausibilityCheck`'s geocode dep — reuses the SAME shared classifier+resolver `deps.geocode` builds from (see the
+ * module header's laziness note), wired at this CLI/MCP layer per the 2b task 5 brief ("`deriveGeocodeRegister`/
+ * formatted register is the geocode dep's concern, wired at the CLI/MCP layer"). The real return type (`GeocodeResult`)
+ * is structurally assignable to `plausibility.ts`'s minimal `GeocodeLike` — no adapter needed.
+ */
+async function resolveGeocode(address: string) {
+	const { classifier, resolver, shards } = await loadCore()
+
+	return geocodeAddress(address, { classifier, resolver, shards: shards.for })
+}
+
 const deps: MCPToolDeps = {
 	async parse(text, opts) {
 		const pipeline = opts?.poi ? await getPoiPipeline(poiDatabasePath) : await getPlainPipeline()
@@ -125,9 +162,7 @@ const deps: MCPToolDeps = {
 	},
 
 	async geocode(text) {
-		const { classifier, resolver, shards } = await loadCore()
-
-		return geocodeAddress(text, { classifier, resolver, shards: shards.for })
+		return resolveGeocode(text)
 	},
 
 	async poiSearch(q) {
@@ -177,6 +212,66 @@ const deps: MCPToolDeps = {
 
 		return { manifest, coverage }
 	},
+
+	async bdcFilingLandscape(q) {
+		// Decision 6 (2b task 7): `mailwoman_bdc_filing_landscape` requires bdc.db unconditionally (no optional-dep
+		// abstain shape exists for this tool), so a missing file becomes a friendly thrown Error naming the layer —
+		// never the raw `node:sqlite` "unable to open database file" message.
+		assertBDCDatabaseExists("mailwoman_bdc_filing_landscape", q.databasePath)
+
+		using db = new DatabaseClient<BDCDatabase>({ database: new DatabaseSync(q.databasePath, { readOnly: true }) })
+
+		return filingLandscape(db, { geoids: q.geoids, h3Cells: q.h3Cells })
+	},
+
+	async plausibilityCheck(q) {
+		const bdcDB = openBDCDatabaseIfPresent(q.bdcDatabasePath)
+		const poi = await openPlausibilityPOIDeps(q.poiDatabasePath)
+
+		try {
+			return await plausibilityCheck(
+				{
+					address: q.address,
+					point: q.point,
+					geoid: q.geoid,
+					technologyCode: q.technologyCode,
+					claimedDownloadMbps: q.claimedDownloadMbps,
+				},
+				{ bdcDB, poi, geocode: resolveGeocode }
+			)
+		} finally {
+			bdcDB?.destroy()
+			poi?.contractDB.destroy()
+		}
+	},
+
+	async filerLookup(q) {
+		// Decision 6/gate 4 (3a task 7): filerLookup has no optional-dep abstain shape — it throws rather than
+		// answer unstamped — so filer.db is required unconditionally, same discipline as bdc.db is for
+		// mailwoman_bdc_filing_landscape.
+		assertFilerDatabaseExists("mailwoman_filer_lookup", q.databasePath)
+
+		using db = openFilerDatabaseIfPresent(q.databasePath)!
+
+		let frn: FRN | undefined
+
+		if (q.frn !== undefined) {
+			const parsed = toFRN(q.frn)
+
+			if (!parsed) {
+				throw new Error(`mailwoman_filer_lookup: "${q.frn}" is not a valid FRN`)
+			}
+
+			frn = parsed
+		}
+
+		return filerLookup(db, {
+			frn,
+			form499ID: q.form499ID,
+			bdcProviderID: q.bdcProviderID,
+			asOf: q.asOf,
+		})
+	},
 }
 
 const server = createMCPServer(deps)

package/layer-guards.ts

@@ -0,0 +1,101 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Decision 6 (2b task 7) layer-absent guards — pulled out of `cli.ts` into their own importable module (task 7
+ *   fix round 1 review finding) so the branching itself has direct unit coverage (`layer-guards.test.ts`), not just
+ *   "the tool handler passes an abstain through" (`tools.test.ts`'s stub-level dispatch tests). `cli.ts`
+ *   top-level-`await`s a real stdio transport connection at import time, so IT can't be imported by vitest — these
+ *   three functions have no such dependency (pure existence-check + open, or a thrown Error), so they live here and
+ *   `cli.ts` just calls them.
+ *
+ *   - `openBDCDatabaseIfPresent` / `openPlausibilityPOIDeps` — `mailwoman_plausibility_check`'s `bdcDB`/`poi` deps
+ *     (`PlausibilityDeps`) are each OPTIONAL, so a missing/absent path degrades to `undefined`, which
+ *     `plausibilityCheck` (`@mailwoman/bdc`) already turns into a typed abstain evidence entry
+ *     (`{type:"abstain", reason:"requires_bdc_layer"|"requires_build_local_layer"}`) — never a raw sqlite throw.
+ *   - `assertBDCDatabaseExists` — `mailwoman_bdc_filing_landscape` requires bdc.db unconditionally (no optional-dep
+ *     abstain shape exists for that tool), so a missing file becomes one friendly thrown `Error` naming the layer
+ *     instead of the raw `node:sqlite` "unable to open database file" message.
+ *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` (3a task 7) — the SAME pairing, for filer.db.
+ *     `mailwoman_filer_lookup` requires filer.db unconditionally (mirrors `mailwoman_bdc_filing_landscape`'s own
+ *     "requires the layer" discipline — `filerLookup` itself has no optional-dep abstain shape either, since gate
+ *     4 makes it throw rather than answer unstamped), so `cli.ts` pairs `assertFilerDatabaseExists` (the friendly
+ *     throw) with `openFilerDatabaseIfPresent` (the actual open) the same way `bdcFilingLandscape`'s handler does.
+ */
+
+import { existsSync } from "node:fs"
+import { DatabaseSync } from "node:sqlite"
+
+import type { BDCDatabase, PlausibilityDeps } from "@mailwoman/bdc"
+import { DatabaseClient } from "@mailwoman/core/kysley/client"
+import type { LayerContractDatabase } from "@mailwoman/core/layers"
+import type { FilerDatabase } from "@mailwoman/filer"
+
+/**
+ * Open a bdc.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw.
+ * See the module header.
+ */
+export function openBDCDatabaseIfPresent(databasePath: string | undefined): DatabaseClient<BDCDatabase> | undefined {
+	if (!databasePath || !existsSync(databasePath)) return undefined
+
+	return new DatabaseClient<BDCDatabase>({ database: new DatabaseSync(databasePath, { readOnly: true }) })
+}
+
+/**
+ * Same graceful discipline as {@link openBDCDatabaseIfPresent}, for the poi.db side of `plausibilityCheck`'s deps —
+ * `undefined` here becomes the `{type:"abstain", reason:"requires_build_local_layer"}` entry `plausibilityCheck`
+ * already produces when a claimed technology's physical-plant categories can't be searched. `POILookup` is dynamically
+ * imported (matching `cli.ts`'s existing `resolver-wof-sqlite` laziness) since it's only ever needed when a caller
+ * actually wires a poi.db. `lookup` and `contractDB` share ONE `DatabaseSync` handle (the AGENTS.md "one connection,
+ * shared" convention) — a real poi.db's rows and its `layer_manifest`/`layer_coverage` tables live in the same file in
+ * production, so disposing `contractDB` (which closes the shared handle) is enough; `POILookup` never owns it
+ * (constructed with `{database}`, not `{databasePath}` — see `poi-lookup.ts`), so it never double-closes.
+ */
+export async function openPlausibilityPOIDeps(databasePath: string | undefined): Promise<PlausibilityDeps["poi"]> {
+	if (!databasePath || !existsSync(databasePath)) return undefined
+
+	const { POILookup } = await import("@mailwoman/resolver-wof-sqlite/poi-lookup")
+	const database = new DatabaseSync(databasePath, { readOnly: true })
+
+	return {
+		lookup: new POILookup({ database }),
+		contractDB: new DatabaseClient<LayerContractDatabase>({ database }),
+	}
+}
+
+/**
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_bdc_filing_landscape`'s guard
+ * (decision 6b). `toolName` is threaded through so the message matches whichever tool calls this (today: only
+ * `mailwoman_bdc_filing_landscape`).
+ */
+export function assertBDCDatabaseExists(toolName: string, databasePath: string): void {
+	if (!existsSync(databasePath)) {
+		throw new Error(`${toolName}: bdc.db not found at "${databasePath}"`)
+	}
+}
+
+/**
+ * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw
+ * (3a task 7, mirroring {@link openBDCDatabaseIfPresent}). Used by `cli.ts`'s `mailwoman_filer_lookup` handler after
+ * {@link assertFilerDatabaseExists} has already confirmed the file is present.
+ */
+export function openFilerDatabaseIfPresent(
+	databasePath: string | undefined
+): DatabaseClient<FilerDatabase> | undefined {
+	if (!databasePath || !existsSync(databasePath)) return undefined
+
+	return new DatabaseClient<FilerDatabase>({ database: new DatabaseSync(databasePath, { readOnly: true }) })
+}
+
+/**
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_filer_lookup`'s guard (3a
+ * task 7, mirroring {@link assertBDCDatabaseExists}). `filerLookup` itself has no optional-dep abstain shape (gate 4
+ * makes it throw rather than answer unstamped), so filer.db is required unconditionally, same as bdc.db is for
+ * `mailwoman_bdc_filing_landscape`.
+ */
+export function assertFilerDatabaseExists(toolName: string, databasePath: string): void {
+	if (!existsSync(databasePath)) {
+		throw new Error(`${toolName}: filer.db not found at "${databasePath}"`)
+	}
+}

package/out/cli.d.ts

@@ -6,14 +6,30 @@
  *
  *   `mailwoman-mcp` — boot the MCP server over stdio. Wires the real `MCPToolDeps` (`tools.ts`) from the mailwoman
  *   library: `createRuntimePipeline` for parse/POI-intent, `geocode-core`'s `geocodeAddress` for geocode,
- *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, and `@mailwoman/core/layers` for the layer
- *   manifest tool.
+ *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, `@mailwoman/core/layers` for the layer
+ *   manifest tool, and `@mailwoman/bdc`'s `filingLandscape`/`plausibilityCheck` for the two BDC tools.
  *
  *   Deps are LAZY: nothing here loads the neural weights or opens a gazetteer db at startup — an MCP client
  *   connects, lists tools, and may never call one (or may call `mailwoman_overpass_export`/`mailwoman_layer_manifest`,
  *   neither of which needs the classifier at all). The shared classifier+resolver are built once, on the FIRST call
  *   to any tool that needs them, and cached for the process lifetime.
  *
+ *   **Graceful layer-absent guards (2b task 7, decision 6).** Both BDC-backed tools treat a missing/unreadable
+ *   database file as absence, never a raw `node:sqlite` throw ("unable to open database file"): `bdcFilingLandscape`
+ *   requires bdc.db unconditionally, so a missing file becomes one friendly thrown `Error` naming the layer;
+ *   `plausibilityCheck`'s `bdcDB`/`poi` deps are each OPTIONAL, so a missing/absent `bdc_database_path`/
+ *   `poi_database_path` degrades to the SAME typed-abstain evidence entry (`{type:"abstain",
+ *   reason:"requires_bdc_layer"|"requires_build_local_layer"}`) the scorer already produces for an omitted dep. The
+ *   guards themselves (`assertBDCDatabaseExists`, `openBDCDatabaseIfPresent`, `openPlausibilityPOIDeps`) live in
+ *   `./layer-guards.ts`, NOT here — they're pure, transport-independent logic with no need for the stdio connection
+ *   this file opens at import time (which is exactly why THIS file can't be unit-tested directly; see
+ *   `layer-guards.test.ts` for their branch coverage).
+ *
+ *   `mailwoman_filer_lookup` (3a task 7) follows the SAME "requires the layer unconditionally" discipline as
+ *   `mailwoman_bdc_filing_landscape` (`assertFilerDatabaseExists` + `openFilerDatabaseIfPresent`, mirroring
+ *   `assertBDCDatabaseExists` + the BDC open) — `filerLookup` itself has no optional-dep abstain shape (gate 4 makes
+ *   it throw rather than answer unstamped), so a missing filer.db becomes one friendly thrown Error naming the layer.
+ *
  *   ```sh
  *   mailwoman-mcp                       # geocode/poi_search degrade gracefully with no poi.db wired
  *   mailwoman-mcp --poi-db poi.db       # mailwoman_poi_search additionally executes against poi.db

package/out/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG"}

package/out/cli.js

@@ -6,14 +6,30 @@
  *
  *   `mailwoman-mcp` — boot the MCP server over stdio. Wires the real `MCPToolDeps` (`tools.ts`) from the mailwoman
  *   library: `createRuntimePipeline` for parse/POI-intent, `geocode-core`'s `geocodeAddress` for geocode,
- *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, and `@mailwoman/core/layers` for the layer
- *   manifest tool.
+ *   `mailwoman/poi-overpass`'s `emitOverpassQL` for the export tool, `@mailwoman/core/layers` for the layer
+ *   manifest tool, and `@mailwoman/bdc`'s `filingLandscape`/`plausibilityCheck` for the two BDC tools.
  *
  *   Deps are LAZY: nothing here loads the neural weights or opens a gazetteer db at startup — an MCP client
  *   connects, lists tools, and may never call one (or may call `mailwoman_overpass_export`/`mailwoman_layer_manifest`,
  *   neither of which needs the classifier at all). The shared classifier+resolver are built once, on the FIRST call
  *   to any tool that needs them, and cached for the process lifetime.
  *
+ *   **Graceful layer-absent guards (2b task 7, decision 6).** Both BDC-backed tools treat a missing/unreadable
+ *   database file as absence, never a raw `node:sqlite` throw ("unable to open database file"): `bdcFilingLandscape`
+ *   requires bdc.db unconditionally, so a missing file becomes one friendly thrown `Error` naming the layer;
+ *   `plausibilityCheck`'s `bdcDB`/`poi` deps are each OPTIONAL, so a missing/absent `bdc_database_path`/
+ *   `poi_database_path` degrades to the SAME typed-abstain evidence entry (`{type:"abstain",
+ *   reason:"requires_bdc_layer"|"requires_build_local_layer"}`) the scorer already produces for an omitted dep. The
+ *   guards themselves (`assertBDCDatabaseExists`, `openBDCDatabaseIfPresent`, `openPlausibilityPOIDeps`) live in
+ *   `./layer-guards.ts`, NOT here — they're pure, transport-independent logic with no need for the stdio connection
+ *   this file opens at import time (which is exactly why THIS file can't be unit-tested directly; see
+ *   `layer-guards.test.ts` for their branch coverage).
+ *
+ *   `mailwoman_filer_lookup` (3a task 7) follows the SAME "requires the layer unconditionally" discipline as
+ *   `mailwoman_bdc_filing_landscape` (`assertFilerDatabaseExists` + `openFilerDatabaseIfPresent`, mirroring
+ *   `assertBDCDatabaseExists` + the BDC open) — `filerLookup` itself has no optional-dep abstain shape (gate 4 makes
+ *   it throw rather than answer unstamped), so a missing filer.db becomes one friendly thrown Error naming the layer.
+ *
  *   ```sh
  *   mailwoman-mcp                       # geocode/poi_search degrade gracefully with no poi.db wired
  *   mailwoman-mcp --poi-db poi.db       # mailwoman_poi_search additionally executes against poi.db
@@ -22,8 +38,10 @@
 import { existsSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { parseArgs } from "node:util";
+import { filingLandscape, plausibilityCheck } from "@mailwoman/bdc";
 import { DatabaseClient } from "@mailwoman/core/kysley/client";
 import { readLayerManifest } from "@mailwoman/core/layers";
+import { filerLookup, toFRN } from "@mailwoman/filer/sdk";
 import { NeuralAddressClassifier } from "@mailwoman/neural";
 import { getPOICategory } from "@mailwoman/poi-taxonomy";
 import { createWOFResolver } from "@mailwoman/resolver";
@@ -31,6 +49,7 @@ import { createRuntimePipeline } from "mailwoman";
 import { geocodeAddress, ShardProvider } from "mailwoman/geocode-core";
 import { emitOverpassQL } from "mailwoman/poi-overpass";
 import { createResolverBackend, mailwomanDataRoot, resolveCandidateDBPath, wofShardPaths, } from "mailwoman/resolver-backend";
+import { assertBDCDatabaseExists, assertFilerDatabaseExists, openBDCDatabaseIfPresent, openFilerDatabaseIfPresent, openPlausibilityPOIDeps, } from "./layer-guards.js";
 import { createMCPServer } from "./server.js";
 const { values } = parseArgs({
     options: {
@@ -91,14 +110,23 @@ async function getPoiPipeline(dbPath) {
     poiPipelines.set(key, pipeline);
     return pipeline;
 }
+/**
+ * `plausibilityCheck`'s geocode dep — reuses the SAME shared classifier+resolver `deps.geocode` builds from (see the
+ * module header's laziness note), wired at this CLI/MCP layer per the 2b task 5 brief ("`deriveGeocodeRegister`/
+ * formatted register is the geocode dep's concern, wired at the CLI/MCP layer"). The real return type (`GeocodeResult`)
+ * is structurally assignable to `plausibility.ts`'s minimal `GeocodeLike` — no adapter needed.
+ */
+async function resolveGeocode(address) {
+    const { classifier, resolver, shards } = await loadCore();
+    return geocodeAddress(address, { classifier, resolver, shards: shards.for });
+}
 const deps = {
     async parse(text, opts) {
         const pipeline = opts?.poi ? await getPoiPipeline(poiDatabasePath) : await getPlainPipeline();
         return pipeline(text);
     },
     async geocode(text) {
-        const { classifier, resolver, shards } = await loadCore();
-        return geocodeAddress(text, { classifier, resolver, shards: shards.for });
+        return resolveGeocode(text);
     },
     async poiSearch(q) {
         const pipeline = await getPoiPipeline(q.poiDatabasePath ?? poiDatabasePath);
@@ -135,6 +163,52 @@ const deps = {
             .executeTakeFirst();
         return { manifest, coverage };
     },
+    async bdcFilingLandscape(q) {
+        // Decision 6 (2b task 7): `mailwoman_bdc_filing_landscape` requires bdc.db unconditionally (no optional-dep
+        // abstain shape exists for this tool), so a missing file becomes a friendly thrown Error naming the layer —
+        // never the raw `node:sqlite` "unable to open database file" message.
+        assertBDCDatabaseExists("mailwoman_bdc_filing_landscape", q.databasePath);
+        using db = new DatabaseClient({ database: new DatabaseSync(q.databasePath, { readOnly: true }) });
+        return filingLandscape(db, { geoids: q.geoids, h3Cells: q.h3Cells });
+    },
+    async plausibilityCheck(q) {
+        const bdcDB = openBDCDatabaseIfPresent(q.bdcDatabasePath);
+        const poi = await openPlausibilityPOIDeps(q.poiDatabasePath);
+        try {
+            return await plausibilityCheck({
+                address: q.address,
+                point: q.point,
+                geoid: q.geoid,
+                technologyCode: q.technologyCode,
+                claimedDownloadMbps: q.claimedDownloadMbps,
+            }, { bdcDB, poi, geocode: resolveGeocode });
+        }
+        finally {
+            bdcDB?.destroy();
+            poi?.contractDB.destroy();
+        }
+    },
+    async filerLookup(q) {
+        // Decision 6/gate 4 (3a task 7): filerLookup has no optional-dep abstain shape — it throws rather than
+        // answer unstamped — so filer.db is required unconditionally, same discipline as bdc.db is for
+        // mailwoman_bdc_filing_landscape.
+        assertFilerDatabaseExists("mailwoman_filer_lookup", q.databasePath);
+        using db = openFilerDatabaseIfPresent(q.databasePath);
+        let frn;
+        if (q.frn !== undefined) {
+            const parsed = toFRN(q.frn);
+            if (!parsed) {
+                throw new Error(`mailwoman_filer_lookup: "${q.frn}" is not a valid FRN`);
+            }
+            frn = parsed;
+        }
+        return filerLookup(db, {
+            frn,
+            form499ID: q.form499ID,
+            bdcProviderID: q.bdcProviderID,
+            asOf: q.asOf,
+        });
+    },
 };
 const server = createMCPServer(deps);
 const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");

package/out/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}

package/out/layer-guards.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Decision 6 (2b task 7) layer-absent guards — pulled out of `cli.ts` into their own importable module (task 7
+ *   fix round 1 review finding) so the branching itself has direct unit coverage (`layer-guards.test.ts`), not just
+ *   "the tool handler passes an abstain through" (`tools.test.ts`'s stub-level dispatch tests). `cli.ts`
+ *   top-level-`await`s a real stdio transport connection at import time, so IT can't be imported by vitest — these
+ *   three functions have no such dependency (pure existence-check + open, or a thrown Error), so they live here and
+ *   `cli.ts` just calls them.
+ *
+ *   - `openBDCDatabaseIfPresent` / `openPlausibilityPOIDeps` — `mailwoman_plausibility_check`'s `bdcDB`/`poi` deps
+ *     (`PlausibilityDeps`) are each OPTIONAL, so a missing/absent path degrades to `undefined`, which
+ *     `plausibilityCheck` (`@mailwoman/bdc`) already turns into a typed abstain evidence entry
+ *     (`{type:"abstain", reason:"requires_bdc_layer"|"requires_build_local_layer"}`) — never a raw sqlite throw.
+ *   - `assertBDCDatabaseExists` — `mailwoman_bdc_filing_landscape` requires bdc.db unconditionally (no optional-dep
+ *     abstain shape exists for that tool), so a missing file becomes one friendly thrown `Error` naming the layer
+ *     instead of the raw `node:sqlite` "unable to open database file" message.
+ *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` (3a task 7) — the SAME pairing, for filer.db.
+ *     `mailwoman_filer_lookup` requires filer.db unconditionally (mirrors `mailwoman_bdc_filing_landscape`'s own
+ *     "requires the layer" discipline — `filerLookup` itself has no optional-dep abstain shape either, since gate
+ *     4 makes it throw rather than answer unstamped), so `cli.ts` pairs `assertFilerDatabaseExists` (the friendly
+ *     throw) with `openFilerDatabaseIfPresent` (the actual open) the same way `bdcFilingLandscape`'s handler does.
+ */
+import type { BDCDatabase, PlausibilityDeps } from "@mailwoman/bdc";
+import { DatabaseClient } from "@mailwoman/core/kysley/client";
+import type { FilerDatabase } from "@mailwoman/filer";
+/**
+ * Open a bdc.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw.
+ * See the module header.
+ */
+export declare function openBDCDatabaseIfPresent(databasePath: string | undefined): DatabaseClient<BDCDatabase> | undefined;
+/**
+ * Same graceful discipline as {@link openBDCDatabaseIfPresent}, for the poi.db side of `plausibilityCheck`'s deps —
+ * `undefined` here becomes the `{type:"abstain", reason:"requires_build_local_layer"}` entry `plausibilityCheck`
+ * already produces when a claimed technology's physical-plant categories can't be searched. `POILookup` is dynamically
+ * imported (matching `cli.ts`'s existing `resolver-wof-sqlite` laziness) since it's only ever needed when a caller
+ * actually wires a poi.db. `lookup` and `contractDB` share ONE `DatabaseSync` handle (the AGENTS.md "one connection,
+ * shared" convention) — a real poi.db's rows and its `layer_manifest`/`layer_coverage` tables live in the same file in
+ * production, so disposing `contractDB` (which closes the shared handle) is enough; `POILookup` never owns it
+ * (constructed with `{database}`, not `{databasePath}` — see `poi-lookup.ts`), so it never double-closes.
+ */
+export declare function openPlausibilityPOIDeps(databasePath: string | undefined): Promise<PlausibilityDeps["poi"]>;
+/**
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_bdc_filing_landscape`'s guard
+ * (decision 6b). `toolName` is threaded through so the message matches whichever tool calls this (today: only
+ * `mailwoman_bdc_filing_landscape`).
+ */
+export declare function assertBDCDatabaseExists(toolName: string, databasePath: string): void;
+/**
+ * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw
+ * (3a task 7, mirroring {@link openBDCDatabaseIfPresent}). Used by `cli.ts`'s `mailwoman_filer_lookup` handler after
+ * {@link assertFilerDatabaseExists} has already confirmed the file is present.
+ */
+export declare function openFilerDatabaseIfPresent(databasePath: string | undefined): DatabaseClient<FilerDatabase> | undefined;
+/**
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_filer_lookup`'s guard (3a
+ * task 7, mirroring {@link assertBDCDatabaseExists}). `filerLookup` itself has no optional-dep abstain shape (gate 4
+ * makes it throw rather than answer unstamped), so filer.db is required unconditionally, same as bdc.db is for
+ * `mailwoman_bdc_filing_landscape`.
+ */
+export declare function assertFilerDatabaseExists(toolName: string, databasePath: string): void;
+//# sourceMappingURL=layer-guards.d.ts.map

package/out/layer-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-guards.d.ts","sourceRoot":"","sources":["../layer-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAAC,WAAW,CAAC,GAAG,SAAS,CAIlH;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAUhH;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAIpF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,cAAc,CAAC,aAAa,CAAC,GAAG,SAAS,CAI3C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAItF"}

package/out/layer-guards.js

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Decision 6 (2b task 7) layer-absent guards — pulled out of `cli.ts` into their own importable module (task 7
+ *   fix round 1 review finding) so the branching itself has direct unit coverage (`layer-guards.test.ts`), not just
+ *   "the tool handler passes an abstain through" (`tools.test.ts`'s stub-level dispatch tests). `cli.ts`
+ *   top-level-`await`s a real stdio transport connection at import time, so IT can't be imported by vitest — these
+ *   three functions have no such dependency (pure existence-check + open, or a thrown Error), so they live here and
+ *   `cli.ts` just calls them.
+ *
+ *   - `openBDCDatabaseIfPresent` / `openPlausibilityPOIDeps` — `mailwoman_plausibility_check`'s `bdcDB`/`poi` deps
+ *     (`PlausibilityDeps`) are each OPTIONAL, so a missing/absent path degrades to `undefined`, which
+ *     `plausibilityCheck` (`@mailwoman/bdc`) already turns into a typed abstain evidence entry
+ *     (`{type:"abstain", reason:"requires_bdc_layer"|"requires_build_local_layer"}`) — never a raw sqlite throw.
+ *   - `assertBDCDatabaseExists` — `mailwoman_bdc_filing_landscape` requires bdc.db unconditionally (no optional-dep
+ *     abstain shape exists for that tool), so a missing file becomes one friendly thrown `Error` naming the layer
+ *     instead of the raw `node:sqlite` "unable to open database file" message.
+ *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` (3a task 7) — the SAME pairing, for filer.db.
+ *     `mailwoman_filer_lookup` requires filer.db unconditionally (mirrors `mailwoman_bdc_filing_landscape`'s own
+ *     "requires the layer" discipline — `filerLookup` itself has no optional-dep abstain shape either, since gate
+ *     4 makes it throw rather than answer unstamped), so `cli.ts` pairs `assertFilerDatabaseExists` (the friendly
+ *     throw) with `openFilerDatabaseIfPresent` (the actual open) the same way `bdcFilingLandscape`'s handler does.
+ */
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { DatabaseClient } from "@mailwoman/core/kysley/client";
+/**
+ * Open a bdc.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw.
+ * See the module header.
+ */
+export function openBDCDatabaseIfPresent(databasePath) {
+    if (!databasePath || !existsSync(databasePath))
+        return undefined;
+    return new DatabaseClient({ database: new DatabaseSync(databasePath, { readOnly: true }) });
+}
+/**
+ * Same graceful discipline as {@link openBDCDatabaseIfPresent}, for the poi.db side of `plausibilityCheck`'s deps —
+ * `undefined` here becomes the `{type:"abstain", reason:"requires_build_local_layer"}` entry `plausibilityCheck`
+ * already produces when a claimed technology's physical-plant categories can't be searched. `POILookup` is dynamically
+ * imported (matching `cli.ts`'s existing `resolver-wof-sqlite` laziness) since it's only ever needed when a caller
+ * actually wires a poi.db. `lookup` and `contractDB` share ONE `DatabaseSync` handle (the AGENTS.md "one connection,
+ * shared" convention) — a real poi.db's rows and its `layer_manifest`/`layer_coverage` tables live in the same file in
+ * production, so disposing `contractDB` (which closes the shared handle) is enough; `POILookup` never owns it
+ * (constructed with `{database}`, not `{databasePath}` — see `poi-lookup.ts`), so it never double-closes.
+ */
+export async function openPlausibilityPOIDeps(databasePath) {
+    if (!databasePath || !existsSync(databasePath))
+        return undefined;
+    const { POILookup } = await import("@mailwoman/resolver-wof-sqlite/poi-lookup");
+    const database = new DatabaseSync(databasePath, { readOnly: true });
+    return {
+        lookup: new POILookup({ database }),
+        contractDB: new DatabaseClient({ database }),
+    };
+}
+/**
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_bdc_filing_landscape`'s guard
+ * (decision 6b). `toolName` is threaded through so the message matches whichever tool calls this (today: only
+ * `mailwoman_bdc_filing_landscape`).
+ */
+export function assertBDCDatabaseExists(toolName, databasePath) {
+    if (!existsSync(databasePath)) {
+        throw new Error(`${toolName}: bdc.db not found at "${databasePath}"`);
+    }
+}
+/**
+ * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw
+ * (3a task 7, mirroring {@link openBDCDatabaseIfPresent}). Used by `cli.ts`'s `mailwoman_filer_lookup` handler after
+ * {@link assertFilerDatabaseExists} has already confirmed the file is present.
+ */
+export function openFilerDatabaseIfPresent(databasePath) {
+    if (!databasePath || !existsSync(databasePath))
+        return undefined;
+    return new DatabaseClient({ database: new DatabaseSync(databasePath, { readOnly: true }) });
+}
+/**
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_filer_lookup`'s guard (3a
+ * task 7, mirroring {@link assertBDCDatabaseExists}). `filerLookup` itself has no optional-dep abstain shape (gate 4
+ * makes it throw rather than answer unstamped), so filer.db is required unconditionally, same as bdc.db is for
+ * `mailwoman_bdc_filing_landscape`.
+ */
+export function assertFilerDatabaseExists(toolName, databasePath) {
+    if (!existsSync(databasePath)) {
+        throw new Error(`${toolName}: filer.db not found at "${databasePath}"`);
+    }
+}
+//# sourceMappingURL=layer-guards.js.map

package/out/layer-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-guards.js","sourceRoot":"","sources":["../layer-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAI9D;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,YAAgC;IACxE,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,SAAS,CAAA;IAEhE,OAAO,IAAI,cAAc,CAAc,EAAE,QAAQ,EAAE,IAAI,YAAY,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;AACzG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,YAAgC;IAC7E,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,SAAS,CAAA;IAEhE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,2CAA2C,CAAC,CAAA;IAC/E,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAEnE,OAAO;QACN,MAAM,EAAE,IAAI,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QACnC,UAAU,EAAE,IAAI,cAAc,CAAwB,EAAE,QAAQ,EAAE,CAAC;KACnE,CAAA;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB,EAAE,YAAoB;IAC7E,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,0BAA0B,YAAY,GAAG,CAAC,CAAA;IACtE,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACzC,YAAgC;IAEhC,IAAI,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,SAAS,CAAA;IAEhE,OAAO,IAAI,cAAc,CAAgB,EAAE,QAAQ,EAAE,IAAI,YAAY,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;AAC3G,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAgB,EAAE,YAAoB;IAC/E,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,4BAA4B,YAAY,GAAG,CAAC,CAAA;IACxE,CAAC;AACF,CAAC"}

package/out/server.d.ts

@@ -12,9 +12,9 @@ import { type MCPToolDeps } from "./tools.ts";
 /**
  * Build an `McpServer` with every `tools.ts` tool registered. A handler's returned value is JSON-stringified into a
  * single `text` content block — every tool here answers with structured data (parse trees, geocode results, search
- * hits), so a plain JSON text block is the simplest faithful rendering; none of the five tools need images, resource
- * links, or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level
- * failure, so a bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
+ * hits), so a plain JSON text block is the simplest faithful rendering; none of the tools need images, resource links,
+ * or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level failure, so a
+ * bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
  */
 export declare function createMCPServer(deps: MCPToolDeps): McpServer;
 //# sourceMappingURL=server.d.ts.map

package/out/server.js

@@ -19,9 +19,9 @@ const MCP_SERVER_VERSION = "7.1.0";
 /**
  * Build an `McpServer` with every `tools.ts` tool registered. A handler's returned value is JSON-stringified into a
  * single `text` content block — every tool here answers with structured data (parse trees, geocode results, search
- * hits), so a plain JSON text block is the simplest faithful rendering; none of the five tools need images, resource
- * links, or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level
- * failure, so a bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
+ * hits), so a plain JSON text block is the simplest faithful rendering; none of the tools need images, resource links,
+ * or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level failure, so a
+ * bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
  */
 export function createMCPServer(deps) {
     const server = new McpServer({ name: "mailwoman", version: MCP_SERVER_VERSION });

package/out/tools.d.ts

@@ -8,7 +8,9 @@
  *   file (the actual product surface) is testable without any MCP plumbing — `tools.test.ts` calls
  *   `buildToolTable` directly with stub deps.
  *
- *   Five tools, one per capability the exotic-POI arc's other packages expose to a human/CLI caller:
+ *   One tool per capability the exotic-POI/BDC arcs' other packages expose to a human/CLI caller — see
+ *   `buildToolTable`'s return value for the authoritative, current list (this comment intentionally states no count,
+ *   so it can't go stale as tools are added):
  *
  *   - `mailwoman_parse` — the runtime pipeline's parse (optionally POI-aware).
  *   - `mailwoman_geocode` — the street-level geocode cascade (`mailwoman/geocode-core`).
@@ -17,6 +19,16 @@
  *     we never run it".
  *   - `mailwoman_layer_manifest` — read a spatial-layer database's provenance manifest + coverage summary
  *     (`@mailwoman/core/layers`).
+ *   - `mailwoman_bdc_filing_landscape` — read a bdc.db layer's provider/technology/speed-bucket filing census over a
+ *     set of census blocks or H3 cells (`@mailwoman/bdc`'s `filingLandscape`).
+ *   - `mailwoman_plausibility_check` — score one claimed broadband-service assertion against BDC filing evidence and
+ *     nearby telecom infrastructure (`@mailwoman/bdc`'s `plausibilityCheck`), returning a positive-evidence-only bundle
+ *     with an always-present `coverage_confidence`. A missing/absent `bdc_database_path`/`poi_database_path` degrades
+ *     to a typed abstain entry in the bundle, never a throw (2b task 7, decision 6).
+ *   - `mailwoman_filer_lookup` (3a task 7) — read the FCC filer identity crosswalk (`@mailwoman/filer`'s
+ *     `filerLookup`) for one identifier (FRN, Form 499 ID, or BDC provider ID): every OTHER identifier it shares an
+ *     authoritative edge with, its current attributes, its authoritative entity cluster, and any inferred links —
+ *     reported separately, never merged into the cluster. `as_of` is always present (defaults to today).
  */
 import { z } from "zod";
 /**
@@ -33,6 +45,30 @@ export interface MCPToolDeps {
     }) => Promise<unknown>;
     overpassExport: (query: string) => Promise<string>;
     layerManifest: (databasePath: string) => Promise<unknown>;
+    bdcFilingLandscape: (q: {
+        databasePath: string;
+        geoids?: string[];
+        h3Cells?: number[];
+    }) => Promise<unknown>;
+    plausibilityCheck: (q: {
+        bdcDatabasePath?: string;
+        poiDatabasePath?: string;
+        address?: string;
+        point?: {
+            type: "Point";
+            coordinates: [number, number];
+        };
+        geoid?: string;
+        technologyCode: number;
+        claimedDownloadMbps: number;
+    }) => Promise<unknown>;
+    filerLookup: (q: {
+        databasePath: string;
+        frn?: string;
+        form499ID?: string;
+        bdcProviderID?: number;
+        asOf?: string;
+    }) => Promise<unknown>;
 }
 /**
  * One MCP tool. `inputSchema` is a plain Zod object (not `any` — this repo's oxlint config errors on

package/out/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACnE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,SAAS,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/E,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClD,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACvC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5D;AA2CD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,CAqE9D"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACnE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,SAAS,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/E,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClD,aAAa,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACzD,kBAAkB,EAAE,CAAC,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5G,iBAAiB,EAAE,CAAC,CAAC,EAAE;QACtB,eAAe,CAAC,EAAE,MAAM,CAAA;QACxB,eAAe,CAAC,EAAE,MAAM,CAAA;QACxB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;QACxD,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,cAAc,EAAE,MAAM,CAAA;QACtB,mBAAmB,EAAE,MAAM,CAAA;KAC3B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACtB,WAAW,EAAE,CAAC,CAAC,EAAE;QAChB,YAAY,EAAE,MAAM,CAAA;QACpB,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,IAAI,CAAC,EAAE,MAAM,CAAA;KACb,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACvC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5D;AAoJD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,EAAE,CAiI9D"}

package/out/tools.js

@@ -8,7 +8,9 @@
  *   file (the actual product surface) is testable without any MCP plumbing — `tools.test.ts` calls
  *   `buildToolTable` directly with stub deps.
  *
- *   Five tools, one per capability the exotic-POI arc's other packages expose to a human/CLI caller:
+ *   One tool per capability the exotic-POI/BDC arcs' other packages expose to a human/CLI caller — see
+ *   `buildToolTable`'s return value for the authoritative, current list (this comment intentionally states no count,
+ *   so it can't go stale as tools are added):
  *
  *   - `mailwoman_parse` — the runtime pipeline's parse (optionally POI-aware).
  *   - `mailwoman_geocode` — the street-level geocode cascade (`mailwoman/geocode-core`).
@@ -17,6 +19,16 @@
  *     we never run it".
  *   - `mailwoman_layer_manifest` — read a spatial-layer database's provenance manifest + coverage summary
  *     (`@mailwoman/core/layers`).
+ *   - `mailwoman_bdc_filing_landscape` — read a bdc.db layer's provider/technology/speed-bucket filing census over a
+ *     set of census blocks or H3 cells (`@mailwoman/bdc`'s `filingLandscape`).
+ *   - `mailwoman_plausibility_check` — score one claimed broadband-service assertion against BDC filing evidence and
+ *     nearby telecom infrastructure (`@mailwoman/bdc`'s `plausibilityCheck`), returning a positive-evidence-only bundle
+ *     with an always-present `coverage_confidence`. A missing/absent `bdc_database_path`/`poi_database_path` degrades
+ *     to a typed abstain entry in the bundle, never a throw (2b task 7, decision 6).
+ *   - `mailwoman_filer_lookup` (3a task 7) — read the FCC filer identity crosswalk (`@mailwoman/filer`'s
+ *     `filerLookup`) for one identifier (FRN, Form 499 ID, or BDC provider ID): every OTHER identifier it shares an
+ *     authoritative edge with, its current attributes, its authoritative entity cluster, and any inferred links —
+ *     reported separately, never merged into the cluster. `as_of` is always present (defaults to today).
  */
 import { z } from "zod";
 const ParseInputSchema = z.object({
@@ -51,6 +63,83 @@ const LayerManifestInputSchema = z.object({
         .min(1)
         .describe("Path to a mailwoman spatial-layer database (poi.db, an address-points shard, etc.)."),
 });
+const BDCFilingLandscapeInputSchema = z.object({
+    database_path: z
+        .string()
+        .min(1)
+        .describe("Path to a bdc.db layer database (FCC Broadband Data Collection availability)."),
+    geoids: z
+        .array(z.string())
+        .min(1)
+        .optional()
+        .describe("15-character census block GEOIDs to query. Provide exactly one of `geoids` or `h3_cells` — never both, never neither, never empty."),
+    h3_cells: z
+        .array(z.number())
+        .min(1)
+        .optional()
+        .describe("Resolution-9 short H3 cell integers (the bdc.db availability spine) to query directly. Provide exactly " +
+        "one of `geoids` or `h3_cells` — never both, never neither, never empty."),
+});
+const PlausibilityCheckPointInputSchema = z.object({
+    type: z.literal("Point").describe('GeoJSON geometry type — always "Point".'),
+    coordinates: z
+        .tuple([z.number(), z.number()])
+        .describe("[longitude, latitude] pair, GeoJSON coordinate order (longitude first)."),
+});
+const PlausibilityCheckInputSchema = z.object({
+    bdc_database_path: z
+        .string()
+        .optional()
+        .describe("Path to a bdc.db layer database (FCC Broadband Data Collection availability). Omit — or point at a file " +
+        "that doesn't exist — to abstain on filing evidence rather than error."),
+    poi_database_path: z
+        .string()
+        .optional()
+        .describe("Path to a poi.db layer database carrying the telecom-infrastructure categories (`telecom_exchange`, " +
+        "`tower_comms`, etc.). Omit — or point at a file that doesn't exist — to abstain on physical-plant " +
+        "evidence rather than error."),
+    address: z
+        .string()
+        .optional()
+        .describe("The claimed service location as a free-text postal address, geocoded via the server's runtime pipeline " +
+        "when `point` isn't also given. At least one of `address`, `point`, or `geoid` is required."),
+    point: PlausibilityCheckPointInputSchema.optional().describe("The claimed service location as a GeoJSON Point, bypassing geocoding. At least one of `address`, `point`, " +
+        "or `geoid` is required."),
+    geoid: z
+        .string()
+        .optional()
+        .describe("15-character census block GEOID for the claimed service location — the exact, native filing-evidence " +
+        "path (no h3-cell approximation). May be supplied alongside `point`/`address` (geoid drives filing " +
+        "evidence; the point drives physical-plant evidence independently). At least one of `address`, " +
+        "`point`, or `geoid` is required."),
+    technology_code: z
+        .number()
+        .describe("FCC BDC technology code for the claimed service, e.g. 50 = optical carrier fiber (BroadbandTechnologyCode)."),
+    claimed_download_mbps: z.number().describe("The claimed downstream speed in Mbps."),
+});
+const FilerLookupInputSchema = z.object({
+    database_path: z.string().min(1).describe("Path to a filer.db layer database (FCC filer identity crosswalk)."),
+    frn: z
+        .string()
+        .optional()
+        .describe("The zero-padded 10-digit FCC Registration Number to look up, e.g. '0001753557'. Provide exactly one of " +
+        "`frn`, `form499_id`, or `bdc_provider_id` — never more than one, never none."),
+    form499_id: z
+        .string()
+        .optional()
+        .describe("The FCC Form 499 filer ID to look up. Provide exactly one of `frn`, `form499_id`, or `bdc_provider_id` — " +
+        "never more than one, never none."),
+    bdc_provider_id: z
+        .number()
+        .optional()
+        .describe("The FCC BDC provider_id to look up. Provide exactly one of `frn`, `form499_id`, or `bdc_provider_id` — " +
+        "never more than one, never none."),
+    as_of: z
+        .string()
+        .optional()
+        .describe("ISO date (YYYY-MM-DD) to scope the lookup as-of — only relationships valid on or before this date, and not " +
+        "yet closed by it, are included. Defaults to today; the result always states the date actually used."),
+});
 /**
  * Build the tool table for a concrete `MCPToolDeps` implementation. Pure — no transport, no I/O of its own.
  */
@@ -112,6 +201,59 @@ export function buildToolTable(deps) {
                 return deps.layerManifest(databasePath);
             },
         },
+        {
+            name: "mailwoman_bdc_filing_landscape",
+            description: "Read the FCC Broadband Data Collection (BDC) provider/technology/speed-bucket filing census over a set " +
+                "of census blocks (`geoids`) or H3 cells (`h3_cells`) from a bdc.db layer database. Returns the source " +
+                "vintage, how many queried blocks were surveyed vs. unknown (never surveyed), and the filing summary. " +
+                "Provide exactly one of `geoids` or `h3_cells`.",
+            inputSchema: BDCFilingLandscapeInputSchema,
+            handler: async (args) => {
+                const { database_path, geoids, h3_cells } = BDCFilingLandscapeInputSchema.parse(args);
+                return deps.bdcFilingLandscape({ databasePath: database_path, geoids, h3Cells: h3_cells });
+            },
+        },
+        {
+            name: "mailwoman_plausibility_check",
+            description: "Score one claimed broadband-service assertion (technology + speed at a location) against the FCC BDC " +
+                "filing census and nearby telecom infrastructure, returning an evidence bundle: filings that corroborate " +
+                "(or don't), nearby physical plant, and a coverage_confidence reflecting survey completeness. NEVER " +
+                "returns a verdict stronger than 'no supporting evidence found' — absence of evidence degrades " +
+                "confidence, it never disproves the claim. Provide at least one of `address`, `point`, or `geoid`.",
+            inputSchema: PlausibilityCheckInputSchema,
+            handler: async (args) => {
+                const { bdc_database_path, poi_database_path, address, point, geoid, technology_code, claimed_download_mbps } = PlausibilityCheckInputSchema.parse(args);
+                return deps.plausibilityCheck({
+                    bdcDatabasePath: bdc_database_path,
+                    poiDatabasePath: poi_database_path,
+                    address,
+                    point,
+                    geoid,
+                    technologyCode: technology_code,
+                    claimedDownloadMbps: claimed_download_mbps,
+                });
+            },
+        },
+        {
+            name: "mailwoman_filer_lookup",
+            description: "Look up the FCC filer identity crosswalk for one identifier (FRN, Form 499 filer ID, or BDC provider_id) " +
+                "from a filer.db layer database: every OTHER identifier it shares an authoritative edge with (never " +
+                "collapsed — a provider_id carrying multiple FRNs reports all of them), its current attributes, its " +
+                "authoritative entity cluster, and any inferred links reported SEPARATELY with their score — never merged " +
+                "into the cluster. Scoped `as_of` a date (defaults to today, always present in the result). Provide " +
+                "exactly one of `frn`, `form499_id`, or `bdc_provider_id`.",
+            inputSchema: FilerLookupInputSchema,
+            handler: async (args) => {
+                const { database_path, frn, form499_id, bdc_provider_id, as_of } = FilerLookupInputSchema.parse(args);
+                return deps.filerLookup({
+                    databasePath: database_path,
+                    frn,
+                    form499ID: form499_id,
+                    bdcProviderID: bdc_provider_id,
+                    asOf: as_of,
+                });
+            },
+        },
     ];
 }
 //# sourceMappingURL=tools.js.map

package/out/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AA4CvB,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2EAA2E,CAAC;IAC7G,GAAG,EAAE,CAAC;SACJ,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACR,+HAA+H,CAC/H;CACF,CAAC,CAAA;AAEF,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CAC5E,CAAC,CAAA;AAEF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACR,wHAAwH,CACxH;IACF,eAAe,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kGAAkG,CAAC;CAC9G,CAAC,CAAA;AAEF,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,8FAA8F,CAAC;CAC1G,CAAC,CAAA;AAEF,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,YAAY,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,qFAAqF,CAAC;CACjG,CAAC,CAAA;AAEF,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,aAAa,EAAE,CAAC;SACd,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,+EAA+E,CAAC;IAC3F,MAAM,EAAE,CAAC;SACP,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACR,oIAAoI,CACpI;IACF,QAAQ,EAAE,CAAC;SACT,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACR,yGAAyG;QACxG,yEAAyE,CAC1E;CACF,CAAC,CAAA;AAEF,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IAC5E,WAAW,EAAE,CAAC;SACZ,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;SAC/B,QAAQ,CAAC,yEAAyE,CAAC;CACrF,CAAC,CAAA;AAEF,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,iBAAiB,EAAE,CAAC;SAClB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,0GAA0G;QACzG,uEAAuE,CACxE;IACF,iBAAiB,EAAE,CAAC;SAClB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,sGAAsG;QACrG,oGAAoG;QACpG,6BAA6B,CAC9B;IACF,OAAO,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,yGAAyG;QACxG,4FAA4F,CAC7F;IACF,KAAK,EAAE,iCAAiC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAC3D,4GAA4G;QAC3G,yBAAyB,CAC1B;IACD,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,uGAAuG;QACtG,oGAAoG;QACpG,gGAAgG;QAChG,kCAAkC,CACnC;IACF,eAAe,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,QAAQ,CACR,6GAA6G,CAC7G;IACF,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;CACnF,CAAC,CAAA;AAEF,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,mEAAmE,CAAC;IAC9G,GAAG,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,yGAAyG;QACxG,8EAA8E,CAC/E;IACF,UAAU,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,2GAA2G;QAC1G,kCAAkC,CACnC;IACF,eAAe,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,yGAAyG;QACxG,kCAAkC,CACnC;IACF,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,6GAA6G;QAC5G,qGAAqG,CACtG;CACF,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC/C,OAAO;QACN;YACC,IAAI,EAAE,iBAAiB;YACvB,WAAW,EACV,yGAAyG;gBACzG,wGAAwG;gBACxG,gGAAgG;YACjG,WAAW,EAAE,gBAAgB;YAC7B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAElD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;YACjC,CAAC;SACD;QACD;YACC,IAAI,EAAE,mBAAmB;YACzB,WAAW,EACV,uGAAuG;gBACvG,wGAAwG;gBACxG,4GAA4G;YAC7G,WAAW,EAAE,kBAAkB;YAC/B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,IAAI,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAE/C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YAC1B,CAAC;SACD;QACD;YACC,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACV,wGAAwG;gBACxG,wGAAwG;gBACxG,yFAAyF;YAC1F,WAAW,EAAE,oBAAoB;YACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAEnE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAA;YAClD,CAAC;SACD;QACD;YACC,IAAI,EAAE,2BAA2B;YACjC,WAAW,EACV,uGAAuG;gBACvG,iGAAiG;gBACjG,6CAA6C;YAC9C,WAAW,EAAE,yBAAyB;YACtC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,KAAK,EAAE,GAAG,yBAAyB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAEvD,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAA;YAClC,CAAC;SACD;QACD;YACC,IAAI,EAAE,0BAA0B;YAChC,WAAW,EACV,0GAA0G;gBAC1G,wGAAwG;gBACxG,kGAAkG;gBAClG,uCAAuC;YACxC,WAAW,EAAE,wBAAwB;YACrC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,YAAY,EAAE,GAAG,wBAAwB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAE7D,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAA;YACxC,CAAC;SACD;QACD;YACC,IAAI,EAAE,gCAAgC;YACtC,WAAW,EACV,yGAAyG;gBACzG,wGAAwG;gBACxG,uGAAuG;gBACvG,gDAAgD;YACjD,WAAW,EAAE,6BAA6B;YAC1C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,6BAA6B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAErF,OAAO,IAAI,CAAC,kBAAkB,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;YAC3F,CAAC;SACD;QACD;YACC,IAAI,EAAE,8BAA8B;YACpC,WAAW,EACV,uGAAuG;gBACvG,0GAA0G;gBAC1G,qGAAqG;gBACrG,gGAAgG;gBAChG,mGAAmG;YACpG,WAAW,EAAE,4BAA4B;YACzC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,GAC5G,4BAA4B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAEzC,OAAO,IAAI,CAAC,iBAAiB,CAAC;oBAC7B,eAAe,EAAE,iBAAiB;oBAClC,eAAe,EAAE,iBAAiB;oBAClC,OAAO;oBACP,KAAK;oBACL,KAAK;oBACL,cAAc,EAAE,eAAe;oBAC/B,mBAAmB,EAAE,qBAAqB;iBAC1C,CAAC,CAAA;YACH,CAAC;SACD;QACD;YACC,IAAI,EAAE,wBAAwB;YAC9B,WAAW,EACV,2GAA2G;gBAC3G,qGAAqG;gBACrG,qGAAqG;gBACrG,2GAA2G;gBAC3G,qGAAqG;gBACrG,2DAA2D;YAC5D,WAAW,EAAE,sBAAsB;YACnC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACvB,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,EAAE,GAAG,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAErG,OAAO,IAAI,CAAC,WAAW,CAAC;oBACvB,YAAY,EAAE,aAAa;oBAC3B,GAAG;oBACH,SAAS,EAAE,UAAU;oBACrB,aAAa,EAAE,eAAe;oBAC9B,IAAI,EAAE,KAAK;iBACX,CAAC,CAAA;YACH,CAAC;SACD;KACD,CAAA;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/mcp",
-  "version": "8.2.0",
+  "version": "8.4.0",
   "description": "MCP server — mailwoman's spatial toolset for agents (parse, geocode, poi_search, overpass_export, layer_manifest).",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -45,17 +45,19 @@
     }
   },
   "dependencies": {
-    "@mailwoman/core": "8.2.0",
-    "@mailwoman/neural": "8.2.0",
-    "@mailwoman/poi-taxonomy": "8.2.0",
-    "@mailwoman/resolver": "8.2.0",
-    "@mailwoman/resolver-wof-sqlite": "8.2.0",
+    "@mailwoman/bdc": "8.3.0",
+    "@mailwoman/core": "8.4.0",
+    "@mailwoman/filer": "8.3.0",
+    "@mailwoman/neural": "8.4.0",
+    "@mailwoman/poi-taxonomy": "8.4.0",
+    "@mailwoman/resolver": "8.4.0",
+    "@mailwoman/resolver-wof-sqlite": "8.4.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "mailwoman": "8.2.0",
+    "mailwoman": "8.4.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@mailwoman/resolver-wof-sqlite": "8.2.0"
+    "@mailwoman/resolver-wof-sqlite": "8.4.0"
   },
   "peerDependenciesMeta": {
     "@mailwoman/resolver-wof-sqlite": {

package/server.ts

@@ -24,9 +24,9 @@ const MCP_SERVER_VERSION = "7.1.0"
 /**
  * Build an `McpServer` with every `tools.ts` tool registered. A handler's returned value is JSON-stringified into a
  * single `text` content block — every tool here answers with structured data (parse trees, geocode results, search
- * hits), so a plain JSON text block is the simplest faithful rendering; none of the five tools need images, resource
- * links, or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level
- * failure, so a bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
+ * hits), so a plain JSON text block is the simplest faithful rendering; none of the tools need images, resource links,
+ * or other MCP content kinds. A thrown error becomes an `isError` tool result instead of a protocol-level failure, so a
+ * bad address / missing db surfaces to the agent as a normal (if unsuccessful) tool call.
  */
 export function createMCPServer(deps: MCPToolDeps): McpServer {
 	const server = new McpServer({ name: "mailwoman", version: MCP_SERVER_VERSION })

package/tools.ts

@@ -8,7 +8,9 @@
  *   file (the actual product surface) is testable without any MCP plumbing — `tools.test.ts` calls
  *   `buildToolTable` directly with stub deps.
  *
- *   Five tools, one per capability the exotic-POI arc's other packages expose to a human/CLI caller:
+ *   One tool per capability the exotic-POI/BDC arcs' other packages expose to a human/CLI caller — see
+ *   `buildToolTable`'s return value for the authoritative, current list (this comment intentionally states no count,
+ *   so it can't go stale as tools are added):
  *
  *   - `mailwoman_parse` — the runtime pipeline's parse (optionally POI-aware).
  *   - `mailwoman_geocode` — the street-level geocode cascade (`mailwoman/geocode-core`).
@@ -17,6 +19,16 @@
  *     we never run it".
  *   - `mailwoman_layer_manifest` — read a spatial-layer database's provenance manifest + coverage summary
  *     (`@mailwoman/core/layers`).
+ *   - `mailwoman_bdc_filing_landscape` — read a bdc.db layer's provider/technology/speed-bucket filing census over a
+ *     set of census blocks or H3 cells (`@mailwoman/bdc`'s `filingLandscape`).
+ *   - `mailwoman_plausibility_check` — score one claimed broadband-service assertion against BDC filing evidence and
+ *     nearby telecom infrastructure (`@mailwoman/bdc`'s `plausibilityCheck`), returning a positive-evidence-only bundle
+ *     with an always-present `coverage_confidence`. A missing/absent `bdc_database_path`/`poi_database_path` degrades
+ *     to a typed abstain entry in the bundle, never a throw (2b task 7, decision 6).
+ *   - `mailwoman_filer_lookup` (3a task 7) — read the FCC filer identity crosswalk (`@mailwoman/filer`'s
+ *     `filerLookup`) for one identifier (FRN, Form 499 ID, or BDC provider ID): every OTHER identifier it shares an
+ *     authoritative edge with, its current attributes, its authoritative entity cluster, and any inferred links —
+ *     reported separately, never merged into the cluster. `as_of` is always present (defaults to today).
  */
 
 import { z } from "zod"
@@ -30,6 +42,23 @@ export interface MCPToolDeps {
 	poiSearch: (q: { query: string; poiDatabasePath?: string }) => Promise<unknown>
 	overpassExport: (query: string) => Promise<string>
 	layerManifest: (databasePath: string) => Promise<unknown>
+	bdcFilingLandscape: (q: { databasePath: string; geoids?: string[]; h3Cells?: number[] }) => Promise<unknown>
+	plausibilityCheck: (q: {
+		bdcDatabasePath?: string
+		poiDatabasePath?: string
+		address?: string
+		point?: { type: "Point"; coordinates: [number, number] }
+		geoid?: string
+		technologyCode: number
+		claimedDownloadMbps: number
+	}) => Promise<unknown>
+	filerLookup: (q: {
+		databasePath: string
+		frn?: string
+		form499ID?: string
+		bdcProviderID?: number
+		asOf?: string
+	}) => Promise<unknown>
 }
 
 /**
@@ -87,6 +116,111 @@ const LayerManifestInputSchema = z.object({
 		.describe("Path to a mailwoman spatial-layer database (poi.db, an address-points shard, etc.)."),
 })
 
+const BDCFilingLandscapeInputSchema = z.object({
+	database_path: z
+		.string()
+		.min(1)
+		.describe("Path to a bdc.db layer database (FCC Broadband Data Collection availability)."),
+	geoids: z
+		.array(z.string())
+		.min(1)
+		.optional()
+		.describe(
+			"15-character census block GEOIDs to query. Provide exactly one of `geoids` or `h3_cells` — never both, never neither, never empty."
+		),
+	h3_cells: z
+		.array(z.number())
+		.min(1)
+		.optional()
+		.describe(
+			"Resolution-9 short H3 cell integers (the bdc.db availability spine) to query directly. Provide exactly " +
+				"one of `geoids` or `h3_cells` — never both, never neither, never empty."
+		),
+})
+
+const PlausibilityCheckPointInputSchema = z.object({
+	type: z.literal("Point").describe('GeoJSON geometry type — always "Point".'),
+	coordinates: z
+		.tuple([z.number(), z.number()])
+		.describe("[longitude, latitude] pair, GeoJSON coordinate order (longitude first)."),
+})
+
+const PlausibilityCheckInputSchema = z.object({
+	bdc_database_path: z
+		.string()
+		.optional()
+		.describe(
+			"Path to a bdc.db layer database (FCC Broadband Data Collection availability). Omit — or point at a file " +
+				"that doesn't exist — to abstain on filing evidence rather than error."
+		),
+	poi_database_path: z
+		.string()
+		.optional()
+		.describe(
+			"Path to a poi.db layer database carrying the telecom-infrastructure categories (`telecom_exchange`, " +
+				"`tower_comms`, etc.). Omit — or point at a file that doesn't exist — to abstain on physical-plant " +
+				"evidence rather than error."
+		),
+	address: z
+		.string()
+		.optional()
+		.describe(
+			"The claimed service location as a free-text postal address, geocoded via the server's runtime pipeline " +
+				"when `point` isn't also given. At least one of `address`, `point`, or `geoid` is required."
+		),
+	point: PlausibilityCheckPointInputSchema.optional().describe(
+		"The claimed service location as a GeoJSON Point, bypassing geocoding. At least one of `address`, `point`, " +
+			"or `geoid` is required."
+	),
+	geoid: z
+		.string()
+		.optional()
+		.describe(
+			"15-character census block GEOID for the claimed service location — the exact, native filing-evidence " +
+				"path (no h3-cell approximation). May be supplied alongside `point`/`address` (geoid drives filing " +
+				"evidence; the point drives physical-plant evidence independently). At least one of `address`, " +
+				"`point`, or `geoid` is required."
+		),
+	technology_code: z
+		.number()
+		.describe(
+			"FCC BDC technology code for the claimed service, e.g. 50 = optical carrier fiber (BroadbandTechnologyCode)."
+		),
+	claimed_download_mbps: z.number().describe("The claimed downstream speed in Mbps."),
+})
+
+const FilerLookupInputSchema = z.object({
+	database_path: z.string().min(1).describe("Path to a filer.db layer database (FCC filer identity crosswalk)."),
+	frn: z
+		.string()
+		.optional()
+		.describe(
+			"The zero-padded 10-digit FCC Registration Number to look up, e.g. '0001753557'. Provide exactly one of " +
+				"`frn`, `form499_id`, or `bdc_provider_id` — never more than one, never none."
+		),
+	form499_id: z
+		.string()
+		.optional()
+		.describe(
+			"The FCC Form 499 filer ID to look up. Provide exactly one of `frn`, `form499_id`, or `bdc_provider_id` — " +
+				"never more than one, never none."
+		),
+	bdc_provider_id: z
+		.number()
+		.optional()
+		.describe(
+			"The FCC BDC provider_id to look up. Provide exactly one of `frn`, `form499_id`, or `bdc_provider_id` — " +
+				"never more than one, never none."
+		),
+	as_of: z
+		.string()
+		.optional()
+		.describe(
+			"ISO date (YYYY-MM-DD) to scope the lookup as-of — only relationships valid on or before this date, and not " +
+				"yet closed by it, are included. Defaults to today; the result always states the date actually used."
+		),
+})
+
 /**
  * Build the tool table for a concrete `MCPToolDeps` implementation. Pure — no transport, no I/O of its own.
  */
@@ -158,5 +292,65 @@ export function buildToolTable(deps: MCPToolDeps): MCPToolDef[] {
 				return deps.layerManifest(databasePath)
 			},
 		},
+		{
+			name: "mailwoman_bdc_filing_landscape",
+			description:
+				"Read the FCC Broadband Data Collection (BDC) provider/technology/speed-bucket filing census over a set " +
+				"of census blocks (`geoids`) or H3 cells (`h3_cells`) from a bdc.db layer database. Returns the source " +
+				"vintage, how many queried blocks were surveyed vs. unknown (never surveyed), and the filing summary. " +
+				"Provide exactly one of `geoids` or `h3_cells`.",
+			inputSchema: BDCFilingLandscapeInputSchema,
+			handler: async (args) => {
+				const { database_path, geoids, h3_cells } = BDCFilingLandscapeInputSchema.parse(args)
+
+				return deps.bdcFilingLandscape({ databasePath: database_path, geoids, h3Cells: h3_cells })
+			},
+		},
+		{
+			name: "mailwoman_plausibility_check",
+			description:
+				"Score one claimed broadband-service assertion (technology + speed at a location) against the FCC BDC " +
+				"filing census and nearby telecom infrastructure, returning an evidence bundle: filings that corroborate " +
+				"(or don't), nearby physical plant, and a coverage_confidence reflecting survey completeness. NEVER " +
+				"returns a verdict stronger than 'no supporting evidence found' — absence of evidence degrades " +
+				"confidence, it never disproves the claim. Provide at least one of `address`, `point`, or `geoid`.",
+			inputSchema: PlausibilityCheckInputSchema,
+			handler: async (args) => {
+				const { bdc_database_path, poi_database_path, address, point, geoid, technology_code, claimed_download_mbps } =
+					PlausibilityCheckInputSchema.parse(args)
+
+				return deps.plausibilityCheck({
+					bdcDatabasePath: bdc_database_path,
+					poiDatabasePath: poi_database_path,
+					address,
+					point,
+					geoid,
+					technologyCode: technology_code,
+					claimedDownloadMbps: claimed_download_mbps,
+				})
+			},
+		},
+		{
+			name: "mailwoman_filer_lookup",
+			description:
+				"Look up the FCC filer identity crosswalk for one identifier (FRN, Form 499 filer ID, or BDC provider_id) " +
+				"from a filer.db layer database: every OTHER identifier it shares an authoritative edge with (never " +
+				"collapsed — a provider_id carrying multiple FRNs reports all of them), its current attributes, its " +
+				"authoritative entity cluster, and any inferred links reported SEPARATELY with their score — never merged " +
+				"into the cluster. Scoped `as_of` a date (defaults to today, always present in the result). Provide " +
+				"exactly one of `frn`, `form499_id`, or `bdc_provider_id`.",
+			inputSchema: FilerLookupInputSchema,
+			handler: async (args) => {
+				const { database_path, frn, form499_id, bdc_provider_id, as_of } = FilerLookupInputSchema.parse(args)
+
+				return deps.filerLookup({
+					databasePath: database_path,
+					frn,
+					form499ID: form499_id,
+					bdcProviderID: bdc_provider_id,
+					asOf: as_of,
+				})
+			},
+		},
 	]
 }