@cliwant/mcp-sam-gov 1.14.0 → 1.16.0

package/src/data-map.ts

@@ -0,0 +1,386 @@
+/**
+ * State & local data map — single source of truth.
+ *
+ * These entries are exported for:
+ *   (a) the MCP resource samgov://data-map/state-local (resources/read)
+ *   (b) consistency tests (SKILL.md table must agree on domain/id/rows)
+ *
+ * Keep verified row counts and notes current here only; SKILL.md table and
+ * the resource content are generated from this array.
+ */
+
+export type DataMapTool =
+  | "socrata_query"
+  | "ckan_query"
+  | "tableau_view_csv"
+  | "open_checkbook_search";
+
+export interface DataMapEntry {
+  /** Two-letter state abbreviation for grouping */
+  state: string;
+  /** Human-readable jurisdiction name */
+  jurisdiction: string;
+  /** Short description of what the dataset contains */
+  dataLabel: string;
+  /** Tool to call */
+  tool: DataMapTool;
+  /** Key args to pass — human-readable form for doc */
+  keyArgs: string;
+  /** Verified approximate row count (null = not precisely known) */
+  rows: number | null;
+  /** Approximate flag — when true prefix rows with '~' */
+  approximate: boolean;
+  /** What this dataset is NOT (common agent error) */
+  notNote: string;
+  /** Extra notes (optional) */
+  extra?: string;
+}
+
+/**
+ * Verified 2026-09-21 — all keyless.
+ */
+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",
+    dataLabel: "eVA PO line items 2023",
+    tool: "ckan_query",
+    keyArgs: "host=data.virginia.gov, resourceId=3c7f1bde-35b0-4fbf-b89c-978a19124d53",
+    rows: 1693227,
+    approximate: false,
+    notNote: "the live eVA portal (login-gated)",
+    extra:
+      "Years 2016–2026 have separate resourceIds; ckan_discover_datasets host=data.virginia.gov q=eVA procurement lists them (2024=25a59527, 2025=b8dc22a8, 2026=76f6831d)",
+  },
+  {
+    state: "MA",
+    jurisdiction: "Massachusetts",
+    dataLabel: "Comptroller vendor payments (CTHRU)",
+    tool: "socrata_query",
+    keyArgs: "domain=cthru.data.socrata.com, datasetId=pegc-naaa",
+    rows: 49000000,
+    approximate: true,
+    notNote: "an award or bid register; these are payment transactions",
+  },
+  {
+    state: "NJ",
+    jurisdiction: "New Jersey",
+    dataLabel: "YourMoney agency purchasing by vendor",
+    tool: "socrata_query",
+    keyArgs: "domain=data.nj.gov, datasetId=ubnu-tqu7",
+    rows: 660425,
+    approximate: false,
+    notNote: "a solicitation or bid register; agency expenditure rows",
+  },
+  {
+    state: "NY",
+    jurisdiction: "New York",
+    dataLabel: "State authority procurement contracts",
+    tool: "socrata_query",
+    keyArgs: "domain=data.ny.gov, datasetId=ehig-g5x3",
+    rows: 275763,
+    approximate: false,
+    notNote: "all NYS agencies (authorities only) and NOT active solicitations",
+  },
+  {
+    state: "NY",
+    jurisdiction: "New York",
+    dataLabel: "MTA procurement contracts",
+    tool: "socrata_query",
+    keyArgs: "domain=data.ny.gov, datasetId=twsw-2mqa",
+    rows: 107503,
+    approximate: false,
+    notNote: "a live MTA bid portal; MTA historical contract records",
+  },
+  {
+    state: "WA",
+    jurisdiction: "Washington",
+    dataLabel: "Agency contract register",
+    tool: "socrata_query",
+    keyArgs: "domain=data.wa.gov, datasetId=s8d5-pj78",
+    rows: 79329,
+    approximate: false,
+    notNote: "a solicitation or bid feed; awarded contract records",
+  },
+  {
+    state: "WA",
+    jurisdiction: "Washington",
+    dataLabel: "Master-contract sales by vendor/customer",
+    tool: "socrata_query",
+    keyArgs: "domain=data.wa.gov, datasetId=n8q6-4twj",
+    rows: 245831,
+    approximate: false,
+    notNote: "open bids; sales reported off statewide master contracts",
+  },
+  {
+    state: "MT",
+    jurisdiction: "Montana",
+    dataLabel: "DOA contracts awarded",
+    tool: "tableau_view_csv",
+    keyArgs: "view=mt_contracts_awarded",
+    rows: 4554,
+    approximate: true,
+    notNote: "a bid portal; awarded records only, freshness set by publisher",
+  },
+  {
+    state: "SD",
+    jurisdiction: "South Dakota",
+    dataLabel: "Open Checkbook vendor payments",
+    tool: "open_checkbook_search",
+    keyArgs: "portal=sd",
+    rows: 741000,
+    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",
+    dataLabel: "CDB capital project future bids",
+    tool: "socrata_query",
+    keyArgs: "domain=data.illinois.gov, datasetId=6rb8-ntpm",
+    rows: 48,
+    approximate: false,
+    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",
+    jurisdiction: "Illinois",
+    dataLabel: "IDHR certified eligible bidders",
+    tool: "socrata_query",
+    keyArgs: "domain=data.illinois.gov, datasetId=w8h2-q8hu",
+    rows: 7848,
+    approximate: false,
+    notNote: "a bid or award register; vendor-eligibility directory only",
+  },
+  // ── Texas — verified 2026-09-21 ──────────────────────────────────────────
+  {
+    state: "TX",
+    jurisdiction: "Texas",
+    dataLabel: "TxDOT current lettings (★live bid-line items)",
+    tool: "socrata_query",
+    keyArgs: "domain=data.texas.gov, datasetId=qh8x-rm8r",
+    rows: 8861,
+    approximate: false,
+    notNote:
+      "rows are bid LINE ITEMS not projects (8,861 rows = 412 distinct project_ids — report project count not row count); TxDOT highway lettings ONLY, not all Texas procurement; rolling window only (past lettings dropped, cannot answer historical questions); ESBD/TxSmartBuy non-TxDOT solicitations are absent",
+    extra:
+      "★First live state solicitation feed in this map. Use $select=count(distinct project_id) for open-bid count.",
+  },
+  {
+    state: "TX",
+    jurisdiction: "Texas",
+    dataLabel: "DIR Cooperative Contract Sales FY2010–FY2025 (archive)",
+    tool: "socrata_query",
+    keyArgs: "domain=data.texas.gov, datasetId=w64c-ndf7",
+    rows: 10749743,
+    approximate: false,
+    notNote: "bids or awards; purchase line items off DIR cooperative contracts (historical)",
+  },
+  {
+    state: "TX",
+    jurisdiction: "Texas",
+    dataLabel: "DIR Cooperative & Tele Contract Sales FY2026",
+    tool: "socrata_query",
+    keyArgs: "domain=data.texas.gov, datasetId=a743-wj72",
+    rows: 2077855,
+    approximate: false,
+    notNote: "historical FY2026 purchase lines (same shape as w64c-ndf7); not bids",
+  },
+  {
+    state: "TX",
+    jurisdiction: "Texas",
+    dataLabel: "DIR Current Active Cooperative Contracts",
+    tool: "socrata_query",
+    keyArgs: "domain=data.texas.gov, datasetId=vipt-h4ye",
+    rows: 5167,
+    approximate: false,
+    notNote: "a solicitation feed; active cooperative contract register (not TxDOT lettings)",
+  },
+  {
+    state: "TX",
+    jurisdiction: "Texas",
+    dataLabel: "TCEQ Current Contracts & Purchase Orders",
+    tool: "socrata_query",
+    keyArgs: "domain=data.texas.gov, datasetId=svjm-sdfz",
+    rows: 2067,
+    approximate: false,
+    notNote: "statewide; one agency (TCEQ) only",
+  },
+  // ── Maryland — verified 2026-09-21 ───────────────────────────────────────
+  {
+    state: "MD",
+    jurisdiction: "Maryland",
+    dataLabel: "eMaryland Marketplace (eMMA) bids — FY2018 exemplar",
+    tool: "socrata_query",
+    keyArgs: "domain=opendata.maryland.gov, datasetId=pgna-cxjh",
+    rows: 107303,
+    approximate: false,
+    notNote:
+      "rows are bid LINE ITEMS not bids — FY2018 is 107,303 rows for only 3,067 bids (35× overcount); always use $select=count(distinct bid_number) for actual bid count. Coverage stops at FY2019 — eMMA migrated to Periscope mid-FY2019; there is no FY2020+ mirror and this dataset cannot answer questions about current Maryland bids",
+    extra:
+      "All six FY datasetIds: FY2018=pgna-cxjh (107,303 rows/3,067 bids), FY2017=qkjf-rv4t (64,331/4,943), FY2016=7ang-84wj (45,204/4,818), FY2015=3hzs-sazv (46,895/4,898), FY2014=itax-4ccz (45,551/4,884), FY2019=ttg5-zfzj (4,623/388 — small because eMMA migrated to Periscope mid-year; first row is a sparse placeholder, subsequent rows are complete).",
+  },
+  // ── Oregon — verified 2026-09-21 ─────────────────────────────────────────
+  {
+    state: "OR",
+    jurisdiction: "Oregon",
+    dataLabel: "OregonBuys Purchases and Contracts FY2022–FY2025",
+    tool: "socrata_query",
+    keyArgs: "domain=data.oregon.gov, datasetId=qyug-f2km",
+    rows: 109119,
+    approximate: false,
+    notNote:
+      "open solicitations — these are issued purchase orders and contracts (not bids). ORPIN was the retired system; OregonBuys is its replacement. qyug-f2km covers sent_date 2021-07-01 → 2025-07-01 (FY2022–FY2025); 92,224 distinct po_nbr",
+    extra:
+      "Historical ORPIN datasets (retired system, same domain): Contracts Issued=6e9e-sfc4 (93,846 rows), Contracts Expired=8izy-bwhd (92,755 rows), Statewide Price Agreement Spend=gart-52me (5,224 rows). All keyless.",
+  },
+  // ── Vermont — verified 2026-09-21 ────────────────────────────────────────
+  {
+    state: "VT",
+    jurisdiction: "Vermont",
+    dataLabel: "Purchase Orders with Vendor Information (current FY, live-ish)",
+    tool: "socrata_query",
+    keyArgs: "domain=data.vermont.gov, datasetId=8ewu-igdm",
+    rows: 111271,
+    approximate: false,
+    notNote:
+      "a bid or award register — issued purchase orders. 39,882 distinct po_id (~2.8 line items per PO). po_date 2025-07-02 → 2026-06-19 (current fiscal year, so this is live-ish state spend, not an archive)",
+  },
+  // ── Colorado (City of Denver on state portal) — verified 2026-09-21 ──────
+  {
+    state: "CO",
+    jurisdiction: "City of Denver",
+    dataLabel: "City of Denver Procurement Transactions (on CO state portal)",
+    tool: "socrata_query",
+    keyArgs: "domain=data.colorado.gov, datasetId=66zf-qjdd",
+    rows: 76357,
+    approximate: false,
+    notNote:
+      "Colorado STATE procurement — this is City of Denver spend 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.",
+  },
+  {
+    state: "CO",
+    jurisdiction: "City of Denver",
+    dataLabel: "City of Denver Checkbook (on CO state portal)",
+    tool: "socrata_query",
+    keyArgs: "domain=data.colorado.gov, datasetId=wnau-xrqi",
+    rows: 154595,
+    approximate: false,
+    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.",
+  },
+];
+
+/**
+ * Format a row count for display.
+ *
+ * HONESTY: an EXACT count (approximate:false) is printed in full with thousands
+ * separators — never rounded. The table header promises a "verified row count",
+ * so rounding a measured 1,693,227 to "2M" would overstate it by 18% while still
+ * reading as exact. Only an entry explicitly marked `approximate` is rounded, and
+ * that form always carries a leading `~` so the reader can tell the two apart.
+ */
+function fmtRows(e: DataMapEntry): string {
+  if (e.rows === null) return "?";
+  if (!e.approximate) return e.rows.toLocaleString("en-US");
+  // Keep 2 significant figures below 10 units so "~5k" never stands in for a
+  // measured 4,554 (a 10% overstatement); 49,000,000 still renders "~49M".
+  const scale = (v: number, suffix: string) =>
+    `${v < 10 ? v.toFixed(1).replace(/\.0$/, "") : String(Math.round(v))}${suffix}`;
+  const n = e.rows >= 1000000 ? scale(e.rows / 1000000, "M") :
+    e.rows >= 1000 ? scale(e.rows / 1000, "k") :
+    String(e.rows);
+  return `~${n}`;
+}
+
+/**
+ * Render the state-level entries as a Markdown table.
+ * Matches the format in SKILL.md §State & local data map.
+ */
+export function renderStateTableMarkdown(): string {
+  const header =
+    "| Jurisdiction | Data | Tool · key args | Rows | NOT |\n" +
+    "|---|---|---|---|---|\n";
+  const rows = DATA_MAP_ENTRIES.map((e) => {
+    const extra = e.extra ? ` ${e.extra}` : "";
+    return `| **${e.jurisdiction}** | ${e.dataLabel} | \`${e.tool}\` ${e.keyArgs} | ${fmtRows(e)} | ${e.notNote}${extra} |`;
+  });
+  return header + rows.join("\n");
+}
+
+/** Full resource content: header + state table */
+export function renderDataMapMarkdown(): string {
+  return `# State & local data map
+
+Agent-readable lookup: jurisdiction → data type → exact tool call → verified row count → what it is NOT (the most common source of agent error).
+
+**State-level open-data sources (verified 2026-09-21, all keyless):**
+
+${renderStateTableMarkdown()}
+
+**County & city** — use \`socrata_discover_datasets\` to find dataset IDs for: NYC (data.cityofnewyork.us), Chicago (data.cityofchicago.org), Austin TX (data.austintexas.gov), Dallas TX (www.dallasopendata.com), LA (controllerdata.lacity.org), King County WA (data.kingcounty.gov), Cook County IL (datacatalog.cookcountyil.gov), Montgomery County MD (data.montgomerycountymd.gov). For Hennepin County MN and Charlotte-Mecklenburg NC capital project pipelines, use \`arcgis_feature_query\` (hennepin_transportation_cip / charlotte_mecklenburg_cip) — these are CIP pipelines, NOT solicitation or award registers.
+
+**State portals with no keyless procurement content (measured absence, not unexplored):**
+- 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/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)