@cliwant/mcp-sam-gov 1.9.0 → 1.11.0

package/src/nhtsa.ts

@@ -19,16 +19,20 @@
  *   entirely — never surfaced, logged, or stored. The B2G value is the
  *   manufacturer / component / safety signal, NOT the VIN.
  *
- * ★ THE HONESTY PILLARS (P1-P4, live-verified 2026-07-15):
+ * ★ THE HONESTY PILLARS (P1/P3/P4 live-verified 2026-07-15; P2 corrected +
+ *   re-verified 2026-07-20):
  *   P1: totalAvailable = `Count` (recalls) / `count` (complaints) — the REAL total.
  *       NHTSA returns the COMPLETE filtered set (no pagination), so in the normal
  *       case Count === results.length ⇒ complete:true. totalAvailable is NEVER
  *       fabricated: a PRESENT numeric Count is trusted verbatim; a MISSING Count
  *       falls back to results.length WITH an honest note (never invented).
- *   P2: results:[] (Count 0) ⇒ an HONEST EMPTY (returned:0, complete:true) — a bad
- *       make/model that returns 200+Count 0 is an honest no-match, NOT an error. A
- *       4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW (never a fake empty); a 200
- *       non-JSON body ⇒ schema_drift.
+ *   P2: ★NHTSA returns HTTP 400 (NOT 200) + {Count/count:0, results:[]} (Message
+ *       "Results returned successfully") for a VALID make/model/year that simply
+ *       has ZERO records (live-verified 2026-07-20). getNhtsa reads the body and
+ *       reclassifies THAT idiom as an HONEST EMPTY (returned:0, totalAvailable:0,
+ *       complete:true) with a note; any OTHER 400 ⇒ invalid_input, a 404 ⇒
+ *       not_found, a 5xx/timeout ⇒ THROW (never a fake empty), a 200 non-JSON
+ *       body ⇒ schema_drift.
  *   P3: booleans (crash/fire/parkIt/parkOutSide/overTheAirUpdate) preserved AS
  *       booleans (a non-boolean ⇒ null, never a fabricated false); counts
  *       (numberOfInjuries/numberOfDeaths) via `num` (a genuine 0 stays 0, NEVER
@@ -42,8 +46,8 @@
  *       so a `../` or `%` can never reach the fixed path).
  */
 
-import { ToolErrorCarrier } from "./errors.js";
-import { getJson, driftError } from "./datasource.js";
+import { ToolErrorCarrier, errorFromResponse } from "./errors.js";
+import { driftError, isRedirectError } from "./datasource.js";
 import { num, str } from "./coerce.js";
 import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
 
@@ -109,10 +113,31 @@ function validateVehicleArgs(args: NhtsaVehicleArgs, label: string): void {
 
 // ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
 /**
- * GET one NHTSA JSON resource on the FIXED host. Builds
- * `https://api.nhtsa.gov${path}?${params}`, asserts the CONSTRUCTED URL's
- * hostname === the fixed host over https (belt-and-suspenders), and sets
- * `redirect:"error"` (fail closed on any off-host 3xx). Keyless — no header/token.
+ * ★ NHTSA's "400-for-empty" idiom. A VALID make/model/year that simply has ZERO
+ * records returns HTTP 400 with a body `{Count/count:0, ..., results:[]}` and
+ * `Message/message:"Results returned successfully"` (live-verified 2026-07-20:
+ * `make=tesla&model=model 3&modelYear=2015` → HTTP 400, Count 0). Recalls use
+ * `Count`/`Message`, complaints use lowercase `count`/`message` — accept either.
+ * This is a genuine no-match, NOT a bad request; the caller reclassifies it to an
+ * honest empty. (A 400 that is NOT this idiom stays a real invalid_input.)
+ */
+function isNhtsaEmptyIdiom(body: unknown): boolean {
+  if (body === null || typeof body !== "object") return false;
+  const b = body as Record<string, unknown>;
+  const rawCount = b.Count ?? b.count;
+  return num(rawCount) === 0 && Array.isArray(b.results) && b.results.length === 0;
+}
+
+/**
+ * GET one NHTSA JSON resource on the FIXED host. Bespoke `fetch` (NOT the shared
+ * getJson) because we must READ a non-2xx body: NHTSA returns HTTP 400 for a valid
+ * query with zero records (the ★400-for-empty idiom above), and getJson would
+ * throw invalid_input and DISCARD the body — turning "zero recalls" (a valid,
+ * high-value answer) into a phantom "Bad request". Asserts the constructed URL's
+ * hostname === the fixed host over https (belt-and-suspenders) + `redirect:"error"`
+ * (fail closed on any off-host 3xx). Keyless — no header/token. Non-2xx that is NOT
+ * the empty idiom keeps the standard taxonomy (400→invalid_input, 404→not_found,
+ * 429→rate_limited, 5xx→upstream_unavailable); a 200 non-JSON body ⇒ schema_drift.
  */
 async function getNhtsa(
   path: string,
@@ -129,7 +154,57 @@ async function getNhtsa(
       upstreamEndpoint: label,
     });
   }
-  return getJson(url, { label, redirect: "error" });
+  let res: Response;
+  try {
+    res = await fetch(built.toString(), {
+      redirect: "error",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (e) {
+    if (isRedirectError(e)) {
+      throw driftError(
+        label,
+        `NHTSA returned an off-host redirect (redirect:"error") while fetching ${label} — refusing to follow it (SSRF safety).`,
+      );
+    }
+    if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        retryable: false,
+        message: `Request to ${label} timed out.`,
+        upstreamEndpoint: label,
+      });
+    }
+    throw new ToolErrorCarrier({
+      kind: "upstream_unavailable",
+      retryable: true,
+      retryAfterSeconds: 30,
+      message: `Network error reaching ${label}: ${e instanceof Error ? e.message : String(e)}`,
+      upstreamEndpoint: label,
+    });
+  }
+  if (!res.ok) {
+    // ★P2 CRUX: read the body — a 400 that is NHTSA's empty idiom is an HONEST
+    // no-match (returned via resolveTotal as Count 0 → total 0), NOT an error.
+    let body: unknown = null;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    if (res.status === 400 && isNhtsaEmptyIdiom(body)) return body;
+    // Any other non-2xx keeps the standard taxonomy (never a fabricated empty).
+    // errorFromResponse returns a plain ToolError → wrap it in the carrier to throw.
+    throw new ToolErrorCarrier(errorFromResponse(res, label));
+  }
+  try {
+    return await res.json();
+  } catch {
+    throw driftError(
+      label,
+      `NHTSA ${label} returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).`,
+    );
+  }
 }
 
 /** Build the shared make/model/modelYear query (module-built; no raw passthrough). */
@@ -142,27 +217,17 @@ function vehicleParams(args: NhtsaVehicleArgs): URLSearchParams {
 }
 
 /**
- * Fetch + parse a NHTSA resource, mirroring datagov-catalog's catch-ladder: a
- * ToolErrorCarrier (host-assert / 4xx-5xx taxonomy) rethrows FIRST (preserving its
- * kind); a 200 non-JSON `.json()` SyntaxError reclassifies to schema_drift; a bare
- * error rethrows LAST.
+ * Build the vehicle query and fetch through getNhtsa, which fully classifies the
+ * response: the ★400-for-empty idiom → an honest empty; every other non-2xx → the
+ * standard taxonomy; a 200 non-JSON body → schema_drift. A thin wrapper — getNhtsa
+ * owns the error contract.
  */
 async function fetchNhtsa(
   path: string,
   label: string,
   args: NhtsaVehicleArgs,
 ): Promise<unknown> {
-  try {
-    return await getNhtsa(path, label, vehicleParams(args));
-  } catch (e) {
-    if (e instanceof ToolErrorCarrier) throw e;
-    if (e instanceof SyntaxError)
-      throw driftError(
-        label,
-        `NHTSA ${label} returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).`,
-      );
-    throw e;
-  }
+  return await getNhtsa(path, label, vehicleParams(args));
 }
 
 /**

package/src/nist-controls.ts

@@ -46,8 +46,10 @@ export type NistControl = {
   id: string; // display form, e.g. "AC-2"
   family: string; // e.g. "AC — Access Control"
   title: string;
-  statement: string; // assembled requirement prose (labelled, multi-line)
+  status: string | null; // OSCAL status prop, e.g. "withdrawn"; null when active
+  statement: string | null; // requirement prose; NULL when absent (a WITHDRAWN control has none) — never ""
   guidance: string | null; // discussion prose
+  incorporatedInto: string[]; // withdrawn control ⇒ the control id(s) it was folded into (e.g. ["AC-2","AU-6"])
   enhancements: { id: string; title: string }[]; // e.g. AC-2(1)
 };
 
@@ -60,6 +62,8 @@ type OscalPart = {
 type OscalControl = {
   id?: string;
   title?: string;
+  props?: { name?: string; value?: string }[];
+  links?: { href?: string; rel?: string }[];
   parts?: OscalPart[];
   controls?: OscalControl[];
 };
@@ -100,12 +104,26 @@ function partProse(control: OscalControl, name: string): string | null {
 }
 
 function mapControl(control: OscalControl, family: string): NistControl {
+  const status =
+    (control.props ?? []).find((p) => p.name === "status")?.value?.trim() || null;
+  // A withdrawn control carries `links[] rel="incorporated-into"` → the control(s)
+  // it was folded into (e.g. AC-13 → AC-2, AU-6). Surface them so a withdrawn
+  // control is never mistaken for an active requirement.
+  const incorporatedInto = (control.links ?? [])
+    .filter((l) => l.rel === "incorporated-into" && typeof l.href === "string")
+    .map((l) => displayId(String(l.href).replace(/^#/, "")))
+    .filter((x) => x.length > 0);
   return {
     id: displayId(control.id ?? ""),
     family,
     title: (control.title ?? "").trim(),
-    statement: partProse(control, "statement") ?? "",
+    status,
+    // [P3] absent statement ⇒ null, NEVER "" — a withdrawn control has no
+    // requirement text; "" would misread as "an active control with a blank
+    // requirement".
+    statement: partProse(control, "statement"),
     guidance: partProse(control, "guidance"),
+    incorporatedInto,
     enhancements: (control.controls ?? []).map((e) => ({
       id: displayId(e.id ?? ""),
       title: (e.title ?? "").trim(),
@@ -119,7 +137,12 @@ function mapControl(control: OscalControl, family: string): NistControl {
  * families (else driftError — a truncated catalog is NEVER a fake empty). Enhancements
  * are carried on each control (not indexed as top-level entries).
  */
-async function loadControls(): Promise<NistControl[]> {
+type OscalMetadata = { version: string | null; lastModified: string | null };
+
+async function loadControls(): Promise<{
+  controls: NistControl[];
+  metadata: OscalMetadata;
+}> {
   return memoize(
     "nist:sp800-53r5",
     async () => {
@@ -131,7 +154,12 @@ async function loadControls(): Promise<NistControl[]> {
         label: OSCAL_LABEL,
         redirect: "error",
         timeoutMs: OSCAL_TIMEOUT_MS,
-      })) as { catalog?: { groups?: unknown } };
+      })) as {
+        catalog?: {
+          groups?: unknown;
+          metadata?: { version?: unknown; "last-modified"?: unknown };
+        };
+      };
       const groups = body.catalog?.groups;
       if (!Array.isArray(groups) || groups.length < FAMILY_FLOOR) {
         throw driftError(
@@ -139,12 +167,21 @@ async function loadControls(): Promise<NistControl[]> {
           `OSCAL catalog.groups missing or implausibly small (${Array.isArray(groups) ? groups.length : "not-an-array"} < ${FAMILY_FLOOR} families) — treating as schema drift / truncation, never a fake-empty catalog.`,
         );
       }
+      // [P5 freshness] The OSCAL catalog is a moving static file on the `main`
+      // branch — surface its exact version + last-modified so a compliance caller
+      // knows WHICH point-release (5.1.1 / 5.2.0 …) they are reading.
+      const md = body.catalog?.metadata ?? {};
+      const metadata: OscalMetadata = {
+        version: typeof md.version === "string" ? md.version : null,
+        lastModified:
+          typeof md["last-modified"] === "string" ? md["last-modified"] : null,
+      };
       const controls: NistControl[] = [];
       for (const g of groups as OscalGroup[]) {
         const family = `${(g.id ?? "").toUpperCase()} — ${(g.title ?? "").trim()}`;
         for (const c of g.controls ?? []) controls.push(mapControl(c, family));
       }
-      return controls;
+      return { controls, metadata };
     },
     OSCAL_CACHE_TTL_MS,
   );
@@ -166,7 +203,7 @@ export async function searchControls(args: {
 }): Promise<MetaBundle> {
   const limit = args.limit ?? 25;
   const offset = args.offset ?? 0;
-  const all = await loadControls();
+  const { controls: all, metadata } = await loadControls();
 
   const filtersApplied: string[] = [];
   const idQ = args.controlId !== undefined ? displayId(args.controlId) : undefined;
@@ -189,7 +226,7 @@ export async function searchControls(args: {
       // Search the title + requirement statement AND each enhancement's title, so a
       // term that lives only in an enhancement (e.g. "multi-factor" → IA-2(1)) still
       // surfaces the parent control. filtersApplied still lists 'keyword'.
-      const hay = `${c.title}\n${c.statement}\n${c.enhancements.map((e) => e.title).join("\n")}`.toLowerCase();
+      const hay = `${c.title}\n${c.statement ?? ""}\n${c.enhancements.map((e) => e.title).join("\n")}`.toLowerCase();
       if (!hay.includes(kwQ)) return false;
     }
     return true;
@@ -201,10 +238,22 @@ export async function searchControls(args: {
   const hasMore = offset + returned < totalAvailable;
   const nextOffset = hasMore ? offset + returned : null;
 
+  const versionLabel = metadata.version ? `Rev ${metadata.version}` : "Rev 5";
+  const notes: string[] = [PROVENANCE_NOTE, CLIENT_FILTER_NOTE, REFERENCE_NOTE];
+  notes.push(
+    `OSCAL catalog ${metadata.version ? `version ${metadata.version}` : "revision 5"}${metadata.lastModified ? `, last-modified ${metadata.lastModified.slice(0, 10)}` : ""} — fetched live from the usnistgov/oscal-content \`main\` branch (a MOVING target; control text can change between point releases, e.g. 5.1.1 → 5.2.0). Cite the version above, not just "Rev 5".`,
+  );
+  const withdrawnOnPage = page.filter((c) => c.status === "withdrawn").length;
+  if (withdrawnOnPage > 0) {
+    notes.push(
+      `${withdrawnOnPage} of the returned control(s) are WITHDRAWN (status:"withdrawn") — a withdrawn control has NO requirement text (statement:null) and is NOT an active requirement; see its incorporatedInto for the control(s) that superseded it.`,
+    );
+  }
+
   return withMeta(
     { controls: page },
     {
-      source: "NIST SP 800-53 Rev 5 (OSCAL catalog, keyless)",
+      source: `NIST SP 800-53 ${versionLabel} (OSCAL catalog, keyless)`,
       keylessMode: true,
       returned,
       totalAvailable,
@@ -213,7 +262,7 @@ export async function searchControls(args: {
       filtersDropped: [],
       fieldsUnavailable: [],
       pagination: { offset, limit, hasMore, nextOffset },
-      notes: [PROVENANCE_NOTE, CLIENT_FILTER_NOTE, REFERENCE_NOTE],
+      notes,
     } satisfies Partial<ResponseMeta>,
   );
 }

package/src/ofac.ts

@@ -206,7 +206,18 @@ export function classifyMatch(
   const allQinE = qt.length > 0 && qt.every((t) => eSet.has(t));
   const allEinQ = et.length > 0 && et.every((t) => qSet.has(t));
   if (allQinE || allEinQ) return "strong";
-  if (entryNorm.includes(queryNorm) || queryNorm.includes(entryNorm)) {
+  // Substring containment is "strong" ONLY when the CONTAINED (shorter) string is
+  // a substantial fragment. Without a floor, a tiny sub-word substring graded
+  // "strong" ("TS" ⊂ "WIDGETS", "IBB" ⊂ "QUIBBLEFARB", "D" ⊂ "WIDGETS") —
+  // overstating confidence and flooding nearly every input with false "strong"
+  // matches (alert fatigue). Whole-token containment is already handled above by
+  // allQinE/allEinQ; this mid-word tier is for the space-stripped joined form and
+  // must clear the same ≥3 bar the token "weak" tier uses — here a slightly higher
+  // floor since a contiguous substring is a weaker signal than a shared whole token.
+  if (
+    Math.min(queryNorm.length, entryNorm.length) >= 5 &&
+    (entryNorm.includes(queryNorm) || queryNorm.includes(entryNorm))
+  ) {
     return "strong";
   }
   for (const t of qt) {

package/src/opengov.ts

@@ -0,0 +1,309 @@
+/**
+ * opengov.ts — OpenGov Procurement (formerly ProcureNow) public solicitations,
+ * a keyless-first SLED bid source (loop cycle — SLED bid campaign, 2026-07-19).
+ *
+ * WHAT IT ADDS: OpenGov Procurement hosts the live open-solicitation portals of
+ * **525+ US state/local governments** (cities, counties, school & special
+ * districts across 42 states + DC). The public portal SPA
+ * (`procurement.opengov.com/portal/{code}`) is served by an UNAUTHENTICATED
+ * backend REST API — the official key-gated `api-key` API is NOT used; this
+ * consumes ONLY the anonymous endpoints the public portal itself calls, so it is
+ * genuinely keyless (live-verified 2026-07-19: bare anonymous request, no api-key /
+ * auth header / cookie). It is the OpenGov sibling of the Socrata/CKAN/ArcGIS
+ * discovery tools and one of the two highest-reach keyless SLED bid feeds (with
+ * Bonfire RSS).
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (GET + POST/JSON via ADR-0014, redirect:"error") / `driftError` / `num`·`str`
+ * (coerce.ts, null-never-0 / null-never-empty) / `withMeta`·`buildMeta`,
+ * mirroring datagov-catalog.ts. KEYLESS: no key seam.
+ *
+ * ★ SSRF: the host is a compile-time literal (`OPENGOV_HOST`). All inputs ride in
+ *   a MODULE-BUILT JSON body / URLSearchParams from validated typed args — NO
+ *   raw-host/raw-path passthrough (this is a FIXED-host API). A post-construction
+ *   hostname/protocol assertion + `redirect:"error"` lock every call.
+ *
+ * ★ TWO endpoints (both anonymous, live-verified):
+ *   - `GET /api/v1/government` → a flat JSON array of ~560 org records (the whole
+ *     directory in one call; `government.code` = the portal slug). We keep the
+ *     ACTIVE, non-internal ones (~525 real public portals).
+ *   - `POST /api/v1/project/list` body `{governmentCode, publicView:true, page,
+ *     limit}` → `{projects:[…], count}`. `publicView:true` is REQUIRED (the public
+ *     gate). `count` is the TRUE total of public projects for that org.
+ *
+ * ★ HONESTY PILLARS (captured live 2026-07-19):
+ *   P1: totalAvailable = the real total — the filtered directory length (govt
+ *     list) or the API's `count` (solicitations) — NEVER the page length.
+ *   P2: getJson→fetchWithRetry THROWS on 429 / 5xx / timeout — NEVER a fake empty.
+ *     A genuine no-match (projects:[], count:0) ⇒ honest empty.
+ *   P3: every scalar via `str` (null-never-empty) / `num` (null-never-0). The
+ *     `status` enum is surfaced VERBATIM (open = currently accepting; the response
+ *     also carries pending/evaluation/closed — the CONSUMER filters; we do not
+ *     hide non-open rows or fabricate an "open count").
+ *   P4: `/government` non-array or `/project/list` `.projects` non-array ⇒
+ *     driftError; a 200 non-JSON body ⇒ schema_drift via the catch-ladder
+ *     (ToolErrorCarrier rethrow FIRST so a 429/5xx keeps its taxonomy).
+ */
+
+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";
+
+// Re-export the shared honesty coercion (num-parity guard).
+export { num };
+
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+export const OPENGOV_HOST = "api.procurement.opengov.com";
+const OPENGOV_GOVERNMENT_PATH = "/api/v1/government";
+const OPENGOV_PROJECT_LIST_PATH = "/api/v1/project/list";
+const OPENGOV_GOV_LABEL = "opengov:/api/v1/government";
+const OPENGOV_PROJ_LABEL = "opengov:/api/v1/project/list";
+const OPENGOV_SOURCE = "procurement.opengov.com via OpenGov Procurement public API (keyless)";
+const OPENGOV_PORTAL = "https://procurement.opengov.com/portal";
+
+// The org slug grammar (SSRF + injection guard). Real slugs are lowercase
+// alnum + hyphen (e.g. "santacruzca", "u-46", "twc-texas-gov"). Validated
+// BEFORE it rides the JSON body — a "../"/space/uppercase ⇒ invalid_input, 0 fetch.
+export const OPENGOV_CODE_RE = /^[a-z0-9-]{1,64}$/;
+
+const OPENGOV_STATUS_NOTE =
+  "`status` is surfaced verbatim: open = currently ACCEPTING responses; pending/evaluation/closed are also returned (publicView shows all public projects). Filter status==='open' for live bids. totalAvailable is the org's TOTAL public-project count (all statuses), not an open-only count.";
+
+// ─── The curated shapes ───────────────────────────────────────────
+export type OpengovGovernment = {
+  code: string | null;
+  name: string | null;
+  city: string | null;
+  state: string | null;
+  website: string | null;
+};
+
+export type OpengovSolicitation = {
+  id: number | null;
+  title: string | null;
+  solicitationNumber: string | null; // financialId
+  status: string | null;
+  type: string | null;
+  department: string | null;
+  releaseDate: string | null;
+  proposalDeadline: string | null; // close/due date
+  contactName: string | null;
+  link: string | null;
+};
+
+/** null-preserving boolean (a real true/false survives; else null). */
+function boolOrNull(x: unknown): boolean | null {
+  return typeof x === "boolean" ? x : null;
+}
+
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
+async function getOpengov(
+  path: string,
+  label: string,
+  init: { method?: "POST"; body?: string } = {},
+): Promise<unknown> {
+  const url = `https://${OPENGOV_HOST}${path}`;
+  const built = new URL(url);
+  if (built.hostname !== OPENGOV_HOST || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Constructed OpenGov URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(OPENGOV_HOST)} over https — refusing to fetch (SSRF safety).`,
+      retryable: false,
+      upstreamEndpoint: label,
+    });
+  }
+  const headers: Record<string, string> =
+    init.method === "POST" ? { "Content-Type": "application/json" } : {};
+  return getJson(url, { label, headers, redirect: "error", ...init });
+}
+
+// ─── Tool 1: opengov_list_governments (the directory) ─────────────
+export type OpengovListGovernmentsArgs = {
+  state?: string;
+  query?: string;
+  limit?: number;
+  offset?: number;
+};
+
+/**
+ * List the OpenGov Procurement government portals (the whole directory arrives in
+ * ONE keyless GET). Client-side filters: `state` (2-letter), `query` (name
+ * substring). Only ACTIVE, non-internal portals are kept. Feeds `code` to
+ * opengov_search_solicitations. totalAvailable = the filtered directory size (P1).
+ */
+export async function listGovernments(
+  args: OpengovListGovernmentsArgs,
+): Promise<MetaBundle> {
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+
+  let body: unknown;
+  try {
+    body = await getOpengov(OPENGOV_GOVERNMENT_PATH, OPENGOV_GOV_LABEL);
+  } catch (e) {
+    if (e instanceof ToolErrorCarrier) throw e;
+    if (e instanceof SyntaxError)
+      throw driftError(OPENGOV_GOV_LABEL, "OpenGov /government returned a non-JSON body at HTTP 200 — schema drift.");
+    throw e;
+  }
+  // P4: the response MUST be an array (a missing/object body is drift).
+  if (!Array.isArray(body)) {
+    throw driftError(OPENGOV_GOV_LABEL, "OpenGov /government shape drift — response must be a JSON array of governments.");
+  }
+
+  const stateFilter = args.state ? args.state.trim().toUpperCase() : null;
+  const queryFilter = args.query ? args.query.trim().toLowerCase() : null;
+  const filtersApplied: string[] = [];
+  if (stateFilter) filtersApplied.push("state");
+  if (queryFilter) filtersApplied.push("query");
+
+  const all: OpengovGovernment[] = [];
+  for (const row of body as unknown[]) {
+    const r = (row ?? {}) as Record<string, unknown>;
+    // Keep only active, non-internal, non-vendor real public portals.
+    if (boolOrNull(r.isActive) === false) continue;
+    if (boolOrNull(r.isInternal) === true) continue;
+    const gov = (r.government ?? {}) as Record<string, unknown>;
+    const g: OpengovGovernment = {
+      code: str(gov.code),
+      name: str(r.name),
+      city: str(r.city),
+      state: str(r.state),
+      website: str(r.website),
+    };
+    if (g.code === null) continue; // no portal slug ⇒ not queryable
+    if (stateFilter && (g.state ?? "").toUpperCase() !== stateFilter) continue;
+    if (queryFilter && !(g.name ?? "").toLowerCase().includes(queryFilter)) continue;
+    all.push(g);
+  }
+
+  const totalAvailable = all.length;
+  const page = all.slice(offset, offset + limit);
+  const returned = page.length;
+  const hasMore = offset + returned < totalAvailable;
+  const nextOffset = hasMore ? offset + returned : null;
+
+  const notes: string[] = [
+    "The full OpenGov Procurement directory is returned in one keyless call and filtered client-side; totalAvailable is the exact filtered portal count. Feed a result's `code` to opengov_search_solicitations.",
+  ];
+  if (filtersApplied.length === 0) {
+    notes.push("No filters applied — this lists ALL active OpenGov portals. Add `state` and/or `query` to scope.");
+  }
+
+  return withMeta(
+    { governments: page },
+    {
+      source: OPENGOV_SOURCE,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset, limit, hasMore, nextOffset },
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}
+
+// ─── Tool 2: opengov_search_solicitations (per org) ───────────────
+export type OpengovSearchSolicitationsArgs = {
+  governmentCode: string;
+  limit?: number;
+  offset?: number;
+};
+
+/**
+ * List an OpenGov government's public solicitations (POST /project/list with the
+ * REQUIRED publicView gate). Returns all public projects with `status` surfaced
+ * (filter status==='open' for live bids). totalAvailable = the API's `count` (the
+ * org's total public-project count — P1, never the page length).
+ */
+export async function searchSolicitations(
+  args: OpengovSearchSolicitationsArgs,
+): Promise<MetaBundle> {
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+  const code = args.governmentCode ?? "";
+
+  // Belt-and-suspenders slug grammar (behind the server's Zod). A bad slug would
+  // ride the JSON body and either error or mis-scope — reject pre-fetch (0 fetch).
+  if (!OPENGOV_CODE_RE.test(code)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Invalid OpenGov governmentCode ${JSON.stringify(code)} — expected a lowercase-alnum/hyphen portal slug (≤64 chars) from opengov_list_governments (e.g. 'santacruzca', 'u-46').`,
+      retryable: false,
+      upstreamEndpoint: OPENGOV_PROJ_LABEL,
+    });
+  }
+
+  // The API paginates by 0-based `page` + `limit`. Map our offset → page.
+  const page = Math.floor(offset / limit);
+  const servedOffset = page * limit;
+  const payload = JSON.stringify({ governmentCode: code, publicView: true, page, limit });
+
+  let body: unknown;
+  try {
+    body = await getOpengov(OPENGOV_PROJECT_LIST_PATH, OPENGOV_PROJ_LABEL, { method: "POST", body: payload });
+  } catch (e) {
+    if (e instanceof ToolErrorCarrier) throw e;
+    if (e instanceof SyntaxError)
+      throw driftError(OPENGOV_PROJ_LABEL, "OpenGov /project/list returned a non-JSON body at HTTP 200 — schema drift.");
+    throw e;
+  }
+
+  const b = (body ?? {}) as { projects?: unknown; count?: unknown };
+  // P4: `projects` MUST be an array (a missing/object projects is drift).
+  if (!Array.isArray(b.projects)) {
+    throw driftError(OPENGOV_PROJ_LABEL, "OpenGov /project/list shape drift — response.projects must be an array.");
+  }
+
+  const solicitations: OpengovSolicitation[] = (b.projects as unknown[]).map((row) => {
+    const r = (row ?? {}) as Record<string, unknown>;
+    const id = num(r.id);
+    const codeForLink = code;
+    return {
+      id,
+      title: str(r.title),
+      solicitationNumber: str(r.financialId),
+      status: str(r.status),
+      type: str(r.type),
+      department: str(r.departmentName),
+      releaseDate: str(r.releaseProjectDate ?? r.postedAt),
+      proposalDeadline: str(r.proposalDeadline),
+      contactName: [str(r.contactFirstName), str(r.contactLastName)].filter((v) => v !== null).join(" ") || null,
+      link: id !== null ? `${OPENGOV_PORTAL}/${codeForLink}/projects/${id}` : null,
+    };
+  });
+  const returned = solicitations.length;
+
+  // P1: totalAvailable = the API `count` (total public projects), NEVER page length.
+  const totalAvailable = num(b.count);
+  const hasMore =
+    totalAvailable !== null ? servedOffset + returned < totalAvailable : returned >= limit;
+  const nextOffset = hasMore ? servedOffset + returned : null;
+
+  const notes: string[] = [OPENGOV_STATUS_NOTE];
+  if (servedOffset !== offset) {
+    notes.push(`offset was snapped to the page boundary ${servedOffset} (OpenGov paginates by fixed pages of ${limit}).`);
+  }
+  if (totalAvailable === null) {
+    notes.push("totalAvailable is unknown (the API omitted `count`); completeness inferred from page fullness.");
+  }
+
+  return withMeta(
+    { governmentCode: code, solicitations },
+    {
+      source: OPENGOV_SOURCE,
+      keylessMode: true,
+      returned,
+      totalAvailable,
+      filtersApplied: ["governmentCode", "publicView"],
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      pagination: { offset: servedOffset, limit, hasMore, nextOffset },
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}