/**
 * Teaching Module Types
 *
 * Centralized type definitions for the teaching pipeline feature.
 * This file serves as the single source of truth for:
 * - API response types (camelCase for frontend)
 * - Internal types (snake_case from YAML/SQL)
 * - Transformation utilities
 * - Validation helpers
 *
 * @module types/teaching
 */
/**
 * Main API response for /api/agent/v1/teaching/pipeline
 */
export interface TeachingPipelineResponse {
    success: boolean;
    schemaVersion?: 'teaching.pipeline.v2';
    detection: TeachingDetectionResponse;
    observedFlow?: ObservedFlow;
    teaching?: TeachingContentResponse | null;
    teachingContent?: TeachingContentResponse | null;
    pinPlan?: TeachingPinPlan;
    overlayPlan?: TeachingOverlayPlan;
    warnings?: TeachingWarning[];
    pinInstructions: PinInstructionResponse[];
    activeRenderingProcesses: ActiveProcess[];
    error?: string;
}
/**
 * Pipeline detection result
 */
export interface PipelineDetectionResult {
    detected: boolean;
    primaryPipelineId: string;
    primaryConfidence: number;
    candidates: PipelineCandidate[];
    features: DetectedFeature[];
    traceRequirementsMissing: string[];
}
/**
 * Backward-compatible API detection payload.
 *
 * The historical teaching endpoint returns snake_case fields. Keep those fields
 * stable while exposing camelCase aliases for new frontend code.
 */
export interface TeachingDetectionResponse {
    detected: boolean;
    primaryPipelineId: string;
    primaryConfidence: number;
    primary_pipeline: {
        id: string;
        confidence: number;
    };
    candidates: PipelineCandidate[];
    features: DetectedFeature[];
    subvariants: RenderingPipelineSubvariants;
    traceRequirementsMissing: string[];
    trace_requirements_missing: string[];
}
export interface RenderingPipelineSubvariants {
    buffer_mode: string;
    flutter_engine: string;
    webview_mode: string;
    game_engine: string;
}
/**
 * Pipeline candidate from detection
 */
export interface PipelineCandidate {
    id: string;
    confidence: number;
}
/**
 * Detected feature from pipeline analysis
 */
export interface DetectedFeature {
    name: string;
    detected: boolean;
    value?: string | number;
}
/**
 * Teaching content for frontend display
 */
export interface TeachingContentResponse {
    title: string;
    summary: string;
    mermaidBlocks: string[];
    threadRoles: ThreadRoleResponse[];
    keySlices: string[];
    docPath: string;
}
/**
 * Thread role for frontend display
 */
export interface ThreadRoleResponse {
    thread: string;
    responsibility: string;
    traceTag?: string;
}
/**
 * Pin instruction for frontend (camelCase)
 */
export interface PinInstructionResponse {
    pattern: string;
    matchBy: 'name' | 'uri' | 'thread' | 'process' | 'slice';
    priority: number;
    reason: string;
    expand?: boolean;
    mainThreadOnly?: boolean;
    smartPin?: boolean;
    skipPin?: boolean;
    activeProcessNames?: string[];
}
/**
 * Active rendering process detected in trace
 */
export interface ActiveProcess {
    upid: number;
    processName: string;
    frameCount: number;
    renderThreadTid: number;
}
export interface TeachingPipelineRequest {
    traceId: string;
    packageName?: string;
    processName?: string;
    selectionContext?: Record<string, unknown>;
    visibleWindow?: Record<string, unknown>;
    startTs?: number | string;
    endTs?: number | string;
}
export type ObservedFlowLaneRole = 'app' | 'render_thread' | 'producer' | 'buffer_queue' | 'surfaceflinger' | 'hwc_present' | 'critical_task' | 'unknown';
export interface ObservedFlowTrackHint {
    matchBy: 'thread' | 'process' | 'slice' | 'layer' | 'uri' | 'name';
    pattern: string;
    processName?: string;
    threadName?: string;
    layerName?: string;
    mainThreadOnly?: boolean;
}
export interface ObservedFlowLane {
    id: string;
    role: ObservedFlowLaneRole;
    title: string;
    processName?: string;
    threadName?: string;
    layerName?: string;
    trackHint?: ObservedFlowTrackHint;
    pipelineIds: string[];
    confidence: number;
    evidenceSource: string;
}
export interface ObservedFlowEvent {
    id: string;
    stage: string;
    name: string;
    ts: number;
    dur: number;
    durMs: number;
    processName?: string;
    threadName?: string;
    trackId?: number;
    utid?: number;
    upid?: number;
    threadStateId?: number;
    criticalTaskId?: string;
    laneId?: string;
    evidenceSource: string;
    relatedFrame?: string;
    relatedLayer?: string;
    confidence: number;
}
export interface ObservedFlowDependency {
    fromLaneId: string;
    toLaneId: string;
    relation: 'produces_to' | 'composes_to' | 'presents_to' | 'overlaps_with' | 'wakes_to' | 'critical_path_to';
    confidence: number;
    evidenceSource: string;
    fromEventId?: string;
    toEventId?: string;
    fromTaskId?: string;
    toTaskId?: string;
    detail?: string;
}
export interface ObservedFlowWakeupRef {
    threadStateId?: number;
    utid?: number;
    processName?: string;
    threadName?: string;
    state?: string;
    irqContext?: boolean;
    kind?: 'irq' | 'swapper' | 'thread' | 'unknown';
}
export interface ObservedFlowCriticalTask {
    id: string;
    kind: 'direct_wakeup' | 'critical_path_segment';
    rootEventId: string;
    rootLaneId?: string;
    laneId?: string;
    name: string;
    ts: number;
    dur: number;
    durMs: number;
    processName?: string;
    threadName?: string;
    utid?: number;
    threadStateId?: number;
    state?: string;
    tableName?: string;
    stackDepth?: number;
    waker?: ObservedFlowWakeupRef;
    evidenceSource: string;
    confidence: number;
}
export interface ObservedFlow {
    schemaVersion: 'observed-flow.v1';
    context: {
        traceId: string;
        packageName?: string;
        processName?: string;
        timeRange?: {
            startTs: number;
            endTs: number;
            source: string;
        };
        selection?: Record<string, unknown>;
        sourcePriority: string[];
        fallbackUsed?: string;
    };
    lanes: ObservedFlowLane[];
    events: ObservedFlowEvent[];
    dependencies: ObservedFlowDependency[];
    criticalTasks?: ObservedFlowCriticalTask[];
    completeness: {
        level: 'high' | 'medium' | 'low';
        missingSignals: string[];
        warnings: string[];
    };
}
export interface TeachingWarning {
    code: string;
    severity: 'info' | 'warning' | 'error';
    message: string;
    source: 'detection' | 'observed_flow' | 'pin' | 'overlay' | 'teaching';
}
export interface TeachingPinPlan {
    status: 'planned' | 'empty' | 'partial' | 'failed';
    instructions: PinInstructionResponse[];
    expectedLaneIds: string[];
    expectedTrackHints: ObservedFlowTrackHint[];
    summary: string;
    warnings: string[];
}
export interface TeachingOverlayPlan {
    status: 'ready' | 'empty' | 'partial' | 'failed';
    skillId: 'pipeline_key_slices_overlay';
    eventIds: string[];
    keySliceNames: string[];
    timeRange?: {
        startTs: number;
        endTs: number;
        source: string;
    };
    summary: string;
    warnings: string[];
}
/**
 * Raw pin instruction from YAML (snake_case)
 */
export interface RawPinInstruction {
    pattern: string;
    match_by: 'name' | 'uri';
    priority: number;
    reason: string;
    expand?: boolean;
    main_thread_only?: boolean;
    smart_filter?: RawSmartFilter;
}
/**
 * Raw smart filter config from YAML
 */
export interface RawSmartFilter {
    enabled: boolean;
    description?: string;
    detection_sql?: string;
    fallback_sql?: string;
}
/**
 * Raw teaching content from YAML
 */
export interface RawTeachingContent {
    title: string;
    summary: string;
    mermaid?: string;
    thread_roles: RawThreadRole[];
    key_slices: RawKeySlice[];
}
/**
 * Raw thread role from YAML
 */
export interface RawThreadRole {
    thread: string;
    role: string;
    description?: string;
    trace_tags?: string;
}
/**
 * Raw key slice from YAML
 */
export interface RawKeySlice {
    name: string;
    thread: string;
    description?: string;
}
/**
 * Generic SQL result structure from skill execution
 */
export interface SqlResult {
    columns?: string[];
    rows?: unknown[][];
    error?: string;
}
/**
 * Raw step data returned by SkillExecutor.
 *
 * Note: In rawResults, SkillExecutor returns an array of objects (one per row),
 * not the {columns, rows} table structure used by displayResults.
 */
export type SkillStepData = Array<Record<string, unknown>> | SqlResult;
/**
 * Step result from skill execution
 */
export interface SkillStepResult {
    data?: SkillStepData;
    error?: string;
}
/**
 * Transform raw pin instruction (snake_case) to API response (camelCase)
 *
 * @param raw - Raw pin instruction from YAML
 * @param activeProcesses - Active rendering processes from SQL
 * @returns Transformed pin instruction for frontend
 */
export declare function transformPinInstruction(raw: RawPinInstruction, activeProcesses: ActiveProcess[]): PinInstructionResponse;
/**
 * Transform raw teaching content (snake_case) to API response (camelCase)
 *
 * @param raw - Raw teaching content from YAML
 * @param docPath - Documentation file path
 * @returns Transformed teaching content for frontend
 */
export declare function transformTeachingContent(raw: RawTeachingContent, docPath: string): TeachingContentResponse;
/**
 * Validate and extract active processes from SQL result
 *
 * Uses column name mapping instead of positional access to prevent
 * silent failures when column order changes.
 *
 * @param stepResult - Step result from skill execution
 * @returns Validated array of active processes
 */
export declare function validateActiveProcesses(stepResult: SkillStepResult | undefined): ActiveProcess[];
/**
 * Validate confidence value is in valid range [0, 1]
 *
 * @param value - Raw confidence value
 * @param defaultValue - Default if invalid
 * @returns Validated confidence between 0 and 1
 */
export declare function validateConfidence(value: unknown, defaultValue?: number): number;
/**
 * Safely parse candidates from detection result
 *
 * @param candidates - Raw candidates string or array
 * @param limit - Maximum number of candidates to return
 * @returns Validated array of pipeline candidates
 */
export declare function parseCandidates(candidates: unknown, limit?: number): PipelineCandidate[];
/**
 * Safely parse features from detection result
 *
 * @param features - Raw features string or array
 * @returns Validated array of detected features
 */
export declare function parseFeatures(features: unknown): DetectedFeature[];
/**
 * Type guard to check if value is a valid PinInstructionResponse
 */
export declare function isPinInstructionResponse(value: unknown): value is PinInstructionResponse;
/**
 * Type guard to check if value is a valid ActiveProcess
 */
export declare function isActiveProcess(value: unknown): value is ActiveProcess;
//# sourceMappingURL=teaching.types.d.ts.map