@mailwoman/mcp 8.3.0 → 8.5.0

package/cli.ts

@@ -6,14 +6,36 @@
  *
  *   `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.
+ *
+ *   `mailwoman_filer_family` (3b task 9) follows the IDENTICAL discipline, reusing the same two guards — `familyRollup`
+ *   has no optional-dep abstain shape either (it throws on a bad `familyID`/`nodeID` XOR or a pre-`filer_family`
+ *   schema), so filer.db is required unconditionally here too. Its result — always `FamilyRollup[]`, never `null` or
+ *   a bare object — is passed through untouched: this data is who-owns-whom, and a silent reshape here would be a
+ *   fabricated relationship claim.
+ *
  *   ```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 +46,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 { familyRollup, 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 +63,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 +148,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 +168,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 +218,80 @@ 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,
+		})
+	},
+
+	async filerFamily(q) {
+		// Same discipline as mailwoman_filer_lookup (3a task 7) — familyRollup has no optional-dep abstain shape
+		// either, so filer.db is required unconditionally.
+		assertFilerDatabaseExists("mailwoman_filer_family", q.databasePath)
+
+		using db = openFilerDatabaseIfPresent(q.databasePath)!
+
+		return familyRollup(db, {
+			familyID: q.familyID,
+			nodeID: q.nodeID,
+			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,36 @@
  *
  *   `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.
+ *
+ *   `mailwoman_filer_family` (3b task 9) follows the IDENTICAL discipline, reusing the same two guards — `familyRollup`
+ *   has no optional-dep abstain shape either (it throws on a bad `familyID`/`nodeID` XOR or a pre-`filer_family`
+ *   schema), so filer.db is required unconditionally here too. Its result — always `FamilyRollup[]`, never `null` or
+ *   a bare object — is passed through untouched: this data is who-owns-whom, and a silent reshape here would be a
+ *   fabricated relationship claim.
+ *
  *   ```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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG"}

package/out/cli.js

@@ -6,14 +6,36 @@
  *
  *   `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.
+ *
+ *   `mailwoman_filer_family` (3b task 9) follows the IDENTICAL discipline, reusing the same two guards — `familyRollup`
+ *   has no optional-dep abstain shape either (it throws on a bad `familyID`/`nodeID` XOR or a pre-`filer_family`
+ *   schema), so filer.db is required unconditionally here too. Its result — always `FamilyRollup[]`, never `null` or
+ *   a bare object — is passed through untouched: this data is who-owns-whom, and a silent reshape here would be a
+ *   fabricated relationship claim.
+ *
  *   ```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 +44,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 { familyRollup, filerLookup, toFRN } from "@mailwoman/filer/sdk";
 import { NeuralAddressClassifier } from "@mailwoman/neural";
 import { getPOICategory } from "@mailwoman/poi-taxonomy";
 import { createWOFResolver } from "@mailwoman/resolver";
@@ -31,6 +55,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 +116,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 +169,63 @@ 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,
+        });
+    },
+    async filerFamily(q) {
+        // Same discipline as mailwoman_filer_lookup (3a task 7) — familyRollup has no optional-dep abstain shape
+        // either, so filer.db is required unconditionally.
+        assertFilerDatabaseExists("mailwoman_filer_family", q.databasePath);
+        using db = openFilerDatabaseIfPresent(q.databasePath);
+        return familyRollup(db, {
+            familyID: q.familyID,
+            nodeID: q.nodeID,
+            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"}