@cliwant/mcp-sam-gov 0.2.1 → 1.0.0

package/dist/disclosure.js

@@ -0,0 +1,57 @@
+/**
+ * disclosure.ts — the single audited disclosure-note TOKENIZER shared across the
+ * keyless DataSources (ADR-0022: an honesty-layer primitive, split into its own
+ * tiny single-concern module — the sibling of coerce.ts's map-layer primitives).
+ *
+ * WHY IT EXISTS: two independent sources (NSF Awards C108 = the OR-note,
+ * ClinicalTrials.gov C109 = the AND-note) each built a mandatory multi-token
+ * disclosure note from the SAME character-for-character delimiter class, and
+ * adversarial verification caught the SAME latent gap on BOTH — a whitespace-only
+ * `.split(/\s+/)` misses the API's PUNCTUATION delimiters, so a compound that only
+ * LOOKS like one token ("coral-reef" = coral OR reef; "Sanofi-Aventis" = Sanofi
+ * AND Aventis) leaks through and the mandatory note is silently SKIPPED. Hoisting
+ * ONE audited tokenizer removes the drift risk (a class regression now fails NSF
+ * AND ClinicalTrials suites at once instead of silently in one) and gives the lint
+ * guardrail (lint-invariants.mjs) + the parity fault test a single home to point
+ * at: "the ONLY sanctioned way to tokenize a disclosure value lives here."
+ *
+ * THE CLASS (`DISCLOSURE_SPLIT_RE`) is the PRECISE ES/Essie confirmed-splitter set,
+ * live-verified byte-identically on BOTH sources 2026-07-12:
+ *   - SPLIT (→ multi-token, the note fires): whitespace + `- , / ; + & | @ # =`
+ *   - DO NOT split (→ one token, no note):   `. : _ '`  (NSF also `\` `*`)
+ * It is deliberately NOT a `[^A-Za-z0-9]+` superset — that would over-disclose a
+ * split the APIs did NOT make on `.`/`_`/`'` (a fabricated union/conjunction). `-`
+ * is placed LAST (a literal, not a range); `/` is escaped for the regex delimiter.
+ *
+ * NOTE-AGNOSTIC BY DESIGN: this returns ONLY the token array. The `.length > 1`
+ * decision, the per-source note WORDING (NSF = OR-union, ClinicalTrials = AND
+ * co-occurrence), and any downstream suppression (ClinicalTrials' sponsor
+ * broadening-note) stay in each CALLER — they are genuinely source-specific and do
+ * NOT belong to the tokenizer.
+ *
+ * THE OPTIONAL `splitRe` PARAM is the sanctioned, honest escape hatch: a FUTURE
+ * source whose analyzer genuinely splits on a DIFFERENT class routes through THIS
+ * helper with its own `splitRe` (explicit, greppable, reviewable) rather than
+ * re-inlining a raw `.split(/\s+/)`. That is exactly what lets the lint ban the
+ * bare whitespace split outright (there is one sanctioned tokenizer, not many).
+ *
+ * No new dep, no I/O, pure function — the exact shape of a coerce.ts primitive.
+ */
+/**
+ * The shared ES/Essie confirmed-splitter class (byte-identical to NSF's former
+ * `NSF_KEYWORD_SPLIT_RE` and ClinicalTrials' former `CT_TOKEN_SPLIT_RE`). Stateless
+ * (no `/g`), so a single module-level RegExp is safe to share across callers.
+ */
+export const DISCLOSURE_SPLIT_RE = /[\s,;+&|@#=\/-]+/;
+/**
+ * Tokenize a disclosure value for a multi-token honesty note: trim, split on the
+ * confirmed-splitter class (default `DISCLOSURE_SPLIT_RE`), and drop empty tokens.
+ * Returns ONLY the token array — the caller owns the `.length > 1` gate + note
+ * wording. `tokenizeForDisclosure("coral-reef")` → `["coral", "reef"]`;
+ * `tokenizeForDisclosure("web_service")` → `["web_service"]` (the class does NOT
+ * split `_`); `tokenizeForDisclosure("robotics")` → `["robotics"]`.
+ */
+export function tokenizeForDisclosure(value, splitRe = DISCLOSURE_SPLIT_RE) {
+    return value.trim().split(splitRe).filter((t) => t.length > 0);
+}
+//# sourceMappingURL=disclosure.js.map

package/dist/disclosure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disclosure.js","sourceRoot":"","sources":["../src/disclosure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,UAAkB,mBAAmB;IAErC,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjE,CAAC"}

package/dist/ecfr.d.ts

@@ -25,8 +25,9 @@ export declare function listTitles(): Promise<{
 export declare function search(args: {
     query: string;
     titleNumber?: number;
+    chapter?: number;
     perPage?: number;
-}): Promise<{
+}): Promise<import("./meta.js").MetaBundle<{
     results: {
         type: string;
         title: string;
@@ -39,6 +40,7 @@ export declare function search(args: {
         score: number;
         ecfrUrl: string;
         effectiveOn: string;
+        endsOn: string | null;
     }[];
-}>;
+}>>;
 //# sourceMappingURL=ecfr.d.ts.map

package/dist/ecfr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ecfr.d.ts","sourceRoot":"","sources":["../src/ecfr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAeH,wBAAsB,UAAU;;;;;;;;;GAsB/B;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;;;;;;;;;;;;GAkDA"}
+{"version":3,"file":"ecfr.d.ts","sourceRoot":"","sources":["../src/ecfr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2BH,wBAAsB,UAAU;;;;;;;;;GAyB/B;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;;;;;;;;;;;;;IA0IA"}

package/dist/ecfr.js

@@ -12,29 +12,38 @@
  *
  * Both keyless. Documented at https://www.ecfr.gov/developers/.
  */
+import { fetchWithRetry } from "./errors.js";
+import { driftError } from "./datasource.js";
+import { memoize } from "./cache.js";
+import { withMeta } from "./meta.js";
 const ECFR = "https://www.ecfr.gov/api";
+// eCFR's /search/v1/results `meta.total_count` is capped by Elasticsearch's
+// `index.max_result_window` (live-verified 10,000). A total AT OR ABOVE this
+// sentinel is a LOWER BOUND, not an exact count — see the totalIsLowerBound
+// wiring in `search` (D1). A genuine count below this stays exact.
+const ECFR_TOTAL_COUNT_CAP = 10000;
 async function fetchJson(url) {
-    const r = await fetch(url, {
+    const r = await fetchWithRetry(url, {
         headers: { Accept: "application/json" },
         signal: AbortSignal.timeout(15_000),
-    });
-    if (!r.ok) {
-        throw new Error(`eCFR ${url} returned ${r.status}`);
-    }
+    }, `ecfr:${url.split("/api/")[1] ?? url}`);
     return (await r.json());
 }
 export async function listTitles() {
-    const json = await fetchJson(`${ECFR}/versioner/v1/titles.json`);
-    return {
-        titles: (json.titles ?? []).map((t) => ({
-            number: t.number ?? 0,
-            name: t.name ?? "",
-            latestAmendedOn: t.latest_amended_on,
-            latestIssueDate: t.latest_issue_date,
-            upToDateAsOf: t.up_to_date_as_of,
-            reserved: !!t.reserved,
-        })),
-    };
+    // 50 CFR titles change very infrequently. Cache aggressively (5 min).
+    return memoize("ecfr:titles", async () => {
+        const json = await fetchJson(`${ECFR}/versioner/v1/titles.json`);
+        return {
+            titles: (json.titles ?? []).map((t) => ({
+                number: t.number ?? 0,
+                name: t.name ?? "",
+                latestAmendedOn: t.latest_amended_on,
+                latestIssueDate: t.latest_issue_date,
+                upToDateAsOf: t.up_to_date_as_of,
+                reserved: !!t.reserved,
+            })),
+        };
+    });
 }
 export async function search(args) {
     const url = new URL(`${ECFR}/search/v1/results`);
@@ -45,8 +54,28 @@ export async function search(args) {
         // an "unpermitted parameter" error from the eCFR API).
         url.searchParams.set("hierarchy[title]", String(args.titleNumber));
     }
+    // Optional chapter filter (additive; existing ecfr_search callers pass none).
+    // Within Title 48: chapter 1 = FAR, chapter 2 = DFARS, chapter 5 = GSAM, etc.
+    // This is what lets far_search scope to FAR/DFARS and keep GSAM/agency
+    // supplements out server-side. Same hierarchy[…] contract as the title filter.
+    if (args.chapter !== undefined) {
+        url.searchParams.set("hierarchy[chapter]", String(args.chapter));
+    }
     const json = await fetchJson(url.toString());
-    return {
+    // F6 (P2 empty-vs-outage): a 200 whose `results` is PRESENT-but-non-array — or
+    // a body carrying NEITHER a `results` array NOR a `meta` object — is drift / an
+    // unexpected shape, NOT a genuine no-match. Throw (schema_drift) rather than
+    // letting `(json.results ?? []).map` coalesce it into a fake AUTHORITATIVE empty.
+    // A GENUINE empty (results:[] with meta.total_count:0) flows through honestly
+    // below. (eCFR normally signals errors via HTTP status caught by fetchWithRetry;
+    // this closes the previously-unhandled + untested 200-body drift path.)
+    if (json.results !== undefined && !Array.isArray(json.results)) {
+        throw driftError("ecfr.gov", "eCFR search returned HTTP 200 but `results` is not an array — treating it as schema drift, NOT an empty result set.");
+    }
+    if (json.results === undefined && json.meta === undefined) {
+        throw driftError("ecfr.gov", "eCFR search returned HTTP 200 with neither a `results` array nor a `meta` object — an unexpected shape; treating it as schema drift, NOT an empty result set.");
+    }
+    const data = {
         results: (json.results ?? []).map((r) => ({
             type: r.type ?? "",
             title: r.hierarchy?.title ?? "",
@@ -64,8 +93,54 @@ export async function search(args) {
                 ? buildEcfrUrl(r.hierarchy)
                 : "",
             effectiveOn: r.starts_on ?? "",
+            // Additive: the version's end date. null = the CURRENT (in-force) version;
+            // a non-null date = a HISTORICAL version. eCFR search returns ~5 versions
+            // per section; existing ecfr_search callers simply ignore this extra field,
+            // while far_search uses it to collapse historical dups to the current one.
+            endsOn: r.ends_on ?? null,
         })),
     };
+    // Truthful `_meta` (spec §1.2 A6, §2.3). eCFR returns a hit count in
+    // `meta.total_count`, BUT that count is capped by Elasticsearch's
+    // `index.max_result_window` at 10,000 (a real ceiling — unlike a genuine
+    // small count, a value at/above the cap is a LOWER BOUND, not an exact
+    // total). Below the cap `totalAvailable` is exact (the AI can tell a top-N
+    // slice from the full match set); at/above the cap we flag
+    // `totalIsLowerBound:true` + a note so a broad query that truly matches
+    // >10,000 sections is NOT reported as if exactly 10,000 (D1). A6: echo the
+    // applied title scope so the AI can VERIFY it searched the intended corpus —
+    // Title 48 (FAR) vs every CFR title — rather than silently trusting a filter
+    // that could return cross-title results if the eCFR param contract ever changes.
+    const returned = data.results.length;
+    const totalAvailable = typeof json.meta?.total_count === "number" ? json.meta.total_count : null;
+    // eCFR's search total_count saturates at the Elasticsearch max_result_window
+    // (live-verified 10,000). Use `>= cap` (not `=== cap`) so a total AT OR ABOVE
+    // the ceiling is treated as a lower bound — strictly safe if the window were
+    // ever configured higher. Mirrors federal-register.ts's FR_COUNT_CAP and
+    // edgar.ts's FTS_WINDOW.
+    const totalIsLowerBound = totalAvailable !== null && totalAvailable >= ECFR_TOTAL_COUNT_CAP;
+    const scopeNote = args.titleNumber !== undefined
+        ? `searched CFR Title ${args.titleNumber}${args.titleNumber === 48 ? " (FAR — Federal Acquisition Regulation)" : ""} only`
+        : "searched all CFR titles (no title filter applied)";
+    const notes = [scopeNote];
+    if (totalIsLowerBound) {
+        notes.push(`eCFR caps total_count at ${ECFR_TOTAL_COUNT_CAP} (Elasticsearch index.max_result_window); totalAvailable is a LOWER BOUND — the true match count may be higher and is UNKNOWN. See totalIsLowerBound. Narrow by title/chapter/date for an exact count.`);
+    }
+    return withMeta(data, {
+        source: "ecfr.gov/api (search/v1)",
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        // Explicit boolean (not conditional): a below-cap count is DEFINITIVELY
+        // exact (totalIsLowerBound:false), an at/above-cap count is a lower bound
+        // (true). The AI can trust `false` as "this is the real total".
+        totalIsLowerBound,
+        truncated: totalAvailable !== null ? returned < totalAvailable : undefined,
+        filtersApplied: args.titleNumber !== undefined ? ["titleNumber"] : [],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
 }
 function stripHtml(s) {
     return s

package/dist/ecfr.js.map

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

package/dist/echo.d.ts

@@ -0,0 +1,143 @@
+/**
+ * EPA ECHO REST services — keyless facility environmental compliance / enforcement
+ * screening (ADR-0009). A NEW capability axis for the product: facility &
+ * competitor environmental compliance-risk screening / due diligence (EPA
+ * enforcement, inspection, violation, and penalty history keyed to a facility),
+ * orthogonal to the spend/contract/regulatory layers.
+ *
+ * The THIRD source on the R2 `DataSource` port (ADR-0005, after Socrata/CKAN):
+ * `echo.ts` writes ZERO fetch/coercion/error code — it REUSES `getJson` /
+ * `driftError` / `num`·`str` / `withMeta`, and COPIES (does NOT import) the
+ * fixed-host SSRF + honesty PATTERN. Fully PUBLIC, KEYLESS (`keylessMode:true`,
+ * byte-clean init — NO headers, like ckan.ts). ECHO is neither Socrata nor CKAN:
+ * it is a bespoke Oracle-PL/SQL-fronted REST facade with a TWO-STEP QueryID
+ * pagination model and a 200-with-error-body failure mode.
+ *
+ *   Step 1 (search):  https://echodata.epa.gov/echo/echo_rest_services.get_facilities?output=JSON&p_st=…
+ *                     → { Results:{ Message, QueryRows:"N", …counts…, QueryID:"n" } }  (NO rows)
+ *   Step 2 (rows):    https://echodata.epa.gov/echo/echo_rest_services.get_qid?output=JSON&qid=n&pageno=k
+ *                     → { Results:{ Message:"Working", Facilities:[ …rows… ] } }
+ *   Detail (DFR):     https://echodata.epa.gov/echo/dfr_rest_services.get_dfr?output=JSON&p_id={RegistryID}
+ *                     → { Results:{ Message:"Success", RegistryID, Reports, Permits, … } }
+ *
+ * ★ SSRF GUARD (policy① — the central design risk; a TIGHTER copy of the
+ *   Socrata/CKAN fixed-host shape). The attack surface is SMALLER than CKAN's:
+ *   (1) SINGLE fixed host constant `ECHO_HOST` — the caller NEVER supplies a host.
+ *   (2) THREE fixed service-path constants (a frozen Set) — the caller NEVER
+ *       supplies a path fragment; a service outside the Set ⇒ invalid_input before
+ *       any fetch (the path-injection guard).
+ *   (3) Every interpolated id is grammar-validated BEFORE use — `state` ∈ a frozen
+ *       US state/territory enum (also the silent-zero guard, below); `naics`
+ *       ^[0-9]{2,6}$ / `sic` ^[0-9]{2,4}$; `registryId` ^[0-9]{9,12}$ (FRS IDs are
+ *       12 digits; all-digit is the security property); the UPSTREAM-supplied
+ *       `qid` is validated ^[0-9]+$ BECAUSE it is external (echodata.epa.gov mints
+ *       it), before it is used in step 2; the internally-computed `pageno` is a
+ *       plain integer. `facilityName` (p_fn) is a free-text filter VALUE — encoded
+ *       through URLSearchParams, never touching the host/path.
+ *   (4) Construct the URL, then ASSERT `new URL(built).hostname === ECHO_HOST` and
+ *       `protocol === "https:"` ⇒ invalid_input on mismatch (belt-and-suspenders).
+ *   B1 (redirect SSRF): every getJson sets `redirect:"error"` — a 3xx off
+ *   echodata.epa.gov (migration / DNS-hijack / reused domain) throws; its body is
+ *   never read. Adding a service/filter later = a CONSTANT edit + a live
+ *   `output=JSON` verification — NEVER a free runtime host/path param.
+ *
+ * ★ 200-WITH-ERROR-BODY (the fake-empty trap — OBSERVED live, not defensive).
+ *   A bogus `qid`, a bad DFR `p_id`, AND a queryset-limit overflow all return HTTP
+ *   200 carrying `{Results:{Error:{ErrorMessage}}}`. `errorFromResponse` keys off
+ *   HTTP status and would pass a 200 straight through. So on EVERY response we
+ *   detect `Results.Error` FIRST and THROW (classified) BEFORE reading
+ *   QueryRows/Facilities — the ECHO analogue of CKAN's success:false-on-200 guard.
+ *   Classification (by ErrorMessage):
+ *     - "Queryset Limit would be exceeded"  ⇒ invalid_input (narrow the query)
+ *     - "…not found in ECHO"  (recycled qid) ⇒ not_found, RETRYABLE (the QueryID
+ *        is an ephemeral globally-recycled slot — a transient, not a missing
+ *        facility; retry echo_search_facilities)
+ *     - "ID … is invalid"  (bad DFR id)      ⇒ not_found (no report for that id)
+ *     - anything else                        ⇒ schema_drift (surfaced, never
+ *        silently swallowed)
+ *
+ * ★ TWO-STEP HIDDEN IN-CALL (ADR-0009 §1a). The QueryID is an ephemeral,
+ *   globally-recycled, monotonically-incrementing cache slot (live-verified:
+ *   IDs jumped 835→909 across a handful of calls) — NOT deterministic, NOT safe to
+ *   persist across tool calls. `echo_search_facilities` therefore performs BOTH
+ *   steps inside ONE invocation (get_facilities → capture QueryRows + fresh
+ *   QueryID → immediately get_qid at the requested page) and NEVER exposes the
+ *   QueryID to the caller. Paginating to page N re-runs get_facilities fresh.
+ *   Two HTTP round-trips per search; robust against id recycling (memoize is
+ *   unsafe here). Pagination is the standard offset/limit contract, translated to
+ *   `pageno = offset/limit + 1` and `responseset = limit`; because ECHO can only
+ *   page on page boundaries, `offset` MUST be an exact multiple of `limit`
+ *   (else invalid_input locally, before any fetch).
+ *
+ * ★ M2 — NAICS vs SIC filtering, LIVE-VERIFIED 2026-07-12 (the data-lie guard).
+ *   `p_st=DC` bare ⇒ QueryRows 4714. `p_st=DC&p_naics=325` / `=32511` / `=54` /
+ *   even a bogus `=999999` ALL returned the identical 4714 ⇒ ECHO DROPS NAICS
+ *   entirely (a real filter would return 0 for a nonexistent code). BUT
+ *   `p_st=DC&p_sic=2911` ⇒ 1 and `&p_sic=9999`/`=8011` ⇒ 0 ⇒ SIC DOES narrow.
+ *   So the two behave DIFFERENTLY (a MIXED outcome — a deviation from the ADR's
+ *   unified Case-A/B framing):
+ *     - `sic`   = Case A (works)   ⇒ a REAL filter; listed in filtersApplied.
+ *     - `naics` = Case B (dropped) ⇒ BEST-EFFORT: marked best-effort in the
+ *       tool-schema description, added to `_meta.filtersDropped` whenever passed,
+ *       AND a `_meta.notes` disclosure warns the returned facilities are NOT
+ *       guaranteed to match the NAICS code. NEVER silently presented as filtered.
+ *
+ * ★ HONESTY (`_meta`; REUSE withMeta/buildMeta). `totalAvailable = num(QueryRows)`
+ *   — the EXACT upstream total, NEVER the page size. `returned =
+ *   Results.Facilities.length`. `hasMore = offset + returned < total` (exact — no
+ *   page-fullness hedge). Genuine-empty (`QueryRows:"0"`, no Results.Error) ⇒
+ *   complete:true / totalAvailable:0. Outage/5xx/timeout ⇒ getJson throws (never a
+ *   fake empty). `num`/`str` are null-never-0. Row-level currency/count fields
+ *   (e.g. TotalPenalties "$1,056,616") pass through VERBATIM.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const ECHO_STATES: readonly ["AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI"];
+export type EchoState = (typeof ECHO_STATES)[number];
+export type EchoRow = Record<string, unknown>;
+/**
+ * GET one ECHO REST service. SSRF guard: `service` ∈ the frozen 3-member Set
+ * (the path-injection guard), params via URLSearchParams (encoded values, no
+ * host-alteration surface), then the CONSTRUCTED URL's hostname === ECHO_HOST
+ * (https) assertion. Sets `redirect:"error"` (B1); NO headers (keyless — ECHO is
+ * anonymous, byte-clean init). Reuses errors.ts retry/timeout/taxonomy (429 →
+ * rate_limited; 5xx → upstream_unavailable; 404 → not_found; 400 → invalid_input).
+ * Returns the parsed JSON (unknown; the caller validates the Results envelope).
+ */
+export declare function echoGet(service: string, params: URLSearchParams): Promise<unknown>;
+/**
+ * Search EPA-regulated facilities by state (+ optional sic / facilityName /
+ * majorOnly / federalOnly / naics-best-effort) with compliance/enforcement
+ * screening fields. The workhorse: state + industry + name + major/federal
+ * across CAA/CWA/RCRA/SDWA. `state` is REQUIRED (an unscoped national query is
+ * ~5.6M rows AND the state enum is the silent-zero guard).
+ *
+ * Hides the two-step QueryID pagination behind ONE call: internally get_facilities
+ * (→ exact QueryRows + a fresh QueryID) then get_qid?pageno=offset/limit+1 (→ the
+ * rows). The QueryID is captured and consumed in-call, NEVER exposed. Rows pass
+ * through verbatim. HONESTY: totalAvailable = num(QueryRows) (exact, never the page
+ * size); genuine-empty (QueryRows:"0") ⇒ complete:true/total:0; a Results.Error ⇒
+ * classified throw (never a fake empty); an outage ⇒ getJson throws.
+ */
+export declare function searchFacilities(args: {
+    state: EchoState;
+    naics?: string;
+    sic?: string;
+    facilityName?: string;
+    majorOnly?: boolean;
+    federalOnly?: boolean;
+    limit?: number;
+    offset?: number;
+}): Promise<MetaBundle>;
+/**
+ * Fetch the Detailed Facility Report (DFR) for ONE facility by its FRS RegistryID
+ * (from echo_search_facilities rows): the per-facility compliance / enforcement /
+ * inspection / permit deep-dive for competitor / acquisition-target due diligence.
+ * Single record (no pagination). A bad/unknown RegistryID ⇒ the 200-with-error-
+ * body guard classifies "ID … is invalid" ⇒ not_found (never a fabricated report).
+ */
+export declare function facilityReport(args: {
+    registryId: string;
+}): Promise<MetaBundle>;
+//# sourceMappingURL=echo.d.ts.map

package/dist/echo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo.d.ts","sourceRoot":"","sources":["../src/echo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAKzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAkCf,eAAO,MAAM,WAAW,2VAOd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAiBrD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAwED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,UAAU,CAAC,CA0JtB;AAGD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqCtB"}