@mailwoman/mcp 10.0.0 → 10.2.0

package/out/cli/main.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+import { filingLandscape, plausibilityCheck } from "@mailwoman/bdc";
+import { dataRootPath } from "@mailwoman/core/data-root";
+import { pathExists } from "@mailwoman/core/fs/readers/stat";
+import { readLayerManifest } from "@mailwoman/core/layers";
+import { parseArguments } from "@mailwoman/core/scripting/arguments";
+import { familyRollup } from "@mailwoman/filer/family-rollup";
+import { filerLookup } from "@mailwoman/filer/filer-lookup";
+import { toFRN } from "@mailwoman/filer/frn";
+import { NeuralAddressClassifier } from "@mailwoman/neural";
+import { getPOICategory } from "@mailwoman/poi-taxonomy";
+import { emitOverpassQL } from "@mailwoman/poi-taxonomy/overpass";
+import { createWOFResolver } from "@mailwoman/resolver";
+import { wofExtractPaths } from "@mailwoman/resolver-wof-sqlite/paths";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+import { createRuntimePipeline } from "mailwoman";
+import { geocodeAddress, USStateDatabaseProvider } from "mailwoman/geocode";
+import { buildNoGazetteerMessage, createResolverBackend, resolveCandidateDBPath } from "mailwoman/resolver-backend";
+import { assertBDCDatabaseExists, assertFilerDatabaseExists, openBDCDatabaseIfPresent, openFilerDatabaseIfPresent, openPlausibilityPOIDeps, } from "#layer-guards";
+import { createMCPServer } from "#server";
+const { values } = parseArguments({
+    options: {
+        "poi-db": { type: "string" },
+    },
+    allowPositionals: true,
+});
+const poiDatabasePath = values["poi-db"] ?? null;
+let corePromise;
+const CORE_BACKED_TOOLS = "mailwoman_parse, mailwoman_geocode, mailwoman_poi_search, mailwoman_overpass_export";
+const CORE_FREE_TOOLS = "mailwoman_layer_manifest, mailwoman_bdc_filing_landscape, mailwoman_filer_lookup, mailwoman_filer_family";
+function loadCore() {
+    corePromise ??= (async () => {
+        const resolverMod = await import("@mailwoman/resolver-wof-sqlite");
+        const wofPaths = [];
+        for (const extractPath of wofExtractPaths()) {
+            if (await pathExists(extractPath)) {
+                wofPaths.push(extractPath);
+            }
+        }
+        const candidateDB = await resolveCandidateDBPath();
+        if (!candidateDB && !wofPaths.length) {
+            throw new Error(`${buildNoGazetteerMessage({
+                dataRoot: dataRootPath(),
+                docsPath: "/docs/developers/how-to/use-the-mcp-server",
+            })}\n\n  Needs it: ${CORE_BACKED_TOOLS}\n  Works without it: ${CORE_FREE_TOOLS}`);
+        }
+        const backend = await createResolverBackend(resolverMod, { wofPaths, candidateDB });
+        const resolver = createWOFResolver(backend);
+        let classifier;
+        try {
+            classifier = await NeuralAddressClassifier.loadRoutedFromWeights({ locale: "en-US" });
+        }
+        catch (error) {
+            throw new Error(`✗ ${error instanceof Error ? error.message : String(error)}\n\n` +
+                `  Needs it: ${CORE_BACKED_TOOLS}\n  Works without it: ${CORE_FREE_TOOLS}`);
+        }
+        const databases = await USStateDatabaseProvider.create(resolverMod, dataRootPath());
+        return { classifier, resolver, databases };
+    })();
+    return corePromise;
+}
+let plainPipeline = null;
+const poiPipelines = new Map();
+async function getPlainPipeline() {
+    if (!plainPipeline) {
+        const { classifier, resolver } = await loadCore();
+        plainPipeline = createRuntimePipeline({ classifier, resolver });
+    }
+    return plainPipeline;
+}
+async function getPoiPipeline(dbPath) {
+    const key = dbPath ?? "";
+    const cached = poiPipelines.get(key);
+    if (cached)
+        return cached;
+    const { classifier, resolver } = await loadCore();
+    const pipeline = createRuntimePipeline({
+        classifier,
+        resolver,
+        poiQueryKind: dbPath ? { poiDatabasePath: dbPath } : "extract",
+    });
+    poiPipelines.set(key, pipeline);
+    return pipeline;
+}
+async function resolveGeocode(address) {
+    const { classifier, resolver, databases } = await loadCore();
+    return geocodeAddress(address, { classifier, resolver, databases: databases.for });
+}
+const deps = {
+    async parse(text, opts) {
+        const pipeline = opts?.poi ? await getPoiPipeline(poiDatabasePath) : await getPlainPipeline();
+        return pipeline(text);
+    },
+    async geocode(text) {
+        return resolveGeocode(text);
+    },
+    async poiSearch(q) {
+        const pipeline = await getPoiPipeline(q.poiDatabasePath ?? poiDatabasePath);
+        const result = await pipeline(q.query);
+        return result.poiIntent ?? { type: "abstain", reason: "not_poi_shaped" };
+    },
+    async overpassExport(query) {
+        const pipeline = await getPoiPipeline(poiDatabasePath);
+        const result = await pipeline(query);
+        const poiIntent = result.poiIntent;
+        if (!poiIntent || poiIntent.type !== "intent") {
+            const reason = poiIntent?.type === "abstain" ? `: ${poiIntent.reason}` : "";
+            throw new Error(`mailwoman_overpass_export: query is not POI-shaped (${poiIntent?.type ?? "no poi intent"}${reason})`);
+        }
+        const { subject } = poiIntent.intent;
+        const osmTags = subject.kind === "category"
+            ? subject.categoryIDs.map((id) => getPOICategory(id)?.osmTag).filter((tag) => tag !== undefined)
+            : [];
+        return emitOverpassQL(poiIntent.intent, subject.kind === "category" && osmTags.length === subject.categoryIDs.length ? { osmTags } : {});
+    },
+    async layerManifest(databasePath) {
+        using db = new DatabaseClient(databasePath, { readOnly: true });
+        const manifest = await readLayerManifest(db);
+        const coverage = await db
+            .selectFrom("layer_coverage")
+            .select((eb) => [
+            eb.fn.count("h3_cell").as("surveyedCellCount"),
+            eb.fn.avg("completeness").as("averageCompleteness"),
+            eb.fn.sum("observed_rows").as("totalObservedRows"),
+        ])
+            .executeTakeFirst();
+        return { manifest, coverage };
+    },
+    async bdcFilingLandscape(q) {
+        await assertBDCDatabaseExists("mailwoman_bdc_filing_landscape", q.databasePath);
+        using db = new DatabaseClient(q.databasePath, { readOnly: true });
+        return await filingLandscape(db, { geoids: q.geoids, h3Cells: q.h3Cells });
+    },
+    async plausibilityCheck(q) {
+        const bdcDB = await 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?.schemadb.destroy();
+        }
+    },
+    async filerLookup(q) {
+        await assertFilerDatabaseExists("mailwoman_filer_lookup", q.databasePath);
+        using db = (await openFilerDatabaseIfPresent(q.databasePath));
+        let frn = null;
+        if (q.frn) {
+            const parsed = toFRN(q.frn);
+            if (!parsed) {
+                throw new Error(`mailwoman_filer_lookup: "${q.frn}" is not a valid FRN`);
+            }
+            frn = parsed;
+        }
+        return await filerLookup(db, {
+            frn,
+            form499ID: q.form499ID,
+            bdcProviderID: q.bdcProviderID,
+            asOf: q.asOf,
+        });
+    },
+    async filerFamily(q) {
+        await assertFilerDatabaseExists("mailwoman_filer_family", q.databasePath);
+        using db = (await openFilerDatabaseIfPresent(q.databasePath));
+        return await familyRollup(db, {
+            familyID: q.familyID,
+            nodeID: q.nodeID,
+            asOf: q.asOf,
+        });
+    },
+};
+const server = createMCPServer(deps);
+const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=main.js.map

package/out/cli/main.js.map

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

package/out/layer-guards.d.ts

@@ -6,18 +6,18 @@
  *   Decision 6 layer-absent guards — kept out of `cli.ts` in their own importable module 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
+ *   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
+ *     (`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` — the SAME pairing, for filer.db.
+ *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` — 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 criterion
  *     4 makes it throw rather than answer unstamped), so `cli.ts` pairs `assertFilerDatabaseExists` (the friendly
@@ -26,39 +26,54 @@
 import type { BDCDatabase, PlausibilityDeps } from "@mailwoman/bdc";
 import type { FilerDatabase } from "@mailwoman/filer";
 import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { PathBuilderLike } from "path-ts";
 /**
- * Open a bdc.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw.
+ * 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): Promise<DatabaseClient<BDCDatabase> | undefined>;
+export declare function openBDCDatabaseIfPresent(databasePath: PathBuilderLike | undefined): Promise<DatabaseClient<BDCDatabase> | null>;
 /**
- * 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
+ * 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 `schemadb` 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 `schemadb` (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"]>;
+export declare function openPlausibilityPOIDeps(databasePath: PathBuilderLike | 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`).
+ * 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): Promise<void>;
+export declare function assertBDCDatabaseExists(toolName: string, databasePath: PathBuilderLike): Promise<void>;
 /**
- * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw
- * (mirroring {@link openBDCDatabaseIfPresent}). Used by `cli.ts`'s `mailwoman_filer_lookup` handler after
- * {@link assertFilerDatabaseExists} has already confirmed the file is present.
+ * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing,
+ * never a raw sqlite throw (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): Promise<DatabaseClient<FilerDatabase> | undefined>;
+export declare function openFilerDatabaseIfPresent(databasePath: PathBuilderLike | undefined): Promise<DatabaseClient<FilerDatabase> | null>;
 /**
- * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_filer_lookup`'s guard
- * (mirroring {@link assertBDCDatabaseExists}). `filerLookup` itself has no optional-dep abstain shape (criterion 4
- * makes it throw rather than answer unstamped), so filer.db is required unconditionally, same as bdc.db is for
- * `mailwoman_bdc_filing_landscape`.
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist —
+ * `mailwoman_filer_lookup`'s guard (mirroring {@link assertBDCDatabaseExists}).
+ *
+ * `filerLookup` itself has no optional-dep abstain shape
+ * (criterion 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): Promise<void>;
+export declare function assertFilerDatabaseExists(toolName: string, databasePath: PathBuilderLike): Promise<void>;
 //# sourceMappingURL=layer-guards.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"layer-guards.d.ts","sourceRoot":"","sources":["../lib/layer-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD;;;GAGG;AACH,wBAAsB,wBAAwB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,CAIlD;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAUhH;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAInG;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC/C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC,CAIpD;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrG"}
+{"version":3,"file":"layer-guards.d.ts","sourceRoot":"","sources":["../lib/layer-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC7C,YAAY,EAAE,eAAe,GAAG,SAAS,GACvC,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,CAI7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC5C,YAAY,EAAE,eAAe,GAAG,SAAS,GACvC,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAUlC;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5G;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC/C,YAAY,EAAE,eAAe,GAAG,SAAS,GACvC,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,CAI/C;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9G"}

package/out/layer-guards.js

@@ -6,42 +6,50 @@
  *   Decision 6 layer-absent guards — kept out of `cli.ts` in their own importable module 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
+ *   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
+ *     (`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` — the SAME pairing, for filer.db.
+ *   - `openFilerDatabaseIfPresent` / `assertFilerDatabaseExists` — 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 criterion
  *     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 { pathExists } from "@mailwoman/core/fs/readers";
+import { pathExists } from "@mailwoman/core/fs/readers/stat";
 import { DatabaseClient } from "@mailwoman/sqlite/client";
 /**
- * Open a bdc.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw.
+ * 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 async function openBDCDatabaseIfPresent(databasePath) {
     if (!databasePath || !(await pathExists(databasePath)))
-        return undefined;
+        return null;
     return new DatabaseClient(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
+ * 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 `schemadb` 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 `schemadb` (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) {
@@ -51,13 +59,15 @@ export async function openPlausibilityPOIDeps(databasePath) {
     const database = new DatabaseClient(databasePath, { readOnly: true });
     return {
         lookup: new POILookup({ database }),
-        contractDB: database,
+        schemadb: 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`).
+ * 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 async function assertBDCDatabaseExists(toolName, databasePath) {
     if (!(await pathExists(databasePath))) {
@@ -65,20 +75,24 @@ export async function assertBDCDatabaseExists(toolName, databasePath) {
     }
 }
 /**
- * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing — NEVER a raw sqlite throw
- * (mirroring {@link openBDCDatabaseIfPresent}). Used by `cli.ts`'s `mailwoman_filer_lookup` handler after
- * {@link assertFilerDatabaseExists} has already confirmed the file is present.
+ * Open a filer.db, or return `undefined` when `databasePath` is unset or the file is missing,
+ * never a raw sqlite throw (mirroring {@link openBDCDatabaseIfPresent}).
+ *
+ * Used by `cli.ts`'s `mailwoman_filer_lookup` handler after {@link assertFilerDatabaseExists}
+ * has already confirmed the file is present.
  */
 export async function openFilerDatabaseIfPresent(databasePath) {
     if (!databasePath || !(await pathExists(databasePath)))
-        return undefined;
+        return null;
     return new DatabaseClient(databasePath, { readOnly: true });
 }
 /**
- * Throws a friendly Error naming the layer when `databasePath` doesn't exist — `mailwoman_filer_lookup`'s guard
- * (mirroring {@link assertBDCDatabaseExists}). `filerLookup` itself has no optional-dep abstain shape (criterion 4
- * makes it throw rather than answer unstamped), so filer.db is required unconditionally, same as bdc.db is for
- * `mailwoman_bdc_filing_landscape`.
+ * Throws a friendly Error naming the layer when `databasePath` doesn't exist —
+ * `mailwoman_filer_lookup`'s guard (mirroring {@link assertBDCDatabaseExists}).
+ *
+ * `filerLookup` itself has no optional-dep abstain shape
+ * (criterion 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 async function assertFilerDatabaseExists(toolName, databasePath) {
     if (!(await pathExists(databasePath))) {

package/out/layer-guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"layer-guards.js","sourceRoot":"","sources":["../lib/layer-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGvD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC7C,YAAgC;IAEhC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IAExE,OAAO,IAAI,cAAc,CAAc,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,YAAgC;IAC7E,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IAExE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,oCAAoC,CAAC,CAAA;IACxE,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAc,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAElF,OAAO;QACN,MAAM,EAAE,IAAI,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QACnC,UAAU,EAAE,QAAQ;KACpB,CAAA;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,QAAgB,EAAE,YAAoB;IACnF,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,0BAA0B,YAAY,GAAG,CAAC,CAAA;IACtE,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,YAAgC;IAEhC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IAExE,OAAO,IAAI,cAAc,CAAgB,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,QAAgB,EAAE,YAAoB;IACrF,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,4BAA4B,YAAY,GAAG,CAAC,CAAA;IACxE,CAAC;AACF,CAAC"}
+{"version":3,"file":"layer-guards.js","sourceRoot":"","sources":["../lib/layer-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAGzD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC7C,YAAyC;IAEzC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAEnE,OAAO,IAAI,cAAc,CAAc,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC5C,YAAyC;IAEzC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IAExE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,oCAAoC,CAAC,CAAA;IACxE,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAc,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IAElF,OAAO;QACN,MAAM,EAAE,IAAI,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QACnC,QAAQ,EAAE,QAAQ;KAClB,CAAA;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,QAAgB,EAAE,YAA6B;IAC5F,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,0BAA0B,YAAY,GAAG,CAAC,CAAA;IACtE,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,YAAyC;IAEzC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAEnE,OAAO,IAAI,cAAc,CAAgB,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,QAAgB,EAAE,YAA6B;IAC9F,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,4BAA4B,YAAY,GAAG,CAAC,CAAA;IACxE,CAAC;AACF,CAAC"}

package/out/server.d.ts

@@ -4,17 +4,21 @@
  * @author Teffen Ellis, et al.
  *
  *   MCP server wiring — thin glue that registers `tools.ts`'s tool table on an `McpServer`. The tool table is the
- *   stable, tested contract (`tools.test.ts`); this module only adapts it to the SDK's `registerTool` signature and
+ *   stable, tested interface (`tools.test.ts`); this module only adapts it to the SDK's `registerTool` signature and
  *   `CallToolResult` envelope. `cli.ts` owns building the real `MCPToolDeps` and connecting a transport.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type MCPToolDeps } from "#tools";
 /**
- * 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 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.
+ * 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 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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../lib/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAA;AAUzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,CAsB5D"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../lib/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAA;AAgBzD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,CAsB5D"}

package/out/server.js

@@ -4,24 +4,35 @@
  * @author Teffen Ellis, et al.
  *
  *   MCP server wiring — thin glue that registers `tools.ts`'s tool table on an `McpServer`. The tool table is the
- *   stable, tested contract (`tools.test.ts`); this module only adapts it to the SDK's `registerTool` signature and
+ *   stable, tested interface (`tools.test.ts`); this module only adapts it to the SDK's `registerTool` signature and
  *   `CallToolResult` envelope. `cli.ts` owns building the real `MCPToolDeps` and connecting a transport.
  */
+import { prettyJSON } from "@mailwoman/core/json";
+import { readPackageJSON } from "@mailwoman/core/module/resolve-from";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { buildToolTable } from "#tools";
 /**
- * The advertised server version — keep in lockstep with `package.json`'s `version` (not read from it dynamically: a
- * static string avoids `resolveJsonModule`/`composite` friction for one cosmetic field, the same tradeoff
- * `nominatim`/`photon`'s OpenAPI `info.version` DON'T make since theirs is a documented public contract; an MCP client
- * only ever logs this).
+ * The advertised server version, read from this package's own manifest at load.
+ *
+ * A JSON import would make `tsc` copy the file into `out/`, where it becomes the package
+ * scope for the compiled tree, so the manifest is read through the module resolver instead.
  */
-const MCP_SERVER_VERSION = "7.1.0";
+const MCP_SERVER_VERSION = await readPackageJSON(import.meta.url, "@mailwoman/mcp").then((manifest) => {
+    if (!manifest.version) {
+        throw new Error("@mailwoman/mcp: package.json carries no version to advertise");
+    }
+    return manifest.version;
+});
 /**
- * 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 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.
+ * 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 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 });
@@ -29,7 +40,7 @@ export function createMCPServer(deps) {
         server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema.shape }, async (args) => {
             try {
                 const result = await tool.handler(args);
-                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                return { content: [{ type: "text", text: prettyJSON(result) }] };
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);

package/out/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../lib/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAoB,MAAM,QAAQ,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,OAAO,CAAA;AAElC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB;IAChD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC,CAAA;IAEhF,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,YAAY,CAClB,IAAI,CAAC,IAAI,EACT,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,EACtE,KAAK,EAAE,IAAI,EAA2B,EAAE;YACvC,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAEvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;YAC9E,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBAEtE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;YACrE,CAAC;QACF,CAAC,CACD,CAAA;IACF,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../lib/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGnE,OAAO,EAAE,cAAc,EAAoB,MAAM,QAAQ,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,MAAM,eAAe,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;IACrG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAA;IAChF,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAA;AACxB,CAAC,CAAC,CAAA;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB;IAChD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC,CAAA;IAEhF,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,YAAY,CAClB,IAAI,CAAC,IAAI,EACT,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,EACtE,KAAK,EAAE,IAAI,EAA2B,EAAE;YACvC,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBAEvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAA;YACjE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBAEtE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;YACrE,CAAC;QACF,CAAC,CACD,CAAA;IACF,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC"}

package/out/tools.d.ts

@@ -2,42 +2,11 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The MCP tool table — pure, transport-free. `server.ts` adapts this to the `@modelcontextprotocol/sdk`'s
- *   registration API; `cli.ts` builds the real `MCPToolDeps` from the mailwoman library. Kept separate so this
- *   file (the actual product surface) is testable without any MCP plumbing — `tools.test.ts` calls
- *   `buildToolTable` directly with stub deps.
- *
- *   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`).
- *   - `mailwoman_poi_search` — POI-intent extraction + (when a poi.db is wired) execution.
- *   - `mailwoman_overpass_export` — OverpassQL EXPORT emitter (`mailwoman/poi-overpass`) — "we print the query;
- *     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 (decision 6).
- *   - `mailwoman_filer_lookup` — 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).
- *   - `mailwoman_filer_family` — read a corporate family's membership (`@mailwoman/filer/sdk`'s
- *     `familyRollup`) from a filer.db layer database, given a `family_id` or a `node_id`. Distinct from an entity
- *     cluster (same filer, different identifiers) — a corporate family spans several DIFFERENT filers under a
- *     holding/parent/subsidiary/management relationship. The handler passes `familyRollup`'s result through
- *     unchanged: no reshaping, filtering, or summarizing of who-owns-whom data.
  */
 import { z } from "zod";
 /**
- * The library surface every tool handler dispatches to. `cli.ts` builds the real implementation.
+ * Defines the library operations that MCP tool handlers call.
+ * `cli.ts` implements those operations.
  */
 export interface MCPToolDeps {
     parse: (text: string, opts?: {
@@ -82,20 +51,21 @@ export interface MCPToolDeps {
     }) => Promise<unknown>;
 }
 /**
- * One MCP tool. `inputSchema` is a plain Zod object (not `any` — this repo's oxlint config errors on
- * `typescript/no-explicit-any`) — `z.ZodRawShape` is zod's own umbrella type for "any object shape", so this stays
- * generic over the concrete per-tool schemas without reaching for `any`. `handler` re-parses `args` through the same
- * schema (cheap; zod objects are small here) rather than trusting an unchecked cast, so the array of heterogeneous
- * tools stays type-safe internally despite the necessarily-uniform external shape.
+ * Describes one MCP tool as registered with the server.
+ *
+ * Each `handler` re-parses `args` through its own `inputSchema` instead of trusting a cast,
+ * because the table's uniform signature erases the per-tool types.
  */
-export interface MCPToolDef {
+interface MCPToolDef {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
     handler: (args: Record<string, unknown>) => Promise<unknown>;
 }
 /**
- * Build the tool table for a concrete `MCPToolDeps` implementation. Pure — no transport, no I/O of its own.
+ * Builds the MCP tool table over the given dependencies, without opening a transport
+ * or performing I/O itself.
  */
 export declare function buildToolTable(deps: MCPToolDeps): MCPToolDef[];
+export {};
 //# sourceMappingURL=tools.d.ts.map