@gracker/smartperfetto 1.0.13

package/dist/config/thresholds.d.ts

@@ -0,0 +1,300 @@
+/**
+ * SmartPerfetto Configurable Thresholds
+ *
+ * This module defines configurable thresholds for performance analysis.
+ * These values were previously hardcoded throughout the codebase but are
+ * now centralized here for:
+ * - Easy customization per device/scenario
+ * - Clear documentation of threshold semantics
+ * - Future extensibility (e.g., device profiles)
+ *
+ * @module config/thresholds
+ */
+/**
+ * Thresholds for classifying jank severity based on rate and count.
+ *
+ * These are used by FrameAgent and other components to determine
+ * whether a jank issue is critical, warning, or informational.
+ */
+export interface JankSeverityThresholds {
+    /** Jank rate (%) above which severity is 'critical' */
+    criticalRate: number;
+    /** Jank count above which severity is 'critical' */
+    criticalCount: number;
+    /** Jank rate (%) above which severity is 'warning' */
+    warningRate: number;
+    /** Jank count above which severity is 'warning' */
+    warningCount: number;
+}
+/**
+ * Default jank severity thresholds.
+ *
+ * Rationale:
+ * - criticalRate (15%): 1 in 7 frames is janky - very noticeable to users
+ * - criticalCount (30): ~0.5s of jank in a typical scroll session
+ * - warningRate (5%): 1 in 20 frames - perceptible to sensitive users
+ * - warningCount (10): ~0.17s of jank - worth investigating
+ *
+ * Note: These thresholds apply to all refresh rates. For 120Hz devices,
+ * the same rate means more absolute jank events but the user perception
+ * of jank rate (%) remains consistent.
+ */
+export declare const DEFAULT_JANK_THRESHOLDS: JankSeverityThresholds;
+/**
+ * Get jank thresholds adjusted for game scenarios.
+ * Games typically have lower frame rates and different tolerance.
+ */
+export declare function getGameJankThresholds(): JankSeverityThresholds;
+/**
+ * Standard refresh rate to VSync period mapping (in nanoseconds).
+ *
+ * This is used when VSync period cannot be detected from the trace
+ * and must be estimated from device configuration.
+ */
+export declare const VSYNC_PERIODS_NS: Record<number, bigint>;
+/**
+ * Default VSync period when refresh rate is unknown.
+ * Uses 120Hz as the modern default for flagship devices.
+ *
+ * Rationale: Most modern Android flagships (2022+) support 120Hz displays.
+ * Using 120Hz as default is more conservative for jank detection:
+ * - A frame that's fine at 60Hz (16ms) would be janky at 120Hz (8.3ms)
+ * - Better to catch potential issues than miss them
+ * - The vsync_config skill will override this with actual trace data
+ */
+export declare const DEFAULT_VSYNC_PERIOD_NS: bigint;
+/**
+ * Number of VSync periods to use when estimating frame end time
+ * from start time (when end_ts and dur_ms are both unavailable).
+ *
+ * Value of 2 accounts for:
+ * - 1 vsync for the frame itself
+ * - 1 vsync buffer for display latency
+ */
+export declare const DEFAULT_VSYNC_PERIODS_FOR_FRAME_ESTIMATION = 2;
+/**
+ * Infer VSync period from trace context or use default.
+ *
+ * Resolution order:
+ * 1. Detected VSync period from trace (vsync_period_ns) - from vsync_config skill
+ * 2. Device refresh rate config (device_refresh_rate)
+ * 3. Default 120Hz (modern flagship assumption)
+ *
+ * @param traceContext - Context containing detected trace properties
+ * @returns VSync period in nanoseconds as BigInt
+ */
+export declare function inferVsyncPeriodNs(traceContext?: {
+    detectedVsyncPeriodNs?: string | bigint | number;
+    deviceRefreshRate?: number;
+}): bigint;
+/**
+ * VRR detection indicators.
+ * Used to determine if a device is using Variable Refresh Rate.
+ */
+export interface VRRIndicators {
+    /** Whether VRR is detected */
+    isVRR: boolean;
+    /** Min observed refresh rate (Hz) */
+    minRefreshRate?: number;
+    /** Max observed refresh rate (Hz) */
+    maxRefreshRate?: number;
+    /** Dominant refresh rate (Hz) - most common during trace */
+    dominantRefreshRate?: number;
+}
+/**
+ * Get jank detection multiplier for VRR devices.
+ *
+ * VRR devices can dynamically adjust refresh rate, so jank detection
+ * needs to account for variable vsync periods. The multiplier adjusts
+ * the frame deadline threshold.
+ *
+ * @param vrr - VRR indicators from trace analysis
+ * @returns Multiplier for frame deadline (1.0 = no adjustment)
+ */
+export declare function getVRRJankMultiplier(vrr: VRRIndicators): number;
+/**
+ * Circuit breaker configuration for user intervention handling.
+ */
+export interface CircuitBreakerThresholds {
+    /** Max times user can force-close per session */
+    maxForceCloseCount: number;
+    /** Cooldown period between force-closes (ms) */
+    forceCloseCooldownMs: number;
+    /** Timeout waiting for user response (ms) */
+    userResponseTimeoutMs: number;
+    /** Number of successes needed to transition HALF_OPEN → CLOSED */
+    halfOpenSuccessThreshold: number;
+}
+/**
+ * Default circuit breaker thresholds.
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_THRESHOLDS: CircuitBreakerThresholds;
+/**
+ * Default concurrency limit for DirectSkillExecutor.
+ *
+ * This limits how many skills can execute in parallel to avoid
+ * overwhelming trace_processor_shell with concurrent queries.
+ */
+export declare const DEFAULT_DIRECT_SKILL_CONCURRENCY = 6;
+/**
+ * Maximum number of frames to analyze per session in deep analysis.
+ *
+ * This prevents runaway analysis on traces with many jank frames.
+ * Can be overridden via skill parameters.
+ */
+export declare const DEFAULT_MAX_FRAMES_PER_SESSION = 8;
+/**
+ * Maximum number of frames per session when cluster-first full analysis is required.
+ *
+ * Used by scrolling strategy stage-2 frame list extraction so we can analyze
+ * significantly more frames (e.g., 50+) and produce actionable K1/K2/K3 clusters.
+ */
+export declare const DEFAULT_CLUSTERING_MAX_FRAMES_PER_SESSION = 200;
+/**
+ * Maximum number of sessions to analyze in overview stage.
+ *
+ * This limits the scope of analysis for very long traces.
+ */
+export declare const DEFAULT_MAX_SESSIONS_TO_ANALYZE = 10;
+/**
+ * Threshold for jank list to be classified as 'critical' severity.
+ *
+ * When the number of detected jank frames exceeds this, the finding
+ * is reported as critical severity in the UI.
+ */
+export declare const JANK_LIST_CRITICAL_THRESHOLD = 20;
+/**
+ * Minimum confidence required to accept analysis results without
+ * triggering additional rounds of investigation.
+ */
+export declare const DEFAULT_CONFIDENCE_THRESHOLD = 0.7;
+/**
+ * Confidence assigned to findings extracted from raw SQL results
+ * (as opposed to AI-generated conclusions).
+ */
+export declare const DEFAULT_RAW_FINDING_CONFIDENCE = 0.75;
+/**
+ * Frame time thresholds for UI display (warning/critical coloring).
+ *
+ * These are derived from VSync periods:
+ * - warningMs: 1 VSync period (16.67ms at 60Hz)
+ * - criticalMs: 2 VSync periods (33.33ms at 60Hz)
+ * - maxCriticalMs: ~6 VSync periods (100ms - severe jank)
+ */
+export interface FrameTimeDisplayThresholds {
+    /** Average frame time warning threshold (ms) */
+    avgWarningMs: number;
+    /** Average frame time critical threshold (ms) */
+    avgCriticalMs: number;
+    /** Max frame time warning threshold (ms) */
+    maxWarningMs: number;
+    /** Max frame time critical threshold (ms) */
+    maxCriticalMs: number;
+}
+/**
+ * Default frame time display thresholds (120Hz assumptions).
+ *
+ * Updated from 60Hz to 120Hz to match modern devices.
+ * These are UI display thresholds; actual jank detection uses vsync_config skill.
+ */
+export declare const DEFAULT_FRAME_TIME_DISPLAY_THRESHOLDS: FrameTimeDisplayThresholds;
+/**
+ * Generate frame time thresholds for a specific refresh rate.
+ *
+ * @param hz - Refresh rate in Hz (must be > 0 and <= 500)
+ * @returns Thresholds for the given refresh rate, or default 60Hz thresholds for invalid input
+ */
+export declare function getFrameTimeThresholdsForHz(hz: number): FrameTimeDisplayThresholds;
+/**
+ * VSync period in nanoseconds for SQL queries.
+ * Used as a constant in SQL WHERE clauses for jank detection.
+ *
+ * Note: We use 16666666 (rounded down from 16666667) for two reasons:
+ * 1. Many existing SQL queries in the codebase use this value
+ * 2. Slightly lower threshold is more conservative (catches edge cases)
+ *
+ * The 1ns difference (0.000001ms) is negligible in practice.
+ */
+export declare const SQL_VSYNC_THRESHOLD_NS = 16666666;
+/**
+ * Double VSync period for jank detection in SQL.
+ * Missing 2+ VSyncs is typically considered jank.
+ */
+export declare const SQL_JANK_THRESHOLD_NS: number;
+/**
+ * Thresholds used in jank_frame_detail.skill.yaml root cause analysis.
+ *
+ * These define when specific conditions trigger diagnostic rules.
+ * Priority order in the YAML determines which rule fires first.
+ *
+ * Design rationale:
+ * - sliceDur (>8ms): Half of 16.7ms vsync, significant for 60Hz
+ * - gpuFence (>3ms): Noticeable GPU blocking
+ * - schedLatency (>5ms): Severe scheduling issue
+ * - ioBlock (>2ms): IO on main thread is problematic
+ * - totalSchedLatency (>3ms): Cumulative runnable wait
+ * - q3 (>20%): Significant CPU contention
+ * - q4 (>30%): Too much blocking/sleeping
+ * - bigFreq (<1200MHz): Below typical boost frequency
+ * - bigLoadPct (>90%): CPU cluster near saturation
+ */
+export declare const ROOT_CAUSE_THRESHOLDS: {
+    sliceDurCritical: number;
+    sliceDurWarning: number;
+    gpuFenceCritical: number;
+    gpuFenceWarning: number;
+    schedLatencyCritical: number;
+    q3CriticalPct: number;
+    ioBlockCritical: number;
+    totalSchedLatencyCritical: number;
+    q4WarningPct: number;
+    renderQ4WarningPct: number;
+    q2WarningPct: number;
+    bigFreqWarningMhz: number;
+    bigLoadCriticalPct: number;
+    bigLoadWarningPct: number;
+};
+export declare const ANALYSIS_THRESHOLDS: {
+    jank: JankSeverityThresholds;
+    circuitBreaker: CircuitBreakerThresholds;
+    vsync: {
+        periods: Record<number, bigint>;
+        default: bigint;
+        framesForEstimation: number;
+    };
+    execution: {
+        directSkillConcurrency: number;
+        maxFramesPerSession: number;
+        clusteringMaxFramesPerSession: number;
+        maxSessionsToAnalyze: number;
+    };
+    confidence: {
+        threshold: number;
+        rawFinding: number;
+    };
+    ui: {
+        jankListCriticalThreshold: number;
+        frameTimeDisplay: FrameTimeDisplayThresholds;
+    };
+    sql: {
+        vsyncThresholdNs: number;
+        jankThresholdNs: number;
+    };
+    rootCause: {
+        sliceDurCritical: number;
+        sliceDurWarning: number;
+        gpuFenceCritical: number;
+        gpuFenceWarning: number;
+        schedLatencyCritical: number;
+        q3CriticalPct: number;
+        ioBlockCritical: number;
+        totalSchedLatencyCritical: number;
+        q4WarningPct: number;
+        renderQ4WarningPct: number;
+        q2WarningPct: number;
+        bigFreqWarningMhz: number;
+        bigLoadCriticalPct: number;
+        bigLoadWarningPct: number;
+    };
+};
+//# sourceMappingURL=thresholds.d.ts.map

package/dist/config/thresholds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.d.ts","sourceRoot":"","sources":["../../src/config/thresholds.ts"],"names":[],"mappings":"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"}

package/dist/config/thresholds.js

@@ -0,0 +1,338 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANALYSIS_THRESHOLDS = exports.ROOT_CAUSE_THRESHOLDS = exports.SQL_JANK_THRESHOLD_NS = exports.SQL_VSYNC_THRESHOLD_NS = exports.DEFAULT_FRAME_TIME_DISPLAY_THRESHOLDS = exports.DEFAULT_RAW_FINDING_CONFIDENCE = exports.DEFAULT_CONFIDENCE_THRESHOLD = exports.JANK_LIST_CRITICAL_THRESHOLD = exports.DEFAULT_MAX_SESSIONS_TO_ANALYZE = exports.DEFAULT_CLUSTERING_MAX_FRAMES_PER_SESSION = exports.DEFAULT_MAX_FRAMES_PER_SESSION = exports.DEFAULT_DIRECT_SKILL_CONCURRENCY = exports.DEFAULT_CIRCUIT_BREAKER_THRESHOLDS = exports.DEFAULT_VSYNC_PERIODS_FOR_FRAME_ESTIMATION = exports.DEFAULT_VSYNC_PERIOD_NS = exports.VSYNC_PERIODS_NS = exports.DEFAULT_JANK_THRESHOLDS = void 0;
+exports.getGameJankThresholds = getGameJankThresholds;
+exports.inferVsyncPeriodNs = inferVsyncPeriodNs;
+exports.getVRRJankMultiplier = getVRRJankMultiplier;
+exports.getFrameTimeThresholdsForHz = getFrameTimeThresholdsForHz;
+/**
+ * Default jank severity thresholds.
+ *
+ * Rationale:
+ * - criticalRate (15%): 1 in 7 frames is janky - very noticeable to users
+ * - criticalCount (30): ~0.5s of jank in a typical scroll session
+ * - warningRate (5%): 1 in 20 frames - perceptible to sensitive users
+ * - warningCount (10): ~0.17s of jank - worth investigating
+ *
+ * Note: These thresholds apply to all refresh rates. For 120Hz devices,
+ * the same rate means more absolute jank events but the user perception
+ * of jank rate (%) remains consistent.
+ */
+exports.DEFAULT_JANK_THRESHOLDS = {
+    criticalRate: 15,
+    criticalCount: 30,
+    warningRate: 5,
+    warningCount: 10,
+};
+/**
+ * Get jank thresholds adjusted for game scenarios.
+ * Games typically have lower frame rates and different tolerance.
+ */
+function getGameJankThresholds() {
+    return {
+        criticalRate: 10, // Games: lower tolerance
+        criticalCount: 20,
+        warningRate: 3,
+        warningCount: 5,
+    };
+}
+// =============================================================================
+// VSync Period Configuration
+// =============================================================================
+/**
+ * Standard refresh rate to VSync period mapping (in nanoseconds).
+ *
+ * This is used when VSync period cannot be detected from the trace
+ * and must be estimated from device configuration.
+ */
+exports.VSYNC_PERIODS_NS = {
+    60: 16666667n, // 16.67ms
+    90: 11111111n, // 11.11ms
+    120: 8333333n, // 8.33ms
+    144: 6944444n, // 6.94ms
+    165: 6060606n, // 6.06ms
+    240: 4166667n, // 4.17ms
+};
+/**
+ * Default VSync period when refresh rate is unknown.
+ * Uses 120Hz as the modern default for flagship devices.
+ *
+ * Rationale: Most modern Android flagships (2022+) support 120Hz displays.
+ * Using 120Hz as default is more conservative for jank detection:
+ * - A frame that's fine at 60Hz (16ms) would be janky at 120Hz (8.3ms)
+ * - Better to catch potential issues than miss them
+ * - The vsync_config skill will override this with actual trace data
+ */
+exports.DEFAULT_VSYNC_PERIOD_NS = exports.VSYNC_PERIODS_NS[120];
+/**
+ * Number of VSync periods to use when estimating frame end time
+ * from start time (when end_ts and dur_ms are both unavailable).
+ *
+ * Value of 2 accounts for:
+ * - 1 vsync for the frame itself
+ * - 1 vsync buffer for display latency
+ */
+exports.DEFAULT_VSYNC_PERIODS_FOR_FRAME_ESTIMATION = 2;
+/**
+ * Infer VSync period from trace context or use default.
+ *
+ * Resolution order:
+ * 1. Detected VSync period from trace (vsync_period_ns) - from vsync_config skill
+ * 2. Device refresh rate config (device_refresh_rate)
+ * 3. Default 120Hz (modern flagship assumption)
+ *
+ * @param traceContext - Context containing detected trace properties
+ * @returns VSync period in nanoseconds as BigInt
+ */
+function inferVsyncPeriodNs(traceContext) {
+    // Try detected value first (from vsync_config skill)
+    if (traceContext?.detectedVsyncPeriodNs) {
+        try {
+            const detected = BigInt(traceContext.detectedVsyncPeriodNs);
+            if (detected > 0n)
+                return detected;
+        }
+        catch {
+            // Fall through to next option
+        }
+    }
+    // Try device refresh rate
+    if (traceContext?.deviceRefreshRate) {
+        const rate = traceContext.deviceRefreshRate;
+        if (exports.VSYNC_PERIODS_NS[rate]) {
+            return exports.VSYNC_PERIODS_NS[rate];
+        }
+        // Calculate for non-standard refresh rates
+        if (rate > 0 && rate <= 500) {
+            return BigInt(Math.round(1000000000 / rate));
+        }
+    }
+    // Default to 120Hz (modern flagship devices)
+    return exports.DEFAULT_VSYNC_PERIOD_NS;
+}
+/**
+ * Get jank detection multiplier for VRR devices.
+ *
+ * VRR devices can dynamically adjust refresh rate, so jank detection
+ * needs to account for variable vsync periods. The multiplier adjusts
+ * the frame deadline threshold.
+ *
+ * @param vrr - VRR indicators from trace analysis
+ * @returns Multiplier for frame deadline (1.0 = no adjustment)
+ */
+function getVRRJankMultiplier(vrr) {
+    if (!vrr.isVRR) {
+        return 1.0; // Fixed refresh rate - no adjustment
+    }
+    // VRR devices: use a more lenient threshold since frame timing varies
+    // If dominant rate is known, use that as baseline
+    if (vrr.dominantRefreshRate && vrr.maxRefreshRate) {
+        // Allow more tolerance when refresh rate varies significantly
+        const variation = vrr.maxRefreshRate / vrr.dominantRefreshRate;
+        if (variation > 1.5) {
+            return 1.3; // High variation: 30% more lenient
+        }
+        return 1.15; // Moderate variation: 15% more lenient
+    }
+    return 1.2; // Default VRR adjustment: 20% more lenient
+}
+/**
+ * Default circuit breaker thresholds.
+ */
+exports.DEFAULT_CIRCUIT_BREAKER_THRESHOLDS = {
+    maxForceCloseCount: 5,
+    forceCloseCooldownMs: 30000, // 30 seconds
+    userResponseTimeoutMs: 5 * 60 * 1000, // 5 minutes
+    halfOpenSuccessThreshold: 3,
+};
+// =============================================================================
+// Execution Concurrency
+// =============================================================================
+/**
+ * Default concurrency limit for DirectSkillExecutor.
+ *
+ * This limits how many skills can execute in parallel to avoid
+ * overwhelming trace_processor_shell with concurrent queries.
+ */
+exports.DEFAULT_DIRECT_SKILL_CONCURRENCY = 6;
+// =============================================================================
+// Analysis Depth Limits
+// =============================================================================
+/**
+ * Maximum number of frames to analyze per session in deep analysis.
+ *
+ * This prevents runaway analysis on traces with many jank frames.
+ * Can be overridden via skill parameters.
+ */
+exports.DEFAULT_MAX_FRAMES_PER_SESSION = 8;
+/**
+ * Maximum number of frames per session when cluster-first full analysis is required.
+ *
+ * Used by scrolling strategy stage-2 frame list extraction so we can analyze
+ * significantly more frames (e.g., 50+) and produce actionable K1/K2/K3 clusters.
+ */
+exports.DEFAULT_CLUSTERING_MAX_FRAMES_PER_SESSION = 200;
+/**
+ * Maximum number of sessions to analyze in overview stage.
+ *
+ * This limits the scope of analysis for very long traces.
+ */
+exports.DEFAULT_MAX_SESSIONS_TO_ANALYZE = 10;
+// =============================================================================
+// Jank List Severity (for UI display)
+// =============================================================================
+/**
+ * Threshold for jank list to be classified as 'critical' severity.
+ *
+ * When the number of detected jank frames exceeds this, the finding
+ * is reported as critical severity in the UI.
+ */
+exports.JANK_LIST_CRITICAL_THRESHOLD = 20;
+// =============================================================================
+// Confidence Thresholds
+// =============================================================================
+/**
+ * Minimum confidence required to accept analysis results without
+ * triggering additional rounds of investigation.
+ */
+exports.DEFAULT_CONFIDENCE_THRESHOLD = 0.7;
+/**
+ * Confidence assigned to findings extracted from raw SQL results
+ * (as opposed to AI-generated conclusions).
+ */
+exports.DEFAULT_RAW_FINDING_CONFIDENCE = 0.75;
+/**
+ * Default frame time display thresholds (120Hz assumptions).
+ *
+ * Updated from 60Hz to 120Hz to match modern devices.
+ * These are UI display thresholds; actual jank detection uses vsync_config skill.
+ */
+exports.DEFAULT_FRAME_TIME_DISPLAY_THRESHOLDS = {
+    avgWarningMs: 8.33, // 1 VSync (120Hz)
+    avgCriticalMs: 16.67, // 2 VSyncs (120Hz)
+    maxWarningMs: 16.67, // 2 VSyncs (120Hz)
+    maxCriticalMs: 100, // ~12 VSyncs (severe)
+};
+/**
+ * Generate frame time thresholds for a specific refresh rate.
+ *
+ * @param hz - Refresh rate in Hz (must be > 0 and <= 500)
+ * @returns Thresholds for the given refresh rate, or default 60Hz thresholds for invalid input
+ */
+function getFrameTimeThresholdsForHz(hz) {
+    // Guard against invalid refresh rates
+    if (!hz || hz <= 0 || hz > 500 || !Number.isFinite(hz)) {
+        return exports.DEFAULT_FRAME_TIME_DISPLAY_THRESHOLDS;
+    }
+    const vsyncMs = 1000 / hz;
+    return {
+        avgWarningMs: vsyncMs,
+        avgCriticalMs: vsyncMs * 2,
+        maxWarningMs: vsyncMs * 2,
+        maxCriticalMs: 100, // Absolute max, not scaled
+    };
+}
+// =============================================================================
+// SQL Query VSync Threshold (nanoseconds)
+// =============================================================================
+/**
+ * VSync period in nanoseconds for SQL queries.
+ * Used as a constant in SQL WHERE clauses for jank detection.
+ *
+ * Note: We use 16666666 (rounded down from 16666667) for two reasons:
+ * 1. Many existing SQL queries in the codebase use this value
+ * 2. Slightly lower threshold is more conservative (catches edge cases)
+ *
+ * The 1ns difference (0.000001ms) is negligible in practice.
+ */
+exports.SQL_VSYNC_THRESHOLD_NS = 16666666;
+/**
+ * Double VSync period for jank detection in SQL.
+ * Missing 2+ VSyncs is typically considered jank.
+ */
+exports.SQL_JANK_THRESHOLD_NS = exports.SQL_VSYNC_THRESHOLD_NS * 2;
+// =============================================================================
+// Root Cause Analysis Thresholds
+// =============================================================================
+/**
+ * Thresholds used in jank_frame_detail.skill.yaml root cause analysis.
+ *
+ * These define when specific conditions trigger diagnostic rules.
+ * Priority order in the YAML determines which rule fires first.
+ *
+ * Design rationale:
+ * - sliceDur (>8ms): Half of 16.7ms vsync, significant for 60Hz
+ * - gpuFence (>3ms): Noticeable GPU blocking
+ * - schedLatency (>5ms): Severe scheduling issue
+ * - ioBlock (>2ms): IO on main thread is problematic
+ * - totalSchedLatency (>3ms): Cumulative runnable wait
+ * - q3 (>20%): Significant CPU contention
+ * - q4 (>30%): Too much blocking/sleeping
+ * - bigFreq (<1200MHz): Below typical boost frequency
+ * - bigLoadPct (>90%): CPU cluster near saturation
+ */
+exports.ROOT_CAUSE_THRESHOLDS = {
+    // Priority 1: Main thread slice duration (ms)
+    sliceDurCritical: 8,
+    sliceDurWarning: 3,
+    // Priority 2: GPU Fence wait (ms)
+    gpuFenceCritical: 3,
+    gpuFenceWarning: 1,
+    // Priority 3: Single scheduling latency (ms)
+    schedLatencyCritical: 5,
+    // Priority 4: Runnable percentage (Q3)
+    q3CriticalPct: 20,
+    // Priority 5: IO blocking (ms)
+    ioBlockCritical: 2,
+    // Priority 6: Total scheduling latency (ms)
+    totalSchedLatencyCritical: 3,
+    // Priority 7: Sleep/blocking percentage (Q4)
+    q4WarningPct: 30,
+    // Priority 8: RenderThread Q4 percentage
+    renderQ4WarningPct: 50,
+    // Priority 9: Small core percentage (Q2)
+    q2WarningPct: 50,
+    // Priority 10: Big core frequency (MHz)
+    bigFreqWarningMhz: 1200,
+    // Priority 11: Big cluster load percentage
+    bigLoadCriticalPct: 90,
+    bigLoadWarningPct: 70,
+    // Priority 12-13: Already covered by gpuFence thresholds
+    // Priority 14: Lower slice duration warning
+    // Already covered by sliceDurWarning
+};
+// =============================================================================
+// Export All Defaults for Easy Access
+// =============================================================================
+exports.ANALYSIS_THRESHOLDS = {
+    jank: exports.DEFAULT_JANK_THRESHOLDS,
+    circuitBreaker: exports.DEFAULT_CIRCUIT_BREAKER_THRESHOLDS,
+    vsync: {
+        periods: exports.VSYNC_PERIODS_NS,
+        default: exports.DEFAULT_VSYNC_PERIOD_NS,
+        framesForEstimation: exports.DEFAULT_VSYNC_PERIODS_FOR_FRAME_ESTIMATION,
+    },
+    execution: {
+        directSkillConcurrency: exports.DEFAULT_DIRECT_SKILL_CONCURRENCY,
+        maxFramesPerSession: exports.DEFAULT_MAX_FRAMES_PER_SESSION,
+        clusteringMaxFramesPerSession: exports.DEFAULT_CLUSTERING_MAX_FRAMES_PER_SESSION,
+        maxSessionsToAnalyze: exports.DEFAULT_MAX_SESSIONS_TO_ANALYZE,
+    },
+    confidence: {
+        threshold: exports.DEFAULT_CONFIDENCE_THRESHOLD,
+        rawFinding: exports.DEFAULT_RAW_FINDING_CONFIDENCE,
+    },
+    ui: {
+        jankListCriticalThreshold: exports.JANK_LIST_CRITICAL_THRESHOLD,
+        frameTimeDisplay: exports.DEFAULT_FRAME_TIME_DISPLAY_THRESHOLDS,
+    },
+    sql: {
+        vsyncThresholdNs: exports.SQL_VSYNC_THRESHOLD_NS,
+        jankThresholdNs: exports.SQL_JANK_THRESHOLD_NS,
+    },
+    rootCause: exports.ROOT_CAUSE_THRESHOLDS,
+};
+//# sourceMappingURL=thresholds.js.map

package/dist/config/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../src/config/thresholds.ts"],"names":[],"mappings":"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"}