@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,101 @@
+/**
+ * `executeTargetAssessment` — the parent DBOS workflow.
+ *
+ * Shape (every external interaction is a `DBOS.runStep` so a crashed
+ * workflow replays from the cache instead of repeating side effects):
+ *
+ *  Phase 0   `phase0Resolve`               — only step allowed to throw
+ *                                            (terminates → `target-unresolved`)
+ *  Phase 1   14 collectors in parallel     — coverage-envelope failures
+ *  Progress  `emitProgress("deciding")`
+ *  Phase 2   2 decisions in parallel       — LLM calls, attempt-numbered
+ *  Progress  `emitProgress("fanning_out")`
+ *  Phase 3   4 fan-out blocks in parallel  — per-item HTTP, withHost semaphore
+ *  Progress  `emitProgress("assembling")`
+ *  Phase 4   `phase4Assemble`              — deterministic
+ *  Progress  `emitProgress("synthesizing")`
+ *  Phase 5a  3 per-section syntheses in parallel
+ *  Phase 5b  `dossierRecommendation` sequential
+ *  Phase 5c  `phase5Persist` (pure)
+ *  Terminal  outermost try/finally:
+ *             - normal:           setDossier         → status="completed"
+ *             - phase0 throw:     markFailed         → "target-unresolved"
+ *             - schema violation: markFailed         → "schema-violation"
+ *             - other throw:      markFailed         → "unexpected-throw"
+ *             - 402 self-cancel:  markAssessmentSuspended → "suspended_insufficient_funds"
+ *             - operator cancel:  markFailed         → "operator-cancelled"
+ *             - soft-deleted row: no-op
+ *
+ * Workflow ID convention: `workflowID === assessmentId`. TA is one-shot
+ * (re-runs create new rows), so the workflowID equals the assessmentId
+ * directly. No `:runId` suffix.
+ */
+import type { Pool } from "pg";
+import { z } from "zod";
+import type { RunSession } from "../auth/types.js";
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { AgentChat } from "../providers/types.js";
+import { TargetAssessmentInputSchema } from "./target-assessment/schemas.js";
+import { type ProgressPhase } from "./target-assessment/progress.js";
+export declare const ExecuteTargetAssessmentInputSchema: z.ZodObject<{
+    assessmentId: z.ZodString;
+    target: z.ZodString;
+    goal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    organizationId: z.ZodString;
+    requestedBy: z.ZodString;
+    billingContextId: z.ZodString;
+}, z.core.$strip>;
+type SerializedInput = z.infer<typeof ExecuteTargetAssessmentInputSchema>;
+/**
+ * Workflow input includes the `runSession` minted at the trigger route.
+ * The schema is for the serialised wire shape (input persisted by DBOS);
+ * the `runSession` is added at the type level so the workflow body can
+ * read the run-authorization credential directly.
+ */
+export type ExecuteTargetAssessmentInput = SerializedInput & {
+    readonly runSession: RunSession;
+    /**
+     * True when Cortex owns the run-authorization lifecycle and therefore must
+     * revoke it on the terminal path. Optional because a workflow persisted
+     * before this field existed (recovered across the deploy that added it)
+     * deserializes without it; the body defaults absent → true, matching the
+     * prior Cortex-owned behavior.
+     */
+    readonly ownsMandate?: boolean;
+};
+export interface ExecuteTargetAssessmentResult {
+    readonly assessmentId: string;
+    readonly status: "completed" | "failed" | "suspended_insufficient_funds" | "deleted";
+    readonly bytes: number;
+}
+export interface ExecuteTargetAssessmentDeps {
+    readonly pool: Pool;
+    /** Run-authorization seam — the terminal path revokes through `revoke`. */
+    readonly runAuthorizer: RunAuthorizer;
+    /** NCBI E-utilities key for the ClinVar / PubMed Phase-1 collectors. */
+    readonly ncbiApiKey?: string;
+    /**
+     * Chat provider — billing resolution is closure-wrapped via the TA
+     * resolver in `harness/billing/target-assessment-resolver.ts` (see §12
+     * registration). The session's `scope.kind === "target-assessment"`
+     * carries the `billingContextId` the resolver keys on.
+     */
+    readonly chatProvider: AgentChat;
+    /** Billing-gateway model for decision agents — typically `env.TARGET_ASSESSMENT_DECISION_MODEL`. */
+    readonly decisionModel: string;
+    /** Billing-gateway model for synthesis agents — typically `env.TARGET_ASSESSMENT_SYNTHESIS_MODEL`. */
+    readonly synthesisModel: string;
+}
+/**
+ * Register the executeTargetAssessment workflow with DBOS. Caller is
+ * responsible for setting `workflowID = assessmentId` via
+ * `DBOS.startWorkflow(_, { workflowID })`.
+ */
+export declare function registerExecuteTargetAssessment(deps: ExecuteTargetAssessmentDeps): (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
+/**
+ * Body extracted so tests can drive it without registering a workflow
+ * (the DBOS calls inside still rely on a workflow context being present).
+ */
+export declare function runExecuteTargetAssessmentBody(input: ExecuteTargetAssessmentInput, deps: ExecuteTargetAssessmentDeps): Promise<ExecuteTargetAssessmentResult>;
+export { TargetAssessmentInputSchema };
+export type { ProgressPhase };

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

@@ -0,0 +1,528 @@
+/**
+ * `executeTargetAssessment` — the parent DBOS workflow.
+ *
+ * Shape (every external interaction is a `DBOS.runStep` so a crashed
+ * workflow replays from the cache instead of repeating side effects):
+ *
+ *  Phase 0   `phase0Resolve`               — only step allowed to throw
+ *                                            (terminates → `target-unresolved`)
+ *  Phase 1   14 collectors in parallel     — coverage-envelope failures
+ *  Progress  `emitProgress("deciding")`
+ *  Phase 2   2 decisions in parallel       — LLM calls, attempt-numbered
+ *  Progress  `emitProgress("fanning_out")`
+ *  Phase 3   4 fan-out blocks in parallel  — per-item HTTP, withHost semaphore
+ *  Progress  `emitProgress("assembling")`
+ *  Phase 4   `phase4Assemble`              — deterministic
+ *  Progress  `emitProgress("synthesizing")`
+ *  Phase 5a  3 per-section syntheses in parallel
+ *  Phase 5b  `dossierRecommendation` sequential
+ *  Phase 5c  `phase5Persist` (pure)
+ *  Terminal  outermost try/finally:
+ *             - normal:           setDossier         → status="completed"
+ *             - phase0 throw:     markFailed         → "target-unresolved"
+ *             - schema violation: markFailed         → "schema-violation"
+ *             - other throw:      markFailed         → "unexpected-throw"
+ *             - 402 self-cancel:  markAssessmentSuspended → "suspended_insufficient_funds"
+ *             - operator cancel:  markFailed         → "operator-cancelled"
+ *             - soft-deleted row: no-op
+ *
+ * Workflow ID convention: `workflowID === assessmentId`. TA is one-shot
+ * (re-runs create new rows), so the workflowID equals the assessmentId
+ * directly. No `:runId` suffix.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { z } from "zod";
+import { forSubAgent } from "../auth/types.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { resolveTarget } from "../tools/lib/identifier-resolver.js";
+import { TargetAssessmentInputSchema } from "./target-assessment/schemas.js";
+import { getAssessment, markAssessmentSuspended, markFailed, setDossier } from "../state/target-assessments.js";
+import { COLLECTOR_MANIFEST } from "./target-assessment/collectors/index.js";
+import { drugsInClass, modulatorTriage } from "./target-assessment/decisions/index.js";
+import { aesForOneClassDrug, aesForOneTrial, faersForOneModulator, polypharmForOneModulator, } from "./target-assessment/fanout/index.js";
+import { fetchApprovalPrecedents, pickIndicationForPrecedents, renderApprovalPrecedents } from "./target-assessment/lib/approval-precedents.js";
+import { readBudgetExceededMarker } from "./target-assessment/lib/llm-step.js";
+import { recordTerminalReason } from "./target-assessment/metrics.js";
+import { phase4Assemble } from "./target-assessment/phase4-assemble.js";
+import { DossierDerivedInvariantError, DossierSchemaViolationError, phase5Persist } from "./target-assessment/phase5-persist.js";
+import { emitProgress } from "./target-assessment/progress.js";
+import { dossierRecommendation, liabilityBullets, safetyFlagsTrail, translationalCommentary, } from "./target-assessment/synthesis/index.js";
+// ── Workflow input ───────────────────────────────────────────────────
+export const ExecuteTargetAssessmentInputSchema = z.object({
+    assessmentId: z.string(),
+    target: z.string(),
+    goal: z.string().nullable().optional(),
+    organizationId: z.string(),
+    requestedBy: z.string(),
+    billingContextId: z.string(),
+});
+// ── Helpers ──────────────────────────────────────────────────────────
+/**
+ * Derive a sub-agent session from the durable `RunSession`. Identity, scope,
+ * and the opaque `auth` capability come from the parent session — no synthetic
+ * envelopes.
+ */
+function buildSession(input, agentId) {
+    return {
+        ...input.runSession,
+        provenance: { agentId, callPath: [agentId] },
+    };
+}
+/**
+ * Type guard: any phase result carrying `{kind: "budget-exceeded"}` means
+ * the LLM step wrapper has already self-cancelled the workflow. The body
+ * should propagate the sentinel up the call chain so no downstream
+ * coverage envelope is fabricated for it.
+ */
+function isBudgetCancel(value) {
+    return typeof value === "object" && value !== null && "kind" in value && value.kind === "budget-exceeded";
+}
+function wrapCollectorThrow(err) {
+    return {
+        coverage: "queried_no_data",
+        error: { message: err instanceof Error ? err.message : String(err) },
+    };
+}
+/**
+ * Internal sentinel thrown by the workflow body when a 402 marker has
+ * been observed at a phase boundary — short-circuits the remaining
+ * phases and lands in the outermost catch, which sets `budgetExceeded`
+ * for the terminal dispatch.
+ */
+class BudgetExceededSkip extends Error {
+    constructor() {
+        super("budget exceeded — skipping remaining phases");
+        this.name = "BudgetExceededSkip";
+    }
+}
+// ── Workflow registration ────────────────────────────────────────────
+/**
+ * Register the executeTargetAssessment workflow with DBOS. Caller is
+ * responsible for setting `workflowID = assessmentId` via
+ * `DBOS.startWorkflow(_, { workflowID })`.
+ */
+export function registerExecuteTargetAssessment(deps) {
+    return DBOS.registerWorkflow(async (input) => {
+        return runExecuteTargetAssessmentBody(input, deps);
+    }, { name: "executeTargetAssessment" });
+}
+/**
+ * Body extracted so tests can drive it without registering a workflow
+ * (the DBOS calls inside still rely on a workflow context being present).
+ */
+export async function runExecuteTargetAssessmentBody(input, deps) {
+    // (§6.1) Outermost try/finally — every termination path dispatches the
+    // matching terminal handler. Phase 0 throws are caught here; every
+    // other phase wraps its body in coverage envelopes and does not throw.
+    // Budget-exceeded (billing-gateway 402) reaches here via `budgetExceeded` set
+    // when any LLM step returns the sentinel. The terminal block writes
+    // `status = "suspended_insufficient_funds"` via DBOS.runStep BEFORE
+    // materialising the cancel — the trailing `DBOS.cancelWorkflow` +
+    // `DBOS.runStep("self-cancel-budget-exceeded")` puts the workflow into
+    // CANCELLED status (the only state `DBOS.resumeWorkflow` replays).
+    // Ownership defaults to true for inputs persisted before the field existed
+    // (a workflow recovered across this deploy) — those were always Cortex-owned.
+    const authorization = {
+        runSession: input.runSession,
+        ownsMandate: input.ownsMandate ?? true, // oss-core-managed-ok
+    };
+    let phase0Error;
+    let schemaViolation;
+    let derivedViolation;
+    let unexpectedError;
+    let budgetExceeded = false;
+    let dossierForPersist;
+    let bytesForPersist = 0;
+    try {
+        // (§5.3, §6.3) Phase 0 — target resolution. The only legitimate throw
+        // site. On throw, the catch below records `phase0Error` and the
+        // terminal block dispatches `markFailed({kind: "target-unresolved"})`.
+        await emitProgress(deps.pool, input.assessmentId, "resolving");
+        const resolved = await DBOS.runStep(async () => {
+            const r = await resolveTarget(input.target);
+            return {
+                assessmentId: input.assessmentId,
+                goal: input.goal ?? null,
+                ...r,
+            };
+        }, { name: "ta-phase0-resolve" }).catch((err) => {
+            phase0Error = err;
+            throw err;
+        });
+        // (§5.4) Phase 1 — 14 collectors in parallel. Each is its own DBOS
+        // step; coverage failures cache as `queried_no_data` and replay
+        // returns the cached envelope. The per-collector run functions emit
+        // different bundle shapes; the union is widened to `unknown` here
+        // and `Phase1Bundle` is reconstructed by manifest key below.
+        await emitProgress(deps.pool, input.assessmentId, "collecting");
+        const manifest = COLLECTOR_MANIFEST;
+        const collectorCtx = { ncbiApiKey: deps.ncbiApiKey };
+        const collectorPairs = await Promise.all(manifest.map((entry) => DBOS.runStep(() => entry.run(resolved, collectorCtx), {
+            name: `ta-collector:${entry.id}`,
+        })
+            .catch((err) => wrapCollectorThrow(err))
+            .then((result) => [entry.id, result])));
+        const collectorById = Object.fromEntries(collectorPairs);
+        const phase1 = {
+            resolved,
+            collectors: {
+                opentargets: collectorById["opentargets"],
+                chemblModulators: collectorById["chembl-modulators"],
+                ctgov: collectorById["ctgov"],
+                faersByTarget: collectorById["faers-by-target"],
+                expressionHuman: collectorById["expression-human"],
+                expressionMultiSpecies: collectorById["expression-multi-species"],
+                clinvar: collectorById["clinvar"],
+                cbioportal: collectorById["cbioportal"],
+                impc: collectorById["impc"],
+                pubmedIndex: collectorById["pubmed-index"],
+                pathways: collectorById["pathways"],
+                stringPpi: collectorById["string-ppi"],
+                familyComplexes: collectorById["family-complexes"],
+                therapeuticPrograms: collectorById["therapeutic-programs"],
+            },
+        };
+        // (§5.5, §5.11) Phase 2 — decisions. Lazy billing resolution happens
+        // inside the chat provider's closure (TA-aware provider in §12). The
+        // session carries the `billingContextId` the provider reads from.
+        await emitProgress(deps.pool, input.assessmentId, "deciding");
+        const decisionSession = buildSession(input, "ta-decisions");
+        const [modulatorRes, drugsRes] = await Promise.all([
+            modulatorTriage(phase1, {
+                chatProvider: deps.chatProvider,
+                session: forSubAgent(decisionSession, "modulator-triage"),
+                model: deps.decisionModel,
+                attempt: 0,
+            }),
+            drugsInClass(phase1, {
+                chatProvider: deps.chatProvider,
+                session: forSubAgent(decisionSession, "drugs-in-class"),
+                model: deps.decisionModel,
+                attempt: 0,
+            }),
+        ]);
+        if (isBudgetCancel(modulatorRes) || isBudgetCancel(drugsRes)) {
+            // An LLM step already sent the budget-exceeded marker. Skip the
+            // remaining phases and fall through to the terminal block, which
+            // dispatches `markAssessmentSuspended` and materialises the cancel.
+            budgetExceeded = true;
+            throw new BudgetExceededSkip();
+        }
+        const phase2 = {
+            phase1,
+            decisions: {
+                modulatorTriage: modulatorRes,
+                failedTrialClassifier: {
+                    coverage: "not_loaded",
+                    reason: "deterministic in Phase 4 (classifyFailureReason)",
+                },
+                offTargetCurator: {
+                    coverage: "not_loaded",
+                    reason: "deterministic in Phase 4 (aggregateOffTargetPanel)",
+                },
+                drugsInClass: drugsRes,
+            },
+        };
+        // (§5.6) Phase 3 — fan-out blocks. Each block iterates items via
+        // Promise.all over DBOS.runStep; `withHost` semaphores inside each
+        // item function cap concurrency to 4 per host.
+        await emitProgress(deps.pool, input.assessmentId, "fanning_out");
+        const triage = phase2.decisions.modulatorTriage;
+        const triageShortlist = triage.coverage === "available"
+            ? triage.data.shortlist.map((m) => ({
+                moleculeChemblId: m.moleculeChemblId,
+                preferredName: m.preferredName,
+                maxPhase: m.maxPhase,
+                firstApproval: m.firstApproval,
+                rationale: m.rationale ?? "",
+            }))
+            : [];
+        const chembl = phase1.collectors.chemblModulators;
+        const primaryTargetChemblId = chembl.coverage === "available" ? chembl.data.targetChemblId : null;
+        const polypharmItems = triageShortlist.map((m) => ({
+            moleculeChemblId: m.moleculeChemblId,
+            preferredName: m.preferredName,
+            primaryTargetChemblId,
+        }));
+        const ctgov = phase1.collectors.ctgov;
+        const trialItems = [];
+        if (ctgov.coverage === "available") {
+            const seen = new Set();
+            for (const t of [...ctgov.data.failed, ...ctgov.data.active]) {
+                if (!t.nctId || seen.has(t.nctId))
+                    continue;
+                seen.add(t.nctId);
+                trialItems.push({ nctId: t.nctId, title: t.title });
+                if (trialItems.length >= 30)
+                    break;
+            }
+        }
+        const dic = phase2.decisions.drugsInClass;
+        const classDrugItems = dic.coverage === "available"
+            ? dic.data.drugs.map((d) => ({
+                moleculeChemblId: d.moleculeChemblId,
+                preferredName: d.preferredName,
+                maxPhase: d.maxPhase,
+                firstApproval: d.firstApproval,
+            }))
+            : [];
+        async function runFanoutBlock(items, stepKindForName, keyOf, fn) {
+            return Promise.all(items.map((item) => DBOS.runStep(() => fn(item), {
+                name: `ta-fanout:${stepKindForName}:${keyOf(item)}`,
+            }).catch((err) => wrapCollectorThrow(err))));
+        }
+        const [perModulatorFaersResults, perTrialAesResults, perModulatorPolypharmResults, perClassDrugAesResults] = await Promise.all([
+            runFanoutBlock(triageShortlist, "modulator-faers", (item) => item.moleculeChemblId, faersForOneModulator),
+            runFanoutBlock(trialItems, "trial-aes", (item) => item.nctId, aesForOneTrial),
+            runFanoutBlock(polypharmItems, "modulator-polypharm", (item) => item.moleculeChemblId, polypharmForOneModulator),
+            runFanoutBlock(classDrugItems, "class-drug-aes", (item) => item.moleculeChemblId, aesForOneClassDrug),
+        ]);
+        const phase3 = {
+            phase2,
+            fanout: {
+                perModulatorFaers: { results: perModulatorFaersResults },
+                perTrialAes: { results: perTrialAesResults },
+                perModulatorPolypharm: { results: perModulatorPolypharmResults },
+                perClassDrugAes: { results: perClassDrugAesResults },
+            },
+        };
+        // (§5.7) Phase 4 — deterministic assembly. Single DBOS step.
+        await emitProgress(deps.pool, input.assessmentId, "assembling");
+        const phase4 = await DBOS.runStep(() => phase4Assemble(deps.pool, phase3), { name: "ta-phase4-assemble" });
+        // (§5.8-pre) Approval-precedent grounding — one deterministic openFDA
+        // lookup, rendered to markdown and injected into every synthesis prompt.
+        // A precedent-lookup failure must NOT fail the whole assessment: a fetch
+        // throw degrades to a "no precedents" block.
+        const approvalPrecedents = await DBOS.runStep(async () => {
+            const indication = pickIndicationForPrecedents(phase4.dossier);
+            let result = null;
+            if (indication !== null) {
+                try {
+                    result = await fetchApprovalPrecedents({ indication });
+                }
+                catch (err) {
+                    console.warn(`[ta-approval-precedents] openFDA lookup failed for "${indication}": ${err instanceof Error ? err.message : err}`);
+                    result = null;
+                }
+            }
+            return renderApprovalPrecedents(indication, result);
+        }, { name: "ta-approval-precedents" });
+        // (§5.8) Phase 5 — three per-section syntheses in parallel.
+        await emitProgress(deps.pool, input.assessmentId, "synthesizing");
+        const synthesisDeps = (agentId) => ({
+            chatProvider: deps.chatProvider,
+            session: { ...buildSession(input, agentId) },
+            model: deps.synthesisModel,
+            attempt: 0,
+            approvalPrecedents,
+        });
+        const [bulletsRes, flagsRes, commentaryRes] = await Promise.all([
+            liabilityBullets(phase4, synthesisDeps("liability-bullets")),
+            safetyFlagsTrail(phase4, synthesisDeps("safety-flags-trail")),
+            translationalCommentary(phase4, synthesisDeps("translational-commentary")),
+        ]);
+        if (isBudgetCancel(bulletsRes) || isBudgetCancel(flagsRes) || isBudgetCancel(commentaryRes)) {
+            budgetExceeded = true;
+            throw new BudgetExceededSkip();
+        }
+        // (§5.9) Phase 5b — sequential dossier-recommendation step.
+        const recommendationRes = await dossierRecommendation({
+            phase4,
+            perSection: {
+                liabilityBullets: bulletsRes,
+                safetyFlagsTrail: flagsRes,
+                translationalCommentary: commentaryRes,
+            },
+        }, synthesisDeps("dossier-recommendation"));
+        if (isBudgetCancel(recommendationRes)) {
+            budgetExceeded = true;
+            throw new BudgetExceededSkip();
+        }
+        // (§5.10) Phase 5c — pure persist function. The DB write moves to
+        // the terminal handler below; this step validates the v5 dossier
+        // and returns the persisted-shape bundle. Schema/derived violations
+        // throw and the terminal handler dispatches to `markFailed`.
+        const persisted = await DBOS.runStep(() => phase5Persist({
+            assessmentId: input.assessmentId,
+            phase4Dossier: phase4.dossier,
+            phase2,
+            synthesis: {
+                bullets: bulletsRes,
+                flags: flagsRes,
+                commentary: commentaryRes,
+                recommendation: recommendationRes,
+            },
+        }), { name: "ta-phase5-persist" });
+        dossierForPersist = persisted.dossier;
+        bytesForPersist = persisted.bytes;
+    }
+    catch (err) {
+        if (err instanceof BudgetExceededSkip) {
+            // Already classified; the terminal block reads `budgetExceeded`.
+        }
+        else if (err instanceof DossierSchemaViolationError) {
+            schemaViolation = err;
+        }
+        else if (err instanceof DossierDerivedInvariantError) {
+            derivedViolation = err;
+        }
+        else if (phase0Error === undefined) {
+            unexpectedError = err;
+        }
+        // phase0Error is already set if it came from the Phase-0 catch above.
+    }
+    // (§6.1, §6.8) Terminal block. Read the row first; if soft-deleted,
+    // no-op (the user's delete during the run wins).
+    const row = await DBOS.runStep(async () => unwrapOrThrow(await getAssessment(deps.pool, input.assessmentId, input.organizationId)), {
+        name: "ta-terminal-read-row",
+    });
+    if (row?.status === "deleted") {
+        recordTerminalReason("deleted");
+        return {
+            assessmentId: input.assessmentId,
+            status: "deleted",
+            bytes: 0,
+        };
+    }
+    // (§6.2) Normal completion — happy path wrote `dossierForPersist`.
+    if (!phase0Error && !schemaViolation && !derivedViolation && !unexpectedError && !budgetExceeded && dossierForPersist) {
+        try {
+            await DBOS.runStep(async () => unwrapOrThrow(await setDossier(deps.pool, input.assessmentId, dossierForPersist)), {
+                name: "ta-terminal-completed",
+            });
+            await emitProgress(deps.pool, input.assessmentId, "completed");
+        }
+        catch (err) {
+            console.error(`[ta-terminal] setDossier failed for ${input.assessmentId}: ${err instanceof Error ? err.message : err}`);
+        }
+        await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-completed");
+        recordTerminalReason("completed");
+        return {
+            assessmentId: input.assessmentId,
+            status: "completed",
+            bytes: bytesForPersist,
+        };
+    }
+    // (§6.3) Phase 0 throw — target unresolved.
+    if (phase0Error) {
+        await DBOS.runStep(async () => unwrapOrThrow(await markFailed(deps.pool, input.assessmentId, {
+            kind: "target-unresolved",
+            message: phase0Error instanceof Error ? phase0Error.message : String(phase0Error),
+        })), { name: "ta-terminal-failed-resolve" });
+        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
+        recordTerminalReason("target-unresolved");
+        return {
+            assessmentId: input.assessmentId,
+            status: "failed",
+            bytes: 0,
+        };
+    }
+    // (§6.4) Schema violation.
+    if (schemaViolation) {
+        await DBOS.runStep(async () => unwrapOrThrow(await markFailed(deps.pool, input.assessmentId, {
+            kind: "schema-invariant-violation",
+            message: schemaViolation.message,
+            details: schemaViolation.issues,
+        })), { name: "ta-terminal-failed-schema" });
+        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
+        recordTerminalReason("schema-violation");
+        return {
+            assessmentId: input.assessmentId,
+            status: "failed",
+            bytes: bytesForPersist,
+        };
+    }
+    // (§6.4 — derived invariant variant — same terminal class, different kind.)
+    if (derivedViolation) {
+        await DBOS.runStep(async () => unwrapOrThrow(await markFailed(deps.pool, input.assessmentId, {
+            kind: "derived-invariant-violation",
+            message: derivedViolation.message,
+        })), { name: "ta-terminal-failed-derived" });
+        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
+        recordTerminalReason("derived-invariant-violation");
+        return {
+            assessmentId: input.assessmentId,
+            status: "failed",
+            bytes: bytesForPersist,
+        };
+    }
+    // (§6.6) Budget exceeded — drain the marker for telemetry, flip the
+    // row to `suspended_insufficient_funds`, then materialise the cancel.
+    // The trailing `DBOS.cancelWorkflow` + `DBOS.runStep` puts the
+    // workflow into CANCELLED status (the only state `DBOS.resumeWorkflow`
+    // will replay; SUCCESS / ERROR are terminal).
+    if (budgetExceeded) {
+        await DBOS.runStep(() => readBudgetExceededMarker(), {
+            name: "ta-terminal-drain-marker",
+        }).catch(() => null);
+        await DBOS.runStep(async () => unwrapOrThrow(await markAssessmentSuspended(deps.pool, input.assessmentId)), { name: "ta-terminal-suspended" });
+        await emitProgress(deps.pool, input.assessmentId, "suspended");
+        await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-canceled");
+        const workflowId = DBOS.workflowID;
+        if (workflowId) {
+            await DBOS.cancelWorkflow(workflowId);
+            // Force one more durable hop so the cancel materialises before the
+            // body returns — without this trailing runStep the workflow would
+            // land SUCCESS in some DBOS versions because the body completed
+            // without re-entering the SDK after the cancel call.
+            await DBOS.runStep(async () => undefined, {
+                name: "ta-self-cancel-budget-exceeded",
+            });
+        }
+        recordTerminalReason("suspended-on-402");
+        return {
+            assessmentId: input.assessmentId,
+            status: "suspended_insufficient_funds",
+            bytes: 0,
+        };
+    }
+    // (§6.5) Unexpected throw — bug somewhere, coverage envelope failed.
+    if (unexpectedError) {
+        await DBOS.runStep(async () => unwrapOrThrow(await markFailed(deps.pool, input.assessmentId, {
+            kind: "unexpected-throw",
+            message: unexpectedError instanceof Error ? unexpectedError.message : String(unexpectedError),
+        })), { name: "ta-terminal-failed-unexpected" });
+        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
+        recordTerminalReason("unexpected-throw");
+        return {
+            assessmentId: input.assessmentId,
+            status: "failed",
+            bytes: 0,
+        };
+    }
+    // Defensive: this branch is unreachable in practice (one of the
+    // categories above must have fired). Fall through to a generic failed
+    // status so a buggy refactor surfaces visibly.
+    await DBOS.runStep(async () => unwrapOrThrow(await markFailed(deps.pool, input.assessmentId, {
+        kind: "unexpected-throw",
+        message: "terminal block reached without classified outcome",
+    })), { name: "ta-terminal-failed-uncategorized" });
+    recordTerminalReason("unexpected-throw");
+    return {
+        assessmentId: input.assessmentId,
+        status: "failed",
+        bytes: 0,
+    };
+}
+/**
+ * Best-effort revoke wrapped in a durableStep for replay idempotency. This
+ * wrapper swallows any runStep-level error so a terminal path is never
+ * aborted by a transient revoke failure.
+ */
+async function revokeRunAuthorizationSafe(deps, authorization, reason) {
+    try {
+        await DBOS.runStep(() => deps.runAuthorizer.revoke(authorization, reason), {
+            name: `ta-revoke-run-auth:${reason}`,
+        });
+    }
+    catch (err) {
+        console.warn(`[execute-target-assessment] revokeRunAuthorization (${reason}) failed:`, err instanceof Error ? err.message : err);
+    }
+}
+// Re-export the canonical TA input schema (consumers and the managed root
+// validate against this shape on the trigger route).
+export { TargetAssessmentInputSchema };

package/dist/workflows/metrics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Workflow-side OTel metrics → Middleware.io.
+ *
+ * Two signals so 3-hour runs and pause-resume cascades are observable:
+ *   - cortex.workflow.parent.cancelled_children — counter, incremented once
+ *     per child the fail-fast or pause cascade reaps. A baseline near 0
+ *     means runs land cleanly; a spike means siblings keep colliding with
+ *     a single failing step.
+ *   - cortex.workflow.stream.bytes               — counter, incremented by
+ *     the byte count of every UI part written onto the DBOS stream. The
+ *     leading indicator for 3-hour stream growth is monotonic — a runaway
+ *     emitter shows up as an unbounded slope.
+ *
+ * Instruments are lazy so the workflow body binds to whichever
+ * `MeterProvider` is globally registered at startup.
+ */
+/**
+ * Record one child cancellation. The parent calls this once per
+ * `DBOS.cancelWorkflow(childWorkflowId)` in the cascade (fail-fast OR
+ * pause). `cause` distinguishes the two so dashboards can split the
+ * counter.
+ */
+export declare function recordCancelledChild(args: {
+    readonly cause: "fail_fast" | "budget_exceeded" | "external_cancel";
+}): void;
+/**
+ * Record one UI-part write. `bytes` is the serialised JSON size of the
+ * part as it lands on the stream; `kind` is the part `type` for
+ * dashboarding. The workflow body wraps its `DBOS.writeStream` call site
+ * so a single emitter records once per part.
+ */
+export declare function recordStreamWrite(args: {
+    readonly bytes: number;
+    readonly kind: string;
+}): void;
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export declare function __resetWorkflowMetricsForTest(): void;