import type { SourceDomain } from '../shared/source-discovery.js';
/** The categories of structural problems a context-pack can exhibit. Each
 *  enum value maps to one rule in computeContextPackDiagnostics. */
export type ContextPackDiagnosticKind = 'missing_required_evidence' | 'missing_required_semantic' | 'zero_claims' | 'undersized_retrieval' | 'budget_underutilized' | 'missing_snippets' | 'low_avg_match_score' | 'orphan_nodes' | 'no_graph_signals' | 'excluded_domain_selected' | 'test_dominated_pack' | 'controller_only_pipeline_pack' | 'isolated_route_method' | 'missing_method_anchor' | 'missing_provider_call_edges' | 'missing_runtime_pipeline' | 'slice_path_nodes_not_promoted' | 'pack_culled_to_budget' | 'polluted_source_path_selected' | 'missing_structural_evidence' | 'runtime_pack_overexpanded';
export type ContextPackDiagnosticSeverity = 'info' | 'warn' | 'error';
export interface ContextPackDiagnosticWarning {
    kind: ContextPackDiagnosticKind;
    severity: ContextPackDiagnosticSeverity;
    message: string;
    /** Optional structured detail — kind-specific. Consumers can read this
     *  for finer-grained UX (e.g., listing the missing evidence classes). */
    detail?: Record<string, unknown>;
}
export interface ContextPackQualitySignals {
    /** Number of nodes in the pack. */
    node_count: number;
    /** Number of relationships in the pack. */
    relationship_count: number;
    /** Number of claims emitted by the pack. */
    claim_count: number;
    /** Share of nodes carrying a non-empty snippet, 0..1. */
    snippet_coverage: number;
    /** Average match_score across nodes that have one, 0..1 (NaN-safe). */
    avg_match_score: number;
    /** token_count from the pack as a fraction of task_contract.budget.
     *  Capped at 1.0 for over-budget packs. */
    budget_utilization: number;
    /** Source-domain distribution across selected nodes. */
    domain_distribution: Partial<Record<SourceDomain, number>>;
    /** Domains the prompt explicitly excluded. */
    excluded_domains: string[];
    /** Number of selected nodes from polluted/generated paths. */
    polluted_source_path_count: number;
}
export interface ContextPackDiagnostics {
    /** Overall quality score, 0..1. 1.0 means no warnings triggered;
     *  weighted-deductions reduce the score toward 0 for problem packs. */
    quality_score: number;
    /** Triggered warnings, ordered by severity desc then kind asc. */
    warnings: ContextPackDiagnosticWarning[];
    /** Raw signals used to compute the score — useful for telemetry and
     *  for consumers that want to apply their own thresholds. */
    signals: ContextPackQualitySignals;
}