@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,149 @@
+/**
+ * Pure async client functions for biological pathway lookups via KEGG and Reactome.
+ *
+ * Used by §3.7 (Pathway Context).
+ */
+import { z } from "zod";
+import { apiFetch, apiFetchValidated, parseTSV } from "./api-utils.js";
+const KEGG_BASE = "https://rest.kegg.jp";
+const REACTOME_BASE = "https://reactome.org/ContentService";
+export function stripHtmlAndCollapseWs(s) {
+    return s
+        .replace(/<[^>]+>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const ORGANISM_MAP = {
+    hsa: "Homo sapiens",
+    mmu: "Mus musculus",
+    rno: "Rattus norvegicus",
+    dre: "Danio rerio",
+    dme: "Drosophila melanogaster",
+    cel: "Caenorhabditis elegans",
+    sce: "Saccharomyces cerevisiae",
+};
+// Reactome ContentService raw wire shapes, validated at the fetch boundary.
+// Every field is optional because the API omits absent values.
+/** A single hit from the Reactome ContentService search response. */
+const ReactomeSearchEntrySchema = z.object({
+    stId: z.string().optional(),
+    name: z.string().optional(),
+});
+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() }));
+/** Participant list — `getPathwayMemberships` reads `refEntities` per participant. */
+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) {
+    const searchRes = await apiFetch(`${KEGG_BASE}/find/pathway/${encodeURIComponent(query)}`, { parseAs: "text" });
+    if (searchRes.isErr())
+        return [];
+    const rows = parseTSV(searchRes.value);
+    const pathways = rows.slice(0, maxResults).map((cols) => {
+        const rawId = (cols[0] ?? "").replace("path:", "").replace("map", organism);
+        return {
+            id: rawId,
+            name: (cols[1] ?? "").trim(),
+            source: "kegg",
+            url: `https://www.kegg.jp/pathway/${rawId}`,
+        };
+    });
+    if (includeGenes) {
+        for (const pw of pathways) {
+            const geneRes = await apiFetch(`${KEGG_BASE}/link/${organism}/${pw.id}`, { parseAs: "text" });
+            if (geneRes.isOk()) {
+                const geneRows = parseTSV(geneRes.value);
+                pw.genes = geneRows.map((r) => (r[1] ?? "").replace(`${organism}:`, ""));
+            }
+        }
+    }
+    return pathways;
+}
+export async function searchReactome(query, species, maxResults, includeGenes) {
+    const params = new URLSearchParams({
+        query,
+        species,
+        types: "Pathway",
+        cluster: "true",
+        rows: String(maxResults),
+    });
+    const searchRes = await apiFetchValidated(`${REACTOME_BASE}/search/query?${params}`, ReactomeSearchResponseSchema, {
+        headers: { Accept: "application/json" },
+    });
+    if (searchRes.isErr())
+        return [];
+    const entries = [];
+    for (const group of searchRes.value.results ?? []) {
+        for (const entry of group.entries ?? [])
+            entries.push(entry);
+    }
+    const pathways = entries.slice(0, maxResults).map((e) => ({
+        id: e.stId ?? "",
+        name: stripHtmlAndCollapseWs(e.name ?? ""),
+        source: "reactome",
+        url: `https://reactome.org/content/detail/${e.stId ?? ""}`,
+    }));
+    if (includeGenes) {
+        for (const pw of pathways) {
+            const partRes = await apiFetchValidated(`${REACTOME_BASE}/data/participants/${pw.id}`, ReactomeParticipantsSchema, {
+                headers: { Accept: "application/json" },
+            });
+            if (partRes.isOk()) {
+                const names = new Set();
+                for (const p of partRes.value) {
+                    if (p.displayName)
+                        names.add(p.displayName);
+                }
+                pw.genes = [...names].sort();
+            }
+        }
+    }
+    return pathways;
+}
+export async function searchPathways(query, options = {}) {
+    const source = options.source ?? "both";
+    const organism = options.organism ?? "hsa";
+    const includeGenes = options.includeGenes ?? false;
+    const maxResults = options.maxResults ?? 10;
+    const reactomeSpecies = ORGANISM_MAP[organism] ?? organism;
+    const tasks = [];
+    if (source === "kegg" || source === "both") {
+        tasks.push(searchKegg(query, organism, maxResults, includeGenes));
+    }
+    if (source === "reactome" || source === "both") {
+        tasks.push(searchReactome(query, reactomeSpecies, maxResults, includeGenes));
+    }
+    const results = await Promise.all(tasks);
+    return results.flat();
+}
+/** 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)]);
+    // For Reactome pathways, fetch participant UniProts (bounded to avoid rate limits).
+    await Promise.all(reactome.slice(0, 50).map(async (pw) => {
+        try {
+            const partRes = await apiFetchValidated(`${REACTOME_BASE}/data/participants/${pw.id}`, ReactomeParticipantEntitiesSchema, {
+                headers: { Accept: "application/json" },
+            });
+            if (partRes.isErr())
+                return;
+            const accs = new Set();
+            for (const entity of partRes.value) {
+                for (const ref of entity.refEntities ?? []) {
+                    if (ref.schemaClass === "ReferenceGeneProduct" && ref.identifier) {
+                        accs.add(ref.identifier);
+                    }
+                }
+            }
+            pw.entity_uniprots = [...accs].sort();
+        }
+        catch {
+            // Leave entity_uniprots undefined on fetch failure — graceful fallback in dedup
+        }
+    }));
+    return [...kegg, ...reactome];
+}

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

@@ -0,0 +1,4 @@
+export declare const PHARMGKB_BASE = "https://api.pharmgkb.org/v1/data";
+export declare const PHARMGKB_HEADERS: {
+    readonly Accept: "application/json";
+};

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

@@ -0,0 +1,2 @@
+export const PHARMGKB_BASE = "https://api.pharmgkb.org/v1/data";
+export const PHARMGKB_HEADERS = { Accept: "application/json" };

package/dist/tools/lib/preview-lock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-previewId serialization for report iterations.
+ *
+ * Two iterations on the same preview must not race on its shared
+ * `assets/` directory or version-dir creation. This lock ensures
+ * sequential execution per previewId; iterations on different previewIds
+ * remain fully parallel.
+ *
+ * SCOPE — in-process only. This Map is process-local: it serializes
+ * iterations within one replica but gives NO cross-pod guarantee, and it
+ * does not survive a DBOS replay. That is acceptable today because
+ * `runReportIteration` runs in the in-process chat path (`passthroughStep`),
+ * not as a durable workflow. When `iterateReport` is ported to a DBOS
+ * workflow, replace this with a durable mechanism (a DBOS queue keyed by
+ * previewId, or a Postgres advisory lock) — an in-process lock would then be
+ * both a replay and a cross-replica correctness bug.
+ */
+/** @internal — exposed for tests to assert no leak after settlement. */
+export declare const __previewLocksForTest: Map<string, Promise<unknown>>;
+export declare function withPreviewLock<T>(previewId: string, fn: () => Promise<T>): Promise<T>;

package/dist/tools/lib/preview-lock.js

@@ -0,0 +1,35 @@
+/**
+ * Per-previewId serialization for report iterations.
+ *
+ * Two iterations on the same preview must not race on its shared
+ * `assets/` directory or version-dir creation. This lock ensures
+ * sequential execution per previewId; iterations on different previewIds
+ * remain fully parallel.
+ *
+ * SCOPE — in-process only. This Map is process-local: it serializes
+ * iterations within one replica but gives NO cross-pod guarantee, and it
+ * does not survive a DBOS replay. That is acceptable today because
+ * `runReportIteration` runs in the in-process chat path (`passthroughStep`),
+ * not as a durable workflow. When `iterateReport` is ported to a DBOS
+ * workflow, replace this with a durable mechanism (a DBOS queue keyed by
+ * previewId, or a Postgres advisory lock) — an in-process lock would then be
+ * both a replay and a cross-replica correctness bug.
+ */
+const previewLocks = new Map();
+/** @internal — exposed for tests to assert no leak after settlement. */
+export const __previewLocksForTest = previewLocks;
+export async function withPreviewLock(previewId, fn) {
+    const prior = previewLocks.get(previewId) ?? Promise.resolve();
+    const next = prior.then(fn, fn);
+    // The stored promise must not surface as an unhandled rejection — callers
+    // only see/handle `next`. Swallow on the stored chain after running the
+    // cleanup hook.
+    const stored = next
+        .finally(() => {
+        if (previewLocks.get(previewId) === stored)
+            previewLocks.delete(previewId);
+    })
+        .catch(() => undefined);
+    previewLocks.set(previewId, stored);
+    return next;
+}

package/dist/tools/lib/protein-family-modality.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Protein-family → preferred modality lookup, used by §2.2 Tractability
+ * fallback when Open Targets has no tractability assessment for the target.
+ */
+export interface ModalityFallback {
+    family: string | null;
+    preferred_modality: string;
+    rationale: string;
+    source: "family-match" | "default";
+}
+/**
+ * Infer a preferred modality from a free-text protein-family description
+ * (typically the UniProt family/keyword). Returns the dataset default when
+ * no family pattern matches.
+ */
+export declare function inferModalityFromFamily(familyText: string | null): ModalityFallback;

package/dist/tools/lib/protein-family-modality.js

@@ -0,0 +1,42 @@
+/**
+ * Protein-family → preferred modality lookup, used by §2.2 Tractability
+ * fallback when Open Targets has no tractability assessment for the target.
+ */
+import familyMappingData from "../../data/protein-family-modality.json" with { type: "json" };
+import { normalizeProteinFamily } from "./protein-family-normalize.js";
+// The JSON import yields an untyped/structurally-wide value; cast to the declared
+// shape, which the bundled data file is authored to satisfy.
+const dataset = familyMappingData;
+function loadDataset() {
+    return dataset;
+}
+/**
+ * Infer a preferred modality from a free-text protein-family description
+ * (typically the UniProt family/keyword). Returns the dataset default when
+ * no family pattern matches.
+ */
+export function inferModalityFromFamily(familyText) {
+    const ds = loadDataset();
+    const normalized = normalizeProteinFamily(familyText);
+    if (normalized) {
+        for (const entry of ds.families) {
+            for (const pattern of entry.patterns) {
+                const normPattern = normalizeProteinFamily(pattern);
+                if (normPattern && normalized.includes(normPattern)) {
+                    return {
+                        family: entry.family,
+                        preferred_modality: entry.preferred_modality,
+                        rationale: entry.rationale,
+                        source: "family-match",
+                    };
+                }
+            }
+        }
+    }
+    return {
+        family: null,
+        preferred_modality: ds.default.preferred_modality,
+        rationale: ds.default.rationale,
+        source: "default",
+    };
+}

package/dist/tools/lib/protein-family-normalize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Map free-text protein-family descriptors (UniProt keywords, HGNC names,
+ * GraphQL labels) to a single canonical lowercase form so the modality lookup
+ * in `protein-family-modality.json` has one pattern set to match against.
+ *
+ * Why this exists: UniProt keyword text and the modality-JSON patterns
+ * disagreed on hyphenation ("G-protein coupled receptor" vs
+ * "G protein-coupled receptor"), causing every GPCR target whose UniProt
+ * keyword used the hyphenated variant to fall through to the dataset default
+ * modality. See review of dossier 9ad29ba5 (GLP1R) — 2026-05-13.
+ */
+export declare function normalizeProteinFamily(input: string | null): string | null;

package/dist/tools/lib/protein-family-normalize.js

@@ -0,0 +1,46 @@
+/**
+ * Map free-text protein-family descriptors (UniProt keywords, HGNC names,
+ * GraphQL labels) to a single canonical lowercase form so the modality lookup
+ * in `protein-family-modality.json` has one pattern set to match against.
+ *
+ * Why this exists: UniProt keyword text and the modality-JSON patterns
+ * disagreed on hyphenation ("G-protein coupled receptor" vs
+ * "G protein-coupled receptor"), causing every GPCR target whose UniProt
+ * keyword used the hyphenated variant to fall through to the dataset default
+ * modality. See review of dossier 9ad29ba5 (GLP1R) — 2026-05-13.
+ */
+const FAMILIES = [
+    {
+        canonical: "g protein-coupled receptor",
+        patterns: [
+            /\bg[-\s]?protein[-\s]?coupled\s+receptor\b/i,
+            /\bgpcr\b/i,
+            /\b7tm\s+receptor\b/i,
+            /\brhodopsin-like\s+receptor\b/i,
+            /\bsecretin-like\s+receptor\b/i,
+        ],
+    },
+    {
+        canonical: "serine/threonine-protein kinase",
+        patterns: [/\bserine\/threonine[-\s]?protein\s+kinase\b/i],
+    },
+    {
+        canonical: "tyrosine-protein kinase",
+        patterns: [/\btyrosine[-\s]?protein\s+kinase\b/i],
+    },
+    // Extend as additional hyphen-style mismatches surface. The default branch
+    // below preserves the lowercased input so callers can still pattern-match
+    // unknown families.
+];
+export function normalizeProteinFamily(input) {
+    if (!input)
+        return null;
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    for (const fam of FAMILIES) {
+        if (fam.patterns.some((rx) => rx.test(trimmed)))
+            return fam.canonical;
+    }
+    return trimmed.toLowerCase();
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Pure async client functions for the PubChem PUG-REST API
+ * (https://pubchem.ncbi.nlm.nih.gov/rest/pug/).
+ *
+ * Used by the modulator-metadata enrichment step to refine ChEMBL's
+ * `molecule_type` annotation when ChEMBL itself returns "Unknown" — PubChem
+ * exposes molecular weight + SMILES + InChI properties that let us
+ * heuristically classify peptides, small molecules, and proteins without a
+ * hand-curated override table.
+ */
+export interface PubChemCompoundProperties {
+    cid: number;
+    molecularWeight: number | null;
+    inchiKey: string | null;
+    canonicalSmiles: string | null;
+    hBondDonorCount: number | null;
+    hBondAcceptorCount: number | null;
+}
+export declare function getCompoundPropertiesByCID(cid: number): Promise<PubChemCompoundProperties | null>;
+/**
+ * Look up a PubChem compound by InChI key (the canonical hash of the 3-D
+ * structure that we can lift from ChEMBL's molecule_structures payload).
+ * Returns null when the key is unknown to PubChem.
+ */
+export declare function getCompoundPropertiesByInChIKey(inchiKey: string): Promise<PubChemCompoundProperties | null>;
+/**
+ * Heuristic molecule-type classifier driven by PubChem properties.
+ *
+ *   MW < 1500            → "Small molecule"
+ *   MW 1500–100,000      → "Peptide" when the SMILES carries ≥5 amide bonds, else "Unknown"
+ *   MW > 100,000         → "Protein"
+ *   No MW available      → "Unknown"
+ *
+ * The amide-bond floor (≥5) is a tractable check that catches insulin-class,
+ * calcitonin-class, and other small/medium peptide drugs while rejecting
+ * polyketides and macrocyclic small molecules of similar MW. We don't try to
+ * distinguish antibody/oligonucleotide modalities here — ChEMBL annotates
+ * those reliably; this heuristic only fires on its "Unknown" rows.
+ */
+export declare function classifyMoleculeType(props: PubChemCompoundProperties): string;

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

@@ -0,0 +1,128 @@
+/**
+ * Pure async client functions for the PubChem PUG-REST API
+ * (https://pubchem.ncbi.nlm.nih.gov/rest/pug/).
+ *
+ * Used by the modulator-metadata enrichment step to refine ChEMBL's
+ * `molecule_type` annotation when ChEMBL itself returns "Unknown" — PubChem
+ * exposes molecular weight + SMILES + InChI properties that let us
+ * heuristically classify peptides, small molecules, and proteins without a
+ * hand-curated override table.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } 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.
+    "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.
+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(),
+});
+const PubChemPropertyResponseSchema = z.object({
+    PropertyTable: z.object({ Properties: z.array(RawPubChemPropertySchema).optional() }).optional(),
+});
+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),
+    };
+}
+export async function getCompoundPropertiesByCID(cid) {
+    const url = `${PUBCHEM_BASE}/compound/cid/${cid}/property/${PROPERTY_FIELDS}/JSON`;
+    const res = await apiFetchValidated(url, PubChemPropertyResponseSchema, {
+        headers: PUBCHEM_HEADERS,
+    });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return null;
+        throw new Error(describeApiError(res.error));
+    }
+    const props = res.value.PropertyTable?.Properties?.[0];
+    if (!props || typeof props.CID !== "number")
+        return null;
+    return mapProps(props);
+}
+/**
+ * Look up a PubChem compound by InChI key (the canonical hash of the 3-D
+ * structure that we can lift from ChEMBL's molecule_structures payload).
+ * Returns null when the key is unknown to PubChem.
+ */
+export async function getCompoundPropertiesByInChIKey(inchiKey) {
+    const cidUrl = `${PUBCHEM_BASE}/compound/inchikey/${encodeURIComponent(inchiKey)}/cids/JSON`;
+    const cidRes = await apiFetchValidated(cidUrl, PubChemCidListResponseSchema, {
+        headers: PUBCHEM_HEADERS,
+    });
+    if (cidRes.isErr()) {
+        if (cidRes.error.type === "http_status" && cidRes.error.status === 404)
+            return null;
+        throw new Error(describeApiError(cidRes.error));
+    }
+    const cid = cidRes.value.IdentifierList?.CID?.[0];
+    if (cid == null)
+        return null;
+    return getCompoundPropertiesByCID(cid);
+}
+const AMIDE_BOND_RE = /C\(=O\)N/g;
+/**
+ * Heuristic molecule-type classifier driven by PubChem properties.
+ *
+ *   MW < 1500            → "Small molecule"
+ *   MW 1500–100,000      → "Peptide" when the SMILES carries ≥5 amide bonds, else "Unknown"
+ *   MW > 100,000         → "Protein"
+ *   No MW available      → "Unknown"
+ *
+ * The amide-bond floor (≥5) is a tractable check that catches insulin-class,
+ * calcitonin-class, and other small/medium peptide drugs while rejecting
+ * polyketides and macrocyclic small molecules of similar MW. We don't try to
+ * distinguish antibody/oligonucleotide modalities here — ChEMBL annotates
+ * those reliably; this heuristic only fires on its "Unknown" rows.
+ */
+export function classifyMoleculeType(props) {
+    const mw = props.molecularWeight;
+    if (mw == null || mw <= 0)
+        return "Unknown";
+    if (mw > 100_000)
+        return "Protein";
+    if (mw >= 1500) {
+        const amideCount = (props.canonicalSmiles ?? "").match(AMIDE_BOND_RE)?.length ?? 0;
+        if (amideCount >= 5)
+            return "Peptide";
+        return "Unknown";
+    }
+    return "Small molecule";
+}

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

@@ -0,0 +1,5 @@
+/** Shared constants for PubChem PUG-REST API tools. */
+export declare const PUBCHEM_BASE = "https://pubchem.ncbi.nlm.nih.gov/rest/pug";
+export declare const PUBCHEM_HEADERS: {
+    readonly Accept: "application/json";
+};

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

@@ -0,0 +1,3 @@
+/** Shared constants for PubChem PUG-REST API tools. */
+export const PUBCHEM_BASE = "https://pubchem.ncbi.nlm.nih.gov/rest/pug";
+export const PUBCHEM_HEADERS = { Accept: "application/json" };

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

@@ -0,0 +1,28 @@
+/**
+ * Pure async client functions for PubMed and PubMed Central via NCBI E-utilities.
+ *
+ * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
+ * pubmed-index Phase-1 collector.
+ */
+import { type ArticleDetail, type PubMedSummary, type FullTextResult } from "./ncbi-utils.js";
+export type { PubMedSummary, ArticleDetail, FullTextResult };
+export interface SearchOptions {
+    maxResults?: number;
+    sort?: "relevance" | "date";
+    dateRange?: {
+        from: string;
+        to: string;
+    };
+}
+/** PubMed search via esearch + esummary. */
+export declare function searchPubmed(ncbiApiKey: string | undefined, query: string, options?: SearchOptions): Promise<{
+    totalFound: number;
+    results: PubMedSummary[];
+}>;
+/** Fetch full PubMed article details (efetch + ID Converter for PMC). */
+export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[]): Promise<{
+    articles: ArticleDetail[];
+    notFound: string[];
+}>;
+/** Fetch open-access full text from PMC. Returns null when unavailable. */
+export declare function getArticleFullText(ncbiApiKey: string | undefined, pmcId: string): Promise<FullTextResult | null>;

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

@@ -0,0 +1,91 @@
+/**
+ * Pure async client functions for PubMed and PubMed Central via NCBI E-utilities.
+ *
+ * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
+ * pubmed-index Phase-1 collector.
+ */
+import { z } from "zod";
+import { apiFetch, apiFetchValidated, describeApiError } from "./api-utils.js";
+import { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEsummary, parseEfetch, parseIdConvResponse, parsePmcFullText, } from "./ncbi-utils.js";
+// NCBI E-utilities JSON payloads, validated at the fetch boundary. Every field
+// is optional because the API omits absent values.
+const EsearchResponseSchema = z.object({
+    esearchresult: z.object({ idlist: z.array(z.string()).optional(), count: z.string().optional() }).optional(),
+});
+const IdConvResponseSchema = z.object({
+    records: z.array(z.object({ pmid: z.string().optional(), pmcid: z.string().optional() })).optional(),
+});
+/** PubMed search via esearch + esummary. */
+export async function searchPubmed(ncbiApiKey, query, options = {}) {
+    const maxResults = options.maxResults ?? 10;
+    const sort = options.sort ?? "relevance";
+    const esearchParams = {
+        db: "pubmed",
+        term: query,
+        retmax: maxResults,
+        retmode: "json",
+        sort: sort === "date" ? "pub+date" : "relevance",
+    };
+    if (options.dateRange) {
+        esearchParams.mindate = options.dateRange.from;
+        esearchParams.maxdate = options.dateRange.to;
+        esearchParams.datetype = "pdat";
+    }
+    const searchUrl = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/esearch.fcgi`, esearchParams);
+    const searchResult = await apiFetchValidated(searchUrl, EsearchResponseSchema);
+    if (searchResult.isErr())
+        throw new Error(describeApiError(searchResult.error));
+    const idList = searchResult.value.esearchresult?.idlist ?? [];
+    const totalFound = parseInt(searchResult.value.esearchresult?.count ?? "0", 10);
+    if (idList.length === 0)
+        return { totalFound, results: [] };
+    const summaryUrl = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/esummary.fcgi`, {
+        db: "pubmed",
+        id: idList.join(","),
+        retmode: "xml",
+    });
+    const summaryResult = await apiFetch(summaryUrl, { parseAs: "text" });
+    if (summaryResult.isErr())
+        throw new Error(describeApiError(summaryResult.error));
+    return { totalFound, results: parseEsummary(summaryResult.value) };
+}
+/** Fetch full PubMed article details (efetch + ID Converter for PMC). */
+export async function getArticleDetails(ncbiApiKey, pmids) {
+    const idString = pmids.join(",");
+    const efetchAsync = apiFetch(ncbiUrl(ncbiApiKey, `${NCBI_BASE}/efetch.fcgi`, {
+        db: "pubmed",
+        id: idString,
+        rettype: "xml",
+        retmode: "xml",
+    }), { parseAs: "text" });
+    const idConvAsync = apiFetchValidated(ncbiUrl(ncbiApiKey, NCBI_IDCONV, { ids: idString, format: "json" }), IdConvResponseSchema);
+    // Both requests run concurrently; each Result is awaited and handled below.
+    const efetchResult = await efetchAsync;
+    const idConvResult = await idConvAsync;
+    if (efetchResult.isErr())
+        throw new Error(describeApiError(efetchResult.error));
+    const articles = parseEfetch(efetchResult.value);
+    if (idConvResult.isOk()) {
+        const pmcMap = parseIdConvResponse(idConvResult.value);
+        for (const article of articles) {
+            article.pmcId = pmcMap.get(article.pmid) ?? null;
+        }
+    }
+    const foundPmids = new Set(articles.map((a) => a.pmid));
+    const notFound = pmids.filter((id) => !foundPmids.has(id));
+    return { articles, notFound };
+}
+/** Fetch open-access full text from PMC. Returns null when unavailable. */
+export async function getArticleFullText(ncbiApiKey, pmcId) {
+    const numericId = pmcId.replace(/^PMC/i, "");
+    const url = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/efetch.fcgi`, {
+        db: "pmc",
+        id: numericId,
+        rettype: "xml",
+        retmode: "xml",
+    });
+    const result = await apiFetch(url, { parseAs: "text" });
+    if (result.isErr())
+        throw new Error(describeApiError(result.error));
+    return parsePmcFullText(result.value);
+}