/**
 * SmartPerfetto Data Contract
 *
 * This file defines the SINGLE SOURCE OF TRUTH for data structures
 * shared between:
 * - Backend (SkillExecutor, AgentRuntime, SSE streaming)
 * - Frontend (AIPanel, SqlResultTable)
 * - HTML Report Generator
 *
 * IMPORTANT: Any changes here must be synchronized with frontend types.
 * Run `npm run generate:frontend-types` to sync types to frontend.
 *
 * @module dataContract
 * @version 2.0.0 - DataEnvelope refactoring
 */
/**
 * Column Data Types - Semantic type of column data
 *
 * The type determines:
 * - How values are parsed and validated
 * - Default formatting
 * - Available click actions
 */
export declare const VALID_COLUMN_TYPES: readonly ["string", "number", "timestamp", "duration", "percentage", "bytes", "boolean", "enum", "json", "link"];
export type ColumnType = typeof VALID_COLUMN_TYPES[number];
/**
 * Column Format - How to display the value
 */
export declare const VALID_COLUMN_FORMATS: readonly ["default", "compact", "full", "relative", "percentage", "duration_ms", "duration_us", "timestamp_relative", "timestamp_absolute", "bytes_human", "code", "truncate"];
export type ColumnFormat = typeof VALID_COLUMN_FORMATS[number];
/**
 * Click Action - What happens when user clicks a column value
 */
export declare const VALID_CLICK_ACTIONS: readonly ["none", "navigate_timeline", "navigate_range", "copy", "expand", "filter", "link"];
export type ClickAction = typeof VALID_CLICK_ACTIONS[number];
/**
 * Column Definition - Complete metadata for a single column
 *
 * This enables self-describing data where the frontend renders
 * based on schema rather than hardcoded column name patterns.
 */
export interface ColumnDefinition {
    /** Column name (must match data column name) */
    name: string;
    /** Human-readable label (defaults to name if not specified) */
    label?: string;
    /** Semantic data type */
    type: ColumnType;
    /** Display format */
    format?: ColumnFormat;
    /** Click action */
    clickAction?: ClickAction;
    /** For timestamp click actions, the associated duration column for range selection */
    durationColumn?: string;
    /** Time unit for timestamp/duration columns (default: 'ns') */
    unit?: 'ns' | 'us' | 'ms' | 's';
    /** Whether this column should be hidden by default */
    hidden?: boolean;
    /** Whether this column is sortable */
    sortable?: boolean;
    /** Default sort direction if this is the default sort column */
    defaultSort?: 'asc' | 'desc';
    /** Column width hint ('narrow', 'medium', 'wide', 'auto' or pixel value) */
    width?: 'narrow' | 'medium' | 'wide' | 'auto' | number;
    /** Tooltip text for column header */
    tooltip?: string;
    /** For enum type, the list of possible values */
    enumValues?: string[];
    /** CSS class to apply to this column */
    cssClass?: string;
}
/**
 * Default column definitions based on common column name patterns
 * Used when skills don't explicitly define columns
 *
 * IMPORTANT: Order matters! More specific patterns should come before generic ones.
 * The first matching pattern wins.
 */
export declare const DEFAULT_COLUMN_PATTERNS: Array<{
    pattern: RegExp;
    definition: Partial<ColumnDefinition>;
}>;
/**
 * Infer column definition from column name using patterns
 */
export declare function inferColumnDefinition(columnName: string): ColumnDefinition;
/**
 * DataEnvelope Meta - Metadata about the data origin and version
 */
export type DataEnvelopeTraceSide = 'current' | 'reference';
export type DataEnvelopePlanPhaseAttribution = 'active' | 'inferred' | 'missing' | 'ambiguous' | 'unexpected_tool' | 'none';
export interface DataEnvelopeMeta {
    /** Data type identifier */
    type: 'skill_result' | 'sql_result' | 'ai_response' | 'diagnostic' | 'chart';
    /** Schema version for forward compatibility */
    version: string;
    /** Source identifier (skill ID, query hash, etc.) */
    source: string;
    /** Creation timestamp */
    timestamp: number;
    /** Optional skill ID if from skill execution */
    skillId?: string;
    /** Optional step ID within a skill */
    stepId?: string;
    /** Stable evidence reference shared by UI, reports, and snapshots */
    evidenceRefId?: string;
    /** Trace side for comparison-mode outputs */
    traceSide?: DataEnvelopeTraceSide;
    /** Backend trace identifier used to produce this data */
    traceId?: string;
    /** Stable hash of the SQL or data-producing query */
    queryHash?: string;
    /** Tool-call identifier that produced this data, when available */
    sourceToolCallId?: string;
    /** Stable hash of the producing tool parameters */
    paramsHash?: string;
    /** Canonical artifact id when this envelope represents artifact-backed rows */
    artifactId?: string;
    /** Compatibility alias from existing artifact rows */
    sourceArtifactId?: string;
    /** Identity sidecar reference for process/thread-sensitive evidence */
    identityRefId?: string;
    /** Identity status carried from the resolver sidecar */
    identityStatus?: import('./identityContract').IdentityResolutionStatus;
    /** Identity warnings that must survive report/export/verifier paths */
    identityWarnings?: string[];
    /** Full Identity Contract sidecar when this envelope was produced behind a resolver gate */
    identityResolution?: import('./identityContract').IdentityResolutionV1;
    /** Raw SQL identity warning for direct SQL paths that bypass Skill identity gate */
    processIdentityWarning?: string;
    /** Matched analysis plan phase ID when this data was produced */
    planPhaseId?: string;
    /** Matched analysis plan phase title when this data was produced */
    planPhaseTitle?: string;
    /** Matched analysis plan phase goal when this data was produced */
    planPhaseGoal?: string;
    /** Whether the plan phase binding is explicit enough to trust */
    planPhaseAttribution?: DataEnvelopePlanPhaseAttribution;
    /** Warning when the phase binding is missing, ambiguous, or tool-mismatched */
    planPhaseWarning?: string;
    /** One-line producer narration for this specific data output */
    toolNarration?: string;
    /** Human-readable reason this output was produced */
    producerReason?: string;
    /** Short producer intent for explaining why this table exists */
    intent?: string;
}
/**
 * DataEnvelope Display Config - How to render this data
 */
export interface DataEnvelopeDisplay {
    /** Display layer (overview, list, session, deep, diagnosis) */
    layer: DisplayLayer;
    /** Display format (table, chart, text, etc.) */
    format: DisplayFormat;
    /** Title to display */
    title: string;
    /** Column definitions for table format */
    columns?: ColumnDefinition[];
    /** Fields to extract as metadata (displayed in header, not columns) */
    metadataFields?: string[];
    /** Highlight rules for conditional styling */
    highlights?: HighlightRule[];
    /** Whether this result should be expanded by default */
    defaultExpanded?: boolean;
    /** Level of detail (key, summary, detail, debug) */
    level?: DisplayLevel;
    /** Rendering priority (0 = highest). Used by frontend to order envelopes within a group. */
    priority?: number;
    /** Group identifier for grouping related envelopes (e.g. "interval_1"). */
    group?: string;
    /** Data severity level. Frontend uses this to sort (critical first) and style. */
    severity?: 'critical' | 'warning' | 'info' | 'normal';
    /** Whether this envelope's table is collapsible in the UI. */
    collapsible?: boolean;
    /** Whether this envelope should be collapsed by default (requires collapsible=true). */
    defaultCollapsed?: boolean;
    /** Maximum number of visible rows before "show more" truncation. */
    maxVisibleRows?: number;
}
/**
 * DataEnvelope - Self-describing data container
 *
 * This is the UNIFIED format for all data flowing through the system.
 * The frontend renders based on `display` configuration rather than
 * hardcoding field names.
 *
 * @template T The type of the data payload
 */
export interface DataEnvelope<T = DataPayload> {
    /** Metadata about data origin */
    meta: DataEnvelopeMeta;
    /** The actual data payload */
    data: T;
    /** Display configuration */
    display: DataEnvelopeDisplay;
}
/**
 * Create a DataEnvelope from raw data
 */
export declare function createDataEnvelope<T = DataPayload>(data: T, options: {
    type: DataEnvelopeMeta['type'];
    source: string;
    skillId?: string;
    stepId?: string;
    title: string;
    layer?: DisplayLayer;
    format?: DisplayFormat;
    columns?: ColumnDefinition[];
    metadataFields?: string[];
    highlights?: HighlightRule[];
    level?: DisplayLevel;
    collapsible?: boolean;
    defaultCollapsed?: boolean;
    evidenceRefId?: string;
    traceSide?: DataEnvelopeTraceSide;
    traceId?: string;
    queryHash?: string;
    sourceToolCallId?: string;
    paramsHash?: string;
    artifactId?: string;
    sourceArtifactId?: string;
    identityRefId?: string;
    identityStatus?: import('./identityContract').IdentityResolutionStatus;
    identityWarnings?: string[];
    identityResolution?: import('./identityContract').IdentityResolutionV1;
    processIdentityWarning?: string;
    planPhaseId?: string;
    planPhaseTitle?: string;
    planPhaseGoal?: string;
    planPhaseAttribution?: DataEnvelopePlanPhaseAttribution;
    planPhaseWarning?: string;
    toolNarration?: string;
    producerReason?: string;
    intent?: string;
}): DataEnvelope<T>;
/**
 * Build column definitions from raw column names
 * Uses explicit definitions if provided, falls back to inference
 */
export declare function buildColumnDefinitions(columnNames: string[], explicitDefinitions?: Partial<ColumnDefinition>[]): ColumnDefinition[];
/**
 * Display Layers - Controls WHERE data appears in the UI
 *
 * - overview: L1 - Top-level aggregated metrics (summary cards)
 * - list: L2 - Main data tables with rows
 * - session: Session-level grouping (e.g., scroll sessions)
 * - deep: L4 - Detailed analysis (expandable rows in L2)
 * - diagnosis: Diagnostic findings and root-cause evidence
 *
 * This is an EXHAUSTIVE list. To add a new layer:
 * 1. Add to this array
 * 2. Update frontend layer handling
 * 3. Update HTML report generation
 */
export declare const VALID_DISPLAY_LAYERS: readonly ["overview", "list", "session", "deep", "diagnosis"];
export type DisplayLayer = typeof VALID_DISPLAY_LAYERS[number];
/**
 * Validate if a string is a valid DisplayLayer
 */
export declare function isValidDisplayLayer(layer: string | undefined): layer is DisplayLayer;
/**
 * Display Levels - Controls HOW MUCH detail to show
 *
 * - none: Do not display
 * - debug: Only show in debug mode
 * - detail: Show full details
 * - summary: Show summarized version
 * - key: Key metric, always prominent
 * - hidden: Keep in envelope but hide by default
 */
export declare const VALID_DISPLAY_LEVELS: readonly ["none", "debug", "detail", "summary", "key", "hidden"];
export type DisplayLevel = typeof VALID_DISPLAY_LEVELS[number];
/**
 * Display Formats - HOW to render the data
 */
export declare const VALID_DISPLAY_FORMATS: readonly ["table", "chart", "text", "timeline", "summary", "metric"];
export type DisplayFormat = typeof VALID_DISPLAY_FORMATS[number];
/**
 * SSE Event Types for streaming updates
 *
 * NEW (v2.0):
 * - data: Unified event carrying DataEnvelope or DataEnvelope[]
 *
 * LEGACY (still supported for backward compatibility):
 * - skill_data: Contains LayeredSkillResult from skill execution
 * - skill_layered_result: Alias for skill_data
 *
 * COMMON:
 * - finding: Individual finding/diagnostic
 * - progress: Phase/step progress update
 * - error: Error message
 * - snapshot_created: Analysis result snapshot persisted for comparison
 * - analysis_completed: Final result with report URL
 */
export declare const SSE_EVENT_TYPES: readonly ["data", "skill_data", "skill_layered_result", "finding", "progress", "conversation_step", "error", "snapshot_created", "analysis_completed", "thought", "tool_call", "conclusion", "scene_detected", "track_data", "worker_thought", "architecture_detected", "scene_story_detected", "scene_story_selection_ready", "scene_story_queued", "scene_story_started", "scene_story_retrying", "scene_story_completed", "scene_story_failed", "scene_story_cancelled", "scene_story_dropped", "scene_story_report_ready", "scene_story_smart_eta_refined"];
export type SSEEventType = typeof SSE_EVENT_TYPES[number];
/**
 * Unified Data Event - v2.0 SSE event format
 *
 * Carries one or more DataEnvelopes with their complete display metadata.
 * Frontend can render directly based on envelope's display configuration.
 */
export interface DataEvent {
    type: 'data';
    /** Unique event ID for deduplication */
    id: string;
    /** Single envelope or array of envelopes */
    envelope: DataEnvelope | DataEnvelope[];
    timestamp: number;
}
/**
 * Check if SSE event type is the new unified data event
 */
export declare function isDataEvent(eventType: string): eventType is 'data';
/**
 * Check if SSE event type is a legacy skill data event
 */
export declare function isLegacySkillEvent(eventType: string): boolean;
/**
 * Metadata Configuration - Defines which fields should be extracted as metadata
 *
 * Metadata fields are extracted from the first row and displayed in the header
 * instead of as columns. This is configurable per skill.
 */
export interface MetadataConfig {
    /** Field names to extract as metadata (displayed in header, not as columns) */
    fields: string[];
    /** Optional labels for metadata fields */
    labels?: Record<string, string>;
}
/**
 * Default metadata fields - extracted from data if present
 * These are commonly used fields that make sense as metadata
 */
export declare const DEFAULT_METADATA_FIELDS: readonly ["layer_name", "process_name", "package_name", "architecture", "device_model", "android_version"];
/**
 * Highlight Rule - For conditional styling of rows
 */
export interface HighlightRule {
    /** Condition expression (e.g., "jank_type != 'None'") */
    condition: string;
    /** CSS color or preset name */
    color?: string;
    /** Icon identifier */
    icon?: string;
    /** Severity level for default styling */
    severity?: 'info' | 'warning' | 'critical';
}
/**
 * Data Payload - The actual data content
 */
export interface DataPayload {
    /** Column names (for table format) */
    columns?: string[];
    /** Row data as 2D array (for table format) */
    rows?: any[][];
    /** Text content (for text format) */
    text?: string;
    /** Chart configuration (for chart format) */
    chart?: ChartConfig;
    /** Summary content (for summary format) */
    summary?: SummaryContent;
    /** Expandable row data (for L2 with L4 details) */
    expandableData?: ExpandableRowData[];
}
/**
 * Chart Configuration
 */
export interface ChartConfig {
    type: 'line' | 'bar' | 'pie' | 'scatter' | 'heatmap';
    data: any;
    options?: Record<string, any>;
}
/**
 * Summary Content
 */
export interface SummaryContent {
    title: string;
    content: string;
    metrics?: Array<{
        label: string;
        value: string | number;
        unit?: string;
        severity?: 'info' | 'warning' | 'critical';
    }>;
}
/**
 * Expandable Row Data - L4 deep analysis embedded in L2 rows
 */
export interface ExpandableRowData {
    /** Original row data (the L2 item) */
    item: Record<string, any>;
    /** Deep analysis result */
    result: {
        success: boolean;
        /** Sections of deep analysis, keyed by section ID */
        sections?: Record<string, SectionData>;
        error?: string;
    };
}
/**
 * Section Data - A single section in deep analysis
 */
export interface SectionData {
    title: string;
    format: DisplayFormat;
    data: DataPayload;
}
/**
 * Display Result - A single displayable result from a skill step
 *
 * This is the CORE structure that flows from backend to frontend.
 */
export interface DisplayResult {
    /** Step ID from skill definition */
    stepId: string;
    /** Display title */
    title: string;
    /** Display level (verbosity) */
    level: DisplayLevel;
    /** Display layer (UI placement) */
    layer?: DisplayLayer;
    /** Display format (rendering type) */
    format: DisplayFormat;
    /** The actual data */
    data: DataPayload;
    /** Highlight rules for conditional styling */
    highlight?: HighlightRule[];
    /** Original SQL query (for reproducibility) */
    sql?: string;
    /** Metadata configuration for this result */
    metadataConfig?: MetadataConfig;
}
/**
 * Layered Skill Result - Organized results by layer
 *
 * This is what flows through SSE to frontend.
 */
export interface LayeredSkillResult {
    /** Skill identifier */
    skillId: string;
    /** Human-readable skill name */
    skillName: string;
    /** Results organized by layer */
    layers: {
        overview?: Record<string, DisplayResult>;
        list?: Record<string, DisplayResult>;
        session?: Record<string, DisplayResult>;
        deep?: Record<string, DisplayResult>;
        diagnosis?: Record<string, DisplayResult>;
    };
    /** Diagnostic findings */
    diagnostics?: DiagnosticFinding[];
    /** Metadata about the execution */
    metadata: {
        executedAt: string;
        executionTimeMs: number;
        version?: string;
    };
    /** Data marked for synthesis/summary generation */
    synthesizeData?: SynthesizeDataItem[];
}
/**
 * Diagnostic Finding - A finding/issue discovered during analysis
 */
export interface DiagnosticFinding {
    id: string;
    severity: 'info' | 'warning' | 'critical';
    title: string;
    description?: string;
    evidence?: Record<string, any>;
    suggestions?: string[];
    confidence: number;
    sourceModule?: string;
}
/**
 * Synthesize Data Item - Data marked for AI summary generation
 */
export interface SynthesizeDataItem {
    stepId: string;
    title: string;
    data: any;
}
/**
 * Skill Data Event - SSE payload for skill results
 */
export interface SkillDataEvent {
    type: 'skill_data';
    data: LayeredSkillResult;
    timestamp: number;
}
/**
 * Finding Event - SSE payload for individual findings
 */
export interface FindingEvent {
    type: 'finding';
    data: DiagnosticFinding;
    timestamp: number;
}
/**
 * Progress Event - SSE payload for progress updates
 */
export interface ProgressEvent {
    type: 'progress';
    data: {
        phase: string;
        message: string;
        step?: number;
        totalSteps?: number;
        details?: Record<string, any>;
    };
    timestamp: number;
}
/**
 * Conversation Step Event - Strictly ordered timeline step for assistant-like UX
 */
export interface ConversationStepEvent {
    type: 'conversation_step';
    id: string;
    data: {
        eventId: string;
        sessionId: string;
        traceId: string;
        phase: 'progress' | 'thinking' | 'tool' | 'result' | 'error';
        role: 'agent' | 'system';
        ordinal: number;
        content: {
            text: string;
        };
        metadata?: Record<string, any>;
        source?: {
            eventType?: string;
            phase?: string;
        };
    };
    timestamp: number;
}
/**
 * Analysis Completed Event - SSE payload for final result
 */
export interface AnalysisCompletedEvent {
    type: 'analysis_completed';
    data: {
        summary: string;
        conclusion?: string;
        conclusionContract?: import('../agent/core/conclusionContract').ConclusionContract;
        claimSupport?: import('./evidenceContract').ClaimSupportV1[];
        claimVerificationResult?: import('./claimVerification').ClaimVerificationResult;
        identityResolutions?: import('./identityContract').IdentityResolutionV1[];
        reportUrl?: string;
        resultSnapshotId?: string;
        confidence?: number;
        rounds?: number;
        totalDurationMs?: number;
        partial?: boolean;
        terminationReason?: string;
        terminationMessage?: string;
        findings: DiagnosticFinding[];
        suggestions: string[];
    };
    timestamp: number;
}
/**
 * Union type for all SSE events
 */
export type SSEEvent = SkillDataEvent | FindingEvent | ProgressEvent | ConversationStepEvent | AnalysisCompletedEvent;
/**
 * Report Section - A section in the HTML report
 */
export interface ReportSection {
    id: string;
    title: string;
    type: 'summary' | 'table' | 'findings' | 'chart' | 'text';
    layer?: DisplayLayer;
    content: DisplayResult | DiagnosticFinding[] | string;
}
/**
 * HTML Report Data - Input for HTML report generation
 */
export interface HTMLReportData {
    traceId: string;
    query: string;
    timestamp: number;
    executionTimeMs: number;
    /** Results organized by layer */
    layeredResults: LayeredSkillResult[];
    /** All findings across all skills */
    findings: DiagnosticFinding[];
    /** Generated summary/answer */
    summary: string;
    /** Organized sections for report */
    sections?: ReportSection[];
}
/**
 * Validation error
 */
export interface ValidationError {
    path: string;
    message: string;
    value?: any;
}
/**
 * Validate a DisplayResult structure
 */
export declare function validateDisplayResult(result: any): ValidationError[];
/**
 * Validate a LayeredSkillResult structure
 */
export declare function validateLayeredSkillResult(result: any): ValidationError[];
/**
 * Extract metadata from a data row based on configured fields
 */
export declare function extractMetadata(row: Record<string, any> | any[], columns: string[], metadataFields?: string[]): Record<string, any>;
/**
 * Remove metadata columns from column list
 */
export declare function filterMetadataColumns(columns: string[], metadataFields?: string[]): string[];
/**
 * Organize DisplayResults into LayeredSkillResult
 */
export declare function organizeIntoLayers(skillId: string, skillName: string, displayResults: DisplayResult[], diagnostics?: DiagnosticFinding[], executionTimeMs?: number): LayeredSkillResult;
/**
 * Convert a DisplayResult to a DataEnvelope
 *
 * This bridges the legacy DisplayResult format to the new DataEnvelope format,
 * enabling gradual migration.
 */
export declare function displayResultToEnvelope(result: DisplayResult, skillId: string, explicitColumns?: Partial<ColumnDefinition>[]): DataEnvelope;
/**
 * Convert a LayeredSkillResult to an array of DataEnvelopes
 *
 * Each DisplayResult in each layer becomes a separate DataEnvelope.
 */
export declare function layeredResultToEnvelopes(result: LayeredSkillResult, columnDefinitions?: Record<string, Partial<ColumnDefinition>[]>): DataEnvelope[];
/**
 * Convert a DataEnvelope back to DisplayResult (for backward compatibility)
 */
export declare function envelopeToDisplayResult(envelope: DataEnvelope): DisplayResult;
/**
 * Convert an array of DataEnvelopes to LayeredSkillResult
 */
export declare function envelopesToLayeredResult(envelopes: DataEnvelope[], skillId: string, skillName: string, diagnostics?: DiagnosticFinding[], executionTimeMs?: number): LayeredSkillResult;
/**
 * Validate a ColumnDefinition
 */
export declare function validateColumnDefinition(column: any): ValidationError[];
/**
 * Validate a DataEnvelope
 */
export declare function validateDataEnvelope(envelope: any): ValidationError[];
/**
 * Generate a unique event ID for deduplication
 */
export declare function generateEventId(skillId: string, stepId?: string): string;
//# sourceMappingURL=dataContract.d.ts.map