@inflexa-ai/harness 0.30.2 → 0.31.0

package/dist/tools/lib/ctx-ops.js

@@ -7,19 +7,53 @@
  * point they share: a DTXSID is used directly, anything else is resolved by
  * exact match against the chemical-search endpoint. `null` means the query
  * resolved to no chemical — an expected outcome, not an error.
+ *
+ * UNVERIFIED CONTRACT, 2026-08-28. Every data path of the CTX API demands
+ * `EPA_CCTE_API_KEY`, and no key exists, thus no schema here parsed a live
+ * answer. The contract comes from three secondary sources: the server source of
+ * the EPA (`github.com/USEPA/ccte-api-{chemical,hazard,exposure,bioactivity}`,
+ * branch `dev`), the contract tests of the EPA (`USEPA/ccte-api-karate`), and
+ * the response bodies that the R client of the EPA (`ctxR` 1.1.3) recorded
+ * against this same base. A Java `List<T>` return type serializes to a JSON
+ * array, thus the server source settles each container shape.
+ *
+ * Absence policy: the CTX API sends an explicit `null` for an absent value, and
+ * it omits a key that its projection excludes. Thus a field carries both
+ * `.nullable()` and `.optional()`.
  */
 import { z } from "zod";
-import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { apiFetchValidated, describeApiError, zWireNumber } from "./api-utils.js";
 import { EPA_CCTE_BASE } from "./toxcast-config.js";
-// The chemical-search endpoint returns rows the code reads `dtxsid` from
-// unguarded, so `dtxsid` stays required — a row missing it is a contract break
-// surfaced as `invalid_response`, not a silent `undefined`. The other fields
-// are optional: the API omits absent values.
-const CtxChemicalSearchRowSchema = z.object({
-    dtxsid: z.string(),
+// A row of the chemical-search endpoint. `dtxsid` is nullable, because a search
+// that matches a DTXCID or a Markush record answers with a row that carries no
+// substance identifier. The caller drops such a row.
+export const CtxChemicalSearchRowSchema = z.object({
+    dtxsid: z.string().nullable().optional(),
     preferredName: z.string().nullable().optional(),
     casrn: z.string().nullable().optional(),
 });
+/**
+ * Is the error the RFC 7807 answer of a search that matched nothing?
+ *
+ * The chemical-search endpoint never answers with an empty array. It answers
+ * HTTP 400 with a `ProblemDetail` body that carries `title`, `detail`, and a
+ * `suggestions` list. Thus that one 400 is the no-match outcome, and every other
+ * 4xx stays a failure.
+ */
+function isNoMatchProblemDetail(error) {
+    if (error.type !== "http_status" || error.status !== 400)
+        return false;
+    try {
+        const body = JSON.parse(error.body);
+        // `suggestions` separates the no-match answer from a generic 400
+        // `ProblemDetail`, which carries `title` and `detail` alone. Without it,
+        // a malformed request reads as a clean no-match.
+        return typeof body === "object" && body !== null && "detail" in body && "title" in body && "suggestions" in body;
+    }
+    catch {
+        return false;
+    }
+}
 /** Resolve a DTXSID / CASRN / name to a chemical. `null` = no match (valid no-data). */
 export async function resolveDtxsid(query, headers) {
     if (query.startsWith("DTXSID")) {
@@ -27,11 +61,14 @@ export async function resolveDtxsid(query, headers) {
     }
     const url = `${EPA_CCTE_BASE}/chemical/search/equal/${encodeURIComponent(query)}`;
     const res = await apiFetchValidated(url, z.array(CtxChemicalSearchRowSchema), { headers });
-    if (res.isErr())
+    if (res.isErr()) {
+        if (isNoMatchProblemDetail(res.error))
+            return null;
         throw new Error(describeApiError(res.error));
-    if (!res.value?.length)
+    }
+    const chem = (res.value ?? []).find((row) => row.dtxsid);
+    if (!chem?.dtxsid)
         return null;
-    const chem = res.value[0];
     return {
         dtxsid: chem.dtxsid,
         preferredName: chem.preferredName ?? query,
@@ -47,7 +84,7 @@ const ToxcastMc5ParamSchema = z.object({
 const ToxcastMc6ParamSchema = z.object({
     flag: z.unknown().optional(),
 });
-const ToxcastBioactivityRowSchema = z.object({
+export const ToxcastBioactivityRowSchema = z.object({
     aeid: z.number().optional(),
     hitc: z.number().optional(),
     maxMean: z.number().nullable().optional(),
@@ -55,27 +92,40 @@ const ToxcastBioactivityRowSchema = z.object({
     mc5Param: ToxcastMc5ParamSchema.nullable().optional(),
     mc6Param: ToxcastMc6ParamSchema.nullable().optional(),
 });
-const ToxcastAssaySummaryRowSchema = z.object({
+/** One assay annotation of `bioactivity/assay/search/by-aeid/`. */
+const ToxcastAssayAnnotationSchema = z.object({
     aeid: z.number().optional(),
-    aenm: z.string().optional(),
+    assayComponentEndpointName: z.string().nullable().optional(),
 });
+/**
+ * The `hitc` of invitrodb v4 is a continuous value from 0 to 1, not a flag. The
+ * EPA calls a value of 0.9 or more active, thus the threshold is the predicate
+ * and an equality against 1 counts almost nothing.
+ */
+const ACTIVE_HIT_CALL = 0.9;
+function isActive(row) {
+    return (row.hitc ?? 0) >= ACTIVE_HIT_CALL;
+}
 /**
  * ToxCast/Tox21 assay results for a chemical, sorted by AC50 ascending.
  * `totalAssays` / `activeAssays` / `activeHitRate` always describe the full
  * tested panel, never the returned slice.
  */
 export async function fetchToxcastBioactivity(dtxsid, headers, opts) {
-    const aeidMap = await fetchAssayNames(dtxsid, headers);
     const bioUrl = `${EPA_CCTE_BASE}/bioactivity/data/search/by-dtxsid/${dtxsid}`;
     const bioRes = await apiFetchValidated(bioUrl, z.array(ToxcastBioactivityRowSchema), { headers });
     if (bioRes.isErr())
         throw new Error(describeApiError(bioRes.error));
     const allResults = bioRes.value ?? [];
     const totalAssays = allResults.length;
-    const activeAssays = allResults.filter((r) => r.hitc === 1).length;
-    const filtered = opts.activeOnly ? allResults.filter((r) => r.hitc === 1) : allResults;
+    const activeAssays = allResults.filter(isActive).length;
+    const filtered = opts.activeOnly ? allResults.filter(isActive) : allResults;
     filtered.sort((a, b) => extractAc50(a) - extractAc50(b));
-    const results = filtered.slice(0, opts.limit).map((r) => {
+    const page = filtered.slice(0, opts.limit);
+    // The names come after the slice, thus one batch call covers the rows that
+    // the caller sees and never the whole tested panel.
+    const aeidMap = await fetchAssayNames(page, headers);
+    const results = page.map((r) => {
         const aeid = r.aeid ?? 0;
         const mc6 = r.mc6Param ?? {};
         const flags = Array.isArray(mc6.flag) ? mc6.flag : [];
@@ -109,14 +159,31 @@ function extractAc50Raw(r) {
     }
     return null;
 }
-async function fetchAssayNames(dtxsid, headers) {
+/**
+ * The endpoint name of each assay of a result page, keyed by its aeid.
+ *
+ * The per-chemical summary endpoint serves a `ChemicalAgg` roll-up, which
+ * carries no assay identifier and no assay name. The names live on the assay
+ * resource, and its batch route takes the whole aeid list in one POST body.
+ * Thus a page of results costs one request, not one for each row.
+ *
+ * A failure gives an empty map, and the caller then labels a row `aeid:N`.
+ */
+async function fetchAssayNames(rows, headers) {
     const map = new Map();
-    const url = `${EPA_CCTE_BASE}/bioactivity/data/summary/search/by-dtxsid/${dtxsid}`;
-    const res = await apiFetchValidated(url, z.array(ToxcastAssaySummaryRowSchema), { headers });
+    const aeids = [...new Set(rows.map((r) => r.aeid).filter((aeid) => aeid != null))];
+    if (aeids.length === 0)
+        return map;
+    const url = `${EPA_CCTE_BASE}/bioactivity/assay/search/by-aeid/`;
+    const res = await apiFetchValidated(url, z.array(ToxcastAssayAnnotationSchema), {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(aeids.map((aeid) => String(aeid))),
+    });
     if (res.isOk() && Array.isArray(res.value)) {
-        for (const s of res.value) {
-            if (s.aeid != null && s.aenm) {
-                map.set(s.aeid, s.aenm);
+        for (const assay of res.value) {
+            if (assay.aeid != null && assay.assayComponentEndpointName) {
+                map.set(assay.aeid, assay.assayComponentEndpointName);
             }
         }
     }
@@ -126,13 +193,12 @@ async function fetchAssayNames(dtxsid, headers) {
 // Each schema below both validates one raw CTX hazard row and normalizes it
 // into the curated output shape via `.transform`; `z.infer` is that output
 // type. Every wire field is optional (the API omits absent values); the two
-// numeric fields the API sends as string-or-number stay `z.unknown()` so
-// `toNumberOrNull` can coerce them without the schema rejecting the row.
-const ToxValSchema = z
+// numeric fields the API sends as string-or-number ride `zWireNumber`.
+export const ToxValSchema = z
     .object({
     source: z.string().nullable().optional(),
     toxvalType: z.string().nullable().optional(),
-    toxvalNumeric: z.unknown().optional(),
+    toxvalNumeric: zWireNumber.nullable().optional(),
     toxvalUnits: z.string().nullable().optional(),
     studyType: z.string().nullable().optional(),
     studyDurationClass: z.string().nullable().optional(),
@@ -141,13 +207,13 @@ const ToxValSchema = z
     toxicologicalEffect: z.string().nullable().optional(),
     riskAssessmentClass: z.string().nullable().optional(),
     humanEco: z.string().nullable().optional(),
-    year: z.unknown().optional(),
+    year: zWireNumber.nullable().optional(),
     quality: z.string().nullable().optional(),
 })
     .transform((r) => ({
     source: r.source ?? "",
     toxvalType: r.toxvalType ?? "",
-    toxvalNumeric: toNumberOrNull(r.toxvalNumeric),
+    toxvalNumeric: r.toxvalNumeric ?? null,
     toxvalUnits: r.toxvalUnits ?? "",
     studyType: r.studyType ?? "",
     studyDurationClass: r.studyDurationClass ?? "",
@@ -156,38 +222,46 @@ const ToxValSchema = z
     toxicologicalEffect: r.toxicologicalEffect ?? "",
     riskAssessmentClass: r.riskAssessmentClass ?? "",
     humanEco: r.humanEco ?? "",
-    year: toNumberOrNull(r.year),
+    year: r.year ?? null,
     quality: r.quality ?? "",
 }));
-const GenetoxSchema = z
+// The genotoxicity SUMMARY record. It is a roll-up over the genotoxicity
+// reports of a chemical: the two headline assay calls, the overall call, and
+// the report counts behind them. The per-report fields (the assay category, the
+// metabolic activation, the species) belong to the `genetox/details` endpoint,
+// which this client does not call.
+export const GenetoxSchema = z
     .object({
-    source: z.string().nullable().optional(),
-    assayCategory: z.string().nullable().optional(),
-    assayType: z.string().nullable().optional(),
-    metabolicActivation: z.string().nullable().optional(),
-    species: z.string().nullable().optional(),
-    overallResult: z.string().nullable().optional(),
-    year: z.unknown().optional(),
+    ames: z.string().nullable().optional(),
+    genetoxCall: z.string().nullable().optional(),
+    micronucleus: z.string().nullable().optional(),
+    reportsPositive: z.number().nullable().optional(),
+    reportsNegative: z.number().nullable().optional(),
+    reportsOther: z.number().nullable().optional(),
+    clowderDocId: z.string().nullable().optional(),
 })
     .transform((r) => ({
-    source: r.source ?? "",
-    assayCategory: r.assayCategory ?? "",
-    assayType: r.assayType ?? "",
-    metabolicActivation: r.metabolicActivation ?? "",
-    species: r.species ?? "",
-    overallResult: r.overallResult ?? "",
-    year: toNumberOrNull(r.year),
+    ames: r.ames ?? "",
+    genetoxCall: r.genetoxCall ?? "",
+    micronucleus: r.micronucleus ?? "",
+    reportsPositive: r.reportsPositive ?? null,
+    reportsNegative: r.reportsNegative ?? null,
+    reportsOther: r.reportsOther ?? null,
+    clowderDocId: r.clowderDocId ?? "",
 }));
-const CancerSchema = z
+// The cancer SUMMARY record. `cancerCall` is the weight-of-evidence annotation,
+// and `exposureRoute` is the route that the annotation applies to.
+export const CancerSchema = z
     .object({
     source: z.string().nullable().optional(),
-    classification: z.string().nullable().optional(),
-    cancerClassification: z.string().nullable().optional(),
+    exposureRoute: z.string().nullable().optional(),
+    cancerCall: z.string().nullable().optional(),
     url: z.string().nullable().optional(),
 })
     .transform((r) => ({
     source: r.source ?? "",
-    classification: r.classification ?? r.cancerClassification ?? "",
+    exposureRoute: r.exposureRoute ?? "",
+    cancerCall: r.cancerCall ?? "",
     url: r.url ?? "",
 }));
 /**
@@ -223,12 +297,6 @@ async function fetchToxval(dtxsid, headers, limit) {
         return [];
     return res.value.slice(0, limit);
 }
-function toNumberOrNull(v) {
-    if (v == null || v === "")
-        return null;
-    const n = typeof v === "number" ? v : Number(v);
-    return Number.isFinite(n) ? n : null;
-}
 async function fetchGenetox(dtxsid, headers, limit) {
     const url = `${EPA_CCTE_BASE}/hazard/genetox/summary/search/by-dtxsid/${dtxsid}`;
     const res = await apiFetchValidated(url, z.array(GenetoxSchema), { headers });
@@ -246,7 +314,7 @@ async function fetchCancer(dtxsid, headers) {
 // Raw CTX chemical-detail wire shape, validated at the fetch boundary. Every
 // field is optional (the API omits absent values); the mapper below normalizes
 // it into `ChemicalDetail`, folding in the resolved `dtxsid` fallback.
-const RawChemicalDetailSchema = z.object({
+export const RawChemicalDetailSchema = z.object({
     dtxsid: z.string().optional(),
     dtxcid: z.string().nullable().optional(),
     casrn: z.string().nullable().optional(),
@@ -256,7 +324,6 @@ const RawChemicalDetailSchema = z.object({
     smiles: z.string().nullable().optional(),
     inchikey: z.string().nullable().optional(),
     monoisotopicMass: z.number().nullable().optional(),
-    averageMass: z.number().nullable().optional(),
     qcLevel: z.number().nullable().optional(),
     totalAssays: z.number().nullable().optional(),
     activeAssays: z.number().nullable().optional(),
@@ -294,7 +361,6 @@ export async function fetchCtxChemicalDetail(dtxsid, headers) {
         smiles: d.smiles ?? "",
         inchikey: d.inchikey ?? "",
         monoisotopicMass: d.monoisotopicMass ?? null,
-        averageMass: d.averageMass ?? null,
         qcLevel: d.qcLevel ?? null,
         totalAssays: d.totalAssays ?? null,
         activeAssays: d.activeAssays ?? null,
@@ -324,20 +390,20 @@ export async function fetchCtxChemicalProperties(dtxsid, headers) {
     }
     return undefined;
 }
-// SEEM exposure-prediction wire shape (endpoint returns a single object or an
-// array). `probabilityPesticde` is the API's own misspelling, read as a
-// fallback before the corrected `probabilityPesticide`, so both stay modeled.
-const RawSeemPredictionSchema = z.object({
+// SEEM exposure-prediction wire shape. The endpoint answers with an array.
+// `probabilityPesticde` is the wire name, and it is the own misspelling of the
+// API. The corrected spelling is served nowhere, thus only the wire name is
+// modeled and the mapped output carries the corrected one.
+export const RawSeemPredictionSchema = z.object({
     dtxsid: z.string().optional(),
     productionVolume: z.number().nullable().optional(),
     units: z.string().nullable().optional(),
     probabilityDietary: z.number().nullable().optional(),
     probabilityResidential: z.number().nullable().optional(),
     probabilityPesticde: z.number().nullable().optional(),
-    probabilityPesticide: z.number().nullable().optional(),
     probabilityIndustrial: z.number().nullable().optional(),
 });
-const RawHttkRowSchema = z.object({
+export const RawHttkRowSchema = z.object({
     parameter: z.string().nullable().optional(),
     measured: z.number().nullable().optional(),
     predicted: z.number().nullable().optional(),
@@ -346,7 +412,7 @@ const RawHttkRowSchema = z.object({
     species: z.string().nullable().optional(),
     reference: z.string().nullable().optional(),
 });
-const RawFunctionalUseRowSchema = z.object({
+export const RawFunctionalUseRowSchema = z.object({
     functioncategory: z.string().nullable().optional(),
     reportedfunction: z.string().nullable().optional(),
     doctitle: z.string().nullable().optional(),
@@ -392,10 +458,10 @@ export async function fetchCtxExposureData(dtxsid, headers, opts) {
 }
 async function fetchSeem(dtxsid, headers) {
     const url = `${EPA_CCTE_BASE}/exposure/seem/general/search/by-dtxsid/${dtxsid}`;
-    const res = await apiFetchValidated(url, z.union([RawSeemPredictionSchema, z.array(RawSeemPredictionSchema)]), { headers });
-    if (res.isErr() || !res.value)
+    const res = await apiFetchValidated(url, z.array(RawSeemPredictionSchema), { headers });
+    if (res.isErr())
         return undefined;
-    const d = Array.isArray(res.value) ? res.value[0] : res.value;
+    const d = res.value[0];
     if (!d)
         return undefined;
     return {
@@ -404,7 +470,7 @@ async function fetchSeem(dtxsid, headers) {
         units: d.units ?? "",
         probabilityDietary: d.probabilityDietary ?? null,
         probabilityResidential: d.probabilityResidential ?? null,
-        probabilityPesticide: d.probabilityPesticde ?? d.probabilityPesticide ?? null,
+        probabilityPesticide: d.probabilityPesticde ?? null,
         probabilityIndustrial: d.probabilityIndustrial ?? null,
     };
 }

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

@@ -5,7 +5,12 @@
  * DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB,
  * GuideToPharmacology, CIViC, …) and reports per-interaction source counts,
  * which the caller uses as a confidence signal.
+ *
+ * Absence policy: the nullability of the GraphQL SDL encodes an absent value.
+ * DGIdb 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 DgidbInteraction {
     geneName: string;
     drugName: string;
@@ -31,6 +36,74 @@ export interface DgidbResult {
     /** Interactions this input had before `limit` trimmed them. */
     totalInteractions: number;
 }
+/** The response envelope. It is exported so that the golden-fixture table drives it. */
+export declare const DgidbResponseSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodObject<{
+        genes: z.ZodOptional<z.ZodObject<{
+            nodes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNullable<z.ZodObject<{
+                name: z.ZodNullable<z.ZodString>;
+                conceptId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                interactions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    interactionScore: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                    interactionTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                        directionality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    }, z.core.$strip>>>;
+                    drug: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        conceptId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    }, z.core.$strip>>>;
+                    gene: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    }, z.core.$strip>>>;
+                    interactionAttributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>>;
+                    publications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        pmid: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                    }, z.core.$strip>>>;
+                    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        sourceDbName: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>>>;
+        }, z.core.$strip>>;
+        drugs: z.ZodOptional<z.ZodObject<{
+            nodes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNullable<z.ZodObject<{
+                name: z.ZodNullable<z.ZodString>;
+                conceptId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                interactions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    interactionScore: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                    interactionTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                        directionality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    }, z.core.$strip>>>;
+                    drug: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        conceptId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    }, z.core.$strip>>>;
+                    gene: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    }, z.core.$strip>>>;
+                    interactionAttributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>>;
+                    publications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        pmid: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                    }, z.core.$strip>>>;
+                    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        sourceDbName: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 export interface DgidbFilters {
     interactionTypes?: string[];
     sourceDbs?: string[];

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

@@ -5,6 +5,10 @@
  * DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB,
  * GuideToPharmacology, CIViC, …) and reports per-interaction source counts,
  * which the caller uses as a confidence signal.
+ *
+ * Absence policy: the nullability of the GraphQL SDL encodes an absent value.
+ * DGIdb 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";
@@ -41,30 +45,31 @@ const DRUG_INTERACTIONS_QUERY = `query($drugs: [String!]!) {
   }
 }`;
 // Shape of the DGIdb GraphQL payload as it arrives on the wire. Validated at
-// the fetch boundary; `mapInteraction` normalizes each record. Most fields are
-// optional/nullable to match GraphQL's per-field nullability — but
-// `RawNode.name` is required because we key the node map on
-// `name.toLowerCase()`; a node missing it is a contract break we surface as an
-// `invalid_response` error rather than a runtime TypeError.
+// the fetch boundary; `mapInteraction` normalizes each record. GraphQL always
+// answers a requested field with a key, thus absence is an explicit `null` and
+// never an omission. As a result each modifier below comes from the SDL:
+// `Gene.name`, `InteractionClaimType.type` and `directionality` are nullable,
+// and `GeneConnection.nodes` is a nullable list of nullable elements.
 const RawInteractionSchema = z.object({
     interactionScore: z.number().nullable().optional(),
-    interactionTypes: z.array(z.object({ type: z.string().optional(), directionality: z.string().nullable().optional() })).optional(),
+    interactionTypes: z.array(z.object({ type: z.string().nullable().optional(), directionality: z.string().nullable().optional() })).optional(),
     drug: z.object({ name: z.string().optional(), conceptId: z.string().nullable().optional() }).nullable().optional(),
-    gene: z.object({ name: z.string().optional() }).nullable().optional(),
+    gene: z.object({ name: z.string().nullable().optional() }).nullable().optional(),
     interactionAttributes: z.array(z.object({ name: z.string().optional(), value: z.string().optional() })).optional(),
     publications: z.array(z.object({ pmid: z.union([z.string(), z.number()]).optional() })).optional(),
     sources: z.array(z.object({ sourceDbName: z.string().optional() })).optional(),
 });
 const RawNodeSchema = z.object({
-    name: z.string(),
+    name: z.string().nullable(),
     conceptId: z.string().nullable().optional(),
     interactions: z.array(RawInteractionSchema).optional(),
 });
-const DgidbResponseSchema = z.object({
+/** The response envelope. It is exported so that the golden-fixture table drives it. */
+export const DgidbResponseSchema = z.object({
     data: z
         .object({
-        genes: z.object({ nodes: z.array(RawNodeSchema).optional() }).optional(),
-        drugs: z.object({ nodes: z.array(RawNodeSchema).optional() }).optional(),
+        genes: z.object({ nodes: z.array(RawNodeSchema.nullable()).nullish() }).optional(),
+        drugs: z.object({ nodes: z.array(RawNodeSchema.nullable()).nullish() }).optional(),
     })
         .optional(),
     errors: z.array(z.object({ message: z.string().optional() })).optional(),
@@ -146,9 +151,16 @@ export async function searchDgidb(inputs, searchType, filters = {}, onPartialErr
     const nodes = (isGene ? body.data.genes?.nodes : body.data.drugs?.nodes) ?? [];
     const nodeMap = new Map();
     for (const node of nodes) {
-        nodeMap.set(node.name.toLowerCase(), node);
+        // The node list and `Gene.name` are nullable in the SDL. The map keys on
+        // the name, thus a null element and a null-named node have no key, and
+        // the input that asked for them reports `found: false`.
+        const name = node?.name;
+        if (!node || !name)
+            continue;
+        const named = { ...node, name };
+        nodeMap.set(name.toLowerCase(), named);
         if (!isGene && node.conceptId)
-            nodeMap.set(node.conceptId.toLowerCase(), node);
+            nodeMap.set(node.conceptId.toLowerCase(), named);
     }
     const limit = filters.limit ?? 20;
     return inputs.map((input) => {