@cliwant/mcp-sam-gov 1.12.0 → 1.13.1

package/dist/tableau.d.ts

@@ -0,0 +1,58 @@
+/**
+ * tableau.ts — Tableau Server "Guest" view CSV export, a keyless-first SLED
+ * transparency source (loop cycle 75, 2026-07-24 — Montana dark-state closure).
+ *
+ * WHAT IT ADDS: many US state/local governments publish contracts / vendor-payment
+ * / checkbook data on a Guest-enabled Tableau Server. A WORKSHEET view exports its
+ * FULL summary data as CSV at
+ *   `https://{host}/t/{site}/views/{workbook}/{view}.csv?:embed=y`
+ * — anonymous, KEYLESS (no login, key, or session cookie required). This is the
+ * export the public Tableau UI itself offers ("Download ▸ Data"). First payload:
+ * Montana state **Contracts Awarded** (DOA), a live gov-con award register.
+ *
+ * ★ CURATED allowlist (SSRF core): each `base` is a FIXED, live-verified Tableau
+ *   Server view URL (up to the view name; the tool appends `.csv?:embed=y`). The
+ *   `view` enum in server.ts is built FROM the keys (single source of truth), and
+ *   a post-construction hostname assertion (over https) guards the fetch
+ *   (`redirect:"error"`). where/columns cannot alter the host.
+ *
+ * ★ HONESTY PILLARS:
+ *   P1: the CSV is the COMPLETE view export — Tableau returns ALL summary rows in
+ *     the view (there is NO server-side pagination on this endpoint), so
+ *     totalAvailable = the parsed DATA-row count (the true total, NOT a page
+ *     length); limit/offset page over it CLIENT-side. NOTE (disclosed every
+ *     response): a Tableau Server MAY server-cap a very large summary export — the
+ *     seeded views are live-verified COMPLETE (non-round counts), and a round-number
+ *     count is flagged as a possible cap.
+ *   P2: getText THROWS on 429 / 5xx / 404 / timeout — NEVER a fake empty. A view
+ *     that is gated/renamed (a 200 sign-in HTML, or a dashboard-CONTAINER whose CSV
+ *     export is empty) ⇒ schema_drift (a loud, honest failure — NEVER a silent 0).
+ *     A worksheet that legitimately has a header but zero data rows ⇒ honest empty.
+ *   P3: values are TRIMMED strings (surrounding whitespace removed; an empty field
+ *     ⇒ null, never 0 or ""). The value CONTENT is preserved — amounts/dates are
+ *     FORMATTED STRINGS (e.g. "$5,879,590.00"), parse client-side. Header trimmed.
+ *   P4: a 200 body that is not CSV (HTML, or no header row) ⇒ schema_drift.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export type TableauView = {
+    key: string;
+    base: string;
+    label: string;
+    note: string;
+};
+export declare const TABLEAU_VIEWS: readonly TableauView[];
+export type TableauViewCsvArgs = {
+    view: string;
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Fetch a curated Tableau Server Guest view's COMPLETE CSV export (keyless) and
+ * page over it client-side. `view` is an allowlist enum; `limit`/`offset` page
+ * the parsed rows. Returns { view, columns, rows:[{col:value…}] } + honest _meta
+ * (totalAvailable = the complete row count, NOT a page length).
+ */
+export declare function viewCsv(args: TableauViewCsvArgs): Promise<MetaBundle>;
+//# sourceMappingURL=tableau.d.ts.map

package/dist/tableau.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableau.d.ts","sourceRoot":"","sources":["../src/tableau.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAKf,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACrF,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAOtC,CAAC;AAwBX,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAuE3E"}

package/dist/tableau.js

@@ -0,0 +1,132 @@
+/**
+ * tableau.ts — Tableau Server "Guest" view CSV export, a keyless-first SLED
+ * transparency source (loop cycle 75, 2026-07-24 — Montana dark-state closure).
+ *
+ * WHAT IT ADDS: many US state/local governments publish contracts / vendor-payment
+ * / checkbook data on a Guest-enabled Tableau Server. A WORKSHEET view exports its
+ * FULL summary data as CSV at
+ *   `https://{host}/t/{site}/views/{workbook}/{view}.csv?:embed=y`
+ * — anonymous, KEYLESS (no login, key, or session cookie required). This is the
+ * export the public Tableau UI itself offers ("Download ▸ Data"). First payload:
+ * Montana state **Contracts Awarded** (DOA), a live gov-con award register.
+ *
+ * ★ CURATED allowlist (SSRF core): each `base` is a FIXED, live-verified Tableau
+ *   Server view URL (up to the view name; the tool appends `.csv?:embed=y`). The
+ *   `view` enum in server.ts is built FROM the keys (single source of truth), and
+ *   a post-construction hostname assertion (over https) guards the fetch
+ *   (`redirect:"error"`). where/columns cannot alter the host.
+ *
+ * ★ HONESTY PILLARS:
+ *   P1: the CSV is the COMPLETE view export — Tableau returns ALL summary rows in
+ *     the view (there is NO server-side pagination on this endpoint), so
+ *     totalAvailable = the parsed DATA-row count (the true total, NOT a page
+ *     length); limit/offset page over it CLIENT-side. NOTE (disclosed every
+ *     response): a Tableau Server MAY server-cap a very large summary export — the
+ *     seeded views are live-verified COMPLETE (non-round counts), and a round-number
+ *     count is flagged as a possible cap.
+ *   P2: getText THROWS on 429 / 5xx / 404 / timeout — NEVER a fake empty. A view
+ *     that is gated/renamed (a 200 sign-in HTML, or a dashboard-CONTAINER whose CSV
+ *     export is empty) ⇒ schema_drift (a loud, honest failure — NEVER a silent 0).
+ *     A worksheet that legitimately has a header but zero data rows ⇒ honest empty.
+ *   P3: values are TRIMMED strings (surrounding whitespace removed; an empty field
+ *     ⇒ null, never 0 or ""). The value CONTENT is preserved — amounts/dates are
+ *     FORMATTED STRINGS (e.g. "$5,879,590.00"), parse client-side. Header trimmed.
+ *   P4: a 200 body that is not CSV (HTML, or no header row) ⇒ schema_drift.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getText, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { parseCsv } from "./gov-domains.js";
+import { withMeta } from "./meta.js";
+export { num };
+export const TABLEAU_VIEWS = [
+    {
+        key: "mt_contracts_awarded",
+        base: "https://tableau-ext.mt.gov/t/DOA/views/ContractsAwarded/ContractsAwarded",
+        label: "Montana DOA — Contracts Awarded",
+        note: "State of Montana contract/solicitation awards (columns: '$ Awarded', 'Award Date', 'Event Title', 'Event Type' (Invitation For Bid / Request for Proposal), 'Event#' (solicitation number), 'Montana Vendor' (Y/N; '?'=unknown), 'Vendor Name', 'Agency'). ~4,554 awards, April 2020–present. ★'$ Awarded' is a FORMATTED STRING (e.g. \" $1,878,796.10 \") — parse client-side. Source: transparency.mt.gov (Tableau Server Guest CSV).",
+    },
+];
+const VIEW_BY_KEY = new Map(TABLEAU_VIEWS.map((v) => [v.key, v]));
+const VALUE_NOTE = "Values are TRIMMED strings (surrounding whitespace removed; an empty field ⇒ null, never 0 or \"\"). The content is preserved — amounts/dates are FORMATTED STRINGS (e.g. \"$5,879,590.00\"), parse client-side.";
+/** Build the `.csv?:embed=y` export URL + assert it stays on the allowlisted host. */
+function csvUrl(v) {
+    const url = `${v.base}.csv?:embed=y`;
+    const allowedHost = new URL(v.base).hostname;
+    const built = new URL(url);
+    if (built.hostname !== allowedHost || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed Tableau URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the allowlisted view host ${JSON.stringify(allowedHost)} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+            upstreamEndpoint: `tableau:${v.key}`,
+        });
+    }
+    return url;
+}
+/**
+ * Fetch a curated Tableau Server Guest view's COMPLETE CSV export (keyless) and
+ * page over it client-side. `view` is an allowlist enum; `limit`/`offset` page
+ * the parsed rows. Returns { view, columns, rows:[{col:value…}] } + honest _meta
+ * (totalAvailable = the complete row count, NOT a page length).
+ */
+export async function viewCsv(args) {
+    const v = VIEW_BY_KEY.get(args.view);
+    if (!v) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Unknown Tableau view ${JSON.stringify(args.view)}. Allowed: ${TABLEAU_VIEWS.map((s) => s.key).join(", ")}.`,
+            retryable: false,
+        });
+    }
+    const limit = args.limit ?? 50;
+    const offset = args.offset ?? 0;
+    // ── Fetch the full view CSV. getText THROWS on 429/5xx/404/timeout (P2). ──
+    const url = csvUrl(v);
+    const body = await getText(url, { label: `tableau:${v.key}`, redirect: "error", timeoutMs: 45_000 });
+    // P4: a non-CSV body (HTML sign-in / error page) ⇒ schema_drift, never parsed as empty.
+    const text = body.replace(/^/, ""); // strip a leading UTF-8 BOM if present
+    if (text.trim().length === 0 || /^\s*</.test(text)) {
+        throw driftError(`tableau:${v.key}`, "Tableau returned an empty or non-CSV (HTML) body at HTTP 200 — the view may be gated, renamed, or a dashboard container (not a worksheet). Schema drift — refusing to report a fake empty.");
+    }
+    const table = parseCsv(text);
+    // P4: the first row MUST be a header (≥1 named column). No rows ⇒ drift.
+    if (table.length === 0 || !Array.isArray(table[0]) || table[0].length === 0) {
+        throw driftError(`tableau:${v.key}`, "Tableau CSV has no header row — schema drift.");
+    }
+    const header = table[0].map((h) => str(h) ?? "");
+    const dataRows = table.slice(1);
+    const totalAvailable = dataRows.length; // P1: complete view export = true total
+    const pageRows = dataRows.slice(offset, offset + limit).map((r) => {
+        const obj = {};
+        for (let i = 0; i < header.length; i++)
+            obj[header[i] || `col${i}`] = str(r[i]);
+        return obj;
+    });
+    const returned = pageRows.length;
+    const hasMore = offset + returned < totalAvailable;
+    const nextOffset = hasMore ? offset + returned : null;
+    // P1 cap disclosure: a suspiciously round total may indicate a server export cap.
+    const roundCap = totalAvailable >= 1000 && totalAvailable % 1000 === 0;
+    const notes = [
+        `Source: ${v.label} (Tableau Server Guest CSV export, keyless). ${v.note}`,
+        "totalAvailable is the COMPLETE view export row count (Tableau returns all summary rows; there is no server-side pagination) — limit/offset page over the full set client-side.",
+        "Pagination order follows the Tableau view's OWN sort. Each call re-fetches the complete CSV and slices it; if the view lacks a stable sort, offsets across SEPARATE calls could shift — for a consistent snapshot of a large view, fetch it with a single large limit.",
+        VALUE_NOTE,
+        "FRESHNESS is set by the publisher: a Tableau export carries no refresh timestamp, and the view reflects whenever the publisher last refreshed it, which can lag by weeks. Check the newest value in the view's date columns before relying on recency.",
+    ];
+    if (roundCap)
+        notes.push(`NOTE: the row count (${totalAvailable}) is an exact multiple of 1000 — Tableau Server MAY have capped this summary export, so totalAvailable could be a lower bound. Treat with caution.`);
+    return withMeta({ view: v.key, columns: header, rows: pageRows }, {
+        source: `${new URL(v.base).hostname} via Tableau Server Guest CSV (keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied: ["view"],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes,
+    });
+}
+//# sourceMappingURL=tableau.js.map

package/dist/tableau.js.map

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cliwant/mcp-sam-gov",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "mcpName": "io.github.cliwant/mcp-sam-gov",
-  "description": "Most comprehensive keyless MCP server for US federal + state/local (SLED) contracting + spending + regulation: SAM.gov, USAspending, Federal Register, eCFR, Grants.gov, plus SLED procurement bids (OpenGov, Bonfire, ArcGIS, Socrata 53 hosts). 150 tools, no API key, plug into Claude Desktop / Claude Code / Codex CLI / Cursor / Continue / Gemini CLI.",
+  "description": "Most comprehensive keyless-first MCP server for US federal + state/local (SLED) contracting + spending + regulation: SAM.gov, USAspending, Federal Register, eCFR, Grants.gov, plus SLED procurement bids (OpenGov, Bonfire, ArcGIS, Socrata 53 hosts). 152 tools (147 need no API key), plug into Claude Desktop / Claude Code / Codex CLI / Cursor / Continue / Gemini CLI.",
   "keywords": [
     "mcp",
     "model-context-protocol",

package/src/arcgis-feature.ts

@@ -79,6 +79,17 @@ export const ARCGIS_SERVICES: readonly ArcgisService[] = [
   { key: "iowadot_public_bid_awards", base: "https://services.arcgis.com/8lRhdTsQyJpO52F1/arcgis/rest/services/Project_Scheduling_Public_Bid_Point_View/FeatureServer/0", label: "Iowa DOT — Public Bid / Project Scheduling", note: "Iowa Department of Transportation public bid & project scheduling (PROJECT_NUMBER/WORK_DESC/LETTING_FISCAL_YEAR/PROGRAM_ESTIMATE/CONTRACT_AWARDED/AWARDED/FINAL_CONTRACT/CONTRACTOR/CONTRACT_ID/STATUS). ~360." },
   { key: "okdot_cirb_contract_status", base: "https://services6.arcgis.com/RBtoEUQ2lmN0K3GY/arcgis/rest/services/CIRB_Project_Status/FeatureServer/0", label: "Oklahoma DOT — CIRB Contract Status", note: "Oklahoma Department of Transportation County Improvements for Roads & Bridges (CIRB) contract status (T_PROJECT/JP_DESCRIPTION/A_CONTRACT_AMOUNT/A_AMOUNT_EARNED/A_AMOUNT_PAID/D_LET_DATE/D_CONTRACT_AWARD_DATE/D_WORK_ORDER_DATE). ~780." },
   { key: "topeka_checkbook_aggregate", base: "https://services1.arcgis.com/EvtgI3PZ9PyCGJZS/arcgis/rest/services/Checkbook_Aggregate/FeatureServer/0", label: "City of Topeka KS — Open Checkbook (aggregate FY2015–2023)", note: "City of Topeka KS open checkbook, all years aggregated FY2015–2023 (fiscal_year/fiscal_period/department/program/fund/vendor_name/description/dollars). ~332k rows, ~323.6k with dollars>0." },
+  // ── North Dakota dark-state closure (loop cycle 74, 2026-07-24). NDDOT federal
+  //    flex-funding AWARDS on Esri-cloud services1.arcgis.com (live-verified
+  //    returnCountOnly + fields, no PII). ★ND's AUTHORITATIVE statewide checkbook
+  //    (omb.nd.gov) and procurement (ndbuys.nd.gov, Ivalua) are keyless-UNREACHABLE
+  //    (the 165.234.x state network refuses external connections — verified from
+  //    two independent vantages) / CAPTCHA+SSO-gated → recorded structurally-blocked
+  //    in TRIAGE; these DOT award layers are ND's best-available keyless proxy. ──
+  { key: "nddot_flex_setaside_road", base: "https://services1.arcgis.com/EDijJFsQQwgz8X53/arcgis/rest/services/Flex_Funding_Awarded_WFL1/FeatureServer/20", label: "North Dakota DOT — Flex Funding Awarded (Set-Aside, Road)", note: "NDDOT federal flex-funding ROAD awards, Set-Aside category (LPA_NAME=recipient local public agency, LPA_TYPE=County/Township/City, Total_Project_Cost, Flex_Funds_Awarded, Work_Type). ~33. ★$ amounts are FORMATTED STRINGS (e.g. \" $5,879,590.00 \") — parse client-side; recipients are LOCAL PUBLIC AGENCIES, not vendors. ND's authoritative checkbook/procurement is keyless-unreachable — this is a proxy." },
+  { key: "nddot_flex_partner_road", base: "https://services1.arcgis.com/EDijJFsQQwgz8X53/arcgis/rest/services/Flex_Funding_Awarded_WFL1/FeatureServer/22", label: "North Dakota DOT — Flex Funding Awarded (Partner-Allocated, Road)", note: "NDDOT federal flex-funding ROAD awards, Partner-Allocated category (LPA_NAME/LPA_TYPE/Total_Project_Cost/Flex_Funds_Awarded/Work_Type). ~22. ★$ amounts are FORMATTED STRINGS; recipients are LOCAL PUBLIC AGENCIES. Companion to nddot_flex_setaside_road. ND's authoritative checkbook/procurement is keyless-unreachable — this is a proxy." },
+  { key: "nddot_flex_setaside_bridge", base: "https://services1.arcgis.com/EDijJFsQQwgz8X53/arcgis/rest/services/Flex_Funding_Awarded_WFL1/FeatureServer/1", label: "North Dakota DOT — Flex Funding Awarded (Set-Aside, Bridge)", note: "NDDOT federal flex-funding BRIDGE awards, Set-Aside category (LPA_NAME/LPA_TYPE/Total_Project_Cost/Flex_Funds_Awarded/Work_Type). ~12. ★$ amounts are FORMATTED STRINGS; recipients are LOCAL PUBLIC AGENCIES. ND's authoritative checkbook/procurement is keyless-unreachable — this is a proxy." },
+  { key: "nddot_flex_partner_bridge", base: "https://services1.arcgis.com/EDijJFsQQwgz8X53/arcgis/rest/services/Flex_Funding_Awarded_WFL1/FeatureServer/21", label: "North Dakota DOT — Flex Funding Awarded (Partner-Allocated, Bridge)", note: "NDDOT federal flex-funding BRIDGE awards, Partner-Allocated category (LPA_NAME/LPA_TYPE/Total_Project_Cost/Flex_Funds_Awarded/Work_Type). ~1. ★$ amounts are FORMATTED STRINGS; recipients are LOCAL PUBLIC AGENCIES. ND's authoritative checkbook/procurement is keyless-unreachable — this is a proxy." },
 ] as const;
 
 const SERVICE_BY_KEY: ReadonlyMap<string, ArcgisService> = new Map(ARCGIS_SERVICES.map((s) => [s.key, s]));

package/src/bonfire.ts

@@ -11,7 +11,7 @@
  * ★ 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_
+ * So this ships a CURATED, live-verified SEED directory (186 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
@@ -53,7 +53,7 @@ const BONFIRE_SOURCE = (org: string) =>
 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) ──
+// ─── The curated 186-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[] = [

package/src/echo.ts

@@ -28,8 +28,12 @@
  *       any fetch (the path-injection guard).
  *   (3) Every interpolated id is grammar-validated BEFORE use — `state` ∈ a frozen
  *       US state/territory enum (also the silent-zero guard, below); `naics`
- *       ^[0-9]{2,6}$ / `sic` ^[0-9]{2,4}$; `registryId` ^[0-9]{9,12}$ (FRS IDs are
- *       12 digits; all-digit is the security property); the UPSTREAM-supplied
+ *       ^[0-9]{2,6}$ / `sic` ^[0-9]{2,4}$; `registryId` ^[A-Za-z0-9]{1,20}$ (FRS
+ *       ids are 12 digits, but ECHO's own search rows also carry state/program ids
+ *       like 'DCR000509282' and short ids like '9434', and get_dfr serves them —
+ *       live-verified 2026-09-13; the ALPHANUMERIC charclass is the security
+ *       property: no separator, space, '%' or newline can reach p_id, and an id
+ *       ECHO does not know comes back "ID … is invalid" ⇒ not_found); the UPSTREAM-supplied
  *       `qid` is validated ^[0-9]+$ BECAUSE it is external (echodata.epa.gov mints
  *       it), before it is used in step 2; the internally-computed `pageno` is a
  *       plain integer. `facilityName` (p_fn) is a free-text filter VALUE — encoded
@@ -122,10 +126,12 @@ const ECHO_SERVICES: ReadonlySet<string> = new Set([
 // ECHO does NOT validate filter VALUES: an unknown value silently returns
 // QueryRows:"0" (indistinguishable from a genuine-empty). So we validate
 // client-side: `state` against the enum below (surfaced by the Zod enum in
-// server.ts), naics/sic against a digit-length grammar, registryId all-digit.
+// server.ts), naics/sic against a digit-length grammar, registryId alphanumeric.
 const NAICS_RE = /^[0-9]{2,6}$/;
 const SIC_RE = /^[0-9]{2,4}$/;
-const REGISTRY_ID_RE = /^[0-9]{9,12}$/;
+// Alphanumeric, not all-digit: ECHO search rows return non-FRS ids (e.g. 'DCR000509282',
+// '9434') that get_dfr accepts, so an all-digit 9–12 grammar broke search → report.
+const REGISTRY_ID_RE = /^[A-Za-z0-9]{1,20}$/;
 // The UPSTREAM-supplied QueryID — validated BECAUSE it is external (echodata mints
 // it), before it is used to build the step-2 URL.
 const QID_RE = /^[0-9]+$/;
@@ -457,11 +463,11 @@ export async function searchFacilities(args: {
 export async function facilityReport(args: {
   registryId: string;
 }): Promise<MetaBundle> {
-  // Belt-and-suspenders (behind the server's Zod ^[0-9]{9,12}$).
+  // Belt-and-suspenders (behind the server's Zod ^[A-Za-z0-9]{1,20}$).
   if (!REGISTRY_ID_RE.test(args.registryId)) {
     throw new ToolErrorCarrier({
       kind: "invalid_input",
-      message: `Invalid registryId ${JSON.stringify(args.registryId)} — expected an all-digit FRS RegistryID (9–12 digits).`,
+      message: `Invalid registryId ${JSON.stringify(args.registryId)} — expected the RegistryID exactly as returned by echo_search_facilities (1–20 letters/digits, e.g. '110059768461' or 'DCR000509282').`,
       retryable: false,
     });
   }

package/src/open-checkbook.ts

@@ -0,0 +1,183 @@
+/**
+ * open-checkbook.ts — Socrata "Open Expenditures / Open Checkbook" row-level
+ * vendor-payment API, a keyless-first SLED source (loop cycle 76, 2026-07-24 —
+ * South Dakota dark-state closure, the LAST dark state).
+ *
+ * WHAT IT ADDS: some US governments run Socrata's "Open Expenditures" product,
+ * whose public dashboard fronts a KEYLESS app-proxy JSON API at
+ *   `https://{host}/api/checkbook_data.json?year=…&{filters}&page=P&limit=L`
+ * → `{ data:[…row-level payments…], count, total_amount }`. First (and, as of
+ * this writing, only live-verified) portal: **South Dakota Open Checkbook**
+ * (740,980 vendor-payment rows, ~$8.41B, the ~3 most-recent fiscal years).
+ *
+ * ★ KEYLESS- vs-GATED HONESTY (load-bearing): the app-proxy above is anonymous
+ *   and public. The UNDERLYING Socrata SODA dataset (7uwr-juaf on
+ *   southdakota.data.socrata.com) is **403 login-gated** — this module NEVER
+ *   touches it and NEVER presents it as reachable. We only call the public
+ *   /api/checkbook_data.json surface the dashboard itself uses anonymously.
+ *
+ * ★ CURATED allowlist (SSRF core): each portal is a FIXED, live-verified host;
+ *   the `portal` enum in server.ts is built FROM the keys. Host asserted before
+ *   fetch (redirect:"error").
+ *
+ * ★ HONESTY PILLARS:
+ *   P1: totalAvailable = the API's own `count` (the REAL filtered total — it
+ *     matches the product's totals.json exactly; e.g. 740,980 unfiltered,
+ *     109,887 for org1=TRANSPORTATION), NEVER the page length.
+ *   P2: getJson THROWS on 429/5xx/timeout — NEVER a fake empty. A bogus filter
+ *     ⇒ honest count:0/empty; a deep offset past the end ⇒ returned:0 with the
+ *     real count preserved (an honest tail, not an outage).
+ *   P3: `amount` ⇒ number|null (a real $0 is 0, an absent value is null, never a
+ *     fabricated 0); all other fields via str (null-never-empty). Dates verbatim.
+ *   P4: a body that is not `{data:[…], count:<number>}` ⇒ schema_drift.
+ *   ★ Coverage disclosure (P5): only the ~3 most-recent fiscal years are exposed
+ *     by the product (NOT full history) — disclosed every response.
+ */
+
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+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 };
+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.",
+  },
+] as const;
+
+const PORTAL_BY_KEY: ReadonlyMap<string, OpenCheckbookPortal> = new Map(OPEN_CHECKBOOK_PORTALS.map((p) => [p.key, p]));
+
+// Sort fields the product supports (validated — an SSRF/injection + silent-noop guard).
+const SORT_FIELDS = new Set(["amount", "payment_date", "vendor", "org1", "expense_category"]);
+
+// ─── SSRF-guarded fetch (fixed allowlist host + assertion) ──
+async function getCheckbook(portal: OpenCheckbookPortal, params: URLSearchParams): Promise<unknown> {
+  const url = `https://${portal.host}/api/checkbook_data.json?${params.toString()}`;
+  const built = new URL(url);
+  if (built.hostname !== portal.host || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Constructed Open-Checkbook URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the allowlisted portal host ${JSON.stringify(portal.host)} over https — refusing to fetch (SSRF safety).`,
+      retryable: false,
+      upstreamEndpoint: `open-checkbook:${portal.key}`,
+    });
+  }
+  return getJson(url, { label: `open-checkbook:${portal.key}`, redirect: "error" });
+}
+
+// ─── Tool: open_checkbook_search ──────────────────────────────────
+export type OpenCheckbookSearchArgs = {
+  portal: string;
+  year?: string;
+  vendor?: string;
+  org?: string;
+  expenseCategory?: string;
+  sortBy?: string;
+  sortOrder?: string;
+  limit?: number;
+  offset?: number;
+};
+
+/**
+ * Row-level vendor-payment search over a curated Socrata Open-Expenditures
+ * checkbook portal (keyless). `portal` is an allowlist enum; `year`/`vendor`/
+ * `org`/`expenseCategory` are EXACT-match filters; `sortBy`/`sortOrder` sort;
+ * `limit`/`offset` page. Returns { portal, rows:[…] } + honest _meta
+ * (totalAvailable = the API's real count, NOT a page length).
+ */
+export async function openCheckbookSearch(args: OpenCheckbookSearchArgs): Promise<MetaBundle> {
+  const portal = PORTAL_BY_KEY.get(args.portal);
+  if (!portal) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Unknown Open-Checkbook portal ${JSON.stringify(args.portal)}. Allowed: ${OPEN_CHECKBOOK_PORTALS.map((p) => p.key).join(", ")}.`,
+      retryable: false,
+    });
+  }
+  const limit = args.limit ?? 25;
+  const offset = args.offset ?? 0;
+  // The product paginates by 1-based `page` + `limit`. Map offset→page and snap
+  // offset to the page boundary (disclosing the served offset when it differs).
+  const page = Math.floor(offset / limit) + 1;
+  const servedOffset = (page - 1) * limit;
+
+  const filtersApplied: string[] = ["portal"];
+  const params = new URLSearchParams();
+  params.set("year", args.year && args.year.trim() ? args.year.trim() : "All Years");
+  if (args.year && args.year.trim()) filtersApplied.push("year");
+  if (args.vendor && args.vendor.trim()) { params.set("vendor", args.vendor.trim()); filtersApplied.push("vendor"); }
+  if (args.org && args.org.trim()) { params.set("org1", args.org.trim()); filtersApplied.push("org"); }
+  if (args.expenseCategory && args.expenseCategory.trim()) { params.set("expense_category", args.expenseCategory.trim()); filtersApplied.push("expenseCategory"); }
+  if (args.sortBy && args.sortBy.trim()) {
+    const sf = args.sortBy.trim();
+    if (!SORT_FIELDS.has(sf)) {
+      throw new ToolErrorCarrier({
+        kind: "invalid_input",
+        message: `Invalid sortBy ${JSON.stringify(sf)}. Allowed: ${[...SORT_FIELDS].join(", ")}.`,
+        retryable: false,
+      });
+    }
+    params.set("sort_field", sf);
+    params.set("sort_order", args.sortOrder === "asc" ? "asc" : "desc");
+    filtersApplied.push("sortBy");
+  }
+  params.set("page", String(page));
+  params.set("limit", String(limit));
+
+  const body = await getCheckbook(portal, params);
+  const b = (body ?? {}) as { data?: unknown; count?: unknown; total_amount?: unknown };
+  // P4: the shape MUST be { data:[…], count:<number> }.
+  if (!Array.isArray(b.data)) throw driftError(`open-checkbook:${portal.key}`, "Open-Checkbook shape drift — response.data must be an array.");
+  const totalAvailable = num(b.count);
+  if (totalAvailable === null) throw driftError(`open-checkbook:${portal.key}`, "Open-Checkbook shape drift — response.count must be a number.");
+
+  const rows = (b.data as unknown[]).map((r) => {
+    const o = (r ?? {}) as Record<string, unknown>;
+    return {
+      vendor: str(o.vendor),
+      amount: num(o.amount), // P3: a real $0 is 0; absent ⇒ null (never a fabricated 0)
+      payment_date: str(o.payment_date),
+      org1: str(o.org1),
+      expense_category: str(o.expense_category),
+      description: str(o.description),
+      fund: str(o.fund),
+      invoice: str(o.custom_checkbook_field7),
+      payment_id: str(o.payment_id),
+    };
+  });
+  const returned = rows.length;
+  const hasMore = servedOffset + returned < totalAvailable;
+  const nextOffset = hasMore ? servedOffset + returned : null;
+
+  const notes: string[] = [
+    `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.",
+    "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)
+    notes.push(`offset ${offset} was snapped to ${servedOffset} (the product paginates by fixed page×limit); pass an offset that is a multiple of limit to avoid snapping.`);
+
+  return withMeta(
+    { portal: portal.key, rows },
+    {
+      source: `${portal.host} via Socrata Open Expenditures (keyless app-proxy)`,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset: servedOffset, limit, hasMore, nextOffset },
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}