@cliwant/mcp-sam-gov 0.2.1 → 1.0.0

package/src/meta.ts

@@ -0,0 +1,292 @@
+/**
+ * @cliwant/mcp-sam-gov/meta — the `_meta` completeness/provenance convention.
+ *
+ * Why this exists
+ * ----------------
+ * These tools' outputs are consumed by an AI, not a human who can eyeball
+ * a table. For an AI consumer, silently-misleading data is strictly worse
+ * than missing data: the AI cannot tell a filtered-but-blank field from a
+ * genuinely-empty one, a hard cap from a complete list, or a swallowed
+ * error from a real zero — and will state the wrong answer confidently.
+ *
+ * Every tool's success payload therefore gains a sibling `_meta` object.
+ * `data` is UNCHANGED (backward compat): the envelope becomes
+ * `{ ok, data, _meta }` where existing consumers reading `ok`/`data.*`
+ * are 100% unaffected.
+ *
+ * See docs/research/02-truthful-outputs-spec.md §2 for the normative spec.
+ */
+
+/** Two-phase (enrich) tools: rows lost to failed per-record enrichment. */
+export type MetaDegraded = {
+  attempted: number;
+  succeeded: number;
+  failed: number;
+};
+
+/** Offset-based pagination descriptor for list/search/aggregate tools. */
+export type MetaPagination = {
+  /**
+   * The row offset of this page. `number` for offset-paginated tools (unchanged —
+   * every existing tool sets an integer). ADR-0010: widened to `number | null` for
+   * OPAQUE-CURSOR tools (GovInfo), where no meaningful numeric offset exists — those
+   * tools set `offset:null` (the honest "not a numeric offset"; continuation is via
+   * `_meta.nextCursor`, not a numeric `nextOffset`). Additive: no existing tool changes.
+   */
+  offset: number | null;
+  limit: number;
+  nextOffset: number | null;
+  hasMore: boolean;
+};
+
+/**
+ * The normative `_meta` shape (spec §2.1). Rides alongside `data` in the
+ * success envelope so the AI can branch on completeness/provenance
+ * deterministically instead of guessing from null fields.
+ */
+export type ResponseMeta = {
+  /** Human+machine label of the upstream + layer that served THIS response. */
+  source: string;
+  /** SAM tools: true when no SAM_GOV_API_KEY. Non-SAM tools: always true. */
+  keylessMode: boolean;
+  /** true iff this response contains the ENTIRE result set for the query. */
+  complete: boolean;
+  /** true iff a hard cap / top-N limited the rows. */
+  truncated: boolean;
+  /** Number of primary records in `data`. */
+  returned: number;
+  /** Upstream's total match count; null when the endpoint doesn't report it. */
+  totalAvailable: number | null;
+  /**
+   * Present (and true) when `totalAvailable` is a KNOWN LOWER BOUND rather than
+   * an exact count — i.e. the upstream reported the total as "≥ N" (e.g. SEC
+   * EDGAR full-text search returns `hits.total.relation: "gte"` with the value
+   * pinned at 10000). The true total is UNKNOWN and ≥ `totalAvailable`. Absent
+   * on endpoints that report an exact total (do NOT read absence as `false`
+   * meaning "exact" for tools that never set it — it is simply not applicable).
+   */
+  totalIsLowerBound?: boolean;
+  /**
+   * Present (and true) when `totalAvailable` (or, for CKAN, the value disclosed
+   * in `notes`) is an upstream STATISTICAL ESTIMATE rather than an exact count —
+   * i.e. the source reported the total as an approximation that may be ABOVE OR
+   * BELOW the true count (CKAN `datastore_search` returns `total_was_estimated:
+   * true` for a PostgreSQL `reltuples`-style estimate, live-verified to overshoot
+   * — so it is NOT a lower bound, unlike `totalIsLowerBound`). CKAN sets this on
+   * the estimated path alongside `totalAvailable:null` (the estimate never drives
+   * pagination — ADR-0006 B1) + a disclosing note carrying the estimate value.
+   * Absent on endpoints that report an exact total (do NOT read absence as
+   * `false` meaning "exact" for tools that never set it — it is not applicable).
+   */
+  totalIsEstimated?: boolean;
+  /**
+   * Present when this response comes from an OPAQUE-CURSOR-paginated source
+   * (ADR-0010 — GovInfo's `offsetMark`): the opaque continuation token to pass back
+   * to fetch the NEXT page (GovInfo: as the `pageMark` argument), or `null` on the
+   * last page (no further cursor). It is a source-minted token, NOT derived from any
+   * secret and NEVER the raw upstream `nextPage` URL (which embeds pageSize + the
+   * api_key). Cursor tools set `nextOffset:null`/`offset:null` (a numeric offset is
+   * meaningless for a cursor) and use THIS as the sole continuation surface. Absent
+   * on offset-paginated tools (do NOT read absence as "no more" for those). Added as
+   * a conditional passthrough exactly like totalIsLowerBound/totalIsEstimated —
+   * only surfaced when the tool provides it, so existing tools' `_meta` stays
+   * byte-identical and the tools/list snapshot is unaffected (it is a runtime `_meta`
+   * field, not part of any tool's input schema).
+   */
+  nextCursor?: string | null;
+  /** Request filters the upstream verifiably honored. */
+  filtersApplied: string[];
+  /** Request filters sent but NOT honored (results are unfiltered on these). */
+  filtersDropped: string[];
+  /** Fields null/absent BY LIMITATION (keyless/endpoint), not "no data". */
+  fieldsUnavailable: string[];
+  /** Two-phase tools only: rows for which per-record detail was fetched. */
+  enrichedCount?: number;
+  /** Two-phase tools: enrichment accounting (see MetaDegraded). */
+  degraded?: MetaDegraded;
+  /** Present on list/search/aggregate tools. */
+  pagination?: MetaPagination;
+  /**
+   * P5 PROVENANCE (ADR-0045 B2/M1). The access path that served THIS response:
+   * `"live"` (the current, and in Phase 1 the ONLY, path) or `"snapshot"` (a
+   * self-hosted cache served when the live upstream was unreachable). Set by the
+   * resilience port's provenance-returning primitive, then threaded by the
+   * adapter ONLY when NON-live — so a live response OMITS this field entirely and
+   * stays byte-identical to pre-P5 output. Surfaced via the guarded
+   * `if (partial.dataPath !== undefined)` passthrough below (NO `??` default).
+   * Absent ⇒ live; do NOT read absence as any other value. Freshness enum, not a
+   * topology label (M2): an independent host serving live data is still `"live"`.
+   */
+  dataPath?: "live" | "snapshot";
+  /**
+   * P5 FRESHNESS (ADR-0045 m3). ISO-8601 UTC timestamp of when a NON-live
+   * (`snapshot`) body was retrieved from the origin — the as-of instant for
+   * deterministic cross-tool freshness comparison. Present ONLY alongside a
+   * non-live `dataPath`; absent on a live response (byte-identical). When a
+   * snapshot carries a `totalAvailable`, it is qualified as an as-of figure via
+   * the existing `totalIsEstimated` flag (m1 forbids a dedicated `totalAsOf`
+   * field — the only NEW P5 fields are `dataPath` and `asOf`).
+   */
+  asOf?: string;
+  /** Short, AI-actionable caveats (natural language). */
+  notes: string[];
+};
+
+/**
+ * Build a fully-populated, invariant-consistent ResponseMeta from a partial.
+ *
+ * Safe defaults (spec §2.1): a tool that supplies nothing gets a truthful,
+ * "single-record / known-complete" meta (`complete:true, truncated:false`).
+ *
+ * The server (or the caller) hands over whatever it knows; this helper fills
+ * the rest and then ENFORCES the §2.1 invariants so the flags the AI trusts
+ * are internally consistent:
+ *   - `complete === true`  ⟺  NOT truncated AND filtersDropped empty AND
+ *     (no pagination OR hasMore===false) AND (no degraded OR failed===0).
+ *   - If totalAvailable is known and returned < totalAvailable ⇒
+ *     complete:false, truncated:true.
+ *   - filtersDropped non-empty ⇒ at least one note is present.
+ */
+export function buildMeta(partial: Partial<ResponseMeta> = {}): ResponseMeta {
+  const source = partial.source ?? "unknown";
+  const keylessMode = partial.keylessMode ?? true;
+  const returned = partial.returned ?? 0;
+  const totalAvailable =
+    partial.totalAvailable === undefined ? null : partial.totalAvailable;
+  const filtersApplied = partial.filtersApplied ?? [];
+  const filtersDropped = partial.filtersDropped ?? [];
+  const fieldsUnavailable = partial.fieldsUnavailable ?? [];
+  const notes = partial.notes ? [...partial.notes] : [];
+  const pagination = partial.pagination;
+  const degraded = partial.degraded;
+
+  // --- Derive truncated -------------------------------------------------
+  // A known total that exceeds what we returned proves truncation.
+  const totalProvesTruncation =
+    totalAvailable !== null && returned < totalAvailable;
+  const paginationHasMore = pagination ? pagination.hasMore : false;
+  let truncated =
+    partial.truncated ?? (totalProvesTruncation || paginationHasMore);
+  if (totalProvesTruncation || paginationHasMore) truncated = true;
+
+  // --- P5 provenance (ADR-0045 B2/M1) -----------------------------------
+  // A NON-live response (a snapshot served because the live upstream was
+  // unreachable) is honesty-qualified below. For a live/absent dataPath this
+  // whole strand is INERT — `nonLiveProvenance` is false, so `complete`, the
+  // notes[], and totalIsEstimated are all derived EXACTLY as before P5 (Phase 1:
+  // no adapter threads a dataPath ⇒ byte-identical output on every one of the
+  // 110 tools).
+  const nonLiveProvenance =
+    partial.dataPath !== undefined && partial.dataPath !== "live";
+
+  // --- Derive complete (single source of truth = the §2.1 invariant) ----
+  const degradedLoss = degraded ? degraded.failed > 0 : false;
+  const derivedComplete =
+    !truncated &&
+    filtersDropped.length === 0 &&
+    !paginationHasMore &&
+    !degradedLoss &&
+    !totalProvesTruncation &&
+    // M1a: `complete` is defined against the LIVE result set (:53), so a snapshot
+    // can NEVER claim complete:true — gate the derivation behind a live/absent
+    // dataPath. (Inert for live: `!false` === true, no change.)
+    !nonLiveProvenance;
+  // Honor an explicit complete:false, but never let a caller claim
+  // complete:true when the invariant says otherwise.
+  const complete =
+    partial.complete === false ? false : derivedComplete;
+
+  // --- Invariant: filtersDropped non-empty ⇒ a note explaining it -------
+  if (filtersDropped.length > 0 && notes.length === 0) {
+    notes.push(
+      `The following requested filters were NOT applied by the upstream and the results are unfiltered on them: ${filtersDropped.join(", ")}. Treat these results as unfiltered on those facets.`,
+    );
+  }
+
+  // --- P5 (ADR-0045 M1c/m1): staleness note on a non-live response ------
+  // Push into the EXISTING notes[] (m1 killed the separate `stalenessNote`
+  // field). Inert for live/absent dataPath. Names the as-of instant when known.
+  if (nonLiveProvenance) {
+    const asOfPhrase = partial.asOf ? ` (as of ${partial.asOf})` : "";
+    notes.push(
+      `Live upstream was unreachable — this response is served from a ${partial.dataPath} snapshot${asOfPhrase}. Freshness is NOT guaranteed; treat completeness and totals as of the snapshot time, not live.`,
+    );
+  }
+
+  const meta: ResponseMeta = {
+    source,
+    keylessMode,
+    complete,
+    truncated,
+    returned,
+    totalAvailable,
+    filtersApplied,
+    filtersDropped,
+    fieldsUnavailable,
+    notes,
+  };
+  if (partial.enrichedCount !== undefined)
+    meta.enrichedCount = partial.enrichedCount;
+  if (degraded) meta.degraded = degraded;
+  if (pagination) meta.pagination = pagination;
+  // Conditional passthrough (like enrichedCount/pagination): only surfaced when
+  // the tool provides it, so existing tools' `_meta` output stays byte-identical.
+  if (partial.totalIsLowerBound !== undefined)
+    meta.totalIsLowerBound = partial.totalIsLowerBound;
+  // Conditional passthrough (identical shape to totalIsLowerBound above): only
+  // surfaced when the tool provides it (CKAN's estimated-total path), so every
+  // existing tool's `_meta` output stays byte-identical. NO new derivation logic.
+  if (partial.totalIsEstimated !== undefined)
+    meta.totalIsEstimated = partial.totalIsEstimated;
+  // Conditional passthrough (IDENTICAL shape to totalIsLowerBound/totalIsEstimated
+  // above): only surfaced when the tool provides it (GovInfo's opaque-cursor path),
+  // so every existing tool's `_meta` output stays byte-identical. NO new derivation
+  // logic — the value (the offsetMark token, or null on the last page) is set by the
+  // cursor tool and passed through verbatim.
+  if (partial.nextCursor !== undefined) meta.nextCursor = partial.nextCursor;
+  // P5 provenance passthrough (ADR-0045 B2) — IDENTICAL guarded idiom to
+  // totalIsLowerBound/nextCursor above: surfaced ONLY when the adapter provides
+  // it, so every existing (live, dataPath-absent) tool `_meta` stays
+  // byte-identical. NO `??` default. In Phase 1 no adapter threads these ⇒ inert.
+  if (partial.dataPath !== undefined) meta.dataPath = partial.dataPath;
+  if (partial.asOf !== undefined) meta.asOf = partial.asOf;
+  // M1b: a snapshot's totalAvailable is an as-of figure, NOT a live exact total —
+  // qualify it via the EXISTING totalIsEstimated flag (m1 forbids a new
+  // totalAsOf field) so an AI never reads it as a live count. Only when a total
+  // is actually present. Inert for live (nonLiveProvenance false).
+  if (nonLiveProvenance && totalAvailable !== null) meta.totalIsEstimated = true;
+  return meta;
+}
+
+/**
+ * Branded wrapper a tool handler returns to attach `_meta` to its payload.
+ *
+ * A handler may return either its raw domain object (server synthesizes a
+ * minimal truthful default) OR `withMeta(data, partialMeta)`. The brand lets
+ * the server distinguish "handler attached meta" from "domain object that
+ * happens to have `data`/`_meta` keys" with zero ambiguity.
+ */
+export class MetaBundle<T = unknown> {
+  readonly __isMetaBundle = true as const;
+  constructor(
+    readonly data: T,
+    readonly meta: Partial<ResponseMeta>,
+  ) {}
+}
+
+/** Attach a partial `_meta` to a handler's `data`. Server finalizes it. */
+export function withMeta<T>(
+  data: T,
+  meta: Partial<ResponseMeta>,
+): MetaBundle<T> {
+  return new MetaBundle(data, meta);
+}
+
+/** Type guard: did the handler hand back a MetaBundle? */
+export function isMetaBundle(v: unknown): v is MetaBundle {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __isMetaBundle?: unknown }).__isMetaBundle === true
+  );
+}

package/src/nih.ts

@@ -0,0 +1,375 @@
+/**
+ * NIH RePORTER v2 — federal research-GRANT project records (keyless).
+ *
+ * A NEW capability axis: **federal research-funding footprint by organization /
+ * UEI / state** — awarded NIH project money keyed to a recipient org (with UEI +
+ * DUNS), a recipient-ENRICHMENT layer orthogonal to the spend/contract/regulatory
+ * sources. It joins the SAM/USAspending recipient graph via `primary_uei` (the
+ * SAME UEI space) — but the award nature DIFFERS (grants fund research, not
+ * goods/services), so every response carries the grant-vs-contract caveat (M2).
+ *
+ * ON-DOMAIN HONESTY: this is research-funding / grants-adjacent, the AWARDED-money
+ * sibling of grants.gov opportunities and the biomedical-R&D slice of USAspending
+ * assistance awards — NOT core procurement. Positioned as recipient-enrichment /
+ * R&D market intel, never as a contract source.
+ *
+ * THE R2 PORT'S FIRST NON-GET CONSUMER (ADR-0014): NIH RePORTER is a
+ * POST-with-JSON-body API. `getJson` (ADR-0005) gained a byte-neutral,
+ * backward-compatible `method`/`body` passthrough for exactly this; this module
+ * writes ZERO fetch/coercion/error code — it REUSES `getJson` / `driftError` /
+ * `num`·`str` / `withMeta` and COPIES (does not import) the fixed-host SSRF +
+ * honesty PATTERN from CKAN/ECHO/FPDS, adapted:
+ *
+ * ★ SSRF GUARD (policy① — the SMALLEST surface of any source): the request URL is
+ * a compile-time CONSTANT (fixed host `api.reporter.nih.gov` + fixed path
+ * `/v2/projects/search`); NO caller input touches it. All filters ride in the POST
+ * body, which is MODULE-BUILT from a validated typed criteria object then
+ * `JSON.stringify`'d — there is NO raw-body / raw-criteria passthrough, so a
+ * caller value cannot break out of its criterion into another key. A
+ * post-construction hostname/protocol assertion + `redirect:"error"` lock it
+ * (fail closed on any off-host 3xx; its body is never read).
+ *
+ * ★ FILTER HONESTY (M1 — the load-bearing discipline): a criterion is shipped ONLY
+ * after being LIVE-CONFIRMED to actually narrow the result set. The confirmed
+ * v1 set is `orgStates` + `orgNames` + `fiscalYears` (each live-verified to
+ * reduce the total below the unfiltered baseline). `agency_ic_codes` is EXCLUDED
+ * — it is silently DROPPED upstream (a filter that no-ops is never presented as
+ * applied). A shipped filter goes in `_meta.filtersApplied`; a silent-drop filter
+ * is never listed there and never exposed in the schema.
+ *
+ * ★ 15,000-RECORD RETRIEVAL WINDOW (M3+M4 — the critical disclosure): NIH caps
+ * keyless retrieval at `offset 0..14,999` (`limit ≤ 500`), so only the first
+ * 15,000 records of any result set are reachable. This is a cap on RETRIEVAL, NOT
+ * on the COUNT: `meta.total` stays EXACT (never truncated to 15,000, never marked
+ * `totalIsLowerBound`). `offset >= 15,000` is refused pre-fetch (`invalid_input`);
+ * after a page, `nextOffset` is null once `offset+returned` reaches the cap or the
+ * exact total (never a dead-end `nextOffset=15000`). `truncated` is derived by
+ * buildMeta from `returned < totalAvailable`; when the count exceeds the window a
+ * `_meta.notes` line discloses the unreachable remainder and recommends narrowing.
+ *
+ * ★ HONESTY `_meta`: shape-guard FIRST (a 200 body that is not `{meta,results:[]}`
+ * → driftError, NEVER a fake empty); a non-numeric/absent `meta.total` →
+ * driftError BEFORE `num(meta.total)`; genuine-empty (`total:0`) → complete:true /
+ * totalAvailable:0; outage/5xx/timeout → getJson throws; 400 (bad offset/limit/
+ * type) → invalid_input (surfaced, never `[]`). `num` is null-never-0 on
+ * `award_amount` (a real $0 award is 0; an absent amount is null). Every response
+ * discloses the grant-vs-contract caveat + a data-currency note.
+ */
+
+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 (single audited copy in ./coerce.js —
+// ADR-0005 v2 FIX-C) so the fault suite's num-parity guard resolves the SAME
+// `num` (nih.num === coerce.num === treasury.num — a num regression fails together).
+export { num };
+
+// ─── Fixed endpoint (SSRF core — a compile-time CONSTANT) ─────────
+const NIH_HOST = "api.reporter.nih.gov";
+const NIH_PATH = "/v2/projects/search";
+const NIH_PROJECTS_URL = `https://${NIH_HOST}${NIH_PATH}`;
+// HOST-only-ish label (path is fixed + carries no token — keyless). Surfaces in
+// ToolError.upstreamEndpoint; no secret can appear here (the API is anonymous).
+const NIH_LABEL = "nih:/v2/projects/search";
+
+// ─── The 15,000-record RETRIEVAL window (live-verified: offset ≤ 14,999,
+// limit ≤ 500). A cap on RETRIEVAL, not on the exact meta.total count. The
+// limit ≤ 500 ceiling is enforced by the server's Zod schema; this module owns
+// the offset-window guard + the never-a-dead-end nextOffset boundary. ──
+const RETRIEVAL_CAP = 15_000;
+
+// ─── Frozen US state/territory 2-letter USPS enum (UPPERCASE-only) ─
+// Built FROM this array by the Zod enum in server.ts (single source of truth).
+// It is BOTH an org_states value guard AND the silent-zero guard: live, an unknown
+// but well-typed value (e.g. "ZZ") returns a genuine total:0 indistinguishable
+// from a real empty, and a lowercase "ca" silently returns zeros — so a typo must
+// be an invalid_input, never read as "no NIH funding" (a silent honesty failure).
+export const NIH_ORG_STATES = [
+  "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL",
+  "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME",
+  "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH",
+  "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI",
+  "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI",
+  "WY", "AS", "GU", "MP", "PR", "VI",
+] as const;
+
+export type NihOrgState = (typeof NIH_ORG_STATES)[number];
+
+// ─── Disclosure constants (honesty obligations) ──────────────────
+/** M2 — the mandatory grant-vs-contract caveat carried in EVERY response. */
+const NIH_GRANT_CAVEAT =
+  "NIH RePORTER records are RESEARCH GRANTS awarded by NIH, NOT federal procurement contracts. The primary_uei joins to SAM/USAspending recipient records, but the award nature differs (grants fund research, not goods/services) — do not present these amounts as contract awards.";
+
+/** m-currency — a conservative data-currency note (not API-verifiable). */
+const DATA_CURRENCY_NOTE =
+  "NIH RePORTER updates on a rolling basis; per-record refresh lag is not API-verifiable.";
+
+/** The UEI join disclosure — how to bridge to the SAM/USAspending recipient graph. */
+const UEI_JOIN_NOTE =
+  "organization.primaryUei is the join key to SAM entities and USAspending recipients (same UEI space); a grant recipient is not necessarily a federal contractor.";
+
+/** M3+M4 — the retrieval-window disclosure when the count exceeds the 15,000 cap. */
+function retrievalCapNote(total: number): string {
+  return `NIH caps keyless retrieval at the first ${RETRIEVAL_CAP} of ${total} matching records; the count is EXACT but records beyond ${RETRIEVAL_CAP} cannot be retrieved via this API — narrow criteria (org, fiscal year, state) to bring the target set under ${RETRIEVAL_CAP}.`;
+}
+
+const SOURCE = "api.reporter.nih.gov v2 (keyless)";
+
+// ─── Record shape (recipient-enrichment payload) ─────────────────
+export type NihPrincipalInvestigator = {
+  profileId: number | null;
+  firstName: string | null;
+  lastName: string | null;
+  fullName: string | null;
+  isContactPi: boolean | null;
+  title: string | null;
+};
+
+export type NihProject = {
+  projectNum: string | null;
+  projectTitle: string | null;
+  fiscalYear: number | null;
+  awardAmount: number | null;
+  awardType: string | null;
+  activityCode: string | null;
+  isActive: boolean | null;
+  organization: {
+    name: string | null;
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    /** The SAM/USAspending recipient join key (but grant ≠ contract — M2). */
+    primaryUei: string | null;
+    primaryDuns: string | null;
+    ueis: string[];
+    duns: string[];
+  };
+  principalInvestigators: NihPrincipalInvestigator[];
+  contactPiName: string | null;
+  fundingIc: {
+    code: string | null;
+    abbreviation: string | null;
+    name: string | null;
+  };
+};
+
+/** "true"/true → true, "false"/false → false, absent/other → null (never a
+ *  fabricated false). */
+function boolOrNull(x: unknown): boolean | null {
+  if (x === true) return true;
+  if (x === false) return false;
+  if (x === "true") return true;
+  if (x === "false") return false;
+  return null;
+}
+
+/** A 2-letter uppercase string array from a mixed value, else []. */
+function strArray(x: unknown): string[] {
+  if (!Array.isArray(x)) return [];
+  return x.map((v) => str(v)).filter((v): v is string => v !== null);
+}
+
+/** Map ONE NIH results[] row → the curated enrichment shape. Every scalar is
+ *  null-never-fabricated (str/num); `award_amount` is num (a real $0 → 0, absent
+ *  → null). Field names are NIH v2 documented keys; an absent field maps to null
+ *  (honest "unknown"), never a crash. */
+function mapProject(raw: unknown): NihProject {
+  const r = (raw ?? {}) as Record<string, unknown>;
+  const org = (r.organization ?? {}) as Record<string, unknown>;
+  const ic = (r.agency_ic_admin ?? {}) as Record<string, unknown>;
+  const pis = Array.isArray(r.principal_investigators)
+    ? (r.principal_investigators as Record<string, unknown>[])
+    : [];
+  return {
+    projectNum: str(r.project_num),
+    projectTitle: str(r.project_title),
+    fiscalYear: num(r.fiscal_year),
+    awardAmount: num(r.award_amount),
+    awardType: str(r.award_type),
+    activityCode: str(r.activity_code),
+    isActive: boolOrNull(r.is_active),
+    organization: {
+      name: str(org.org_name),
+      city: str(org.org_city),
+      state: str(org.org_state),
+      country: str(org.org_country),
+      primaryUei: str(org.primary_uei),
+      primaryDuns: str(org.primary_duns),
+      ueis: strArray(org.org_ueis),
+      duns: strArray(org.org_duns),
+    },
+    principalInvestigators: pis.map((p) => ({
+      profileId: num(p.profile_id),
+      firstName: str(p.first_name),
+      lastName: str(p.last_name),
+      fullName: str(p.full_name),
+      isContactPi: boolOrNull(p.is_contact_pi),
+      title: str(p.title),
+    })),
+    contactPiName: str(r.contact_pi_name),
+    fundingIc: {
+      code: str(ic.code),
+      abbreviation: str(ic.abbreviation),
+      name: str(ic.name),
+    },
+  };
+}
+
+// ─── The confirmed criteria surface (v1) ─────────────────────────
+export type NihSearchArgs = {
+  orgStates?: NihOrgState[];
+  orgNames?: string[];
+  fiscalYears?: number[];
+  limit?: number;
+  offset?: number;
+};
+
+/**
+ * Search awarded NIH research projects (POST /v2/projects/search). Structured,
+ * LIVE-CONFIRMED-narrowing criteria only (orgStates / orgNames / fiscalYears),
+ * AND-combined in a MODULE-BUILT criteria object → JSON.stringify (no raw
+ * passthrough). Returns curated recipient-enrichment rows + honest `_meta`:
+ * exact totalAvailable, exact within-window pagination, the 15,000-retrieval-cap
+ * disclosure when the count exceeds it, and the mandatory grant-vs-contract
+ * caveat. Disclose-not-refuse: an unscoped query is NOT refused — it returns the
+ * first page + the exact total + a note recommending a criterion when the total
+ * exceeds the window.
+ */
+export async function searchProjects(args: NihSearchArgs): Promise<MetaBundle> {
+  const limit = args.limit ?? 50;
+  const offset = args.offset ?? 0;
+
+  // ── 15k window pre-fetch guard (M3): offset >= 15,000 is UNREACHABLE — refuse
+  //    BEFORE any fetch (also enforced by the server's Zod .max(14_999); this is
+  //    the belt-and-suspenders module guard so a direct caller can't slip past). ──
+  if (offset >= RETRIEVAL_CAP) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `NIH RePORTER caps pagination at the first ${RETRIEVAL_CAP} records (offset 0..${RETRIEVAL_CAP - 1}); offset ${offset} is unreachable via this keyless API. Narrow criteria (org, fiscal year, state) to bring the target set under ${RETRIEVAL_CAP}.`,
+      retryable: false,
+      upstreamEndpoint: NIH_LABEL,
+    });
+  }
+
+  // ── Build the criteria object from VALIDATED typed input (SSRF: no raw
+  //    passthrough; every value is enum/typed by the server's Zod before here). A
+  //    filter is added — and listed in filtersApplied — ONLY when it is one of the
+  //    LIVE-CONFIRMED narrowing criteria (M1). agency_ic_codes is never built (it
+  //    silently no-ops upstream and is not in the schema). ──
+  const criteria: Record<string, unknown> = {};
+  const filtersApplied: string[] = [];
+  if (args.fiscalYears && args.fiscalYears.length > 0) {
+    criteria.fiscal_years = args.fiscalYears;
+    filtersApplied.push("fiscalYears");
+  }
+  if (args.orgStates && args.orgStates.length > 0) {
+    criteria.org_states = args.orgStates;
+    filtersApplied.push("orgStates");
+  }
+  if (args.orgNames && args.orgNames.length > 0) {
+    criteria.org_names = args.orgNames;
+    filtersApplied.push("orgNames");
+  }
+
+  const payload = { criteria, limit, offset };
+
+  // ── SSRF belt-and-suspenders: the URL is a compile-time constant, but assert it
+  //    cannot have drifted (a future typo) — exactly the CKAN/FPDS post-construction
+  //    check, adapted (no URLSearchParams: there are no query params). ──
+  const built = new URL(NIH_PROJECTS_URL);
+  if (built.hostname !== NIH_HOST || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      message: `Constructed NIH URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${NIH_HOST} over https — refusing to fetch (SSRF safety).`,
+      retryable: false,
+      upstreamEndpoint: NIH_LABEL,
+    });
+  }
+
+  // ── The R2 port's first POST call. Content-Type is MANDATORY for NIH (415
+  //    without it, 405 on GET). redirect:"error" fails closed on any off-host 3xx
+  //    (its body is never read). The body is the module-built, JSON.stringify'd
+  //    typed payload — never string-concatenated. ──
+  const body = await getJson<unknown>(NIH_PROJECTS_URL, {
+    label: NIH_LABEL,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+    redirect: "error",
+  });
+
+  // ── Shape guard FIRST → THROW (never fake-empty). A 200 body must be an OBJECT
+  //    with a `meta` object and an array `results`. An array body (a 200-with-array
+  //    drift), a missing `meta`, or a non-array `results` → driftError; NEVER read
+  //    `results` as []. ──
+  if (
+    typeof body !== "object" ||
+    body === null ||
+    Array.isArray(body)
+  ) {
+    throw driftError(
+      NIH_LABEL,
+      "NIH /v2/projects/search returned a 200 body that is not an object {meta,results} (an array or scalar) — refusing to report it as an empty result.",
+    );
+  }
+  const b = body as { meta?: unknown; results?: unknown };
+  if (typeof b.meta !== "object" || b.meta === null || !Array.isArray(b.results)) {
+    throw driftError(
+      NIH_LABEL,
+      "NIH /v2/projects/search returned an unexpected shape (expected an object with a `meta` object and an array `results`).",
+    );
+  }
+  const meta = b.meta as { total?: unknown };
+
+  // ── m-total-guard: a non-number `meta.total` (or absent) is drift — num() cannot
+  //    tell a non-number from an absent one, so typeof-check BEFORE num() (CKAN m6).
+  //    Nothing trustworthy to report as a total → THROW, never proceed with null. ──
+  if (typeof meta.total !== "number") {
+    throw driftError(
+      NIH_LABEL,
+      "NIH meta.total absent/non-numeric — nothing trustworthy to report as a total (treating as schema drift).",
+    );
+  }
+  // EXACT total (§1a) — NEVER results.length, NEVER a lower bound. num() defensively
+  // (a finite number passes through; a non-finite would be caught, but the typeof
+  // guard above already rejected non-numbers).
+  const totalAvailable = num(meta.total);
+
+  const projects = (b.results as unknown[]).map(mapProject);
+  const returned = projects.length;
+
+  // ── Pagination (M3+M4): NEVER hand a dead-end nextOffset=15000. nextOffset is
+  //    null once offset+returned reaches the cap OR the exact total; hasMore mirrors
+  //    it. NO mid-page clamp (offset+limit>15000 does NOT 400 — only offset≥15000). ──
+  const candidateNext = offset + returned;
+  const nextOffset =
+    candidateNext >= RETRIEVAL_CAP ||
+    (totalAvailable !== null && candidateNext >= totalAvailable)
+      ? null
+      : candidateNext;
+  const hasMore = nextOffset !== null;
+
+  const notes: string[] = [NIH_GRANT_CAVEAT, UEI_JOIN_NOTE, DATA_CURRENCY_NOTE];
+  // Disclose-not-refuse + the reachability-cap disclosure: fire whenever the exact
+  // count exceeds the reachable window (records beyond 15,000 are UNREACHABLE — the
+  // honest superset of "truncated by the cap" and "an unscoped broad query").
+  if (totalAvailable !== null && totalAvailable > RETRIEVAL_CAP) {
+    notes.push(retrievalCapNote(totalAvailable));
+  }
+
+  const metaOut: Partial<ResponseMeta> = {
+    source: SOURCE,
+    keylessMode: true,
+    returned,
+    totalAvailable,
+    filtersApplied,
+    filtersDropped: [],
+    fieldsUnavailable: [],
+    pagination: { offset, limit, hasMore, nextOffset },
+    notes,
+  };
+
+  return withMeta({ projects }, metaOut);
+}