@inflexa-ai/harness 0.30.2 → 0.31.0

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

@@ -2,14 +2,19 @@
  * 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";
 import { apiFetch, apiFetchValidated, parseTSV } from "./api-utils.js";
 const KEGG_BASE = "https://rest.kegg.jp";
-// The ContentService of the primary host answers 404 on each path. The release
-// host serves the same API, and a probe of `search/query`, `data/query/{stId}`
-// and `data/participants/{stId}` returned 200 on it. The web pages that a result
-// links to stay on the primary host, thus only the API base moves.
+// Both `reactome.org/ContentService` and `release.reactome.org/ContentService`
+// answer 200 on each path that this file calls. The two hosts serve different
+// data releases, thus the same stable identifier gives a different record on
+// each. The release host is the pinned one, and the web pages that a result
+// links to stay on the primary host.
 const REACTOME_BASE = "https://release.reactome.org/ContentService";
 export function stripHtmlAndCollapseWs(s) {
     // Strip tags to a fixpoint: a single pass can leave a `<…>` behind when
@@ -39,11 +44,11 @@ const ReactomeSearchEntrySchema = z.object({
     stId: z.string().optional(),
     name: z.string().optional(),
 });
-const ReactomeSearchResponseSchema = z.object({
+export const ReactomeSearchResponseSchema = z.object({
     results: z.array(z.object({ entries: z.array(ReactomeSearchEntrySchema).optional() })).optional(),
 });
 /** Participant list — `searchReactome` reads `displayName` per participant. */
-const ReactomeParticipantsSchema = z.array(z.object({ displayName: z.string().optional() }));
+export const ReactomeParticipantsSchema = z.array(z.object({ displayName: z.string().optional() }));
 /** One Reactome event record, as `/data/query/{stId}` serves it. */
 const ReactomeEntrySchema = z.object({
     stId: z.string().optional(),
@@ -51,7 +56,7 @@ const ReactomeEntrySchema = z.object({
     summation: z.array(z.object({ text: z.string().optional() })).optional(),
 });
 /** Participant list — `getPathwayMemberships` reads `refEntities` per participant. */
-const ReactomeParticipantEntitiesSchema = z.array(z.object({
+export const ReactomeParticipantEntitiesSchema = z.array(z.object({
     refEntities: z.array(z.object({ schemaClass: z.string().optional(), identifier: z.string().optional() })).optional(),
 }));
 export async function searchKegg(query, organism, maxResults, includeGenes) {
@@ -79,6 +84,81 @@ export async function searchKegg(query, organism, maxResults, includeGenes) {
     }
     return pathways;
 }
+/**
+ * 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 function selectKeggGeneId(rows, symbol) {
+    const wanted = symbol.trim().toUpperCase();
+    for (const cols of rows) {
+        const id = (cols[0] ?? "").trim();
+        // Column two is `ALIAS1, ALIAS2; definition`.
+        const aliases = (cols[1] ?? "").split(";")[0] ?? "";
+        for (const alias of aliases.split(",")) {
+            if (alias.trim().toUpperCase() === wanted)
+                return id;
+        }
+    }
+    return null;
+}
+/** The pathway identifiers of a `link/pathway/{geneId}` answer, without the `path:` prefix. */
+export function parseKeggPathwayLinks(rows) {
+    const ids = [];
+    for (const cols of rows) {
+        const id = (cols[1] ?? "").replace("path:", "").trim();
+        if (id)
+            ids.push(id);
+    }
+    return ids;
+}
+/**
+ * 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 async function keggPathwaysForGene(geneSymbol, organism, maxResults) {
+    const geneRes = await apiFetch(`${KEGG_BASE}/find/${organism}/${encodeURIComponent(geneSymbol)}`, { parseAs: "text" });
+    if (geneRes.isErr())
+        return [];
+    const geneId = selectKeggGeneId(parseTSV(geneRes.value), geneSymbol);
+    if (!geneId)
+        return [];
+    const linkRes = await apiFetch(`${KEGG_BASE}/link/pathway/${encodeURIComponent(geneId)}`, { parseAs: "text" });
+    if (linkRes.isErr())
+        return [];
+    const pathwayIds = parseKeggPathwayLinks(parseTSV(linkRes.value)).slice(0, maxResults);
+    if (pathwayIds.length === 0)
+        return [];
+    const names = await keggPathwayNames(organism);
+    return pathwayIds.map((id) => ({
+        id,
+        name: names.get(id) ?? id,
+        source: "kegg",
+        url: `https://www.kegg.jp/pathway/${id}`,
+    }));
+}
+/** The pathway vocabulary of one organism, keyed by the pathway identifier. */
+async function keggPathwayNames(organism) {
+    const names = new Map();
+    const res = await apiFetch(`${KEGG_BASE}/list/pathway/${encodeURIComponent(organism)}`, { parseAs: "text" });
+    if (res.isErr())
+        return names;
+    for (const cols of parseTSV(res.value)) {
+        const id = (cols[0] ?? "").trim();
+        const name = (cols[1] ?? "").trim();
+        if (id && name)
+            names.set(id, name);
+    }
+    return names;
+}
 export async function searchReactome(query, species, maxResults, includeGenes) {
     const params = new URLSearchParams({
         query,
@@ -195,7 +275,7 @@ export async function getPathwayById(id) {
 }
 /** Pathway memberships for a gene symbol — used directly by §3.7 collector. */
 export async function getPathwayMemberships(geneSymbol) {
-    const [kegg, reactome] = await Promise.all([searchKegg(geneSymbol, "hsa", 25, false), searchReactome(geneSymbol, "Homo sapiens", 25, false)]);
+    const [kegg, reactome] = await Promise.all([keggPathwaysForGene(geneSymbol, "hsa", 25), searchReactome(geneSymbol, "Homo sapiens", 25, false)]);
     // For Reactome pathways, fetch participant UniProts (bounded to avoid rate limits).
     await Promise.all(reactome.slice(0, 50).map(async (pw) => {
         try {

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

@@ -1,9 +1,43 @@
 /**
- * Pure async client functions for PharmGKB clinical annotations.
+ * Pure async client functions for the PharmGKB clinical annotations, which
+ * ClinPGx now serves.
  *
  * Public API, no key required. Matching is an exact field filter, not a search:
  * `location.genes.symbol` for a gene, `relatedChemicals.name` for a drug.
+ *
+ * Absence policy: the sampled ClinPGx payloads carry no explicit `null`, and a
+ * record omits the key of an absent value. Thus a maybe-absent field carries
+ * `.optional()`, not `.nullable()`.
  */
+import { z } from "zod";
+export declare const PharmgkbAnnotationSchema: z.ZodObject<{
+    location: z.ZodOptional<z.ZodObject<{
+        genes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            symbol: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    relatedChemicals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    levelOfEvidence: z.ZodOptional<z.ZodObject<{
+        term: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const PharmgkbResponseSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        location: z.ZodOptional<z.ZodObject<{
+            genes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                symbol: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        relatedChemicals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        levelOfEvidence: z.ZodOptional<z.ZodObject<{
+            term: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 /**
  * One PharmGKB clinical annotation.
  *

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

@@ -1,27 +1,43 @@
 /**
- * Pure async client functions for PharmGKB clinical annotations.
+ * Pure async client functions for the PharmGKB clinical annotations, which
+ * ClinPGx now serves.
  *
  * Public API, no key required. Matching is an exact field filter, not a search:
  * `location.genes.symbol` for a gene, `relatedChemicals.name` for a drug.
+ *
+ * Absence policy: the sampled ClinPGx payloads carry no explicit `null`, and a
+ * record omits the key of an absent value. Thus a maybe-absent field carries
+ * `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
 import { PHARMGKB_BASE, PHARMGKB_HEADERS } from "./pharmgkb-config.js";
-// Raw PharmGKB clinicalAnnotation wire shape, validated at the fetch boundary.
-// Every field is optional because the API omits absent values.
-const PharmgkbAnnotationSchema = z.object({
+// Raw ClinPGx clinicalAnnotation wire shape, validated at the fetch boundary.
+export const PharmgkbAnnotationSchema = z.object({
     location: z.object({ genes: z.array(z.object({ symbol: z.string().optional() })).optional() }).optional(),
     relatedChemicals: z.array(z.object({ name: z.string().optional() })).optional(),
     levelOfEvidence: z.object({ term: z.string().optional() }).optional(),
 });
-const PharmgkbResponseSchema = z.object({
+// `data` is polymorphic by status: an array of annotation records on HTTP 200,
+// and an error OBJECT (`{"errors":[…]}`) on a 4xx. The undeclared sibling key
+// `status` carries `"success"` or `"fail"`. This schema models the 200 arm only,
+// because the 4xx arm never reaches it — `apiFetch` reports a non-ok status as
+// `http_status` before the body is parsed.
+export const PharmgkbResponseSchema = z.object({
     data: z.array(PharmgkbAnnotationSchema).optional(),
 });
 export async function searchPharmgkb(query, searchType, limit = 20) {
     const filter = searchType === "gene" ? `location.genes.symbol=${encodeURIComponent(query)}` : `relatedChemicals.name=${encodeURIComponent(query)}`;
     const res = await apiFetchValidated(`${PHARMGKB_BASE}/clinicalAnnotation?${filter}`, PharmgkbResponseSchema, { headers: PHARMGKB_HEADERS });
-    if (res.isErr())
+    if (res.isErr()) {
+        // ClinPGx answers "no results matching criteria" with HTTP 404, not with
+        // an empty array. A gene or a drug that the corpus does not annotate is
+        // an expected miss, thus it gives an empty result. Every other failure
+        // still throws, because it is an outage or a contract break.
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return { annotations: [], totalFound: 0 };
         throw new Error(describeApiError(res.error));
+    }
     const data = res.value?.data ?? [];
     const annotations = data.slice(0, limit).map((ann) => ({
         gene: ann.location?.genes?.map((g) => g.symbol).join(", ") ?? query,

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

@@ -1,4 +1,11 @@
-export declare const PHARMGKB_BASE = "https://api.pharmgkb.org/v1/data";
+/**
+ * Shared constants for the PharmGKB clinical-annotation API.
+ *
+ * PharmGKB is now ClinPGx, and `api.pharmgkb.org` no longer resolves. The
+ * successor host serves the same paths, the same envelope, and the same field
+ * names, thus only the host changes here.
+ */
+export declare const PHARMGKB_BASE = "https://api.clinpgx.org/v1/data";
 export declare const PHARMGKB_HEADERS: {
     readonly Accept: "application/json";
 };

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

@@ -1,2 +1,9 @@
-export const PHARMGKB_BASE = "https://api.pharmgkb.org/v1/data";
+/**
+ * Shared constants for the PharmGKB clinical-annotation API.
+ *
+ * PharmGKB is now ClinPGx, and `api.pharmgkb.org` no longer resolves. The
+ * successor host serves the same paths, the same envelope, and the same field
+ * names, thus only the host changes here.
+ */
+export const PHARMGKB_BASE = "https://api.clinpgx.org/v1/data";
 export const PHARMGKB_HEADERS = { Accept: "application/json" };

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

@@ -7,7 +7,12 @@
  * exposes molecular weight + SMILES + InChI properties that let us
  * heuristically classify peptides, small molecules, and proteins without a
  * hand-curated override table.
+ *
+ * Absence policy: PubChem omits the key of an absent value, per `minOccurs=0`
+ * in its XSD, and it never sends an explicit `null`. Thus a maybe-absent field
+ * carries `.optional()`, not `.nullable()`.
  */
+import { z } from "zod";
 export interface PubChemCompoundProperties {
     cid: number;
     molecularWeight: number | null;
@@ -16,6 +21,23 @@ export interface PubChemCompoundProperties {
     hBondDonorCount: number | null;
     hBondAcceptorCount: number | null;
 }
+export declare const PubChemPropertyResponseSchema: z.ZodObject<{
+    PropertyTable: z.ZodOptional<z.ZodObject<{
+        Properties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            CID: z.ZodOptional<z.ZodNumber>;
+            MolecularWeight: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>;
+            InChIKey: z.ZodOptional<z.ZodString>;
+            ConnectivitySMILES: z.ZodOptional<z.ZodString>;
+            HBondDonorCount: z.ZodOptional<z.ZodNumber>;
+            HBondAcceptorCount: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const PubChemCidListResponseSchema: z.ZodObject<{
+    IdentifierList: z.ZodOptional<z.ZodObject<{
+        CID: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare function getCompoundPropertiesByCID(cid: number): Promise<PubChemCompoundProperties | null>;
 /**
  * Look up a PubChem compound by InChI key (the canonical hash of the 3-D

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

@@ -7,61 +7,63 @@
  * exposes molecular weight + SMILES + InChI properties that let us
  * heuristically classify peptides, small molecules, and proteins without a
  * hand-curated override table.
+ *
+ * Absence policy: PubChem omits the key of an absent value, per `minOccurs=0`
+ * in its XSD, 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";
+import { apiFetchValidated, describeApiError, zWireNumber } from "./api-utils.js";
 import { PUBCHEM_BASE, PUBCHEM_HEADERS } from "./pubchem-config.js";
 const PROPERTY_FIELDS = [
     "MolecularWeight",
     "InChIKey",
-    // The PUG-REST schema renamed the small-molecule SMILES field to
-    // ConnectivitySMILES in late 2024; CanonicalSMILES still works but is
-    // deprecated. We request both and fall back through them.
+    // PubChem retired the response key `CanonicalSMILES`, and it answers a request
+    // for that name with `ConnectivitySMILES`. Thus the request names the live key.
     "ConnectivitySMILES",
-    "CanonicalSMILES",
     "HBondDonorCount",
     "HBondAcceptorCount",
 ].join(",");
 // A single record from the PUG-REST `PropertyTable.Properties` array, validated
-// at the fetch boundary. Every field is optional — PubChem omits absent
-// properties, and a row missing `CID` is handled gracefully by the caller's
-// guard (returns null) rather than being a contract break.
+// at the fetch boundary. PubChem omits an absent property and it never sends
+// `null`, thus each property carries `.optional()` and a declared type. Under
+// zod 4 a bare `z.unknown()` is required, which rejects an omission.
 const RawPubChemPropertySchema = z.object({
     CID: z.number().optional(),
-    MolecularWeight: z.unknown(),
-    InChIKey: z.unknown(),
-    ConnectivitySMILES: z.unknown(),
-    CanonicalSMILES: z.unknown(),
-    HBondDonorCount: z.unknown(),
-    HBondAcceptorCount: z.unknown(),
+    // PUG-REST serializes MolecularWeight as a string (e.g. "180.16") to
+    // preserve significant figures, thus it reads through the wire-number helper.
+    MolecularWeight: zWireNumber.optional(),
+    InChIKey: z.string().optional(),
+    ConnectivitySMILES: z.string().optional(),
+    HBondDonorCount: z.number().optional(),
+    HBondAcceptorCount: z.number().optional(),
 });
-const PubChemPropertyResponseSchema = z.object({
+export const PubChemPropertyResponseSchema = z.object({
     PropertyTable: z.object({ Properties: z.array(RawPubChemPropertySchema).optional() }).optional(),
 });
-const PubChemCidListResponseSchema = z.object({
+export const PubChemCidListResponseSchema = z.object({
     IdentifierList: z.object({ CID: z.array(z.number()).optional() }).optional(),
 });
-function parseNumber(value) {
-    if (value == null)
-        return null;
-    if (typeof value === "number")
-        return Number.isFinite(value) ? value : null;
-    if (typeof value === "string") {
-        const n = parseFloat(value);
-        return Number.isFinite(n) ? n : null;
-    }
-    return null;
-}
 function mapProps(raw) {
     return {
         cid: raw.CID ?? 0,
-        molecularWeight: parseNumber(raw.MolecularWeight),
-        inchiKey: typeof raw.InChIKey === "string" ? raw.InChIKey : null,
-        canonicalSmiles: typeof raw.ConnectivitySMILES === "string" ? raw.ConnectivitySMILES : typeof raw.CanonicalSMILES === "string" ? raw.CanonicalSMILES : null,
-        hBondDonorCount: typeof raw.HBondDonorCount === "number" ? raw.HBondDonorCount : parseNumber(raw.HBondDonorCount),
-        hBondAcceptorCount: typeof raw.HBondAcceptorCount === "number" ? raw.HBondAcceptorCount : parseNumber(raw.HBondAcceptorCount),
+        molecularWeight: raw.MolecularWeight ?? null,
+        inchiKey: raw.InChIKey ?? null,
+        canonicalSmiles: raw.ConnectivitySMILES ?? null,
+        hBondDonorCount: raw.HBondDonorCount ?? null,
+        hBondAcceptorCount: raw.HBondAcceptorCount ?? null,
     };
 }
+/**
+ * Does the record hold a property?
+ *
+ * PubChem answers HTTP 200 for a CID that does not exist, with one row that
+ * carries the `CID` alone. Thus a record with no property is an absence, and a
+ * caller must not read it as a compound.
+ */
+function carriesProperties(props) {
+    return Object.entries(props).some(([key, value]) => key !== "cid" && value !== null);
+}
 export async function getCompoundPropertiesByCID(cid) {
     const url = `${PUBCHEM_BASE}/compound/cid/${cid}/property/${PROPERTY_FIELDS}/JSON`;
     const res = await apiFetchValidated(url, PubChemPropertyResponseSchema, {
@@ -75,7 +77,8 @@ export async function getCompoundPropertiesByCID(cid) {
     const props = res.value.PropertyTable?.Properties?.[0];
     if (!props || typeof props.CID !== "number")
         return null;
-    return mapProps(props);
+    const mapped = mapProps(props);
+    return carriesProperties(mapped) ? mapped : null;
 }
 /**
  * Look up a PubChem compound by InChI key (the canonical hash of the 3-D

package/dist/tools/lib/pubchem-ops.d.ts

@@ -4,14 +4,18 @@
  * One home for the wire schemas, the URL construction, and the "PubChem 404
  * means no data" contract, so a caller cannot drift from it: every function
  * returns an empty collection for a 404 and throws on any other API failure.
+ *
+ * Absence policy: PubChem omits the key of an absent value, per `minOccurs=0`
+ * in its XSD, and it never sends an explicit `null`. Thus a maybe-absent field
+ * carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
 export type PubChemSearchBy = "name" | "smiles" | "inchi" | "inchikey" | "cid";
 declare const PugPropertyRowSchema: z.ZodPipe<z.ZodObject<{
     CID: z.ZodOptional<z.ZodNumber>;
-    CanonicalSMILES: z.ZodOptional<z.ZodString>;
+    ConnectivitySMILES: z.ZodOptional<z.ZodString>;
     MolecularFormula: z.ZodOptional<z.ZodString>;
-    MolecularWeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    MolecularWeight: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>;
     IUPACName: z.ZodOptional<z.ZodString>;
     InChI: z.ZodOptional<z.ZodString>;
     InChIKey: z.ZodOptional<z.ZodString>;
@@ -37,9 +41,9 @@ declare const PugPropertyRowSchema: z.ZodPipe<z.ZodObject<{
     complexity: number | null;
 }, {
     CID?: number | undefined;
-    CanonicalSMILES?: string | undefined;
+    ConnectivitySMILES?: string | undefined;
     MolecularFormula?: string | undefined;
-    MolecularWeight?: string | number | undefined;
+    MolecularWeight?: number | null | undefined;
     IUPACName?: string | undefined;
     InChI?: string | undefined;
     InChIKey?: string | undefined;
@@ -51,10 +55,68 @@ declare const PugPropertyRowSchema: z.ZodPipe<z.ZodObject<{
     Complexity?: number | undefined;
 }>>;
 export type PubChemCompound = z.infer<typeof PugPropertyRowSchema>;
+export declare const PubChemPropertyResponseSchema: z.ZodObject<{
+    PropertyTable: z.ZodOptional<z.ZodObject<{
+        Properties: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+            CID: z.ZodOptional<z.ZodNumber>;
+            ConnectivitySMILES: z.ZodOptional<z.ZodString>;
+            MolecularFormula: z.ZodOptional<z.ZodString>;
+            MolecularWeight: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>;
+            IUPACName: z.ZodOptional<z.ZodString>;
+            InChI: z.ZodOptional<z.ZodString>;
+            InChIKey: z.ZodOptional<z.ZodString>;
+            XLogP: z.ZodOptional<z.ZodNumber>;
+            TPSA: z.ZodOptional<z.ZodNumber>;
+            HBondDonorCount: z.ZodOptional<z.ZodNumber>;
+            HBondAcceptorCount: z.ZodOptional<z.ZodNumber>;
+            RotatableBondCount: z.ZodOptional<z.ZodNumber>;
+            Complexity: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodTransform<{
+            cid: number;
+            canonicalSmiles: string | null;
+            molecularFormula: string | null;
+            molecularWeight: number | null;
+            iupacName: string | null;
+            inchi: string | null;
+            inchiKey: string | null;
+            xlogp: number | null;
+            tpsa: number | null;
+            hbondDonorCount: number | null;
+            hbondAcceptorCount: number | null;
+            rotatableBondCount: number | null;
+            complexity: number | null;
+        }, {
+            CID?: number | undefined;
+            ConnectivitySMILES?: string | undefined;
+            MolecularFormula?: string | undefined;
+            MolecularWeight?: number | null | undefined;
+            IUPACName?: string | undefined;
+            InChI?: string | undefined;
+            InChIKey?: string | undefined;
+            XLogP?: number | undefined;
+            TPSA?: number | undefined;
+            HBondDonorCount?: number | undefined;
+            HBondAcceptorCount?: number | undefined;
+            RotatableBondCount?: number | undefined;
+            Complexity?: number | undefined;
+        }>>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export interface PubChemCrossRef {
-    source: string;
+    /** The registry that the identifier pattern names, or `null` when no pattern matches. */
+    source: string | null;
     id: string;
 }
+export declare const PubChemXrefResponseSchema: z.ZodObject<{
+    InformationList: z.ZodOptional<z.ZodObject<{
+        Information: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            CID: z.ZodOptional<z.ZodNumber>;
+            RegistryID: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The registry of one identifier, or `null` when no pattern matches it. */
+export declare function classifyRegistryId(id: string): string | null;
 export interface PubChemAssay {
     aid: number;
     assayName: string | null;
@@ -62,6 +124,17 @@ export interface PubChemAssay {
     activityOutcome: string | null;
     activityValue: number | null;
 }
+export declare const PugAssaySummarySchema: z.ZodObject<{
+    Table: z.ZodOptional<z.ZodObject<{
+        Columns: z.ZodOptional<z.ZodObject<{
+            Column: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        Row: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            Cell: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type PugAssaySummary = z.infer<typeof PugAssaySummarySchema>;
 /** Resolve a compound to its identity + computed properties. Empty array = no match. */
 export declare function fetchPubchemCompounds(query: string, searchBy: PubChemSearchBy): Promise<PubChemCompound[]>;
 /** External registry ids for a CID. Empty array = the CID is in no external registry. */
@@ -71,4 +144,11 @@ export declare function fetchPubchemAssays(cid: number, opts: {
     activeOnly: boolean;
     limit: number;
 }): Promise<PubChemAssay[]>;
+/**
+ * Read the assay table by its wire headings.
+ *
+ * The `targetName` of a record is the target accession, because the table names
+ * no protein. The accession resolves against UniProt or against a ChEMBL target.
+ */
+export declare function parseAssaySummary(data: PugAssaySummary): PubChemAssay[];
 export {};