stageflow 0.40.0 → 0.44.0

package/dist/evals/read/results.js

@@ -0,0 +1,107 @@
+import { mean, passFraction, percentile } from "../stats.js";
+import { EXECUTED_RESULT_STATUSES, resultKey } from "../statsTypes.js";
+export const RESULT_ROW_STATUSES = ["passed", "failed", "errored", "flaky"];
+function caseField(c, key) {
+    return c ? c.case[key] : undefined;
+}
+function buildFacts(caseRow, caseId, results, reviews, targetKind) {
+    const sorted = [...results].sort((a, b) => a.repeatIndex - b.repeatIndex);
+    const executedResults = sorted.filter((r) => EXECUTED_RESULT_STATUSES.includes(r.status));
+    const completed = executedResults.filter((r) => r.status === "completed");
+    const failedGraders = new Set();
+    const failureTags = new Set();
+    let cost = 0;
+    for (const r of sorted) {
+        cost += r.costUsd ?? 0;
+        for (const g of r.grades)
+            cost += g.judgeCostUsd ?? 0;
+        for (const tag of reviews.get(resultKey(caseId, r.repeatIndex))?.tags ?? [])
+            failureTags.add(tag);
+    }
+    for (const r of executedResults) {
+        for (const g of r.grades) {
+            if (g.status === "error" || g.passed === false)
+                failedGraders.add(g.graderId);
+        }
+    }
+    const passed = executedResults.filter((r) => r.passed).length;
+    const latencies = completed
+        .map((r) => r.latencyMs)
+        .filter((v) => v !== null)
+        .sort((a, b) => a - b);
+    const turns = executedResults.flatMap((r) => (r.turns !== null ? [r.turns] : []));
+    const toolCalls = executedResults.flatMap((r) => (r.toolCallCount !== null ? [r.toolCallCount] : []));
+    const agentData = targetKind === "agent" || turns.length > 0 || toolCalls.length > 0;
+    const title = caseField(caseRow, "title");
+    const tags = caseField(caseRow, "tags") ?? [];
+    return {
+        executed: executedResults.length,
+        passed,
+        errored: executedResults.some((r) => r.status !== "completed"),
+        haystack: [caseId, title ?? "", JSON.stringify(caseField(caseRow, "input") ?? {})].join("\n").toLowerCase(),
+        row: {
+            case_id: caseId,
+            position: caseRow?.position ?? 0,
+            title: title ?? null,
+            tags,
+            repeats: sorted.map((r) => ({
+                repeat_index: r.repeatIndex,
+                status: r.status,
+                passed: r.passed,
+                score: r.score,
+            })),
+            pass_fraction: passFraction(passed, executedResults.length),
+            mean_score: mean(completed.filter((r) => r.score !== null).map((r) => r.score)),
+            failed_graders: [...failedGraders].sort(),
+            latency_ms_p50: percentile(latencies, 0.5),
+            cost_usd: cost,
+            failure_tags: [...failureTags].sort(),
+            ...(agentData ? { turns: mean(turns), tool_calls: mean(toolCalls) } : {}),
+        },
+    };
+}
+function matchesStatus(f, status) {
+    if (status === "errored")
+        return f.errored;
+    if (f.executed === 0)
+        return false;
+    if (status === "passed")
+        return f.passed === f.executed;
+    if (status === "failed")
+        return f.passed < f.executed;
+    return f.passed > 0 && f.passed < f.executed && f.executed >= 2;
+}
+export function buildResultRows(input) {
+    const { filter = {} } = input;
+    const reviews = new Map(input.reviews.map((r) => [resultKey(r.caseId, r.repeatIndex), r]));
+    const byCase = new Map();
+    for (const r of input.results) {
+        const list = byCase.get(r.caseId);
+        if (list)
+            list.push(r);
+        else
+            byCase.set(r.caseId, [r]);
+    }
+    const caseById = new Map(input.cases.map((c) => [c.caseId, c]));
+    const ordered = [...byCase.keys()].sort((a, b) => (caseById.get(a)?.position ?? 0) - (caseById.get(b)?.position ?? 0) || (a < b ? -1 : a > b ? 1 : 0));
+    const q = filter.q?.trim().toLowerCase();
+    const facts = ordered
+        .map((id) => buildFacts(caseById.get(id), id, byCase.get(id) ?? [], reviews, input.targetKind))
+        .filter((f) => {
+        if (filter.grader !== undefined && !f.row.failed_graders.includes(filter.grader))
+            return false;
+        if (filter.tag !== undefined && !f.row.failure_tags.includes(filter.tag) && !f.row.tags.includes(filter.tag)) {
+            return false;
+        }
+        return q === undefined || q === "" || f.haystack.includes(q);
+    });
+    const counts = {
+        all: facts.length,
+        passed: facts.filter((f) => matchesStatus(f, "passed")).length,
+        failed: facts.filter((f) => matchesStatus(f, "failed")).length,
+        errored: facts.filter((f) => matchesStatus(f, "errored")).length,
+        flaky: facts.filter((f) => matchesStatus(f, "flaky")).length,
+    };
+    const selected = filter.status === undefined ? facts : facts.filter((f) => matchesStatus(f, filter.status));
+    return { rows: selected.map((f) => f.row), counts };
+}

package/dist/evals/read/runs.d.ts

@@ -0,0 +1,154 @@
+import { type AgentCatalogPort } from "../../config/resolveAgentTarget.js";
+import type { RunStore } from "../../runstore/port.js";
+import type { EvalLiveState } from "../manager.js";
+import { type LowestCase, type Stats } from "../stats.js";
+import { type GraderRef, type PreviousRunLite } from "../statsTypes.js";
+import type { EvalGradeRow, EvalResultWithGrades, EvalReviewRow, EvalRunRow } from "../storeTypes.js";
+export type ReadStore = Pick<RunStore, "listEvalRuns" | "getEvalRun" | "getEvalRunByNumber" | "listEvalResults" | "getEvalResultsForCase" | "getEvalCases" | "getEvalReviews">;
+export type RunHeadline = {
+    eval_run_id: string;
+    eval_id: string;
+    run_number: number;
+    status: string;
+    passed: boolean | null;
+    pass_rate: number | null;
+    pass_rate_ci: {
+        low: number;
+        high: number;
+    } | null;
+    results_executed: number;
+    cost_total: number;
+    finished_at: string | null;
+    fingerprint: string;
+    label: string | null;
+};
+export type WireGrade = {
+    grader_id: string;
+    grader_type: string;
+    status: string;
+    passed: boolean | null;
+    score: number | null;
+    raw_value: number | null;
+    reason: string | null;
+    details: unknown;
+    error_code: string | null;
+    judge_model: string | null;
+    judge_cost_usd: number | null;
+    judge_tokens_in: number | null;
+    judge_tokens_out: number | null;
+};
+export type WireResultDetail = {
+    case_id: string;
+    repeat_index: number;
+    status: string;
+    error_code: string | null;
+    error_message: string | null;
+    stage_run_id: string | null;
+    subject_ref: string | null;
+    turns: number | null;
+    tool_call_count: number | null;
+    agent?: {
+        id: string;
+        session_id: string | null;
+    } | null;
+    output: unknown;
+    latency_ms: number | null;
+    cost_usd: number | null;
+    tokens_in: number | null;
+    tokens_out: number | null;
+    score: number | null;
+    passed: boolean;
+    grades: WireGrade[];
+    budget_warnings: string[];
+    review: {
+        label: string | null;
+        note: string | null;
+    } | null;
+    tags: string[];
+};
+export type RunCurrent = {
+    stage_version_hash: string | null;
+    dataset_hash: string | null;
+    grader_hashes: Record<string, string> | null;
+    agent_revision?: number | null;
+    agent_definition_hash?: string | null;
+};
+export type ConversationView = {
+    messages: unknown[];
+    tool_calls: unknown[];
+    final_reply: string;
+    stop_reason: string;
+};
+export declare function conversationView(output: unknown): ConversationView | null;
+export type EvalRunDetail = {
+    eval_run_id: string;
+    run_number: number;
+    eval_id: string;
+    eval_path: string;
+    status: string;
+    status_reason: string | null;
+    passed: boolean | null;
+    label: string | null;
+    started_via: string;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+    progress: {
+        results_done: number;
+        results_total: number;
+        cost_usd: number;
+        max_cost_usd: number;
+        cases_total: number;
+    };
+    config: Record<string, unknown>;
+    fingerprint: string;
+    components: Record<string, unknown>;
+    stats: Stats | null;
+    lowest_cases_by_grader: Record<string, LowestCase[]>;
+    current: RunCurrent;
+    cases: Array<{
+        id: string;
+        title: string | null;
+        position: number;
+    }>;
+    live?: Array<{
+        case_id: string;
+        repeat_index: number;
+        phase: string;
+    }>;
+};
+export declare function runHeadline(row: EvalRunRow): RunHeadline;
+export type ActiveRun = {
+    run_number: number;
+    eval_run_id: string;
+    status: "queued" | "running";
+    results_done: number;
+    results_total: number;
+};
+/** The newest queued or running run of an eval, or null. */
+export declare function activeRunOf(store: Pick<ReadStore, "listEvalRuns">, projectRoot: string, evalId: string): Promise<ActiveRun | null>;
+export declare function graderRefsOf(row: Pick<EvalRunRow, "config">): GraderRef[];
+export declare function reviewTagMap(reviews: readonly EvalReviewRow[]): Map<string, string[]>;
+export declare function statsOfRun(row: EvalRunRow, results: readonly EvalResultWithGrades[], extra?: {
+    reviews?: readonly EvalReviewRow[];
+    previousRun?: PreviousRunLite | null;
+}): Stats;
+export declare function completedRunsNewestFirst(store: Pick<ReadStore, "listEvalRuns">, projectRoot: string, evalId: string, limit?: number): Promise<EvalRunRow[]>;
+export declare function previousRunLite(store: ReadStore, row: EvalRunRow, graders: readonly GraderRef[]): Promise<PreviousRunLite | null>;
+export declare function gradeToWire(g: EvalGradeRow): WireGrade;
+export declare function resultToWire(r: EvalResultWithGrades, review: EvalReviewRow | undefined, agentId?: string): WireResultDetail;
+export declare function currentHashes(row: EvalRunRow, agents?: AgentCatalogPort): Promise<RunCurrent>;
+export declare function buildRunDetail(input: {
+    store: ReadStore;
+    row: EvalRunRow;
+    live?: EvalLiveState | null;
+    agents?: AgentCatalogPort;
+}): Promise<EvalRunDetail>;
+export declare function buildExport(input: {
+    store: ReadStore;
+    row: EvalRunRow;
+    what: "results" | "config";
+}): Promise<{
+    filename: string;
+    body: unknown;
+}>;

package/dist/evals/read/runs.js

@@ -0,0 +1,295 @@
+import path from "node:path";
+import { loadDatasetFile } from "../../config/loadDataset.js";
+import { loadEvalOutcome, resolveEvalPaths } from "../../config/loadEval.js";
+import { resolveAgentTarget } from "../../config/resolveAgentTarget.js";
+import { resolveEvalTarget } from "../../config/resolveEvalTarget.js";
+import { computeStats, lowestCases } from "../stats.js";
+import { toGradeRecords, toResultRecord } from "../statsAdapter.js";
+import { resultKey } from "../statsTypes.js";
+export function conversationView(output) {
+    const rec = asRecord(output);
+    if (rec.kind !== "conversation")
+        return null;
+    if (!Array.isArray(rec.messages) || !Array.isArray(rec.tool_calls))
+        return null;
+    return {
+        messages: rec.messages,
+        tool_calls: rec.tool_calls,
+        final_reply: typeof rec.final_reply === "string" ? rec.final_reply : "",
+        stop_reason: typeof rec.stop_reason === "string" ? rec.stop_reason : "",
+    };
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function runHeadline(row) {
+    const summary = (row.summary ?? {});
+    return {
+        eval_run_id: row.evalRunId,
+        eval_id: row.evalId,
+        run_number: row.runNumber,
+        status: row.status,
+        passed: row.passed,
+        pass_rate: summary.pass_rate ?? null,
+        pass_rate_ci: summary.pass_rate_ci ?? null,
+        results_executed: summary.results_executed ?? row.resultsDone,
+        cost_total: summary.cost_total ?? row.costUsd,
+        finished_at: row.finishedAt,
+        fingerprint: row.configFingerprint,
+        label: row.label,
+    };
+}
+/** The newest queued or running run of an eval, or null. */
+export async function activeRunOf(store, projectRoot, evalId) {
+    const found = [];
+    for (const status of ["running", "queued"]) {
+        const page = await store.listEvalRuns({ projectRoot, evalId, status, limit: 50 });
+        found.push(...page.items);
+    }
+    const row = found.sort((a, b) => b.runNumber - a.runNumber)[0];
+    if (!row || (row.status !== "queued" && row.status !== "running"))
+        return null;
+    return {
+        run_number: row.runNumber,
+        eval_run_id: row.evalRunId,
+        status: row.status,
+        results_done: row.resultsDone,
+        results_total: row.resultsTotal,
+    };
+}
+export function graderRefsOf(row) {
+    const graders = asRecord(row.config).graders;
+    if (!Array.isArray(graders))
+        return [];
+    return graders.flatMap((g) => {
+        const rec = asRecord(g);
+        return typeof rec.id === "string" && typeof rec.hash === "string"
+            ? [{ id: rec.id, type: typeof rec.type === "string" ? rec.type : "", hash: rec.hash }]
+            : [];
+    });
+}
+export function reviewTagMap(reviews) {
+    const map = new Map();
+    for (const review of reviews) {
+        if (review.tags.length > 0)
+            map.set(resultKey(review.caseId, review.repeatIndex), review.tags);
+    }
+    return map;
+}
+export function statsOfRun(row, results, extra = {}) {
+    return computeStats({
+        ...(row.targetKind === "agent" ? { targetKind: "agent" } : {}),
+        results: results.map(toResultRecord),
+        grades: results.flatMap(toGradeRecords),
+        graders: graderRefsOf(row),
+        repeats: row.repeats,
+        passThreshold: row.passThreshold,
+        ...(extra.reviews ? { reviewsTags: reviewTagMap(extra.reviews) } : {}),
+        ...(extra.previousRun !== undefined ? { previousRun: extra.previousRun } : {}),
+    });
+}
+export async function completedRunsNewestFirst(store, projectRoot, evalId, limit = 50) {
+    const page = await store.listEvalRuns({ projectRoot, evalId, status: "completed", limit });
+    return [...page.items].sort((a, b) => b.runNumber - a.runNumber);
+}
+export async function previousRunLite(store, row, graders) {
+    const earlier = (await completedRunsNewestFirst(store, row.projectRoot, row.evalId)).filter((r) => r.runNumber < row.runNumber);
+    if (earlier.length === 0)
+        return null;
+    const rates = new Map();
+    const rateOf = async (run, graderId) => {
+        let byGrader = rates.get(run.evalRunId);
+        if (!byGrader) {
+            const stats = statsOfRun(run, await store.listEvalResults(run.evalRunId));
+            byGrader = new Map(stats.by_grader.map((g) => [g.grader_id, g.pass_rate]));
+            rates.set(run.evalRunId, byGrader);
+        }
+        return byGrader.get(graderId) ?? null;
+    };
+    const lite = [];
+    for (const g of graders) {
+        let changedHash;
+        let match;
+        for (const run of earlier) {
+            const found = graderRefsOf(run).find((x) => x.id === g.id);
+            if (!found)
+                continue;
+            if (found.hash === g.hash) {
+                match = run;
+                break;
+            }
+            changedHash ??= found.hash;
+        }
+        if (match)
+            lite.push({ graderId: g.id, hash: g.hash, passRate: await rateOf(match, g.id) });
+        else if (changedHash !== undefined)
+            lite.push({ graderId: g.id, hash: changedHash, passRate: null });
+    }
+    return { graders: lite };
+}
+export function gradeToWire(g) {
+    return {
+        grader_id: g.graderId,
+        grader_type: g.graderType,
+        status: g.status,
+        passed: g.passed,
+        score: g.score,
+        raw_value: g.rawValue,
+        reason: g.reason,
+        details: g.details,
+        error_code: g.errorCode,
+        judge_model: g.judgeModel,
+        judge_cost_usd: g.judgeCostUsd,
+        judge_tokens_in: g.judgeTokensIn,
+        judge_tokens_out: g.judgeTokensOut,
+    };
+}
+export function resultToWire(r, review, agentId) {
+    const hasReview = review !== undefined && (review.label !== null || review.note !== null);
+    return {
+        case_id: r.caseId,
+        repeat_index: r.repeatIndex,
+        status: r.status,
+        error_code: r.errorCode,
+        error_message: r.errorMessage,
+        stage_run_id: r.stageRunId,
+        subject_ref: r.subjectRef,
+        turns: r.turns,
+        tool_call_count: r.toolCallCount,
+        ...(agentId !== undefined
+            ? { agent: r.subjectRef !== null ? { id: agentId, session_id: r.subjectRef } : null }
+            : {}),
+        output: r.output,
+        latency_ms: r.latencyMs,
+        cost_usd: r.costUsd,
+        tokens_in: r.tokensIn,
+        tokens_out: r.tokensOut,
+        score: r.score,
+        passed: r.passed,
+        grades: r.grades.map(gradeToWire),
+        budget_warnings: r.budgetWarnings ?? [],
+        review: hasReview ? { label: review.label, note: review.note } : null,
+        tags: review?.tags ?? [],
+    };
+}
+export async function currentHashes(row, agents) {
+    const isAgent = row.targetKind === "agent";
+    const none = {
+        stage_version_hash: null,
+        dataset_hash: null,
+        grader_hashes: null,
+        ...(isAgent ? { agent_revision: null, agent_definition_hash: null } : {}),
+    };
+    const evalAbs = path.resolve(row.projectRoot, row.evalPath);
+    try {
+        const outcome = await loadEvalOutcome(evalAbs, row.projectRoot);
+        if (!outcome.ok)
+            return none;
+        const loaded = outcome.value;
+        const paths = resolveEvalPaths(loaded.file, loaded.path);
+        const datasetHashOf = async () => {
+            const dataset = await loadDatasetFile(paths.datasetPath, { root: row.projectRoot });
+            return dataset.findings.some((f) => f.severity === "error") ? null : dataset.contentHash;
+        };
+        const graderHashes = Object.fromEntries(loaded.graders.map((g) => [g.id, g.hash]));
+        if (isAgent) {
+            const resolved = agents ? await resolveAgentTarget(loaded.file, row.projectRoot, agents) : null;
+            return {
+                stage_version_hash: null,
+                dataset_hash: await datasetHashOf(),
+                grader_hashes: graderHashes,
+                agent_revision: resolved?.ok ? resolved.value.revision : null,
+                agent_definition_hash: resolved?.ok ? resolved.value.definitionHash : null,
+            };
+        }
+        const [target, datasetHash] = await Promise.all([
+            resolveEvalTarget(loaded.file, loaded.path, row.projectRoot),
+            datasetHashOf(),
+        ]);
+        return {
+            stage_version_hash: target.ok ? target.value.stageVersionHash : null,
+            dataset_hash: datasetHash,
+            grader_hashes: graderHashes,
+        };
+    }
+    catch {
+        return none;
+    }
+}
+function plannedCase(row) {
+    const title = row.case.title;
+    return { id: row.caseId, title: typeof title === "string" && title !== "" ? title : null, position: row.position };
+}
+export async function buildRunDetail(input) {
+    const { store, row } = input;
+    const [results, reviews, storedCases] = await Promise.all([
+        store.listEvalResults(row.evalRunId),
+        store.getEvalReviews(row.evalRunId),
+        store.getEvalCases(row.evalRunId),
+    ]);
+    const graders = graderRefsOf(row);
+    const grades = results.flatMap(toGradeRecords);
+    const executed = results.some((r) => ["completed", "stage_failed", "needs_input", "error"].includes(r.status));
+    const stats = executed
+        ? statsOfRun(row, results, { reviews, previousRun: await previousRunLite(store, row, graders) })
+        : null;
+    const detail = {
+        eval_run_id: row.evalRunId,
+        run_number: row.runNumber,
+        eval_id: row.evalId,
+        eval_path: row.evalPath,
+        status: row.status,
+        status_reason: row.statusReason,
+        passed: row.passed,
+        label: row.label,
+        started_via: row.startedVia,
+        created_at: row.createdAt,
+        started_at: row.startedAt,
+        finished_at: row.finishedAt,
+        progress: {
+            results_done: row.resultsDone,
+            results_total: row.resultsTotal,
+            cost_usd: row.costUsd,
+            max_cost_usd: row.maxCostUsd,
+            cases_total: row.casesTotal,
+        },
+        config: row.config,
+        fingerprint: row.configFingerprint,
+        components: row.configComponents,
+        stats,
+        lowest_cases_by_grader: executed
+            ? Object.fromEntries(graders.map((g) => [g.id, lowestCases(grades.filter((x) => x.graderId === g.id))]))
+            : {},
+        current: await currentHashes(row, input.agents),
+        cases: storedCases.map(plannedCase),
+    };
+    if (input.live && (row.status === "running" || row.status === "queued")) {
+        detail.live = input.live.phases.map((p) => ({
+            case_id: p.caseId,
+            repeat_index: p.repeatIndex,
+            phase: p.phase,
+        }));
+    }
+    return detail;
+}
+export async function buildExport(input) {
+    const { store, row, what } = input;
+    const filename = `${row.evalId}-run-${row.runNumber}-${what}.json`;
+    if (what === "config")
+        return { filename, body: row.config };
+    const [detail, results, reviews] = await Promise.all([
+        buildRunDetail({ store, row }),
+        store.listEvalResults(row.evalRunId),
+        store.getEvalReviews(row.evalRunId),
+    ]);
+    const reviewByKey = new Map(reviews.map((r) => [resultKey(r.caseId, r.repeatIndex), r]));
+    return {
+        filename,
+        body: {
+            ...detail,
+            results: results.map((r) => resultToWire(r, reviewByKey.get(resultKey(r.caseId, r.repeatIndex)))),
+        },
+    };
+}

package/dist/evals/read/suggestions.d.ts

@@ -0,0 +1,43 @@
+import { type TriageBucket } from "../triage/constants.js";
+import type { SuggestionRow } from "../triage/types.js";
+export type WireSuggestion = {
+    id: string;
+    case_id: string;
+    repeat_index: number;
+    source: "jev" | "judge";
+    bucket: TriageBucket;
+    failure_type: string | null;
+    confidence: number;
+    bucket_probabilities: Record<TriageBucket, number>;
+    grader_false_alarms: Array<{
+        grader_id: string;
+        probability: number;
+    }>;
+    model: string;
+    prompt_version: number;
+    status: "pending" | "accepted" | "dismissed";
+    created_at: string;
+};
+export type SuggestionSummary = {
+    by_bucket: Record<TriageBucket, number>;
+    by_type: Record<string, number>;
+    pending: number;
+    accepted: number;
+    dismissed: number;
+    low_confidence: number;
+};
+export declare function suggestionToWire(row: SuggestionRow): WireSuggestion;
+export declare function isLowConfidence(row: Pick<SuggestionRow, "bucket" | "confidence">): boolean;
+/**
+ * One suggestion stands for a result: the newest that is not dismissed, else the newest dismissed. A result sorted by
+ * both backends therefore counts once. Ties on time keep the later source name so the choice is stable.
+ */
+export declare function representatives(rows: readonly SuggestionRow[]): SuggestionRow[];
+/**
+ * Counts per result (see `representatives`). `by_bucket`, `by_type` and `low_confidence` count suggestions that are not
+ * dismissed; `pending`, `accepted` and `dismissed` count every representative by status. A null failure type is not
+ * counted in `by_type`. Low confidence means the bucket is `unclear` or its confidence is below 0.7.
+ */
+export declare function buildSuggestionSummary(rows: readonly SuggestionRow[]): SuggestionSummary;
+/** The suggestion shown for one result in the case drawer: its representative, or null. */
+export declare function suggestionFor(rows: readonly SuggestionRow[], caseId: string, repeatIndex: number): WireSuggestion | null;

package/dist/evals/read/suggestions.js

@@ -0,0 +1,73 @@
+import { LOW_CONFIDENCE_THRESHOLD, TRIAGE_BUCKETS } from "../triage/constants.js";
+export function suggestionToWire(row) {
+    return {
+        id: row.id,
+        case_id: row.caseId,
+        repeat_index: row.repeatIndex,
+        source: row.source,
+        bucket: row.bucket,
+        failure_type: row.failureType,
+        confidence: row.confidence,
+        bucket_probabilities: row.bucketProbabilities,
+        grader_false_alarms: row.graderFalseAlarms.map((a) => ({ grader_id: a.graderId, probability: a.probability })),
+        model: row.model,
+        prompt_version: row.promptVersion,
+        status: row.status,
+        created_at: row.createdAt,
+    };
+}
+export function isLowConfidence(row) {
+    return row.bucket === "unclear" || row.confidence < LOW_CONFIDENCE_THRESHOLD;
+}
+/**
+ * One suggestion stands for a result: the newest that is not dismissed, else the newest dismissed. A result sorted by
+ * both backends therefore counts once. Ties on time keep the later source name so the choice is stable.
+ */
+export function representatives(rows) {
+    const best = new Map();
+    const rank = (row) => [row.status === "dismissed" ? 0 : 1, row.createdAt, row.source];
+    for (const row of rows) {
+        const key = `${row.caseId}\u0000${row.repeatIndex}`;
+        const current = best.get(key);
+        if (current === undefined) {
+            best.set(key, row);
+            continue;
+        }
+        const [a, b] = [rank(row), rank(current)];
+        if (a[0] > b[0] || (a[0] === b[0] && (a[1] > b[1] || (a[1] === b[1] && a[2] > b[2]))))
+            best.set(key, row);
+    }
+    return [...best.values()];
+}
+/**
+ * Counts per result (see `representatives`). `by_bucket`, `by_type` and `low_confidence` count suggestions that are not
+ * dismissed; `pending`, `accepted` and `dismissed` count every representative by status. A null failure type is not
+ * counted in `by_type`. Low confidence means the bucket is `unclear` or its confidence is below 0.7.
+ */
+export function buildSuggestionSummary(rows) {
+    const summary = {
+        by_bucket: Object.fromEntries(TRIAGE_BUCKETS.map((b) => [b, 0])),
+        by_type: {},
+        pending: 0,
+        accepted: 0,
+        dismissed: 0,
+        low_confidence: 0,
+    };
+    for (const row of representatives(rows)) {
+        summary[row.status] += 1;
+        if (row.status === "dismissed")
+            continue;
+        summary.by_bucket[row.bucket] += 1;
+        if (row.failureType !== null)
+            summary.by_type[row.failureType] = (summary.by_type[row.failureType] ?? 0) + 1;
+        if (isLowConfidence(row))
+            summary.low_confidence += 1;
+    }
+    return summary;
+}
+/** The suggestion shown for one result in the case drawer: its representative, or null. */
+export function suggestionFor(rows, caseId, repeatIndex) {
+    const own = rows.filter((r) => r.caseId === caseId && r.repeatIndex === repeatIndex);
+    const [rep] = representatives(own);
+    return rep === undefined ? null : suggestionToWire(rep);
+}