@inflexa-ai/harness 0.30.2 → 0.31.0

package/dist/tools/lib/chembl-client.js

@@ -2,10 +2,32 @@
  * Pure async client functions for the ChEMBL REST API.
  *
  * Used directly by target-assessment workflow steps and by tool wrappers.
+ *
+ * Absence policy: ChEMBL sends an explicit `null` for an absent value, and it
+ * never omits the key. Thus a maybe-absent field carries `.nullable()`, not
+ * `.optional()`.
  */
 import { z } from "zod";
-import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError, zWireNumber } from "./api-utils.js";
 import { CHEMBL_BASE, CHEMBL_HEADERS as HEADERS } from "./chembl-config.js";
+/** The `max_phase` of an approved drug. ChEMBL serializes it as the string "4.0". */
+const APPROVED_MAX_PHASE = 4;
+/**
+ * Report one molecule that a per-molecule lookup dropped from its result.
+ *
+ * These loops turned every error into a skipped molecule, thus a ChEMBL contract
+ * break emptied a whole modulator list in silence. An unexpected cause now
+ * reaches the injected `Logger` before the loop degrades. An expected miss, such
+ * as an HTTP 404, stays silent, because ChEMBL holds no record of that molecule.
+ */
+function reportSkippedMolecule(logger, error, moleculeChemblId) {
+    if (!isUnexpectedApiError(error))
+        return;
+    logger.error("molecule dropped from the result", { moleculeChemblId, cause: describeApiError(error) });
+}
+/** How many disease terms one drug can contribute to an indication read. */
+const INDICATIONS_PER_DRUG = 20;
 const TargetComponentSynonymSchema = z.object({
     syn_type: z.string().optional(),
     component_synonym: z.string().optional(),
@@ -18,54 +40,59 @@ const RawTargetSchema = z.object({
     target_chembl_id: z.string().optional(),
     pref_name: z.string().optional(),
     target_type: z.string().optional(),
-    organism: z.string().optional(),
+    organism: z.string().nullable().optional(),
     target_components: z.array(TargetComponentSchema).optional(),
 });
+// ChEMBL serves a Tastypie `decimal` as a JSON string ("41.0"), and it encodes an
+// absent value as an explicit `null` rather than an omitted key. Thus a decimal
+// field reads through `zWireNumber`, and a field that the published schema marks
+// nullable carries `.nullable()`.
 /** A raw activity row from the ChEMBL `activity` endpoint. */
 const RawChemblActivitySchema = z.object({
     activity_id: z.number().optional(),
     molecule_chembl_id: z.string().optional(),
     target_chembl_id: z.string().optional(),
     standard_type: z.string().optional(),
-    standard_value: z.union([z.string(), z.number()]).nullable().optional(),
-    standard_units: z.string().optional(),
+    standard_value: zWireNumber.nullable().optional(),
+    standard_units: z.string().nullable().optional(),
     assay_chembl_id: z.string().optional(),
     assay_type: z.string().optional(),
-    pchembl_value: z.union([z.string(), z.number()]).nullable().optional(),
+    pchembl_value: zWireNumber.nullable().optional(),
 });
 /** A raw mechanism row from the ChEMBL `mechanism` endpoint. */
 const RawChemblMechanismSchema = z.object({
     mechanism_of_action: z.string().optional(),
-    action_type: z.string().optional(),
-    target_chembl_id: z.string().optional(),
+    action_type: z.string().nullable().optional(),
+    target_chembl_id: z.string().nullable().optional(),
     molecule_chembl_id: z.string().optional(),
 });
-/** A drug-indication record nested inside a ChEMBL molecule/drug record. */
-const DrugIndicationRecordSchema = z.object({
+/** A raw row of the ChEMBL `drug_indication` resource, which pairs a molecule with a disease term. */
+const RawDrugIndicationSchema = z.object({
+    molecule_chembl_id: z.string().nullable().optional(),
     mesh_heading: z.string().optional(),
-    efo_term: z.string().optional(),
+    efo_term: z.string().nullable().optional(),
+    max_phase_for_ind: zWireNumber.nullable().optional(),
 });
-/** A raw molecule/drug record from the ChEMBL `molecule` / `drug` endpoints. */
+/** A raw molecule record from the ChEMBL `molecule` endpoint. */
 const RawChemblMoleculeSchema = z.object({
     molecule_chembl_id: z.string().optional(),
-    pref_name: z.string().optional(),
-    max_phase: z.number().nullable().optional(),
-    molecule_type: z.string().optional(),
+    pref_name: z.string().nullable().optional(),
+    max_phase: zWireNumber.nullable().optional(),
+    molecule_type: z.string().nullable().optional(),
     first_approval: z.number().nullable().optional(),
-    drug_indications: z.array(DrugIndicationRecordSchema).optional(),
     molecule_hierarchy: z.object({ parent_chembl_id: z.string().optional() }).optional(),
 });
 // Response envelopes returned by the ChEMBL list/record endpoints, validated at
 // the fetch boundary. Every wrapper field is optional because the API omits it
 // when there is no data (a 404 is handled separately as an expected empty).
-const TargetSearchResponseSchema = z.object({ targets: z.array(RawTargetSchema).optional() });
-const ActivitiesResponseSchema = z.object({ activities: z.array(RawChemblActivitySchema).optional() });
-const MechanismsResponseSchema = z.object({ mechanisms: z.array(RawChemblMechanismSchema).optional() });
-const DrugSearchResponseSchema = z.object({ drugs: z.array(RawChemblMoleculeSchema).optional() });
-const MoleculeSearchResponseSchema = z.object({ molecules: z.array(RawChemblMoleculeSchema).optional() });
+export const TargetSearchResponseSchema = z.object({ targets: z.array(RawTargetSchema).optional() });
+export const ActivitiesResponseSchema = z.object({ activities: z.array(RawChemblActivitySchema).optional() });
+export const MechanismsResponseSchema = z.object({ mechanisms: z.array(RawChemblMechanismSchema).optional() });
+export const DrugIndicationsResponseSchema = z.object({ drug_indications: z.array(RawDrugIndicationSchema).optional() });
+export const MoleculeSearchResponseSchema = z.object({ molecules: z.array(RawChemblMoleculeSchema).optional() });
 const TargetNameResponseSchema = z.object({ pref_name: z.string().optional() });
-const MoleculeStructuresResponseSchema = z.object({
-    molecule_structures: z.object({ standard_inchi_key: z.string().nullable().optional() }).optional(),
+export const MoleculeStructuresResponseSchema = z.object({
+    molecule_structures: z.object({ standard_inchi_key: z.string().nullable().optional() }).nullable().optional(),
 });
 const TargetComponentsResponseSchema = z.object({
     target_components: z.array(z.object({ accession: z.string().optional(), component_type: z.string().optional() })).optional(),
@@ -90,9 +117,11 @@ const CompoundRecordSchema = z
         .optional(),
     molecule_properties: z
         .object({
-        full_mwt: z.string().nullable().optional(),
-        alogp: z.string().nullable().optional(),
-        molecular_formula: z.string().nullable().optional(),
+        full_mwt: zWireNumber.nullable().optional(),
+        alogp: zWireNumber.nullable().optional(),
+        // `full_molformula` is the wire name of the molecular formula. The
+        // `molecule_properties` block carries no `molecular_formula` key.
+        full_molformula: z.string().nullable().optional(),
     })
         .nullable()
         .optional(),
@@ -101,11 +130,11 @@ const CompoundRecordSchema = z
     chemblId: raw.molecule_chembl_id ?? "",
     preferredCompoundName: raw.pref_name ?? null,
     canonicalSmiles: raw.molecule_structures?.canonical_smiles ?? null,
-    molecularWeight: raw.molecule_properties?.full_mwt ? parseFloat(raw.molecule_properties.full_mwt) : null,
-    alogp: raw.molecule_properties?.alogp ? parseFloat(raw.molecule_properties.alogp) : null,
-    molecularFormula: raw.molecule_properties?.molecular_formula ?? null,
+    molecularWeight: raw.molecule_properties?.full_mwt ?? null,
+    alogp: raw.molecule_properties?.alogp ?? null,
+    molecularFormula: raw.molecule_properties?.full_molformula ?? null,
 }));
-const CompoundsResponseSchema = z.object({ molecules: z.array(CompoundRecordSchema).optional() });
+export const CompoundsResponseSchema = z.object({ molecules: z.array(CompoundRecordSchema).optional() });
 // The two hops of the target-mode compound search read one id each, so they
 // project the response down to that id rather than reusing the richer
 // target/activity schemas above.
@@ -139,12 +168,6 @@ function mapTarget(raw) {
         geneNames: extractGeneNames(raw.target_components),
     };
 }
-function parseNumeric(val) {
-    if (val == null)
-        return null;
-    const n = typeof val === "number" ? val : parseFloat(val);
-    return Number.isNaN(n) ? null : n;
-}
 /**
  * Compounds assayed against a target: resolve the query to a target ChEMBL ID,
  * read that target's activity rows, then fetch the unique molecules behind them.
@@ -264,11 +287,11 @@ export async function getBioactivity(chemblId, type, options = {}) {
         compoundChemblId: raw.molecule_chembl_id ?? "",
         targetChemblId: raw.target_chembl_id ?? null,
         standardType: raw.standard_type ?? null,
-        standardValue: parseNumeric(raw.standard_value),
+        standardValue: raw.standard_value ?? null,
         standardUnits: raw.standard_units ?? null,
         assayChemblId: raw.assay_chembl_id ?? null,
         assayType: raw.assay_type ?? null,
-        pchemblValue: parseNumeric(raw.pchembl_value),
+        pchemblValue: raw.pchembl_value ?? null,
     }));
 }
 async function fetchTargetName(targetChemblId) {
@@ -311,56 +334,137 @@ export async function getMechanism(chemblId) {
         moleculeChemblId: raw.molecule_chembl_id ?? "",
     }));
 }
-function extractIndication(indications) {
-    if (!indications?.length)
-        return null;
+function mapDrug(raw, indication) {
+    return {
+        moleculeChemblId: raw.molecule_chembl_id ?? "",
+        preferredName: raw.pref_name ?? null,
+        maxPhase: raw.max_phase ?? null,
+        moleculeType: raw.molecule_type ?? null,
+        firstApproval: raw.first_approval ?? null,
+        indication,
+    };
+}
+/** Join the disease terms of one molecule. The MeSH heading is the curated name, thus it comes first. */
+function joinIndicationTerms(rows) {
     const terms = new Set();
-    for (const ind of indications) {
-        if (ind.mesh_heading)
-            terms.add(ind.mesh_heading);
-        else if (ind.efo_term)
-            terms.add(ind.efo_term);
+    for (const row of rows) {
+        const term = row.mesh_heading ?? row.efo_term;
+        if (term)
+            terms.add(term);
     }
     return terms.size > 0 ? [...terms].join("; ") : null;
 }
-export async function getDrugInfo(query, limit = 25) {
-    const drugUrl = `${CHEMBL_BASE}/drug/search.json?q=${encodeURIComponent(query)}&limit=${limit}`;
-    const drugRes = await apiFetchValidated(drugUrl, DrugSearchResponseSchema, { headers: HEADERS });
-    if (drugRes.isOk() && drugRes.value.drugs?.length) {
-        return drugRes.value.drugs.map((raw) => ({
-            moleculeChemblId: raw.molecule_chembl_id ?? "",
-            preferredName: raw.pref_name ?? null,
-            maxPhase: raw.max_phase != null ? Number(raw.max_phase) : null,
-            moleculeType: raw.molecule_type ?? null,
-            firstApproval: raw.first_approval ?? null,
-            indication: extractIndication(raw.drug_indications),
-        }));
+/**
+ * Read the `drug_indication` resource under one filter.
+ *
+ * The rows come highest-phase first, thus an approved indication survives the
+ * `limit` of a disease that hundreds of molecules carry.
+ */
+async function fetchDrugIndications(filter, limit) {
+    const url = `${CHEMBL_BASE}/drug_indication.json?${filter}&order_by=-max_phase_for_ind&limit=${limit}`;
+    const res = await apiFetchValidated(url, DrugIndicationsResponseSchema, { headers: HEADERS });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    return res.value.drug_indications ?? [];
+}
+/** Read one batch of molecule records by id. */
+async function fetchMoleculeSet(moleculeChemblIds) {
+    const res = await apiFetchValidated(`${CHEMBL_BASE}/molecule/set/${moleculeChemblIds.join(";")}.json`, MoleculeSearchResponseSchema, {
+        headers: HEADERS,
+    });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    return res.value.molecules ?? [];
+}
+/** Collect the indication rows of each molecule, up to `maxMolecules` molecules. */
+function groupIndicationsByMolecule(rows, maxMolecules) {
+    const byMolecule = new Map();
+    for (const row of rows) {
+        const moleculeChemblId = row.molecule_chembl_id;
+        if (!moleculeChemblId)
+            continue;
+        const collected = byMolecule.get(moleculeChemblId);
+        if (collected)
+            collected.push(row);
+        else if (byMolecule.size < maxMolecules)
+            byMolecule.set(moleculeChemblId, [row]);
     }
-    if (drugRes.isErr() && !(drugRes.error.type === "http_status" && drugRes.error.status === 404)) {
-        throw new Error(describeApiError(drugRes.error));
+    return byMolecule;
+}
+/** The drugs that ChEMBL indexes under a disease term, with the terms that matched. */
+async function searchDrugsByIndication(query, limit) {
+    const encoded = encodeURIComponent(query);
+    // The two filters cover the two vocabularies of the resource. EFO comes first,
+    // because it carries the finer term, and a MeSH-only query still reaches the
+    // second read.
+    let rows = await fetchDrugIndications(`efo_term__icontains=${encoded}`, limit);
+    if (rows.length === 0)
+        rows = await fetchDrugIndications(`mesh_heading__icontains=${encoded}`, limit);
+    const byMolecule = groupIndicationsByMolecule(rows, limit);
+    if (byMolecule.size === 0)
+        return [];
+    const molecules = await fetchMoleculeSet([...byMolecule.keys()]);
+    return molecules.map((raw) => mapDrug(raw, joinIndicationTerms(byMolecule.get(raw.molecule_chembl_id ?? "") ?? [])));
+}
+/** The indication terms of each named molecule, keyed by the molecule id. */
+async function fetchIndicationsOf(moleculeChemblIds) {
+    if (moleculeChemblIds.length === 0)
+        return new Map();
+    // A molecule carries one row for each disease term, thus the cap scales with the
+    // number of molecules that the caller resolved.
+    const rows = await fetchDrugIndications(`molecule_chembl_id__in=${moleculeChemblIds.join(",")}`, moleculeChemblIds.length * INDICATIONS_PER_DRUG);
+    const terms = new Map();
+    for (const [moleculeChemblId, collected] of groupIndicationsByMolecule(rows, moleculeChemblIds.length)) {
+        const joined = joinIndicationTerms(collected);
+        if (joined)
+            terms.set(moleculeChemblId, joined);
     }
-    const molUrl = `${CHEMBL_BASE}/molecule/search.json?q=${encodeURIComponent(query)}&limit=${limit}`;
-    const molRes = await apiFetchValidated(molUrl, MoleculeSearchResponseSchema, { headers: HEADERS });
-    if (molRes.isErr()) {
-        if (molRes.error.type === "http_status" && molRes.error.status === 404)
+    return terms;
+}
+/** The approved molecules whose name matches the query. */
+async function searchApprovedDrugsByName(query, limit) {
+    const url = `${CHEMBL_BASE}/molecule/search.json?q=${encodeURIComponent(query)}&limit=${limit}`;
+    const res = await apiFetchValidated(url, MoleculeSearchResponseSchema, { headers: HEADERS });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
             return [];
-        throw new Error(describeApiError(molRes.error));
+        throw new Error(describeApiError(res.error));
     }
-    const approved = (molRes.value.molecules ?? []).filter((mol) => mol.max_phase != null && mol.max_phase >= 4);
-    return approved.map((raw) => ({
-        moleculeChemblId: raw.molecule_chembl_id ?? "",
-        preferredName: raw.pref_name ?? null,
-        maxPhase: raw.max_phase != null ? Number(raw.max_phase) : null,
-        moleculeType: raw.molecule_type ?? null,
-        firstApproval: raw.first_approval ?? null,
-        indication: null,
-    }));
+    const approved = (res.value.molecules ?? []).filter((mol) => mol.max_phase != null && mol.max_phase >= APPROVED_MAX_PHASE);
+    if (approved.length === 0)
+        return [];
+    const moleculeChemblIds = approved.map((mol) => mol.molecule_chembl_id).filter((id) => id !== undefined && id.length > 0);
+    const indications = await fetchIndicationsOf(moleculeChemblIds);
+    return approved.map((raw) => mapDrug(raw, indications.get(raw.molecule_chembl_id ?? "") ?? null));
+}
+/**
+ * Approved drugs by name or by disease term.
+ *
+ * The `drug` resource of ChEMBL has no search endpoint, and it carries neither a
+ * name nor an indication. The molecule name search runs first, because an
+ * `icontains` read of `drug_indication` captures a drug name that is a substring
+ * of a disease term ("insulin" matches "insulin resistance"). A query that
+ * names no molecule falls through to the indication read, which answers
+ * highest-phase first and can carry a clinical-stage molecule below approval.
+ */
+export async function getDrugInfo(query, limit = 25) {
+    const byName = await searchApprovedDrugsByName(query, limit);
+    if (byName.length > 0)
+        return byName;
+    return searchDrugsByIndication(query, limit);
 }
 /**
  * Fetch all clinical-stage modulators (max_phase ≥ 2 by default) for a target.
  * Used for §2.6.6 (class precedent) and as the input to §2.6.4 (off-target panel).
  */
-export async function getTargetModulators(targetChemblId, options = {}) {
+export async function getTargetModulators(targetChemblId, options = {}, logger) {
+    const log = (logger ?? createNoopLogger()).named("chembl-client.target-modulators").with({ targetChemblId });
     const minPhase = options.minPhase ?? 2;
     const limit = options.limit ?? 200;
     const mechUrl = `${CHEMBL_BASE}/mechanism.json?target_chembl_id=${encodeURIComponent(targetChemblId)}` + `&limit=${limit}`;
@@ -386,10 +490,12 @@ export async function getTargetModulators(targetChemblId, options = {}) {
             const res = await apiFetchValidated(`${CHEMBL_BASE}/molecule/${id}.json`, RawChemblMoleculeSchema, {
                 headers: HEADERS,
             });
-            if (res.isErr())
+            if (res.isErr()) {
+                reportSkippedMolecule(log, res.error, id);
                 return null;
+            }
             const m = res.value;
-            const phase = m.max_phase != null ? Number(m.max_phase) : null;
+            const phase = m.max_phase ?? null;
             if (phase == null || phase < minPhase)
                 return null;
             return {
@@ -429,7 +535,7 @@ export async function getModulatorPolypharmacology(moleculeChemblId, options = {
             continue;
         if (options.excludeTargetChemblId && tid === options.excludeTargetChemblId)
             continue;
-        const pchembl = parseNumeric(raw.pchembl_value);
+        const pchembl = raw.pchembl_value ?? null;
         const existing = byTarget.get(tid);
         if (!existing || (pchembl != null && (existing.pchemblValue == null || pchembl > existing.pchemblValue))) {
             byTarget.set(tid, {
@@ -438,7 +544,7 @@ export async function getModulatorPolypharmacology(moleculeChemblId, options = {
                 targetName: null,
                 assayChemblId: raw.assay_chembl_id ?? null,
                 standardType: raw.standard_type ?? null,
-                standardValue: parseNumeric(raw.standard_value),
+                standardValue: raw.standard_value ?? null,
                 standardUnits: raw.standard_units ?? null,
                 pchemblValue: pchembl,
             });
@@ -466,14 +572,17 @@ export async function getModulatorPolypharmacology(moleculeChemblId, options = {
  * Used by the polypharm fanout step so the assembler's computeSelectivity
  * can produce real fold values instead of selectivity_unknown.
  */
-export async function getModulatorOnTargetPchembl(modulatorChemblId, targetChemblId) {
+export async function getModulatorOnTargetPchembl(modulatorChemblId, targetChemblId, logger) {
+    const log = (logger ?? createNoopLogger()).named("chembl-client.on-target-pchembl").with({ targetChemblId });
     const url = `${CHEMBL_BASE}/activity.json?molecule_chembl_id=${encodeURIComponent(modulatorChemblId)}` +
         `&target_chembl_id=${encodeURIComponent(targetChemblId)}` +
         `&pchembl_value__isnull=false&limit=10`;
     const res = await apiFetchValidated(url, ActivitiesResponseSchema, { headers: HEADERS });
-    if (res.isErr())
+    if (res.isErr()) {
+        reportSkippedMolecule(log, res.error, modulatorChemblId);
         return null;
-    const values = (res.value.activities ?? []).map((a) => parseNumeric(a.pchembl_value)).filter((v) => v !== null);
+    }
+    const values = (res.value.activities ?? []).map((a) => a.pchembl_value).filter((v) => v != null);
     if (values.length === 0)
         return null;
     values.sort((a, b) => a - b);
@@ -493,8 +602,9 @@ export async function getModulatorOnTargetPchembl(modulatorChemblId, targetChemb
  * Returns one `ChemblModulator` per unique molecule that passes the
  * min-phase and molecule-type filters.
  */
-export async function getModulatorsViaActivity(args) {
+export async function getModulatorsViaActivity(args, logger) {
     const { target_chembl_id, max_phase_min = 2, molecule_type, limit = 50 } = args;
+    const log = (logger ?? createNoopLogger()).named("chembl-client.modulators-via-activity").with({ targetChemblId: target_chembl_id });
     let url = `${CHEMBL_BASE}/activity.json?target_chembl_id=${encodeURIComponent(target_chembl_id)}` + `&max_phase__gte=${max_phase_min}&limit=${limit}`;
     if (molecule_type) {
         url += `&molecule_type=${encodeURIComponent(molecule_type)}`;
@@ -522,10 +632,12 @@ export async function getModulatorsViaActivity(args) {
             const molRes = await apiFetchValidated(`${CHEMBL_BASE}/molecule/${id}.json`, RawChemblMoleculeSchema, {
                 headers: HEADERS,
             });
-            if (molRes.isErr())
+            if (molRes.isErr()) {
+                reportSkippedMolecule(log, molRes.error, id);
                 return null;
+            }
             const m = molRes.value;
-            const phase = m.max_phase != null ? Number(m.max_phase) : null;
+            const phase = m.max_phase ?? null;
             if (phase == null || phase < max_phase_min)
                 return null;
             const molType = m.molecule_type ?? null;

package/dist/tools/lib/clinical-benchmarks-client.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Absence policy: this file calls no external API, thus no wire encodes an
+ * absent value. The bundled dataset gives each key, and `getBenchmarks` answers
+ * with the "all" baseline for an unknown therapeutic area.
+ */
 export interface PhaseTransitions {
     phase1_to_phase2: number;
     phase2_to_phase3: number;

package/dist/tools/lib/clinical-benchmarks-client.js

@@ -1,3 +1,8 @@
+/**
+ * Absence policy: this file calls no external API, thus no wire encodes an
+ * absent value. The bundled dataset gives each key, and `getBenchmarks` answers
+ * with the "all" baseline for an unknown therapeutic area.
+ */
 import benchmarksData from "../../data/clinical-benchmarks.json" with { type: "json" };
 const dataset = benchmarksData;
 if (!dataset.phase_transitions || !dataset.phase_transitions.all) {

package/dist/tools/lib/clinical-trials-client.d.ts

@@ -3,6 +3,10 @@
  *
  * Used by target-assessment workflow steps for §2.5 (clinical record),
  * §2.6.3 (trial AEs), §2.5 (failed trials), and §6.5 (discovery trials).
+ *
+ * Absence policy: the API omits the key of an absent value, and its OpenAPI
+ * document marks nothing as nullable. Thus a maybe-absent field carries
+ * `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
 export interface ClinicalTrial {
@@ -70,12 +74,18 @@ export interface TrialDetails {
     adverseEventGroups: AdverseEventGroup[];
     adverseEvents: AdverseEvent[];
 }
+/**
+ * One phase token of `protocolSection.designModule.phases`. `NA` marks a study
+ * that runs under no phase, such as an observational study.
+ */
+export type TrialPhase = "EARLY_PHASE1" | "PHASE1" | "PHASE2" | "PHASE3" | "PHASE4" | "NA";
 export interface SearchOptions {
-    phase?: "EARLY_PHASE1" | "PHASE1" | "PHASE2" | "PHASE3" | "PHASE4";
+    phase?: TrialPhase;
     status?: "RECRUITING" | "ACTIVE_NOT_RECRUITING" | "COMPLETED" | "NOT_YET_RECRUITING" | "TERMINATED" | "WITHDRAWN" | "SUSPENDED";
     limit?: number;
 }
-declare const CtStudySchema: z.ZodObject<{
+/** One study record. It is exported so that the golden-fixture table drives it. */
+export declare const CtStudySchema: z.ZodObject<{
     protocolSection: z.ZodOptional<z.ZodObject<{
         identificationModule: z.ZodOptional<z.ZodObject<{
             nctId: z.ZodOptional<z.ZodString>;
@@ -184,7 +194,126 @@ declare const CtStudySchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 type CtStudy = z.infer<typeof CtStudySchema>;
+/** The search envelope. It is exported so that the golden-fixture table drives it. */
+export declare const CtSearchResponseSchema: z.ZodObject<{
+    studies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        protocolSection: z.ZodOptional<z.ZodObject<{
+            identificationModule: z.ZodOptional<z.ZodObject<{
+                nctId: z.ZodOptional<z.ZodString>;
+                briefTitle: z.ZodOptional<z.ZodString>;
+                officialTitle: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            statusModule: z.ZodOptional<z.ZodObject<{
+                overallStatus: z.ZodOptional<z.ZodString>;
+                whyStopped: z.ZodOptional<z.ZodString>;
+                startDateStruct: z.ZodOptional<z.ZodObject<{
+                    date: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                primaryCompletionDateStruct: z.ZodOptional<z.ZodObject<{
+                    date: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            designModule: z.ZodOptional<z.ZodObject<{
+                phases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                studyType: z.ZodOptional<z.ZodString>;
+                designInfo: z.ZodOptional<z.ZodObject<{
+                    primaryPurpose: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                enrollmentInfo: z.ZodOptional<z.ZodObject<{
+                    count: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            descriptionModule: z.ZodOptional<z.ZodObject<{
+                briefSummary: z.ZodOptional<z.ZodString>;
+                detailedDescription: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            conditionsModule: z.ZodOptional<z.ZodObject<{
+                conditions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            armsInterventionsModule: z.ZodOptional<z.ZodObject<{
+                interventions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodOptional<z.ZodString>;
+                    type: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    otherNames: z.ZodOptional<z.ZodUnknown>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            sponsorCollaboratorsModule: z.ZodOptional<z.ZodObject<{
+                leadSponsor: z.ZodOptional<z.ZodObject<{
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            outcomesModule: z.ZodOptional<z.ZodObject<{
+                primaryOutcomes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    measure: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    timeFrame: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                secondaryOutcomes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    measure: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    timeFrame: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                otherOutcomes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    measure: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    timeFrame: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        resultsSection: z.ZodOptional<z.ZodObject<{
+            outcomeMeasuresModule: z.ZodOptional<z.ZodObject<{
+                outcomeMeasures: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    title: z.ZodOptional<z.ZodString>;
+                    unitOfMeasure: z.ZodOptional<z.ZodString>;
+                    classes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                            measurements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                                value: z.ZodOptional<z.ZodString>;
+                                lowerLimit: z.ZodOptional<z.ZodString>;
+                                upperLimit: z.ZodOptional<z.ZodString>;
+                            }, z.core.$strip>>>;
+                        }, z.core.$strip>>>;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            adverseEventsModule: z.ZodOptional<z.ZodObject<{
+                eventGroups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    id: z.ZodOptional<z.ZodString>;
+                    title: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                seriousEvents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    term: z.ZodOptional<z.ZodString>;
+                    organSystem: z.ZodOptional<z.ZodString>;
+                    stats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        groupId: z.ZodOptional<z.ZodString>;
+                        numAffected: z.ZodOptional<z.ZodNumber>;
+                        numAtRisk: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>>>;
+                otherEvents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    term: z.ZodOptional<z.ZodString>;
+                    organSystem: z.ZodOptional<z.ZodString>;
+                    stats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        groupId: z.ZodOptional<z.ZodString>;
+                        numAffected: z.ZodOptional<z.ZodNumber>;
+                        numAtRisk: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    totalCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare function mapClinicalTrialStudy(s: CtStudy): ClinicalTrial;
+/**
+ * Search the registry.
+ *
+ * `totalFound` is the count of the whole query, which `countTotal=true` asks
+ * for. A phase filter runs over the returned page only, thus `totalFound` can
+ * exceed the number of trials that the answer carries.
+ */
 export declare function searchTrials(query: string, options?: SearchOptions): Promise<{
     totalFound: number;
     trials: ClinicalTrial[];