@cliwant/mcp-sam-gov 1.10.0 → 1.12.0

package/src/bonfire.ts

@@ -153,7 +153,18 @@ async function getBonfireRss(org: string): Promise<string> {
       upstreamEndpoint: bonfireLabel(org),
     });
   }
-  return getText(url, { label: bonfireLabel(org), redirect: "error" });
+  // Single-fetch path (retry:false) so a redirect is classified as a NON-retryable
+  // schema_drift, NOT a retryable upstream_unavailable. A drifted seed slug whose
+  // Bonfire portal has moved returns a 3xx (live-observed 307 on sanantonio /
+  // kingcounty / rutgers); routed through fetchWithRetry it would masquerade as a
+  // transient outage ("retry in 30s") that never recovers. A 5xx/429/404/timeout
+  // still THROWS honestly on the single attempt (never a fake empty).
+  return getText(url, {
+    label: bonfireLabel(org),
+    redirect: "error",
+    retry: false,
+    redirectMessage: `Bonfire org ${JSON.stringify(org)} redirected off ${host} (an HTTP 3xx) — this seed slug's portal has moved or been retired, so the entry is drifted (retrying will not help). Re-discover the current slug via bonfire_list_organizations or probe {slug}.bonfirehub.com/opportunities/rss.`,
+  });
 }
 
 // ─── Tool 1: bonfire_list_organizations (curated seed directory) ──
@@ -218,7 +229,11 @@ export async function searchOpportunities(args: BonfireSearchArgs): Promise<Meta
     throw driftError(bonfireLabel(org), "Bonfire returned a non-RSS body at HTTP 200 — schema drift (expected an <rss><channel> feed).");
   }
 
-  const items = body.match(/<item>[\s\S]*?<\/item>/gi) ?? [];
+  // 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;

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/census-economic.ts

@@ -94,7 +94,12 @@ const GEOGRAPHIES = new Set(["us", "state", "county"]);
 // (no CENSUS_API_KEY was available at build time). See SUPPRESSED_NOTE.
 const CENSUS_SENTINEL_FLOOR = -100000000;
 
-const DEFAULT_YEAR = "2022"; // the latest confirmed CBP vintage (ADR-0047)
+// Latest PUBLISHED CBP vintage (live-verified 2026-07-20:
+// api.census.gov/data/2023/cbp/variables.json → 200; /data/2024 → 404). CBP is
+// released with a ~2-year lag and irregularly, so a dynamic "current year − N" is
+// unsafe (it would query an unpublished vintage) — this is a hard-coded latest;
+// bump it (and re-verify) when a newer /data/{year}/cbp appears. ADR-0047.
+const DEFAULT_YEAR = "2023";
 
 // ─── Honesty notes (ADR-0047 required set) ────────────────────────
 const KEY_REQUIRED_NOTE =
@@ -145,7 +150,7 @@ export type CensusBusinessPatternsArgs = {
   naics?: string;
   geography?: string; // us | state | county (default us)
   state?: string; // 2-digit FIPS (required for county; optional filter for state)
-  year?: string; // ^\d{4}$ (default 2022)
+  year?: string; // ^\d{4}$ (default 2023)
   limit?: number; // OPTIONAL client-side top-N slice (CBP has no server pagination)
 };
 
@@ -172,6 +177,7 @@ export async function businessPatterns(
 
   // ── Validate + default the inputs (belt-and-suspenders behind the server Zod;
   //    a DIRECT handler call bypasses Zod). ──
+  const yearWasDefaulted = args.year === undefined;
   const year = args.year ?? DEFAULT_YEAR;
   if (!YEAR_RE.test(year)) {
     throw new ToolErrorCarrier({
@@ -395,6 +401,11 @@ export async function businessPatterns(
     SUPPRESSED_NOTE,
     NO_PAGINATION_NOTE,
   ];
+  if (yearWasDefaulted) {
+    notes.push(
+      `No \`year\` was supplied, so it defaulted to ${DEFAULT_YEAR} — the latest PUBLISHED CBP vintage as of the last verification (CBP is released with a ~2-year lag). Pass an explicit \`year\` for a different vintage.`,
+    );
+  }
 
   let rows = allRows;
   if (

package/src/ckan.ts

@@ -441,7 +441,7 @@ export async function discoverDatasets(args: {
   params.set("rows", String(limit));
 
   const key = `ckan:package_search:${args.host}:${args.q}:${limit}`;
-  const { totalAvailable, results } = await memoize(
+  const { totalAvailable, results, packagesReturned } = await memoize(
     key,
     async () => {
       const body = await getCkanPackageSearch(args.host, params);
@@ -468,16 +468,31 @@ export async function discoverDatasets(args: {
       const total = num(b.result.count);
       const packages = Array.isArray(b.result.results) ? b.result.results : [];
       const rows = packages.flatMap(mapPackageResources);
-      return { totalAvailable: total, results: rows };
+      // packagesReturned = the number of DATASETS on this page. Truncation is a
+      // DATASET question (totalAvailable is a dataset count), NOT a resource-row
+      // one — the two units differ because a dataset can expose several resources.
+      return { totalAvailable: total, results: rows, packagesReturned: packages.length };
     },
     10 * 60 * 1000,
   );
 
   const returned = results.length;
+  // [truncation honesty] complete/truncated is a DATASET question — compare the
+  // DATASETS returned (packagesReturned) against the dataset total, NOT the
+  // per-resource row count (which can EXCEED the dataset total, e.g. 2 datasets →
+  // 14 resource rows vs count 10, and would spoof complete:true when only 2 of 10
+  // datasets were shown). This tool returns the first `limit` datasets and has no
+  // offset param, so nextOffset is null (raise `limit` to see more).
+  const hasMore = totalAvailable !== null && packagesReturned < totalAvailable;
   const notes: string[] = [
     `package_search over ${args.host} (rows=${limit}). Feed a datastoreActive:true result's resourceId to ckan_query; a datastoreActive:false resource is a raw file blob (CSV/PDF/…) NOT in the datastore and is NOT queryable.`,
-    "totalAvailable is the count of matching DATASETS (packages); the rows are per-RESOURCE (a dataset may expose several resources), so returned may differ from totalAvailable.",
+    "totalAvailable is the count of matching DATASETS (packages); the rows are per-RESOURCE (a dataset may expose several resources), so returned (resource rows) may differ from totalAvailable (datasets). complete/truncated tracks DATASETS shown vs matched.",
   ];
+  if (hasMore) {
+    notes.push(
+      `Only the first ${packagesReturned} of ${totalAvailable} matching datasets are shown (this tool returns the first \`limit\` datasets and does not page); raise \`limit\` to retrieve more.`,
+    );
+  }
 
   return withMeta(
     { host: args.host, query: args.q, results },
@@ -489,6 +504,7 @@ export async function discoverDatasets(args: {
       filtersApplied: ["q"],
       filtersDropped: [],
       fieldsUnavailable: [],
+      pagination: { offset: 0, limit, hasMore, nextOffset: null },
       notes,
     } satisfies Partial<ResponseMeta>,
   );

package/src/clinicaltrials.ts

@@ -543,19 +543,31 @@ export async function searchStudies(args: CtSearchArgs): Promise<MetaBundle> {
       "clinicaltrials shape drift — /studies response.studies must be an array.",
     );
   }
-  // countTotal=true was sent, so totalCount MUST be a finite number — its absence
-  // is drift, NEVER a silently-null total, NEVER studies.length (§Honesty #1).
-  if (typeof b.totalCount !== "number" || !Number.isFinite(b.totalCount)) {
+  // §Honesty #1: totalCount is returned ONLY on the FIRST page of a cursor sequence —
+  // ClinicalTrials.gov v2 OMITS it on every pageToken CONTINUATION, even with
+  // countTotal=true (live-verified: page 1 carries totalCount, every subsequent
+  // pageToken call omits it). So its absence is drift ONLY on the first page; on a
+  // continuation an absent total is EXPECTED (handled at the totalAvailable step below).
+  const isContinuation = args.pageToken !== undefined;
+
+  const studies = (b.studies as unknown[]).map((s) => mapStudy(s, false));
+  const returned = studies.length;
+  // First page: totalCount MUST be a finite number (typeof-checked BEFORE num() so a
+  // non-number can't silently parse; NEVER studies.length) — its absence is drift.
+  // Continuation page: totalCount is legitimately omitted ⇒ totalAvailable:null (the
+  // first page's total still describes the whole set; disclosed in a note).
+  let totalAvailable: number | null;
+  if (typeof b.totalCount === "number" && Number.isFinite(b.totalCount)) {
+    totalAvailable = num(b.totalCount) as number; // EXACT (genuine 0 → 0)
+  } else if (isContinuation) {
+    totalAvailable = null;
+  } else {
     throw driftError(
       CT_LABEL,
-      "clinicaltrials shape drift — /studies totalCount missing/non-number on a countTotal=true request (typeof-checked BEFORE num() so a non-number can't silently parse; NEVER fall back to studies.length).",
+      "clinicaltrials shape drift — /studies totalCount missing/non-number on a FIRST-page countTotal=true request (typeof-checked BEFORE num(); NEVER fall back to studies.length).",
     );
   }
 
-  const studies = (b.studies as unknown[]).map((s) => mapStudy(s, false));
-  const returned = studies.length;
-  const totalAvailable = num(b.totalCount) as number; // EXACT (genuine 0 → 0)
-
   // ── Opaque-cursor honesty (§Honesty #2). Terminal = token ABSENT. The token is
   //    surfaced VERBATIM (never fabricated/derived). Phantom-empty guard: 0
   //    studies WITH a token ⇒ terminal (never advertise a continuation into an
@@ -576,6 +588,11 @@ export async function searchStudies(args: CtSearchArgs): Promise<MetaBundle> {
   // ── Notes: the mandatory caveat + cursor + data-currency always; the
   //    conditional facet/tokenization disclosures; the unscoped recommendation. ──
   const notes: string[] = [CT_TRIAL_CAVEAT, CT_CURSOR_NOTE];
+  if (isContinuation && totalAvailable === null) {
+    notes.push(
+      "totalAvailable is null on this continuation page — ClinicalTrials.gov reports the study total ONLY on the first page of a cursor sequence (it is omitted on every pageToken continuation, even with countTotal=true). The total from the first page still describes the whole result set.",
+    );
+  }
   notes.push(...andNotes);
   // Emit the sponsor-broadening note ONLY for a SINGLE-token sponsor. For a
   // MULTI-token sponsor CT AND-split and NARROWED (the andNotes AND-note fired),

package/src/fdic.ts

@@ -523,7 +523,7 @@ export async function searchInstitutions(args: {
   const records = env.records.map(mapInstitution);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const filtersApplied: string[] = [];
@@ -618,7 +618,7 @@ export async function institutionFinancials(args: {
   const records = env.records.map(mapFinancials);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const notes: string[] = [freshnessNote(env.indexName, env.indexCreated), ASSET_NOTE];
@@ -862,7 +862,7 @@ export async function bankFailures(args: {
   const records = env.records.map(mapFailure);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const filtersApplied: string[] = [];
@@ -1184,7 +1184,7 @@ export async function institutionHistory(args: {
   const records = env.records.map(mapHistory);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const filtersApplied: string[] = [];
@@ -1524,7 +1524,7 @@ export async function industrySummary(args: {
   const records = env.records.map(mapSummary);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const filtersApplied: string[] = [];
@@ -1820,7 +1820,7 @@ export async function riskRatios(args: {
   const records = env.records.map(mapRiskRatios);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const filtersApplied: string[] = ["cert"];
@@ -2013,7 +2013,7 @@ export async function branchDeposits(args: {
   const records = env.records.map(mapBranchDeposit);
   const returned = records.length;
   const totalAvailable = env.totalAvailable;
-  const hasMore = offset + returned < totalAvailable;
+  const hasMore = returned > 0 && offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
   const filtersApplied: string[] = [];

package/src/fema.ts

@@ -407,8 +407,14 @@ function shapeResponse(args: {
 
   const rows = coerceAmounts(rawRows as FemaRow[], def.amountFields);
   const returned = rows.length;
+  // `returned > 0` guard (matches nvd/usaspending): an EMPTY page MUST terminate the
+  // walk. OpenFEMA's metadata.count can EXCEED the rows it will actually serve via
+  // $skip/$top (live: the ~822k-row public_assistance set stops serving rows well
+  // before its count), so without this guard a near-end offset yields returned:0 while
+  // offset < count ⇒ hasMore:true, nextOffset === offset — a non-advancing cursor an
+  // agent following nextOffset re-requests forever (empty page, re-scan, repeat).
   const hasMore =
-    totalAvailable !== null && args.offset + returned < totalAvailable;
+    returned > 0 && totalAvailable !== null && args.offset + returned < totalAvailable;
   const nextOffset = hasMore ? args.offset + returned : null;
 
   const notes: string[] = [SHAPE_NOTE];
@@ -421,6 +427,14 @@ function shapeResponse(args: {
       "This page returned fewer rows than the requested limit while more remain (OpenFEMA byte-truncates a wide page below $top); metadata.count is authoritative — page with a larger offset ($skip).",
     );
   }
+  // Phantom tail: OpenFEMA returned 0 rows though metadata.count is higher — its count
+  // can exceed the rows it will serve via pagination, so the walk is COMPLETE here even
+  // though returned:0 < count. Disclose it so the count is not read as a reachable target.
+  if (returned === 0 && totalAvailable !== null && args.offset > 0 && args.offset < totalAvailable) {
+    notes.push(
+      `OpenFEMA served 0 rows at offset ${args.offset} although metadata.count is ${totalAvailable} — its count can exceed the rows actually pageable via $skip/$top, so pagination is COMPLETE here (do not treat count as a reachable row target; narrow the filter for an exact set).`,
+    );
+  }
   // Deep-offset caveat on the ~800k PA set (ADR-0016 OQ2).
   if (args.offset > 100000) {
     notes.push(

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

@@ -45,13 +45,17 @@ export async function searchGrants(args: {
   oppStatuses?: GrantStatus[];
   rows?: number;
 }) {
+  // The tool ALWAYS sends oppStatuses — default forecasted|posted when the caller
+  // omits it — so it is ALWAYS an applied server-side filter (disclosed below).
+  const effOppStatuses = args.oppStatuses ?? ["forecasted", "posted"];
+  const statusDefaulted = args.oppStatuses == null;
   const body: Record<string, unknown> = {
     rows: args.rows ?? 10,
     keyword: args.keyword ?? "",
     cfda: args.cfda ?? "",
     agencies: args.agency ?? "",
     oppNum: args.oppNum ?? "",
-    oppStatuses: (args.oppStatuses ?? ["forecasted", "posted"]).join("|"),
+    oppStatuses: effOppStatuses.join("|"),
   };
   type Resp = {
     errorcode?: number;
@@ -135,11 +139,20 @@ export async function searchGrants(args: {
   if (args.cfda) sent.push("cfda");
   if (args.agency) sent.push("agency");
   if (args.oppNum) sent.push("oppNum");
-  if (args.oppStatuses?.length) sent.push("oppStatuses");
+  // oppStatuses is ALWAYS sent (default or caller-supplied), so ALWAYS disclose the
+  // EFFECTIVE set — omitting it when defaulted made totalAvailable (a status-filtered
+  // subset) read as unfiltered (live: keyword=cybersecurity → 235 forecasted|posted vs
+  // 2008 all-statuses, a 1773-record closed/archived bucket hidden).
+  sent.push(`oppStatuses(${effOppStatuses.join("|") || "all-statuses"})`);
   const notes: string[] = [];
+  if (statusDefaulted) {
+    notes.push(
+      "No oppStatuses supplied — DEFAULTED to forecasted|posted, so CLOSED and ARCHIVED opportunities are EXCLUDED from both the results AND totalAvailable (this total is the open/forecasted subset, not all statuses). To count or return every status, pass oppStatuses including 'closed'/'archived'.",
+    );
+  }
   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-csv.ts

@@ -57,10 +57,12 @@
 import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { once } from "node:events";
 import { pipeline } from "node:stream/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fetchWithRetry, ToolErrorCarrier } from "./errors.js";
+import { driftError } from "./datasource.js";
 import { withMeta } from "./meta.js";
 
 // ─── Source + config ─────────────────────────────────────────────
@@ -309,20 +311,34 @@ function fieldsFromRecord(rec: string[]): NoticeFields {
  * loads the whole file into memory — readline yields one physical line at a
  * time and the assembler holds at most one in-progress (quote-spanning) record.
  */
-async function buildIndexFromFile(
+export async function buildIndexFromFile(
   csvPath: string,
 ): Promise<{ notices: Record<string, NoticeFields>; rowCount: number }> {
   const notices: Record<string, NoticeFields> = Object.create(null);
   let headerSeen = false;
   let rowCount = 0;
 
-  const rl = createInterface({
-    input: createReadStream(csvPath, { encoding: "utf8" }),
-    crlfDelay: Infinity,
-  });
+  const stream = createReadStream(csvPath, { encoding: "utf8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
   const asm = makeRecordAssembler((rec) => {
     if (!headerSeen) {
       headerSeen = true; // first logical record is the 47-column header
+      // [P4] The column contract is POSITIONAL (fixed COL indices). If GSA
+      // reorders / inserts / renames a column, trusting the old positions would
+      // serve WRONG-POSITION data as authoritative (or, if NoticeId shifts, skip
+      // every row → a false "not in the current CSV snapshot"). Neither throws
+      // today. Assert the expected header NAME at each COL index before indexing
+      // any data row — a mismatch is schema drift, never a fake-empty (mirrors the
+      // census-economic.ts header guard). Each COL key IS its expected header name.
+      for (const [expectedName, idx] of Object.entries(COL)) {
+        const got = (rec[idx] ?? "").trim();
+        if (got !== expectedName) {
+          throw driftError(
+            "gsa:csv",
+            `GSA Contract-Opportunities CSV header drift — column ${idx} is ${JSON.stringify(got)}, expected ${JSON.stringify(expectedName)}. The positional column contract changed; refusing to index (a silent column shift would serve wrong-position data as authoritative, or skip every row as a false "not in the current snapshot").`,
+          );
+        }
+      }
       return;
     }
     rowCount++;
@@ -333,8 +349,23 @@ async function buildIndexFromFile(
     notices[noticeId.toLowerCase()] = fieldsFromRecord(rec);
   });
 
-  for await (const line of rl) asm.push(line);
-  asm.flush();
+  try {
+    for await (const line of rl) asm.push(line);
+    asm.flush();
+  } finally {
+    // Release the OS file handle on ALL exit paths (including the header-drift
+    // throw, which aborts mid-stream). destroy() is ASYNC — the fd is not freed
+    // until the 'close' event — so AWAIT it; otherwise a caller deleting the file
+    // immediately after (Windows holds a lock on an open read stream) hits
+    // ENOTEMPTY/EBUSY. On the normal EOF path the stream auto-destroys, so guard
+    // on `.destroyed` and set the listener BEFORE destroy() to catch its 'close'.
+    rl.close();
+    if (!stream.destroyed) {
+      const closed = once(stream, "close");
+      stream.destroy();
+      await closed.catch(() => {});
+    }
+  }
 
   return { notices, rowCount };
 }

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,