@cliwant/mcp-sam-gov 1.15.0 → 1.17.0

package/src/data-map.ts

@@ -41,6 +41,36 @@ export interface DataMapEntry {
  */
 export const DATA_MAP_ENTRIES: DataMapEntry[] = [
   // ── State-level ──────────────────────────────────────────────────────────
+  {
+    state: "CA",
+    jurisdiction: "California",
+    dataLabel: "DGS Purchase Order Data 2012–2015",
+    tool: "ckan_query",
+    keyArgs: "host=data.ca.gov, resourceId=bb82edc5-9c78-44e2-8947-68ece26197c5",
+    rows: 344504,
+    approximate: false,
+    notNote: "live Cal eProcure portal (WAF-403); FY2012–2015 only — no post-2015 rows",
+  },
+  {
+    state: "CA",
+    jurisdiction: "California",
+    dataLabel: "DGS-Approved Non-Competitive Bids",
+    tool: "ckan_query",
+    keyArgs: "host=data.ca.gov, resourceId=14932789-485b-481b-910a-dafb40d3471c",
+    rows: 480,
+    approximate: false,
+    notNote: "open competitive solicitations; sole-source/non-competitive award register",
+  },
+  {
+    state: "OK",
+    jurisdiction: "Oklahoma",
+    dataLabel: "Vendor Payments FY2019 Q1 (OMES)",
+    tool: "ckan_query",
+    keyArgs: "host=data.ok.gov, resourceId=cc443616-15eb-4a1f-8d87-93e5711ac43c",
+    rows: 286185,
+    approximate: false,
+    notNote: "bids or awards; vendor PAYMENTS — per-quarter resources, one fiscal year = 4 calls",
+  },
   {
     state: "VA",
     jurisdiction: "Virginia",
@@ -133,6 +163,18 @@ export const DATA_MAP_ENTRIES: DataMapEntry[] = [
     approximate: true,
     notNote: "an award register; only ~3 most-recent FYs, exact-match filters",
   },
+  // ── Alaska — verified 2026-09-21 ─────────────────────────────────────────
+  {
+    state: "AK",
+    jurisdiction: "Alaska",
+    dataLabel: "Open Checkbook vendor payments (FY2026 ONLY)",
+    tool: "open_checkbook_search",
+    keyArgs: "portal=ak, year=2026",
+    rows: 41751,
+    approximate: false,
+    notNote:
+      "historical FY coverage — ONLY FY2026 is published by this portal. FY2019–FY2025 return count:0, meaning 'not published', NOT 'no spending'. Probed years 2019–2026 and no-year on 2026-09-21: 2019–2025 = 0 rows each; 2026 = 41,751 rows ($1,179,091,896.12); no-year = 0 rows. Always pass year='2026' to get results.",
+  },
   {
     state: "IL",
     jurisdiction: "Illinois",
@@ -141,7 +183,7 @@ export const DATA_MAP_ENTRIES: DataMapEntry[] = [
     keyArgs: "domain=data.illinois.gov, datasetId=6rb8-ntpm",
     rows: 48,
     approximate: false,
-    notNote: "a comprehensive solicitation feed; only ~48 upcoming CDB capital bids",
+    notNote: "a comprehensive solicitation feed, and NOT currently open bids — these are ~48 CDB capital solicitations the publisher describes as \"anticipated for a future date, but have not been posted yet\" (estimated_bid_date field)",
   },
   {
     state: "IL",
@@ -270,6 +312,18 @@ export const DATA_MAP_ENTRIES: DataMapEntry[] = [
     notNote:
       "Colorado STATE procurement — this is City of Denver checkbook data hosted on the Colorado state portal (data.colorado.gov). An agent that reads the domain as the jurisdiction gets this wrong. Updated 2026-09-20.",
   },
+  // ── Fulton County GA (second portal) — verified 2026-09-21 ───────────────
+  {
+    state: "GA",
+    jurisdiction: "Fulton County GA",
+    dataLabel: "Vendor Payments 2014–present (sharefulton portal)",
+    tool: "socrata_query",
+    keyArgs: "domain=sharefulton.fultoncountyga.gov, datasetId=kp4p-scak",
+    rows: 226797,
+    approximate: false,
+    notNote:
+      "data.fultoncountyga.gov (a DIFFERENT host that is also allowlisted — both are official Fulton County portals). Fields: fiscal_year, fy_period, disb_date, dept, department_name, unit, unit_name, object, object_name, fund, fund_name, amount, vendor_code, vendor_legal_name. Updated 2026-09-14, attribution: 'Fulton County Government (GA)', 226,797 rows spanning 2014-01-01 to present.",
+  },
 ];
 
 /**
@@ -325,5 +379,8 @@ ${renderStateTableMarkdown()}
 - Login-gated or WAF-blocked live-bid portals: CA (Cal eProcure), TX ESBD/TxSmartBuy non-TxDOT (TxDOT lettings ARE available via qh8x-rm8r above), OH, NC, MI, and Periscope-based portals for IL/MA/NJ live bids.
 - Portal exists but carries no procurement datasets: PA (data.pa.gov is live; scoped catalog has 0 bid/vendor/procurement datasets matching). Michigan (data.michigan.gov) was checked 2026-09-21 and carries only NIGP commodity code reference tables (w3u3-uptp 9,333 rows; jv5q-yp8x 235 rows) — not procurement transactions.
 - No state-level open-data portal: FL (data.fl.gov NXDOMAIN), GA (data.georgia.gov NXDOMAIN). These states have no keyless state procurement data source — this is a measured absence, not a connectivity block.
+
+**City-level measured absences (portals exist but carry no procurement data):**
+- New Orleans LA (rank 46, 383,997 people): data.nola.gov exists but has NO procurement dataset. Full scan across 9 terms (procurement, solicitation, bid opportunities, vendor payments, purchase orders, contracts awarded, checkbook, supplier diversity, expenditure) on 2026-09-21 found only a 626-row DBE directory last updated 2019-11-11. Largest datasets are permits (347,839) and traffic citations (4M+) — not procurement. Use opengov_search_solicitations or bonfire_search_opportunities for New Orleans live bids.
 `;
 }

package/src/fpds.ts

@@ -48,9 +48,10 @@ const FPDS_HOST = "www.fpds.gov";
 const FPDS_PATH = "/ezsearch/FEEDS/ATOM";
 const FPDS_ORIGIN_PATH = `https://${FPDS_HOST}${FPDS_PATH}`;
 const FPDS_LABEL = "www.fpds.gov";
-// WAF-friendly browser-ish UA (mirrors gao.ts convention).
+// Identify this client honestly — same string used by every other module in the
+// project. Live-verified 2026-09-22: FPDS returns 200 to this UA and with no UA.
 const FPDS_UA =
-  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+  "Mozilla/5.0 (compatible; @cliwant/mcp-sam-gov; +https://github.com/cliwant/mcp-sam-gov)";
 
 const PAGE_SIZE = 10;
 /** Hard cap on entries sliced per feed (page size is 10; anything past a small

package/src/gao.ts

@@ -42,11 +42,12 @@ import { withMeta } from "./meta.js";
 
 // ─── Shared HTTP ─────────────────────────────────────────────────
 
-// GAO's edge (Cloudflare/WAF) will 403 a bare client — always send a realistic
-// browser User-Agent. Mirror the shape the rest of the server uses for GAO-ish
-// public HTML/RSS scraping so behavior is consistent.
+// Identify this client honestly — same string used by every other module in the
+// project. Live-verified 2026-09-22: GAO's RSS feed returns 200 to this UA, to
+// the formerly-used fake Chrome UA, and even with no UA at all. GAO per-decision
+// pages 403 from Akamai regardless of UA, so spoofing a browser gains nothing.
 const GAO_UA =
-  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+  "Mozilla/5.0 (compatible; @cliwant/mcp-sam-gov; +https://github.com/cliwant/mcp-sam-gov)";
 
 const RSS_URL = "https://www.gao.gov/rss/reportslegal.xml";
 const PRODUCT_BASE = "https://www.gao.gov/products/";
@@ -58,9 +59,9 @@ const SOURCE = "gao.gov Legal Products RSS + decision pages (keyless)";
  * in `data` and inside `_meta.notes` so no consumer can miss the scope boundary.
  */
 const ACCESS_NOTE =
-  "Keyless GAO access covers only RECENT decisions from the public Legal-Products RSS feed (a rolling ~25-item window). GAO's faceted historical protest search (by protester/agency/outcome/date across all years) is WAF-blocked to automated clients and available only via a paid third-party API. Do NOT treat these results as the complete protest history.";
+  "Keyless GAO access covers only RECENT decisions from the public Legal-Products RSS feed (a rolling ~25-item window). GAO's faceted historical protest search (by protester/agency/outcome/date across all years) is WAF-blocked to automated clients — keyless programmatic access is unavailable (a human can search at https://www.gao.gov/search). Do NOT treat these results as the complete protest history.";
 
-// Thin LOCAL wrapper (ADR-0013) that injects GAO's WAF-friendly UA + RSS Accept
+// Thin LOCAL wrapper (ADR-0013) that injects the project's honest UA + RSS Accept
 // for the tool's two call sites, then delegates to the shared `getText` port
 // (retry defaults true → fetchWithRetry, byte-identical to the former
 // hand-rolled fetcher). `timeoutMs` is preserved as a param default (never
@@ -710,6 +711,19 @@ export async function gaoProtestLookup(args: {
     );
   }
 
+  // When a protester/agency/solicitationNumber filter was given and the window
+  // contains no matching decisions, give the caller a precise next step: GAO's
+  // own search pre-filtered to bid-protest decisions with the term filled in.
+  // (This is NOT a reading list — it is a single direct link to the full
+  // historical database that a human can open immediately.)
+  const searchTerm = (args.protester ?? args.agency ?? args.solicitationNumber)?.trim();
+  if (decisions.length === 0 && filtersApplied.length > 0 && searchTerm) {
+    const encoded = encodeURIComponent(searchTerm);
+    notes.push(
+      `"${searchTerm}" does not appear in the current ~25-decision window. GAO's full protest database is searchable at https://www.gao.gov/search?f%5B0%5D=ctype_search%3ABid%20Protest%20Decision&keyword=${encoded} — each result shows parties, agency, date and outcome. Keyless programmatic access to the historical archive is unavailable; the link above goes directly to the relevant results.`,
+    );
+  }
+
   return withMeta(
     { accessNote: ACCESS_NOTE, decisions },
     {

package/src/gsa-perdiem.ts

@@ -93,6 +93,10 @@ const STANDARD_RATE_NOTE =
   "standardRate:true means this location falls under the CONUS STANDARD rate (not an individually-set non-standard rate). standardRate/isOconus are booleans coerced from the API's string 'true'/'false'.";
 const NO_PAGINATION_NOTE =
   "The per-diem API returns the COMPLETE rate set for the lookup (no pagination); totalAvailable equals the number of rows returned.";
+const FISCAL_YEAR_NOTE =
+  "fiscalYear (= year) is the U.S. FEDERAL FISCAL YEAR (Oct 1–Sep 30). " +
+  "Example: October 2026 falls in FY2027 (FY runs Oct 2026–Sep 2027); September 2026 falls in FY2026. " +
+  "To look up October 2026 rates, pass year='2027'. To look up September 2026 rates, pass year='2026'.";
 
 // ─── STRING-boolean coercion (null-never-fabricate) ───────────────
 /** Coerce the API's string 'true'/'false' → a real boolean; anything else ⇒ null. */
@@ -119,6 +123,11 @@ export type PerdiemRate = {
   state: string | null;
   zip: string | null;
   year: number | null;
+  /** Explicit U.S. federal fiscal year label (Oct 1–Sep 30). Same numeric value as
+   * `year` (the GSA API's year field IS the FY number). Surfaced as a separate named
+   * field so callers never confuse it with a calendar year. E.g. fiscalYear:2027 means
+   * rates run Oct 2026–Sep 2027; October 2026 travel uses FY2027 rates. */
+  fiscalYear: number | null;
   isOconus: boolean | null; // OCONUS (outside-CONUS) flag — coerced from string boolean
   standardRate: boolean | null; // CONUS standard-rate flag — coerced from string boolean
   mealsUsd: number | null; // M&IE ceiling ($) — null-never-0
@@ -350,6 +359,8 @@ export async function perdiemRates(
         state: gState,
         zip: str(r.zip),
         year: gYear,
+        fiscalYear: gYear, // same numeric value as year; surfaced separately so callers
+                           // never confuse it with a calendar year (GSA year IS the FY)
         isOconus: gOconus,
         standardRate: strBool(r.standardRate),
         mealsUsd: num(r.meals),
@@ -359,7 +370,7 @@ export async function perdiemRates(
   }
 
   const returned = rows.length;
-  const notes: string[] = [RATE_MEANING_NOTE, STANDARD_RATE_NOTE, NO_PAGINATION_NOTE];
+  const notes: string[] = [RATE_MEANING_NOTE, STANDARD_RATE_NOTE, NO_PAGINATION_NOTE, FISCAL_YEAR_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.`,

package/src/keys.ts

@@ -159,6 +159,7 @@ export const KEY_REGISTRY: readonly KeyRegistryEntry[] = [
     envVar: "COURTLISTENER_API_TOKEN",
     sources: [
       "CourtListener federal court opinions (courtlistener_search_opinions)",
+      "CourtListener RECAP dockets (courtlistener_search_dockets)",
     ],
     required: false,
     signupUrl: "https://www.courtlistener.com/help/api/rest/",

package/src/open-checkbook.ts

@@ -41,14 +41,37 @@ import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
 
 export { num };
 
-// ─── Curated portal allowlist (SSRF core) — LIVE-VERIFIED 2026-07-24 ──
-export type OpenCheckbookPortal = { key: string; host: string; label: string; note: string };
+// ─── Curated portal allowlist (SSRF core) — LIVE-VERIFIED 2026-07-24/2026-09-21 ──
+export type OpenCheckbookPortal = {
+  key: string;
+  host: string;
+  label: string;
+  note: string;
+  /**
+   * What fiscal-year span this portal actually publishes, as MEASURED (not assumed).
+   * Portals differ: SD exposes roughly the three most recent FYs, AK exposes exactly
+   * one. Emitting a single hardcoded coverage sentence for both made the envelope
+   * contradict itself — the generic line claimed "~3 most-recent fiscal years" while
+   * the AK portal note in the same response said FY2026 only.
+   */
+  coverageNote: string;
+};
 export const OPEN_CHECKBOOK_PORTALS: readonly OpenCheckbookPortal[] = [
   {
     key: "sd",
     host: "southdakota.spending.socrata.com",
     label: "South Dakota — Open Checkbook",
     note: "State of South Dakota vendor-payment checkbook (row fields: expense_category, description, fund, payment_date, vendor, org1=department, amount, custom_checkbook_field7=invoice ref, payment_id). ~740,980 rows / ~$8.41B across the ~3 most-recent fiscal years (NOT full history). The underlying Socrata SODA dataset is login-gated; this public app-proxy is the keyless door.",
+    coverageNote:
+      "COVERAGE: this portal exposes only the ~3 most-recent fiscal years — NOT South Dakota's full payment history.",
+  },
+  {
+    key: "ak",
+    host: "checkbook.alaska.gov",
+    label: "Alaska — Open Checkbook",
+    note: "State of Alaska vendor-payment checkbook (official .gov CNAME to alaska-state.spending.socrata.com). Verified live 2026-09-21: 41,751 rows / $1,179,091,896.12 for FY2026. ★ FY COVERAGE CAVEAT: ONLY FY2026 is published by this portal — years 2019–2025 and no-year all return count:0 / empty data. A count:0 result for a non-2026 year means 'this portal does not publish that year', NOT 'Alaska spent nothing'. Do NOT interpret zero results for FY2019–FY2025 as an absence of spending.",
+    coverageNote:
+      "COVERAGE: this portal publishes ONLY FY2026 (measured 2026-09-21: FY2019-FY2025 and an omitted year each return count:0). A count:0 for any other year means the portal does not publish that year — it does NOT mean Alaska made no payments.",
   },
 ] as const;
 
@@ -160,7 +183,7 @@ export async function openCheckbookSearch(args: OpenCheckbookSearchArgs): Promis
     `Source: ${portal.label} (Socrata Open Expenditures app-proxy /api/checkbook_data.json, keyless). ${portal.note}`,
     "totalAvailable = the API's exact match count (matches the product's totals.json), NOT the page length.",
     "Filters (year/vendor/org/expenseCategory) are EXACT-match — a partial/misspelled value returns an honest count:0, not an error. amount is number|null (a real $0 is 0, an absent value is null, never a fabricated 0).",
-    "COVERAGE: only the ~3 most-recent fiscal years are exposed by this product — this is NOT the state's full payment history.",
+    portal.coverageNote,
     "FRESHNESS is set by the publisher: the portal says it refreshes each payment cycle, but refreshes can lag by weeks. To check recency, sort by payment_date (sortBy='payment_date', sortOrder='desc') and read the newest date.",
   ];
   if (servedOffset !== offset)

package/src/pricing.ts

@@ -164,10 +164,26 @@ function epochToIso(v: number | string | undefined): string | null {
   return null;
 }
 
+// Maximum pages to scan when a client-side filter (county / constructionType)
+// requires a full-state sweep.  10 pages × 50 rows = 500 WDs — well above any
+// real state's active DBA stock (IL has 70 as of 2026-09-22).
+const WD_SCAN_PAGE_CAP = 10;
+const WD_SCAN_SIZE = 50; // max the SGS API accepts per request
+
+/** Extract constructionTypes as a lowercase string array (handles string[] or unknown). */
+function resultConstructionTypes(r: SgsResult): string[] {
+  const ct = r.constructionTypes;
+  if (!ct) return [];
+  if (Array.isArray(ct)) return ct.map((v) => String(v).toLowerCase());
+  if (typeof ct === "string") return [ct.toLowerCase()];
+  return [];
+}
+
 export async function searchWageDeterminations(args: {
   coverage: string;
   state?: string;
   county?: string;
+  constructionType?: string;
   query?: string;
   activeOnly?: boolean;
   standardOnly?: boolean;
@@ -181,35 +197,47 @@ export async function searchWageDeterminations(args: {
   const page = Math.max(0, Math.floor(args.page ?? 0));
   const stateFilter = args.state?.trim().toUpperCase() || undefined;
   const countyFilter = args.county?.trim().toLowerCase() || undefined;
+  const ctFilter = args.constructionType?.trim().toLowerCase() || undefined;
+
+  // When county or constructionType is given, we must scan ALL pages for the
+  // state to avoid missing matching WDs (e.g. IL has 70 DBA WDs — the target
+  // Cook County Building WD is on page 1).  We use max size=50 per fetch and
+  // cap at WD_SCAN_PAGE_CAP pages to keep the request count bounded.
+  const needsFullScan = Boolean(countyFilter || ctFilter);
 
-  const params = new URLSearchParams({
-    index,
-    size: String(limit),
-    page: String(page),
-    mode: "search",
-    sort: "-modifiedDate",
-  });
-  if (activeOnly) params.set("is_active", "true");
-  if (standardOnly) params.set("is_standard", "true");
-  // `q` matches WD number/title ONLY (NOT occupation) — verified q=guard→0.
-  if (args.query) params.set("q", args.query);
-  // `state` IS honored server-side (LIVE-VERIFIED 2026-07-03: index=sca&state=VA
-  // → 30 vs 1028 unfiltered, and every returned WD's location contains VA;
-  // state=ZZ → 0). It wants the 2-letter USPS code (a full name like "Virginia"
-  // → 0). This CORRECTS the earlier brief which assumed state was ignored.
   const filtersApplied: string[] = [`coverage(${index})`];
   const filtersDropped: string[] = [];
   const notes: string[] = [];
   if (activeOnly) filtersApplied.push("activeOnly");
   if (standardOnly) filtersApplied.push("standardOnly");
   if (args.query) filtersApplied.push("query(WD number/title only)");
+
+  // Build the base URLSearchParams that are shared across every page fetch.
+  function buildParams(pg: number, sz: number): URLSearchParams {
+    const p = new URLSearchParams({
+      index,
+      size: String(sz),
+      page: String(pg),
+      mode: "search",
+      sort: "-modifiedDate",
+    });
+    if (activeOnly) p.set("is_active", "true");
+    if (standardOnly) p.set("is_standard", "true");
+    // `q` matches WD number/title ONLY (NOT occupation) — verified q=guard→0.
+    if (args.query) p.set("q", args.query);
+    return p;
+  }
+
+  // `state` IS honored server-side (LIVE-VERIFIED 2026-07-03: index=sca&state=VA
+  // → 30 vs 1028 unfiltered, and every returned WD's location contains VA;
+  // state=ZZ → 0). It wants the 2-letter USPS code (a full name like "Virginia"
+  // → 0). This CORRECTS the earlier brief which assumed state was ignored.
+  const needsClientState =
+    stateFilter !== undefined && !/^[A-Z]{2}$/.test(stateFilter);
   if (stateFilter) {
-    if (/^[A-Z]{2}$/.test(stateFilter)) {
-      params.set("state", stateFilter);
+    if (!needsClientState) {
       filtersApplied.push("state(server-side)");
     } else {
-      // Not a 2-letter code → the server would return 0; apply client-side
-      // instead so a full name still works, and disclose it.
       filtersDropped.push("state(server-side; not a 2-letter code)");
       notes.push(
         `The state value '${args.state}' is not a 2-letter USPS code; the SGS 'state' param only matches 2-letter codes (a full name returns 0), so it was applied CLIENT-SIDE over the fetched page instead. Pass a 2-letter code (e.g. 'VA') for a precise server-side filter.`,
@@ -217,30 +245,75 @@ export async function searchWageDeterminations(args: {
     }
   }
 
-  const url = `${SGS_BASE}?${params.toString()}`;
-  const json = await getJson<SgsSearchResp>(url, SAM_HAL_HEADERS, `sam:sgs:${index}`);
-  const rawResults = json._embedded?.results ?? [];
-  const serverTotal = json.page?.totalElements ?? null;
+  // ── Fetch: one page (no client filters) OR full-state scan ──────
+  let allRaw: SgsResult[];
+  let serverTotal: number | null;
+  let scanCapHit = false;
+
+  if (!needsFullScan) {
+    // Original single-page path (no county/constructionType filter).
+    const params = buildParams(page, limit);
+    if (!needsClientState && stateFilter) params.set("state", stateFilter);
+    const url = `${SGS_BASE}?${params.toString()}`;
+    const json = await getJson<SgsSearchResp>(url, SAM_HAL_HEADERS, `sam:sgs:${index}`);
+    allRaw = json._embedded?.results ?? [];
+    serverTotal = json.page?.totalElements ?? null;
+  } else {
+    // Full-state scan: fetch all pages with size=50 until exhausted or cap.
+    const scanParams = buildParams(0, WD_SCAN_SIZE);
+    if (!needsClientState && stateFilter) scanParams.set("state", stateFilter);
+    const firstUrl = `${SGS_BASE}?${scanParams.toString()}`;
+    const firstJson = await getJson<SgsSearchResp>(firstUrl, SAM_HAL_HEADERS, `sam:sgs:${index}`);
+    allRaw = firstJson._embedded?.results ?? [];
+    serverTotal = firstJson.page?.totalElements ?? null;
+    const totalPages = firstJson.page?.totalPages ?? 1;
+
+    const pagesToFetch = Math.min(totalPages, WD_SCAN_PAGE_CAP);
+    if (totalPages > WD_SCAN_PAGE_CAP) scanCapHit = true;
+
+    for (let pg = 1; pg < pagesToFetch; pg++) {
+      const p = buildParams(pg, WD_SCAN_SIZE);
+      if (!needsClientState && stateFilter) p.set("state", stateFilter);
+      const pgJson = await getJson<SgsSearchResp>(
+        `${SGS_BASE}?${p.toString()}`,
+        SAM_HAL_HEADERS,
+        `sam:sgs:${index}`,
+      );
+      allRaw = allRaw.concat(pgJson._embedded?.results ?? []);
+    }
+  }
 
-  // Client-side filtering: county is NOT a documented SGS server param, so it
-  // is applied here over the fetched page. A non-2-letter state also lands here.
-  const needsClientState = filtersDropped.some((f) => f.startsWith("state"));
-  let filtered = rawResults;
+  // ── Client-side filtering ────────────────────────────────────────
+  let filtered = allRaw;
   if (needsClientState && stateFilter) {
     filtered = filtered.filter((r) =>
-      resultStateCodes(r).some((c) => c === stateFilter || r.location?.state?.name?.toUpperCase() === stateFilter),
+      resultStateCodes(r).some(
+        (c) => c === stateFilter || r.location?.state?.name?.toUpperCase() === stateFilter,
+      ),
     );
   }
   if (countyFilter) {
-    filtersApplied.push("county(client-side)");
+    filtersApplied.push("county(client-side, full-state scan)");
     filtered = filtered.filter((r) =>
       resultCounties(r).some((c) => c.name.toLowerCase().includes(countyFilter)),
     );
-    notes.push(
-      "County is filtered CLIENT-SIDE over the fetched page only (the SGS API has no county filter). A county filter combined with a small limit can miss WDs on later pages — raise `limit` or narrow by `state` (server-side) to be sure.",
+  }
+  if (ctFilter) {
+    filtersApplied.push(`constructionType(client-side, value=${args.constructionType})`);
+    filtered = filtered.filter((r) =>
+      resultConstructionTypes(r).includes(ctFilter),
     );
   }
 
+  // ── Specificity ranking: single-county WDs before multi-county ──
+  if (countyFilter) {
+    filtered.sort((a, b) => {
+      const aCount = resultCounties(a).length;
+      const bCount = resultCounties(b).length;
+      return aCount - bCount; // 1-county first, then 2-county, etc.
+    });
+  }
+
   const determinations = filtered.map((r) => {
     const coverageCode = r.type?.code ?? (index === "sca" ? "SCA" : "DBA");
     return {
@@ -273,27 +346,48 @@ export async function searchWageDeterminations(args: {
     "The `q` parameter matches the WD number/title only — it does NOT search by occupation or job title (e.g. q=guard returns 0). To find rates for a specific occupation, open the WD and read its rate table.",
   );
 
-  // totalAvailable: the server total is REAL for the coverage/active/standard/
-  // query/state filters (state is server-side). But when we additionally filter
-  // client-side (county, or a non-code state), the returned page count no longer
-  // reflects a full server total for THAT combined filter → null it out and say so.
-  const clientFiltered = Boolean(countyFilter) || needsClientState;
-  const totalAvailable = clientFiltered ? null : serverTotal;
+  // ── Honest meta ──────────────────────────────────────────────────
+  const clientFiltered = Boolean(countyFilter) || Boolean(ctFilter) || needsClientState;
+  const scannedCount = allRaw.length;
   const returned = determinations.length;
-  const truncated = clientFiltered
-    ? true // page-bounded client filter → can't prove completeness
-    : serverTotal !== null && page * limit + returned < serverTotal;
 
-  if (clientFiltered) {
+  // When we did a full-state scan, totalAvailable is the REAL count of matching
+  // WDs across the scanned pages (not null).  Only null it when the scan cap was
+  // hit (we didn't see all pages) or when there was no client filter.
+  let totalAvailable: number | null;
+  let truncated: boolean;
+
+  if (!clientFiltered) {
+    // No client filter: server total is accurate for this result set.
+    totalAvailable = serverTotal;
+    truncated = serverTotal !== null && page * limit + returned < serverTotal;
+  } else if (needsFullScan && !scanCapHit) {
+    // Full scan completed: real match count is known.
+    totalAvailable = returned;
+    truncated = false;
+  } else {
+    // Scan cap hit or no full scan (shouldn't happen but be safe).
+    totalAvailable = null;
+    truncated = true;
+  }
+
+  if (needsFullScan) {
+    const stateLabel = stateFilter ?? "all states";
+    const capNote = scanCapHit
+      ? ` (scan cap of ${WD_SCAN_PAGE_CAP * WD_SCAN_SIZE} WDs reached — some WDs may have been missed)`
+      : "";
     notes.push(
-      "totalAvailable is null because a client-side filter (county and/or a non-code state) was applied over just the fetched page — the true match count for the combined filter is unknown. The server-side total for the coverage/state/active filters was " +
-        (serverTotal ?? "unknown") +
-        ".",
+      `Scanned ${scannedCount} of ${serverTotal ?? scannedCount} ${stateLabel} ${index.toUpperCase()} WDs across all pages${capNote}. ` +
+        (countyFilter ? `County filter applied across all scanned WDs. ` : "") +
+        (ctFilter ? `constructionType filter (${args.constructionType}) applied. ` : "") +
+        (countyFilter
+          ? "Single-county WDs ranked first — they are almost always the most specific match for a given locality. "
+          : ""),
     );
   }
 
   return withMeta(
-    { determinations, coverageIndex: index, page, limit },
+    { determinations, coverageIndex: index, page: needsFullScan ? 0 : page, limit: needsFullScan ? returned : limit },
     {
       source: WD_SEARCH_SOURCE,
       keylessMode: true,
@@ -301,9 +395,9 @@ export async function searchWageDeterminations(args: {
       totalAvailable,
       truncated,
       pagination: {
-        offset: page * limit,
-        limit,
-        nextOffset: truncated ? (page + 1) * limit : null,
+        offset: 0,
+        limit: needsFullScan ? returned : limit,
+        nextOffset: truncated && !needsFullScan ? (page + 1) * limit : null,
         hasMore: truncated,
       },
       filtersApplied,