/**
 * Diagnosis core domain types — canonical shapes for the post-run
 * synthesis layer (Doc 05).
 *
 * `Diagnosis.inputs` is the four-version cache envelope (VER-01); any
 * segment bump invalidates a cached Diagnosis. `DiagnosisCard` is an
 * outer-`status` discriminated union with a nested `cardType`
 * discriminator inside the `ready` variant.
 *
 * Phase 1 lands placeholder body shapes; Phase 5 enriches each per
 * AI-SPEC §3 and CONTEXT D-05/D-07. The `DiagnosisCard` discriminated
 * union surface (arms + `cardType` literals) is stable — only the
 * `body: <BodyInterface>` references resolve to richer shapes.
 *
 * @see docs/decisions/D0049-shared-confidence-contract.md
 * @see docs/decisions/D0052-judgment-ref-granularity.md
 * @see docs/decisions/D0050-artifact-registry-post-hoc-versioned-extension.md
 */
import type { Confidence } from "./confidence.js";
import type { RunId } from "./branded-ids.js";
import type { ReportId } from "./index.js";
import type { ModelId } from "../ports/llm-client.js";
/**
 * The four-version cache envelope. Every cached `Diagnosis` carries the
 * versions of the inputs that produced it; any bump in any segment
 * invalidates the cache (cross-package contract test asserts this).
 *
 * Strings everywhere; semver convention by humans where authored
 * manually. No branding, no tuples, no content-hash typing — keeps the
 * envelope trivially serializable + greppable.
 */
export interface VersionedInputs {
    graderJudgmentsVersion: string;
    ensembleVersion: string;
    diagnosisVersion: string;
    cardVersion: string;
}
/**
 * The 8 ready-card archetypes. Phase 5 cards register against these
 * literals; the slim-shape boundary in Phase 7 reads them to render the
 * Studio diagnosis renderer.
 */
export type CardType = "area-summary" | "failure-mode-summary" | "no-issues" | "top-recommendations" | "weakest-area" | "low-confidence-attribution" | "doc-attribution-spotlight" | "regression-vs-baseline";
/**
 * Per-card telemetry envelope. `cardVersion` here is the per-card
 * version (e.g. `"area-summary@0.1.0"`), not the compound. Drives
 * DIAG-06 cost telemetry in Phase 6.
 */
export interface CardMeta {
    cardVersion: string;
    tokenUsage?: {
        input: number;
        output: number;
    };
    latencyMs?: number;
    /** ISO 8601 UTC timestamp. */
    generatedAt: string;
    cost?: number;
    model?: ModelId;
}
/**
 * A single actionable suggestion surfaced by a recommendations card.
 *
 * Phase 5 adds `docSlug` (the canonical doc page to rewrite) and
 * `sectionHeading` (null when the suggestion targets the whole page)
 * per AI-SPEC actionability-specificity rubric + failure-mode #2
 * mitigation.
 */
export interface ActionSuggestion {
    title: string;
    body: string;
    priority: "high" | "medium" | "low";
    /** Canonical slug of the documentation page this suggestion targets. */
    docSlug: string;
    /**
     * Heading within `docSlug` that should be revised, or `null` when the
     * suggestion targets the page as a whole.
     */
    sectionHeading: string | null;
}
/**
 * Minimal judgment reference per D0052 (taskId × modelId × dimension).
 * Used by `LowConfidenceAttributionBody.judgmentRefs` to cite the
 * specific judgments that drove a low-confidence finding.
 */
export interface JudgmentRef {
    taskId: string;
    modelId: string;
    dimension: string;
}
/**
 * Phase 5 enriched body shapes. Each keeps `summary: string` (load-bearing
 * for CLI default render per AI-SPEC §6) and adds fields the corresponding
 * Zod schema needs (asserting `satisfies z.ZodType<T>` in the card file).
 */
/** area-summary: deterministic — keep only summary (no behavioral claims). */
export interface AreaSummaryBody {
    summary: string;
}
/**
 * failure-mode-summary: deterministic + D-05 dimension/failureMode gate.
 * `count` = frequency in the report; `sampleSize` = judgment count for the
 * dimension (per AI-SPEC failure-mode #3 mitigation).
 */
export interface FailureModeSummaryBody {
    summary: string;
    /** Rubric dimension this summary targets (e.g. "task-completion"). */
    dimension: string;
    /** Canonical failure mode within this dimension. */
    failureMode: string;
    /** Number of judgments in this report with this failure mode. */
    count: number;
    /** Total judgments for this dimension — calibration denominator. */
    sampleSize: number;
}
/**
 * no-issues: deterministic + AI-SPEC failure-mode #7 sycophancy guard.
 * `thresholdScore` surfaces the threshold used to qualify as "no issues"
 * so readers can see the criterion behind the positive assessment.
 */
export interface NoIssuesBody {
    summary: string;
    /** Minimum composite score that qualified this area as "no issues". */
    thresholdScore: number;
}
/**
 * top-recommendations: LLM-driven. `suggestions` reuses the enriched
 * `ActionSuggestion` shape (docSlug + sectionHeading per AI-SPEC
 * actionability-specificity rubric + failure-mode #2 mitigation).
 */
export interface TopRecommendationsBody {
    summary: string;
    suggestions: ActionSuggestion[];
}
/**
 * weakest-area: LLM-driven. Adds area identification, dimension/failureMode
 * context, and a small-sample calibration guard (AI-SPEC failure-mode #3).
 */
export interface WeakestAreaBody {
    summary: string;
    /** Documentation area with the lowest composite score. */
    area: string;
    /** Primary dimension driving the low score. */
    dimension: string;
    /** Dominant failure mode in this area. */
    failureMode: string;
    /** Number of judgments sampled for this area — calibration denominator. */
    sampleSize: number;
    /** Calibrated confidence per D0049 (ensemble-stdev derivation). */
    confidence: Confidence;
}
/**
 * regression-vs-baseline: LLM-driven. `deltas` is the per-area diff
 * (JS-computed pre-call, max 10 entries); `drivers` is LLM prose;
 * `overallTrend` is a 4-bucket summary per AI-SPEC §3 lines 605-613.
 */
export interface RegressionVsBaselineBody {
    summary: string;
    /**
     * Per-area score deltas (max 10). `drivers` carries the LLM's prose
     * reasoning about what caused the change.
     */
    deltas: {
        area: string;
        direction: "improved" | "regressed" | "unchanged";
        pointsDelta: number;
        drivers: string[];
    }[];
    /** 4-bucket aggregate trend across all deltas. */
    overallTrend: "net-improved" | "net-regressed" | "mixed" | "stable";
}
/**
 * low-confidence-attribution: LLM-driven. `judgmentRefs` cites the
 * specific judgments (D0052 triple) that drove the low-confidence finding.
 */
export interface LowConfidenceAttributionBody {
    summary: string;
    /** Judgment references (D0052) driving this low-confidence finding. */
    judgmentRefs: JudgmentRef[];
}
/**
 * doc-attribution-spotlight: LLM-driven. `docCitations` carries per-doc
 * attribution roles and confidence calibration (AI-SPEC failure-mode #5).
 */
export interface DocAttributionSpotlightBody {
    summary: string;
    /**
     * Per-doc attribution records. `role` classifies how the doc contributed;
     * `confidence` calibrates the attribution certainty (D0049).
     */
    docCitations: {
        docSlug: string;
        confidence: Confidence;
        role: "supports" | "contradicts" | "missing" | "irrelevant";
    }[];
}
/**
 * Outer-`status` discriminated union: 8 ready variants (one per
 * `cardType`, each carrying its per-cardType body), plus a `degraded`
 * variant (parse failed or downgraded by the runner) and a `missing`
 * variant (card not produced for this run).
 *
 * No `not-yet-generated` variant — old-report fallback is a Phase 7
 * concern at the slim-shape boundary, handled at fetch-time, not in
 * `DiagnosisCard` itself.
 *
 * D-07: only the `body: <BodyInterface>` references resolve to richer
 * shapes. The union arms, status literals, and cardType literals are
 * identical to Phase 1.
 */
export type DiagnosisCard = {
    status: "ready";
    cardType: "area-summary";
    body: AreaSummaryBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "failure-mode-summary";
    body: FailureModeSummaryBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "no-issues";
    body: NoIssuesBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "top-recommendations";
    body: TopRecommendationsBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "weakest-area";
    body: WeakestAreaBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "low-confidence-attribution";
    body: LowConfidenceAttributionBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "doc-attribution-spotlight";
    body: DocAttributionSpotlightBody;
    meta: CardMeta;
} | {
    status: "ready";
    cardType: "regression-vs-baseline";
    body: RegressionVsBaselineBody;
    meta: CardMeta;
} | {
    status: "degraded";
    cardType: CardType;
    reason: string;
    parseFailed: boolean;
    meta: CardMeta;
} | {
    status: "missing";
    cardType: CardType;
    reason: string;
};
/**
 * The post-run synthesis aggregate. Consumed by Phase 5 (runner +
 * cards), Phase 6 (CLI) and Phase 7 (Studio). Phase 1 lands the
 * declarative shape; runtime construction lands in Phase 5.
 */
export interface Diagnosis {
    runId: RunId;
    reportId: ReportId;
    inputs: VersionedInputs;
    cards: DiagnosisCard[];
    /** ISO 8601 UTC timestamp. */
    generatedAt: string;
}
