@inflexa-ai/harness 0.1.1

package/dist/workflows/target-assessment/correction-loop.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Correction loop for Phase-3 fan-out branches that returned empty
+ * without an error.
+ *
+ * Contract:
+ *   1. If `coverage` is `available` (non-empty data), pass through.
+ *   2. If `coverage` is `queried_no_data` and we have a deterministic
+ *      alt-name retry available, run ONE retry. If it succeeds, return
+ *      the new payload tagged `available`.
+ *   3. If still empty after the alt-name retry, escalate ONCE to the
+ *      responsible Phase-2 agent (via the supplied `escalate` callback)
+ *      with the failure bundle. If the agent returns a usable payload,
+ *      return it. Otherwise return `coverage: "queried_no_data"`.
+ *
+ * The escalation callback is optional — callers without an agent fall
+ * back to a final coverage tag without escalation.
+ */
+import type { Coverage, SerializedError } from "./coverage.js";
+type CoverageEnvelope<T> = {
+    coverage: "available";
+    data: T;
+} | {
+    coverage: "queried_no_data";
+    error?: SerializedError;
+} | {
+    coverage: "not_loaded";
+    reason?: string;
+};
+export interface CorrectionInput<T> {
+    initial: CoverageEnvelope<T>;
+    altRetry?: () => Promise<CoverageEnvelope<T>>;
+    escalate?: () => Promise<CoverageEnvelope<T>>;
+}
+export interface CorrectionTrace {
+    altRetryAttempted: boolean;
+    altRetrySucceeded: boolean;
+    escalationAttempted: boolean;
+    escalationSucceeded: boolean;
+    finalCoverage: Coverage;
+}
+export declare function runCorrectionLoop<T>(input: CorrectionInput<T>): Promise<{
+    result: CoverageEnvelope<T>;
+    trace: CorrectionTrace;
+}>;
+export {};

package/dist/workflows/target-assessment/correction-loop.js

@@ -0,0 +1,62 @@
+/**
+ * Correction loop for Phase-3 fan-out branches that returned empty
+ * without an error.
+ *
+ * Contract:
+ *   1. If `coverage` is `available` (non-empty data), pass through.
+ *   2. If `coverage` is `queried_no_data` and we have a deterministic
+ *      alt-name retry available, run ONE retry. If it succeeds, return
+ *      the new payload tagged `available`.
+ *   3. If still empty after the alt-name retry, escalate ONCE to the
+ *      responsible Phase-2 agent (via the supplied `escalate` callback)
+ *      with the failure bundle. If the agent returns a usable payload,
+ *      return it. Otherwise return `coverage: "queried_no_data"`.
+ *
+ * The escalation callback is optional — callers without an agent fall
+ * back to a final coverage tag without escalation.
+ */
+export async function runCorrectionLoop(input) {
+    const trace = {
+        altRetryAttempted: false,
+        altRetrySucceeded: false,
+        escalationAttempted: false,
+        escalationSucceeded: false,
+        finalCoverage: input.initial.coverage,
+    };
+    if (input.initial.coverage === "available") {
+        return { result: input.initial, trace };
+    }
+    if (input.initial.coverage === "not_loaded") {
+        return { result: input.initial, trace };
+    }
+    if (input.altRetry) {
+        trace.altRetryAttempted = true;
+        try {
+            const retried = await input.altRetry();
+            if (retried.coverage === "available") {
+                trace.altRetrySucceeded = true;
+                trace.finalCoverage = "available";
+                return { result: retried, trace };
+            }
+        }
+        catch {
+            // alt retry failed; proceed to escalation
+        }
+    }
+    if (input.escalate) {
+        trace.escalationAttempted = true;
+        try {
+            const esc = await input.escalate();
+            if (esc.coverage === "available") {
+                trace.escalationSucceeded = true;
+                trace.finalCoverage = "available";
+                return { result: esc, trace };
+            }
+        }
+        catch {
+            // escalation failed; fall through
+        }
+    }
+    trace.finalCoverage = "queried_no_data";
+    return { result: input.initial, trace };
+}

package/dist/workflows/target-assessment/coverage.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared coverage discriminator for target-assessment workflow steps.
+ *
+ * Per design §6, every collector / decision / fan-out / synthesis step
+ * MUST wrap its body in try/catch and return a `{ coverage, ... }` shape
+ * instead of throwing. Only Phase 0 (target resolution) is allowed to
+ * throw — that legitimately aborts the workflow.
+ *
+ * Coverage states:
+ *   - "available"        — the upstream returned data; payload is present.
+ *   - "queried_no_data"  — the upstream was queried but came back empty
+ *                          (no rows / 404 / etc.) OR threw an error which
+ *                          we serialized into `error` instead of bubbling.
+ *   - "not_loaded"       — the upstream was never queried (feature flag,
+ *                          config disable, or upstream skipped because a
+ *                          precondition was not met).
+ */
+import { z } from "zod";
+export declare const CoverageSchema: z.ZodEnum<{
+    available: "available";
+    queried_no_data: "queried_no_data";
+    not_loaded: "not_loaded";
+}>;
+export type Coverage = z.infer<typeof CoverageSchema>;
+export declare const SerializedErrorSchema: z.ZodObject<{
+    message: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    stack: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SerializedError = z.infer<typeof SerializedErrorSchema>;
+export declare function serializeError(err: unknown): SerializedError;
+/**
+ * Build the schema for a `{ coverage, data, error? }` step output.
+ *
+ * Use as: `outputSchema: withCoverage(MyDataSchema)` where `MyDataSchema`
+ * is the shape of the Phase-1 / Phase-2 / etc. payload for this step.
+ */
+export declare function withCoverage<TData extends z.ZodTypeAny>(dataSchema: TData): z.ZodDiscriminatedUnion<[z.ZodObject<{
+    coverage: z.ZodLiteral<"available">;
+    data: TData;
+}, z.core.$strip>, z.ZodObject<{
+    coverage: z.ZodLiteral<"queried_no_data">;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        stack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    coverage: z.ZodLiteral<"not_loaded">;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "coverage">;
+/**
+ * Run a step body with the standard try/catch envelope. If the body
+ * resolves, returns `{ coverage: "available", data }`. If it throws,
+ * returns `{ coverage: "queried_no_data", error: serializeError(err) }`.
+ */
+export declare function runWithCoverage<T>(body: () => Promise<T>): Promise<{
+    coverage: "available";
+    data: T;
+} | {
+    coverage: "queried_no_data";
+    error: SerializedError;
+}>;
+/**
+ * Convenience wrapper for `{ rows: T[] }` payloads. Maps an empty rows
+ * array to `coverage: "queried_no_data"` so the dossier discriminator's
+ * "available ≡ we have data" invariant holds without per-callsite
+ * length checks. Use at any assembler callsite that emits a `rows`
+ * shape from a query that may legitimately return zero items.
+ */
+export declare function coverageFromRows<T>(rows: T[], opts?: {
+    reason?: string;
+}): {
+    coverage: "available";
+    data: {
+        rows: T[];
+    };
+} | {
+    coverage: "queried_no_data";
+    error: SerializedError;
+};

package/dist/workflows/target-assessment/coverage.js

@@ -0,0 +1,82 @@
+/**
+ * Shared coverage discriminator for target-assessment workflow steps.
+ *
+ * Per design §6, every collector / decision / fan-out / synthesis step
+ * MUST wrap its body in try/catch and return a `{ coverage, ... }` shape
+ * instead of throwing. Only Phase 0 (target resolution) is allowed to
+ * throw — that legitimately aborts the workflow.
+ *
+ * Coverage states:
+ *   - "available"        — the upstream returned data; payload is present.
+ *   - "queried_no_data"  — the upstream was queried but came back empty
+ *                          (no rows / 404 / etc.) OR threw an error which
+ *                          we serialized into `error` instead of bubbling.
+ *   - "not_loaded"       — the upstream was never queried (feature flag,
+ *                          config disable, or upstream skipped because a
+ *                          precondition was not met).
+ */
+import { z } from "zod";
+export const CoverageSchema = z.enum(["available", "queried_no_data", "not_loaded"]);
+export const SerializedErrorSchema = z.object({
+    message: z.string(),
+    name: z.string().optional(),
+    stack: z.string().optional(),
+});
+export function serializeError(err) {
+    if (err instanceof Error) {
+        return { message: err.message, name: err.name, stack: err.stack };
+    }
+    return { message: String(err) };
+}
+/**
+ * Build the schema for a `{ coverage, data, error? }` step output.
+ *
+ * Use as: `outputSchema: withCoverage(MyDataSchema)` where `MyDataSchema`
+ * is the shape of the Phase-1 / Phase-2 / etc. payload for this step.
+ */
+export function withCoverage(dataSchema) {
+    return z.discriminatedUnion("coverage", [
+        z.object({
+            coverage: z.literal("available"),
+            data: dataSchema,
+        }),
+        z.object({
+            coverage: z.literal("queried_no_data"),
+            error: SerializedErrorSchema.optional(),
+        }),
+        z.object({
+            coverage: z.literal("not_loaded"),
+            reason: z.string().optional(),
+        }),
+    ]);
+}
+/**
+ * Run a step body with the standard try/catch envelope. If the body
+ * resolves, returns `{ coverage: "available", data }`. If it throws,
+ * returns `{ coverage: "queried_no_data", error: serializeError(err) }`.
+ */
+export async function runWithCoverage(body) {
+    try {
+        const data = await body();
+        return { coverage: "available", data };
+    }
+    catch (err) {
+        return { coverage: "queried_no_data", error: serializeError(err) };
+    }
+}
+/**
+ * Convenience wrapper for `{ rows: T[] }` payloads. Maps an empty rows
+ * array to `coverage: "queried_no_data"` so the dossier discriminator's
+ * "available ≡ we have data" invariant holds without per-callsite
+ * length checks. Use at any assembler callsite that emits a `rows`
+ * shape from a query that may legitimately return zero items.
+ */
+export function coverageFromRows(rows, opts) {
+    if (rows.length === 0) {
+        return {
+            coverage: "queried_no_data",
+            error: { message: opts?.reason ?? "no rows returned" },
+        };
+    }
+    return { coverage: "available", data: { rows } };
+}

package/dist/workflows/target-assessment/decisions/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Phase-2 decision functions for the harness DBOS workflow.
+ *
+ * `modulatorTriage` selects up to 8 ChEMBL modulators for downstream
+ * fan-out; `drugsInClass` identifies clinically-advanced drugs in the
+ * class. Both are single-shot, structured-output LLM calls — no tools,
+ * no multi-step reasoning. Each function is `(input, deps) => Promise<CoverageEnvelope<...>>`.
+ *
+ * Coverage envelope is the failure mode: an LLM throw (non-402) → the
+ * function returns `coverage: "queried_no_data"`. A billing-gateway 402 reaches
+ * here as a `RunLlmStepResult` with `kind: "budget-exceeded"`; the caller
+ * stops scheduling because the workflow has self-cancelled.
+ */
+import { z } from "zod";
+import type { AgentSession } from "../../../auth/types.js";
+import type { AgentChat } from "../../../providers/types.js";
+import type { Phase1Bundle } from "../schemas.js";
+import { BUDGET_EXCEEDED_SENTINEL } from "../lib/llm-step.js";
+export declare const ModulatorTriageOutputSchema: z.ZodObject<{
+    shortlist: z.ZodArray<z.ZodObject<{
+        moleculeChemblId: z.ZodString;
+        preferredName: z.ZodString;
+        maxPhase: z.ZodNullable<z.ZodNumber>;
+        firstApproval: z.ZodNullable<z.ZodNumber>;
+        rationale: z.ZodString;
+    }, z.core.$strip>>;
+    notes: z.ZodString;
+    dropped_synonyms: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        chemblId: z.ZodString;
+        reason: z.ZodEnum<{
+            same_active_substance: "same_active_substance";
+            ambiguous_name_synonym: "ambiguous_name_synonym";
+        }>;
+        keptId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ModulatorTriageOutput = z.infer<typeof ModulatorTriageOutputSchema>;
+export declare const DrugsInClassOutputSchema: z.ZodObject<{
+    drugs: z.ZodArray<z.ZodObject<{
+        moleculeChemblId: z.ZodString;
+        preferredName: z.ZodString;
+        maxPhase: z.ZodNullable<z.ZodNumber>;
+        firstApproval: z.ZodNullable<z.ZodNumber>;
+        moleculeType: z.ZodNullable<z.ZodString>;
+        sources: z.ZodArray<z.ZodEnum<{
+            chembl: "chembl";
+            dgidb: "dgidb";
+            drugbank: "drugbank";
+        }>>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+export type DrugsInClassOutput = z.infer<typeof DrugsInClassOutputSchema>;
+interface CoverageAvailable<T> {
+    readonly coverage: "available";
+    readonly data: T;
+}
+interface CoverageQueriedNoData {
+    readonly coverage: "queried_no_data";
+    readonly error?: {
+        message: string;
+    };
+}
+type CoverageEnvelope<T> = CoverageAvailable<T> | CoverageQueriedNoData;
+export interface DecisionAgentDeps {
+    readonly chatProvider: AgentChat;
+    readonly session: AgentSession;
+    /** Billing-gateway model id — e.g. `env.TARGET_ASSESSMENT_DECISION_MODEL`. */
+    readonly model: string;
+    /** Attempt counter — bumped on resume so a 402-cancelled call lands a fresh DBOS step slot. */
+    readonly attempt: number;
+}
+export type ModulatorTriageResult = CoverageEnvelope<ModulatorTriageOutput & {
+    dropped_synonyms?: unknown;
+}> | {
+    readonly kind: "budget-exceeded";
+    readonly sentinel: typeof BUDGET_EXCEEDED_SENTINEL;
+};
+export declare function modulatorTriage(input: Phase1Bundle, deps: DecisionAgentDeps): Promise<ModulatorTriageResult>;
+export type DrugsInClassResult = CoverageEnvelope<DrugsInClassOutput> | {
+    readonly kind: "budget-exceeded";
+    readonly sentinel: typeof BUDGET_EXCEEDED_SENTINEL;
+};
+export declare function drugsInClass(input: Phase1Bundle, deps: DecisionAgentDeps): Promise<DrugsInClassResult>;
+export {};

package/dist/workflows/target-assessment/decisions/index.js

@@ -0,0 +1,127 @@
+/**
+ * Phase-2 decision functions for the harness DBOS workflow.
+ *
+ * `modulatorTriage` selects up to 8 ChEMBL modulators for downstream
+ * fan-out; `drugsInClass` identifies clinically-advanced drugs in the
+ * class. Both are single-shot, structured-output LLM calls — no tools,
+ * no multi-step reasoning. Each function is `(input, deps) => Promise<CoverageEnvelope<...>>`.
+ *
+ * Coverage envelope is the failure mode: an LLM throw (non-402) → the
+ * function returns `coverage: "queried_no_data"`. A billing-gateway 402 reaches
+ * here as a `RunLlmStepResult` with `kind: "budget-exceeded"`; the caller
+ * stops scheduling because the workflow has self-cancelled.
+ */
+import { z } from "zod";
+import { drugsInClassPrompt } from "../../../prompts/target-assessment/drugs-in-class.js";
+import { modulatorTriagePrompt } from "../../../prompts/target-assessment/modulator-triage.js";
+import { dedupModulatorsByParent } from "../lib/dedup-modulators.js";
+import { structuredLlmCall } from "../lib/structured-llm.js";
+// ── Output schemas ────────────────────────────────────────────────────
+export const ModulatorTriageOutputSchema = z.object({
+    shortlist: z.array(z.object({
+        moleculeChemblId: z.string(),
+        preferredName: z.string(),
+        maxPhase: z.number().nullable(),
+        firstApproval: z.number().nullable(),
+        rationale: z.string(),
+    })),
+    notes: z.string(),
+    dropped_synonyms: z
+        .array(z.object({
+        chemblId: z.string(),
+        reason: z.enum(["same_active_substance", "ambiguous_name_synonym"]),
+        keptId: z.string().nullable(),
+    }))
+        .default([]),
+});
+export const DrugsInClassOutputSchema = z.object({
+    drugs: z.array(z.object({
+        moleculeChemblId: z.string(),
+        preferredName: z.string(),
+        maxPhase: z.number().nullable(),
+        firstApproval: z.number().nullable(),
+        moleculeType: z.string().nullable(),
+        sources: z.array(z.enum(["chembl", "dgidb", "drugbank"])),
+    })),
+    total: z.number(),
+    truncated: z.boolean(),
+});
+function fail(message) {
+    return { coverage: "queried_no_data", error: { message } };
+}
+function failFromErr(err) {
+    return fail(err instanceof Error ? err.message : String(err));
+}
+export async function modulatorTriage(input, deps) {
+    const modulators = input.collectors.chemblModulators;
+    if (modulators.coverage !== "available" || modulators.data.modulators.length === 0) {
+        return fail("no modulators to triage");
+    }
+    const { kept, dropped } = dedupModulatorsByParent(modulators.data.modulators);
+    if (kept.length === 0) {
+        return fail("no modulators after dedup");
+    }
+    const prompt = [
+        `Target: ${input.resolved.geneSymbol} (${input.resolved.canonicalId})`,
+        `ChEMBL target id: ${modulators.data.targetChemblId ?? "unknown"}`,
+        ``,
+        `Modulators (${kept.length}, deduped from ${modulators.data.modulators.length}):`,
+        JSON.stringify(kept, null, 2),
+    ].join("\n");
+    try {
+        const result = await structuredLlmCall({
+            stepName: `ta-decision:modulator-triage:${deps.attempt}`,
+            agentId: "modulator-triage",
+            provider: deps.chatProvider,
+            session: deps.session,
+            system: modulatorTriagePrompt,
+            prompt,
+            schema: ModulatorTriageOutputSchema,
+            model: deps.model,
+        });
+        if (result.kind === "budget-exceeded") {
+            return { kind: "budget-exceeded", sentinel: result.sentinel };
+        }
+        return {
+            coverage: "available",
+            data: { ...result.value, dropped_synonyms: dropped },
+        };
+    }
+    catch (err) {
+        return failFromErr(err);
+    }
+}
+export async function drugsInClass(input, deps) {
+    const modulators = input.collectors.chemblModulators;
+    if (modulators.coverage !== "available" || modulators.data.modulators.length === 0) {
+        return fail("no modulators in class");
+    }
+    const { kept } = dedupModulatorsByParent(modulators.data.modulators);
+    if (kept.length === 0) {
+        return fail("no modulators after dedup");
+    }
+    const prompt = [
+        `Target: ${input.resolved.geneSymbol}`,
+        `ChEMBL modulators (max_phase ≥ 2, deduped by active substance):`,
+        JSON.stringify(kept, null, 2),
+    ].join("\n");
+    try {
+        const result = await structuredLlmCall({
+            stepName: `ta-decision:drugs-in-class:${deps.attempt}`,
+            agentId: "drugs-in-class",
+            provider: deps.chatProvider,
+            session: deps.session,
+            system: drugsInClassPrompt,
+            prompt,
+            schema: DrugsInClassOutputSchema,
+            model: deps.model,
+        });
+        if (result.kind === "budget-exceeded") {
+            return { kind: "budget-exceeded", sentinel: result.sentinel };
+        }
+        return { coverage: "available", data: result.value };
+    }
+    catch (err) {
+        return failFromErr(err);
+    }
+}

package/dist/workflows/target-assessment/fanout/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Phase-3 fan-out item functions for the harness DBOS workflow.
+ *
+ * Each function operates on one item (one modulator, one trial, one class
+ * drug) and returns a coverage envelope. The DBOS workflow body iterates
+ * the item list and dispatches each via `DBOS.runStep` with a deterministic
+ * step name `"ta-fanout:{kind}:{itemKey}"`. The `withHost` semaphore inside
+ * each body caps openFDA / ChEMBL / ctgov in-flight at 4.
+ *
+ * No throws — coverage envelope is the failure mode. Recovery replays the
+ * cached envelope from the DBOS step cache.
+ */
+import type { SerializedError } from "../coverage.js";
+import type { ClassDrugItem, PerClassDrugAEsItem } from "../steps/fanout/aes-for-one-class-drug-step.js";
+import type { PerTrialAEsItem, TrialItem } from "../steps/fanout/aes-for-one-trial-step.js";
+import type { ModulatorItem, PerModulatorFaersItem } from "../steps/fanout/faers-for-one-modulator-step.js";
+import type { PerModulatorPolypharmItem, PolypharmInputItem } from "../steps/fanout/polypharm-for-one-modulator-step.js";
+export type { ClassDrugItem, ModulatorItem, PerClassDrugAEsItem, PerModulatorFaersItem, PerModulatorPolypharmItem, PerTrialAEsItem, PolypharmInputItem, TrialItem, };
+type CoverageAvailable<T> = {
+    coverage: "available";
+    data: T;
+};
+type CoverageQueriedNoData = {
+    coverage: "queried_no_data";
+    error?: SerializedError;
+};
+type CoverageEnvelope<T> = CoverageAvailable<T> | CoverageQueriedNoData;
+export declare function faersForOneModulator(item: ModulatorItem): Promise<CoverageEnvelope<PerModulatorFaersItem>>;
+export declare function polypharmForOneModulator(item: PolypharmInputItem): Promise<CoverageEnvelope<PerModulatorPolypharmItem>>;
+export declare function aesForOneTrial(item: TrialItem): Promise<CoverageEnvelope<PerTrialAEsItem>>;
+export declare function aesForOneClassDrug(item: ClassDrugItem): Promise<CoverageEnvelope<PerClassDrugAEsItem>>;

package/dist/workflows/target-assessment/fanout/index.js

@@ -0,0 +1,155 @@
+/**
+ * Phase-3 fan-out item functions for the harness DBOS workflow.
+ *
+ * Each function operates on one item (one modulator, one trial, one class
+ * drug) and returns a coverage envelope. The DBOS workflow body iterates
+ * the item list and dispatches each via `DBOS.runStep` with a deterministic
+ * step name `"ta-fanout:{kind}:{itemKey}"`. The `withHost` semaphore inside
+ * each body caps openFDA / ChEMBL / ctgov in-flight at 4.
+ *
+ * No throws — coverage envelope is the failure mode. Recovery replays the
+ * cached envelope from the DBOS step cache.
+ */
+import { withHost } from "../../../lib/host-concurrency.js";
+import { getModulatorOnTargetPchembl, getModulatorPolypharmacology } from "../../../tools/lib/chembl-client.js";
+import { getTrialDetails } from "../../../tools/lib/clinical-trials-client.js";
+import { getFaersByDrug, getFaersSeriousness } from "../../../tools/lib/openfda-client.js";
+function fail(message) {
+    return { coverage: "queried_no_data", error: { message } };
+}
+function failFromErr(err) {
+    return fail(err instanceof Error ? err.message : String(err));
+}
+// ── Per-modulator FAERS ──────────────────────────────────────────────
+export async function faersForOneModulator(item) {
+    const probe = item.preferredName;
+    if (!probe) {
+        return fail(`no preferred name for ${item.moleculeChemblId}`);
+    }
+    try {
+        const [byDrug, seriousness] = await Promise.all([
+            withHost("openfda", () => getFaersByDrug(probe, { limit: 10 })),
+            withHost("openfda", () => getFaersSeriousness(probe)),
+        ]);
+        const total = byDrug.totalReports ?? 0;
+        if (total === 0 && byDrug.adverseEvents.length === 0) {
+            return fail(`FAERS returned no reports for ${probe}`);
+        }
+        if (seriousness !== null &&
+            seriousness.totalReports >= 1000 &&
+            seriousness.fatalCount === 0 &&
+            seriousness.hospitalizationCount === 0 &&
+            seriousness.lifeThreateningCount === 0 &&
+            seriousness.disablingCount === 0 &&
+            seriousness.congenitalAnomalyCount === 0 &&
+            seriousness.otherSeriousCount === 0) {
+            return fail(`FAERS seriousness all-zero across ${seriousness.totalReports} reports for ${probe}; openFDA seriousness fields not reliably populated`);
+        }
+        return {
+            coverage: "available",
+            data: {
+                moleculeChemblId: item.moleculeChemblId,
+                preferredName: probe,
+                totalReports: byDrug.totalReports ?? null,
+                topReactions: byDrug.adverseEvents,
+                seriousness,
+            },
+        };
+    }
+    catch (err) {
+        return failFromErr(err);
+    }
+}
+// ── Per-modulator polypharmacology ──────────────────────────────────
+export async function polypharmForOneModulator(item) {
+    try {
+        const [hits, primaryPchembl] = await Promise.all([
+            withHost("chembl", () => getModulatorPolypharmacology(item.moleculeChemblId, {
+                minPchembl: 5,
+                excludeTargetChemblId: item.primaryTargetChemblId ?? undefined,
+                limit: 200,
+            })),
+            item.primaryTargetChemblId
+                ? withHost("chembl", () => getModulatorOnTargetPchembl(item.moleculeChemblId, item.primaryTargetChemblId))
+                : Promise.resolve(null),
+        ]);
+        if (hits.length === 0) {
+            return fail(`no polypharm hits for ${item.moleculeChemblId}`);
+        }
+        return {
+            coverage: "available",
+            data: {
+                moleculeChemblId: item.moleculeChemblId,
+                preferredName: item.preferredName,
+                primaryPchembl,
+                hits: hits.map((h) => ({
+                    targetChemblId: h.targetChemblId,
+                    targetName: h.targetName,
+                    pchemblValue: h.pchemblValue,
+                    standardType: h.standardType,
+                    standardValue: h.standardValue,
+                    standardUnits: h.standardUnits,
+                })),
+            },
+        };
+    }
+    catch (err) {
+        return failFromErr(err);
+    }
+}
+// ── Per-trial AEs ────────────────────────────────────────────────────
+export async function aesForOneTrial(item) {
+    try {
+        const details = await withHost("ctgov", () => getTrialDetails(item.nctId));
+        if (!details) {
+            return fail(`no details for ${item.nctId}`);
+        }
+        if (details.adverseEvents.length === 0 && details.outcomes.length === 0) {
+            return fail(`no AE/outcome rows for ${item.nctId}`);
+        }
+        return {
+            coverage: "available",
+            data: {
+                nctId: item.nctId,
+                title: item.title,
+                whyStopped: details.whyStopped,
+                outcomes: details.outcomes,
+                groups: details.adverseEventGroups,
+                events: details.adverseEvents,
+            },
+        };
+    }
+    catch (err) {
+        return failFromErr(err);
+    }
+}
+// ── Per-class-drug AEs ───────────────────────────────────────────────
+export async function aesForOneClassDrug(item) {
+    const probe = item.preferredName;
+    if (!probe) {
+        return fail(`no preferred name for ${item.moleculeChemblId}`);
+    }
+    try {
+        const [byDrug, seriousness] = await Promise.all([
+            withHost("openfda", () => getFaersByDrug(probe, { limit: 10 })),
+            withHost("openfda", () => getFaersSeriousness(probe)),
+        ]);
+        const total = byDrug.totalReports ?? 0;
+        if (total === 0 && byDrug.adverseEvents.length === 0) {
+            return fail(`FAERS returned no reports for ${probe}`);
+        }
+        return {
+            coverage: "available",
+            data: {
+                moleculeChemblId: item.moleculeChemblId,
+                preferredName: probe,
+                totalReports: byDrug.totalReports ?? null,
+                topReactions: byDrug.adverseEvents,
+                seriousness,
+            },
+        };
+    }
+    catch (err) {
+        return failFromErr(err);
+    }
+}