@inflexa-ai/harness 0.30.2 → 0.31.0

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

@@ -10,20 +10,32 @@
  * panels never list a sibling receptor-complex as a developable hit.
  */
 import { z } from "zod";
-import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
 import { IUPHAR_BASE, IUPHAR_HEADERS as HEADERS } from "./iuphar-config.js";
-// Validated at the fetch boundary. GtoPdb returns familyIds/complexIds as
-// arrays on every target, and the resolver reads `.length` / iterates them
-// without a guard, so they stay required — a missing value surfaces as
-// `invalid_response` rather than a runtime TypeError. subunitIds and type are
-// only read behind a guard, so they may be absent.
-const IupharTargetSchema = z.object({
+// Validated at the fetch boundary. GtoPdb serves the target record in three
+// wire shapes under this one schema, and the key set differs per shape:
+//
+//   Shape A — the `/targets?…` list and `/targets/{id}/complexes`. It OMITS
+//     `complexIds`, and `type` is lower snake case (`gpcr`,
+//     `catalytic_receptor`, and `""` for an accessory protein).
+//   Shape B — `/targets/{id}/subunits`. It carries `complexIds` as a populated
+//     number array, and `type` is CamelCase (`GPCR`, `AccessoryProtein`).
+//   Shape C — `/targets/{id}`. Same key set as shape B, plus about 27 flat
+//     cross-reference keys, but `type` is the shape A casing again.
+//
+// Thus `complexIds` is optional, and its one read site in
+// `getFamilyHeterodimers` guards the omission. `familyIds` stays required,
+// because every shape sends it and an accessory protein sends `[]`. A missing
+// `familyIds` surfaces as `invalid_response` rather than as a runtime
+// TypeError.
+export const IupharTargetSchema = z.object({
     targetId: z.number(),
     name: z.string(),
     type: z.string().nullable().optional(),
     familyIds: z.array(z.number()),
     subunitIds: z.array(z.number()).optional(),
-    complexIds: z.array(z.number()),
+    complexIds: z.array(z.number()).optional(),
     subunitType: z.string().optional(),
 });
 const UNIPROT_ACCESSION_RE = /^[A-Z][0-9][A-Z0-9]{3}[0-9]$/;
@@ -93,7 +105,11 @@ export async function getSubunits(complexId) {
  */
 export async function getFamilyHeterodimers(uniprotOrGeneSymbol) {
     const target = await resolveTarget(uniprotOrGeneSymbol);
-    if (!target || target.complexIds.length === 0)
+    // `resolveTarget` gives a shape A record, which omits `complexIds`. An
+    // omission thus says nothing about the complexes of the target, and only a
+    // present and empty array proves that there is none. `?.length === 0` is
+    // false for the omission, thus the `/complexes` call below answers for it.
+    if (!target || target.complexIds?.length === 0)
         return [];
     const url = `${IUPHAR_BASE}/targets/${target.targetId}/complexes`;
     const res = await apiFetchValidated(url, z.array(IupharTargetSchema), { headers: HEADERS });
@@ -112,6 +128,12 @@ export async function getFamilyHeterodimers(uniprotOrGeneSymbol) {
             const complex = batch[j];
             const subunits = subunitLists[j];
             const cleanedSubunits = subunits.map((s) => ({ ...s, name: stripHtml(s.name) }));
+            // Only a shape B row reaches this filter, because `getSubunits`
+            // calls `/targets/{id}/subunits`. Shape B is the one shape that
+            // names the kind of a target as `AccessoryProtein`, and the
+            // lower-case compare matches that CamelCase form. Shape A and shape
+            // C send `""` for the same target, thus the same filter over a list
+            // row or a single-target row would match nothing.
             const accessories = cleanedSubunits.filter((s) => (s.type ?? "").toLowerCase() === "accessoryprotein");
             results.push({
                 complex: { ...complex, name: stripHtml(complex.name) },
@@ -143,7 +165,7 @@ export async function getAccessoryProteinNames(uniprotOrGeneSymbol) {
 }
 // getFamilySiblingUniprots iterates `targetIds` without a guard, so it stays
 // required; the other fields are not read, so they may be absent.
-const IupharFamilySchema = z.object({
+export const IupharFamilySchema = z.object({
     familyId: z.number().optional(),
     name: z.string().optional(),
     targetIds: z.array(z.number()),
@@ -158,9 +180,15 @@ export async function getFamily(familyId) {
             return null;
         throw new Error(describeApiError(res.error));
     }
+    // GtoPdb answers an unknown family with HTTP 200 and the sentinel record
+    // `{familyId: -1, targetIds: []}`, never with a 404. Thus the sentinel is
+    // the one signal that the family does not exist, and the `notFound` branch
+    // above cannot report it.
+    if (res.value.familyId === -1)
+        return null;
     return res.value;
 }
-const IupharDatabaseLinkSchema = z.object({
+export const IupharDatabaseLinkSchema = z.object({
     accession: z.string().optional(),
     database: z.string().optional(),
     species: z.string().optional(),
@@ -193,7 +221,8 @@ export async function getTargetHumanUniprots(targetId) {
  * CALCRL accession; the AMY1/2/3 complexes are excluded because they are
  * heterodimers, not separate primary proteins.
  */
-export async function getFamilySiblingUniprots(uniprotOrGeneSymbol) {
+export async function getFamilySiblingUniprots(uniprotOrGeneSymbol, logger) {
+    const log = (logger ?? createNoopLogger()).named("iuphar-client.family-siblings").with({ query: uniprotOrGeneSymbol });
     const self = await resolveTarget(uniprotOrGeneSymbol);
     if (!self)
         return [];
@@ -221,8 +250,15 @@ export async function getFamilySiblingUniprots(uniprotOrGeneSymbol) {
         const uniprotLists = await Promise.all(batch.map(async (tid) => {
             const url = `${IUPHAR_BASE}/targets/${tid}`;
             const res = await apiFetchValidated(url, IupharTargetSchema, { headers: HEADERS });
-            if (res.isErr())
+            if (res.isErr()) {
+                // A sibling that GtoPdb does not serve is a normal miss, and the
+                // loop drops it. But a contract break drops every sibling in the
+                // same way, thus an unexpected cause reaches the Logger first.
+                if (isUnexpectedApiError(res.error)) {
+                    log.error("sibling target dropped from the result", { targetId: tid, cause: describeApiError(res.error) });
+                }
                 return [];
+            }
             const t = res.value;
             if (t.subunitIds && t.subunitIds.length > 0)
                 return [];

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

@@ -11,6 +11,10 @@
  * rather than by matching prose.
  *
  * The API is keyless and public.
+ *
+ * Absence policy: the OpenAPI document of Monarch declares an absent value as
+ * `anyOf` with `null`, thus the API sends an explicit `null`. A maybe-absent
+ * field carries `.nullish()` exactly.
  */
 /** A curated human phenotype attributed to variation in the gene. */
 export interface MonarchPhenotypeAssociation {

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

@@ -11,6 +11,10 @@
  * rather than by matching prose.
  *
  * The API is keyless and public.
+ *
+ * Absence policy: the OpenAPI document of Monarch declares an absent value as
+ * `anyOf` with `null`, thus the API sends an explicit `null`. A maybe-absent
+ * field carries `.nullish()` exactly.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";

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

@@ -3,7 +3,12 @@
  *
  * Used by §2.6.2 (FAERS summary) and §2.6.6 (class precedent — drugs-in-class
  * AEs).
+ *
+ * Absence policy: openFDA omits the key of an absent value, and the `openfda`
+ * object can arrive as `{}`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
+import { z } from "zod";
 export interface AdverseEventCount {
     reaction: string;
     count: number;
@@ -42,6 +47,35 @@ export declare function getFaersByDrug(drugName: string, options?: {
  * and §2.6.8 risk summary.
  */
 export declare function getFaersSeriousness(drugName: string): Promise<SeriousnessProfile | null>;
+export declare const OpenFdaLabelResponseSchema: z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        set_id: z.ZodOptional<z.ZodUnknown>;
+        openfda: z.ZodOptional<z.ZodObject<{
+            application_number: z.ZodOptional<z.ZodUnknown>;
+            brand_name: z.ZodOptional<z.ZodUnknown>;
+            generic_name: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+        effective_time: z.ZodOptional<z.ZodUnknown>;
+        boxed_warning: z.ZodOptional<z.ZodUnknown>;
+        warnings_and_cautions: z.ZodOptional<z.ZodUnknown>;
+        warnings: z.ZodOptional<z.ZodUnknown>;
+        spl_medguide: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        patient_medication_information: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodTransform<DrugLabelAction, {
+        set_id?: unknown;
+        openfda?: {
+            application_number?: unknown;
+            brand_name?: unknown;
+            generic_name?: unknown;
+        } | undefined;
+        effective_time?: unknown;
+        boxed_warning?: unknown;
+        warnings_and_cautions?: unknown;
+        warnings?: unknown;
+        spl_medguide?: string[] | undefined;
+        patient_medication_information?: string[] | undefined;
+    }>>>>;
+}, z.core.$strip>;
 /**
  * Fetch FDA Structured Product Label entries by drug name. The name matches
  * the generic name or the brand name, thus a caller that holds only a brand

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

@@ -3,6 +3,10 @@
  *
  * Used by §2.6.2 (FAERS summary) and §2.6.6 (class precedent — drugs-in-class
  * AEs).
+ *
+ * Absence policy: openFDA omits the key of an absent value, and the `openfda`
+ * object can arrive as `{}`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -22,7 +26,13 @@ const OpenFdaLabelMetaSchema = z.object({
     brand_name: z.unknown().optional(),
     generic_name: z.unknown().optional(),
 });
-/** A single openFDA structured-product-label record (raw wire shape). */
+/**
+ * A single openFDA structured-product-label record (raw wire shape).
+ *
+ * `spl_medguide` and `patient_medication_information` are the two label sections
+ * that carry the patient-facing safety documents. The field reference of the
+ * provider types both as an array of string.
+ */
 const OpenFdaLabelSchema = z.object({
     set_id: z.unknown().optional(),
     openfda: OpenFdaLabelMetaSchema.optional(),
@@ -30,9 +40,8 @@ const OpenFdaLabelSchema = z.object({
     boxed_warning: z.unknown().optional(),
     warnings_and_cautions: z.unknown().optional(),
     warnings: z.unknown().optional(),
-    rems_summary: z.unknown().optional(),
-    rems_indication: z.unknown().optional(),
-    medication_guide: z.unknown().optional(),
+    spl_medguide: z.array(z.string()).optional(),
+    patient_medication_information: z.array(z.string()).optional(),
 });
 /**
  * Escape a value for embedding inside a double-quoted openFDA (Lucene) phrase.
@@ -166,8 +175,12 @@ function buildLabelSourceUrl(label) {
 }
 function mapLabel(raw) {
     const openfda = raw?.openfda ?? {};
-    const remsTextCandidates = [raw?.rems_summary, raw?.rems_indication, raw?.medication_guide];
-    const hasRems = remsTextCandidates.some((v) => joinSection(v) !== null) || (joinSection(raw?.boxed_warning)?.toLowerCase().includes("rems") ?? false);
+    // The label reference carries no REMS field, thus the signal is the word
+    // itself in one of the three sections that a REMS program writes to. The
+    // presence of a medication guide alone is not the signal: many labels with no
+    // REMS carry one, and a presence test would report a REMS that does not exist.
+    const remsTextCandidates = [raw?.boxed_warning, raw?.spl_medguide, raw?.patient_medication_information];
+    const hasRems = remsTextCandidates.some((v) => joinSection(v)?.toLowerCase().includes("rems") ?? false);
     return {
         applicationNumber: firstString(openfda.application_number),
         brandName: firstString(openfda.brand_name),
@@ -181,8 +194,9 @@ function mapLabel(raw) {
 }
 // The label endpoint's records are mapped to `DrugLabelAction` rows by
 // `mapLabel` — a context-free normalize folded into the schema so ONE schema
-// validates the raw wire AND emits the output rows.
-const OpenFdaLabelResponseSchema = z.object({
+// validates the raw wire AND emits the output rows. It is exported so that the
+// golden-fixture table drives it.
+export const OpenFdaLabelResponseSchema = z.object({
     results: z.array(OpenFdaLabelSchema.transform(mapLabel)).optional(),
 });
 /**

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

@@ -2,7 +2,12 @@
  * Pure async client functions for the Open Targets Platform GraphQL API.
  *
  * Used directly by target-assessment workflow steps and by tool wrappers.
+ *
+ * Absence policy: the nullability of the GraphQL SDL encodes an absent value.
+ * Open Targets answers each requested field with a key and an explicit `null`,
+ * thus the SDL gives each modifier and `.optional()` is wrong.
  */
+import { z } from "zod";
 export interface Association {
     diseaseId: string;
     diseaseName: string;
@@ -50,6 +55,13 @@ export interface BaselineExpressionEntry {
     tissueId: string;
     tissueLabel: string;
     organSystem: string | null;
+    /**
+     * The Open Targets datasource of the row, for example `gtex`,
+     * `tabula_sapiens` or `DICE`. One target carries rows of more than one
+     * datasource, and each datasource has its own unit and its own resolution.
+     * Thus a consumer that compares two entries must first compare this value.
+     */
+    datasourceId: string;
     rna: {
         value: number;
         unit: string;
@@ -58,6 +70,82 @@ export interface BaselineExpressionEntry {
         level: number | null;
     } | null;
 }
+export declare const TargetAssociationsDataSchema: z.ZodObject<{
+    target: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        approvedSymbol: z.ZodString;
+        approvedName: z.ZodString;
+        tractability: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            modality: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>;
+    associations: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        associatedDiseases: z.ZodOptional<z.ZodObject<{
+            rows: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                disease: z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                }, z.core.$strip>;
+                score: z.ZodNumber;
+                datatypeScores: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                    id: z.ZodOptional<z.ZodString>;
+                    score: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>>;
+            }, z.core.$strip>>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const TargetSafetyDataSchema: z.ZodObject<{
+    target: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        approvedSymbol: z.ZodString;
+        safetyLiabilities: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            event: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            biosamples: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                tissueLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>>;
+            effects: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                direction: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>>;
+            datasource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * `Target.baselineExpression`, per the SDL.
+ *
+ * The modifiers come from the SDL and from nothing else: `BaselineExpression!`
+ * and its `count`, `rows`, `unit`, `datasourceId` and `targetId` are non-null,
+ * the five quantile fields are `Float` and thus nullable, and each biosample
+ * link is a nullable `Biosample`.
+ */
+export declare const TargetExpressionDataSchema: z.ZodObject<{
+    target: z.ZodNullable<z.ZodObject<{
+        baselineExpression: z.ZodObject<{
+            count: z.ZodNumber;
+            rows: z.ZodArray<z.ZodObject<{
+                unit: z.ZodString;
+                median: z.ZodNullable<z.ZodNumber>;
+                q1: z.ZodNullable<z.ZodNumber>;
+                q3: z.ZodNullable<z.ZodNumber>;
+                min: z.ZodNullable<z.ZodNumber>;
+                max: z.ZodNullable<z.ZodNumber>;
+                datasourceId: z.ZodString;
+                targetId: z.ZodString;
+                tissueBiosample: z.ZodNullable<z.ZodObject<{
+                    biosampleId: z.ZodString;
+                    biosampleName: z.ZodString;
+                }, z.core.$strip>>;
+                tissueBiosampleParent: z.ZodNullable<z.ZodObject<{
+                    biosampleId: z.ZodString;
+                    biosampleName: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /** Fetch target info, tractability, and disease associations for an Ensembl gene id. */
 export declare function searchTargetAssociations(ensemblId: string, limit?: number): Promise<TargetInfo | null>;
 /** Fetch target associations for a disease (EFO id). */
@@ -77,8 +165,15 @@ export declare function getTargetSafetyLiabilities(ensemblId: string): Promise<{
     safetyLiabilities: SafetyLiability[];
 } | null>;
 /**
- * Fetch baseline RNA/protein expression across tissues. Open Targets
- * exposes per-tissue expression with organ system tags — used by §2.7
- * (Off-Tissue Risk) and §3.9 (Normal Tissue Expression).
+ * Map one `baselineExpression` page onto the baseline-expression entries.
+ *
+ * The function is pure, thus the golden-fixture table exercises it against a
+ * stored payload.
+ */
+export declare function mapBaselineExpression(data: z.infer<typeof TargetExpressionDataSchema>): BaselineExpressionEntry[];
+/**
+ * Fetch baseline RNA expression across tissues. Open Targets gives one row for
+ * each tissue and datasource, with the parent biosample as the organ system —
+ * used by §2.7 (Off-Tissue Risk) and §3.9 (Normal Tissue Expression).
  */
-export declare function getBaselineExpression(ensemblId: string): Promise<BaselineExpressionEntry[]>;
+export declare function getBaselineExpression(ensemblId: string, limit?: number): Promise<BaselineExpressionEntry[]>;

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

@@ -2,6 +2,10 @@
  * Pure async client functions for the Open Targets Platform GraphQL API.
  *
  * Used directly by target-assessment workflow steps and by tool wrappers.
+ *
+ * Absence policy: the nullability of the GraphQL SDL encodes an absent value.
+ * Open Targets answers each requested field with a key and an explicit `null`,
+ * thus the SDL gives each modifier and `.optional()` is wrong.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -79,22 +83,36 @@ const SAFETY_QUERY = `
   }
 `;
 const EXPRESSION_QUERY = `
-  query TargetExpression($ensemblId: String!) {
+  query TargetBaselineExpression($ensemblId: String!, $size: Int!) {
     target(ensemblId: $ensemblId) {
       id
       approvedSymbol
-      expressions {
-        tissue {
-          id
-          label
-          organs
+      baselineExpression(page: { size: $size, index: 0 }) {
+        count
+        rows {
+          unit
+          median
+          q1
+          q3
+          min
+          max
+          datasourceId
+          targetId
+          tissueBiosample { biosampleId biosampleName }
+          tissueBiosampleParent { biosampleId biosampleName }
         }
-        rna { value unit }
-        protein { level }
       }
     }
   }
 `;
+/**
+ * The page size of one `baselineExpression` request.
+ *
+ * `Pagination.size` caps at 3000 in the SDL, and one target carries more than
+ * 1400 rows. Thus a smaller page drops tissues, and it gives no signal that it
+ * dropped them.
+ */
+const BASELINE_EXPRESSION_PAGE_SIZE = 3000;
 // Open Targets GraphQL `data` payload schemas, validated at the fetch boundary.
 // Fields the mapping code reads behind a guard (optional chaining, `?? default`,
 // `Array.isArray`) are `.nullable().optional()`; fields read directly — a missing
@@ -104,7 +122,7 @@ const EXPRESSION_QUERY = `
 // that resolves empty — an unknown/retired id yields `{"target": null}`, which a
 // bare `.optional()` rejects, turning a clean "not found" into a thrown error.
 const DatatypeScoreSchema = z.object({ id: z.string().optional(), score: z.number().optional() });
-const TargetAssociationsDataSchema = z.object({
+export const TargetAssociationsDataSchema = z.object({
     target: z
         .object({
         id: z.string(),
@@ -175,7 +193,7 @@ const DiseaseSearchDataSchema = z.object({
         .nullable()
         .optional(),
 });
-const TargetSafetyDataSchema = z.object({
+export const TargetSafetyDataSchema = z.object({
     target: z
         .object({
         id: z.string().optional(),
@@ -199,35 +217,57 @@ const TargetSafetyDataSchema = z.object({
         .nullable()
         .optional(),
 });
-const TargetExpressionDataSchema = z.object({
+/** `Biosample`, as `BaselineExpressionRow` embeds it. Both leaf fields are non-null in the SDL. */
+const BiosampleSchema = z.object({ biosampleId: z.string(), biosampleName: z.string() });
+/**
+ * `Target.baselineExpression`, per the SDL.
+ *
+ * The modifiers come from the SDL and from nothing else: `BaselineExpression!`
+ * and its `count`, `rows`, `unit`, `datasourceId` and `targetId` are non-null,
+ * the five quantile fields are `Float` and thus nullable, and each biosample
+ * link is a nullable `Biosample`.
+ */
+export const TargetExpressionDataSchema = z.object({
     target: z
         .object({
-        expressions: z
-            .array(z.object({
-            tissue: z.object({ id: z.string(), label: z.string(), organs: z.array(z.string()).nullable().optional() }),
-            rna: z.object({ value: z.number().nullable().optional(), unit: z.string().nullable().optional() }).nullable().optional(),
-            protein: z.object({ level: z.number().nullable().optional() }).nullable().optional(),
-        }))
-            .nullable()
-            .optional(),
+        baselineExpression: z.object({
+            count: z.number(),
+            rows: z.array(z.object({
+                unit: z.string(),
+                median: z.number().nullable(),
+                q1: z.number().nullable(),
+                q3: z.number().nullable(),
+                min: z.number().nullable(),
+                max: z.number().nullable(),
+                datasourceId: z.string(),
+                targetId: z.string(),
+                tissueBiosample: BiosampleSchema.nullable(),
+                tissueBiosampleParent: BiosampleSchema.nullable(),
+            })),
+        }),
     })
-        .nullable()
-        .optional(),
+        .nullable(),
 });
 function extractDatatype(datatypeScores, id) {
     const match = datatypeScores.find((d) => d.id === id);
     return match?.score ?? null;
 }
 async function gqlFetch(query, variables, schema) {
-    const res = await apiFetchValidated(OT_GRAPHQL, z.object({ data: schema.optional() }), {
+    const res = await apiFetchValidated(OT_GRAPHQL, z.object({ data: schema.optional(), errors: z.array(z.object({ message: z.string().optional() })).optional() }), {
         method: "POST",
         headers: OT_HEADERS,
         body: JSON.stringify({ query, variables }),
     });
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    if (!res.value.data)
-        throw new Error("Open Targets returned no data");
+    if (!res.value.data) {
+        // A GraphQL server answers HTTP 200 with an `errors` array and no `data`
+        // key when the document itself is invalid, for example when it names a
+        // retired field. Without the first message the caller sees only "no
+        // data", which names no cause and points at no field.
+        const firstError = res.value.errors?.[0]?.message;
+        throw new Error(firstError ? `Open Targets returned no data: ${firstError}` : "Open Targets returned no data");
+    }
     return res.value.data;
 }
 /** Fetch target info, tractability, and disease associations for an Ensembl gene id. */
@@ -318,18 +358,38 @@ export async function getTargetSafetyLiabilities(ensemblId) {
     return { targetSymbol: target.approvedSymbol, safetyLiabilities };
 }
 /**
- * Fetch baseline RNA/protein expression across tissues. Open Targets
- * exposes per-tissue expression with organ system tags — used by §2.7
- * (Off-Tissue Risk) and §3.9 (Normal Tissue Expression).
+ * Map one `baselineExpression` page onto the baseline-expression entries.
+ *
+ * The function is pure, thus the golden-fixture table exercises it against a
+ * stored payload.
+ */
+export function mapBaselineExpression(data) {
+    const entries = [];
+    for (const row of data.target?.baselineExpression.rows ?? []) {
+        // A row with no tissue biosample measures a cell type alone, thus it
+        // carries no tissue identity and it cannot become a tissue entry.
+        const tissue = row.tissueBiosample;
+        if (!tissue)
+            continue;
+        entries.push({
+            tissueId: tissue.biosampleId,
+            tissueLabel: tissue.biosampleName,
+            organSystem: row.tissueBiosampleParent?.biosampleName ?? null,
+            datasourceId: row.datasourceId,
+            rna: row.median === null ? null : { value: row.median, unit: row.unit },
+            // The `baselineExpression` surface carries no protein measurement,
+            // thus the protein level of an entry is always absent.
+            protein: null,
+        });
+    }
+    return entries;
+}
+/**
+ * Fetch baseline RNA expression across tissues. Open Targets gives one row for
+ * each tissue and datasource, with the parent biosample as the organ system —
+ * used by §2.7 (Off-Tissue Risk) and §3.9 (Normal Tissue Expression).
  */
-export async function getBaselineExpression(ensemblId) {
-    const data = await gqlFetch(EXPRESSION_QUERY, { ensemblId }, TargetExpressionDataSchema);
-    const expressions = data.target?.expressions ?? [];
-    return expressions.map((e) => ({
-        tissueId: e.tissue.id,
-        tissueLabel: e.tissue.label,
-        organSystem: Array.isArray(e.tissue.organs) && e.tissue.organs.length > 0 ? e.tissue.organs[0] : null,
-        rna: e.rna && typeof e.rna.value === "number" ? { value: e.rna.value, unit: e.rna.unit ?? "TPM" } : null,
-        protein: e.protein ? { level: typeof e.protein.level === "number" ? e.protein.level : null } : null,
-    }));
+export async function getBaselineExpression(ensemblId, limit = BASELINE_EXPRESSION_PAGE_SIZE) {
+    const data = await gqlFetch(EXPRESSION_QUERY, { ensemblId, size: limit }, TargetExpressionDataSchema);
+    return mapBaselineExpression(data);
 }

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

@@ -2,7 +2,12 @@
  * Pure async client functions for biological pathway lookups via KEGG and Reactome.
  *
  * Used by §3.7 (Pathway Context).
+ *
+ * Absence policy: Reactome omits the key of an absent value, thus a maybe-absent
+ * field carries `.optional()`. KEGG serves plain text, not JSON, thus it has no
+ * key to omit.
  */
+import { z } from "zod";
 export declare function stripHtmlAndCollapseWs(s: string): string;
 export type PathwaySource = "kegg" | "reactome";
 export interface Pathway {
@@ -14,6 +19,25 @@ export interface Pathway {
     entity_uniprots?: string[];
     url?: string;
 }
+export declare const ReactomeSearchResponseSchema: z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        entries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            stId: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Participant list — `searchReactome` reads `displayName` per participant. */
+export declare const ReactomeParticipantsSchema: z.ZodArray<z.ZodObject<{
+    displayName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/** Participant list — `getPathwayMemberships` reads `refEntities` per participant. */
+export declare const ReactomeParticipantEntitiesSchema: z.ZodArray<z.ZodObject<{
+    refEntities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        schemaClass: z.ZodOptional<z.ZodString>;
+        identifier: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>>;
 export interface PathwaySearchOptions {
     source?: "kegg" | "reactome" | "both";
     organism?: string;
@@ -21,6 +45,27 @@ export interface PathwaySearchOptions {
     maxResults?: number;
 }
 export declare function searchKegg(query: string, organism: string, maxResults: number, includeGenes: boolean): Promise<Pathway[]>;
+/**
+ * Read the KEGG gene identifier of a symbol, for example `hsa:7157` for `TP53`.
+ *
+ * `find/{organism}/{symbol}` searches the gene names of one organism, and it
+ * ranks a partial name match above an exact one. A query for `TP53` puts
+ * `TP53BP2` first. Thus the caller matches the symbol against the alias list of
+ * each row, and it never takes the first row.
+ */
+export declare function selectKeggGeneId(rows: string[][], symbol: string): string | null;
+/** The pathway identifiers of a `link/pathway/{geneId}` answer, without the `path:` prefix. */
+export declare function parseKeggPathwayLinks(rows: string[][]): string[];
+/**
+ * The pathways that hold one gene, from KEGG.
+ *
+ * `find/pathway/{query}` matches a pathway NAME only, thus a gene symbol gives
+ * an empty body there. The membership path is a gene resolution, then
+ * `link/pathway/{geneId}`, then one `list/pathway/{organism}` call for the
+ * names. The one list call costs about 22 kB and names every pathway of the
+ * organism, thus it replaces one `get/{id}` call for each membership.
+ */
+export declare function keggPathwaysForGene(geneSymbol: string, organism: string, maxResults: number): Promise<Pathway[]>;
 export declare function searchReactome(query: string, species: string, maxResults: number, includeGenes: boolean): Promise<Pathway[]>;
 export declare function searchPathways(query: string, options?: PathwaySearchOptions): Promise<Pathway[]>;
 /**