@inflexa-ai/harness 0.1.1

package/dist/workflows/target-assessment/phase4-assemble.js

@@ -0,0 +1,39 @@
+/**
+ * Phase 4 — deterministic dossier assembly.
+ *
+ * Pure function over a Phase-3 bundle. Calls `assembleDossier` (~3.5K LOC
+ * of pure compute) and returns the assembled `DossierV4Body`. The Phase-5
+ * synthesis sections (translational commentary, liability bullets, safety-
+ * flags trail) are stamped by the Phase-5 persist step after this step
+ * completes.
+ *
+ * The DBOS workflow body wraps this in `DBOS.runStep({name: "phase4-assemble"})`
+ * so recovery on a fresh replica replays the cached output without re-running
+ * the ~1-3 sec compute.
+ *
+ * `assembleDossier` accepts an optional `ClinicalConsequenceAnnotatorDeps`
+ * bundle that is threaded through to `annotateOffTargetPanel`. For the
+ * DBOS workflow the parameter is undefined — the annotator falls back to
+ * its DB cache + no-LLM path. Threading a real deps bundle (provider +
+ * session + model) through Phase-4 is a follow-up tracked in §17 cleanup.
+ */
+import { DossierV4BodySchema } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import { z } from "zod";
+import { assembleDossier } from "./assemblers/index.js";
+import { Phase3BundleSchema } from "./steps/phase3-aggregate.js";
+export const Phase4OutputSchema = z.object({
+    assessmentId: z.string(),
+    dossier: DossierV4BodySchema,
+});
+export { Phase3BundleSchema };
+/**
+ * Run Phase 4 — assemble the v4 dossier body from the Phase-3 bundle.
+ * Deterministic over its inputs; safely cached on DBOS replay.
+ */
+export async function phase4Assemble(pool, phase3) {
+    const dossier = await assembleDossier(pool, phase3.phase2, phase3, undefined);
+    return {
+        assessmentId: phase3.phase2.phase1.resolved.assessmentId,
+        dossier,
+    };
+}

package/dist/workflows/target-assessment/phase5-persist.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Phase 5 — stamps the four Phase-5 synthesis outputs into the Phase-4 dossier,
+ * runs the deterministic refinement passes (coverage-qualifier reconcile,
+ * no-liabilities disclosure rewrite, recommendation citation validation +
+ * demotion, recommendation quality gates), upgrades the v4 body to v5,
+ * computes derived fields, and validates against `DossierV5Schema`.
+ *
+ * The DB write (`setDossier` / `markFailed`) lives in the workflow's terminal
+ * handler in §6. This module returns the validated dossier instead of writing it.
+ * Typed throws (`DossierSchemaViolationError`, `DossierDerivedInvariantError`)
+ * let the terminal handler dispatch to `markFailed` with the matching `error.kind`.
+ *
+ * The direction-of-effect audit (`auditCitationDirections`) is NOT called here —
+ * it requires an LLM and is not on the PR #4 critical path. Follow-up tracked
+ * in §17 if a harness-native audit pipeline is wired.
+ */
+import { z } from "zod";
+import { type DossierV4Body } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import type { Phase2Bundle } from "./steps/phase2-aggregate.js";
+import type { DossierRecommendationStepOutput, LiabilityBulletsStepOutput, SafetyFlagsTrailStepOutput, TranslationalCommentaryStepOutput } from "./synthesis/index.js";
+export declare class DossierSchemaViolationError extends Error {
+    readonly issues: readonly unknown[];
+    constructor(message: string, issues: readonly unknown[]);
+}
+export declare class DossierDerivedInvariantError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export interface Phase5PersistInput {
+    readonly assessmentId: string;
+    readonly phase4Dossier: DossierV4Body;
+    readonly phase2: Phase2Bundle;
+    readonly synthesis: {
+        readonly bullets: LiabilityBulletsStepOutput;
+        readonly flags: SafetyFlagsTrailStepOutput;
+        readonly commentary: TranslationalCommentaryStepOutput;
+        readonly recommendation: DossierRecommendationStepOutput;
+    };
+}
+export declare const Phase5PersistResultSchema: z.ZodObject<{
+    assessmentId: z.ZodString;
+    dossier: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+export interface Phase5PersistResult {
+    readonly assessmentId: string;
+    readonly dossier: Record<string, unknown>;
+    readonly bytes: number;
+}
+/**
+ * Run Phase-5 persist as a pure function. Returns the validated v5
+ * dossier (and computed bytes) on success. Throws
+ * `DossierDerivedInvariantError` when `computeDerivedFields` rejects the
+ * dossier; throws `DossierSchemaViolationError` when the v5 schema
+ * rejects the final dossier.
+ */
+export declare function phase5Persist(input: Phase5PersistInput): Promise<Phase5PersistResult>;

package/dist/workflows/target-assessment/phase5-persist.js

@@ -0,0 +1,461 @@
+/**
+ * Phase 5 — stamps the four Phase-5 synthesis outputs into the Phase-4 dossier,
+ * runs the deterministic refinement passes (coverage-qualifier reconcile,
+ * no-liabilities disclosure rewrite, recommendation citation validation +
+ * demotion, recommendation quality gates), upgrades the v4 body to v5,
+ * computes derived fields, and validates against `DossierV5Schema`.
+ *
+ * The DB write (`setDossier` / `markFailed`) lives in the workflow's terminal
+ * handler in §6. This module returns the validated dossier instead of writing it.
+ * Typed throws (`DossierSchemaViolationError`, `DossierDerivedInvariantError`)
+ * let the terminal handler dispatch to `markFailed` with the matching `error.kind`.
+ *
+ * The direction-of-effect audit (`auditCitationDirections`) is NOT called here —
+ * it requires an LLM and is not on the PR #4 critical path. Follow-up tracked
+ * in §17 if a harness-native audit pipeline is wired.
+ */
+import { z } from "zod";
+import { DossierV5Schema, } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import { getDrugPrimaryTargetUniprots } from "../../tools/lib/chembl-client.js";
+import { deterministicTranslationalCommentary } from "./assemblers/index.js";
+import { validateRecommendationCitations } from "./lib/citation-validator.js";
+import { classifyClinicalEvidenceTrial } from "./lib/clinical-evidence-attribution.js";
+import { computeDerivedFields } from "./lib/compute-derived.js";
+import { detectStructuralEvidenceConflicts } from "./lib/evidence-conflict-detector.js";
+import { applyRecommendationQualityGates } from "./lib/recommendation-quality-gates.js";
+import { sanitizeRecommendation } from "./lib/recommendation-sanitizer.js";
+import { resolveFamilySiblingUniprots } from "./lib/target-identity-filter.js";
+const SOFT_CAP_BYTES = 16 * 1024 * 1024;
+// ── Typed throws — handled in §6 terminal handler ────────────────────
+export class DossierSchemaViolationError extends Error {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = "DossierSchemaViolationError";
+    }
+}
+export class DossierDerivedInvariantError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "DossierDerivedInvariantError";
+    }
+}
+export const Phase5PersistResultSchema = z.object({
+    assessmentId: z.string(),
+    dossier: z.record(z.string(), z.unknown()),
+    bytes: z.number(),
+});
+// ── Internal helpers ─────────────────────────────────────────────────
+function approximateSize(d) {
+    return Buffer.byteLength(JSON.stringify(d), "utf-8");
+}
+function truncateOversize(d) {
+    const next = structuredClone(d);
+    const ta = next.reference_biology.therapeutic_area_associations;
+    if (ta.coverage === "available" && ta.data.rows.length > 50) {
+        ta.data.rows = ta.data.rows.slice(0, 50);
+        ta.truncated = true;
+    }
+    const ind = next.indications;
+    if (ind.coverage === "available" && ind.data.rows.length > 25) {
+        ind.data.rows = ind.data.rows.slice(0, 25);
+        ind.truncated = true;
+    }
+    const ppi = next.reference_biology.ppi_network;
+    if (ppi.coverage === "available" && ppi.data.partners.length > 50) {
+        ppi.data.partners = ppi.data.partners.slice(0, 50);
+        ppi.truncated = true;
+    }
+    return next;
+}
+function pickCommentarySeverity(row) {
+    const blob = `${row.predicate} ${row.commentary}`.toLowerCase();
+    if (row.topic === "ko_phenotype" && /pre[- ]?weaning|embryonic|lethal/i.test(blob)) {
+        return "caution";
+    }
+    if (row.topic === "expression_translation" && /(≥|>=|two[- ]?step|2[- ]?step|diverge|divergence|rank.*differ)/i.test(blob)) {
+        return "caution";
+    }
+    if (/queried.+(no data|no calls|empty|no tissue)/i.test(blob)) {
+        return "gap";
+    }
+    return "ok";
+}
+function stampSynthesis(phase4Dossier, syn, phase2) {
+    const next = structuredClone(phase4Dossier);
+    if (syn.bullets.coverage === "available") {
+        next.liability_summary.liability_bullets = syn.bullets.data.bullets.map((b) => ({ text: b.text, rationale: b.rationale, category: b.category }));
+    }
+    if (syn.flags.coverage === "available" && syn.flags.data.flags.length > 0) {
+        next.safety_profile.target_organ_liabilities = syn.flags.data.flags;
+    }
+    const deterministicAll = deterministicTranslationalCommentary(phase2);
+    const deterministicSorted = [...deterministicAll].sort((a, b) => {
+        const order = { caution: 0, gap: 1, ok: 2 };
+        return order[a.severity] - order[b.severity];
+    });
+    const deterministic = deterministicSorted.slice(0, 4);
+    const agentRows = syn.commentary.coverage === "available"
+        ? syn.commentary.data.rows.slice(0, 4).map((r) => ({
+            severity: pickCommentarySeverity(r),
+            text: `${r.predicate}. ${r.commentary}`,
+        }))
+        : [];
+    const allRows = [...deterministic, ...agentRows].slice(0, 8);
+    if (allRows.length > 0) {
+        next.reference_biology.preclinical.translational_commentary = {
+            coverage: "available",
+            data: { rows: allRows },
+        };
+    }
+    else if (syn.commentary.coverage === "queried_no_data") {
+        next.reference_biology.preclinical.translational_commentary = {
+            coverage: "queried_no_data",
+            error: syn.commentary.error,
+        };
+    }
+    const recommendation = syn.recommendation.coverage === "available"
+        ? {
+            coverage: "available",
+            data: sanitizeRecommendation(syn.recommendation.data),
+        }
+        : {
+            coverage: "queried_no_data",
+            error: syn.recommendation.error,
+        };
+    next.executive_recommendation = recommendation;
+    if (syn.flags.coverage !== "available" && next.executive_recommendation.coverage === "available") {
+        const qual = next.executive_recommendation.data.coverage_qualifier;
+        if (qual) {
+            if (!qual.sections_unavailable.includes("safety_profile.target_organ_liabilities")) {
+                qual.sections_unavailable.push("safety_profile.target_organ_liabilities");
+            }
+            const errorKind = syn.flags.error?.kind ?? "unavailable";
+            const annotation = `The deterministic safety-flag audit trail was not generated for this dossier (synthesis step \`safety-flags-trail\` failed with \`${errorKind}\`); the safety-bullet citations below are not anchored to a per-flag audit row.`;
+            qual.note = qual.note ? `${annotation} ${qual.note}` : annotation;
+        }
+    }
+    const diagnostics = [syn.bullets.diagnostic, syn.flags.diagnostic, syn.commentary.diagnostic, syn.recommendation.diagnostic];
+    next.analytics.synthesis_diagnostics = {
+        coverage: "available",
+        data: { rows: diagnostics },
+    };
+    if (syn.recommendation.coverage === "available") {
+        try {
+            const audit = validateRecommendationCitations(syn.recommendation.data, next);
+            if (audit.citations_unresolved.length > 0) {
+                console.warn(`[phase5-persist] recommendation_audit: ${audit.citations_unresolved.length} unresolved citation(s)`);
+            }
+            next.analytics.recommendation_audit = {
+                coverage: "available",
+                data: audit,
+            };
+        }
+        catch (err) {
+            next.analytics.recommendation_audit = {
+                coverage: "queried_no_data",
+                error: { message: err instanceof Error ? err.message : String(err) },
+            };
+        }
+    }
+    return next;
+}
+function applyCitationAuditDemotion(rec, audit) {
+    const flagged = audit.citations_unresolved.filter((u) => u.surface === "organ_claim_without_probe_pass");
+    if (flagged.length === 0)
+        return rec;
+    const flaggedExcerpts = flagged.map((f) => ("excerpt" in f ? f.excerpt : ""));
+    const keptRisks = [];
+    const demotedTexts = new Set();
+    for (const risk of rec.key_risks) {
+        const isFlagged = flaggedExcerpts.some((excerpt) => excerpt.length > 0 && risk.includes(excerpt.slice(0, Math.min(80, excerpt.length))));
+        if (isFlagged) {
+            demotedTexts.add(risk);
+        }
+        else {
+            keptRisks.push(risk);
+        }
+    }
+    const unverified = flagged.map((f) => ({
+        text: [...demotedTexts].find((t) => "excerpt" in f && t.includes(f.excerpt.slice(0, Math.min(80, f.excerpt.length)))) ?? ("excerpt" in f ? f.excerpt : ""),
+        bullet_category: f.bullet_category,
+        surface: "organ_claim_without_probe_pass",
+    }));
+    return {
+        ...rec,
+        key_risks: keptRisks,
+        coverage_qualifier: {
+            ...rec.coverage_qualifier,
+            unverified_bullets: unverified,
+        },
+    };
+}
+function rewriteNoLiabilitiesDisclosure(dossier) {
+    const ls = dossier.liability_summary;
+    if (!ls)
+        return;
+    const bullets = Array.isArray(ls.liability_bullets)
+        ? ls.liability_bullets
+        : [];
+    const current = String(ls.no_liabilities_disclosure ?? "");
+    if (current.startsWith("insufficient safety data"))
+        return;
+    const m = current.match(/(\d+) of 4 safety data sources returned data/);
+    if (!m)
+        return;
+    const N = m[1];
+    if (bullets.length === 0) {
+        ls.no_liabilities_disclosure =
+            `${N} of 4 safety data sources returned data; no class-level liabilities synthesised`;
+    }
+    else {
+        ls.no_liabilities_disclosure =
+            `${bullets.length} liabilities identified across ${N} of 4 safety data sources`;
+    }
+}
+function resolveSection(dossier, path) {
+    let cur = dossier;
+    for (const part of path.split(".")) {
+        if (cur == null || typeof cur !== "object")
+            return { resolved: false };
+        cur = cur[part];
+    }
+    if (cur === undefined)
+        return { resolved: false };
+    const coverage = cur && typeof cur === "object" && typeof cur.coverage === "string" ? cur.coverage : undefined;
+    return { resolved: true, coverage };
+}
+function reconcileCoverageQualifier(dossier) {
+    const cq = dossier.executive_recommendation
+        ?.data?.coverage_qualifier;
+    if (!cq || !Array.isArray(cq.sections_unavailable))
+        return;
+    cq.sections_unavailable = cq.sections_unavailable.filter((entry) => {
+        const path = String(entry).split(" (")[0].trim();
+        const { resolved, coverage } = resolveSection(dossier, path);
+        if (!resolved)
+            return false;
+        return coverage !== "available";
+    });
+}
+function makeUnknownAttribution(reason) {
+    return {
+        relationship: "unknown",
+        evidence_role: "excluded",
+        basis: [{ kind: "text_match", source: "legacy-v4-upgrade" }],
+        resolved_interventions: [],
+        exclusion_reason: reason,
+    };
+}
+async function buildAttributionContext(phase2, knownClassDrugsBase, therapeuticPrograms) {
+    const ctgov = phase2.phase1.collectors.ctgov.coverage === "available"
+        ? [...phase2.phase1.collectors.ctgov.data.active, ...phase2.phase1.collectors.ctgov.data.failed]
+        : [];
+    const assessmentUniprot = phase2.phase1.resolved.ids?.uniprot ?? "";
+    const geneSymbol = phase2.phase1.resolved.geneSymbol ?? "";
+    const [familyUniprots, resolvedDrugs] = await Promise.all([
+        assessmentUniprot || geneSymbol ? resolveFamilySiblingUniprots(assessmentUniprot || geneSymbol) : Promise.resolve([]),
+        Promise.all(knownClassDrugsBase.map(async (drug) => {
+            const resolved = drug.moleculeChemblId ? await getDrugPrimaryTargetUniprots(drug.moleculeChemblId).catch(() => []) : [];
+            const targetUniprots = resolved.length > 0 ? resolved : assessmentUniprot ? [assessmentUniprot] : [];
+            return { ...drug, targetUniprots };
+        })),
+    ]);
+    return {
+        byNct: new Map(ctgov.map((trial) => [trial.nctId, trial])),
+        classifyOpts: {
+            assessmentSymbol: geneSymbol,
+            assessmentUniprot,
+            familyUniprots,
+            knownClassDrugs: resolvedDrugs,
+            therapeuticPrograms,
+        },
+    };
+}
+function attachAttribution(row, ctx) {
+    const source = ctx.byNct.get(row.nct_id);
+    const classified = source
+        ? classifyClinicalEvidenceTrial(source, ctx.classifyOpts)
+        : {
+            attribution: makeUnknownAttribution("No normalized CT.gov source row was available for this legacy row."),
+            eligible_for_toxicology_aggregation: false,
+        };
+    return {
+        ...row,
+        attribution: classified.attribution,
+        eligible_for_toxicology_aggregation: classified.eligible_for_toxicology_aggregation,
+    };
+}
+function upgradeTrialRows(rows, ctx) {
+    const kept = [];
+    const excluded = [];
+    for (const row of rows) {
+        const upgraded = attachAttribution(row, ctx);
+        if (upgraded.eligible_for_toxicology_aggregation)
+            kept.push(upgraded);
+        else
+            excluded.push(upgraded);
+    }
+    return { rows: kept, excluded_rows: excluded };
+}
+function normalizeRegulatoryActionRows(rows) {
+    return rows.map((row) => {
+        if (row.source_kind)
+            return row;
+        const action_kind = row.action_kind;
+        const agency = row.agency;
+        const source_kind = action_kind === "black_box"
+            ? "boxed_warning"
+            : action_kind === "REMS"
+                ? "rems"
+                : action_kind === "withdrawal"
+                    ? "withdrawal"
+                    : agency === "EMA"
+                        ? "referral"
+                        : "label_warning";
+        return {
+            ...row,
+            source_kind,
+            action_kind: source_kind === "label_warning" && action_kind === "safety_communication" ? "label_warning" : action_kind,
+            source_date: row.action_date,
+        };
+    });
+}
+async function upgradeDossierToV5(body, phase2) {
+    const next = structuredClone(body);
+    next.schema_version = "5";
+    const drugInteractions = next.drug_interactions;
+    const knownClassDrugsBase = drugInteractions?.coverage === "available"
+        ? (drugInteractions.data?.rows ?? []).map((row) => ({
+            name: String(row.drug_name ?? ""),
+            moleculeChemblId: row.drug_id ?? null,
+        }))
+        : [];
+    const tpCollector = phase2.phase1.collectors.therapeuticPrograms;
+    const therapeuticPrograms = tpCollector?.coverage === "available"
+        ? tpCollector.data.programs.map((program) => ({
+            programId: program.programId,
+            name: program.name,
+            targetSymbol: program.targetSymbol,
+            targetUniprot: program.targetUniprot,
+            modality: program.modality,
+            nctIds: program.nctIds,
+        }))
+        : [];
+    const attributionCtx = await buildAttributionContext(phase2, knownClassDrugsBase, therapeuticPrograms);
+    const cd = next.clinical_development;
+    if (cd?.trials?.coverage === "available") {
+        const upgraded = upgradeTrialRows(cd.trials.data.rows, attributionCtx);
+        cd.trials.data.rows = upgraded.rows;
+        cd.trials.data.excluded_rows = [...(cd.trials.data.excluded_rows ?? []), ...upgraded.excluded_rows];
+    }
+    if (cd?.failed_trials?.coverage === "available") {
+        const upgraded = upgradeTrialRows(cd.failed_trials.data.rows, attributionCtx);
+        cd.failed_trials.data.rows = upgraded.rows;
+        cd.failed_trials.data.excluded_rows = [...(cd.failed_trials.data.excluded_rows ?? []), ...upgraded.excluded_rows];
+    }
+    if (cd?.outcomes?.coverage === "available") {
+        cd.outcomes.data.rows = cd.outcomes.data.rows.map((row) => attachAttribution(row, attributionCtx));
+    }
+    const analytics = next.analytics;
+    if (analytics?.discovery_trials?.coverage === "available") {
+        const upgraded = upgradeTrialRows(analytics.discovery_trials.data.rows, attributionCtx);
+        analytics.discovery_trials.data.rows = upgraded.rows;
+        analytics.discovery_trials.data.excluded_rows = [...(analytics.discovery_trials.data.excluded_rows ?? []), ...upgraded.excluded_rows];
+        delete analytics.discovery_trials.data.related_target_trials;
+        delete analytics.discovery_trials.data.related_receptor;
+    }
+    const sp = next.safety_profile;
+    const regulatory = sp?.regulatory_actions;
+    if (regulatory?.coverage === "available") {
+        regulatory.data.rows = normalizeRegulatoryActionRows(regulatory.data.rows ?? []);
+    }
+    next.analytics.quality_gates ??= {
+        coverage: "available",
+        data: { rows: [] },
+    };
+    return next;
+}
+// ── Pure-function entry point ────────────────────────────────────────
+/**
+ * Run Phase-5 persist as a pure function. Returns the validated v5
+ * dossier (and computed bytes) on success. Throws
+ * `DossierDerivedInvariantError` when `computeDerivedFields` rejects the
+ * dossier; throws `DossierSchemaViolationError` when the v5 schema
+ * rejects the final dossier.
+ */
+export async function phase5Persist(input) {
+    // The dossier rides through this function as an untyped working blob; the
+    // `as unknown as DossierV{4,5}Body` casts below are version-shim views that
+    // let the typed helpers operate on it. None of these casts is load-bearing
+    // for soundness: `DossierV5Schema.safeParse(fullDossier)` at the end is the
+    // single validation gate, and it throws before anything is returned.
+    let dossier = stampSynthesis(input.phase4Dossier, input.synthesis, input.phase2);
+    // Demote organ-claim flagged bullets into coverage_qualifier.unverified_bullets.
+    const exec = dossier.executive_recommendation;
+    if (exec?.coverage === "available") {
+        const audit = dossier.analytics.recommendation_audit?.data;
+        if (audit && exec.data) {
+            dossier.executive_recommendation.data = applyCitationAuditDemotion(exec.data, audit);
+        }
+    }
+    reconcileCoverageQualifier(dossier);
+    rewriteNoLiabilitiesDisclosure(dossier);
+    dossier = (await upgradeDossierToV5(dossier, input.phase2));
+    const recommendationAudit = dossier.analytics.recommendation_audit?.data;
+    const synthesisDiagnostics = dossier.analytics.synthesis_diagnostics?.coverage ===
+        "available"
+        ? dossier.analytics.synthesis_diagnostics.data.rows
+        : [];
+    const trials = dossier.clinical_development
+        .trials;
+    const hasDirectClinicalEvidence = trials?.coverage === "available" && (trials.data.rows ?? []).some((row) => row.eligible_for_toxicology_aggregation === true);
+    const gated = applyRecommendationQualityGates({
+        executive_recommendation: dossier.executive_recommendation,
+        synthesis_diagnostics: synthesisDiagnostics,
+        recommendation_audit: recommendationAudit,
+        has_direct_clinical_evidence: hasDirectClinicalEvidence,
+    });
+    dossier.executive_recommendation = gated.executive_recommendation;
+    const qg = dossier.analytics.quality_gates;
+    dossier.analytics.quality_gates = {
+        coverage: "available",
+        data: {
+            rows: [...(qg?.data?.rows ?? []), ...gated.quality_gates],
+        },
+    };
+    let bytes = approximateSize(dossier);
+    if (bytes > SOFT_CAP_BYTES) {
+        dossier = truncateOversize(dossier);
+        bytes = approximateSize(dossier);
+    }
+    let derived;
+    try {
+        derived = computeDerivedFields(dossier);
+    }
+    catch (err) {
+        throw new DossierDerivedInvariantError(err instanceof Error ? err.message : String(err), err);
+    }
+    const fullDossier = { ...dossier, derived };
+    const structuralConflicts = detectStructuralEvidenceConflicts(fullDossier);
+    if (structuralConflicts.length > 0) {
+        const existing = fullDossier.analytics.evidence_conflicts;
+        const existingRows = existing?.coverage === "available" ? (existing.data?.rows ?? []) : [];
+        fullDossier.analytics.evidence_conflicts = {
+            coverage: "available",
+            data: { rows: [...existingRows, ...structuralConflicts] },
+        };
+    }
+    const parsed = DossierV5Schema.safeParse(fullDossier);
+    if (!parsed.success) {
+        throw new DossierSchemaViolationError("Dossier failed v5 schema validation", parsed.error.issues);
+    }
+    return {
+        assessmentId: input.assessmentId,
+        dossier: parsed.data,
+        bytes,
+    };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Progress emission for the target-assessment DBOS workflow.
+ *
+ * Emits a typed `data-target-assessment-progress` part via
+ * `DBOS.writeStream("progress", part)` and updates `cortex_target_assessments.progress`.
+ * Both writes happen inside a `DBOS.runStep` so a recovered workflow does not
+ * duplicate the event.
+ *
+ * Wire shape: `TargetAssessmentProgressEventSchema` in
+ * `harness/src/contracts/target-dossier.ts`. The SSE route reads via
+ * `DBOS.readStream(workflowId, "progress")` and folds-on-read by `phase`.
+ */
+import type { Pool } from "pg";
+import type { TargetAssessmentPhase, TargetAssessmentProgressEvent } from "@inflexa-ai/harness/contracts/target-dossier.js";
+/** DBOS stream key the SSE route reads via `DBOS.readStream(wfId, "progress")`. */
+export declare const TA_PROGRESS_STREAM_KEY = "progress";
+export type ProgressPhase = TargetAssessmentPhase;
+/**
+ * Wire shape of one progress event. Matches the harness's contracts
+ * `TargetAssessmentProgressEventSchema`. Wrapped in a typed chat part
+ * envelope by the SSE route on the way out.
+ */
+export interface ProgressPart {
+    readonly type: "data-target-assessment-progress";
+    readonly payload: TargetAssessmentProgressEvent;
+}
+export declare const PROGRESS_PERCENTS: Record<ProgressPhase, number>;
+export declare const PROGRESS_MESSAGES: Record<ProgressPhase, string>;
+/**
+ * Emit one progress transition. MUST be called from inside the workflow
+ * body — the `DBOS.runStep` wrapper makes it replay-safe (DBOS persists
+ * the stream-write offset under `(workflowID, function_id)`; replay
+ * returns cached without re-writing the part).
+ *
+ * Best-effort: a DB or stream failure logs and continues — progress
+ * emission MUST NOT block the workflow.
+ */
+export declare function emitProgress(pool: Pool, assessmentId: string, phase: ProgressPhase): Promise<void>;

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

@@ -0,0 +1,76 @@
+/**
+ * Progress emission for the target-assessment DBOS workflow.
+ *
+ * Emits a typed `data-target-assessment-progress` part via
+ * `DBOS.writeStream("progress", part)` and updates `cortex_target_assessments.progress`.
+ * Both writes happen inside a `DBOS.runStep` so a recovered workflow does not
+ * duplicate the event.
+ *
+ * Wire shape: `TargetAssessmentProgressEventSchema` in
+ * `harness/src/contracts/target-dossier.ts`. The SSE route reads via
+ * `DBOS.readStream(workflowId, "progress")` and folds-on-read by `phase`.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { describeDbError } from "../../lib/db-result.js";
+import { updateProgress } from "../../state/target-assessments.js";
+/** DBOS stream key the SSE route reads via `DBOS.readStream(wfId, "progress")`. */
+export const TA_PROGRESS_STREAM_KEY = "progress";
+export const PROGRESS_PERCENTS = {
+    resolving: 5,
+    collecting: 25,
+    deciding: 55,
+    fanning_out: 70,
+    assembling: 85,
+    synthesizing: 90,
+    completed: 100,
+    failed: 100,
+    suspended: 100,
+};
+export const PROGRESS_MESSAGES = {
+    resolving: "Resolving target identity",
+    collecting: "Collecting evidence from 14 data sources",
+    deciding: "Triaging modulators and classifying trials",
+    fanning_out: "Building per-modulator and per-trial detail",
+    assembling: "Assembling dossier sections",
+    synthesizing: "Drafting safety and translational commentary",
+    completed: "Completed",
+    failed: "Failed",
+    suspended: "Suspended — insufficient funds",
+};
+/**
+ * Emit one progress transition. MUST be called from inside the workflow
+ * body — the `DBOS.runStep` wrapper makes it replay-safe (DBOS persists
+ * the stream-write offset under `(workflowID, function_id)`; replay
+ * returns cached without re-writing the part).
+ *
+ * Best-effort: a DB or stream failure logs and continues — progress
+ * emission MUST NOT block the workflow.
+ */
+export async function emitProgress(pool, assessmentId, phase) {
+    const message = PROGRESS_MESSAGES[phase];
+    const percent = PROGRESS_PERCENTS[phase];
+    await DBOS.runStep(async () => {
+        const part = {
+            type: "data-target-assessment-progress",
+            payload: { phase, message, percent, at: new Date().toISOString() },
+        };
+        try {
+            await DBOS.writeStream(TA_PROGRESS_STREAM_KEY, part);
+        }
+        catch (err) {
+            console.warn(`[ta-progress] writeStream failed for ${assessmentId} (${phase}): ${err instanceof Error ? err.message : err}`);
+        }
+        // The "suspended" phase is owned by the terminal handler
+        // (`markAssessmentSuspended` already set status + progress text). A
+        // row write here would either race or overwrite the suspended status.
+        if (phase !== "suspended") {
+            const rowStatus = phase === "completed" ? "completed" : phase === "failed" ? "failed" : "running";
+            // Best-effort: log a failed row write and continue — progress
+            // emission MUST NOT block the workflow. `updateProgress` returns
+            // its DB failure as an `Err`, so handle both branches here.
+            (await updateProgress(pool, assessmentId, message, rowStatus)).match(() => { }, (error) => {
+                console.warn(`[ta-progress] updateProgress failed for ${assessmentId} (${phase}): ${describeDbError(error)}`);
+            });
+        }
+    }, { name: `ta-progress:${phase}` });
+}