@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,126 @@
+/**
+ * Pure async client functions for the NCBI ClinVar API.
+ *
+ * Used by §3.4 (Genetic Alterations — ClinVar variants).
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { ncbiUrl } from "./ncbi-utils.js";
+// NCBI esummary wire shapes, validated at the fetch boundary. Every field is
+// optional — esummary omits absent values, and the record mapping below tolerates
+// partial payloads, so an over-strict schema would regress graceful degradation.
+/** NCBI esummary v2 classification block (germline or legacy). */
+const ClinvarClassificationSchema = z.object({
+    description: z.string().optional(),
+    review_status: z.string().optional(),
+    trait_set: z.array(z.object({ trait_name: z.string().optional() })).optional(),
+});
+/** A single ClinVar esummary record. */
+const ClinvarSummaryRecordSchema = z.object({
+    title: z.string().optional(),
+    accession: z.string().optional(),
+    genes: z.array(z.object({ symbol: z.string().optional() })).optional(),
+    germline_classification: ClinvarClassificationSchema.optional(),
+    clinical_significance: z.union([ClinvarClassificationSchema, z.string()]).optional(),
+    trait_set: z.array(z.object({ trait_name: z.string().optional() })).optional(),
+    molecular_consequence_list: z.array(z.string()).optional(),
+    variation_set: z.array(z.object({ variation_loc: z.array(z.object({ variant_type: z.string().optional() })).optional() })).optional(),
+});
+const ClinvarSearchResponseSchema = z.object({
+    esearchresult: z
+        .object({
+        idlist: z.array(z.string()).optional(),
+        count: z.union([z.string(), z.number()]).optional(),
+    })
+        .optional(),
+});
+// esummary keys each record under its UID; the `uids` key holds a string[] of
+// the returned UIDs, so a record value is a summary object OR that string[].
+// The array member is listed first so an actual array never falls through to
+// the object schema (which rejects arrays).
+const ClinvarSummaryResponseSchema = z.object({
+    result: z.record(z.string(), z.union([z.array(z.string()), ClinvarSummaryRecordSchema])).optional(),
+});
+const SIG_MAP = {
+    pathogenic: "clinsig_pathogenic",
+    "likely-pathogenic": "clinsig_likely_pathogenic",
+    benign: "clinsig_benign",
+    "likely-benign": "clinsig_likely_benign",
+    uncertain: "clinsig_uncertain",
+};
+/** Filter out uninformative ClinVar entries (literal "not provided", placeholders). */
+export function filterInformative(variants) {
+    const noise = /^(not provided|not specified|reclassified)$/i;
+    return variants.filter((v) => {
+        const sig = (v.clinicalSignificance ?? "").trim();
+        if (!sig || noise.test(sig))
+            return false;
+        return true;
+    });
+}
+export async function searchClinvar(ncbiApiKey, query, options = {}) {
+    const limit = options.limit ?? 20;
+    let searchTerm = query;
+    if (options.clinicalSignificance) {
+        searchTerm += ` AND ${SIG_MAP[options.clinicalSignificance]}[Properties]`;
+    }
+    const searchUrl = ncbiUrl(ncbiApiKey, "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi", {
+        db: "clinvar",
+        term: searchTerm,
+        retmax: String(limit),
+        retmode: "json",
+    });
+    const searchRes = await apiFetchValidated(searchUrl, ClinvarSearchResponseSchema);
+    if (searchRes.isErr())
+        throw new Error(describeApiError(searchRes.error));
+    const ids = searchRes.value?.esearchresult?.idlist ?? [];
+    const totalFound = Number(searchRes.value?.esearchresult?.count ?? ids.length);
+    if (ids.length === 0)
+        return { totalFound, variants: [] };
+    const summaryUrl = ncbiUrl(ncbiApiKey, "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi", {
+        db: "clinvar",
+        id: ids.join(","),
+        retmode: "json",
+    });
+    const summaryRes = await apiFetchValidated(summaryUrl, ClinvarSummaryResponseSchema);
+    if (summaryRes.isErr())
+        throw new Error(describeApiError(summaryRes.error));
+    const result = summaryRes.value?.result ?? {};
+    const rawUids = result.uids;
+    const uids = Array.isArray(rawUids) ? rawUids : ids;
+    const variants = uids.map((uid) => {
+        const recEntry = result[uid];
+        const rec = recEntry && !Array.isArray(recEntry) ? recEntry : {};
+        const genes = rec.genes ?? [];
+        const geneSymbol = genes[0]?.symbol ?? "";
+        // NCBI esummary v2 schema: germline_classification holds the primary
+        // pathogenicity call. The legacy top-level clinical_significance field
+        // no longer appears in responses — fall back gracefully for older cached data.
+        const germline = rec.germline_classification ?? {};
+        // The legacy field is either a classification object or a bare string.
+        const legacy = rec.clinical_significance;
+        const legacyObj = typeof legacy === "object" ? legacy : null;
+        const legacyStr = typeof legacy === "string" ? legacy : null;
+        const clinSig = germline.description ?? legacyObj?.description ?? legacyStr ?? "";
+        const reviewStatus = germline.review_status ?? legacyObj?.review_status ?? "";
+        const conditions = (germline.trait_set ?? rec.trait_set ?? []).map((t) => t.trait_name ?? "");
+        const molecularConsequence = rec.molecular_consequence_list?.join(", ") ??
+            rec.variation_set
+                ?.flatMap((vs) => vs.variation_loc ?? [])
+                .map((vl) => vl.variant_type ?? "")
+                .filter(Boolean)
+                .join(", ") ??
+            "";
+        return {
+            variationId: uid,
+            title: rec.title ?? "",
+            clinicalSignificance: clinSig,
+            reviewStatus,
+            geneSymbol,
+            molecularConsequence,
+            conditions,
+            accession: rec.accession ?? `VCV${uid.padStart(9, "0")}`,
+        };
+    });
+    return { totalFound, variants };
+}

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

@@ -0,0 +1,2 @@
+export declare const DISGENET_BASE = "https://www.disgenet.org/api";
+export declare function getDisgenetHeaders(apiKey: string): Record<string, string>;

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

@@ -0,0 +1,11 @@
+export const DISGENET_BASE = "https://www.disgenet.org/api";
+export function getDisgenetHeaders(apiKey) {
+    const key = apiKey;
+    if (!key) {
+        throw new Error("DISGENET_API_KEY environment variable is not set. " + "Obtain a key from https://www.disgenet.org/api/#/Authorization");
+    }
+    return {
+        Authorization: `Bearer ${key}`,
+        Accept: "application/json",
+    };
+}

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

@@ -0,0 +1,2 @@
+export declare const DRUGBANK_BASE = "https://api.drugbank.com/v1";
+export declare function getDrugbankHeaders(apiKey: string): Record<string, string>;

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

@@ -0,0 +1,12 @@
+export const DRUGBANK_BASE = "https://api.drugbank.com/v1";
+export function getDrugbankHeaders(apiKey) {
+    const key = apiKey;
+    if (!key) {
+        throw new Error("DRUGBANK_API_KEY environment variable is not set. " + "Obtain a key from https://go.drugbank.com/");
+    }
+    return {
+        Authorization: key,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Pure async client functions for the EMA (European Medicines Agency)
+ * referrals catalogue.
+ *
+ * The catalogue is exposed as a single bulk JSON download (~700KB) that
+ * lists every ongoing and completed EMA referral procedure (Article 31,
+ * Article 20, etc.). We fetch and cache it in-process; per-drug queries
+ * filter the cached records by INN, referral name, and associated
+ * medicine names.
+ */
+export interface EmaReferral {
+    category: string;
+    referralName: string;
+    inn: string;
+    currentStatus: string;
+    safetyReferral: boolean;
+    referralType: string;
+    associatedMedicinesCentrally: string[];
+    associatedMedicinesNationally: string[];
+    class: string;
+    referenceNumber: string;
+    authorisationModel: string;
+    procedureStartDate: string;
+    pracRecommendationDate: string;
+    cmdhPositionDate: string;
+    chmpOpinionDate: string;
+    europeanCommissionDecisionDate: string;
+    firstPublishedDate: string;
+    lastUpdatedDate: string;
+    referralUrl: string;
+}
+/**
+ * Download (or return cached) full EMA referrals catalogue. The catalogue
+ * updates twice daily — a 6h in-process TTL is well within freshness
+ * tolerance while keeping the per-collector overhead near zero.
+ */
+export declare function fetchAllReferrals(): Promise<EmaReferral[]>;
+/**
+ * Find EMA referrals associated with a drug name (matches INN, referral
+ * name, and centrally/nationally-authorised medicine names). Returns all
+ * matches; the caller filters by referralType / currentStatus as needed.
+ */
+export declare function getReferralsByDrug(drugName: string): Promise<EmaReferral[]>;
+/** Reset the in-process catalogue cache. Test-only. */
+export declare function __resetReferralsCacheForTest(): void;

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

@@ -0,0 +1,127 @@
+/**
+ * Pure async client functions for the EMA (European Medicines Agency)
+ * referrals catalogue.
+ *
+ * The catalogue is exposed as a single bulk JSON download (~700KB) that
+ * lists every ongoing and completed EMA referral procedure (Article 31,
+ * Article 20, etc.). We fetch and cache it in-process; per-drug queries
+ * filter the cached records by INN, referral name, and associated
+ * medicine names.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { EMA_REFERRALS_URL } from "./ema-config.js";
+function parseMedicineList(field) {
+    if (!field || !field.trim())
+        return [];
+    return field
+        .split(/[;,]/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+// One schema that both validates the raw referral wire shape (snake_case, every
+// field optional or null — the bulk file omits or nulls absent values) and
+// normalizes it into the camelCase `EmaReferral` we return. Parsing IS the
+// validation: `apiFetchValidated` runs this over the download, so a record whose
+// field TYPES drift is rejected as `invalid_response` instead of silently
+// mis-mapped. Every field is `.nullable()` so one null-bearing record in the
+// ~600-row catalogue doesn't fail the whole `data` array (the transform already
+// collapses null to "" via `??`).
+const EmaReferralSchema = z
+    .object({
+    category: z.string().nullable().optional(),
+    referral_name: z.string().nullable().optional(),
+    international_non_proprietary_name_inn_common_name: z.string().nullable().optional(),
+    current_status: z.string().nullable().optional(),
+    safety_referral: z.string().nullable().optional(),
+    referral_type: z.string().nullable().optional(),
+    associated_names_centrally_authorised_medicines: z.string().nullable().optional(),
+    associated_names_non_centrally_authorised_medicines: z.string().nullable().optional(),
+    class: z.string().nullable().optional(),
+    reference_number: z.string().nullable().optional(),
+    authorisation_model: z.string().nullable().optional(),
+    procedure_start_date: z.string().nullable().optional(),
+    prac_recommendation_date: z.string().nullable().optional(),
+    cmdh_position_date: z.string().nullable().optional(),
+    chmp_cvmp_opinion_date: z.string().nullable().optional(),
+    european_commission_decision_date: z.string().nullable().optional(),
+    first_published_date: z.string().nullable().optional(),
+    last_updated_date: z.string().nullable().optional(),
+    referral_url: z.string().nullable().optional(),
+})
+    .transform((raw) => ({
+    category: raw.category ?? "",
+    referralName: raw.referral_name ?? "",
+    inn: raw.international_non_proprietary_name_inn_common_name ?? "",
+    currentStatus: raw.current_status ?? "",
+    safetyReferral: (raw.safety_referral ?? "").toLowerCase() === "yes",
+    referralType: raw.referral_type ?? "",
+    associatedMedicinesCentrally: parseMedicineList(raw.associated_names_centrally_authorised_medicines),
+    associatedMedicinesNationally: parseMedicineList(raw.associated_names_non_centrally_authorised_medicines),
+    class: raw.class ?? "",
+    referenceNumber: raw.reference_number ?? "",
+    authorisationModel: raw.authorisation_model ?? "",
+    procedureStartDate: raw.procedure_start_date ?? "",
+    pracRecommendationDate: raw.prac_recommendation_date ?? "",
+    cmdhPositionDate: raw.cmdh_position_date ?? "",
+    chmpOpinionDate: raw.chmp_cvmp_opinion_date ?? "",
+    europeanCommissionDecisionDate: raw.european_commission_decision_date ?? "",
+    firstPublishedDate: raw.first_published_date ?? "",
+    lastUpdatedDate: raw.last_updated_date ?? "",
+    referralUrl: raw.referral_url ?? "",
+}));
+const ReferralFileSchema = z.object({
+    meta: z.object({ total_records: z.number().optional(), timestamp: z.string().optional() }).optional(),
+    data: z.array(EmaReferralSchema).optional(),
+});
+let _cache = null;
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+/**
+ * Download (or return cached) full EMA referrals catalogue. The catalogue
+ * updates twice daily — a 6h in-process TTL is well within freshness
+ * tolerance while keeping the per-collector overhead near zero.
+ */
+export async function fetchAllReferrals() {
+    if (_cache && Date.now() - _cache.fetchedAt < CACHE_TTL_MS) {
+        return _cache.referrals;
+    }
+    const res = await apiFetchValidated(EMA_REFERRALS_URL, ReferralFileSchema, {
+        headers: { Accept: "application/json" },
+    });
+    if (res.isErr())
+        throw new Error(`EMA referrals fetch failed: ${describeApiError(res.error)}`);
+    const referrals = res.value.data ?? [];
+    _cache = { fetchedAt: Date.now(), referrals };
+    return referrals;
+}
+function nameMatches(referral, needle) {
+    if (!needle)
+        return false;
+    if (referral.inn.toLowerCase().includes(needle))
+        return true;
+    if (referral.referralName.toLowerCase().includes(needle))
+        return true;
+    for (const m of referral.associatedMedicinesCentrally) {
+        if (m.toLowerCase().includes(needle))
+            return true;
+    }
+    for (const m of referral.associatedMedicinesNationally) {
+        if (m.toLowerCase().includes(needle))
+            return true;
+    }
+    return false;
+}
+/**
+ * Find EMA referrals associated with a drug name (matches INN, referral
+ * name, and centrally/nationally-authorised medicine names). Returns all
+ * matches; the caller filters by referralType / currentStatus as needed.
+ */
+export async function getReferralsByDrug(drugName) {
+    const all = await fetchAllReferrals();
+    const needle = drugName.toLowerCase().trim();
+    return all.filter((r) => nameMatches(r, needle));
+}
+/** Reset the in-process catalogue cache. Test-only. */
+export function __resetReferralsCacheForTest() {
+    _cache = null;
+}

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

@@ -0,0 +1,7 @@
+/** Shared constants for the EMA (European Medicines Agency) data downloads. */
+/**
+ * Full referrals catalogue (~600 rows, ~700KB). Updated twice daily at
+ * 06:00 and 18:00 Amsterdam time. There is no per-drug query endpoint;
+ * we download the bulk file and filter in-process.
+ */
+export declare const EMA_REFERRALS_URL = "https://www.ema.europa.eu/en/documents/report/referrals-output-json-report_en.json";

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

@@ -0,0 +1,7 @@
+/** Shared constants for the EMA (European Medicines Agency) data downloads. */
+/**
+ * Full referrals catalogue (~600 rows, ~700KB). Updated twice daily at
+ * 06:00 and 18:00 Amsterdam time. There is no per-drug query endpoint;
+ * we download the bulk file and filter in-process.
+ */
+export const EMA_REFERRALS_URL = "https://www.ema.europa.eu/en/documents/report/referrals-output-json-report_en.json";

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

@@ -0,0 +1,27 @@
+/**
+ * Pure async client functions for the Ensembl REST API.
+ *
+ * Used by §1.1 (Entity resolution) and as a fallback for ID resolution.
+ */
+export interface GeneInfo {
+    symbol: string;
+    id: string;
+    displayName: string;
+    description: string;
+    biotype: string;
+    start: number;
+    end: number;
+    strand: number;
+    assemblyName: string;
+    seqRegionName: string;
+}
+export interface LookupOptions {
+    species?: string;
+    expand?: boolean;
+}
+export declare function lookupGenes(symbols: string[], options?: LookupOptions): Promise<{
+    genes: GeneInfo[];
+    notFound: string[];
+}>;
+/** Resolve a single human gene symbol to its canonical Ensembl ID. */
+export declare function resolveSymbolToEnsemblId(symbol: string): Promise<string | null>;

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

@@ -0,0 +1,82 @@
+/**
+ * Pure async client functions for the Ensembl REST API.
+ *
+ * Used by §1.1 (Entity resolution) and as a fallback for ID resolution.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+const ENSEMBL_BASE = "https://rest.ensembl.org";
+const HEADERS = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+};
+// Raw Ensembl gene wire shape (snake_case), validated at the fetch boundary.
+// Every field is optional because the API omits absent values; `mapGene`
+// normalizes each into the camelCase `GeneInfo` we return.
+const RawGeneSchema = z.object({
+    id: z.string().optional(),
+    display_name: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    biotype: z.string().optional(),
+    start: z.number().optional(),
+    end: z.number().optional(),
+    strand: z.number().optional(),
+    assembly_name: z.string().optional(),
+    seq_region_name: z.string().optional(),
+});
+function mapGene(symbol, raw) {
+    return {
+        symbol,
+        id: raw.id ?? "",
+        displayName: raw.display_name ?? "",
+        description: raw.description ?? "",
+        biotype: raw.biotype ?? "",
+        start: raw.start ?? 0,
+        end: raw.end ?? 0,
+        strand: raw.strand ?? 0,
+        assemblyName: raw.assembly_name ?? "",
+        seqRegionName: raw.seq_region_name ?? "",
+    };
+}
+export async function lookupGenes(symbols, options = {}) {
+    const species = options.species ?? "homo_sapiens";
+    const expand = options.expand ?? false;
+    if (symbols.length === 1) {
+        const expandParam = expand ? "?expand=1" : "";
+        const result = await apiFetchValidated(`${ENSEMBL_BASE}/lookup/symbol/${species}/${symbols[0]}${expandParam}`, RawGeneSchema, { headers: HEADERS });
+        if (result.isErr()) {
+            if (result.error.type === "http_status" && result.error.status === 400) {
+                return { genes: [], notFound: [symbols[0]] };
+            }
+            throw new Error(describeApiError(result.error));
+        }
+        return { genes: [mapGene(symbols[0], result.value)], notFound: [] };
+    }
+    const result = await apiFetchValidated(`${ENSEMBL_BASE}/lookup/symbol/${species}`, z.record(z.string(), RawGeneSchema), {
+        method: "POST",
+        headers: HEADERS,
+        body: JSON.stringify({ symbols }),
+    });
+    if (result.isErr())
+        throw new Error(describeApiError(result.error));
+    const genes = [];
+    const notFound = [];
+    for (const sym of symbols) {
+        const raw = result.value[sym];
+        if (raw)
+            genes.push(mapGene(sym, raw));
+        else
+            notFound.push(sym);
+    }
+    return { genes, notFound };
+}
+/** Resolve a single human gene symbol to its canonical Ensembl ID. */
+export async function resolveSymbolToEnsemblId(symbol) {
+    const url = `${ENSEMBL_BASE}/lookup/symbol/homo_sapiens/${encodeURIComponent(symbol)}`;
+    const res = await apiFetchValidated(url, z.object({ id: z.string().optional() }), { headers: HEADERS });
+    if (res.isErr())
+        return null;
+    if (typeof res.value.id !== "string" || !res.value.id.startsWith("ENSG"))
+        return null;
+    return res.value.id;
+}

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

@@ -0,0 +1,4 @@
+export declare const GWAS_BASE = "https://www.ebi.ac.uk/gwas/rest/api";
+export declare const GWAS_HEADERS: {
+    readonly Accept: "application/json";
+};

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

@@ -0,0 +1,2 @@
+export const GWAS_BASE = "https://www.ebi.ac.uk/gwas/rest/api";
+export const GWAS_HEADERS = { Accept: "application/json" };

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

@@ -0,0 +1,85 @@
+/**
+ * Identifier resolver — combines HGNC, UniProt, Ensembl, and ChEMBL gene-name
+ * fields into a single canonical entity payload with synonyms.
+ *
+ * Used by Phase 0 of the target-assessment workflow to resolve a user-
+ * supplied target string (gene symbol, alias, UniProt accession, Ensembl
+ * id, ChEMBL target id) to a canonical entity that downstream collectors
+ * can key off.
+ *
+ * Resolution order:
+ *   1. If the input matches a known id pattern (ENSG, UniProt 6-char,
+ *      CHEMBL\d+), use that as the seed.
+ *   2. Otherwise treat as a gene symbol and resolve via HGNC, then enrich
+ *      with UniProt, Ensembl, and ChEMBL.
+ *
+ * This is the only step in the workflow allowed to throw — a hard
+ * resolution failure aborts the assessment with `error.kind:
+ * "target-unresolved"` (per design §6).
+ */
+export interface ResolvedTarget {
+    /** Canonical id used as the entity-resolution anchor — preferred order: HGNC, then Ensembl. */
+    canonicalId: string;
+    /** What ontology produced the canonical id ("hgnc" or "ensembl"). */
+    canonicalOntology: "hgnc" | "ensembl";
+    /** Approved HGNC symbol (always uppercase). */
+    geneSymbol: string;
+    /** Full gene name. */
+    approvedName: string;
+    /** Cross-reference identifiers, populated where available. */
+    ids: {
+        hgnc: string | null;
+        ensembl: string | null;
+        uniprot: string | null;
+        chembl: string | null;
+        entrez: string | null;
+    };
+    /** Gene symbol synonyms. */
+    synonyms: string[];
+    /** Protein name synonyms (UniProt). */
+    proteinSynonyms: string[];
+    /** Protein family / classification fields gathered from UniProt or ChEMBL — used by §2.2 family fallback. */
+    proteinFamily: string | null;
+    /** Whether each upstream lookup succeeded — used to disclose coverage. */
+    resolutionCoverage: {
+        hgnc: boolean;
+        uniprot: boolean;
+        ensembl: boolean;
+        chembl: boolean;
+    };
+}
+/**
+ * Resolve a free-form target identifier to a canonical entity.
+ *
+ * @throws when the input cannot be mapped to any human gene/protein.
+ */
+export declare function resolveTarget(input: string): Promise<ResolvedTarget>;
+export interface AutocompleteCandidate {
+    /** Approved HGNC symbol when known, otherwise the input symbol. */
+    symbol: string;
+    /** Full gene/protein name. */
+    displayName: string | null;
+    hgncId: string | null;
+    ensemblId: string | null;
+    uniprotId: string | null;
+    /** Sorted synonyms across HGNC + UniProt. */
+    synonyms: string[];
+}
+/**
+ * Resolve a single gene-symbol query for the autocomplete UI by fanning
+ * out HGNC + UniProt + Ensembl in parallel and merging into one canonical
+ * candidate. Per `target-assessment/spec.md` "Autocomplete returns
+ * canonical identifiers" — three identifiers populated on one row, not
+ * three separate rows.
+ *
+ * Returns `null` when none of the upstream sources find a match. Throws
+ * never — failures of individual sources degrade to `null` for that field.
+ *
+ * Symbol handling mirrors `resolveTarget` so both entry points behave the
+ * same on edge cases:
+ *   - The query is upper-cased before hitting upstream APIs (HGNC's
+ *     `symbol` index is case-sensitive; `tp53` would miss).
+ *   - HGNC is queried with a `symbol` → `alias_symbol` → `prev_symbol`
+ *     fallback ladder so deprecated symbols still resolve.
+ */
+export declare function searchTargetByName(symbol: string): Promise<AutocompleteCandidate | null>;