@inflexa-ai/harness 0.30.3 → 0.31.0

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

@@ -1,91 +1,96 @@
 /**
- * Pure async client functions for DrugBank.
+ * Pure async client functions for the DrugBank Discovery API.
+ *
+ * CONTRACT UNVERIFIED (key-blocked, 2026-08-28). No key exists here, and an
+ * unauthenticated probe answers 401 before it routes, thus no live call proves
+ * a route or a record. The evidence is secondary: the Wayback captures of
+ * `docs.drugbank.com/discovery/v1` and the sample code of the provider. Refer to
+ * the truth map, file 07, section 1.
  *
  * Requires a DrugBank API key; `getDrugbankHeaders` throws when it is absent.
+ *
+ * Absence policy: no evidence establishes the encoding of an absent value,
+ * because no key exists for a live call and both fixtures are synthetic. Each
+ * maybe-absent field carries `.optional()` today, and no field carries
+ * `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
 import { DRUGBANK_BASE, getDrugbankHeaders } from "./drugbank-config.js";
 /** Hard ceiling on each prose field at the parse boundary; callers trim further. */
 const PROSE_CEILING = 500;
-// A single schema that both validates and normalizes one DrugBank record.
-// The `.object(...)` half is the snake_case wire shape (every field optional —
-// the API omits absent values); the `.transform(...)` half maps it into the
-// camelCase result we return. Parsing IS the validation: `apiFetchValidated`
-// runs this schema over the JSON, so a payload whose field TYPES drift (an
-// object where the API used to send an array, a number for a string) is
-// rejected as `invalid_response` instead of being silently mis-mapped. Because
-// the schema carries the transform, `z.infer` below is the OUTPUT (camelCase)
-// type callers receive — there is no separate raw interface or mapper to keep
-// in sync.
+/** The page ceiling of the `per_page` parameter. There is no `limit` parameter. */
+const MAX_PER_PAGE = 50;
+// A single schema that both validates and normalizes one Discovery drug record.
+// The `.object(...)` half is the snake_case wire shape; the `.transform(...)`
+// half maps it into the camelCase result we return. Parsing IS the validation:
+// `apiFetchValidated` runs this schema over the JSON, so a payload whose field
+// TYPES drift is rejected as `invalid_response` instead of being silently
+// mis-mapped. Because the schema carries the transform, `z.infer` below is the
+// OUTPUT (camelCase) type callers receive.
+//
+// `drugbank_id` is MANDATORY. It is the one key that every Discovery record
+// carries, thus an error envelope such as `{"error":"Key invalid"}` fails the
+// parse and the caller sees `invalid_response` rather than one blank drug row.
 const DrugResultSchema = z
     .object({
-    drugbank_id: z.string().optional(),
+    drugbank_id: z.string(),
     name: z.string().optional(),
     description: z.string().optional(),
     type: z.string().optional(),
     groups: z.array(z.string()).optional(),
-    categories: z.array(z.object({ category: z.string().optional() })).optional(),
-    indication: z.string().optional(),
-    pharmacodynamics: z.string().optional(),
-    mechanism_of_action: z.string().optional(),
-    toxicity: z.string().optional(),
-    half_life: z.string().optional(),
-    targets: z
-        .array(z.object({
-        name: z.string().optional(),
-        gene_name: z.string().optional(),
-        actions: z.array(z.string()).optional(),
-        known_action: z.string().optional(),
-    }))
-        .optional(),
-    drug_interactions: z
-        .array(z.object({
-        drugbank_id: z.string().optional(),
-        name: z.string().optional(),
-        description: z.string().optional(),
-    }))
-        .optional(),
 })
     .transform((raw) => ({
-    drugbankId: raw.drugbank_id ?? "",
+    drugbankId: raw.drugbank_id,
     name: raw.name ?? "",
     description: (raw.description ?? "").slice(0, PROSE_CEILING),
     type: raw.type ?? "",
     groups: raw.groups ?? [],
-    categories: (raw.categories ?? []).map((c) => c.category ?? "").filter(Boolean),
-    indication: (raw.indication ?? "").slice(0, PROSE_CEILING),
-    pharmacodynamics: (raw.pharmacodynamics ?? "").slice(0, PROSE_CEILING),
-    mechanismOfAction: (raw.mechanism_of_action ?? "").slice(0, PROSE_CEILING),
-    toxicity: (raw.toxicity ?? "").slice(0, PROSE_CEILING),
-    halfLife: raw.half_life ?? "",
-    targets: (raw.targets ?? []).map((t) => ({
-        name: t.name ?? "",
-        geneSymbol: t.gene_name ?? "",
-        actions: t.actions ?? [],
-        knownAction: t.known_action ?? "",
-    })),
-    interactions: (raw.drug_interactions ?? []).map((i) => ({
-        drugbankId: i.drugbank_id ?? "",
-        name: i.name ?? "",
-        description: (i.description ?? "").slice(0, 200),
-    })),
 }));
-// The /drugs endpoint returns a single object (by-id lookup) or an array
-// (query/target lookups); accept either, transforming each element.
-const DrugResponseSchema = z.union([DrugResultSchema, z.array(DrugResultSchema)]);
+// The Discovery API wraps nothing: a list route answers with a bare JSON array,
+// and a lookup route answers with a bare object. Accept either, and transform
+// each element.
+export const DrugResponseSchema = z.union([DrugResultSchema, z.array(DrugResultSchema)]);
+// One bond of `/bonds/targets`. The row names the drug that binds the target,
+// thus a gene query reaches the drugs through the bonds. The bond carries no
+// drug record beyond the id and the name.
+export const BondResponseSchema = z.array(z.object({
+    drug: z.object({ drugbank_id: z.string(), name: z.string().optional() }),
+}));
+/** Translate the internal limit into the `per_page` of the provider. */
+function perPageOf(limit) {
+    return Math.min(Math.max(limit, 1), MAX_PER_PAGE);
+}
+/** The drugs that bind a target, keyed by the gene name of its polypeptides. */
+async function searchDrugbankByTarget(headers, gene, limit) {
+    const query = encodeURIComponent(`polypeptides.gene_name:${gene}`);
+    const url = `${DRUGBANK_BASE}/bonds/targets?q=${query}&per_page=${perPageOf(limit)}`;
+    const res = await apiFetchValidated(url, BondResponseSchema, { headers });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    // One drug binds a target through more than one bond, thus the rows repeat a
+    // drug. The map keeps the first row of each drug.
+    const drugs = new Map();
+    for (const bond of res.value) {
+        if (drugs.has(bond.drug.drugbank_id))
+            continue;
+        drugs.set(bond.drug.drugbank_id, {
+            drugbankId: bond.drug.drugbank_id,
+            name: bond.drug.name ?? "",
+            description: "",
+            type: "",
+            groups: [],
+        });
+    }
+    return [...drugs.values()].slice(0, limit);
+}
 export async function searchDrugbank(apiKey, query, searchType, limit = 10) {
     const headers = getDrugbankHeaders(apiKey);
-    let url;
-    if (searchType === "target") {
-        url = `${DRUGBANK_BASE}/drugs?target=${encodeURIComponent(query)}&limit=${limit}`;
-    }
-    else if (query.startsWith("DB")) {
-        url = `${DRUGBANK_BASE}/drugs/${query}`;
-    }
-    else {
-        url = `${DRUGBANK_BASE}/drugs?q=${encodeURIComponent(query)}&limit=${limit}`;
-    }
+    if (searchType === "target")
+        return searchDrugbankByTarget(headers, query, limit);
+    const url = query.startsWith("DB")
+        ? `${DRUGBANK_BASE}/drugs/${encodeURIComponent(query)}`
+        : `${DRUGBANK_BASE}/drugs?q=${encodeURIComponent(query)}&per_page=${perPageOf(limit)}`;
     const res = await apiFetchValidated(url, DrugResponseSchema, { headers });
     if (res.isErr())
         throw new Error(describeApiError(res.error));

package/dist/tools/lib/drugbank-config.d.ts

@@ -1,2 +1,7 @@
-export declare const DRUGBANK_BASE = "https://api.drugbank.com/v1";
+/**
+ * The Discovery API of DrugBank. The Clinical API (`/v1`) serves no `?q=` search
+ * on its drug resource, thus only Discovery answers a name search and a target
+ * search.
+ */
+export declare const DRUGBANK_BASE = "https://api.drugbank.com/discovery/v1";
 export declare function getDrugbankHeaders(apiKey: string): Record<string, string>;

package/dist/tools/lib/drugbank-config.js

@@ -1,4 +1,9 @@
-export const DRUGBANK_BASE = "https://api.drugbank.com/v1";
+/**
+ * The Discovery API of DrugBank. The Clinical API (`/v1`) serves no `?q=` search
+ * on its drug resource, thus only Discovery answers a name search and a target
+ * search.
+ */
+export const DRUGBANK_BASE = "https://api.drugbank.com/discovery/v1";
 export function getDrugbankHeaders(apiKey) {
     const key = apiKey;
     if (!key) {

package/dist/tools/lib/ema-client.d.ts

@@ -7,7 +7,12 @@
  * Article 20, etc.). We fetch and cache it in-process; per-drug queries
  * filter the cached records by INN, referral name, and associated
  * medicine names.
+ *
+ * Absence policy: the bulk file gives each key and writes an absent value as
+ * the empty string. Thus a field carries neither `.nullable()` nor
+ * `.optional()`.
  */
+import { z } from "zod";
 export interface EmaReferral {
     category: string;
     referralName: string;
@@ -29,6 +34,54 @@ export interface EmaReferral {
     lastUpdatedDate: string;
     referralUrl: string;
 }
+/** The catalogue file. It is exported so that the golden-fixture table drives it. */
+export declare const ReferralFileSchema: z.ZodObject<{
+    meta: z.ZodOptional<z.ZodObject<{
+        total_records: z.ZodOptional<z.ZodNumber>;
+        timestamp: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    data: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        referral_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        international_non_proprietary_name_inn_common_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        current_status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        safety_referral: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        referral_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        associated_names_centrally_authorised_medicines: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        associated_names_non_centrally_authorised_medicines: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        class: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        reference_number: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authorisation_model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        procedure_start_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        prac_recommendation_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        cmdh_position_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        chmp_cvmp_opinion_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        european_commission_decision_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        first_published_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        last_updated_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        referral_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodTransform<EmaReferral, {
+        category?: string | null | undefined;
+        referral_name?: string | null | undefined;
+        international_non_proprietary_name_inn_common_name?: string | null | undefined;
+        current_status?: string | null | undefined;
+        safety_referral?: string | null | undefined;
+        referral_type?: string | null | undefined;
+        associated_names_centrally_authorised_medicines?: string | null | undefined;
+        associated_names_non_centrally_authorised_medicines?: string | null | undefined;
+        class?: string | null | undefined;
+        reference_number?: string | null | undefined;
+        authorisation_model?: string | null | undefined;
+        procedure_start_date?: string | null | undefined;
+        prac_recommendation_date?: string | null | undefined;
+        cmdh_position_date?: string | null | undefined;
+        chmp_cvmp_opinion_date?: string | null | undefined;
+        european_commission_decision_date?: string | null | undefined;
+        first_published_date?: string | null | undefined;
+        last_updated_date?: string | null | undefined;
+        referral_url?: string | null | undefined;
+    }>>>>;
+}, z.core.$strip>;
 /**
  * Download (or return cached) full EMA referrals catalogue. The catalogue
  * updates twice daily — a 6h in-process TTL is well within freshness

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

@@ -7,26 +7,37 @@
  * Article 20, etc.). We fetch and cache it in-process; per-drug queries
  * filter the cached records by INN, referral name, and associated
  * medicine names.
+ *
+ * Absence policy: the bulk file gives each key and writes an absent value as
+ * the empty string. Thus a field carries neither `.nullable()` nor
+ * `.optional()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
 import { EMA_REFERRALS_URL } from "./ema-config.js";
+/**
+ * Split one medicine column into names.
+ *
+ * The separator is the semicolon alone. A comma belongs to the name of the
+ * medicine, for example `Lidocaïne / Prilocaïne 5% Focus, Crème`, thus a split on
+ * the comma breaks that name into two.
+ */
 function parseMedicineList(field) {
     if (!field || !field.trim())
         return [];
     return field
-        .split(/[;,]/)
+        .split(";")
         .map((s) => s.trim())
         .filter(Boolean);
 }
-// One schema that both validates the raw referral wire shape (snake_case, every
-// field optional or null — the bulk file omits or nulls absent values) and
+// One schema that both validates the raw referral wire shape (snake_case) and
 // normalizes it into the camelCase `EmaReferral` we return. Parsing IS the
 // validation: `apiFetchValidated` runs this over the download, so a record whose
 // field TYPES drift is rejected as `invalid_response` instead of silently
-// mis-mapped. Every field is `.nullable()` so one null-bearing record in the
-// ~600-row catalogue doesn't fail the whole `data` array (the transform already
-// collapses null to "" via `??`).
+// mis-mapped. The sampled records give each key and write an absent value as the
+// empty string. The modifiers stay wider than that sample, thus one odd record in
+// the ~600-row catalogue does not fail the whole `data` array. The transform
+// collapses a null to "" with `??`.
 const EmaReferralSchema = z
     .object({
     category: z.string().nullable().optional(),
@@ -70,7 +81,8 @@ const EmaReferralSchema = z
     lastUpdatedDate: raw.last_updated_date ?? "",
     referralUrl: raw.referral_url ?? "",
 }));
-const ReferralFileSchema = z.object({
+/** The catalogue file. It is exported so that the golden-fixture table drives it. */
+export const ReferralFileSchema = z.object({
     meta: z.object({ total_records: z.number().optional(), timestamp: z.string().optional() }).optional(),
     data: z.array(EmaReferralSchema).optional(),
 });

package/dist/tools/lib/ensembl-client.d.ts

@@ -2,6 +2,10 @@
  * Pure async client functions for the Ensembl REST API.
  *
  * Used by §1.1 (Entity resolution) and as a fallback for ID resolution.
+ *
+ * Absence policy: Ensembl omits the key of an absent value, and it never sends
+ * an explicit `null`. Thus a maybe-absent field carries `.optional()`, not
+ * `.nullable()`.
  */
 export interface GeneInfo {
     symbol: string;

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

@@ -2,6 +2,10 @@
  * Pure async client functions for the Ensembl REST API.
  *
  * Used by §1.1 (Entity resolution) and as a fallback for ID resolution.
+ *
+ * Absence policy: Ensembl omits the key of an absent value, and it never sends
+ * an explicit `null`. Thus a maybe-absent field carries `.optional()`, not
+ * `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";

package/dist/tools/lib/gwas-catalog-client.d.ts

@@ -5,6 +5,10 @@
  * per-SNP associations), by trait (EFO trait search then its associations), by
  * variant (direct rsID associations), and by study (the associations of one
  * GCST study accession).
+ *
+ * Absence policy: the sampled payloads show an explicit `null` for an absent
+ * leaf value, and the key set of one projection stays constant. A key is absent
+ * only when the projection that the request named excludes it.
  */
 import { z } from "zod";
 export interface GwasAssociation {
@@ -38,7 +42,9 @@ declare const RawGwasAssociationSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     study: z.ZodOptional<z.ZodObject<{
         accessionId: z.ZodOptional<z.ZodString>;
-        pubmedId: z.ZodOptional<z.ZodString>;
+        publicationInfo: z.ZodOptional<z.ZodObject<{
+            pubmedId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
         initialSampleSize: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     pvalueMantissa: z.ZodOptional<z.ZodNumber>;
@@ -49,6 +55,63 @@ declare const RawGwasAssociationSchema: z.ZodObject<{
     range: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 type RawGwasAssociation = z.infer<typeof RawGwasAssociationSchema>;
+export declare const GwasEmbeddedSchema: z.ZodObject<{
+    _embedded: z.ZodOptional<z.ZodObject<{
+        associations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            _snpRsId: z.ZodOptional<z.ZodString>;
+            loci: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                strongestRiskAlleles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    riskAlleleName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>>>;
+                authorReportedGenes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    geneName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>;
+            efoTraits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                trait: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>;
+            study: z.ZodOptional<z.ZodObject<{
+                accessionId: z.ZodOptional<z.ZodString>;
+                publicationInfo: z.ZodOptional<z.ZodObject<{
+                    pubmedId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strip>>;
+                initialSampleSize: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            pvalueMantissa: z.ZodOptional<z.ZodNumber>;
+            pvalueExponent: z.ZodOptional<z.ZodNumber>;
+            riskFrequency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            orPerCopyNum: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            betaNum: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            range: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    page: z.ZodOptional<z.ZodObject<{
+        totalElements: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const GwasTraitSearchResponseSchema: z.ZodObject<{
+    _embedded: z.ZodOptional<z.ZodObject<{
+        efoTraits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            _links: z.ZodOptional<z.ZodObject<{
+                self: z.ZodOptional<z.ZodObject<{
+                    href: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const GwasSnpSearchResponseSchema: z.ZodObject<{
+    _embedded: z.ZodOptional<z.ZodObject<{
+        singleNucleotidePolymorphisms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            rsId: z.ZodOptional<z.ZodString>;
+            _links: z.ZodOptional<z.ZodObject<{
+                associations: z.ZodOptional<z.ZodObject<{
+                    href: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare function mapAssociation(a: RawGwasAssociation): GwasAssociation;
 export interface GwasSearchOptions {
     pValueThreshold?: number;

package/dist/tools/lib/gwas-catalog-client.js

@@ -5,6 +5,10 @@
  * per-SNP associations), by trait (EFO trait search then its associations), by
  * variant (direct rsID associations), and by study (the associations of one
  * GCST study accession).
+ *
+ * Absence policy: the sampled payloads show an explicit `null` for an absent
+ * leaf value, and the key set of one projection stays constant. A key is absent
+ * only when the projection that the request named excludes it.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -12,9 +16,16 @@ import { GWAS_BASE, GWAS_HEADERS } from "./gwas-catalog-config.js";
 // GWAS Catalog raw wire shapes (HAL+JSON), validated at the fetch boundary.
 // Every field is optional because the API omits absent values; leaf strings
 // that the API can return as an explicit `null` are `.nullable()`.
+//
+// The `study` and `efoTraits` keys of an association exist only on some
+// projections: `associationByStudy` nests the study, `associationByEfoTrait`
+// nests the traits, and the gene path serves neither. Thus their absence is a
+// property of the projection that the request named, and it is not drift.
 const RawGwasStudySchema = z.object({
     accessionId: z.string().optional(),
-    pubmedId: z.string().optional(),
+    // The PubMed id is a field of the publication record, and never of the study
+    // record itself.
+    publicationInfo: z.object({ pubmedId: z.string().nullable().optional() }).optional(),
     initialSampleSize: z.string().optional(),
 });
 // `_snpRsId` is not on the wire — the 'gene' search path assigns it after
@@ -36,18 +47,18 @@ const RawGwasAssociationSchema = z.object({
     betaNum: z.number().nullable().optional(),
     range: z.string().nullable().optional(),
 });
-const GwasEmbeddedSchema = z.object({
+export const GwasEmbeddedSchema = z.object({
     _embedded: z.object({ associations: z.array(RawGwasAssociationSchema).optional() }).optional(),
     page: z.object({ totalElements: z.number().optional() }).optional(),
 });
-const GwasTraitSearchResponseSchema = z.object({
+export const GwasTraitSearchResponseSchema = z.object({
     _embedded: z
         .object({
         efoTraits: z.array(z.object({ _links: z.object({ self: z.object({ href: z.string().optional() }).optional() }).optional() })).optional(),
     })
         .optional(),
 });
-const GwasSnpSearchResponseSchema = z.object({
+export const GwasSnpSearchResponseSchema = z.object({
     _embedded: z
         .object({
         singleNucleotidePolymorphisms: z
@@ -79,7 +90,7 @@ export function mapAssociation(a) {
         trait: traits.join("; "),
         mappedGenes: [...new Set(genes)],
         studyAccession: String(study.accessionId ?? ""),
-        pubmedId: String(study.pubmedId ?? ""),
+        pubmedId: String(study.publicationInfo?.pubmedId ?? ""),
         sampleSize: String(study.initialSampleSize ?? ""),
     };
 }
@@ -123,7 +134,11 @@ export async function searchGwasCatalog(query, searchType, options = {}) {
         associationsUrl = `${GWAS_BASE}/studies/${encodeURIComponent(query)}/associations?projection=associationByStudy&size=${limit}`;
     }
     else {
-        const traitRes = await apiFetchValidated(`${GWAS_BASE}/efoTraits/search/findBySearchQuery?query=${encodeURIComponent(query)}`, GwasTraitSearchResponseSchema, {
+        // `findByEfoTrait` matches the EXACT EFO trait label (case-insensitive),
+        // and it answers HTTP 200 with an empty `efoTraits` list when nothing
+        // matches. A paraphrase of a label thus reads as clean no-data, and the
+        // tool description warns the caller.
+        const traitRes = await apiFetchValidated(`${GWAS_BASE}/efoTraits/search/findByEfoTrait?trait=${encodeURIComponent(query)}`, GwasTraitSearchResponseSchema, {
             headers: GWAS_HEADERS,
         });
         if (traitRes.isErr())

package/dist/tools/lib/identifier-resolver.d.ts

@@ -17,6 +17,8 @@
  * resolution failure aborts the assessment with `error.kind:
  * "target-unresolved"` (per design §6).
  */
+import { z } from "zod";
+import type { Logger } from "../../lib/logger.js";
 export interface ResolvedTarget {
     /** Canonical id used as the entity-resolution anchor — preferred order: HGNC, then Ensembl. */
     canonicalId: string;
@@ -48,12 +50,26 @@ export interface ResolvedTarget {
         chembl: boolean;
     };
 }
+export declare const HgncResponseSchema: z.ZodObject<{
+    response: z.ZodOptional<z.ZodObject<{
+        docs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            symbol: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            hgnc_id: z.ZodOptional<z.ZodString>;
+            ensembl_gene_id: z.ZodOptional<z.ZodString>;
+            uniprot_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            entrez_id: z.ZodOptional<z.ZodString>;
+            alias_symbol: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            prev_symbol: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * Resolve a free-form target identifier to a canonical entity.
  *
  * @throws when the input cannot be mapped to any human gene/protein.
  */
-export declare function resolveTarget(input: string): Promise<ResolvedTarget>;
+export declare function resolveTarget(input: string, logger?: Logger): Promise<ResolvedTarget>;
 export interface AutocompleteCandidate {
     /** Approved HGNC symbol when known, otherwise the input symbol. */
     symbol: string;

package/dist/tools/lib/identifier-resolver.js

@@ -18,6 +18,7 @@
  * "target-unresolved"` (per design §6).
  */
 import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { apiFetchValidated } from "./api-utils.js";
 import { resolveSymbolToEnsemblId } from "./ensembl-client.js";
 import { searchTargets as searchChemblTargets } from "./chembl-client.js";
@@ -33,7 +34,9 @@ const HGNC_RE = /^HGNC:\d+$/;
 // HGNC search payload, validated at the fetch boundary. Every field is optional
 // because the API omits absent values; each read below is optional-chained /
 // defaulted, so a missing field degrades gracefully rather than throwing.
-const HgncResponseSchema = z.object({
+// The schema is exported for the golden-fixture table, which is the only place
+// that asserts the contract itself instead of the resolved entity.
+export const HgncResponseSchema = z.object({
     response: z
         .object({
         docs: z
@@ -69,7 +72,6 @@ const UniprotResponseSchema = z.object({
             synonyms: z.array(z.object({ value: z.string().optional() })).optional(),
         }))
             .optional(),
-        proteinFamily: z.string().optional(),
         extraAttributes: z.object({ uniParcId: z.string().optional() }).optional(),
         keywords: z.array(z.object({ name: z.string().optional() })).optional(),
     }))
@@ -124,7 +126,8 @@ function extractProteinFamily(uniprotKeywords) {
  *
  * @throws when the input cannot be mapped to any human gene/protein.
  */
-export async function resolveTarget(input) {
+export async function resolveTarget(input, logger) {
+    const log = (logger ?? createNoopLogger()).named("identifier-resolver").with({ target: input });
     const trimmed = input.trim();
     if (!trimmed)
         throw new Error("Target identifier is required");
@@ -199,7 +202,13 @@ export async function resolveTarget(input) {
     // Step 4: ChEMBL
     let chemblId = seedChembl;
     if (!chemblId && symbolForEnsembl) {
-        const targets = await searchChemblTargets(symbolForEnsembl, 5).catch(() => []);
+        // `searchTargets` answers an unknown symbol with an empty list, thus a throw
+        // here is always an unexpected cause. Without this record the ChEMBL id stays
+        // null and every downstream collector reports a false "no ChEMBL entry".
+        const targets = await searchChemblTargets(symbolForEnsembl, 5).catch((error) => {
+            log.error("ChEMBL target search failed", { symbol: symbolForEnsembl, ...log.errorFields(error) });
+            return [];
+        });
         const human = targets.find((t) => t.organism === "Homo sapiens");
         chemblId = (human ?? targets[0])?.targetChemblId ?? null;
     }

package/dist/tools/lib/impc-client.d.ts

@@ -3,6 +3,10 @@
  * Consortium) Solr API.
  *
  * Used by §3.10.1 (Knockout phenotype card).
+ *
+ * Absence policy: the Solr API omits the key of an absent value, and it never
+ * sends an explicit `null`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
 export interface MpTerm {
     id: string;

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

@@ -3,6 +3,10 @@
  * Consortium) Solr API.
  *
  * Used by §3.10.1 (Knockout phenotype card).
+ *
+ * Absence policy: the Solr API omits the key of an absent value, and it never
+ * sends an explicit `null`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";

package/dist/tools/lib/iuphar-client.d.ts

@@ -10,13 +10,14 @@
  * panels never list a sibling receptor-complex as a developable hit.
  */
 import { z } from "zod";
-declare const IupharTargetSchema: z.ZodObject<{
+import type { Logger } from "../../lib/logger.js";
+export declare const IupharTargetSchema: z.ZodObject<{
     targetId: z.ZodNumber;
     name: z.ZodString;
     type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     familyIds: z.ZodArray<z.ZodNumber>;
     subunitIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-    complexIds: z.ZodArray<z.ZodNumber>;
+    complexIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     subunitType: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type IupharTarget = z.infer<typeof IupharTargetSchema>;
@@ -53,7 +54,7 @@ export declare function getFamilyHeterodimers(uniprotOrGeneSymbol: string): Prom
  * Example: getAccessoryProteinNames("CALCR") → ["RAMP1", "RAMP2", "RAMP3"].
  */
 export declare function getAccessoryProteinNames(uniprotOrGeneSymbol: string): Promise<string[]>;
-declare const IupharFamilySchema: z.ZodObject<{
+export declare const IupharFamilySchema: z.ZodObject<{
     familyId: z.ZodOptional<z.ZodNumber>;
     name: z.ZodOptional<z.ZodString>;
     targetIds: z.ZodArray<z.ZodNumber>;
@@ -62,6 +63,11 @@ declare const IupharFamilySchema: z.ZodObject<{
 }, z.core.$strip>;
 export type IupharFamily = z.infer<typeof IupharFamilySchema>;
 export declare function getFamily(familyId: number): Promise<IupharFamily | null>;
+export declare const IupharDatabaseLinkSchema: z.ZodObject<{
+    accession: z.ZodOptional<z.ZodString>;
+    database: z.ZodOptional<z.ZodString>;
+    species: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /** Fetch the UniProtKB cross-references (human only) for an IUPHAR target. */
 export declare function getTargetHumanUniprots(targetId: number): Promise<string[]>;
 /**
@@ -71,5 +77,4 @@ export declare function getTargetHumanUniprots(targetId: number): Promise<string
  * CALCRL accession; the AMY1/2/3 complexes are excluded because they are
  * heterodimers, not separate primary proteins.
  */
-export declare function getFamilySiblingUniprots(uniprotOrGeneSymbol: string): Promise<string[]>;
-export {};
+export declare function getFamilySiblingUniprots(uniprotOrGeneSymbol: string, logger?: Logger): Promise<string[]>;