@inflexa-ai/harness 0.1.1

package/dist/workflows/target-assessment/lib/dedup-modulators.d.ts

@@ -0,0 +1,37 @@
+import { type ChemblModulator } from "../../../tools/lib/chembl-client.js";
+export type DroppedSynonym = {
+    chemblId: string;
+    reason: "same_active_substance" | "ambiguous_name_synonym";
+    keptId: string | null;
+};
+export type DedupResult<T extends Pick<ChemblModulator, "moleculeChemblId" | "parentChemblId" | "maxPhase" | "firstApproval">> = {
+    kept: T[];
+    dropped: DroppedSynonym[];
+};
+/**
+ * Group modulators by parent_molecule_chembl_id (or moleculeChemblId when
+ * the parent is absent — singleton groups). Within each group keep the
+ * "most informative" entry: prefer firstApproval populated, then highest
+ * maxPhase, then earliest moleculeChemblId for deterministic tie-break.
+ *
+ * Reason: ChEMBL exposes the same active substance under multiple
+ * molecule_chembl_ids (e.g., CALCITONIN SALMON vs generic CALCITONIN),
+ * which causes downstream FAERS queries to double-count the same reports.
+ *
+ * A second pass handles name-prefix synonyms where ChEMBL does not populate
+ * molecule_hierarchy (e.g., CALCITONIN → CALCITONIN HUMAN). Entries with a
+ * null firstApproval whose preferredName (uppercased) is a strict
+ * word-boundary prefix of another entry's name within the same moleculeType
+ * are dropped as same_active_substance (one match) or ambiguous_name_synonym
+ * (multiple matches).
+ */
+export declare function dedupModulatorsByParent<T extends Pick<ChemblModulator, "moleculeChemblId" | "parentChemblId" | "maxPhase" | "firstApproval" | "preferredName" | "moleculeType">>(modulators: T[]): DedupResult<T>;
+/**
+ * For each modulator whose ChEMBL `moleculeType` is empty or "Unknown",
+ * fetch the molecule's standard InChI key from ChEMBL, look it up in
+ * PubChem, and apply the heuristic classifier (MW + amide-bond count).
+ * Returns a new array of modulators with `moleculeType` replaced when a
+ * confident classification emerges; otherwise the original ChEMBL value is
+ * preserved. Network failures are isolated per modulator.
+ */
+export declare function resolveModulatorMoleculeType<T extends Pick<ChemblModulator, "moleculeChemblId" | "moleculeType">>(modulators: T[]): Promise<T[]>;

package/dist/workflows/target-assessment/lib/dedup-modulators.js

@@ -0,0 +1,157 @@
+import { getMoleculeInChIKey } from "../../../tools/lib/chembl-client.js";
+import { classifyMoleculeType, getCompoundPropertiesByInChIKey } from "../../../tools/lib/pubchem-client.js";
+import { withHost } from "../../../lib/host-concurrency.js";
+/**
+ * Group modulators by parent_molecule_chembl_id (or moleculeChemblId when
+ * the parent is absent — singleton groups). Within each group keep the
+ * "most informative" entry: prefer firstApproval populated, then highest
+ * maxPhase, then earliest moleculeChemblId for deterministic tie-break.
+ *
+ * Reason: ChEMBL exposes the same active substance under multiple
+ * molecule_chembl_ids (e.g., CALCITONIN SALMON vs generic CALCITONIN),
+ * which causes downstream FAERS queries to double-count the same reports.
+ *
+ * A second pass handles name-prefix synonyms where ChEMBL does not populate
+ * molecule_hierarchy (e.g., CALCITONIN → CALCITONIN HUMAN). Entries with a
+ * null firstApproval whose preferredName (uppercased) is a strict
+ * word-boundary prefix of another entry's name within the same moleculeType
+ * are dropped as same_active_substance (one match) or ambiguous_name_synonym
+ * (multiple matches).
+ */
+export function dedupModulatorsByParent(modulators) {
+    const groups = new Map();
+    for (const m of modulators) {
+        const key = m.parentChemblId ?? m.moleculeChemblId;
+        const arr = groups.get(key) ?? [];
+        arr.push(m);
+        groups.set(key, arr);
+    }
+    const kept = [];
+    const dropped = [];
+    for (const group of groups.values()) {
+        if (group.length === 1) {
+            kept.push(group[0]);
+            continue;
+        }
+        const ranked = [...group].sort((a, b) => {
+            const aHasApp = a.firstApproval != null ? 1 : 0;
+            const bHasApp = b.firstApproval != null ? 1 : 0;
+            if (aHasApp !== bHasApp)
+                return bHasApp - aHasApp;
+            const aPhase = a.maxPhase ?? -1;
+            const bPhase = b.maxPhase ?? -1;
+            if (aPhase !== bPhase)
+                return bPhase - aPhase;
+            return a.moleculeChemblId.localeCompare(b.moleculeChemblId);
+        });
+        const winner = ranked[0];
+        kept.push(winner);
+        for (const loser of ranked.slice(1)) {
+            dropped.push({
+                chemblId: loser.moleculeChemblId,
+                reason: "same_active_substance",
+                keptId: winner.moleculeChemblId,
+            });
+        }
+    }
+    // Second pass: name-prefix synonym detection within the same moleculeType.
+    // Handles cases where ChEMBL does not populate molecule_hierarchy for
+    // unqualified generic names (e.g., "CALCITONIN" as a prefix of
+    // "CALCITONIN HUMAN" and "CALCITONIN SALMON"). Only drops entries with
+    // null firstApproval — an approved generic name should never be silently
+    // dropped.
+    const byType = new Map();
+    for (const m of kept) {
+        const k = (m.moleculeType ?? "").toUpperCase();
+        const arr = byType.get(k) ?? [];
+        arr.push(m);
+        byType.set(k, arr);
+    }
+    const dropIds = new Set();
+    for (const group of byType.values()) {
+        for (const shortEntry of group) {
+            if (shortEntry.firstApproval != null)
+                continue;
+            const shortName = (shortEntry.preferredName ?? "").trim().toUpperCase();
+            if (!shortName)
+                continue;
+            const longerMatches = group.filter((other) => {
+                if (other === shortEntry)
+                    return false;
+                const longName = (other.preferredName ?? "").trim().toUpperCase();
+                if (longName.length <= shortName.length)
+                    return false;
+                if (!longName.startsWith(shortName))
+                    return false;
+                // Require a word-boundary character (whitespace or hyphen) immediately
+                // after the prefix — prevents "CALC" from matching "CALCITONIN".
+                const boundary = longName.charAt(shortName.length);
+                return /[\s-]/.test(boundary);
+            });
+            if (longerMatches.length === 1) {
+                dropIds.add(shortEntry.moleculeChemblId);
+                dropped.push({
+                    chemblId: shortEntry.moleculeChemblId,
+                    reason: "same_active_substance",
+                    keptId: longerMatches[0].moleculeChemblId,
+                });
+            }
+            else if (longerMatches.length > 1) {
+                dropIds.add(shortEntry.moleculeChemblId);
+                dropped.push({
+                    chemblId: shortEntry.moleculeChemblId,
+                    reason: "ambiguous_name_synonym",
+                    keptId: null,
+                });
+            }
+        }
+    }
+    const finalKept = kept.filter((m) => !dropIds.has(m.moleculeChemblId));
+    return { kept: finalKept, dropped };
+}
+// ── PubChem-backed molecule_type backfill ─────────────────────────────────────
+function looksUnknown(value) {
+    if (!value)
+        return true;
+    const lowered = value.trim().toLowerCase();
+    return lowered === "" || lowered === "unknown";
+}
+/**
+ * For each modulator whose ChEMBL `moleculeType` is empty or "Unknown",
+ * fetch the molecule's standard InChI key from ChEMBL, look it up in
+ * PubChem, and apply the heuristic classifier (MW + amide-bond count).
+ * Returns a new array of modulators with `moleculeType` replaced when a
+ * confident classification emerges; otherwise the original ChEMBL value is
+ * preserved. Network failures are isolated per modulator.
+ */
+export async function resolveModulatorMoleculeType(modulators) {
+    const candidates = modulators.filter((m) => looksUnknown(m.moleculeType));
+    if (candidates.length === 0)
+        return modulators;
+    const refined = new Map();
+    await Promise.all(candidates.map(async (m) => {
+        try {
+            const inchiKey = await withHost("chembl", () => getMoleculeInChIKey(m.moleculeChemblId));
+            if (!inchiKey)
+                return;
+            const props = await withHost("pubchem", () => getCompoundPropertiesByInChIKey(inchiKey));
+            if (!props)
+                return;
+            const classified = classifyMoleculeType(props);
+            if (classified !== "Unknown")
+                refined.set(m.moleculeChemblId, classified);
+        }
+        catch {
+            // Per-modulator failures must not blank out the others — keep the
+            // original ChEMBL annotation.
+        }
+    }));
+    if (refined.size === 0)
+        return modulators;
+    return modulators.map((m) => {
+        const next = refined.get(m.moleculeChemblId);
+        if (!next)
+            return m;
+        return { ...m, moleculeType: next };
+    });
+}

package/dist/workflows/target-assessment/lib/evidence-conflict-detector.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic structural conflict detector.
+ *
+ * Each rule is a pure function over the dossier body. A row is emitted
+ * when the body internally contradicts itself in a way that should be
+ * impossible post-pipeline-fix. The post-fix pipeline should produce an
+ * empty array for any well-formed body; the rules exist to catch
+ * regressions and to surface upstream pipeline bugs.
+ */
+export type StructuralEvidenceConflict = {
+    evidence_item_id: string;
+    predicate: string;
+    contradicting_predicates: string[];
+    surfaced_in_section: string;
+    evidence: never[];
+};
+export declare function detectStructuralEvidenceConflicts(bodyInput: unknown): StructuralEvidenceConflict[];

package/dist/workflows/target-assessment/lib/evidence-conflict-detector.js

@@ -0,0 +1,100 @@
+/**
+ * Deterministic structural conflict detector.
+ *
+ * Each rule is a pure function over the dossier body. A row is emitted
+ * when the body internally contradicts itself in a way that should be
+ * impossible post-pipeline-fix. The post-fix pipeline should produce an
+ * empty array for any well-formed body; the rules exist to catch
+ * regressions and to surface upstream pipeline bugs.
+ */
+import { HIGH_EXPRESSION_TPM_THRESHOLD } from "./expression-constants.js";
+function checkFaersCoverage(body) {
+    const faers = body?.safety_profile?.faers;
+    const cp = body?.safety_profile?.class_precedent;
+    if (faers?.coverage !== "queried_no_data")
+        return null;
+    if (cp?.coverage !== "available")
+        return null;
+    let total = 0;
+    for (const o of cp.data?.per_organ ?? []) {
+        for (const ae of o.top_aes ?? [])
+            total += ae.report_count ?? 0;
+    }
+    if (total === 0)
+        return null;
+    return {
+        evidence_item_id: "structural:faers_coverage",
+        predicate: "safety_profile.faers.coverage=queried_no_data",
+        contradicting_predicates: [`safety_profile.class_precedent has ${total} FAERS-derived reports across per_organ.top_aes`],
+        surfaced_in_section: "safety_profile.faers",
+        evidence: [],
+    };
+}
+function checkFatalSignal(body) {
+    const signal = body?.derived?.risk_summary?.any_fatal_signal;
+    if (signal !== "unknown")
+        return null;
+    const bullets = body?.liability_summary?.liability_bullets ?? [];
+    const fatal = bullets.find((b) => b?.category === "fatal_post_market");
+    if (!fatal)
+        return null;
+    return {
+        evidence_item_id: "structural:fatal_signal",
+        predicate: "derived.risk_summary.any_fatal_signal=unknown",
+        contradicting_predicates: ["liability_summary.liability_bullets contains a fatal_post_market entry"],
+        surfaced_in_section: "derived.risk_summary",
+        evidence: [],
+    };
+}
+function checkTrialCount(body) {
+    const trials = body?.clinical_development?.trials;
+    const outcomes = body?.clinical_development?.outcomes;
+    if (trials?.coverage !== "queried_no_data")
+        return null;
+    const outcomeRows = outcomes?.coverage === "available" ? (outcomes.data?.rows ?? []) : [];
+    if (outcomeRows.length === 0)
+        return null;
+    return {
+        evidence_item_id: "structural:trial_count",
+        predicate: "clinical_development.trials.coverage=queried_no_data",
+        contradicting_predicates: [`clinical_development.outcomes.data.rows has ${outcomeRows.length} row(s)`],
+        surfaced_in_section: "clinical_development.outcomes",
+        evidence: [],
+    };
+}
+function checkHighExpressionCount(body) {
+    const reported = body?.derived?.liability_summary?.expression_breadth?.high_expression_tissue_count;
+    if (typeof reported !== "number")
+        return null;
+    const set = new Set();
+    const consensusRows = body?.reference_biology?.normal_tissue_expression?.data?.rows ?? [];
+    for (const r of consensusRows) {
+        if ((r.value ?? 0) >= HIGH_EXPRESSION_TPM_THRESHOLD && r.tissue) {
+            set.add(`${r.tissue}::human`);
+        }
+    }
+    const cells = body?.reference_biology?.preclinical?.expression_heatmap?.data?.cells ?? [];
+    for (const c of cells) {
+        if (c.rank === "high" && c.tissue)
+            set.add(`${c.tissue}::${c.species ?? "unknown"}`);
+    }
+    if (set.size === reported)
+        return null;
+    return {
+        evidence_item_id: "structural:high_expression_count",
+        predicate: `derived.liability_summary.expression_breadth.high_expression_tissue_count=${reported}`,
+        contradicting_predicates: [`body-recomputed count is ${set.size}`],
+        surfaced_in_section: "derived.liability_summary.expression_breadth",
+        evidence: [],
+    };
+}
+export function detectStructuralEvidenceConflicts(bodyInput) {
+    const body = bodyInput;
+    const out = [];
+    for (const fn of [checkFaersCoverage, checkFatalSignal, checkTrialCount, checkHighExpressionCount]) {
+        const row = fn(body);
+        if (row)
+            out.push(row);
+    }
+    return out;
+}

package/dist/workflows/target-assessment/lib/expression-constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TPM threshold for "high expression" classification, aligned with the
+ * Human Protein Atlas tissue-expression categorisation. Tissues with
+ * TPM >= this threshold count toward
+ * liability_summary.expression_breadth.high_expression_tissue_count
+ * and inform organ-rollup signal scoring.
+ */
+export declare const HIGH_EXPRESSION_TPM_THRESHOLD = 50;
+/**
+ * Off-tissue floor for CNS regions. Brain subregions (hypothalamus excepted)
+ * carry biologically meaningful CALCR/peptide-GPCR expression at single-digit
+ * nTPM; the default 100 floor produced organ_claim_without_probe_pass audit
+ * failures for CNS bullets that the recommendation makes.
+ */
+export declare const CNS_REGION_TPM_FLOOR = 5;
+/**
+ * Off-tissue floor for musculoskeletal tissues. Skeletal muscle and bone
+ * surfaces routinely show 20-80 nTPM for GPCRs whose ligands affect
+ * mineral and muscle metabolism.
+ */
+export declare const MUSCULOSKELETAL_TPM_FLOOR = 20;

package/dist/workflows/target-assessment/lib/expression-constants.js

@@ -0,0 +1,21 @@
+/**
+ * TPM threshold for "high expression" classification, aligned with the
+ * Human Protein Atlas tissue-expression categorisation. Tissues with
+ * TPM >= this threshold count toward
+ * liability_summary.expression_breadth.high_expression_tissue_count
+ * and inform organ-rollup signal scoring.
+ */
+export const HIGH_EXPRESSION_TPM_THRESHOLD = 50;
+/**
+ * Off-tissue floor for CNS regions. Brain subregions (hypothalamus excepted)
+ * carry biologically meaningful CALCR/peptide-GPCR expression at single-digit
+ * nTPM; the default 100 floor produced organ_claim_without_probe_pass audit
+ * failures for CNS bullets that the recommendation makes.
+ */
+export const CNS_REGION_TPM_FLOOR = 5;
+/**
+ * Off-tissue floor for musculoskeletal tissues. Skeletal muscle and bone
+ * surfaces routinely show 20-80 nTPM for GPCRs whose ligands affect
+ * mineral and muscle metabolism.
+ */
+export const MUSCULOSKELETAL_TPM_FLOOR = 20;

package/dist/workflows/target-assessment/lib/family-complex-supplement.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Build the obligate-cofactor supplement rows shown in
+ * OffTargetPanelV4.excluded_rows from the IUPHAR family-complexes collector
+ * bundle. Replaces the hand-curated calcitonin-only supplement that
+ * previously lived next to it.
+ *
+ * pchembl is set to 0 because IUPHAR exposes complex structure, not
+ * ligand affinity for the complex; the row is marked selectivity_unknown
+ * with an explicit reason so downstream readers see the obligate-cofactor
+ * surface rather than a developable potency claim. The per-row LLM
+ * clinical_consequence annotator populates `clinical_consequence` once
+ * the per-row annotation step runs.
+ */
+import type { ExcludedOffTargetRowV4Schema } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import type { z } from "zod";
+import type { FamilyComplexesBundle } from "../schemas.js";
+type ExcludedOffTargetRowV4 = z.infer<typeof ExcludedOffTargetRowV4Schema>;
+export declare function buildFamilyComplexSupplement(bundle: FamilyComplexesBundle): (Omit<ExcludedOffTargetRowV4, "evidence"> & {
+    evidence: [];
+})[];
+export {};

package/dist/workflows/target-assessment/lib/family-complex-supplement.js

@@ -0,0 +1,37 @@
+/**
+ * Build the obligate-cofactor supplement rows shown in
+ * OffTargetPanelV4.excluded_rows from the IUPHAR family-complexes collector
+ * bundle. Replaces the hand-curated calcitonin-only supplement that
+ * previously lived next to it.
+ *
+ * pchembl is set to 0 because IUPHAR exposes complex structure, not
+ * ligand affinity for the complex; the row is marked selectivity_unknown
+ * with an explicit reason so downstream readers see the obligate-cofactor
+ * surface rather than a developable potency claim. The per-row LLM
+ * clinical_consequence annotator populates `clinical_consequence` once
+ * the per-row annotation step runs.
+ */
+export function buildFamilyComplexSupplement(bundle) {
+    return bundle.complexes.map((c) => {
+        const accDesc = c.accessoryNames.length > 0 ? c.accessoryNames.join("+") : "an accessory protein";
+        return {
+            off_target_id: null,
+            off_target_name: c.complexName,
+            target_class: "GPCR receptor-accessory complex",
+            pchembl: 0,
+            is_safety_panel_target: false,
+            organ_system: null,
+            clinical_consequence: null,
+            selectivity: {
+                selectivity_unknown: true,
+                reason: "obligate cofactor (same primary protein, different accessory)",
+            },
+            selectivity_window_below_threshold: false,
+            relationship: "obligate_cofactor",
+            reason: `${c.complexName} is ${bundle.primaryTargetGene} heterodimerised with ${accDesc}; ` +
+                `selectivity is not pharmacologically attainable. Surfaced as an intrinsic-pharmacology ` +
+                `liability rather than a developable off-target.`,
+            evidence: [],
+        };
+    });
+}

package/dist/workflows/target-assessment/lib/heterodimer-filter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Detect receptor-accessory heterodimer entries that share the assessment
+ * target's gene product. These are NOT off-targets in the pharmacological
+ * sense: the primary protein is the same, only the obligate accessory
+ * cofactor differs. Selectivity windows between such partner complexes are
+ * not pharmacologically attainable and should not be reported as off-target
+ * liabilities.
+ *
+ * The accessory list is supplied by the IUPHAR family-complexes collector
+ * at runtime — there is no hardcoded RAMP/MRAP/RGS pattern. For a CALCR
+ * assessment the collector returns ["RAMP1","RAMP2","RAMP3"], so the
+ * regex matches "CALCR/RAMP1", "CALCR/RAMP2", "CALCR/RAMP3" only.
+ */
+export interface HeterodimerFilterInput {
+    assessmentGeneSymbol: string;
+    accessoryProteinNames: string[];
+}
+/**
+ * Build a predicate that returns true when an off-target name describes a
+ * heterodimer of the assessment target's primary protein with one of the
+ * supplied accessory gene symbols. Returns a constant-false predicate when
+ * the inputs cannot produce a meaningful match (missing gene symbol or
+ * empty accessory list).
+ *
+ * Matched substrings:
+ *   "<primary>/<accessory>"  (e.g., "CALCR/RAMP3")
+ *   "<primary> + <accessory>"
+ *   "<primary>-<accessory>"  (some sources use a hyphen)
+ */
+export declare function makeHeterodimerOfAssessmentFilter(input: HeterodimerFilterInput): (offTargetName: string) => boolean;
+/**
+ * One-shot helper for callers that already have an accessory list in hand.
+ * Equivalent to `makeHeterodimerOfAssessmentFilter(input)(offTargetName)`.
+ */
+export declare function isHeterodimerOfAssessment(input: {
+    assessmentGeneSymbol: string;
+    accessoryProteinNames: string[];
+    offTargetName: string;
+}): boolean;

package/dist/workflows/target-assessment/lib/heterodimer-filter.js

@@ -0,0 +1,54 @@
+/**
+ * Detect receptor-accessory heterodimer entries that share the assessment
+ * target's gene product. These are NOT off-targets in the pharmacological
+ * sense: the primary protein is the same, only the obligate accessory
+ * cofactor differs. Selectivity windows between such partner complexes are
+ * not pharmacologically attainable and should not be reported as off-target
+ * liabilities.
+ *
+ * The accessory list is supplied by the IUPHAR family-complexes collector
+ * at runtime — there is no hardcoded RAMP/MRAP/RGS pattern. For a CALCR
+ * assessment the collector returns ["RAMP1","RAMP2","RAMP3"], so the
+ * regex matches "CALCR/RAMP1", "CALCR/RAMP2", "CALCR/RAMP3" only.
+ */
+const ACC_ESCAPE_RE = /[.*+?^${}()|[\]\\]/g;
+function escapeForRegex(token) {
+    return token.replace(ACC_ESCAPE_RE, "\\$&");
+}
+/**
+ * Build a predicate that returns true when an off-target name describes a
+ * heterodimer of the assessment target's primary protein with one of the
+ * supplied accessory gene symbols. Returns a constant-false predicate when
+ * the inputs cannot produce a meaningful match (missing gene symbol or
+ * empty accessory list).
+ *
+ * Matched substrings:
+ *   "<primary>/<accessory>"  (e.g., "CALCR/RAMP3")
+ *   "<primary> + <accessory>"
+ *   "<primary>-<accessory>"  (some sources use a hyphen)
+ */
+export function makeHeterodimerOfAssessmentFilter(input) {
+    const target = input.assessmentGeneSymbol.trim().toUpperCase();
+    const accessories = input.accessoryProteinNames.map((n) => n.trim()).filter((n) => n.length > 0);
+    if (!target || accessories.length === 0) {
+        return () => false;
+    }
+    const alternation = accessories.map(escapeForRegex).join("|");
+    const re = new RegExp(`\\b([A-Z][A-Z0-9]{1,9})\\s*[\\/+\\-]\\s*(${alternation})\\b`, "i");
+    return (offTargetName) => {
+        const m = re.exec(offTargetName);
+        if (!m)
+            return false;
+        return m[1].toUpperCase() === target;
+    };
+}
+/**
+ * One-shot helper for callers that already have an accessory list in hand.
+ * Equivalent to `makeHeterodimerOfAssessmentFilter(input)(offTargetName)`.
+ */
+export function isHeterodimerOfAssessment(input) {
+    return makeHeterodimerOfAssessmentFilter({
+        assessmentGeneSymbol: input.assessmentGeneSymbol,
+        accessoryProteinNames: input.accessoryProteinNames,
+    })(input.offTargetName);
+}

package/dist/workflows/target-assessment/lib/intended-polypharm-filter.d.ts

@@ -0,0 +1,4 @@
+export declare function isIntendedCoTarget(modulatorChemblId: string, offTargetChemblId: string): {
+    intended: boolean;
+    reason?: string;
+};

package/dist/workflows/target-assessment/lib/intended-polypharm-filter.js

@@ -0,0 +1,24 @@
+/**
+ * Hand-curated catalogue of multi-target peptide agonists. Conservative
+ * by design — only well-documented dual/triple agonists where the
+ * additional receptor IS the marketed mechanism. Ambiguous cases stay
+ * in the off-target panel.
+ *
+ * Source: ChEMBL triage_rationale strings + class-precedent literature.
+ * Extend as new dual/triple agonists appear in chembl-modulators output.
+ */
+const INTENDED_PAIRS = [
+    { modulator: "CHEMBL4297839", coTarget: "CHEMBL4383", reason: "tirzepatide is a dual GLP-1R/GIPR agonist" },
+    { modulator: "CHEMBL4297630", coTarget: "CHEMBL1985", reason: "cotadutide is a dual GLP-1R/GCGR agonist" },
+    { modulator: "CHEMBL5095485", coTarget: "CHEMBL4383", reason: "retatrutide is a triple GLP-1R/GIPR/GCGR agonist" },
+    { modulator: "CHEMBL5095485", coTarget: "CHEMBL1985", reason: "retatrutide is a triple GLP-1R/GIPR/GCGR agonist" },
+    { modulator: "CHEMBL5314776", coTarget: "CHEMBL1985", reason: "survodutide is a dual GLP-1R/GCGR agonist" },
+    { modulator: "CHEMBL4297576", coTarget: "CHEMBL1985", reason: "efinopegdutide is a dual GLP-1R/GCGR agonist" },
+    { modulator: "CHEMBL3990012", coTarget: "CHEMBL1985", reason: "pegapamodutide is a dual GLP-1R/GCGR agonist" },
+];
+export function isIntendedCoTarget(modulatorChemblId, offTargetChemblId) {
+    const hit = INTENDED_PAIRS.find((p) => p.modulator === modulatorChemblId && p.coTarget === offTargetChemblId);
+    if (hit)
+        return { intended: true, reason: hit.reason };
+    return { intended: false };
+}

package/dist/workflows/target-assessment/lib/llm-step.d.ts

@@ -0,0 +1,77 @@
+/**
+ * LLM step wrapper for the target-assessment DBOS workflow body.
+ *
+ * Each Phase-2 decision and Phase-5 synthesis LLM call goes through
+ * `runLlmStep` — it wraps `DBOS.runStep({name})` around the chat provider
+ * call and classifies caught errors:
+ *
+ *   - `isBudgetExceeded(err) === true` (billing-gateway 402): self-send a
+ *     `BUDGET_EXCEEDED_TOPIC` marker addressed to this workflow's own
+ *     id, then return a sentinel marker. The wrapper does NOT call
+ *     `DBOS.cancelWorkflow` itself — the workflow body's terminal block
+ *     reads the marker, writes `status = "suspended_insufficient_funds"`
+ *     via `DBOS.runStep({name: "ta-terminal-suspended"})`, then issues
+ *     `DBOS.cancelWorkflow` + a trailing `runStep` to materialise the
+ *     CANCELLED terminal state. Deferring the cancel keeps the terminal
+ *     handler's DB writes inside DBOS step boundaries (replay-cached).
+ *   - anything else: rethrow so the caller wraps the failure as
+ *     `coverage: "queried_no_data"` with `error.kind: "synthesis-unavailable"`
+ *     (or `"queried_no_data"` for decisions).
+ *
+ * The step name is attempt-numbered by the caller — e.g.
+ * `"ta-synth:liability-bullets:0"`. On 402 + top-up + `DBOS.resumeWorkflow`
+ * the caller bumps the attempt counter so the resumed call lands a fresh
+ * DBOS cache slot rather than replaying the cancelled prior attempt.
+ */
+import type { AgentChat, ChatRequest, ChatResponse } from "../../../providers/types.js";
+import type { AgentSession } from "../../../auth/types.js";
+/**
+ * DBOS message topic the LLM step uses to mark the workflow as
+ * self-cancelled on a billing-gateway 402. The terminal handler drains the topic
+ * to dispatch to `markAssessmentSuspended` rather than the generic
+ * operator-cancel handler.
+ */
+export declare const BUDGET_EXCEEDED_TOPIC = "ta-budget-exceeded";
+export interface BudgetExceededMarker {
+    readonly stepName: string;
+    readonly agentId: string;
+    readonly error: string;
+}
+export interface RunLlmStepOptions {
+    /** Durable-step name — already attempt-numbered by the caller. */
+    readonly stepName: string;
+    /** Agent id stamped in the marker for telemetry. */
+    readonly agentId: string;
+    readonly provider: AgentChat;
+    readonly req: ChatRequest;
+    readonly session: AgentSession;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Sentinel returned (NOT thrown) when the wrapper has self-cancelled the
+ * workflow. The next `DBOS.runStep` after this point raises
+ * `DBOSWorkflowCancelledError`, so call sites only see this value on the
+ * synchronous return path before the cancel materialises. Callers MUST NOT
+ * wrap this as `coverage: "queried_no_data"` — the workflow is unwinding.
+ */
+export declare const BUDGET_EXCEEDED_SENTINEL: unique symbol;
+export type RunLlmStepResult = {
+    readonly kind: "ok";
+    readonly response: ChatResponse;
+} | {
+    readonly kind: "budget-exceeded";
+    readonly sentinel: typeof BUDGET_EXCEEDED_SENTINEL;
+};
+/**
+ * Run one LLM call inside a `DBOS.runStep` boundary. On a billing-gateway 402 the
+ * workflow self-cancels and the caller receives a sentinel result; on any
+ * other throw the original error rethrows.
+ */
+export declare function runLlmStep(opts: RunLlmStepOptions): Promise<RunLlmStepResult>;
+/**
+ * Drain the budget-exceeded topic for this workflow. Called from the
+ * terminal handler (after the body has unwound) to decide whether the
+ * workflow cancelled because of a 402 or because of an operator-initiated
+ * cancel. Returns the first marker (or `null` if none queued).
+ */
+export declare function readBudgetExceededMarker(): Promise<BudgetExceededMarker | null>;