@cliwant/mcp-sam-gov 1.9.0 → 1.11.0

package/src/bonfire.ts

@@ -0,0 +1,249 @@
+/**
+ * bonfire.ts — Bonfire (Euna Solutions) per-organization open-solicitation RSS,
+ * a keyless-first SLED bid source (loop — SLED bid campaign, 2026-07-19).
+ *
+ * WHAT IT ADDS: Bonfire hosts the open-bid portals of thousands of US state/local
+ * governments; each org exposes a KEYLESS RSS 2.0 feed of its currently-open
+ * opportunities at `https://{org}.bonfirehub.com/opportunities/rss` (live-verified
+ * on Dallas/Harris County/Utah/Bernalillo/…). One of the two highest-reach keyless
+ * SLED bid feeds (with OpenGov Procurement).
+ *
+ * ★ NO keyless directory API: Bonfire's authoritative org list
+ * (`GET common-production-api-global.bonfirehub.com/v1.0/organizations/external`)
+ * is AUTH-GATED (a free vendor-account token) — OUT OF BOUNDS (we never sign in).
+ * So this ships a CURATED, live-verified SEED directory (187 US orgs; §BONFIRE_
+ * ORGS) as `bonfire_list_organizations`, and documents the keyless RSS-probe
+ * refresh method (no catch-all: `{slug}.bonfirehub.com/opportunities/rss` returns
+ * 200 <rss> for a real org, a connection failure for a non-provisioned slug). The
+ * seed is a PARTIAL directory (Euna markets up to ~900 US orgs) — disclosed.
+ *
+ * The module REUSES `getText` (shared XML/RSS fetch, redirect:"error") /
+ * `driftError` / `str`·`num` / `withMeta`·`buildMeta`, mirroring fpds/gao. KEYLESS.
+ *
+ * ★ SSRF: org is charclass-validated (`^[a-z0-9-]{1,64}$` — no dots), the URL is
+ *   built on the FIXED `.bonfirehub.com` suffix, and a post-construction assertion
+ *   requires `hostname === {org}.bonfirehub.com` (over https) BEFORE the fetch;
+ *   `redirect:"error"`.
+ *
+ * ★ HONESTY PILLARS:
+ *   P1: the RSS is the COMPLETE current open-opportunity set for the org (no server
+ *     pagination), so totalAvailable = the parsed item count (the true total, NOT a
+ *     page length); client-side limit/offset page over it.
+ *   P2: getText THROWS on 429 / 5xx / 404 / timeout — NEVER a fake empty. An empty
+ *     channel (0 items) ⇒ honest empty (the org has no open opportunities now).
+ *   P3: every field via `str` (null-never-empty); dates surfaced verbatim.
+ *   P4: a 200 body that is not RSS (no `<rss`/`<channel`) ⇒ schema_drift (never
+ *     parsed as an empty set).
+ */
+
+import { ToolErrorCarrier } from "./errors.js";
+import { getText, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+export { num };
+
+// ─── Fixed suffix (SSRF core) + org grammar ───────────────────────
+const BONFIRE_SUFFIX = ".bonfirehub.com";
+export const BONFIRE_ORG_RE = /^[a-z0-9-]{1,64}$/;
+const bonfireLabel = (org: string) => `bonfire:${org}/opportunities/rss`;
+const BONFIRE_SOURCE = (org: string) =>
+  `${org}.bonfirehub.com via Bonfire (Euna) open-opportunities RSS (keyless)`;
+
+const BONFIRE_SEED_NOTE =
+  "This directory is a CURATED, live-verified SEED (Bonfire has NO keyless org-list API; the authoritative list is auth-gated and out of bounds). Euna markets up to ~900 US orgs, so the seed is partial — probe `{slug}.bonfirehub.com/opportunities/rss` (200 <rss> = real org) to extend. Feed a result's `org` to bonfire_search_opportunities.";
+
+// ─── The curated 187-org US seed directory (live-verified 2026-07-19) ──
+// "slug|Entity|ST" — the slug is the RSS subdomain. Non-US (.ca / cayman / etc.)
+// deliberately excluded.
+const BONFIRE_SEED_RAW: readonly string[] = [
+  "littlerock|City of Little Rock|AR",
+  "buckeyeaz|City of Buckeye|AZ", "goodyearaz|City of Goodyear|AZ", "peoriaaz|City of Peoria|AZ", "scottsdaleaz|City of Scottsdale|AZ", "yumaaz|City of Yuma|AZ", "pinalcountyaz|Pinal County|AZ", "susd|Scottsdale USD|AZ", "tollesonuhsd|Tolleson Union HSD|AZ",
+  "cityofirvine|City of Irvine|CA", "oaklandca|City of Oakland|CA", "alamedacounty|Alameda County|CA", "solanocounty|Solano County|CA", "ventura|County of Ventura|CA", "yolocounty|Yolo County|CA", "mtc|Metropolitan Transportation Commission|CA", "azusa|Azusa USD|CA", "stocktonusd|Stockton USD|CA", "weta|SF Bay Area Water Emergency Transportation Authority|CA", "acwd|Alameda County Water District|CA", "wrd|Water Replenishment District of Southern CA|CA", "actransit|AC Transit|CA", "marintransit|Marin Transit|CA", "mst|Monterey-Salinas Transit|CA", "omnitrans|Omnitrans|CA", "smctd|San Mateo County Transit District|CA", "sonomamarintrain|Sonoma-Marin Area Rail Transit|CA", "ggbhtd|Golden Gate Bridge Highway & Transportation District|CA",
+  "bouldercounty|Boulder County|CO",
+  "crcog|Capitol Region Council of Governments|CT", "easternct|Eastern Connecticut State University|CT",
+  "dfm|DE OMB - Division of Facility Management|DE", "gss|DE OMB - Government Support Services|DE",
+  "daviefl|Town of Davie|FL", "ocoee|City of Ocoee|FL", "broward|Broward County|FL", "hillsboroughcounty|Hillsborough County|FL", "marionfl|Marion County|FL", "monroecounty-fl|Monroe County|FL", "pascocountyfl|Pasco County|FL", "famu|Florida A&M University|FL", "fau|Florida Atlantic University|FL", "fgcu|Florida Gulf Coast University|FL", "floridapoly|Florida Polytechnic University|FL", "ucf|University of Central Florida|FL", "tampabaywater|Tampa Bay Water|FL", "gohart|Hillsborough Transit Authority|FL", "psta|Pinellas Suncoast Transit Authority|FL",
+  "brookhavenga|City of Brookhaven|GA", "sandysprings|City of Sandy Springs|GA", "chathamcountyga|Chatham County|GA", "columbiacountyga|Columbia County|GA", "gwinnett|Gwinnett County Public Schools|GA",
+  "cityofnampa|City of Nampa|ID", "adacounty|Ada County|ID", "bannockcounty|Bannock County|ID",
+  "cookcountyil|Cook County|IL", "thecha|Chicago Housing Authority|IL", "cps|Chicago Public Schools|IL", "u-46|School District U-46|IL", "chicagoparkdistrict|Chicago Park District|IL", "mwrd|Metro Water Reclamation District of Greater Chicago|IL", "transitchicago|Chicago Transit Authority|IL", "metra|Metra|IL",
+  "indygo|Indianapolis Public Transportation Corp|IN",
+  "olatheks|City of Olathe|KS", "wichita|City of Wichita|KS",
+  "covingtonky|City of Covington|KY", "louisvilleky|City of Louisville|KY", "owensboro|City of Owensboro|KY", "lexingtonky|Lexington-Fayette|KY", "kyhousing|Kentucky Housing Corporation|KY", "tarc|Transit Authority of River City|KY",
+  "umass|University of Massachusetts|MA",
+  "harfordcountymd|Harford County|MD", "habc|Housing Authority of Baltimore City|MD", "hcpss|Howard County Public School System|MD", "menv|Maryland Environmental Service|MD", "mdcourts|Maryland Judiciary|MD",
+  "maine|State of Maine|ME",
+  "detroit|City of Detroit|MI",
+  "ramseycountymn|Ramsey County|MN", "sourcewell|Sourcewell|MN",
+  "jeffersoncitymo|Jefferson City|MO", "stlouiscountymo|St. Louis County|MO", "stlcc|St. Louis Community College|MO",
+  "apexnc|Town of Apex|NC", "charlottenc|City of Charlotte|NC", "wake|Wake County|NC", "ncat|NC A&T State University|NC", "ncsu|NC State University|NC",
+  "rutgers|Rutgers University|NJ",
+  "cabq|City of Albuquerque|NM", "mckinleycounty|McKinley County|NM",
+  "clarkcountynv|Clark County|NV", "ccsd|Clark County School District|NV",
+  "suffolkcountyny|Suffolk County|NY", "stonybrook|Stony Brook University|NY", "healthsolutions|Public Health Solutions|NY", "centro|Central NY Regional Transportation Authority|NY", "nfta|Niagara Frontier Transportation Authority|NY", "panynj|Port Authority of New York & New Jersey|NY",
+  "akronohio|City of Akron|OH", "cincinnati-oh|City of Cincinnati|OH", "columbus|City of Columbus|OH", "equalisgroup|Equalis Group|OH",
+  "pdx|Portland State University|OR",
+  "pennbid|PennBid|PA", "alleghenycounty|Allegheny County|PA",
+  "charlestoncounty|Charleston County|SC", "tridenttech|Trident Technical College|SC",
+  "apsu|Austin Peay State University|TN",
+  "dfwairport|DFW International Airport|TX", "amarillo|City of Amarillo|TX", "arlingtontx|City of Arlington|TX", "brownsvilletx|City of Brownsville|TX", "burlesontx|City of Burleson|TX", "cityoflewisville|City of Lewisville|TX", "dallascityhall|City of Dallas|TX", "fortworthtexas|City of Fort Worth|TX", "friscotexas|City of Frisco|TX", "leandertx|City of Leander|TX", "mckinneytexas|City of McKinney|TX", "midlandtexas|City of Midland|TX", "roundrocktexas|City of Round Rock|TX", "sanantonio|City of San Antonio|TX", "schertz|City of Schertz|TX", "southlake|City of Southlake|TX", "templetx|City of Temple|TX", "waco-texas|City of Waco|TX", "mansfield|Mansfield Council of Governments|TX", "brazoriacounty|Brazoria County|TX", "dentoncounty|Denton County|TX", "galvestoncountytx|Galveston County|TX", "harriscountytx|Harris County|TX", "johnsoncountytx|Johnson County|TX", "lubbock|Lubbock County|TX", "parkercountytx|Parker County|TX", "smithcounty|Smith County|TX", "wilco|Williamson County|TX", "hccs|Houston Community College|TX", "rice-edu|Rice University|TX", "tccd|Tarrant County College District|TX", "utdallas|UT Dallas|TX", "utexas|UT Austin|TX", "utrgv|UT Rio Grande Valley|TX", "uttyler|UT Tyler|TX", "uthscsa|UT Health San Antonio|TX", "saha|Opportunity Home San Antonio|TX", "universityhealth|University Health (hospital district)|TX", "allenisd|Allen ISD|TX", "austinisd|Austin ISD|TX", "comalisd|Comal ISD|TX", "dallasisd|Dallas ISD|TX", "fortbendisd|Fort Bend ISD|TX", "kleinisd|Klein ISD|TX", "laredoisd|Laredo ISD|TX", "magnoliaisd|Magnolia ISD|TX", "mesquiteisd|Mesquite ISD|TX", "tomballisd|Tomball ISD|TX", "twc-texas-gov|Texas Workforce Commission|TX", "txdot|Texas Department of Transportation|TX", "dart|Dallas Area Rapid Transit|TX", "ridemetro|Harris County METRO|TX",
+  "ccog|The Cooperative Council of Governments|US", "omniapartners|OMNIA Partners|US", "utah|U3P / Utah Public Procurement Place|UT",
+  "fairfaxcounty|Fairfax County|VA", "cnu|Christopher Newport University|VA", "gmu|George Mason University|VA", "nsu|Norfolk State University|VA", "fcps|Fairfax County Public Schools|VA",
+  "cityofvancouver|City of Vancouver WA|WA", "federalwaywa|City of Federal Way|WA", "clarkcountywa|Clark County WA|WA", "kingcounty|King County|WA", "portolympia|Port of Olympia|WA", "lwsd|Lake Washington School District|WA", "tacoma|Tacoma Public Schools|WA",
+  "cityofmilwaukee|City of Milwaukee|WI", "westalliswi|City of West Allis|WI", "racinecounty|Racine County|WI", "waukeshacounty|Waukesha County|WI", "cvtc|Chippewa Valley Technical College|WI", "mmsd|Milwaukee Metropolitan Sewerage District|WI",
+  "marshall|Marshall University|WV",
+];
+
+export type BonfireOrg = { org: string; name: string; state: string };
+export const BONFIRE_ORGS: readonly BonfireOrg[] = BONFIRE_SEED_RAW.map((r) => {
+  const [org, name, state] = r.split("|");
+  return { org: org ?? "", name: name ?? "", state: state ?? "" };
+});
+
+// ─── XML helpers (bespoke regex parser, mirrors fpds/gao) ─────────
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"')
+    .replace(/&#0?39;/g, "'").replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function tag(block: string, name: string): string | null {
+  const m = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`).exec(block);
+  if (!m) return null;
+  return decodeEntities((m[1] ?? "").replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1").trim());
+}
+
+export type BonfireOpportunity = {
+  referenceNumber: string | null;
+  name: string | null;
+  description: string | null;
+  closeDate: string | null;
+  link: string | null;
+  pubDate: string | null;
+};
+
+/** Parse a Bonfire RSS item block → curated opportunity. Title is
+ *  "Reference #: <ref>. Name: <name>"; description embeds "closes <date>". */
+function mapItem(block: string): BonfireOpportunity {
+  const title = tag(block, "title");
+  const description = tag(block, "description");
+  let referenceNumber: string | null = null;
+  let name: string | null = str(title);
+  if (title) {
+    const m = /Reference #:\s*(.*?)\.\s*Name:\s*([\s\S]*)$/.exec(title);
+    if (m) { referenceNumber = str(m[1]); name = str(m[2]); }
+  }
+  let closeDate: string | null = null;
+  if (description) {
+    const c = /\bcloses\s+([A-Za-z0-9:,\s]+?(?:AM|PM)[A-Za-z0-9 ]*)$/i.exec(description) || /\bcloses\s+(.+)$/i.exec(description);
+    if (c && c[1]) closeDate = str(c[1].trim());
+  }
+  return { referenceNumber, name, description: str(description), closeDate, link: str(tag(block, "link")), pubDate: str(tag(block, "pubDate")) };
+}
+
+// ─── SSRF-guarded fetch ───────────────────────────────────────────
+async function getBonfireRss(org: string): Promise<string> {
+  const host = `${org}${BONFIRE_SUFFIX}`;
+  const url = `https://${host}/opportunities/rss`;
+  const built = new URL(url);
+  if (built.hostname !== host || !built.hostname.endsWith(BONFIRE_SUFFIX) || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Constructed Bonfire URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${JSON.stringify(host)} over https — refusing to fetch (SSRF safety).`,
+      retryable: false,
+      upstreamEndpoint: bonfireLabel(org),
+    });
+  }
+  return getText(url, { label: bonfireLabel(org), redirect: "error" });
+}
+
+// ─── Tool 1: bonfire_list_organizations (curated seed directory) ──
+export type BonfireListArgs = { state?: string; query?: string; limit?: number; offset?: number };
+
+export async function listOrganizations(args: BonfireListArgs): Promise<MetaBundle> {
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+  const stateFilter = args.state ? args.state.trim().toUpperCase() : null;
+  const queryFilter = args.query ? args.query.trim().toLowerCase() : null;
+  const filtersApplied: string[] = [];
+  if (stateFilter) filtersApplied.push("state");
+  if (queryFilter) filtersApplied.push("query");
+
+  const filtered = BONFIRE_ORGS.filter(
+    (o) =>
+      (!stateFilter || o.state.toUpperCase() === stateFilter) &&
+      (!queryFilter || o.name.toLowerCase().includes(queryFilter)),
+  );
+  const totalAvailable = filtered.length;
+  const page = filtered.slice(offset, offset + limit);
+  const returned = page.length;
+  const hasMore = offset + returned < totalAvailable;
+
+  return withMeta(
+    { organizations: page },
+    {
+      source: "Bonfire (Euna) curated seed directory (keyless)",
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit, hasMore, nextOffset: hasMore ? offset + returned : null },
+      notes: [BONFIRE_SEED_NOTE],
+    } satisfies Partial<ResponseMeta>,
+  );
+}
+
+// ─── Tool 2: bonfire_search_opportunities (per-org RSS) ───────────
+export type BonfireSearchArgs = { org: string; limit?: number; offset?: number };
+
+export async function searchOpportunities(args: BonfireSearchArgs): Promise<MetaBundle> {
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+  const org = args.org ?? "";
+
+  if (!BONFIRE_ORG_RE.test(org)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Invalid Bonfire org ${JSON.stringify(org)} — expected a lowercase-alnum/hyphen subdomain slug (from bonfire_list_organizations, e.g. 'harriscountytx', 'u-46').`,
+      retryable: false,
+      upstreamEndpoint: bonfireLabel(org),
+    });
+  }
+
+  const body = await getBonfireRss(org); // getText THROWS on 429/5xx/404/timeout (P2)
+
+  // P4: a 200 body must be RSS (no <rss/<channel ⇒ drift; e.g. an error/HTML page).
+  if (!/<rss[\s>]/i.test(body) || !/<channel[\s>]/i.test(body)) {
+    throw driftError(bonfireLabel(org), "Bonfire returned a non-RSS body at HTTP 200 — schema drift (expected an <rss><channel> feed).");
+  }
+
+  // Tolerate attributes on the opening <item …> tag (consistent with the <channel[\s>]
+  // drift guard and the inner tag() matcher). RSS 2.0 <item> has no standard attributes,
+  // but a namespaced/extended feed could add them — a bare-<item> regex would silently
+  // DROP such items and undercount totalAvailable (a latent P1 risk caught in dogfooding).
+  const items = body.match(/<item(?:\s[^>]*)?>[\s\S]*?<\/item>/gi) ?? [];
+  const all = items.map(mapItem);
+  // P1: the RSS is the COMPLETE open set ⇒ totalAvailable = item count (true total).
+  const totalAvailable = all.length;
+  const pageRows = all.slice(offset, offset + limit);
+  const returned = pageRows.length;
+  const hasMore = offset + returned < totalAvailable;
+
+  return withMeta(
+    { org, opportunities: pageRows },
+    {
+      source: BONFIRE_SOURCE(org),
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied: ["org"],
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit, hasMore, nextOffset: hasMore ? offset + returned : null },
+      notes: [
+        "The RSS is the COMPLETE set of the org's currently-OPEN opportunities (no server pagination) — totalAvailable is the exact open-opportunity count, and this tool pages over it client-side. An empty feed (returned 0) means the org has no open opportunities right now. closeDate is parsed best-effort from the description text.",
+      ],
+    } satisfies Partial<ResponseMeta>,
+  );
+}

package/src/cbp-border.ts

@@ -1,8 +1,10 @@
 /**
  * cbp-border.ts — CBP Border Wait Times (bwt.cbp.gov, KEYLESS) — the FREIGHT /
- * LOGISTICS lane. Live commercial-vehicle (and passenger) wait times at every US
+ * LOGISTICS lane. Live COMMERCIAL-VEHICLE (freight-truck) wait times at every US
  * land border port (Canadian + Mexican): per-port lane delays, operational status,
- * and open-lane counts. Answers "what's the current commercial-truck delay at port
+ * and open-lane counts. (The raw feed also carries passenger/pedestrian lanes, but
+ * this tool surfaces ONLY the commercial-vehicle lanes — the freight lane.)
+ * Answers "what's the current commercial-truck delay at port
  * X" — real-time freight-crossing situational awareness for logistics/trade vendors.
  *
  * SOURCE: CBP's official Border Wait Times API (bwt.cbp.gov/api/bwtnew) — a .gov host,
@@ -127,9 +129,11 @@ async function loadPorts(): Promise<CbpPort[]> {
 
 // ─── Tool: cbp_border_wait_times ──────────────────────────────────
 /**
- * List CBP land-border-port commercial-vehicle (+ passenger) wait times, optionally
- * filtered by border (Canadian/Mexican) and/or port name (substring). Client-side
- * filter over the live feed; honest `_meta` (exact match total + real-time freshness).
+ * List CBP land-border-port COMMERCIAL-VEHICLE (freight-truck) wait times, optionally
+ * filtered by border (Canadian/Mexican) and/or port name (substring, applied
+ * CLIENT-SIDE over the full fetched set and disclosed as such). Passenger/pedestrian
+ * lanes are NOT surfaced (freight lane only). Honest `_meta` (exact match total +
+ * real-time freshness).
  */
 export async function borderWaitTimes(args: {
   border?: string;
@@ -142,10 +146,20 @@ export async function borderWaitTimes(args: {
   const all = await loadPorts();
 
   const filtersApplied: string[] = [];
+  const filtersDropped: string[] = [];
   const borderQ = args.border?.trim().toLowerCase();
   const portQ = args.portName?.trim().toLowerCase();
-  if (args.border !== undefined) filtersApplied.push("border");
-  if (args.portName !== undefined) filtersApplied.push("portName");
+  // [filter honesty] Only claim a filter APPLIED when its query is non-empty — a
+  // border:"" / portName:"" (or whitespace) narrows nothing, so reporting it as
+  // applied while returning every port would be a false filtersApplied.
+  if (args.border !== undefined) {
+    if (borderQ) filtersApplied.push("border");
+    else filtersDropped.push("border(empty)");
+  }
+  if (args.portName !== undefined) {
+    if (portQ) filtersApplied.push("portName");
+    else filtersDropped.push("portName(empty)");
+  }
 
   const matched = all.filter((p) => {
     if (borderQ && !(p.border ?? "").toLowerCase().includes(borderQ)) return false;
@@ -159,6 +173,13 @@ export async function borderWaitTimes(args: {
   const hasMore = offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
+  const notes: string[] = [PROVENANCE_NOTE, FRESHNESS_NOTE];
+  if (filtersApplied.length > 0) {
+    notes.push(
+      "border / portName are applied CLIENT-SIDE over the full live port set (fetched in ONE request — the CBP feed has no server-side filter); totalAvailable is the EXACT matched count over that full set.",
+    );
+  }
+
   return withMeta(
     { ports: page },
     {
@@ -168,10 +189,10 @@ export async function borderWaitTimes(args: {
       totalAvailable,
       truncated: hasMore,
       filtersApplied,
-      filtersDropped: [],
+      filtersDropped,
       fieldsUnavailable: [],
       pagination: { offset, limit, hasMore, nextOffset },
-      notes: [PROVENANCE_NOTE, FRESHNESS_NOTE],
+      notes,
     } satisfies Partial<ResponseMeta>,
   );
 }

package/src/gao.ts

@@ -593,6 +593,21 @@ export async function gaoProtestLookup(args: {
 
   // ── Feed path ──────────────────────────────────────────────────────
   const xml = await getText(RSS_URL, "gao:rss");
+  // [P2/P4] A 200 body that isn't the RSS feed (GAO's edge is Cloudflare/WAF — a
+  // challenge or maintenance interstitial returns 200 HTML, NOT the feed) must
+  // NOT be parsed into an empty decision list: parseFeed's <item> regex yields []
+  // on any non-RSS body, which would read as "no recent bid protests" — an
+  // outage-as-empty lie. A real feed always carries <rss>/<channel>/<item> (a
+  // genuinely EMPTY feed still has <channel>, so a 0-item feed passes). Guard the
+  // shape and surface a retryable outage instead of a fabricated empty result.
+  if (!/<(rss|feed|channel|item)\b/i.test(xml)) {
+    throw new ToolErrorCarrier({
+      kind: "upstream_unavailable",
+      retryable: true,
+      message: `GAO RSS returned a 200 body with no <rss>/<channel>/<item> markup (${xml.length} bytes) — GAO's Cloudflare/WAF edge most likely served a challenge or maintenance interstitial instead of the feed. Surfaced as a retryable outage rather than a fabricated empty decision list (which would falsely read as "no recent bid protests"). Retry shortly.`,
+      upstreamEndpoint: "gao:rss",
+    });
+  }
   const rawItems = parseFeed(xml);
   const protests = rawItems.filter(isBidProtest);
 
@@ -653,9 +668,16 @@ export async function gaoProtestLookup(args: {
 
   // Apply the outcome filter now that we (may) have parsed outcomes, then cap.
   const filtersDropped: string[] = [];
+  let outcomeUndetermined = 0;
   if (outcomeFilter) {
     if (enrich) {
       filtersApplied.push("outcome(from decision page)");
+      // [filter honesty] A decision whose page could not be enriched has
+      // outcome=null — UNDETERMINED, not confirmed "≠ outcomeFilter". Dropping
+      // those silently makes returned:0 read as "no <outcome> protests exist"
+      // when the truth is "no outcome could be read" (GAO per-decision pages are
+      // intermittently WAF-blocked). Count them so it is disclosed, not swallowed.
+      outcomeUndetermined = decisions.filter((d) => d.outcome === null).length;
       decisions = decisions.filter((d) => d.outcome === outcomeFilter);
     } else {
       // Can't determine outcome without enrichment → don't silently pretend to.
@@ -672,6 +694,11 @@ export async function gaoProtestLookup(args: {
       `${enrichFailures} decision(s) returned feed-level fields only; per-decision page enrichment failed (agency/outcome/solicitation may be null for those).`,
     );
   }
+  if (outcomeFilter && enrich && outcomeUndetermined > 0) {
+    notes.push(
+      `${outcomeUndetermined} recent decision(s) were EXCLUDED from the outcome='${outcomeFilter}' filter because their decision page could not be read (enrichment failed) — their outcome is UNDETERMINED, not confirmed to differ. Treat a 0 or low result here as "outcome could not be determined for those", NOT "none exist"; retry (GAO per-decision pages are intermittently WAF-blocked) or drop the outcome filter to list all recent decisions.`,
+    );
+  }
   if (!enrich) {
     notes.push(
       "enrich=false: only RSS feed-level fields were returned (protester/title/date/summary). Agency, outcome, solicitation number, and the decision PDF require the per-decision page — call again with enrich=true or a specific bNumber.",

package/src/grants.ts

@@ -139,7 +139,7 @@ export async function searchGrants(args: {
   const notes: string[] = [];
   if (args.agency || args.cfda) {
     notes.push(
-      "Grants.gov silently ignores an unknown agency code or CFDA number (it returns the UNFILTERED result set instead of an error) and does not confirm which filters were honored — if the result count looks too broad, verify the agency/CFDA value.",
+      "Grants.gov applies the agency/CFDA filter server-side (live-verified 2026-07-20): a bogus or misspelled value returns 0 results, NOT an error and NOT the unfiltered set — so an unexpectedly EMPTY filtered search most often means the agency/CFDA value is invalid, not that no grants exist. `filtersApplied` reflects that the filter was sent. Verify the agency code / CFDA number if a filtered result is surprisingly empty.",
     );
   }
   // VQ-1 (C82 dogfooding): Grants.gov OR-tokenizes multi-word keywords (matches ANY

package/src/gsa-perdiem.ts

@@ -57,8 +57,26 @@ const GSA_PERDIEM_LABEL = "gsa-perdiem:/travel/perdiem/v2/rates";
 const GSA_PERDIEM_SOURCE = (mode: string) =>
   `${GSA_PERDIEM_HOST} via GSA Federal Travel Per-Diem API (${mode})`;
 
-// The default per-diem fiscal year (ADR-0050 — the current confirmed vintage).
-export const DEFAULT_PERDIEM_YEAR = "2025";
+/**
+ * The US federal fiscal year for a date (ADR-0050). The FY begins Oct 1, so
+ * Oct–Dec belong to the NEXT calendar year's FY (e.g. 2025-11 → FY2026) while
+ * Jan–Sep stay in the current (e.g. 2026-07 → FY2026). Pure + UTC-based so it is
+ * deterministic and timezone-independent (the intra-day rollover instant is
+ * immaterial — per-diem rates do not change within a day).
+ */
+export function federalFiscalYear(d: Date): number {
+  return d.getUTCMonth() >= 9 ? d.getUTCFullYear() + 1 : d.getUTCFullYear();
+}
+
+/**
+ * The default per-diem year when the caller omits `year`: the CURRENT federal
+ * fiscal year. GSA publishes rates per FY; a hard-coded default silently serves
+ * an EXPIRED vintage once the FY rolls over (the drift this replaces — a no-year
+ * lookup must track the live FY, not a frozen year).
+ */
+export function defaultPerdiemYear(): string {
+  return String(federalFiscalYear(new Date()));
+}
 
 // ─── Validation charclasses (SSRF + "verify the input" honesty) ───
 // Each rides in a single PATH segment (encodeURIComponent-escaped), so these are
@@ -158,7 +176,7 @@ async function getGsaPerdiem(path: string): Promise<unknown> {
 
 /**
  * Look up GSA Federal Travel per-diem rates by EITHER (city + state) OR zip, for a
- * given `year` (default 2025). Returns flattened rate rows (each outer state/year
+ * given `year` (default: the current U.S. federal fiscal year). Returns flattened rate rows (each outer state/year
  * group × inner city/rate) + honest `_meta`: totalAvailable = the row count (no
  * pagination — P1), lodging/meals as null-never-0 dollars (P3), standardRate/isOconus
  * as real booleans, the months array preserved as-is. The DEMO_KEY rate disclosure
@@ -168,7 +186,8 @@ export async function perdiemRates(
   args: GsaPerdiemRatesArgs,
 ): Promise<MetaBundle> {
   const label = GSA_PERDIEM_LABEL;
-  const year = args.year ?? DEFAULT_PERDIEM_YEAR;
+  const yearWasDefaulted = args.year === undefined;
+  const year = args.year ?? defaultPerdiemYear();
 
   // ── [INPUT] EITHER (city + state) OR zip — never both, never neither. This is a
   //    caller-shape check (0 fetch): an ambiguous or empty lookup is invalid_input,
@@ -341,6 +360,11 @@ export async function perdiemRates(
 
   const returned = rows.length;
   const notes: string[] = [RATE_MEANING_NOTE, STANDARD_RATE_NOTE, NO_PAGINATION_NOTE];
+  if (yearWasDefaulted) {
+    notes.push(
+      `No \`year\` was supplied, so it defaulted to the CURRENT U.S. federal fiscal year (FY${year}). GSA per-diem ceilings are set per fiscal year (Oct 1–Sep 30); pass an explicit \`year\` for a prior or upcoming FY.`,
+    );
+  }
   pushKeyNote(notes);
 
   return withMeta(

package/src/integrity.ts

@@ -294,7 +294,22 @@ export async function checkExclusions(args: {
   const serverTruncated =
     totalElements !== null && rawResults.length < totalElements;
   const hitCap = totalElements !== null && totalElements > SGS_MAX_RECORDS;
-  const truncated = serverTruncated || hitCap || postFiltered;
+  // totalAvailable HONESTY: the raw free-text `totalElements` counts every record
+  // that merely shares a WORD with the query — NOT the name-gated matches this
+  // tool reports. Surfacing it read as "0 of 252 matches, incomplete" for a firm
+  // with ZERO real matches (a vetting tool must not overstate match availability).
+  // When the result is name-gated (the normal case — a selector is always
+  // required), the true count of name-MATCHING exclusions is genuinely unknown
+  // from one page of text hits, so report null (never the free-text total); the
+  // per-page match count stays in data.matchCount.
+  const totalAvailable = postFiltered ? null : totalElements;
+  // truncated only when there is genuinely more to see: more server pages, the
+  // deep-paging cap, or this page dropped loose text hits (so a name VARIANT
+  // could match on a later page). The old `|| postFiltered` forced truncated:true
+  // even over a genuinely empty result set (0 text hits) — asserting incompleteness
+  // over an empty set, a contradiction. A fully-consumed name-gated result is a
+  // complete, honest empty.
+  const truncated = serverTruncated || hitCap || (postFiltered && looseTextHits > 0);
 
   const notes: string[] = [NOT_PROOF_NOTE];
   notes.push(
@@ -307,7 +322,7 @@ export async function checkExclusions(args: {
   }
   if (postFiltered) {
     notes.push(
-      "A uei/cage/classification/activeOnly post-filter was applied over the fetched page only — the true match count for the combined filter may exceed this page. Narrow with a more specific `query` or raise `size`.",
+      "A uei/cage/classification/activeOnly post-filter was applied over the fetched page only — the true name-matched total is unknown from one page, so `totalAvailable` is null (the raw free-text hit count is NOT the match count). `matchCount` is this page's name-gated matches; narrow with a more specific `query` or raise `size`.",
     );
   }
   if (hitCap) {
@@ -333,7 +348,7 @@ export async function checkExclusions(args: {
       source: EXCLUSIONS_SOURCE,
       keylessMode: true,
       returned: records.length,
-      totalAvailable: totalElements,
+      totalAvailable,
       truncated,
       pagination: {
         offset: page * size,

package/src/lda.ts

@@ -173,7 +173,7 @@ export type LdaSearchFilingsArgs = {
   lobbyistName?: string;
   filingYear?: string; // ^\d{4}$
   filingType?: string; // a short code (e.g. "Q1", "RR")
-  agency?: string; // → government_entity (the federal entity lobbied)
+  agency?: string; // NOT server-filterable on /filings/ (API silently ignores government_entity) — never sent upstream; reported in _meta.filtersDropped with a workaround note.
   issue?: string; // → filing_specific_lobbying_issues
   page?: number; // 1-based, default 1
   pageSize?: number; // 1..25, default 25
@@ -218,11 +218,22 @@ export async function searchFilings(
   setFilter("lobbyist_name", args.lobbyistName, "lobbyistName");
   setFilter("filing_year", args.filingYear, "filingYear");
   setFilter("filing_type", args.filingType, "filingType");
-  setFilter("government_entity", args.agency, "agency");
   setFilter("filing_specific_lobbying_issues", args.issue, "issue");
   params.set("page", String(page));
   params.set("page_size", String(pageSize));
 
+  // [filter honesty] `agency` maps to NO server-side filter on /filings/: the LDA
+  // API silently ignores `government_entity` (live-verified — adding it does NOT
+  // narrow `count`; government entities are nested per lobbying activity, not a
+  // top-level filter). So we NEVER send it (an ignored param buys nothing) and
+  // disclose it as DROPPED — reporting it as applied while returning the full
+  // corpus would be a silent-filter-drop lie (filtersApplied + totalAvailable
+  // overstated as if agency-scoped).
+  const filtersDropped: string[] = [];
+  if (args.agency !== undefined && args.agency !== "") {
+    filtersDropped.push("agency");
+  }
+
   const url = `https://${LDA_HOST}${LDA_FILINGS_PATH}?${params.toString()}`;
   // Belt-and-suspenders: the fixed host + strictly-built query leave nothing to
   // steer the authority; assert the built URL cannot have been moved off-host.
@@ -266,8 +277,8 @@ export async function searchFilings(
         kind: "invalid_input",
         retryable: false,
         message: apiMsg
-          ? `LDA rejected the request (HTTP 400): ${apiMsg}. Check the filter parameters (filingYear, filingType, agency, issue, …).`
-          : "LDA rejected the request (HTTP 400) — check the filter parameters (filingYear, filingType, agency, issue, …).",
+          ? `LDA rejected the request (HTTP 400): ${apiMsg}. Check the filter parameters (filingYear, filingType, issue, …).`
+          : "LDA rejected the request (HTTP 400) — check the filter parameters (filingYear, filingType, issue, …).",
         upstreamStatus: 400,
         upstreamEndpoint: LDA_FILINGS_LABEL,
       });
@@ -310,6 +321,11 @@ export async function searchFilings(
       `This is page ${page} (pageSize ${pageSize}) of ~${Math.ceil(totalAvailable / pageSize)} — pass page=${page + 1} for the next page.`,
     );
   }
+  if (filtersDropped.includes("agency")) {
+    notes.push(
+      "The `agency` filter was NOT applied: the keyless LDA /filings/ endpoint has no server-side government-entity filter (the API silently ignores it and returns the full corpus), so it is reported in filtersDropped rather than falsely narrowed — totalAvailable and filtersApplied reflect ONLY the filters actually applied. Government entities are nested per lobbying activity: each returned filing's lobbyingActivities[].governmentEntities lists them. To find lobbying that targeted a specific agency, narrow by registrantName/clientName/issue and inspect those nested governmentEntities.",
+    );
+  }
 
   return withMeta(
     { filings },
@@ -319,7 +335,7 @@ export async function searchFilings(
       returned,
       totalAvailable,
       filtersApplied,
-      filtersDropped: [],
+      filtersDropped,
       fieldsUnavailable: [],
       pagination: { offset, limit: pageSize, hasMore, nextOffset },
       notes,