@inflexa-ai/harness 0.35.8 → 0.36.1

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

@@ -1,39 +0,0 @@
-/**
- * Phase 4 — dossier assembly.
- *
- * Calls `assembleDossier` (~3.5K LOC of aggregation over the Phase-3 bundle)
- * and returns the assembled `DossierBody`. The safety-corroboration and
- * claim-investigation sections are stamped by the workflow body between this
- * step and synthesis; the Phase-5 synthesis sections (translational commentary,
- * liability bullets, safety-flags trail) are stamped by the Phase-5 persist
- * step.
- *
- * 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 compute. Replay caching earns its keep here because `annotatorDeps`
- * carries the per-row clinical-consequence annotator's LLM seam: assembly makes
- * bounded model calls for off-target rows that have no cached annotation. Those
- * calls are per-row best-effort — a failure leaves the row's original fallback —
- * and their results are cached in Postgres, so a repeat assessment of the same
- * target reaches them without an LLM call at all.
- */
-import { DossierBodySchema } 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: DossierBodySchema,
-});
-export { Phase3BundleSchema };
-/**
- * Run Phase 4 — assemble the dossier body from the Phase-3 bundle.
- * Safely cached on DBOS replay; the caller supplies the annotator seam.
- */
-export async function phase4Assemble(pool, phase3, annotatorDeps, logger) {
-    const dossier = await assembleDossier(pool, phase3.phase2, phase3, annotatorDeps, logger);
-    return {
-        assessmentId: phase3.phase2.phase1.resolved.assessmentId,
-        dossier,
-    };
-}

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

@@ -1,59 +0,0 @@
-/**
- * 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), computes derived fields, and
- * validates against `DossierSchema`.
- *
- * The DB write (`setDossier` / `markFailed`) belongs to the workflow's terminal
- * handler; this module returns the validated dossier instead of writing it.
- * Typed throws (`DossierSchemaViolationError`, `DossierDerivedInvariantError`)
- * let that handler dispatch to `markFailed` with the matching `error.kind`.
- *
- * Every pass here is deterministic. The direction-of-effect audit
- * (`auditCitationDirections`) is not among them because it needs an LLM call,
- * and this module runs after synthesis has closed.
- */
-import type { Logger } from "../../lib/logger.js";
-import { type DossierBody } from "@inflexa-ai/harness/contracts/target-dossier.js";
-import type { OrganSignalProjection } from "./lib/fda-label-safety.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 {
-    /** Operational logging seam; omitted falls back to no-op. */
-    readonly logger?: Logger;
-    readonly assessmentId: string;
-    readonly phase4Dossier: DossierBody;
-    readonly phase2: Phase2Bundle;
-    /**
-     * Per-organ signals segmented from the FDA labels the approval-precedent
-     * step fetched. Null when no indication resolved and no label was queried.
-     */
-    readonly regulatoryOrganSignals: OrganSignalProjection | null;
-    readonly synthesis: {
-        readonly bullets: LiabilityBulletsStepOutput;
-        readonly flags: SafetyFlagsTrailStepOutput;
-        readonly commentary: TranslationalCommentaryStepOutput;
-        readonly recommendation: DossierRecommendationStepOutput;
-    };
-}
-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 dossier (and
- * computed bytes) on success. Throws `DossierDerivedInvariantError` when
- * `computeDerivedFields` rejects the dossier; throws
- * `DossierSchemaViolationError` when the schema rejects the final dossier.
- */
-export declare function phase5Persist(input: Phase5PersistInput): Promise<Phase5PersistResult>;

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

@@ -1,349 +0,0 @@
-/**
- * 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), computes derived fields, and
- * validates against `DossierSchema`.
- *
- * The DB write (`setDossier` / `markFailed`) belongs to the workflow's terminal
- * handler; this module returns the validated dossier instead of writing it.
- * Typed throws (`DossierSchemaViolationError`, `DossierDerivedInvariantError`)
- * let that handler dispatch to `markFailed` with the matching `error.kind`.
- *
- * Every pass here is deterministic. The direction-of-effect audit
- * (`auditCitationDirections`) is not among them because it needs an LLM call,
- * and this module runs after synthesis has closed.
- */
-import { createNoopLogger } from "../../lib/console-logger.js";
-import { DossierSchema, } from "@inflexa-ai/harness/contracts/target-dossier.js";
-import { assembleRegulatoryOrganSignals, deterministicTranslationalCommentary } from "./assemblers/index.js";
-import { validateRecommendationCitations } from "./lib/citation-validator.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";
-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";
-    }
-}
-// ── 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";
-}
-const CITED_PMID_RE = /\bPMID[:\s]?(\d{6,9})\b/gi;
-/**
- * A synthesised claim stands on the papers it cites. One that cites none says
- * so — a section path is a pointer into this dossier, not a record a reader
- * can independently check.
- */
-function supportFromCitedPmids(text, reasonWhenUncited) {
-    const pmids = [...new Set([...text.matchAll(CITED_PMID_RE)].map((m) => m[1]))];
-    if (pmids.length === 0)
-        return { state: "unknown", reason: reasonWhenUncited };
-    return { state: "scored", evidence: pmids.map((pmid) => ({ pmid, source: "pubmed" })) };
-}
-function stampSynthesis(logger, phase4Dossier, syn, phase2, regulatoryOrganSignals) {
-    const next = structuredClone(phase4Dossier);
-    next.safety_profile.regulatory_organ_signals = assembleRegulatoryOrganSignals(regulatoryOrganSignals);
-    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,
-            support: supportFromCitedPmids(`${b.text} ${b.rationale} ${b.evidence_pointer}`, `bullet cites ${b.evidence_pointer} rather than a paper`),
-        }));
-    }
-    if (syn.flags.coverage === "available" && syn.flags.data.flags.length > 0) {
-        next.safety_profile.target_organ_liabilities = {
-            coverage: "available",
-            data: {
-                rows: syn.flags.data.flags.map((f) => ({
-                    organ: f.organ,
-                    severity: f.severity,
-                    trail: f.trail,
-                    mechanism_hypothesis: f.mechanism_hypothesis,
-                    support: supportFromCitedPmids(f.trail, "the audit trail is assembled from dossier sections and cites no paper"),
-                })),
-            },
-        };
-    }
-    else if (syn.flags.coverage === "queried_no_data") {
-        next.safety_profile.target_organ_liabilities = { coverage: "queried_no_data", error: syn.flags.error };
-    }
-    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) {
-                logger.warn("recommendation_audit: unresolved citation(s)", {
-                    unresolvedCount: audit.citations_unresolved.length,
-                    unresolved: audit.citations_unresolved,
-                });
-            }
-            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";
-    });
-}
-// ── Pure-function entry point ────────────────────────────────────────
-/**
- * Run Phase-5 persist as a pure function. Returns the validated dossier (and
- * computed bytes) on success. Throws `DossierDerivedInvariantError` when
- * `computeDerivedFields` rejects the dossier; throws
- * `DossierSchemaViolationError` when the schema rejects the final dossier.
- */
-export async function phase5Persist(input) {
-    const logger = (input.logger ?? createNoopLogger()).named("phase5-persist").with({ assessmentId: input.assessmentId });
-    // The dossier rides through this function as an untyped working blob; the
-    // `as unknown as DossierBody` casts below let the typed helpers operate on
-    // it. None of these casts is load-bearing for soundness:
-    // `DossierSchema.safeParse(fullDossier)` at the end is the single
-    // validation gate, and it throws before anything is returned.
-    let dossier = stampSynthesis(logger, input.phase4Dossier, input.synthesis, input.phase2, input.regulatoryOrganSignals);
-    // 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);
-    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 = DossierSchema.safeParse(fullDossier);
-    if (!parsed.success) {
-        throw new DossierSchemaViolationError("Dossier failed schema validation", parsed.error.issues);
-    }
-    return {
-        assessmentId: input.assessmentId,
-        dossier: parsed.data,
-        bytes,
-    };
-}

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

@@ -1,75 +0,0 @@
-/**
- * TargetAssessmentProgressStream — the read side of a target assessment's
- * durable progress stream.
- *
- * `emitProgress` (the sibling `progress.ts`) writes one part per phase
- * transition and nothing reads it back, so an embedder that wants to show a
- * user how far an assessment has got had to reach for the durability engine
- * itself. This seam is that read, and it quarantines the engine the way
- * `RunLauncher` does for starting workflows: the delivered value is the
- * harness's own `TargetAssessmentProgressEvent` contract type, and no engine
- * type appears in the exported signature.
- *
- * It is far simpler than `execution/run-event-stream.ts`, and deliberately so.
- * A run fans out over a parent workflow and every sandbox-step child, each
- * writing its own stream, so that seam polls a ledger to discover children and
- * folds reconciling parts before delivery. A target assessment writes progress
- * from the parent body alone, under `workflowID === assessmentId`. One stream,
- * no discovery, no pool.
- *
- * It is a push subscription rather than a returned iterator because handing the
- * engine's async generator back to a caller would put the engine's model on the
- * very surface this seam exists to remove, and would leave nowhere to contain a
- * failure. A handler gives both, and matches the `EmitFn` idiom the writer side
- * already speaks.
- */
-import { type TargetAssessmentProgressEvent } from "@inflexa-ai/harness/contracts/target-dossier.js";
-import type { Logger } from "../../lib/logger.js";
-/**
- * Construction-time dependencies. The logger is where every contained failure
- * is reported, and defaults to silence so an embedder that wired none sees
- * nothing rather than having console forced on it.
- */
-export interface TargetAssessmentProgressStreamDeps {
-    readonly logger?: Logger;
-}
-/**
- * Receives one progress event. May be async — the subscription awaits it, so a
- * handler is never invoked concurrently with itself. A throw is logged and
- * swallowed.
- */
-export type TargetAssessmentProgressHandler = (event: TargetAssessmentProgressEvent) => void | Promise<void>;
-/** Call-time parameters of one subscription. */
-export interface TargetAssessmentProgressSubscribeOptions {
-    /** The assessment to observe. Also the workflow's id — TA sets the two equal. */
-    readonly assessmentId: string;
-    /** Where each delivered event goes. */
-    readonly onEvent: TargetAssessmentProgressHandler;
-    /** Aborting stops delivery and settles the returned promise. */
-    readonly signal: AbortSignal;
-}
-/**
- * The progress read seam. One method, because an assessment-scoped subscription
- * is the whole capability — a general-purpose stream reader would leak the
- * engine's model back into the surface this exists to quarantine.
- */
-export interface TargetAssessmentProgressStream {
-    /**
-     * Deliver every progress event the assessment produces to `onEvent`,
-     * resolving when the assessment's stream drains or when the signal aborts.
-     *
-     * The stream drains when the workflow stops being active. A workflow that
-     * self-cancels on a 402 is no longer active, so the stream drains at the
-     * `suspended` phase and this settles there — it does NOT wait for a later
-     * `DBOS.resumeWorkflow`. Re-opening across a resume would mean polling the
-     * row's status, which is the caller's business, not this seam's.
-     *
-     * Events arrive in the order the workflow wrote them, each exactly once.
-     * There is no fold: the body emits each phase once and the engine caches a
-     * step's stream-write offset, so a recovered workflow does not re-write one.
-     * A fold would collapse nothing and cost a buffer.
-     */
-    subscribe(options: TargetAssessmentProgressSubscribeOptions): Promise<void>;
-}
-/** Build the DBOS-backed realization of {@link TargetAssessmentProgressStream}. */
-export declare function createTargetAssessmentProgressStream(deps?: TargetAssessmentProgressStreamDeps): TargetAssessmentProgressStream;

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

@@ -1,110 +0,0 @@
-/**
- * TargetAssessmentProgressStream — the read side of a target assessment's
- * durable progress stream.
- *
- * `emitProgress` (the sibling `progress.ts`) writes one part per phase
- * transition and nothing reads it back, so an embedder that wants to show a
- * user how far an assessment has got had to reach for the durability engine
- * itself. This seam is that read, and it quarantines the engine the way
- * `RunLauncher` does for starting workflows: the delivered value is the
- * harness's own `TargetAssessmentProgressEvent` contract type, and no engine
- * type appears in the exported signature.
- *
- * It is far simpler than `execution/run-event-stream.ts`, and deliberately so.
- * A run fans out over a parent workflow and every sandbox-step child, each
- * writing its own stream, so that seam polls a ledger to discover children and
- * folds reconciling parts before delivery. A target assessment writes progress
- * from the parent body alone, under `workflowID === assessmentId`. One stream,
- * no discovery, no pool.
- *
- * It is a push subscription rather than a returned iterator because handing the
- * engine's async generator back to a caller would put the engine's model on the
- * very surface this seam exists to remove, and would leave nowhere to contain a
- * failure. A handler gives both, and matches the `EmitFn` idiom the writer side
- * already speaks.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { TargetAssessmentProgressEventSchema } from "@inflexa-ai/harness/contracts/target-dossier.js";
-import { createNoopLogger } from "../../lib/console-logger.js";
-import { TA_PROGRESS_STREAM_KEY } from "./progress.js";
-/**
- * Shape `emitProgress` writes. The `data-target-assessment-progress` key is not
- * in the chat-part registry — it is the writer's private envelope — so the
- * payload, not the envelope, is what a caller gets.
- */
-function readEvent(value) {
-    if (typeof value !== "object" || value === null)
-        return null;
-    const parsed = TargetAssessmentProgressEventSchema.safeParse(value.payload);
-    return parsed.success ? parsed.data : null;
-}
-/** Build the DBOS-backed realization of {@link TargetAssessmentProgressStream}. */
-export function createTargetAssessmentProgressStream(deps = {}) {
-    const baseLogger = (deps.logger ?? createNoopLogger()).named("ta-progress-stream");
-    return {
-        async subscribe({ assessmentId, onEvent, signal }) {
-            const logger = baseLogger.with({ assessmentId });
-            let resolveAbort;
-            const aborted = new Promise((resolve) => {
-                resolveAbort = resolve;
-            });
-            const generator = DBOS.readStream(assessmentId, TA_PROGRESS_STREAM_KEY);
-            // The engine's reader exposes no cancellation: while it waits on a
-            // quiet-but-active workflow it is suspended inside an await, where a
-            // queued `return()` is only honoured once it next reaches a yield.
-            // Teardown is therefore best-effort by construction, and the read's
-            // own promise is raced against the signal rather than waiting on it.
-            const onAbort = () => {
-                resolveAbort();
-                void generator.return(undefined).catch(() => {
-                    /* the read is already being abandoned */
-                });
-            };
-            if (signal.aborted)
-                onAbort();
-            else
-                signal.addEventListener("abort", onAbort, { once: true });
-            const read = (async () => {
-                try {
-                    for (;;) {
-                        const next = await generator.next();
-                        // Checked after the read, not before: `next()` is what
-                        // notices the workflow going inactive, and an aborted
-                        // subscription must deliver nothing further.
-                        if (next.done === true || signal.aborted)
-                            return;
-                        const event = readEvent(next.value);
-                        if (event === null) {
-                            logger.debug("dropped a stream value outside the progress contract");
-                            continue;
-                        }
-                        try {
-                            await onEvent(event);
-                        }
-                        catch (err) {
-                            logger.warn("progress handler threw", { phase: event.phase, ...logger.errorFields(err) });
-                        }
-                    }
-                }
-                catch (err) {
-                    // Observation is a diagnostic channel: `emitProgress` already
-                    // treats a failed write as best-effort so a lost frame cannot
-                    // fail the workflow. A read that propagated here would be
-                    // strictly less robust than the writer it observes.
-                    logger.error("progress stream read failed", logger.errorFields(err));
-                }
-                finally {
-                    void generator.return(undefined).catch(() => {
-                        /* already finished, or abandoned under abort */
-                    });
-                }
-            })();
-            try {
-                await Promise.race([read, aborted]);
-            }
-            finally {
-                signal.removeEventListener("abort", onAbort);
-            }
-        },
-    };
-}

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

@@ -1,39 +0,0 @@
-/**
- * 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";
-import type { Logger } from "../../lib/logger.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, logger: Logger, assessmentId: string, phase: ProgressPhase): Promise<void>;