@cliwant/mcp-sam-gov 0.2.1 → 1.0.0

package/dist/clinicaltrials.js

@@ -0,0 +1,730 @@
+/**
+ * clinicaltrials.ts — ClinicalTrials.gov API v2 (`clinicaltrials.gov/api/v2`) —
+ * federally-registered clinical-research studies with LEAD-SPONSOR / COLLABORATOR
+ * / ORGANIZATION / FUNDING-SOURCE entity enrichment. ADR-0021. Source #21 on the
+ * R2 `getJson` GET port (a plain keyless GET — no key, no signup, no UA).
+ *
+ * WHAT IT ADDS: the trial-REGISTRATION axis of the research-funding entity layer
+ * already served by NIH RePORTER (ADR-0014) + NSF Awards (ADR-0020). The
+ * `leadSponsor` / `collaborators` / `organization` here are the pharma / biotech /
+ * university / agency entities that ALSO receive federal grants/contracts — the
+ * study-registration SIBLING of the grant sources, not a duplicate. On-mission =
+ * the ENTITY/sponsor/funding dimension (NOT the clinical minutiae).
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (redirect:"error", a plain GET) / `driftError` / `num`·`str` (coerce.ts,
+ * null-never-0 / null-never-empty-string) / `withMeta`·`buildMeta` /
+ * `ResponseMeta.nextCursor`, and COPIES (does NOT import) the GovInfo opaque-cursor
+ * honesty + the fixed-host SSRF idiom into the single audited `getCT` helper [M2].
+ *
+ * ★ SSRF ([M2] — one audited fetch home): BOTH tools route through `getCT(path,
+ *   label, params)`. The host is a compile-time literal (`CT_BASE`); every filter
+ *   rides in a MODULE-BUILT `URLSearchParams` (each value URLSearchParams-encoded)
+ *   assembled key-by-key from validated typed args — NO raw-query passthrough. The
+ *   single-study path segment `nctId` is regex-validated `^NCT\d{8}$` BEFORE the
+ *   path is built (a `../` / `%2F` / non-matching id → invalid_input, 0 fetch —
+ *   mirror edgar `buildFramesUrl` S1/S2). A post-construction hostname/protocol
+ *   assertion + `redirect:"error"` lock it (fail closed on any off-host 3xx).
+ *
+ * ★ THE THREE HONESTY FACTS (LIVE-verified 2026-07-12, keyless plain GET, this IP):
+ *   1. `totalCount` is EXACT + filter-respecting + UNCAPPED — but OMITTED unless
+ *      `countTotal=true` is sent (default keys = [studies, nextPageToken]). So the
+ *      module ALWAYS sends `countTotal=true`; `totalAvailable = num(totalCount)`
+ *      (a genuine 0 → 0, NEVER null, NEVER studies.length); a missing/non-number
+ *      totalCount on a countTotal=true call ⇒ schema_drift. (cancer=142304,
+ *      unfiltered=593334 — an exact non-round number, no saturation cap.)
+ *   2. Pagination is an OPAQUE cursor (`nextPageToken`). Terminal = token ABSENT
+ *      (BOTH genuine-empty AND a single-complete-page omit it — live-verified
+ *      progeria total=10/returned=10/no token). `nextCursor` is passed back
+ *      VERBATIM as the `pageToken` argument (never fabricated/derived); a bad
+ *      token loud-fails at HTTP 400 ⇒ getJson THROWS (never a silent-empty cursor).
+ *      offset/nextOffset are null (meaningless for a cursor). CT's terminal is
+ *      token-absent — there is NO GovInfo-style `"*"` sentinel.
+ *   3. An INVALID `funderType` SILENTLY returns `totalCount:0` at HTTP 200 (NOT a
+ *      400 — contrast a bad overallStatus / pageToken / aggFilters-KEY, which all
+ *      400). So `funderType` is a FROZEN 4-value enum ([M1] re-validated IN THE
+ *      HANDLER, not only in Zod) — a non-member ⇒ invalid_input PRE-fetch, 0
+ *      network call, NEVER passed through to be read as a genuine empty.
+ *
+ * ★ [M1] IN-HANDLER ENUM RE-GUARD: `funderType` AND `overallStatus` are re-checked
+ *   against the frozen CT enum arrays INLINE in the search handler (throw
+ *   invalid_input pre-fetch, 0 fetch) — closing the funderType silent fake-empty
+ *   even on a Zod-BYPASSING direct handler call (mirror govinfo's in-handler
+ *   collection re-check).
+ *
+ * ★ TOKENIZATION is AND-conjunctive for query.term/query.spons/query.cond, and CT
+ *   splits on whitespace AND a PUNCTUATION set (NOT whitespace alone) — live-verified
+ *   2026-07-12: `query.spons=sanofi<delim>aventis` == the whitespace count (3) for
+ *   space + `- , / ; + & | @ # =`; `. : _ '` do NOT split. So a single-token-LOOKING
+ *   compound like "Sanofi-Aventis" is really 'Sanofi' AND 'Aventis' (→3 vs Sanofi
+ *   →3416 — a ~1000× silent false-negative). A multi-TOKEN value (tokenized via the
+ *   shared tokenizeForDisclosure / DISCLOSURE_SPLIT_RE, not just whitespace) fires a
+ *   MANDATORY `_meta` AND-note (the mirror of NSF's OR-note, but AND); a multi-token
+ *   sponsor SUPPRESSES the
+ *   contradictory "matches more variants" broadening note (CT NARROWED, not broadened).
+ *
+ * ★ funderType facets OVERLAP (non-exclusive: nih+fed+industry+other sum >
+ *   registry total) — a `_meta` note forbids summing them into a partition.
+ *
+ * ★ trial ≠ federal award (EVERY response): a registration is NOT an award;
+ *   leadSponsor.name is FREE TEXT (not a UEI) → a NOMINAL name match only.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { tokenizeForDisclosure } from "./disclosure.js";
+import { withMeta } 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` (clinicaltrials.num === coerce.num — a num regression fails together;
+// NO local num/str in this module).
+export { num };
+// Re-export the shared disclosure tokenizer (single audited copy in
+// ./disclosure.js — ADR-0022) so the fault suite's parity guard resolves the SAME
+// function (clinicaltrials.tokenizeForDisclosure === nsf.tokenizeForDisclosure ===
+// disclosure.tokenizeForDisclosure — a class regression fails both suites at once).
+export { tokenizeForDisclosure } from "./disclosure.js";
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+const CT_HOST = "clinicaltrials.gov";
+// The FIXED base literal (host + api version). All paths interpolate off this.
+const CT_BASE = "https://clinicaltrials.gov/api/v2";
+const CT_STUDIES_PATH = "/studies";
+// HOST+path label (keyless ⇒ no token can ever appear). Surfaces in
+// ToolError.upstreamEndpoint.
+const CT_LABEL = "clinicaltrials:/api/v2/studies";
+// ADR-0024 — the facet-counts endpoint (per-field value distribution), a SIBLING
+// path on the SAME fixed host, routed through the SAME audited getCT helper. Its
+// own HOST+path label (keyless ⇒ no token) so ToolError.upstreamEndpoint and the
+// _meta.source distinguish the facet endpoint from the row endpoint.
+const CT_STATS_FIELDS_PATH = "/stats/field/values";
+const CT_STATS_FIELDS_LABEL = "clinicaltrials:/api/v2/stats/field/values";
+// ─── Frozen enums (Zod source of truth + [M1] in-handler re-guard) ─
+// overallStatus — the 14 values from /stats/field/values (P24). Built FROM this
+// array by the Zod enum in server.ts; re-validated in the handler (a bad value
+// LOUD-fails at HTTP 400 upstream, so this guard's value is mostly a clean
+// pre-fetch invalid_input + parity with funderType's re-guard).
+export const CT_STATUSES = [
+    "COMPLETED",
+    "UNKNOWN",
+    "RECRUITING",
+    "TERMINATED",
+    "NOT_YET_RECRUITING",
+    "ACTIVE_NOT_RECRUITING",
+    "WITHDRAWN",
+    "ENROLLING_BY_INVITATION",
+    "SUSPENDED",
+    "WITHHELD",
+    "NO_LONGER_AVAILABLE",
+    "AVAILABLE",
+    "APPROVED_FOR_MARKETING",
+    "TEMPORARILY_NOT_AVAILABLE",
+];
+const CT_STATUSES_SET = new Set(CT_STATUSES);
+// funderType — the 4 live-nonzero-confirmed values (P16). The other 4 (indiv /
+// network / ambig / unknown) return 0 even on the whole registry (behaviorally
+// IDENTICAL to the P18 silent-invalid-zero), so they are EXCLUDED. This is the
+// load-bearing honesty guard: an INVALID funderType silently fake-empties at
+// HTTP 200, so a non-member is invalid_input PRE-fetch, NEVER sent.
+export const CT_FUNDER_TYPES = ["nih", "fed", "industry", "other"];
+const CT_FUNDER_TYPES_SET = new Set(CT_FUNDER_TYPES);
+// ─── Facet-counts field whitelist (ADR-0024 — the SECOND tool's Zod source of
+//     truth + its [ssrf] in-handler re-guard) ──────────────────────────────
+// The 11 LIVE-VERIFIED (2026-07-12, keyless) `type:"ENUM"` faceteable fields on
+// `/stats/field/values`, each of which returns COMPLETE (topValues.length ==
+// uniqueValuesCount — max observed 14 ≪ the endpoint's hard 250-value cap) and a
+// UNIFORM `{uniqueValuesCount:number, topValues:[{value,studiesCount}]}` shape.
+// The Zod enum in server.ts is DERIVED from this frozen array (single source of
+// truth); the handler ALSO re-checks each requested field against CT_FACET_FIELDS_SET
+// INLINE (the [ssrf] re-guard — a Zod-bypassing DIRECT handler call cannot smuggle a
+// raw field name; mirrors CT_FUNDER_TYPES_SET / CT_STATUSES_SET). ENUM-ONLY by design:
+// a whitelisted field whose response is NOT type:"ENUM" (e.g. the BOOLEAN
+// HealthyVolunteers `{trueCount,falseCount}` shape, which has NO topValues) is
+// schema_drift, never a silent mis-parse (§Honesty #7).
+export const CT_FACET_FIELDS = [
+    "OverallStatus", // 14 values — study-status distribution
+    "StudyType", // 3  — interventional / observational / expanded-access
+    "Phase", // 6  — ARRAY-valued ⇒ OVERLAP note (not a partition)
+    "LeadSponsorClass", // 9  — ★ the FUNDING-SOURCE distribution (B2G: NIH/FED/OTHER_GOV/…)
+    "Sex", // 3
+    "DesignAllocation", // 3
+    "DesignPrimaryPurpose", // 10
+    "DesignInterventionModel", // 5
+    "DesignMasking", // 5
+    "DesignObservationalModel", // 9
+    "DesignTimePerspective", // 4
+];
+const CT_FACET_FIELDS_SET = new Set(CT_FACET_FIELDS);
+// The ARRAY-valued members whose per-value counts OVERLAP (a study can hold several,
+// e.g. PHASE1|PHASE2) so Σ counts + missing OVERSHOOTS the registry total (Phase:
+// live-verified sum 477032 + missing 140698 = 617730 > 593334). The v1 whitelist's
+// ONLY array member is Phase; all 10 others are scalar (sum + missing == 593334, an
+// exact partition). A static Set (no /stats/size call needed) drives the not-a-
+// partition note + the per-facet `overlapping` flag.
+export const CT_FACET_ARRAY_FIELDS = new Set(["Phase"]);
+// ─── Client-side value grammars (SSRF + injection guards) ─────────
+// [M2] NCT id = exactly 8 digits (P1/P11/P12 — every observed id). Validated
+// BEFORE the single-study path is built (no `/`, `?`, `..`, `%2F`, space can be
+// injected — belt-and-suspenders behind the server's Zod, load-bearing for a
+// direct handler call that bypasses Zod).
+export const CT_NCT_RE = /^NCT\d{8}$/;
+// The opaque pageToken alphabet is a base64/URL-safe SUPERSET (the real injection
+// guard is URLSearchParams encoding; the regex bounds length + rejects obvious
+// garbage). Mirrors GovInfo's page-mark regex MINUS the `"*"` sentinel (CT has no
+// first-page sentinel — the first page is simply a call with no pageToken) AND
+// MINUS a literal `%` — URLSearchParams would double-encode a `%` (`%2e`→`%252e`)
+// and corrupt the cursor; CT's observed tokens are base64url (no `%`), so a stray
+// `%` is rejected as invalid_input rather than silently corrupting pagination.
+export const CT_TOKEN_RE = new RegExp("^[A-Za-z0-9+/=_~.,:-]{1,4096}$");
+// ─── Disclosure constants (honesty obligations) ──────────────────
+/** The mandatory trial≠federal-award caveat carried in EVERY response. */
+const CT_TRIAL_CAVEAT = "A ClinicalTrials.gov record is the REGISTRATION of a clinical study, NOT a federal grant or contract award. leadSponsor.class / funderType (NIH/FED) indicate the study's funding-SOURCE class, and the sponsor / collaborator / organization NAMES overlap the entities in NIH RePORTER / NSF Awards / SAM / USAspending — but leadSponsor.name is a FREE-TEXT string, NOT a UEI, so any cross-reference to a federal award is a NOMINAL name match, not an authoritative entity join, and a registered trial does not imply a federal award to that sponsor.";
+/** The opaque-cursor disclosure (offset/nextOffset are meaningless). */
+const CT_CURSOR_NOTE = "ClinicalTrials.gov uses an opaque cursor: pagination.offset/nextOffset are not meaningful (null). Continue by passing _meta.nextCursor back as the `pageToken` argument; hasMore:false / nextCursor:null means this is the last page.";
+/** funderType is a NON-EXCLUSIVE facet (values overlap; sum > registry total). */
+const CT_FUNDER_OVERLAP_NOTE = "funderType is an OVERLAPPING facet — a study can have multiple funders, so the per-funderType counts MUST NOT be summed across values to reconstruct a registry total.";
+/** query.spons is a fuzzy sponsor NAME search, not an exact-entity join. Emitted
+ *  ONLY for a SINGLE-token sponsor: for a MULTI-token sponsor CT AND-splits and
+ *  NARROWS (e.g. 'Sanofi-Aventis' → 'Sanofi' AND 'Aventis'), so the "matches more
+ *  variants" broadening framing here would be the OPPOSITE of what happened — the
+ *  AND-note (andTokenNote) takes precedence in that case (see searchStudies). */
+const CT_SPONSOR_NOTE = "sponsor is a full-text sponsor-NAME search (query.spons), not an exact-entity equality — a single-token name also matches related name variants (e.g. 'Pfizer' matches 'Pfizer's Upjohn'), and the name is free text, NOT a UEI (nominal match only).";
+/** A conservative data-currency note (not API-verifiable). */
+const CT_DATA_CURRENCY_NOTE = "ClinicalTrials.gov updates registrations on a rolling basis; per-record refresh lag is not API-verifiable.";
+// ─── Facet-counts disclosure constants (ADR-0024 honesty obligations) ──────
+const CT_FACET_SOURCE = "clinicaltrials.gov /api/v2/stats/field/values (keyless)";
+/**
+ * [M1] totalAvailable/returned UNIT disclosure. For the facet tool ONLY,
+ * `_meta.totalAvailable = Σ facet.uniqueValuesCount` and `_meta.returned =
+ * Σ facet.values.length` — these drive buildMeta's `returned < totalAvailable ⇒
+ * truncated` invariant, but they count DISTINCT FIELD VALUES, NOT studies (in
+ * every OTHER tool, incl. clinicaltrials_search_studies, totalAvailable is a
+ * study/record match count). Mandatory on every facet response so an AI never
+ * reads the distinct-value total as a study total.
+ */
+const CT_FACET_UNIT_NOTE = "In this facet-counts response _meta.totalAvailable and _meta.returned count DISTINCT FIELD VALUES across the requested facet(s), NOT studies (e.g. OverallStatus+Phase ⇒ totalAvailable = 14+6 = 20 distinct values, which is NOT a study count). The per-value STUDY counts are facets[].values[].studiesCount; for a COUNT of studies use clinicaltrials_search_studies (its _meta.totalAvailable is the exact study total).";
+/**
+ * [M2] Whole-registry scope note — NO hard-coded registry size (the registry only
+ * grows; freezing a total in a truthfulness string would go stale). These counts
+ * are ALWAYS over the ENTIRE registry and are UNfilterable (query/filter/countTotal/
+ * pageSize params all HTTP-400 here). Cross-links the sibling row tool for filtered
+ * totals.
+ */
+const CT_FACET_SCOPE_NOTE = "These are whole-registry distribution counts — they cover the ENTIRE ClinicalTrials.gov registry and are NOT filtered by any query (the /stats/field/values endpoint rejects query.*/filter.*/countTotal/pageSize with HTTP 400). To count studies matching a specific query / sponsor / condition / status, use clinicaltrials_search_studies (its _meta.totalAvailable is the exact filtered total).";
+/**
+ * The FACET-SCOPED trial≠federal-award caveat (EVERY facet response). Carries the
+ * same trial-registration ≠ federal-award substance as the row-level
+ * CT_TRIAL_CAVEAT, but REWORDED for a distribution output — it describes the
+ * LeadSponsorClass DISTRIBUTION, not a row-level leadSponsor.name free-text field.
+ */
+const CT_FACET_TRIAL_CAVEAT = "A ClinicalTrials.gov facet count is a DISTRIBUTION over clinical-study REGISTRATIONS, NOT over federal grants or contract awards. LeadSponsorClass (NIH / FED / OTHER_GOV vs INDUSTRY / OTHER / NETWORK / …) is the study's funding-SOURCE class, NOT a count of federal awards; these classes overlap — but do NOT equal — the entities in NIH RePORTER / NSF Awards / SAM / USAspending (a nominal funding-source-class distribution, not a UEI-keyed award join). A registered trial does not imply a federal award to its sponsor.";
+/** Per-facet TOP-N truncation note — the 250-cap disclosure. Never fires for the
+ *  v1 ENUM whitelist (all ≤14 unique ≪ 250) but is load-bearing: if the whitelist
+ *  is ever extended to a high-cardinality (STRING) field, this discloses the cap. */
+function ctFacetTruncationNote(field, unique, returned) {
+    return `Field '${field}' has ${unique} distinct values but ClinicalTrials.gov's /stats/field/values returned only the top ${returned} by study count (a hard 250-value cap, not pageable); the remaining ${unique - returned} value(s) are OMITTED — this is NOT the full distribution.`;
+}
+/** Per-facet not-a-partition note — an ARRAY-valued field (Phase) whose per-value
+ *  counts OVERLAP and MUST NOT be summed to a registry total. */
+function ctFacetOverlapNote(field) {
+    return `'${field}' is multi-valued per study (a study can carry several values, e.g. a trial registered as PHASE1|PHASE2), so its per-value studiesCount counts OVERLAP and MUST NOT be summed to a registry total (Σ counts + missingStudiesCount OVERSHOOTS the registry size). The other facets are scalar (each study has at most one value). Always read missingStudiesCount alongside the shown buckets.`;
+}
+/** Per-facet high-missing interpretation note — when more studies LACK a value for
+ *  the field than are represented across all shown buckets, the distribution covers
+ *  a MINORITY of the registry. `missing` is this response's exact (live) count — NOT
+ *  a frozen constant (M2). */
+function ctFacetHighMissingNote(field, missing) {
+    return `Field '${field}' has ${missing} studies with NO value for it — MORE than the studies represented across all shown buckets — so this distribution covers a MINORITY of the registry; do NOT read the shown value counts as registry-wide (the uncounted / missing studies dominate).`;
+}
+// CT's Essie analyzer AND-tokenizes free-text query.spons/query.cond/query.term on
+// whitespace AND the confirmed PUNCTUATION set (space + `- , / ; + & | @ # =` split
+// into the AND co-occurrence; `. : _ '` do NOT — live-verified 2026-07-12), so a
+// single-token-LOOKING compound like "Sanofi-Aventis" is really 'Sanofi' AND
+// 'Aventis' (→3 vs Sanofi→3416 — a ~1000× silent false-negative). That precise
+// class is the SHARED tokenizeForDisclosure / DISCLOSURE_SPLIT_RE (src/disclosure.js,
+// ADR-0022) — byte-identical to NSF's former CT_TOKEN_SPLIT_RE / NSF_KEYWORD_SPLIT_RE
+// (there OR, here AND) — so a whitespace-only detector can never miss the AND-note.
+/** The AND-tokenization disclosure for a multi-TOKEN term/sponsor/condition value. */
+function andTokenNote(field, tokens) {
+    return `ClinicalTrials.gov tokenizes a multi-word ${field} on whitespace AND punctuation (hyphen, comma, slash, semicolon, etc.) and matches it as AND — ALL tokens must co-occur; this value was split into [${tokens.join(", ")}], so a 0/small count means no study matches EVERY token, NOT that the ${field} is absent (e.g. 'Sanofi-Aventis' = 'Sanofi' AND 'Aventis' → far fewer than 'Sanofi' alone). Try a single distinctive token.`;
+}
+const CT_SOURCE = "clinicaltrials.gov /api/v2/studies (keyless)";
+/** A string array from a mixed value, else [] (drops non-string entries). */
+function strArray(x) {
+    if (!Array.isArray(x))
+        return [];
+    return x.map((v) => str(v)).filter((v) => v !== null);
+}
+/** Map a collaborators[]-style array of {name,class} entities (honest [] when absent). */
+function mapEntities(x) {
+    if (!Array.isArray(x))
+        return [];
+    return x.map((c) => {
+        const it = (c ?? {});
+        return { name: str(it.name), class: str(it.class) };
+    });
+}
+/**
+ * Map ONE study (a search `studies[]` row OR the get single-study body — both
+ * carry `protocolSection`) → the curated entity shape. Every scalar is
+ * null-never-fabricated (str, null-never-empty-string — a missing/blank sponsor
+ * name is null, NEVER ""). collaborators/phases/conditions default to [] (an
+ * honest "none listed"). `briefSummary` is included ONLY for get_study.
+ */
+function mapStudy(item, includeSummary) {
+    const it = (item ?? {});
+    const ps = (it.protocolSection ?? {});
+    const idm = (ps.identificationModule ?? {});
+    const org = (idm.organization ?? {});
+    const orgStudyIdInfo = (idm.orgStudyIdInfo ?? {});
+    const scm = (ps.sponsorCollaboratorsModule ?? {});
+    const lead = (scm.leadSponsor ?? {});
+    const statusM = (ps.statusModule ?? {});
+    const startStruct = (statusM.startDateStruct ?? {});
+    const designM = (ps.designModule ?? {});
+    const condM = (ps.conditionsModule ?? {});
+    const descM = (ps.descriptionModule ?? {});
+    const leadClass = str(lead.class);
+    const study = {
+        nctId: str(idm.nctId),
+        briefTitle: str(idm.briefTitle),
+        orgStudyId: str(orgStudyIdInfo.id),
+        organization: { name: str(org.fullName), class: str(org.class) },
+        leadSponsor: { name: str(lead.name), class: leadClass },
+        collaborators: mapEntities(scm.collaborators),
+        fundingClass: leadClass,
+        overallStatus: str(statusM.overallStatus),
+        startDate: str(startStruct.date),
+        studyType: str(designM.studyType),
+        phases: strArray(designM.phases),
+        conditions: strArray(condM.conditions),
+    };
+    if (includeSummary)
+        study.briefSummary = str(descM.briefSummary);
+    return study;
+}
+// ─── SSRF-guarded fetch ([M2] — one audited fetch home for BOTH tools) ──
+/**
+ * GET one ClinicalTrials.gov v2 JSON resource. `path` is `/studies` (search) or
+ * `/studies/{nctId}` (get — the caller validates `nctId` `^NCT\d{8}$` BEFORE
+ * building the path); all query params ride in `params` (URLSearchParams,
+ * encoded). Builds `${CT_BASE}${path}?${params}` on the FIXED host literal, then
+ * asserts the CONSTRUCTED URL is `clinicaltrials.gov` over https (belt-and-
+ * suspenders — a future constant typo/downgrade fails closed), sets
+ * `redirect:"error"` (an off-host 3xx fails closed — its body is never read). NO
+ * headers (keyless — no key/UA required, byte-clean init). Returns the parsed
+ * JSON (unknown; the caller validates the response envelope + throws driftError).
+ */
+async function getCT(path, label, params) {
+    const qs = params.toString();
+    const url = `${CT_BASE}${path}${qs ? `?${qs}` : ""}`;
+    const built = new URL(url);
+    if (built.protocol !== "https:" || built.hostname !== CT_HOST) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed ClinicalTrials.gov URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(CT_HOST)} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+            upstreamEndpoint: label,
+        });
+    }
+    return getJson(url, { label, redirect: "error" });
+}
+/**
+ * Search federally-registered clinical studies with sponsor / condition /
+ * location / status / funding-source filters. Each shipped filter is
+ * LIVE-CONFIRMED to narrow; the query is MODULE-BUILT from validated typed args
+ * through URLSearchParams (NO raw passthrough) with `countTotal=true` ALWAYS
+ * appended (§Honesty #1). Returns curated ENTITY rows (briefSummary EXCLUDED —
+ * payload) + honest `_meta`: the EXACT filtered total, the opaque-cursor
+ * continuation, the AND-tokenization disclosure, the funderType-overlap note, and
+ * the mandatory trial≠federal-award caveat. Disclose-not-refuse: an unscoped call
+ * is NOT refused — it returns the first page + the exact total + a narrowing note.
+ */
+export async function searchStudies(args) {
+    const pageSize = args.pageSize ?? 20;
+    // ── [M1] In-handler enum re-guard (funderType AND overallStatus) — throw
+    //    invalid_input PRE-fetch (0 network call), mirroring govinfo's in-handler
+    //    collection re-check. This is load-bearing for a DIRECT handler call that
+    //    bypasses Zod: an unknown funderType would build aggFilters=funderType:<v>
+    //    and get a fabricated HTTP-200 totalCount:0 (the silent fake-empty trap). ──
+    if (args.funderType !== undefined &&
+        !CT_FUNDER_TYPES_SET.has(args.funderType)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `funderType ${JSON.stringify(args.funderType)} is not supported by this tool (ships: ${CT_FUNDER_TYPES.join(", ")}). An unlisted funderType silently returns totalCount:0 at HTTP 200 on ClinicalTrials.gov (indistinguishable from a genuine empty) — refused before any fetch.`,
+            retryable: false,
+            upstreamEndpoint: CT_LABEL,
+        });
+    }
+    if (args.overallStatus !== undefined &&
+        !CT_STATUSES_SET.has(args.overallStatus)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `overallStatus ${JSON.stringify(args.overallStatus)} is not one of the ${CT_STATUSES.length} ClinicalTrials.gov statuses (${CT_STATUSES.join(", ")}) — refused before any fetch.`,
+            retryable: false,
+            upstreamEndpoint: CT_LABEL,
+        });
+    }
+    // ── Belt-and-suspenders pageToken + pageSize grammars (behind the server's
+    //    Zod). A bad token would loud-fail at HTTP 400, but reject it pre-fetch. ──
+    if (args.pageToken !== undefined && !CT_TOKEN_RE.test(args.pageToken)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid pageToken (opaque cursor) — must be a ≤4096-char base64/URL-safe token. Pass back the _meta.nextCursor from the previous page.`,
+            retryable: false,
+            upstreamEndpoint: CT_LABEL,
+        });
+    }
+    if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 1000) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid pageSize ${JSON.stringify(pageSize)} — must be an integer in [1, 1000] (ClinicalTrials.gov clamps a larger request to 1000).`,
+            retryable: false,
+            upstreamEndpoint: CT_LABEL,
+        });
+    }
+    // ── Build the query from VALIDATED typed args, key-by-key (SSRF: no raw
+    //    passthrough). countTotal=true is ALWAYS appended (§Honesty #1 — omitting
+    //    it drops the total entirely). ──
+    const params = new URLSearchParams();
+    const filtersApplied = [];
+    const andNotes = [];
+    // A helper: push a filter + detect MULTI-TOKEN AND-tokenization on CT's REAL
+    // delimiter set via the shared tokenizeForDisclosure (whitespace AND the confirmed
+    // punctuation splitters — DISCLOSURE_SPLIT_RE), so a compound like "Sanofi-Aventis"
+    // (= Sanofi AND Aventis) fires the mandatory AND-note instead of leaking as one
+    // token through a hyphen/comma/slash. Returns true iff the value split into 2+
+    // tokens (so the caller can suppress the contradictory sponsor-broadening note).
+    // andField=null ONLY for a field with no AND-note obligation. term/sponsor/
+    // condition AND location all ride the SAME Essie AND-tokenizer (query.locn is
+    // AND-split exactly like query.term/spons/cond — a multi-word location like
+    // "New York" is 'New' AND 'York'), so each passes its own andField label.
+    const pushText = (value, upstreamKey, filterLabel, andField) => {
+        if (value === undefined)
+            return false;
+        params.set(upstreamKey, value);
+        filtersApplied.push(filterLabel);
+        if (andField === null)
+            return false;
+        const tokens = tokenizeForDisclosure(value);
+        if (tokens.length > 1) {
+            andNotes.push(andTokenNote(andField, tokens));
+            return true;
+        }
+        return false;
+    };
+    pushText(args["query.term"], "query.term", "query.term", "term");
+    const sponsorMultiToken = pushText(args.sponsor, "query.spons", "sponsor", "sponsor");
+    pushText(args.condition, "query.cond", "condition", "condition");
+    // D2 (no-silent-filter): location (→ query.locn) is AND-tokenized identically to
+    // term/sponsor/condition — so a multi-word location must emit the SAME mandatory
+    // AND-note (was silently exempted with andField=null, hiding the narrowing).
+    pushText(args.location, "query.locn", "location", "location");
+    if (args.overallStatus !== undefined) {
+        params.set("filter.overallStatus", args.overallStatus);
+        filtersApplied.push("overallStatus");
+    }
+    if (args.funderType !== undefined) {
+        // The module builds the aggFilters string from the enum-validated value —
+        // never from raw caller text (§SSRF #3).
+        params.set("aggFilters", `funderType:${args.funderType}`);
+        filtersApplied.push("funderType");
+    }
+    params.set("countTotal", "true"); // ALWAYS — §Honesty #1
+    params.set("pageSize", String(pageSize));
+    if (args.pageToken !== undefined)
+        params.set("pageToken", args.pageToken);
+    const body = await getCT(CT_STUDIES_PATH, CT_LABEL, params);
+    const b = (body ?? {});
+    // ── Container-guarded drift (never a TypeError masking drift as
+    //    upstream_unavailable, never a fake empty). ──
+    if (!Array.isArray(b.studies)) {
+        throw driftError(CT_LABEL, "clinicaltrials shape drift — /studies response.studies must be an array.");
+    }
+    // countTotal=true was sent, so totalCount MUST be a finite number — its absence
+    // is drift, NEVER a silently-null total, NEVER studies.length (§Honesty #1).
+    if (typeof b.totalCount !== "number" || !Number.isFinite(b.totalCount)) {
+        throw driftError(CT_LABEL, "clinicaltrials shape drift — /studies totalCount missing/non-number on a countTotal=true request (typeof-checked BEFORE num() so a non-number can't silently parse; NEVER fall back to studies.length).");
+    }
+    const studies = b.studies.map((s) => mapStudy(s, false));
+    const returned = studies.length;
+    const totalAvailable = num(b.totalCount); // EXACT (genuine 0 → 0)
+    // ── Opaque-cursor honesty (§Honesty #2). Terminal = token ABSENT. The token is
+    //    surfaced VERBATIM (never fabricated/derived). Phantom-empty guard: 0
+    //    studies WITH a token ⇒ terminal (never advertise a continuation into an
+    //    empty cursor loop). ──
+    const rawNext = b.nextPageToken;
+    const nextToken = typeof rawNext === "string" && rawNext.length > 0 ? rawNext : null;
+    let hasMore;
+    let nextCursor;
+    if (returned === 0 && nextToken !== null) {
+        hasMore = false;
+        nextCursor = null;
+    }
+    else {
+        hasMore = nextToken !== null;
+        nextCursor = nextToken;
+    }
+    // ── Notes: the mandatory caveat + cursor + data-currency always; the
+    //    conditional facet/tokenization disclosures; the unscoped recommendation. ──
+    const notes = [CT_TRIAL_CAVEAT, CT_CURSOR_NOTE];
+    notes.push(...andNotes);
+    // Emit the sponsor-broadening note ONLY for a SINGLE-token sponsor. For a
+    // MULTI-token sponsor CT AND-split and NARROWED (the andNotes AND-note fired),
+    // so the "matches more variants" framing would AFFIRMATIVELY MISLEAD (the
+    // opposite of what happened) — the AND-note is what the caller must see.
+    if (args.sponsor !== undefined && !sponsorMultiToken)
+        notes.push(CT_SPONSOR_NOTE);
+    if (args.funderType !== undefined)
+        notes.push(CT_FUNDER_OVERLAP_NOTE);
+    if (filtersApplied.length === 0) {
+        notes.push("No filters were applied — this is an unscoped query over the WHOLE ClinicalTrials.gov registry (~593k studies). Add a filter (query.term, sponsor, condition, location, overallStatus, funderType) for a meaningful scoped result set.");
+    }
+    notes.push(CT_DATA_CURRENCY_NOTE);
+    return withMeta({ studies }, {
+        source: CT_SOURCE,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        // complete is DERIVED by buildMeta (never forced): a first-page call whose
+        // returned === totalAvailable with no token ⇒ complete:true; a continuation
+        // page (or any page with returned < total / a token) ⇒ complete:false.
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [
+            "briefSummary (search rows omit it — use clinicaltrials_get_study)",
+        ],
+        // Cursor page: offset/nextOffset null (no numeric offset); continuation is
+        // nextCursor (the opaque nextPageToken, passed back verbatim as pageToken).
+        pagination: { offset: null, limit: pageSize, hasMore, nextOffset: null },
+        nextCursor,
+        notes,
+    });
+}
+// ─── Tool 2: clinicaltrials_get_study ─────────────────────────────
+/**
+ * Fetch ONE study by its NCT id; returns the fuller single record (entity fields
+ * + briefSummary). [M2] `nctId` is regex-validated `^NCT\d{8}$` BEFORE the path is
+ * built (a `../` / non-matching id ⇒ invalid_input, 0 fetch). A 404 (nonexistent
+ * NCT id) ⇒ honest found:false (never a fabricated study).
+ */
+export async function getStudy(args) {
+    const nctId = args.nctId;
+    // [M2] Validate BEFORE building the path (belt-and-suspenders behind the
+    // server's Zod — load-bearing for a direct call; a traversal never reaches the
+    // path). 0 fetch on a mismatch.
+    if (!CT_NCT_RE.test(nctId)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid nctId ${JSON.stringify(nctId)} — expected an NCT id of the form NCT followed by exactly 8 digits (e.g. NCT02403869). Refused before any fetch (path-segment injection guard).`,
+            retryable: false,
+            upstreamEndpoint: CT_LABEL,
+        });
+    }
+    const notes = [CT_TRIAL_CAVEAT, CT_DATA_CURRENCY_NOTE];
+    let body;
+    try {
+        body = await getCT(`${CT_STUDIES_PATH}/${nctId}`, CT_LABEL, new URLSearchParams());
+    }
+    catch (e) {
+        // A nonexistent NCT id ⇒ HTTP 404 ⇒ getJson throws not_found ⇒ honest
+        // found:false (a definitive answer, never a fabricated study).
+        if (e instanceof ToolErrorCarrier && e.toolError.kind === "not_found") {
+            return withMeta({ found: false, nctId, study: null }, {
+                source: CT_SOURCE,
+                keylessMode: true,
+                returned: 0,
+                totalAvailable: 0,
+                complete: true,
+                filtersApplied: ["nctId"],
+                filtersDropped: [],
+                fieldsUnavailable: [],
+                notes: [
+                    `No ClinicalTrials.gov study found for nctId ${JSON.stringify(nctId)} (HTTP 404) — the id does not exist. Not fabricated.`,
+                    ...notes,
+                ],
+            });
+        }
+        throw e;
+    }
+    // A valid single-study 200 carries protocolSection at the TOP level (P11). Its
+    // absence is drift (never a fabricated all-null record).
+    const bo = (body ?? {});
+    if (bo.protocolSection === null ||
+        typeof bo.protocolSection !== "object" ||
+        Array.isArray(bo.protocolSection)) {
+        throw driftError(CT_LABEL, "clinicaltrials shape drift — /studies/{nctId} response is missing a protocolSection object.");
+    }
+    const study = mapStudy(body, true); // FULL record incl. briefSummary
+    return withMeta({ found: true, nctId, study }, {
+        source: CT_SOURCE,
+        keylessMode: true,
+        returned: 1,
+        totalAvailable: 1,
+        complete: true,
+        filtersApplied: ["nctId"],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+/**
+ * Map ONE `/stats/field/values` facet element → the curated facet shape (a FRESH
+ * mapper — does NOT reuse mapStudy/strArray/mapEntities, which are row-shaped).
+ * ENUM-ONLY drift guard (§Honesty #7): the element MUST be `type:"ENUM"` with an
+ * ARRAY `topValues` and a NUMBER `uniqueValuesCount` — a BOOLEAN
+ * (`{trueCount,falseCount}`, no topValues) / STRING / re-typed shape for a
+ * whitelisted field is schema_drift, NEVER read as an empty distribution. Each
+ * `studiesCount` is typeof-checked to a finite NUMBER BEFORE `num()` (mirrors the
+ * search tool's totalCount guard) so a non-number can NEVER silently parse or
+ * coerce-to-0 — an EXACT count or drift, never a fabricated 0.
+ */
+function mapFacet(requested, item) {
+    const o = (item ?? {});
+    if (o.type !== "ENUM") {
+        throw driftError(CT_STATS_FIELDS_LABEL, `clinicaltrials facet shape drift — field '${requested}' returned type ${JSON.stringify(o.type)} (expected "ENUM"). A non-ENUM shape (e.g. a BOOLEAN {trueCount,falseCount} with NO topValues) must NEVER be read as an empty distribution.`);
+    }
+    if (!Array.isArray(o.topValues)) {
+        throw driftError(CT_STATS_FIELDS_LABEL, `clinicaltrials facet shape drift — field '${requested}' topValues is not an array (container-guarded — a TypeError must never mask drift as upstream_unavailable, never a fake empty).`);
+    }
+    if (typeof o.uniqueValuesCount !== "number" || !Number.isFinite(o.uniqueValuesCount)) {
+        throw driftError(CT_STATS_FIELDS_LABEL, `clinicaltrials facet shape drift — field '${requested}' uniqueValuesCount is missing/non-number (typeof-checked BEFORE num() so a string can't silently parse).`);
+    }
+    const values = o.topValues.map((v) => {
+        const it = (v ?? {});
+        if (typeof it.studiesCount !== "number" || !Number.isFinite(it.studiesCount)) {
+            throw driftError(CT_STATS_FIELDS_LABEL, `clinicaltrials facet shape drift — a topValues[].studiesCount for field '${requested}' is missing/non-number (typeof-checked BEFORE num() so a non-number can NEVER be silently coerced to 0 — a per-value count is EXACT or it is drift).`);
+        }
+        return { value: str(it.value), studiesCount: num(it.studiesCount) };
+    });
+    const uniqueValuesCount = num(o.uniqueValuesCount);
+    const returned = values.length;
+    return {
+        field: requested,
+        fieldPath: str(o.field),
+        valueType: str(o.type),
+        uniqueValuesCount,
+        missingStudiesCount: num(o.missingStudiesCount),
+        returned,
+        // The universal truncation invariant: returned < unique ⇒ truncated (rolled up
+        // into buildMeta via the response-level returned/totalAvailable roll-up too).
+        truncated: returned < uniqueValuesCount,
+        overlapping: CT_FACET_ARRAY_FIELDS.has(requested),
+        values,
+    };
+}
+/**
+ * Aggregate / statistical view: EXACT per-value study counts over the WHOLE
+ * ClinicalTrials.gov registry for one or more whitelisted ENUM fields
+ * (studies-by-OverallStatus / by-Phase / by-LeadSponsorClass = the funding-source
+ * distribution / …). The aggregate SIBLING of clinicaltrials_search_studies (which
+ * gives the exact FILTERED total for a query) — this gives the exact WHOLE-REGISTRY
+ * distribution across a field's values. Reuses the shipped getCT verbatim (one new
+ * path constant), coerce.num/str, buildMeta/withMeta — ZERO new fetch/coerce/error/
+ * meta code.
+ */
+export async function facetCounts(args) {
+    // ── [ssrf] In-handler field RE-GUARD (load-bearing for a Zod-BYPASSING direct
+    //    call): re-check EACH requested field against the frozen CT_FACET_FIELDS_SET
+    //    INLINE (mirror CT_FUNDER_TYPES_SET / CT_STATUSES_SET) BEFORE building params,
+    //    and dedupe (preserving order). A non-member ⇒ invalid_input PRE-fetch, 0
+    //    network call — NO raw field-name ever reaches the URL. ──
+    const requested = args.fields ?? [];
+    const seen = new Set();
+    const fields = [];
+    for (const f of requested) {
+        if (!CT_FACET_FIELDS_SET.has(f)) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                message: `field ${JSON.stringify(f)} is not a supported facet (ships: ${CT_FACET_FIELDS.join(", ")}). An unlisted field is NOT asserted upstream-invalid (it may be a real STRING/BOOLEAN field this tool deliberately does not whitelist) — refused before any fetch (SSRF + ENUM-shape-stability guard).`,
+                retryable: false,
+                upstreamEndpoint: CT_STATS_FIELDS_LABEL,
+            });
+        }
+        if (!seen.has(f)) {
+            seen.add(f);
+            fields.push(f);
+        }
+    }
+    if (fields.length === 0) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `at least one facet field is required (ships: ${CT_FACET_FIELDS.join(", ")}).`,
+            retryable: false,
+            upstreamEndpoint: CT_STATS_FIELDS_LABEL,
+        });
+    }
+    // ── Build the query from the enum-validated array (SSRF: module-built, comma-
+    //    joined; each element is a frozen enum member — no raw passthrough). The ONLY
+    //    query key is `fields`; no filter/scope/page key is EVER sent (they 400). ──
+    const params = new URLSearchParams();
+    params.set("fields", fields.join(","));
+    const body = await getCT(CT_STATS_FIELDS_PATH, CT_STATS_FIELDS_LABEL, params);
+    // The 200 body is a TOP-LEVEL ARRAY (one object per requested field). Its absence
+    // is drift, NEVER a fake-empty distribution. A 404 (a whitelisted field missing
+    // upstream = whitelist drift) / 400 / 5xx is THROWN by getJson (never caught).
+    if (!Array.isArray(body)) {
+        throw driftError(CT_STATS_FIELDS_LABEL, "clinicaltrials facet shape drift — /stats/field/values response must be a top-level array (one object per requested field).");
+    }
+    // Match each requested field to its response element by the echoed `piece`
+    // (robust to element ordering); a whitelisted field absent from the response is
+    // whitelist drift ⇒ driftError, never a silent empty.
+    const byPiece = new Map();
+    for (const el of body) {
+        const p = (el ?? {});
+        if (typeof p.piece === "string" && !byPiece.has(p.piece))
+            byPiece.set(p.piece, el);
+    }
+    const facets = [];
+    for (const f of fields) {
+        const el = byPiece.get(f);
+        if (el === undefined) {
+            throw driftError(CT_STATS_FIELDS_LABEL, `clinicaltrials facet shape drift — requested field '${f}' is absent from the response (a whitelisted field must always be echoed; its absence signals the whitelist drifted from upstream — NEVER read as an empty distribution).`);
+        }
+        facets.push(mapFacet(f, el));
+    }
+    // ── [M1] Response-level roll-up: returned = Σ values.length, totalAvailable =
+    //    Σ uniqueValuesCount (DISTINCT VALUES, not studies — the unit note discloses
+    //    it). buildMeta's `returned < totalAvailable ⇒ truncated:true / complete:false`
+    //    auto-derives truncation the instant ANY facet is capped; for the v1 ENUM
+    //    whitelist returned == totalAvailable ⇒ complete:true, truncated:false. ──
+    const returned = facets.reduce((a, ff) => a + ff.values.length, 0);
+    const totalAvailable = facets.reduce((a, ff) => a + (ff.uniqueValuesCount ?? 0), 0);
+    // ── Notes: the mandatory unit (M1) + scope (M2) always; per-facet truncation /
+    //    overlap / high-missing conditionals; the facet-scoped trial≠award caveat +
+    //    data-currency always. ──
+    const notes = [CT_FACET_UNIT_NOTE, CT_FACET_SCOPE_NOTE];
+    for (const ff of facets) {
+        if (ff.truncated && ff.uniqueValuesCount !== null) {
+            notes.push(ctFacetTruncationNote(ff.field, ff.uniqueValuesCount, ff.returned));
+        }
+    }
+    for (const ff of facets) {
+        if (ff.overlapping)
+            notes.push(ctFacetOverlapNote(ff.field));
+    }
+    for (const ff of facets) {
+        const missing = ff.missingStudiesCount;
+        const shown = ff.values.reduce((a, v) => a + (v.studiesCount ?? 0), 0);
+        // Denominator-free (no frozen registry total, M2): the shown buckets cover a
+        // MINORITY when more studies lack a value than are represented across them.
+        if (missing !== null && missing > shown) {
+            notes.push(ctFacetHighMissingNote(ff.field, missing));
+        }
+    }
+    notes.push(CT_FACET_TRIAL_CAVEAT, CT_DATA_CURRENCY_NOTE);
+    return withMeta({ facets }, {
+        source: CT_FACET_SOURCE,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        // complete/truncated DERIVED by buildMeta from returned/totalAvailable (never
+        // forced): v1 ENUM ⇒ complete:true; a future capped facet ⇒ complete:false.
+        filtersApplied: [],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        // NO pagination object — /stats/field/values is un-paged (pageSize 400s);
+        // leave `pagination` undefined (NOT {hasMore:false}).
+        notes,
+    });
+}
+//# sourceMappingURL=clinicaltrials.js.map