observability-toolkit 2.0.0 → 2.1.1

package/dist/lib/quality/quality-feature-engineering.js

@@ -0,0 +1,2076 @@
+/**
+ * Feature Engineering for Evaluation Analytics (Design Doc Section 16)
+ *
+ * Derived features, adaptive score scaling, label encoding, and composite metrics
+ * computed from existing evaluation data. Enhances anomaly detection, correlation
+ * discovery, and role-appropriate information presentation.
+ *
+ * @see quality-metrics.ts for core types
+ * @see frontend/docs/llm-explainability-design.md Section 16
+ */
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { z } from 'zod';
+import { normalizedScoreSchema } from '../core/shared-schemas.js';
+import { pipe, map, filter, sort } from 'remeda';
+import { roundTo, SCORE_PRECISION, } from './quality-metrics.js';
+import { AUDITOR_EXPLANATION_TRUNCATION, AUDITOR_MAX_WORST_EVALUATIONS, BINARY_SCALE_EXCELLENT_THRESHOLD, CONFIRMATION_MIN_CONSECUTIVE_BREACHES, COVERAGE_SAMPLE_HIGH_THRESHOLD, COVERAGE_SAMPLE_LOW_THRESHOLD, DYNAMICS_CONFIDENCE_BASE, DYNAMICS_CONFIDENCE_MAX, DYNAMICS_CONFIDENCE_STEP, EWMA_BASELINE_FRACTION, EWMA_BASELINE_MIN_POINTS, EWMA_DRIFT_MIN_VALUES, EWMA_RANGE_FALLBACK_RATIO, EXECUTIVE_EXPLANATION_TRUNCATION, EXECUTIVE_MAX_WORST_EVALUATIONS, GRANGER_FIXED_LAG_ORDER, LATENCY_NORMALIZATION_MAX_SECONDS, LATENCY_SKEW_SIGNAL_THRESHOLD, LOG_SCALE_DIVISOR, MAD_CONSISTENCY_FACTOR, MIN_PERIOD_HOURS, NUMERICAL_MIN_DENOMINATOR, OPERATOR_MAX_WORST_EVALUATIONS, SCORE_BAND_ADEQUATE, SCORE_BAND_EXCELLENT, SCORE_BAND_GOOD, SCORE_BAND_POOR, STEP_SCALE_ADEQUATE_THRESHOLD, STEP_SCALE_EXCELLENT_THRESHOLD, DEGRADATION_BASELINE_RATIO, DEGRADATION_STATE_FILE, MIN_BUCKETS_FOR_SIGNAL, CALIBRATION_WINDOW_DAYS, PSI_RECALIBRATION_THRESHOLD, CALIBRATION_STATE_FILE, DEFAULT_BIN_COUNT, PSI_LOG_EPSILON, AHP_RANDOM_INDEX, AHP_CRITIC_DEFAULT_ALPHA, TUNED_CQI_WEIGHTS_FEATURE_VERSION, } from './quality-constants.js';
+import { TIME_MS, } from '../core/units.js';
+import { TEXT_PREVIEW_LIMIT } from '../core/constants.js';
+import * as ss from 'simple-statistics';
+import tCdf from '@stdlib/stats-base-dists-t-cdf';
+import fCdf from '@stdlib/stats-base-dists-f-cdf';
+import { DDSketch } from '@datadog/sketches-js';
+import { Matrix, solve } from 'ml-matrix';
+const QUANTILE_P10 = 0.1;
+const QUANTILE_P25 = 0.25;
+const QUANTILE_P50 = 0.5;
+const QUANTILE_P75 = 0.75;
+const QUANTILE_P90 = 0.9;
+const DEFAULT_SENSITIVITY_DELTA = 0.05;
+const CORRELATION_MIN_POINTS = 3;
+const FORMAT_JSON_INDENT_SPACES = 2;
+/** Default scale strategy per metric */
+export const METRIC_SCALE_STRATEGY = {
+    relevance: 'quantile',
+    faithfulness: 'binary',
+    coherence: 'uniform',
+    hallucination: 'log',
+    task_completion: 'step',
+    tool_correctness: 'categorical',
+    evaluation_latency: 'percentile_rank',
+};
+/**
+ * Map a score value to a 5-band color band with direction awareness.
+ * For 'minimize' metrics (hallucination, latency), low scores are excellent.
+ * For 'maximize' metrics (relevance, faithfulness), high scores are excellent.
+ */
+export function scoreColorBand(value, direction = 'maximize') {
+    const v = direction === 'minimize' ? 1 - value : value;
+    if (v >= SCORE_BAND_EXCELLENT)
+        return 'excellent';
+    if (v >= SCORE_BAND_GOOD)
+        return 'good';
+    if (v >= SCORE_BAND_ADEQUATE)
+        return 'adequate';
+    if (v >= SCORE_BAND_POOR)
+        return 'poor';
+    return 'failing';
+}
+// ============================================================================
+// Zod Schemas for Feature Engineering Types
+// ============================================================================
+/**
+ * Zod schemas for runtime validation of quality feature types.
+ * Used for state persistence and API data validation.
+ */
+export const percentileDistributionSchema = z.object({
+    p10: normalizedScoreSchema,
+    p25: normalizedScoreSchema,
+    p50: normalizedScoreSchema,
+    p75: normalizedScoreSchema,
+    p90: normalizedScoreSchema,
+});
+export const scoreDirectionSchema = z.enum(['maximize', 'minimize']);
+export const scaleStrategySchema = z.enum([
+    'quantile',
+    'binary',
+    'uniform',
+    'log',
+    'step',
+    'categorical',
+    'percentile_rank',
+]);
+export const scoreColorBandSchema = z.enum(['excellent', 'good', 'adequate', 'poor', 'failing']);
+export const degradationStateSchema = z.object({
+    lastRun: z.string(),
+    breaches: z.record(z.string(), z.int().nonnegative()),
+});
+export const calibrationStateSchema = z.object({
+    lastCalibrated: z.string(),
+    distributions: z.record(z.string(), z.object({
+        distribution: percentileDistributionSchema,
+        sampleSize: z.int().nonnegative(),
+        windowStart: z.string(),
+        windowEnd: z.string(),
+    })),
+    psiValues: z.record(z.string(), z.number()).optional(),
+    rawScores: z.record(z.string(), z.array(z.number())).optional(),
+});
+export const psiResultSchema = z.object({
+    psi: z.number().nonnegative(),
+    drifted: z.boolean(),
+});
+export const backtestConfigSchema = z.object({
+    varianceThreshold: z.number().positive(),
+    coverageDropoutThreshold: normalizedScoreSchema,
+    latencySkewThreshold: z.number().positive(),
+    confirmationWindow: z.int().positive(),
+    ewmaLambda: normalizedScoreSchema.optional().describe('EWMA smoothing factor for drift detection (0–1). Default: EWMA_LAMBDA'),
+    stabilityThreshold: z.number().positive().optional().describe('Number of MAD multiples above baseline that constitute drift'),
+});
+export const backtestSnapshotSchema = z.object({
+    currentStdDev: z.number().nonnegative(),
+    baselineStdDev: z.number().nonnegative(),
+    coverageGapCount: z.int().nonnegative(),
+    totalCoverageCells: z.int().nonnegative(),
+    latencyP95: z.number().nonnegative().optional(),
+    latencyP50: z.number().nonnegative().optional(),
+});
+export const taprMetricsSchema = z.object({
+    precision: normalizedScoreSchema,
+    recall: normalizedScoreSchema,
+    f1: normalizedScoreSchema,
+    detectionDelay: z.number().nonnegative(),
+});
+export const degradationBacktestResultSchema = z.object({
+    config: backtestConfigSchema,
+    truePositives: z.int().nonnegative(),
+    falsePositives: z.int().nonnegative(),
+    falseNegatives: z.int().nonnegative(),
+    trueNegatives: z.int().nonnegative(),
+    tapr: taprMetricsSchema,
+    pointPrecision: normalizedScoreSchema,
+    pointRecall: normalizedScoreSchema,
+    pointF1: normalizedScoreSchema,
+});
+export const backtestSweepResultSchema = z.object({
+    results: z.array(degradationBacktestResultSchema),
+    bestByF1: degradationBacktestResultSchema,
+    bestByRecall: degradationBacktestResultSchema,
+    currentConfigResult: degradationBacktestResultSchema,
+});
+export const ahpComparisonSchema = z.object({
+    metricA: z.string().min(1),
+    metricB: z.string().min(1),
+    preference: z.enum(['1', '3', '5', '7', '9']).transform((v) => parseInt(v)),
+    preferred: z.enum(['A', 'B']),
+}).refine((data) => data.metricA < data.metricB, {
+    error: 'metricA must be less than metricB (alphabetically sorted)'
+});
+export const tunedCQIWeightsSchema = z.object({
+    featureVersion: z.string(),
+    weights: z.record(z.string(), normalizedScoreSchema),
+    ahpWeights: z.record(z.string(), z.number().nonnegative()),
+    criticWeights: z.record(z.string(), z.number().nonnegative()),
+    alpha: z.number(),
+    consistencyRatio: z.number(),
+    incidentCorrelations: z.record(z.string(), z.number()),
+});
+/**
+ * Compute empirical CDF position for a value within a percentile distribution.
+ * Returns 0-1 representing where the value falls in the empirical distribution.
+ * Uses linear interpolation between known percentile points.
+ */
+export function empiricalCDF(value, dist) {
+    if (!Number.isFinite(value))
+        return QUANTILE_P50;
+    const points = [
+        [dist.p10, QUANTILE_P10],
+        [dist.p25, QUANTILE_P25],
+        [dist.p50, QUANTILE_P50],
+        [dist.p75, QUANTILE_P75],
+        [dist.p90, QUANTILE_P90],
+    ];
+    // Below p10
+    if (value <= dist.p10)
+        return Math.max(0, QUANTILE_P10 * (value / Math.max(dist.p10, NUMERICAL_MIN_DENOMINATOR)));
+    // Above p90
+    if (value >= dist.p90)
+        return Math.min(1, QUANTILE_P90 + QUANTILE_P10 * Math.min(1, (value - dist.p90) / Math.max(1 - dist.p90, NUMERICAL_MIN_DENOMINATOR)));
+    // Linear interpolation between adjacent percentile points
+    for (let i = 0; i < points.length - 1; i++) {
+        const [v0, p0] = points[i];
+        const [v1, p1] = points[i + 1];
+        if (value >= v0 && value <= v1) {
+            const range = v1 - v0;
+            if (range === 0)
+                return p0;
+            return p0 + (p1 - p0) * ((value - v0) / range);
+        }
+    }
+    return QUANTILE_P50; // Fallback
+}
+/**
+ * Minimum sample size for quantile-based scaling to be considered valid.
+ * Below this threshold, quantile scaling falls back to uniform even when
+ * distribution data is provided (insufficient data for reliable percentiles).
+ */
+export const MIN_QUANTILE_SAMPLE_SIZE = 100;
+/**
+ * Adaptive score color band using per-metric scaling strategies.
+ * Falls back to uniform scoreColorBand when distribution data is unavailable.
+ *
+ * @param value - Raw score value
+ * @param metric - Metric name (used to look up ScaleStrategy)
+ * @param direction - Score direction (maximize or minimize)
+ * @param distribution - Optional empirical percentile distribution for quantile scaling
+ * @param sampleSize - Number of samples used to compute distribution; quantile requires >= 100
+ * @example
+ * ```ts
+ * adaptiveScoreColorBand(0.92, 'relevance');                   // 'excellent' (uniform, maximize)
+ * adaptiveScoreColorBand(0.3, 'hallucination', 'minimize');    // 'excellent' (low hallucination is good)
+ * adaptiveScoreColorBand(0.5, 'coherence', 'maximize', dist, 200); // quantile-scaled band
+ * ```
+ */
+export function adaptiveScoreColorBand(value, metric, direction = 'maximize', distribution, sampleSize) {
+    const strategy = METRIC_SCALE_STRATEGY[metric] ?? 'uniform';
+    switch (strategy) {
+        case 'quantile': {
+            if (!distribution || (sampleSize !== undefined && sampleSize < MIN_QUANTILE_SAMPLE_SIZE)) {
+                return scoreColorBand(value, direction);
+            }
+            const rank = empiricalCDF(value, distribution);
+            return scoreColorBand(rank, 'maximize');
+        }
+        case 'log': {
+            const clamped = Math.max(value, NUMERICAL_MIN_DENOMINATOR);
+            const logNorm = Math.min(1, -Math.log10(clamped) / LOG_SCALE_DIVISOR);
+            return scoreColorBand(logNorm, 'maximize');
+        }
+        case 'binary':
+            return value >= BINARY_SCALE_EXCELLENT_THRESHOLD ? 'excellent' : 'failing';
+        case 'step':
+            // Rule-based: binary pass/fail; LLM-based: standard 5-band
+            return value >= STEP_SCALE_EXCELLENT_THRESHOLD ? 'excellent' : value >= STEP_SCALE_ADEQUATE_THRESHOLD ? 'adequate' : 'failing';
+        case 'categorical':
+            // Display as fraction; color by standard bands
+            return scoreColorBand(value, direction);
+        case 'percentile_rank':
+            // Without distribution data, fall back to uniform
+            if (!distribution)
+                return scoreColorBand(value, direction);
+            return scoreColorBand(empiricalCDF(value, distribution), 'maximize');
+        case 'uniform':
+        default:
+            return scoreColorBand(value, direction);
+    }
+}
+/**
+ * Metrics where lower scores are better. Used as fallback when alert
+ * configuration is unavailable for direction inference.
+ */
+export const MINIMIZE_METRICS = new Set([
+    'hallucination',
+    'evaluation_latency',
+    'error_rate',
+    'cost',
+]);
+/**
+ * Infer ScoreDirection from a metric's alert configuration.
+ * Metrics whose primary alert fires on 'below' are 'maximize' metrics.
+ * Metrics whose primary alert fires on 'above' are 'minimize' metrics.
+ */
+export function inferScoreDirection(alertDirection) {
+    return alertDirection === 'above' ? 'minimize' : 'maximize';
+}
+/** Known label-to-ordinal lookup table */
+const LABEL_ORDINAL_MAP = {
+    // Ordinal 4 - Excellent (Pass)
+    excellent: { ordinal: 4, category: 'Pass' },
+    highly_relevant: { ordinal: 4, category: 'Pass' },
+    fully_faithful: { ordinal: 4, category: 'Pass' },
+    perfect: { ordinal: 4, category: 'Pass' },
+    // Ordinal 3 - Good (Pass)
+    relevant: { ordinal: 3, category: 'Pass' },
+    good: { ordinal: 3, category: 'Pass' },
+    faithful: { ordinal: 3, category: 'Pass' },
+    pass: { ordinal: 3, category: 'Pass' },
+    correct: { ordinal: 3, category: 'Pass' },
+    coherent: { ordinal: 3, category: 'Pass' },
+    // Ordinal 2 - Review
+    partial: { ordinal: 2, category: 'Review' },
+    borderline: { ordinal: 2, category: 'Review' },
+    adequate: { ordinal: 2, category: 'Review' },
+    mixed: { ordinal: 2, category: 'Review' },
+    // Ordinal 1 - Fail
+    off_topic: { ordinal: 1, category: 'Fail' },
+    irrelevant: { ordinal: 1, category: 'Fail' },
+    unfaithful: { ordinal: 1, category: 'Fail' },
+    fail: { ordinal: 1, category: 'Fail' },
+    incorrect: { ordinal: 1, category: 'Fail' },
+    incoherent: { ordinal: 1, category: 'Fail' },
+    // Ordinal 0 - Critical Fail
+    hallucinated: { ordinal: 0, category: 'Fail' },
+    fabricated: { ordinal: 0, category: 'Fail' },
+    toxic: { ordinal: 0, category: 'Fail' },
+    dangerous: { ordinal: 0, category: 'Fail' },
+};
+/**
+ * Normalize a label for lookup: lowercase, replace hyphens with underscores.
+ */
+function normalizeLabel(label) {
+    return label.toLowerCase().replace(/-/g, '_').trim();
+}
+/**
+ * Convert a free-text score label to an ordinal value for sorting/filtering.
+ * Unmapped labels default to ordinal 2 ("Review") with mapped=false.
+ *
+ * @param label - Free-text score label from EvaluationResult.scoreLabel
+ * @returns Ordinal encoding with category and mapping status
+ */
+export function labelToOrdinal(label) {
+    const normalized = normalizeLabel(label);
+    const entry = LABEL_ORDINAL_MAP[normalized];
+    if (entry) {
+        return { ordinal: entry.ordinal, category: entry.category, mapped: true };
+    }
+    // Default: unmapped labels are "Review" with ordinal 2
+    return { ordinal: 2, category: 'Review', mapped: false };
+}
+/**
+ * Get the label filter category for a given ordinal value.
+ */
+export function ordinalToCategory(ordinal) {
+    if (ordinal >= 3)
+        return 'Pass';
+    if (ordinal === 2)
+        return 'Review';
+    return 'Fail';
+}
+// ============================================================================
+// Composite Quality Index (Section 16.3)
+// ============================================================================
+/** CQI per-metric contribution breakdown */
+export const cqiContributionSchema = z.object({
+    metric: z.string(),
+    rawScore: z.number(),
+    normalizedScore: z.number(),
+    weight: z.number(),
+    contribution: z.number(),
+});
+/** Composite Quality Index result */
+export const compositeQualityIndexSchema = z.object({
+    /** Feature version for historical comparison validity */
+    featureVersion: z.string(),
+    /** Weighted composite value (0-1) */
+    value: normalizedScoreSchema,
+    /** Weight configuration used */
+    weights: z.record(z.string(), z.number()),
+    /** Per-metric breakdown */
+    contributions: z.array(cqiContributionSchema),
+});
+// ============================================================================
+// CQI Weight Constants
+// ============================================================================
+const CQI_WEIGHT_RELEVANCE = 0.25;
+const CQI_WEIGHT_FAITHFULNESS = 0.20;
+const CQI_WEIGHT_HALLUCINATION = 0.20;
+const CQI_WEIGHT_TASK_COMPLETION = 0.15;
+const CQI_WEIGHT_COHERENCE = 0.10;
+const CQI_WEIGHT_TOOL_CORRECTNESS = 0.05;
+const CQI_WEIGHT_EVALUATION_LATENCY = 0.05;
+/** Default CQI weights per design doc Section 16.3 */
+export const DEFAULT_CQI_WEIGHTS = {
+    relevance: CQI_WEIGHT_RELEVANCE,
+    faithfulness: CQI_WEIGHT_FAITHFULNESS,
+    hallucination: CQI_WEIGHT_HALLUCINATION,
+    task_completion: CQI_WEIGHT_TASK_COMPLETION,
+    coherence: CQI_WEIGHT_COHERENCE,
+    tool_correctness: CQI_WEIGHT_TOOL_CORRECTNESS,
+    evaluation_latency: CQI_WEIGHT_EVALUATION_LATENCY,
+};
+/** Current feature version for CQI */
+const CQI_FEATURE_VERSION = '1.0';
+/**
+ * Compute Composite Quality Index from metric results.
+ * Direction-normalizes scores before weighting (minimize metrics are inverted).
+ * Metrics with no data are excluded; weights are renormalized over available metrics.
+ *
+ * @param metrics - Quality metric results from dashboard summary
+ * @param weights - Optional custom weights (default: DEFAULT_CQI_WEIGHTS)
+ * @returns CQI result, or undefined if no metrics have data
+ * @example
+ * ```ts
+ * const cqi = computeCQI(dashboardSummary.metrics);
+ * // { score: 0.82, band: 'good', contributions: [...], featureVersion: '1.0' }
+ *
+ * // Custom weights emphasizing relevance
+ * const custom = computeCQI(metrics, { relevance: 0.4, faithfulness: 0.3, coherence: 0.3 });
+ * ```
+ */
+export function computeCQI(metrics, weights) {
+    const w = weights ?? DEFAULT_CQI_WEIGHTS;
+    const contributions = [];
+    let totalWeight = 0;
+    for (const metric of metrics) {
+        const weight = w[metric.name];
+        if (weight === undefined || weight <= 0)
+            continue;
+        // Use avg as the primary aggregation for CQI
+        const rawScore = metric.values.avg;
+        if (rawScore === null)
+            continue;
+        // Direction-normalize: minimize metrics (hallucination, eval_latency) are inverted
+        const direction = inferScoreDirection(metric.alerts[0]?.direction ?? (MINIMIZE_METRICS.has(metric.name) ? 'above' : 'below'));
+        let normalizedScore;
+        if (direction === 'minimize') {
+            // For latency (range 0-LATENCY_NORMALIZATION_MAX_SECONDS), normalize to 0-1 first
+            if (metric.name === 'evaluation_latency') {
+                normalizedScore = Math.max(0, 1 - rawScore / LATENCY_NORMALIZATION_MAX_SECONDS);
+            }
+            else {
+                normalizedScore = 1 - rawScore;
+            }
+        }
+        else {
+            normalizedScore = rawScore;
+        }
+        normalizedScore = Math.max(0, Math.min(1, normalizedScore));
+        totalWeight += weight;
+        contributions.push({
+            metric: metric.name,
+            rawScore: roundTo(rawScore, SCORE_PRECISION),
+            normalizedScore: roundTo(normalizedScore, SCORE_PRECISION),
+            weight,
+            contribution: 0, // placeholder, computed after renormalization
+        });
+    }
+    if (contributions.length === 0 || totalWeight === 0)
+        return undefined;
+    // Renormalize weights and compute contributions so they sum to rawValue
+    for (const c of contributions) {
+        const normalizedWeight = c.weight / totalWeight;
+        c.contribution = roundTo(c.normalizedScore * normalizedWeight, SCORE_PRECISION);
+    }
+    const rawValue = contributions.reduce((sum, c) => sum + c.contribution, 0);
+    return {
+        featureVersion: CQI_FEATURE_VERSION,
+        value: roundTo(rawValue, SCORE_PRECISION),
+        weights: w,
+        contributions,
+    };
+}
+/**
+ * Compute CQI sensitivity by perturbing each weight +/- delta.
+ * Reports the CQI range when each weight varies independently.
+ *
+ * Only metrics with positive base weights are analyzed. Perturbed weights are
+ * not renormalized — computeCQI handles renormalization internally, so the
+ * sensitivity reflects the effect of shifting one weight's relative importance.
+ *
+ * @param metrics - Quality metric results
+ * @param weights - Base weights (default: DEFAULT_CQI_WEIGHTS)
+ * @param delta - Perturbation amount (default: 0.05)
+ * @returns Sensitivity analysis, or undefined if CQI cannot be computed
+ * @example
+ * ```ts
+ * const sens = computeCQISensitivity(metrics);
+ * // { baseValue: 0.82, delta: 0.05, entries: [
+ * //   { metric: 'relevance', baseWeight: 0.25, low: 0.80, high: 0.84, range: 0.04 },
+ * //   ...
+ * // ]}
+ * ```
+ */
+export function computeCQISensitivity(metrics, weights, delta = DEFAULT_SENSITIVITY_DELTA) {
+    const baseWeights = weights ?? DEFAULT_CQI_WEIGHTS;
+    const baseCQI = computeCQI(metrics, baseWeights);
+    if (!baseCQI)
+        return undefined;
+    const entries = pipe(Object.entries(baseWeights), filter(([, weight]) => weight > 0), map(([key, weight]) => {
+        const lowWeights = { ...baseWeights, [key]: Math.max(0, weight - delta) };
+        const highWeights = { ...baseWeights, [key]: weight + delta };
+        const lowCQI = computeCQI(metrics, lowWeights);
+        const highCQI = computeCQI(metrics, highWeights);
+        const low = lowCQI?.value ?? baseCQI.value;
+        const high = highCQI?.value ?? baseCQI.value;
+        return {
+            metric: key,
+            baseWeight: weight,
+            low: roundTo(Math.min(low, high), SCORE_PRECISION),
+            high: roundTo(Math.max(low, high), SCORE_PRECISION),
+            range: roundTo(Math.abs(high - low), SCORE_PRECISION),
+        };
+    }), sort((a, b) => b.range - a.range));
+    return {
+        baseValue: baseCQI.value,
+        delta,
+        entries,
+    };
+}
+const DYNAMICS_FEATURE_VERSION = '1.1';
+/** Default exponential smoothing factor for velocity noise suppression */
+const EMA_ALPHA = 0.3;
+/**
+ * Apply exponential moving average to a sequence of values.
+ * More recent values receive higher weight (alpha).
+ *
+ * @param values - Time-ordered values (oldest first)
+ * @param alpha - Smoothing factor (0-1). Higher = less smoothing.
+ * @returns Smoothed values array of same length
+ */
+function exponentialSmooth(values, alpha) {
+    if (values.length === 0)
+        return [];
+    const result = [values[0]];
+    for (let i = 1; i < values.length; i++) {
+        result.push(alpha * values[i] + (1 - alpha) * result[i - 1]);
+    }
+    return result;
+}
+/**
+ * Compute metric dynamics from consecutive trend snapshots.
+ * When trendHistory is provided, applies exponential smoothing (alpha=0.3)
+ * to suppress noise amplification from second derivatives.
+ *
+ * @param currentTrend - Current period trend
+ * @param previousTrend - Previous period trend (for acceleration)
+ * @param periodHours - Length of each period in hours
+ * @param thresholds - Alert thresholds for breach projection
+ * @param trendHistory - Optional array of historical trends (oldest first) for EMA smoothing
+ * @returns Metric dynamics, or undefined if insufficient data
+ * @example
+ * ```ts
+ * const dynamics = computeMetricDynamics(
+ *   { currentValue: 0.85, previousValue: 0.80, delta: 0.05 },
+ *   { currentValue: 0.80, previousValue: 0.78, delta: 0.02 },
+ *   1, // 1-hour periods
+ *   [{ value: 0.7, direction: 'below', severity: 'warning' }]
+ * );
+ * // { velocity: 0.05, acceleration: 0.03, confidence: 0.5, projectedStatus: 'healthy', ... }
+ * ```
+ */
+export function computeMetricDynamics(currentTrend, previousTrend, periodHours, thresholds, trendHistory) {
+    if (periodHours < MIN_PERIOD_HOURS)
+        return undefined;
+    let velocity;
+    let acceleration = 0;
+    let inflectionDetected = false;
+    if (trendHistory && trendHistory.length >= 2) {
+        // Apply exponential smoothing to the velocity series for noise suppression
+        const rawVelocities = trendHistory.map(t => t.delta / periodHours);
+        const smoothed = exponentialSmooth(rawVelocities, EMA_ALPHA);
+        velocity = smoothed[smoothed.length - 1];
+        // Acceleration from last two smoothed velocities
+        if (smoothed.length >= 2) {
+            const prevSmoothedVel = smoothed[smoothed.length - 2];
+            acceleration = (velocity - prevSmoothedVel) / periodHours;
+            inflectionDetected = prevSmoothedVel !== 0 && Math.sign(velocity) !== Math.sign(prevSmoothedVel);
+        }
+    }
+    else {
+        // Fallback to raw computation (backward-compatible)
+        velocity = currentTrend.delta / periodHours;
+        if (previousTrend) {
+            const previousVelocity = previousTrend.delta / periodHours;
+            acceleration = (velocity - previousVelocity) / periodHours;
+            inflectionDetected = previousVelocity !== 0 && Math.sign(velocity) !== Math.sign(previousVelocity);
+        }
+    }
+    // Confidence: higher with more data points and smoothing
+    // 0.275 (1 trend), 0.35 (2 trends), 0.575 (5 trends), caps at DYNAMICS_CONFIDENCE_MAX (11+ trends)
+    const dataPoints = trendHistory ? trendHistory.length : (previousTrend ? 2 : 1);
+    const confidence = Math.min(DYNAMICS_CONFIDENCE_MAX, DYNAMICS_CONFIDENCE_BASE + DYNAMICS_CONFIDENCE_STEP * dataPoints);
+    // Project breach time
+    let projectedStatus = 'healthy';
+    let projectedBreachTime;
+    if (thresholds && velocity !== 0) {
+        const currentValue = currentTrend.currentValue;
+        const now = Date.now();
+        // Find nearest threshold breach
+        let minBreachHours = Infinity;
+        for (const t of thresholds) {
+            // Determine if velocity is moving toward breach
+            const distanceToThreshold = t.direction === 'above'
+                ? t.value - currentValue // Need to go up to breach
+                : currentValue - t.value; // Need to go down to breach
+            if (distanceToThreshold <= 0) {
+                // Already breached
+                projectedStatus = t.severity === 'critical' ? 'critical' : 'warning';
+                continue;
+            }
+            // Check if velocity is moving toward threshold
+            const movingToward = t.direction === 'above' ? velocity > 0 : velocity < 0;
+            if (!movingToward)
+                continue;
+            const hoursToBreak = distanceToThreshold / Math.abs(velocity);
+            if (hoursToBreak < minBreachHours) {
+                minBreachHours = hoursToBreak;
+                projectedStatus = t.severity === 'critical' ? 'critical' : 'warning';
+                projectedBreachTime = new Date(now + hoursToBreak * TIME_MS.HOUR).toISOString();
+            }
+        }
+    }
+    return {
+        featureVersion: DYNAMICS_FEATURE_VERSION,
+        velocity: roundTo(velocity, SCORE_PRECISION),
+        acceleration: roundTo(acceleration, SCORE_PRECISION),
+        inflectionDetected,
+        projectedStatus,
+        projectedBreachTime,
+        confidence: roundTo(confidence, SCORE_PRECISION),
+    };
+}
+const COVERAGE_CONFIDENCE_VERSION = '2.0';
+/**
+ * Compute Normalized Shannon Entropy (Pielou's J) for distribution uniformity.
+ * Returns 1 for perfectly uniform, 0 for maximally concentrated.
+ *
+ * @param counts - Array of counts per group (e.g., evaluations per metric category)
+ * @returns Normalized Shannon entropy J in [0,1] where 1 = perfectly uniform
+ */
+export function computeNormalizedEntropy(counts) {
+    if (counts.length <= 1)
+        return 1;
+    const total = counts.reduce((s, c) => s + c, 0);
+    if (total === 0)
+        return 0;
+    const k = counts.length;
+    const hMax = Math.log2(k);
+    let h = 0;
+    for (const c of counts) {
+        if (c > 0) {
+            const p = c / total;
+            h -= p * Math.log2(p);
+        }
+    }
+    return roundTo(Math.max(0, Math.min(1, h / hMax)), SCORE_PRECISION);
+}
+/**
+ * Compute coverage-weighted confidence.
+ * Adjusts confidence level based on evaluation distribution uniformity across inputs.
+ * A metric with 100 evaluations all from one session is less representative
+ * than 100 evaluations across 50 sessions.
+ *
+ * @param baseConfidence - Base confidence indicator from computeConfidence()
+ * @param evaluationsPerInput - Count of evaluations per input (session or trace)
+ * @returns Extended confidence with coverage weighting
+ */
+export function computeCoverageWeightedConfidence(baseConfidence, evaluationsPerInput) {
+    const coverageUniformity = computeNormalizedEntropy(evaluationsPerInput);
+    const effectiveSampleSize = roundTo(baseConfidence.sampleCount * coverageUniformity, SCORE_PRECISION);
+    // Recalculate level using effective sample size
+    // Minimum COVERAGE_SAMPLE_HIGH_THRESHOLD effective samples for "high" regardless of uniformity
+    let adjustedLevel;
+    if (effectiveSampleSize < COVERAGE_SAMPLE_LOW_THRESHOLD) {
+        adjustedLevel = 'low';
+    }
+    else if (effectiveSampleSize >= COVERAGE_SAMPLE_HIGH_THRESHOLD && baseConfidence.level !== 'low') {
+        adjustedLevel = 'high';
+    }
+    else {
+        adjustedLevel = 'medium';
+    }
+    return {
+        ...baseConfidence,
+        featureVersion: COVERAGE_CONFIDENCE_VERSION,
+        coverageUniformity,
+        effectiveSampleSize,
+        adjustedLevel,
+    };
+}
+// ============================================================================
+// Degradation Signal (Section 16.1)
+// ============================================================================
+/**
+ * Variance ratio threshold for "increasing" trend detection.
+ * Research R5: shifted from 1.5x (~87% coverage, 13% FP) to 2.0 (~95% coverage, 5% FP).
+ * Aligns with Datadog 2-3 sigma default anomaly bounds.
+ */
+export const VARIANCE_INCREASE_THRESHOLD = 2.0;
+/**
+ * Variance decrease threshold. Ratios below this indicate decreasing variance.
+ * Mirrors VARIANCE_INCREASE_THRESHOLD: values significantly below 1.0 indicate
+ * the metric is converging (less noisy than baseline).
+ */
+export const VARIANCE_DECREASE_THRESHOLD = 0.7;
+/**
+ * Coverage dropout rate threshold. Rates above this are considered degraded.
+ * A 20% gap rate means 1 in 5 coverage cells is missing evaluations.
+ */
+export const COVERAGE_DROPOUT_THRESHOLD = 0.2;
+/** EWMA smoothing factor. lambda=0.1 catches slow drift; higher = more reactive. */
+export const EWMA_LAMBDA = 0.1;
+/** Current feature version for degradation signal */
+const DEGRADATION_FEATURE_VERSION = '1.1';
+/**
+ * Compute EWMA (Exponentially Weighted Moving Average) from a time series.
+ * EWMA with lambda=0.1 catches slow quality drift that period-over-period deltas miss.
+ *
+ * @param values - Time-ordered score values (oldest first)
+ * @param lambda - Smoothing factor (0-1). Default: EWMA_LAMBDA (0.1)
+ * @returns Final EWMA value, or undefined if no values
+ */
+export function computeEWMA(values, lambda = EWMA_LAMBDA) {
+    if (values.length === 0)
+        return undefined;
+    let ewma = values[0];
+    for (let i = 1; i < values.length; i++) {
+        ewma = lambda * values[i] + (1 - lambda) * ewma;
+    }
+    return roundTo(ewma, SCORE_PRECISION);
+}
+/**
+ * Compute Median Absolute Deviation (MAD) for robust dispersion estimation.
+ * MAD is resistant to outliers unlike standard deviation.
+ * Scaled by 1.4826 for normal-equivalent consistency.
+ *
+ * @param values - Numeric values
+ * @returns Scaled MAD value, or 0 for insufficient data
+ */
+export function computeMAD(values) {
+    if (values.length < 2)
+        return 0;
+    const mad = ss.medianAbsoluteDeviation(values);
+    return roundTo(mad * MAD_CONSISTENCY_FACTOR, SCORE_PRECISION);
+}
+/**
+ * Detect EWMA drift by comparing the trailing EWMA to a baseline mean.
+ * The baseline is the first 70% of the series; drift is detected when the
+ * EWMA (which tracks recent values) deviates from the baseline by > k * MAD.
+ * When MAD = 0, falls back to range-based detection (> 10% of range).
+ */
+export function detectEWMADrift(values, lambda = EWMA_LAMBDA, k = 2) {
+    if (values.length < EWMA_DRIFT_MIN_VALUES)
+        return false;
+    const ewma = computeEWMA(values, lambda);
+    if (ewma === undefined)
+        return false;
+    // Use first EWMA_BASELINE_FRACTION of series as baseline
+    const baselineEnd = Math.max(EWMA_BASELINE_MIN_POINTS, Math.floor(values.length * EWMA_BASELINE_FRACTION));
+    const baseline = values.slice(0, baselineEnd);
+    const baselineMean = baseline.reduce((s, v) => s + v, 0) / baseline.length;
+    const mad = computeMAD(baseline);
+    if (mad === 0) {
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        const range = max - min;
+        return range > 0 && Math.abs(ewma - baselineMean) > EWMA_RANGE_FALLBACK_RATIO * range;
+    }
+    return Math.abs(ewma - baselineMean) > k * mad;
+}
+/**
+ * Compute degradation signal from current and baseline metrics.
+ *
+ * @param currentStdDev - Current period score standard deviation
+ * @param baselineStdDev - Baseline period score standard deviation
+ * @param coverageGapCount - Number of missing coverage cells
+ * @param totalCoverageCells - Total coverage cells expected
+ * @param latencyP95 - Evaluation latency p95 (optional)
+ * @param latencyP50 - Evaluation latency p50 (optional)
+ * @param options - Additional options for EWMA drift and confirmation windows
+ */
+export function computeDegradationSignal(currentStdDev, baselineStdDev, coverageGapCount, totalCoverageCells, latencyP95, latencyP50, options) {
+    // Variance ratio — when baseline had zero variance but current has variance,
+    // use VARIANCE_INCREASE_THRESHOLD + 1 to signal a clear spike rather than
+    // defaulting to 1 (stable) which masks the transition from stable to unstable.
+    let varianceRatio;
+    if (currentStdDev !== null && baselineStdDev !== null) {
+        if (baselineStdDev > 0) {
+            varianceRatio = roundTo(currentStdDev / baselineStdDev, SCORE_PRECISION);
+        }
+        else if (currentStdDev > 0) {
+            varianceRatio = VARIANCE_INCREASE_THRESHOLD + 1;
+        }
+        else {
+            varianceRatio = 1;
+        }
+    }
+    else {
+        varianceRatio = 1;
+    }
+    // Variance trend (R5: shifted from 1.5x to 2.0 for 5% FP rate)
+    let varianceTrend = 'stable';
+    if (varianceRatio > VARIANCE_INCREASE_THRESHOLD)
+        varianceTrend = 'increasing';
+    else if (varianceRatio < VARIANCE_DECREASE_THRESHOLD)
+        varianceTrend = 'decreasing';
+    // Coverage dropout rate
+    const coverageDropoutRate = totalCoverageCells > 0
+        ? roundTo(coverageGapCount / totalCoverageCells, SCORE_PRECISION)
+        : 0;
+    // Latency skew ratio
+    const latencySkewRatio = (latencyP95 != null && latencyP50 != null && latencyP50 > 0)
+        ? roundTo(latencyP95 / latencyP50, SCORE_PRECISION)
+        : 1;
+    // EWMA drift detection
+    const ewmaDriftDetected = options?.historicalValues
+        ? detectEWMADrift(options.historicalValues)
+        : false;
+    // Predicted status from feature combination
+    let predictedStatus = 'healthy';
+    const signals = [
+        varianceTrend === 'increasing',
+        coverageDropoutRate > COVERAGE_DROPOUT_THRESHOLD,
+        latencySkewRatio > LATENCY_SKEW_SIGNAL_THRESHOLD,
+    ];
+    const activeSignals = signals.filter(Boolean).length;
+    if (activeSignals >= 2)
+        predictedStatus = 'critical';
+    else if (activeSignals >= 1)
+        predictedStatus = 'warning';
+    // EWMA drift escalates healthy -> warning (supplementary signal)
+    if (ewmaDriftDetected && predictedStatus === 'healthy') {
+        predictedStatus = 'warning';
+    }
+    // Confirmation window: require CONFIRMATION_MIN_CONSECUTIVE_BREACHES+ for confirmed status
+    const priorBreaches = options?.priorConsecutiveBreaches ?? 0;
+    const currentlyBreaching = predictedStatus !== 'healthy';
+    const consecutiveBreaches = currentlyBreaching ? priorBreaches + 1 : 0;
+    const confirmed = consecutiveBreaches >= CONFIRMATION_MIN_CONSECUTIVE_BREACHES;
+    return {
+        featureVersion: DEGRADATION_FEATURE_VERSION,
+        varianceTrend,
+        varianceRatio,
+        coverageDropoutRate,
+        latencySkewRatio,
+        predictedStatus,
+        ewmaDriftDetected,
+        consecutiveBreaches,
+        confirmed,
+    };
+}
+const CORRELATION_FEATURE_VERSION = '3.1';
+/**
+ * Compute Pearson correlation coefficient between two numeric arrays.
+ * Returns 0 for insufficient data (< 3 points) or zero variance.
+ */
+export function computePearsonR(xs, ys) {
+    const n = Math.min(xs.length, ys.length);
+    if (n < CORRELATION_MIN_POINTS)
+        return 0;
+    const xSlice = xs.slice(0, n);
+    const ySlice = ys.slice(0, n);
+    const r = ss.sampleCorrelation(xSlice, ySlice);
+    if (!Number.isFinite(r))
+        return 0;
+    return roundTo(r, SCORE_PRECISION);
+}
+/**
+ * Compute p-value for Pearson R using t-distribution approximation.
+ * t = r * sqrt((n-2) / (1-r^2)), two-tailed test.
+ * Uses the incomplete beta function approximation for t-distribution CDF.
+ */
+export function pearsonPValue(r, n) {
+    if (n < CORRELATION_MIN_POINTS)
+        return null;
+    const absR = Math.abs(r);
+    if (absR >= 1)
+        return 0;
+    if (absR === 0)
+        return 1;
+    const df = n - 2;
+    const t = absR * Math.sqrt(df / (1 - absR * absR));
+    // Two-tailed p-value via t-distribution CDF
+    const p = 2 * (1 - tCdf(t, df));
+    return Math.max(0, Math.min(1, p));
+}
+/**
+ * Apply Benjamini-Hochberg FDR correction to a set of p-values.
+ * Returns a boolean array indicating which hypotheses are significant.
+ *
+ * @param pValues - Array of p-values
+ * @param q - FDR threshold (default: 0.05)
+ * @returns Boolean array: true = significant at given FDR level
+ */
+export function benjaminiHochberg(pValues, q = DEFAULT_SENSITIVITY_DELTA) {
+    const m = pValues.length;
+    if (m === 0)
+        return [];
+    // Sort indices by p-value
+    const indexed = pValues.map((p, i) => ({ p, i }));
+    indexed.sort((a, b) => a.p - b.p);
+    // Find largest k where p_(k) <= k/m * q
+    const significant = new Array(m).fill(false);
+    let maxK = -1;
+    for (let k = 0; k < m; k++) {
+        const threshold = ((k + 1) / m) * q;
+        if (indexed[k].p <= threshold) {
+            maxK = k;
+        }
+    }
+    // All hypotheses up to maxK are significant
+    for (let k = 0; k <= maxK; k++) {
+        significant[indexed[k].i] = true;
+    }
+    return significant;
+}
+/**
+ * Compute Spearman rank correlation coefficient.
+ * Converts values to fractional ranks (average rank for ties) then computes Pearson R on ranks.
+ * Better than Pearson for bounded [0,1] quality scores that may have non-linear relationships.
+ */
+export function computeSpearmanR(xs, ys) {
+    const n = Math.min(xs.length, ys.length);
+    if (n < CORRELATION_MIN_POINTS)
+        return 0;
+    return computePearsonR(fractionalRanks(xs.slice(0, n)), fractionalRanks(ys.slice(0, n)));
+}
+/** Convert values to fractional ranks (1-based, average rank for ties) */
+function fractionalRanks(values) {
+    const indexed = values.map((v, i) => ({ v, i }));
+    indexed.sort((a, b) => a.v - b.v);
+    const ranks = new Array(values.length);
+    let i = 0;
+    while (i < indexed.length) {
+        let j = i;
+        while (j < indexed.length && indexed[j].v === indexed[i].v)
+            j++;
+        const avgRank = (i + j + 1) / 2; // average of 1-based ranks i+1..j
+        for (let k = i; k < j; k++)
+            ranks[indexed[k].i] = avgRank;
+        i = j;
+    }
+    return ranks;
+}
+/**
+ * Compute Cohen's d effect size from a correlation coefficient.
+ * d = 2r / sqrt(1 - r^2). Interpretation: small=0.2, medium=0.5, large=0.8.
+ */
+function correlationToCohenD(r) {
+    const absR = Math.abs(r);
+    if (absR >= 1)
+        return Infinity;
+    const d = (2 * absR) / Math.sqrt(1 - absR * absR);
+    return roundTo(d, SCORE_PRECISION);
+}
+/**
+ * Find the best lag (highest |R|) for a pair of time series.
+ * Tests lags from 0 to maxLagSteps by shifting seriesB forward.
+ */
+function findBestLag(seriesA, seriesB, maxLagSteps) {
+    let bestR = computePearsonR(seriesA, seriesB);
+    let bestLag = 0;
+    for (let lag = 1; lag <= maxLagSteps; lag++) {
+        // Shift B forward by lag: compare A[lag:] with B[0:n-lag]
+        const n = Math.min(seriesA.length, seriesB.length) - lag;
+        if (n < CORRELATION_MIN_POINTS)
+            break;
+        const shiftedA = seriesA.slice(lag);
+        const shiftedB = seriesB.slice(0, n);
+        const r = computePearsonR(shiftedA, shiftedB);
+        if (Math.abs(r) > Math.abs(bestR)) {
+            bestR = r;
+            bestLag = lag;
+        }
+        // Also test negative lag: A[0:n-lag] with B[lag:]
+        const revA = seriesA.slice(0, n);
+        const revB = seriesB.slice(lag);
+        const rRev = computePearsonR(revA, revB);
+        if (Math.abs(rRev) > Math.abs(bestR)) {
+            bestR = rRev;
+            bestLag = -lag;
+        }
+    }
+    return { r: bestR, lagStep: bestLag };
+}
+// ============================================================================
+// R3: Bivariate Granger Causality Test
+// ============================================================================
+const GRANGER_MIN_SAMPLE_SIZE = 30;
+/**
+ * Fit an autoregressive (AR) model using OLS and return the sum of squared residuals.
+ * y[t] = c + sum(a_i * y[t-i]) + sum(b_j * x[t-j]) + e[t]
+ *
+ * When xLags is empty, fits a univariate (restricted) model.
+ * When xLags is provided, fits a bivariate (unrestricted) model.
+ *
+ * Uses normal equations: (X'X)^-1 X'y via Gaussian elimination.
+ */
+function fitARResidualSSR(y, yLags, xLags = []) {
+    const n = y.length;
+    const k = 1 + yLags.length + xLags.length; // intercept + yLag cols + xLag cols
+    if (n <= k)
+        return 0;
+    // Build design matrix X (n x k): [intercept, yLag1..., xLag1...]
+    const xData = [];
+    for (let i = 0; i < n; i++) {
+        const row = [1];
+        for (const lagCol of yLags)
+            row.push(lagCol[i]);
+        for (const lagCol of xLags)
+            row.push(lagCol[i]);
+        xData.push(row);
+    }
+    const X = new Matrix(xData);
+    const Y = Matrix.columnVector(y);
+    // Solve normal equations: (X'X)β = X'y via QR decomposition
+    const beta = solve(X, Y, false);
+    // Compute SSR = sum((y - Xβ)^2)
+    const residuals = X.mmul(beta).sub(Y);
+    let ssr = 0;
+    for (let i = 0; i < n; i++) {
+        const r = residuals.get(i, 0);
+        ssr += r * r;
+    }
+    return ssr;
+}
+/**
+ * Compute p-value for F-distribution.
+ * P(F > f) = 1 - CDF(f, d1, d2)
+ */
+function fDistPValue(f, d1, d2) {
+    if (f <= 0 || d1 <= 0 || d2 <= 0)
+        return 1;
+    return 1 - fCdf(f, d1, d2);
+}
+/**
+ * Run bivariate Granger causality test: does X Granger-cause Y?
+ *
+ * Compares restricted model (Y on own lags) vs unrestricted model (Y on own lags + X lags).
+ * F = ((SSR_r - SSR_u) / p) / (SSR_u / (n - 2p - 1))
+ *
+ * @returns F-statistic and p-value, or undefined if insufficient data
+ */
+function grangerFTest(y, x, lags) {
+    const n = Math.min(y.length, x.length);
+    if (n < lags + GRANGER_MIN_SAMPLE_SIZE)
+        return undefined;
+    const effectiveN = n - lags;
+    const yTarget = y.slice(lags, lags + effectiveN);
+    // Build lag matrices
+    const yLagCols = [];
+    const xLagCols = [];
+    for (let lag = 1; lag <= lags; lag++) {
+        yLagCols.push(y.slice(lags - lag, lags - lag + effectiveN));
+        xLagCols.push(x.slice(lags - lag, lags - lag + effectiveN));
+    }
+    const ssrRestricted = fitARResidualSSR(yTarget, yLagCols);
+    const ssrUnrestricted = fitARResidualSSR(yTarget, yLagCols, xLagCols);
+    if (ssrUnrestricted <= 0)
+        return undefined;
+    const p = lags; // number of additional parameters
+    const dfResidual = effectiveN - 2 * p - 1;
+    if (dfResidual <= 0)
+        return undefined;
+    const fStat = ((ssrRestricted - ssrUnrestricted) / p) / (ssrUnrestricted / dfResidual);
+    if (!Number.isFinite(fStat) || fStat < 0)
+        return undefined;
+    const pValue = fDistPValue(fStat, p, dfResidual);
+    return { fStatistic: roundTo(fStat, SCORE_PRECISION), pValue: roundTo(pValue, SCORE_PRECISION) };
+}
+/**
+ * Compute Granger causality for a pair of time series.
+ * Tests both directions (A->B and B->A) using the best lag from correlation analysis.
+ *
+ * @param seriesA - Time-ordered scores for metric A
+ * @param seriesB - Time-ordered scores for metric B
+ * @param lags - Number of lags to use (from correlation lag detection, minimum 1)
+ * @param significanceLevel - P-value threshold (default: 0.05)
+ */
+export function computeGrangerCausality(seriesA, seriesB, lags, significanceLevel = DEFAULT_SENSITIVITY_DELTA) {
+    // Cap lags at n/4 to ensure sufficient residual degrees of freedom (Lütkepohl 2005).
+    // With GRANGER_MIN_SAMPLE_SIZE=30, effectiveLags=1 needs n>=31, effectiveLags=2 needs n>=32.
+    const effectiveLags = Math.max(1, Math.min(lags, Math.floor(Math.min(seriesA.length, seriesB.length) / 4)));
+    // Test A -> B (does A Granger-cause B?)
+    const abTest = grangerFTest(seriesB, seriesA, effectiveLags);
+    // Test B -> A (does B Granger-cause A?)
+    const baTest = grangerFTest(seriesA, seriesB, effectiveLags);
+    if (!abTest && !baTest)
+        return undefined;
+    const abSignificant = abTest != null && abTest.pValue < significanceLevel;
+    const baSignificant = baTest != null && baTest.pValue < significanceLevel;
+    let direction = 'none';
+    let bestF;
+    let bestP;
+    if (abSignificant && baSignificant) {
+        if (!abTest || !baTest) {
+            throw new Error('Expected both Granger tests when both are significant');
+        }
+        direction = 'bidirectional';
+        bestF = Math.max(abTest.fStatistic, baTest.fStatistic);
+        bestP = Math.min(abTest.pValue, baTest.pValue);
+    }
+    else if (abSignificant) {
+        if (!abTest) {
+            throw new Error('Expected A->B Granger test when significant');
+        }
+        direction = 'A->B';
+        bestF = abTest.fStatistic;
+        bestP = abTest.pValue;
+    }
+    else if (baSignificant) {
+        if (!baTest) {
+            throw new Error('Expected B->A Granger test when significant');
+        }
+        direction = 'B->A';
+        bestF = baTest.fStatistic;
+        bestP = baTest.pValue;
+    }
+    else {
+        // Neither significant: report the one with lower p-value
+        if (abTest && baTest) {
+            bestF = abTest.pValue < baTest.pValue ? abTest.fStatistic : baTest.fStatistic;
+            bestP = Math.min(abTest.pValue, baTest.pValue);
+        }
+        else {
+            const test = abTest ?? baTest;
+            if (!test) {
+                throw new Error('Expected at least one Granger test result');
+            }
+            bestF = test.fStatistic;
+            bestP = test.pValue;
+        }
+    }
+    return {
+        fStatistic: bestF,
+        pValue: bestP,
+        lags: effectiveLags,
+        direction,
+    };
+}
+/**
+ * Compute correlation matrix across all metric pairs.
+ * Supports time-lag detection and BH-FDR significance testing.
+ *
+ * Empty metric time series arrays are valid input and result in `pearsonR=0`
+ * for any pair involving that metric (insufficient data for correlation).
+ *
+ * @param metricTimeSeries - Map of metric name to time-ordered score arrays
+ * @param knownToxicCombos - Set of "metricA:metricB" pairs from correlation rules
+ * @param degradedPeriods - Map of metric name to boolean arrays (true = degraded in that period)
+ * @param options - Lag detection and significance testing options
+ * @example
+ * ```ts
+ * const series = new Map([
+ *   ['relevance', [0.9, 0.85, 0.88, 0.92]],
+ *   ['faithfulness', [0.8, 0.82, 0.79, 0.85]],
+ * ]);
+ * const correlations = computeCorrelationMatrix(series);
+ * // [{ metricA: 'faithfulness', metricB: 'relevance', pearsonR: 0.87, ... }]
+ * ```
+ */
+export function computeCorrelationMatrix(metricTimeSeries, knownToxicCombos, degradedPeriods, options) {
+    const metrics = [...metricTimeSeries.keys()].sort();
+    const maxLagSteps = options?.maxLagSteps ?? 0;
+    const lagStepHours = options?.lagStepHours ?? 1;
+    const fdrQ = options?.fdrQ ?? DEFAULT_SENSITIVITY_DELTA;
+    const results = [];
+    // First pass: compute all correlations and p-values
+    const pairData = [];
+    for (let i = 0; i < metrics.length; i++) {
+        for (let j = i + 1; j < metrics.length; j++) {
+            const metricA = metrics[i];
+            const metricB = metrics[j];
+            const seriesA = metricTimeSeries.get(metricA);
+            const seriesB = metricTimeSeries.get(metricB);
+            if (!seriesA || !seriesB) {
+                console.debug(`[computeCorrelationMatrix] skipping pair (${metricA}, ${metricB}): series not found`);
+                continue;
+            }
+            // Find best lag (or use lag=0 if no lag detection)
+            let pearsonR;
+            let lagStep;
+            if (maxLagSteps > 0) {
+                const best = findBestLag(seriesA, seriesB, maxLagSteps);
+                pearsonR = best.r;
+                lagStep = best.lagStep;
+            }
+            else {
+                pearsonR = computePearsonR(seriesA, seriesB);
+                lagStep = 0;
+            }
+            const effectiveN = Math.min(seriesA.length, seriesB.length) - Math.abs(lagStep);
+            const pValue = pearsonPValue(pearsonR, effectiveN);
+            // Spearman rank correlation (computed at best lag)
+            let spearmanR;
+            if (lagStep === 0) {
+                spearmanR = computeSpearmanR(seriesA, seriesB);
+            }
+            else if (lagStep > 0) {
+                spearmanR = computeSpearmanR(seriesA.slice(lagStep), seriesB.slice(0, effectiveN));
+            }
+            else {
+                spearmanR = computeSpearmanR(seriesA.slice(0, effectiveN), seriesB.slice(-lagStep));
+            }
+            const effectSize = correlationToCohenD(pearsonR);
+            // Co-occurrence rate from degraded periods
+            let coOccurrenceRate = 0;
+            if (degradedPeriods) {
+                const degradedA = degradedPeriods.get(metricA);
+                const degradedB = degradedPeriods.get(metricB);
+                if (degradedA && degradedB) {
+                    const n = Math.min(degradedA.length, degradedB.length);
+                    if (n > 0) {
+                        let coCount = 0;
+                        for (let k = 0; k < n; k++) {
+                            if (degradedA[k] && degradedB[k])
+                                coCount++;
+                        }
+                        coOccurrenceRate = roundTo(coCount / n, SCORE_PRECISION);
+                    }
+                }
+            }
+            const comboKey = `${metricA}:${metricB}`;
+            const reverseKey = `${metricB}:${metricA}`;
+            const isKnownToxicCombo = knownToxicCombos
+                ? (knownToxicCombos.has(comboKey) || knownToxicCombos.has(reverseKey))
+                : false;
+            pairData.push({
+                metricA, metricB, pearsonR, spearmanR, effectSize,
+                lagHours: lagStep * lagStepHours,
+                pValue, coOccurrenceRate, isKnownToxicCombo, effectiveN,
+            });
+        }
+    }
+    // Second pass: apply BH-FDR significance testing
+    // Filter out pairs with null pValues (insufficient data) before BH-FDR
+    const validIndices = pairData.reduce((acc, d, i) => {
+        if (d.pValue !== null)
+            acc.push(i);
+        return acc;
+    }, []);
+    const validPValues = validIndices.map(i => pairData[i].pValue);
+    const validSignificantFlags = benjaminiHochberg(validPValues, fdrQ);
+    const validIndexMap = new Map(validIndices.map((idx, pos) => [idx, pos]));
+    const significantFlags = pairData.map((d, i) => {
+        if (d.pValue === null)
+            return false;
+        const validPos = validIndexMap.get(i);
+        return validPos !== undefined ? validSignificantFlags[validPos] : false;
+    });
+    // Granger causality config
+    const grangerCfg = options?.grangerConfig;
+    const grangerEnabled = grangerCfg?.enabled === true;
+    const grangerMinN = grangerCfg?.minSampleSize ?? GRANGER_MIN_SAMPLE_SIZE;
+    const grangerAlpha = grangerCfg?.significanceLevel ?? DEFAULT_SENSITIVITY_DELTA;
+    for (let idx = 0; idx < pairData.length; idx++) {
+        const d = pairData[idx];
+        const isSignificant = significantFlags[idx];
+        // Run Granger test on significant pairs when enabled
+        let granger;
+        let causalConfidence = 'correlation';
+        if (grangerEnabled && isSignificant && d.effectiveN >= grangerMinN) {
+            const seriesA = metricTimeSeries.get(d.metricA);
+            const seriesB = metricTimeSeries.get(d.metricB);
+            if (!seriesA || !seriesB) {
+                continue;
+            }
+            // Use fixed lag=GRANGER_FIXED_LAG_ORDER (not correlation-detected lag) to avoid data-snooping
+            // inflation of Type I error. The correlation lag maximizes |R| across
+            // tested offsets; reusing it for AR order would bias the F-test.
+            granger = computeGrangerCausality(seriesA, seriesB, GRANGER_FIXED_LAG_ORDER, grangerAlpha);
+            if (granger && granger.direction !== 'none') {
+                causalConfidence = 'granger';
+            }
+        }
+        results.push({
+            featureVersion: CORRELATION_FEATURE_VERSION,
+            metricA: d.metricA,
+            metricB: d.metricB,
+            pearsonR: d.pearsonR,
+            spearmanR: d.spearmanR,
+            effectSize: d.effectSize,
+            lagHours: d.lagHours,
+            significant: isSignificant,
+            pValue: d.pValue,
+            causalConfidence,
+            coOccurrenceRate: d.coOccurrenceRate,
+            isKnownToxicCombo: d.isKnownToxicCombo,
+            granger,
+        });
+    }
+    return results;
+}
+// ============================================================================
+// R4: Percentile Distribution & Streaming Digest (Section 16.2)
+// ============================================================================
+/**
+ * Compute percentile distribution from an array of numeric scores.
+ * Uses linear interpolation between adjacent sorted values.
+ *
+ * @param scores - Array of numeric scores (unsorted ok, will be sorted internally)
+ * @returns PercentileDistribution with p10/p25/p50/p75/p90, or undefined if < 3 scores
+ */
+export function computePercentileDistribution(scores) {
+    if (scores.length < CORRELATION_MIN_POINTS)
+        return undefined;
+    const sorted = [...scores].sort((a, b) => a - b);
+    return {
+        p10: roundTo(ss.quantileSorted(sorted, QUANTILE_P10), SCORE_PRECISION),
+        p25: roundTo(ss.quantileSorted(sorted, QUANTILE_P25), SCORE_PRECISION),
+        p50: roundTo(ss.quantileSorted(sorted, QUANTILE_P50), SCORE_PRECISION),
+        p75: roundTo(ss.quantileSorted(sorted, QUANTILE_P75), SCORE_PRECISION),
+        p90: roundTo(ss.quantileSorted(sorted, QUANTILE_P90), SCORE_PRECISION),
+    };
+}
+/**
+ * Compute the percentile rank of a value within a sorted array.
+ * Returns the fraction of values in the array that are <= the given value (0-1).
+ *
+ * @param value - The value to rank
+ * @param sortedScores - Pre-sorted (ascending) array of scores
+ * @returns Percentile rank (0-1)
+ */
+export function computePercentileRank(value, sortedScores) {
+    if (sortedScores.length === 0)
+        return QUANTILE_P50;
+    const n = sortedScores.length;
+    // Binary search for first index where sortedScores[idx] > value (upper bound)
+    let lo = 0, hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sortedScores[mid] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const upper = lo; // count of values <= value
+    // Binary search for first index where sortedScores[idx] >= value (lower bound)
+    lo = 0;
+    hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sortedScores[mid] < value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const lower = lo; // count of values < value
+    // Fractional rank: midpoint of tied range
+    return roundTo((lower + upper) / (2 * n), SCORE_PRECISION);
+}
+/**
+ * Streaming percentile estimator backed by DDSketch.
+ * Wraps `@datadog/sketches-js` with a simplified API for quality pipeline use.
+ */
+export class StreamingPercentile {
+    sketch;
+    totalCount = 0;
+    constructor() {
+        this.sketch = new DDSketch();
+    }
+    /** Add a single value to the sketch */
+    add(value) {
+        if (!Number.isFinite(value))
+            throw new TypeError(`StreamingPercentile: value must be finite, got ${value}`);
+        this.sketch.accept(value);
+        this.totalCount++;
+    }
+    /** Add multiple values at once */
+    addAll(values) {
+        for (const v of values)
+            this.add(v);
+    }
+    /** Get the current total count of observed values */
+    count() {
+        return this.totalCount;
+    }
+    /** Estimate a percentile (0-100) from the sketch */
+    percentile(p) {
+        if (this.totalCount === 0)
+            return 0;
+        return roundTo(this.sketch.getValueAtQuantile(p / 100), SCORE_PRECISION);
+    }
+    /** Get full percentile distribution */
+    distribution() {
+        if (this.totalCount < CORRELATION_MIN_POINTS)
+            return undefined;
+        return {
+            p10: roundTo(this.sketch.getValueAtQuantile(QUANTILE_P10), SCORE_PRECISION),
+            p25: roundTo(this.sketch.getValueAtQuantile(QUANTILE_P25), SCORE_PRECISION),
+            p50: roundTo(this.sketch.getValueAtQuantile(QUANTILE_P50), SCORE_PRECISION),
+            p75: roundTo(this.sketch.getValueAtQuantile(QUANTILE_P75), SCORE_PRECISION),
+            p90: roundTo(this.sketch.getValueAtQuantile(QUANTILE_P90), SCORE_PRECISION),
+        };
+    }
+}
+/**
+ * Compute Population Stability Index (PSI) between two distributions.
+ * PSI measures distribution shift: < 0.1 = stable, 0.1–0.25 = moderate, > 0.25 = significant.
+ *
+ * Uses a `bins`-bin histogram comparison between expected (baseline) and actual (current).
+ * Returns { psi: 0, drifted: false } when either array has fewer than MIN_QUANTILE_SAMPLE_SIZE
+ * values (insufficient data for reliable estimation).
+ */
+export function computePSI(expected, actual, bins = DEFAULT_BIN_COUNT) {
+    if (expected.length < MIN_QUANTILE_SAMPLE_SIZE || actual.length < MIN_QUANTILE_SAMPLE_SIZE) {
+        return { psi: 0, drifted: false };
+    }
+    const toBinProportions = (values) => {
+        const hist = new Array(bins).fill(0);
+        for (const v of values) {
+            const bin = Math.min(Math.max(Math.floor(v * bins), 0), bins - 1);
+            hist[bin]++;
+        }
+        // PSI_LOG_EPSILON prevents log(0) when a bin is empty
+        return hist.map(c => Math.max(c / values.length, PSI_LOG_EPSILON));
+    };
+    const pExpected = toBinProportions(expected);
+    const pActual = toBinProportions(actual);
+    let psi = 0;
+    for (let i = 0; i < bins; i++) {
+        psi += (pActual[i] - pExpected[i]) * Math.log(pActual[i] / pExpected[i]);
+    }
+    const roundedPsi = roundTo(Math.max(0, psi), SCORE_PRECISION);
+    return {
+        psi: roundedPsi,
+        drifted: roundedPsi > PSI_RECALIBRATION_THRESHOLD,
+    };
+}
+/**
+ * Determine whether calibration state should be rewritten based on PSI drift.
+ * Returns shouldWrite: true on first run (null previousState) or if any metric drifts.
+ */
+export function shouldRecalibrate(previousState, currentScores) {
+    if (previousState === null) {
+        return { shouldWrite: true, psiValues: {} };
+    }
+    if (!previousState.rawScores) {
+        return { shouldWrite: true, psiValues: {} };
+    }
+    const psiValues = {};
+    let shouldWrite = false;
+    for (const metric of Object.keys(currentScores)) {
+        const previous = previousState.rawScores[metric];
+        if (!previous) {
+            shouldWrite = true;
+            continue;
+        }
+        const result = computePSI(previous, currentScores[metric]);
+        psiValues[metric] = result.psi;
+        if (result.drifted) {
+            shouldWrite = true;
+        }
+    }
+    return { shouldWrite, psiValues };
+}
+/**
+ * Compute calibration distributions from per-metric evaluation scores.
+ * Skips metrics with fewer than MIN_QUANTILE_SAMPLE_SIZE scores (unreliable percentiles).
+ * Uses StreamingPercentile to compute p10/p25/p50/p75/p90 for each qualifying metric.
+ * windowStart/windowEnd metadata reflects a CALIBRATION_WINDOW_DAYS rolling window,
+ * but the caller is responsible for pre-filtering scores to that window before passing them in.
+ */
+export function computeCalibrationDistributions(evaluationsByMetric) {
+    const distributions = {};
+    const now = new Date().toISOString();
+    const windowStart = new Date(Date.now() - CALIBRATION_WINDOW_DAYS * TIME_MS.DAY).toISOString();
+    for (const [metric, scores] of Object.entries(evaluationsByMetric)) {
+        if (scores.length < MIN_QUANTILE_SAMPLE_SIZE)
+            continue;
+        const dist = computePercentileDistribution(scores);
+        if (!dist)
+            continue;
+        distributions[metric] = {
+            distribution: dist,
+            sampleSize: scores.length,
+            windowStart,
+            windowEnd: now,
+        };
+    }
+    return distributions;
+}
+/**
+ * Load calibration state from persisted JSON file.
+ * Returns null if file does not exist or is malformed.
+ */
+export function loadCalibrationState(dir) {
+    const filePath = join(dir, CALIBRATION_STATE_FILE);
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const result = calibrationStateSchema.safeParse(parsed);
+        if (result.success) {
+            return result.data;
+        }
+    }
+    catch { /* file not found or malformed */ }
+    return null;
+}
+/**
+ * Save calibration state to JSON file for cross-run use by the dashboard API.
+ * Validates state before writing to ensure round-trip integrity.
+ */
+export function saveCalibrationState(dir, state) {
+    const validated = calibrationStateSchema.parse(state);
+    writeFileSync(join(dir, CALIBRATION_STATE_FILE), JSON.stringify(validated, null, FORMAT_JSON_INDENT_SPACES) + '\n');
+}
+/**
+ * Compute all derived features in correct dependency order.
+ *
+ * Pipeline ordering (QM2):
+ *   Step 2 (aggregate) outputs: metrics, CoverageHeatmap
+ *     ↓
+ *   Step 3a: CQI (depends on metrics)
+ *   Step 3b: Coverage-weighted confidence (depends on metrics + CoverageHeatmap via evaluationsPerInput)
+ *   Step 3c: Correlation matrix (depends on metricTimeSeries, independent of 3a/3b)
+ *
+ * CoverageHeatmap must be computed before calling this function.
+ * The evaluationsPerInput parameter is derived from CoverageHeatmap output.
+ *
+ * @param input - Aggregated data from Step 2
+ * @returns All derived features
+ */
+export function computeDerivedFeatures(input) {
+    // Step 3a: Composite Quality Index (depends only on metrics)
+    const cqi = computeCQI(input.metrics, input.cqiWeights);
+    const cqiSensitivity = cqi ? computeCQISensitivity(input.metrics, input.cqiWeights) : undefined;
+    // Step 3b: Coverage-weighted confidence (depends on metrics + evaluationsPerInput from CoverageHeatmap)
+    const coverageConfidence = new Map();
+    if (input.evaluationsPerInput) {
+        for (const metric of input.metrics) {
+            const perInput = input.evaluationsPerInput.get(metric.name);
+            if (metric.confidence && perInput && perInput.length > 0) {
+                coverageConfidence.set(metric.name, computeCoverageWeightedConfidence(metric.confidence, perInput));
+            }
+        }
+    }
+    // Step 3c: Correlation matrix (depends on metricTimeSeries, independent of 3a/3b)
+    const correlations = input.metricTimeSeries
+        ? computeCorrelationMatrix(input.metricTimeSeries, input.knownToxicCombos, input.degradedPeriods, input.correlationOptions)
+        : [];
+    return { cqi, cqiSensitivity, coverageConfidence, correlations };
+}
+/** Parameter grid for sweepDegradationParams — all combinations are evaluated */
+export const BACKTEST_SWEEP = {
+    varianceThreshold: [1.5, 1.75, 2.0, 2.5, 3.0],
+    coverageDropoutThreshold: [0.1, 0.15, 0.2, 0.3, 0.4],
+    ewmaLambda: [0.05, 0.1, 0.15, 0.2, 0.3],
+    confirmationWindow: [1, 2, 3, 4],
+    stabilityThreshold: [0.005, 0.01, 0.02, 0.03, 0.05],
+};
+/** Current production detector configuration used as baseline in sweepDegradationParams */
+export const CURRENT_PRODUCTION_CONFIG = {
+    varianceThreshold: VARIANCE_INCREASE_THRESHOLD,
+    coverageDropoutThreshold: COVERAGE_DROPOUT_THRESHOLD,
+    latencySkewThreshold: LATENCY_SKEW_SIGNAL_THRESHOLD,
+    ewmaLambda: EWMA_LAMBDA,
+    confirmationWindow: CONFIRMATION_MIN_CONSECUTIVE_BREACHES,
+};
+/**
+ * Inject synthetic degradation into baseline snapshots for testing.
+ * Returns a new array with degradation injected at the specified range.
+ *
+ * - variance_spike: sets currentStdDev = baselineStdDev * magnitude
+ * - coverage_gap: sets coverageGapCount = totalCoverageCells * magnitude (fraction)
+ * - latency_jump: sets latencyP95 = latencyP50 * magnitude (creates skew ratio = magnitude)
+ */
+export function injectDegradationScenario(snapshots, type, magnitude, startIdx, duration) {
+    return snapshots.map((s, i) => {
+        if (i < startIdx || i >= startIdx + duration)
+            return s;
+        switch (type) {
+            case 'variance_spike':
+                return { ...s, currentStdDev: s.baselineStdDev * magnitude };
+            case 'coverage_gap':
+                return { ...s, coverageGapCount: Math.round(s.totalCoverageCells * magnitude) };
+            case 'latency_jump':
+                if (s.latencyP50 === undefined)
+                    return s;
+                return { ...s, latencyP95: s.latencyP50 * magnitude };
+            default:
+                return s;
+        }
+    });
+}
+// ============================================================================
+// Role-Aware Feature Config (Section 16.4)
+// ============================================================================
+/** Zod schema for feature visibility configuration per role */
+export const roleFeatureConfigSchema = z.object({
+    showCQI: z.boolean(),
+    showCQIBreakdown: z.boolean(),
+    showVariance: z.boolean(),
+    showAcceleration: z.boolean(),
+    showProjectedBreach: z.boolean(),
+    showCorrelationRemediation: z.boolean(),
+    showCoverageHeatmap: z.boolean(),
+    showPipelineFunnel: z.boolean(),
+    showProvenance: z.boolean(),
+    showRawExport: z.boolean(),
+    /** Chars before "Show more" truncation in explanations */
+    explanationTruncation: z.number().int().nonnegative(),
+    /** How many worst evaluations to display */
+    maxWorstEvaluations: z.number().int().nonnegative(),
+});
+/** Feature configuration per role per design doc Section 16.4 */
+const configs = {
+    executive: {
+        showCQI: true,
+        showCQIBreakdown: true,
+        showVariance: false,
+        showAcceleration: false,
+        showProjectedBreach: true,
+        showCorrelationRemediation: false,
+        showCoverageHeatmap: false,
+        showPipelineFunnel: false,
+        showProvenance: false,
+        showRawExport: false,
+        explanationTruncation: EXECUTIVE_EXPLANATION_TRUNCATION,
+        maxWorstEvaluations: EXECUTIVE_MAX_WORST_EVALUATIONS,
+    },
+    operator: {
+        showCQI: false,
+        showCQIBreakdown: false,
+        showVariance: true,
+        showAcceleration: true,
+        showProjectedBreach: true,
+        showCorrelationRemediation: true,
+        showCoverageHeatmap: true,
+        showPipelineFunnel: true,
+        showProvenance: false,
+        showRawExport: false,
+        explanationTruncation: TEXT_PREVIEW_LIMIT,
+        maxWorstEvaluations: OPERATOR_MAX_WORST_EVALUATIONS,
+    },
+    auditor: {
+        showCQI: true,
+        showCQIBreakdown: true,
+        showVariance: true,
+        showAcceleration: false,
+        showProjectedBreach: false,
+        showCorrelationRemediation: true,
+        showCoverageHeatmap: true,
+        showPipelineFunnel: true,
+        showProvenance: true,
+        showRawExport: true,
+        explanationTruncation: AUDITOR_EXPLANATION_TRUNCATION,
+        maxWorstEvaluations: AUDITOR_MAX_WORST_EVALUATIONS,
+    },
+};
+/**
+ * Get the feature configuration for a role.
+ */
+export function getRoleFeatureConfig(role) {
+    return configs[role];
+}
+/**
+ * Compute sample standard deviation from an array of scores.
+ * Returns null for arrays with fewer than 2 values.
+ */
+export function computeStdDev(values) {
+    if (values.length < 2)
+        return null;
+    return roundTo(ss.sampleStandardDeviation(values), SCORE_PRECISION);
+}
+/**
+ * Load degradation state from persisted JSON file.
+ * Returns empty state if file does not exist or is malformed.
+ */
+export function loadDegradationState(dir) {
+    const filePath = join(dir, DEGRADATION_STATE_FILE);
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const result = degradationStateSchema.safeParse(parsed);
+        if (result.success) {
+            return result.data;
+        }
+    }
+    catch { /* file not found or malformed */ }
+    return { lastRun: '', breaches: {} };
+}
+/**
+ * Save degradation state to JSON file for cross-run breach tracking.
+ * Validates state before writing to ensure round-trip integrity.
+ */
+export function saveDegradationState(dir, state) {
+    const validated = degradationStateSchema.parse(state);
+    writeFileSync(join(dir, DEGRADATION_STATE_FILE), JSON.stringify(validated, null, FORMAT_JSON_INDENT_SPACES) + '\n');
+}
+/**
+ * Compute degradation signals for all metrics from time-bucketed evaluation data.
+ *
+ * Bridges the gap between sync-to-kv's bucket structure and computeDegradationSignal()'s
+ * input requirements:
+ * - Computes stdDev inline from bucket scores (not available in computeAggregations)
+ * - Defines baseline as first DEGRADATION_BASELINE_RATIO (70%) of non-empty buckets
+ * - Uses bucket sparsity (buckets with 0 evals / total buckets) as coverage proxy
+ * - Passes latencyP95/P50 as null (latencySkewRatio defaults to 1.0)
+ * - Reads priorConsecutiveBreaches from persisted DegradationState
+ *
+ * Skips metrics with fewer than MIN_BUCKETS_FOR_SIGNAL (3) non-empty buckets.
+ */
+export function computeRollingDegradationSignals(timeBuckets, metricNames, state, window) {
+    const reports = [];
+    for (const metricName of metricNames) {
+        const buckets = timeBuckets[metricName];
+        if (!buckets || buckets.length === 0)
+            continue;
+        // Filter to non-empty buckets for baseline/current split
+        const nonEmptyBuckets = buckets.filter(b => b.scores.length > 0);
+        if (nonEmptyBuckets.length < MIN_BUCKETS_FOR_SIGNAL)
+            continue;
+        // Split into baseline (first 70%) and current (last bucket)
+        const baselineEnd = Math.max(1, Math.floor(nonEmptyBuckets.length * DEGRADATION_BASELINE_RATIO));
+        const baselineBuckets = nonEmptyBuckets.slice(0, baselineEnd);
+        const currentBucket = nonEmptyBuckets[nonEmptyBuckets.length - 1];
+        // Compute stdDev for baseline and current
+        const baselineScores = baselineBuckets.flatMap(b => b.scores);
+        const currentStdDev = computeStdDev(currentBucket.scores);
+        const baselineStdDev = computeStdDev(baselineScores);
+        // Bucket sparsity as coverage proxy
+        const bucketSparsityGaps = buckets.filter(b => b.scores.length === 0).length;
+        // Historical values: per-bucket averages, oldest-first (for EWMA).
+        // Includes the current bucket intentionally — EWMA uses the full series to
+        // track drift including the most recent observation. Contrast with
+        // baselineStdDev (L2349) which uses only baselineBuckets (first 70%),
+        // because stdDev comparison is meant to measure change vs. the stable baseline.
+        const historicalValues = nonEmptyBuckets
+            .map(b => b.scores.reduce((s, v) => s + v, 0) / b.scores.length);
+        const priorBreaches = state.breaches[metricName] ?? 0;
+        const signal = computeDegradationSignal(currentStdDev, baselineStdDev, bucketSparsityGaps, buckets.length, null, // latencyP95 unavailable
+        null, // latencyP50 unavailable
+        { historicalValues, priorConsecutiveBreaches: priorBreaches });
+        // Total evaluation count
+        const evaluationCount = buckets.reduce((sum, b) => sum + b.scores.length, 0);
+        // Baseline period timestamps
+        const baselinePeriod = {
+            startDate: baselineBuckets[0].startTime,
+            endDate: baselineBuckets[baselineBuckets.length - 1].endTime,
+        };
+        reports.push({
+            metricName,
+            signal,
+            trend: null, // QualityMetricConfig unavailable here; caller enriches via computeTrend()
+            window,
+            baselinePeriod,
+            evaluationCount,
+        });
+    }
+    return reports;
+}
+export function computeAHPWeights(comparisons, metrics) {
+    const n = metrics.length;
+    const equalWeight = 1 / n;
+    if (comparisons.length === 0) {
+        const weights = {};
+        for (const m of metrics)
+            weights[m] = equalWeight;
+        return { weights, consistencyRatio: 0 };
+    }
+    // Build n×n comparison matrix
+    const matrix = Array.from({ length: n }, () => Array(n).fill(1));
+    const indexMap = {};
+    for (let i = 0; i < n; i++) {
+        const m = metrics[i];
+        if (m === undefined)
+            throw new Error(`AHP: metrics array has hole at index ${i}`);
+        indexMap[m] = i;
+    }
+    for (const c of comparisons) {
+        const i = indexMap[c.metricA];
+        const j = indexMap[c.metricB];
+        if (i === undefined || j === undefined)
+            continue;
+        const val = c.preferred === 'A' ? c.preference : 1 / c.preference;
+        if (matrix[i])
+            matrix[i][j] = val;
+        if (matrix[j])
+            matrix[j][i] = 1 / val;
+    }
+    // Geometric mean of each row → normalize
+    const geoMeans = pipe(matrix, map((row) => Math.pow(row.reduce((acc, v) => acc * v, 1), 1 / n)));
+    const geoSum = geoMeans.reduce((acc, v) => acc + v, 0);
+    const weights = Object.fromEntries(metrics.map((m, i) => [m, (geoMeans[i] ?? 0) / geoSum]));
+    // Consistency check
+    const weightVec = metrics.map(m => weights[m] ?? 0);
+    let lambdaMax = 0;
+    for (let i = 0; i < n; i++) {
+        let rowSum = 0;
+        const matrixRow = matrix[i];
+        const wi = weightVec[i];
+        if (!matrixRow || wi === undefined || wi === 0)
+            throw new Error(`AHP: corrupt weight vector at index ${i}`);
+        for (let j = 0; j < n; j++)
+            rowSum += (matrixRow[j] ?? 0) * (weightVec[j] ?? 0);
+        lambdaMax += rowSum / wi;
+    }
+    lambdaMax /= n;
+    const ci = (lambdaMax - n) / (n - 1);
+    const ri = AHP_RANDOM_INDEX[n] ?? 0;
+    const consistencyRatio = ri === 0 ? 0 : ci / ri;
+    return { weights, consistencyRatio };
+}
+export function computeCRITICWeights(metricScoreHistory) {
+    const metrics = Object.keys(metricScoreHistory);
+    if (metrics.length === 1) {
+        const m = metrics[0] ?? '';
+        const sd = computeStdDev(metricScoreHistory[m] ?? []) ?? 0;
+        return {
+            weights: { [m]: 1.0 },
+            informationContent: { [m]: sd },
+        };
+    }
+    // Stddev per metric
+    const stdevs = {};
+    for (const m of metrics)
+        stdevs[m] = computeStdDev(metricScoreHistory[m] ?? []) ?? 0;
+    // Pearson correlation matrix
+    const correlations = {};
+    for (const m of metrics) {
+        correlations[m] = {};
+        for (const other of metrics) {
+            if (m === other) {
+                if (correlations[m])
+                    correlations[m][other] = 1;
+            }
+            else {
+                if (correlations[m])
+                    correlations[m][other] = computePearsonR(metricScoreHistory[m] ?? [], metricScoreHistory[other] ?? []);
+            }
+        }
+    }
+    // Information content = stddev × (1 - mean(|correlations with other metrics|))
+    const informationContent = {};
+    for (const m of metrics) {
+        const others = metrics.filter(o => o !== m);
+        const meanAbsCorr = others.length === 0
+            ? 0
+            : others.reduce((acc, o) => acc + Math.abs(correlations[m]?.[o] ?? 0), 0) / others.length;
+        const ic = (stdevs[m] ?? 0) * (1 - meanAbsCorr);
+        informationContent[m] = Number.isFinite(ic) ? ic : 0;
+    }
+    // Normalize to get weights
+    const totalIC = Object.values(informationContent).reduce((a, v) => a + v, 0);
+    const weights = {};
+    if (totalIC === 0) {
+        for (const m of metrics)
+            weights[m] = 1 / metrics.length;
+    }
+    else {
+        for (const m of metrics)
+            weights[m] = (informationContent[m] ?? 0) / totalIC;
+    }
+    return { weights, informationContent };
+}
+export function computeHybridCQIWeights(ahpWeights, criticWeights, incidents, metrics, alpha = AHP_CRITIC_DEFAULT_ALPHA) {
+    // Blend AHP and CRITIC weights
+    const blended = {};
+    for (const m of metrics) {
+        blended[m] = alpha * (ahpWeights[m] ?? 0) + (1 - alpha) * (criticWeights[m] ?? 0);
+    }
+    // Normalize blended weights
+    const blendedSum = Object.values(blended).reduce((a, v) => a + v, 0);
+    const weights = {};
+    for (const m of metrics) {
+        weights[m] = blendedSum === 0 ? 1 / metrics.length : (blended[m] ?? 0) / blendedSum;
+    }
+    // Incident correlations
+    const incidentCorrelations = {};
+    if (incidents.length === 0) {
+        for (const m of metrics)
+            incidentCorrelations[m] = 0;
+    }
+    else {
+        // For each metric: average score drop at incident times vs overall mean
+        // Use point-biserial: incident signal = 1 at incident timestamps, 0 otherwise
+        // Simplify: compute mean metric score at incident times; higher drop = higher correlation
+        // Actually compute the "drop magnitude" = overallMean - incidentMean (if positive, metric drops at incidents)
+        // Normalize across metrics to get relative correlation values
+        const drops = {};
+        for (const m of metrics) {
+            const incidentScores = incidents
+                .map(inc => inc.metricScores[m])
+                .filter((v) => v !== undefined);
+            const meanAtIncident = incidentScores.length === 0
+                ? 0
+                : incidentScores.reduce((a, v) => a + v, 0) / incidentScores.length;
+            drops[m] = 1 - meanAtIncident; // higher drop value means more correlated with incident
+        }
+        // Normalize drops to sum to 1 if there's signal, else keep raw
+        const maxDrop = Math.max(...Object.values(drops));
+        const minDrop = Math.min(...Object.values(drops));
+        const range = maxDrop - minDrop;
+        for (const m of metrics) {
+            incidentCorrelations[m] = range === 0 ? 0 : ((drops[m] ?? 0) - minDrop) / range;
+        }
+    }
+    return {
+        featureVersion: TUNED_CQI_WEIGHTS_FEATURE_VERSION,
+        weights,
+        ahpWeights,
+        criticWeights,
+        alpha,
+        consistencyRatio: 0,
+        incidentCorrelations,
+    };
+}
+const ZERO_TAPR_METRICS = { precision: 0, recall: 0, f1: 0, detectionDelay: 0 };
+export function computeTaPR(detectedRanges, incidentRanges) {
+    if (detectedRanges.length === 0 || incidentRanges.length === 0)
+        return ZERO_TAPR_METRICS;
+    const overlapMs = (a, b) => Math.max(0, Math.min(a.end, b.end) - Math.max(a.start, b.start));
+    // Precision: average overlap ratio per detected range
+    let precisionSum = 0;
+    for (const d of detectedRanges) {
+        const dDuration = d.end - d.start;
+        if (dDuration <= 0)
+            continue;
+        let overlap = 0;
+        for (const inc of incidentRanges)
+            overlap += overlapMs(d, inc);
+        precisionSum += Math.min(1, overlap / dDuration);
+    }
+    const precision = precisionSum / detectedRanges.length;
+    // Recall: average overlap ratio per incident range
+    let recallSum = 0;
+    for (const inc of incidentRanges) {
+        const incDuration = inc.end - inc.start;
+        if (incDuration <= 0)
+            continue;
+        let overlap = 0;
+        for (const d of detectedRanges)
+            overlap += overlapMs(d, inc);
+        recallSum += Math.min(1, overlap / incDuration);
+    }
+    const recall = recallSum / incidentRanges.length;
+    const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
+    // Detection delay: for each incident with an overlapping detection, delay = max(0, firstOverlappingDetection.start - incident.start)
+    const delays = [];
+    for (const inc of incidentRanges) {
+        const overlapping = detectedRanges.filter(d => overlapMs(d, inc) > 0);
+        if (overlapping.length === 0)
+            continue;
+        const firstStart = Math.min(...overlapping.map(d => d.start));
+        delays.push(Math.max(0, firstStart - inc.start));
+    }
+    const detectionDelay = delays.length > 0 ? delays.reduce((a, b) => a + b, 0) / delays.length : 0;
+    return { precision, recall, f1, detectionDelay };
+}
+/** Returns true if any signal for the point exceeds its configured threshold. */
+function isPointBreaching(pt, config) {
+    const varianceRatio = pt.baselineStdDev > 0 ? pt.currentStdDev / pt.baselineStdDev : 0;
+    const dropoutRate = pt.totalCoverageCells > 0 ? pt.coverageGapCount / pt.totalCoverageCells : 0;
+    const skewRatio = pt.latencyP50 > 0 ? pt.latencyP95 / pt.latencyP50 : 0;
+    const ewmaDrift = config.ewmaLambda !== undefined && pt.historicalValues.length > 0
+        && detectEWMADrift(pt.historicalValues, config.ewmaLambda);
+    const signals = [
+        varianceRatio > config.varianceThreshold,
+        dropoutRate > config.coverageDropoutThreshold,
+        skewRatio > config.latencySkewThreshold,
+        ewmaDrift,
+    ];
+    return signals.some(Boolean);
+}
+/**
+ * Runs a degradation signal backtest with a specific parameter configuration.
+ * Replays historical time series data and compares detected degradation periods
+ * against labeled incidents using TaPR and point-based metrics.
+ */
+export function backtestDegradationConfig(config, timeSeries, incidents) {
+    if (timeSeries.length === 0) {
+        return { config, truePositives: 0, falsePositives: 0, falseNegatives: 0, trueNegatives: 0,
+            tapr: ZERO_TAPR_METRICS, pointPrecision: 0, pointRecall: 0, pointF1: 0 };
+    }
+    const incidentRanges = incidents.map(inc => ({
+        start: new Date(inc.startTime).getTime(),
+        end: new Date(inc.endTime).getTime(),
+    }));
+    // Classify each timestamp as breaching or not
+    const breaching = timeSeries.map(pt => isPointBreaching(pt, config));
+    // Build confirmed degradation state per timestamp (confirmationWindow consecutive breaches)
+    const confirmed = new Array(timeSeries.length).fill(false);
+    let consecutiveBreaches = 0;
+    for (let i = 0; i < timeSeries.length; i++) {
+        consecutiveBreaches = breaching[i] ? consecutiveBreaches + 1 : 0;
+        confirmed[i] = consecutiveBreaches >= config.confirmationWindow;
+    }
+    // Build detected ranges from consecutive confirmed timestamps
+    const detectedRanges = [];
+    let rangeStart = null;
+    for (let i = 0; i < timeSeries.length; i++) {
+        if (confirmed[i]) {
+            if (rangeStart === null)
+                rangeStart = timeSeries[i].timestamp;
+        }
+        else {
+            if (rangeStart !== null) {
+                detectedRanges.push({ start: rangeStart, end: timeSeries[i - 1].timestamp });
+                rangeStart = null;
+            }
+        }
+    }
+    if (rangeStart !== null) {
+        detectedRanges.push({ start: rangeStart, end: timeSeries[timeSeries.length - 1].timestamp });
+    }
+    const tapr = computeTaPR(detectedRanges, incidentRanges);
+    // Point-based classification
+    let tp = 0, fp = 0, fn = 0, tn = 0;
+    for (let i = 0; i < timeSeries.length; i++) {
+        const ts = timeSeries[i].timestamp;
+        const inIncident = incidentRanges.some(r => ts >= r.start && ts <= r.end);
+        if (confirmed[i]) {
+            if (inIncident)
+                tp++;
+            else
+                fp++;
+        }
+        else {
+            if (inIncident)
+                fn++;
+            else
+                tn++;
+        }
+    }
+    const pointPrecision = tp + fp > 0 ? tp / (tp + fp) : 0;
+    const pointRecall = tp + fn > 0 ? tp / (tp + fn) : 0;
+    const pointF1 = pointPrecision + pointRecall > 0
+        ? (2 * pointPrecision * pointRecall) / (pointPrecision + pointRecall)
+        : 0;
+    return { config, truePositives: tp, falsePositives: fp, falseNegatives: fn, trueNegatives: tn,
+        tapr, pointPrecision, pointRecall, pointF1 };
+}
+/** All cartesian-product BacktestConfig combinations from BACKTEST_SWEEP */
+const SWEEP_CONFIGS = (() => {
+    const { varianceThreshold, coverageDropoutThreshold, ewmaLambda, confirmationWindow, stabilityThreshold } = BACKTEST_SWEEP;
+    const configs = [];
+    for (const vt of varianceThreshold) {
+        for (const cdt of coverageDropoutThreshold) {
+            for (const lambda of ewmaLambda) {
+                for (const cw of confirmationWindow) {
+                    for (const st of stabilityThreshold) {
+                        configs.push({ varianceThreshold: vt, coverageDropoutThreshold: cdt, ewmaLambda: lambda, confirmationWindow: cw, stabilityThreshold: st, latencySkewThreshold: LATENCY_SKEW_SIGNAL_THRESHOLD });
+                    }
+                }
+            }
+        }
+    }
+    return configs;
+})();
+/**
+ * Runs a full parameter sweep across the BACKTEST_SWEEP grid, ranks results by TaPR F1,
+ * and includes the current production config as a baseline comparison.
+ */
+export function sweepDegradationParams(timeSeries, incidents) {
+    const configs = SWEEP_CONFIGS;
+    const results = configs.map(config => backtestDegradationConfig(config, timeSeries, incidents));
+    const currentConfigResult = backtestDegradationConfig(CURRENT_PRODUCTION_CONFIG, timeSeries, incidents);
+    const bestByF1 = results.reduce((best, r) => r.tapr.f1 > best.tapr.f1 ? r : best, results[0]);
+    const bestByRecall = results.reduce((best, r) => r.tapr.recall > best.tapr.recall ? r : best, results[0]);
+    return { results, bestByF1, bestByRecall, currentConfigResult };
+}
+/**
+ * Leave-one-out cross-validation for sweepDegradationParams.
+ *
+ * With only 5-10 incidents, overfitting risk is high. This function holds out
+ * each incident in turn, runs the full sweep on the remaining incidents, and
+ * reports variance in the optimal config selection across folds.
+ *
+ * High parameterVariance values indicate that the best config is sensitive to
+ * individual incidents and should not be trusted for threshold graduation.
+ */
+export function sweepWithCrossValidation(timeSeries, incidents) {
+    const fullSweep = sweepDegradationParams(timeSeries, incidents);
+    // LOO folds — each fold holds out one incident
+    const folds = incidents.map((heldOut, i) => {
+        const remaining = incidents.filter((_, j) => j !== i);
+        return { heldOutIncident: heldOut, sweepResult: sweepDegradationParams(timeSeries, remaining) };
+    });
+    // Compute std dev of best-by-F1 config parameters across folds
+    const paramValues = folds.map(f => f.sweepResult.bestByF1.config);
+    const varStd = computeStdDev(paramValues.map(c => c.varianceThreshold)) ?? 0;
+    const dropStd = computeStdDev(paramValues.map(c => c.coverageDropoutThreshold)) ?? 0;
+    const winStd = computeStdDev(paramValues.map(c => c.confirmationWindow)) ?? 0;
+    // Stable when every LOO fold selects the same best-by-F1 config as the full sweep.
+    // Values are from a discrete sweep grid, so exact equality is safe.
+    const fullBest = fullSweep.bestByF1.config;
+    const isStable = folds.every(f => {
+        const fb = f.sweepResult.bestByF1.config;
+        return fb.varianceThreshold === fullBest.varianceThreshold &&
+            fb.coverageDropoutThreshold === fullBest.coverageDropoutThreshold &&
+            fb.confirmationWindow === fullBest.confirmationWindow;
+    });
+    return {
+        fullSweep,
+        folds,
+        parameterStability: {
+            varianceThresholdStdDev: varStd,
+            coverageDropoutThresholdStdDev: dropStd,
+            confirmationWindowStdDev: winStd,
+        },
+        isStable,
+    };
+}
+//# sourceMappingURL=quality-feature-engineering.js.map