apm-optima 1.0.4 → 2.0.0

package/dist/core/telemetry/telemetry.service.js

@@ -1,20 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const local_repository_1 = require("../storage/local.repository");
-const config_1 = require("../../config");
+exports.TelemetryService = void 0;
+function globToRegExp(glob) {
+    let source = '';
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === '*') {
+            if (glob[i + 1] === '*') {
+                const slash = glob[i + 2] === '/';
+                source += slash ? '(?:.*/)?' : '.*';
+                i += slash ? 2 : 1;
+            }
+            else {
+                source += '[^/]*';
+            }
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else {
+            source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
 class TelemetryService {
     storage;
-    constructor(storage = local_repository_1.storage) {
+    excludePatterns;
+    inFlight = 0;
+    drainWaiters = [];
+    constructor(storage, config) {
         this.storage = storage;
+        this.excludePatterns = config.collection.excludePaths.map(globToRegExp);
     }
     isPathExcluded(endpoint) {
         const cleanPath = endpoint.split('?')[0];
-        const userConfig = (0, config_1.getConfig)();
-        const configuredPaths = userConfig?.excludePaths || [];
-        const allPatterns = [...configuredPaths];
-        return allPatterns.some(pattern => {
-            const cleanPattern = pattern.replace(/\*/g, '');
-            return cleanPath.includes(cleanPattern);
+        return this.excludePatterns.some(pattern => pattern.test(cleanPath));
+    }
+    track() {
+        this.inFlight++;
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            this.inFlight--;
+            if (this.inFlight === 0) {
+                const waiters = this.drainWaiters;
+                this.drainWaiters = [];
+                for (const w of waiters)
+                    w();
+            }
+        };
+    }
+    get inFlightCount() { return this.inFlight; }
+    whenDrained(timeoutMs) {
+        if (this.inFlight === 0)
+            return Promise.resolve(true);
+        return new Promise(resolve => {
+            const timer = setTimeout(() => {
+                this.drainWaiters = this.drainWaiters.filter(w => w !== onDrain);
+                resolve(false);
+            }, timeoutMs);
+            timer.unref();
+            const onDrain = () => { clearTimeout(timer); resolve(true); };
+            this.drainWaiters.push(onDrain);
         });
     }
     record(data, startHrTime) {
@@ -33,4 +83,4 @@ class TelemetryService {
         return telemetryRequest;
     }
 }
-exports.default = TelemetryService;
+exports.TelemetryService = TelemetryService;

package/dist/core/telemetry/utility/correlation-analysis.d.ts

@@ -0,0 +1,9 @@
+import { CorrelationAnalysis } from '../../domain';
+interface AnalyzeCorrelationOptions {
+    strongThreshold?: number;
+    maxLag?: number;
+    xLabel?: string;
+    yLabel?: string;
+}
+export declare function analyzeCorrelation(xInput: number[], yInput: number[], requiredN: number, options?: AnalyzeCorrelationOptions): CorrelationAnalysis;
+export {};

package/dist/core/telemetry/utility/correlation-analysis.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCorrelation = analyzeCorrelation;
+const statistics_1 = require("../../utility/statistics");
+const DEFAULT_STRONG_THRESHOLD = 0.7;
+const DEFAULT_MAX_LAG = 5;
+const MIN_POINTS = 5;
+const VARIATION_TOLERANCE = 1e-9;
+function keepFinitePairs(x, y) {
+    const xs = [];
+    const ys = [];
+    for (let i = 0; i < x.length; i++) {
+        if (Number.isFinite(x[i]) && Number.isFinite(y[i])) {
+            xs.push(x[i]);
+            ys.push(y[i]);
+        }
+    }
+    return { x: xs, y: ys };
+}
+function isConstant(series) {
+    return series.every((value) => value === series[0]);
+}
+function hasNoVariation(series, reference) {
+    const scale = Math.max(1, reference.reduce((max, v) => Math.max(max, Math.abs(v)), 0));
+    return (0, statistics_1.standardDeviation)(series) <= VARIATION_TOLERANCE * scale;
+}
+function insufficient(sampleSize, requiredSampleSize, recommendation, partial = {}) {
+    return {
+        status: 'INSUFFICIENT_DATA',
+        direction: 'NONE',
+        pearsonR: 0,
+        spearmanR: 0,
+        rawPearsonR: 0,
+        differencePearsonR: 0,
+        determination: 0,
+        lag: 0,
+        laggedPearsonR: 0,
+        sampleSize,
+        effectiveSampleSize: 0,
+        requiredSampleSize,
+        autocorrelationX: 0,
+        autocorrelationY: 0,
+        trendDriven: false,
+        recommendation,
+        ...partial
+    };
+}
+function signOf(value) {
+    return value > 0 ? 'POSITIVE' : value < 0 ? 'NEGATIVE' : 'NONE';
+}
+function analyzeCorrelation(xInput, yInput, requiredN, options = {}) {
+    if (xInput.length !== yInput.length) {
+        throw new RangeError(`Series must have the same length (got ${xInput.length} and ${yInput.length})`);
+    }
+    const strong = options.strongThreshold ?? DEFAULT_STRONG_THRESHOLD;
+    const maxLag = options.maxLag ?? DEFAULT_MAX_LAG;
+    const xLabel = options.xLabel ?? 'X';
+    const yLabel = options.yLabel ?? 'Y';
+    const { x, y } = keepFinitePairs(xInput, yInput);
+    const n = x.length;
+    if (n < Math.max(requiredN, MIN_POINTS)) {
+        return insufficient(n, requiredN, `Insufficient data points. At least ${requiredN} valid pairs of ${xLabel} and ${yLabel} are required.`);
+    }
+    if (isConstant(x) || isConstant(y)) {
+        return insufficient(n, requiredN, `One of the series (${xLabel} or ${yLabel}) is constant. Correlation cannot be computed.`);
+    }
+    const dx = (0, statistics_1.linearDetrend)(x);
+    const dy = (0, statistics_1.linearDetrend)(y);
+    if (hasNoVariation(dx, x) || hasNoVariation(dy, y)) {
+        return insufficient(n, requiredN, `One of the series (${xLabel} or ${yLabel}) has no variation after detrending. Correlation cannot be computed.`);
+    }
+    const autocorrelationX = (0, statistics_1.autocorrelation)(dx, 1);
+    const autocorrelationY = (0, statistics_1.autocorrelation)(dy, 1);
+    const nEff = (0, statistics_1.effectiveSampleSize)(n, autocorrelationX, autocorrelationY);
+    if (nEff < requiredN) {
+        return insufficient(n, requiredN, `Effective sample size is too small. At least ${requiredN} effective pairs of ${xLabel} and ${yLabel} are required.`, {
+            effectiveSampleSize: nEff,
+            autocorrelationX,
+            autocorrelationY
+        });
+    }
+    const pearsonR = (0, statistics_1.pearsonCorrelation)(dx, dy);
+    const spearmanR = (0, statistics_1.spearmanCorrelation)(dx, dy);
+    const rawPearsonR = (0, statistics_1.pearsonCorrelation)(x, y);
+    const differencePearsonR = (0, statistics_1.pearsonCorrelation)((0, statistics_1.difference)(x), (0, statistics_1.difference)(y));
+    const { determination } = (0, statistics_1.determinationAndAlienation)(pearsonR);
+    const lagged = (0, statistics_1.laggedCorrelation)(dx, dy, maxLag);
+    let status;
+    let direction;
+    if (Math.abs(pearsonR) >= strong) {
+        status = 'STRONG_LINEAR_ASSOCIATION';
+        direction = signOf(pearsonR);
+    }
+    else if (Math.abs(spearmanR) >= strong) {
+        status = 'STRONG_MONOTONIC_NONLINEAR_ASSOCIATION';
+        direction = signOf(spearmanR);
+    }
+    else {
+        status = 'NO_STRONG_ASSOCIATION';
+        direction = 'NONE';
+    }
+    const trendDriven = Math.abs(rawPearsonR) >= strong && Math.abs(pearsonR) < strong;
+    return {
+        status,
+        direction,
+        pearsonR,
+        spearmanR,
+        rawPearsonR,
+        differencePearsonR,
+        determination,
+        lag: lagged.lag,
+        laggedPearsonR: lagged.r,
+        sampleSize: n,
+        effectiveSampleSize: nEff,
+        requiredSampleSize: requiredN,
+        autocorrelationX,
+        autocorrelationY,
+        trendDriven,
+        recommendation: describe(status, direction, { pearsonR, spearmanR, rawPearsonR, lag: lagged.lag, laggedR: lagged.r, strong, trendDriven, xLabel, yLabel })
+    };
+}
+function describe(status, direction, ctx) {
+    const sign = direction === 'NEGATIVE' ? 'negative' : 'positive';
+    const parts = [];
+    if (status === 'STRONG_LINEAR_ASSOCIATION') {
+        parts.push(`In the observed period a strong linear correlation (${sign}, r=${ctx.pearsonR.toFixed(2)}) was detected between ${ctx.xLabel} and ${ctx.yLabel}. Correlation does not prove causality.`);
+    }
+    else if (status === 'STRONG_MONOTONIC_NONLINEAR_ASSOCIATION') {
+        parts.push(`In the observed period a strong monotonic nonlinear correlation (${sign}, ρ=${ctx.spearmanR.toFixed(2)}, r=${ctx.pearsonR.toFixed(2)}) was detected between ${ctx.xLabel} and ${ctx.yLabel}. The relationship could be logarithmic, threshold-based, saturating, or due to deviations; correlation does not prove causality.`);
+    }
+    else {
+        parts.push(`In the observed period no strong correlational relationship was detected between ${ctx.xLabel} and ${ctx.yLabel}.`);
+    }
+    if (ctx.trendDriven) {
+        parts.push(`The correlation is strong only on the raw series (r=${ctx.rawPearsonR.toFixed(2)}); it is possible that it is driven by a common trend.`);
+    }
+    if (ctx.lag !== 0 && Math.abs(ctx.laggedR) >= ctx.strong && status === 'NO_STRONG_ASSOCIATION') {
+        const leader = ctx.lag > 0 ? ctx.xLabel : ctx.yLabel;
+        const follower = ctx.lag > 0 ? ctx.yLabel : ctx.xLabel;
+        parts.push(`At a lag of ${Math.abs(ctx.lag)} samples (${leader} leads ${follower}), a strong correlation (r=${ctx.laggedR.toFixed(2)}) was observed.`);
+    }
+    return parts.join(' ');
+}

package/dist/core/telemetry/utility/correlation-finding.d.ts

@@ -0,0 +1,70 @@
+import type { analyzeCorrelation } from "./correlation-analysis";
+export declare const CORRELATION_METHOD_VERSION = "cor-2.0.0";
+export declare const INPUT_SCHEMA_VERSION = 2;
+export type CorrelationTransform = 'raw' | 'detrend' | 'difference';
+export type CorrelationResult = ReturnType<typeof analyzeCorrelation>;
+export interface CorrelationParameters {
+    requiredSampleSize: number;
+    minCorrelation: number;
+    alpha: number;
+    power: number;
+    strongThreshold: number;
+    maxLag: number;
+    maxWindow: number;
+    minCoverage: number;
+    gapPolicy: 'compact';
+}
+export interface CorrelationScope {
+    method?: string;
+    route?: string;
+}
+export interface InputIdentity {
+    sessionId: string;
+    bucketCount: number;
+    ranges: Array<[number, number]>;
+    digest: string;
+}
+export type CorrelationFinding = {
+    findingId: string;
+    evaluationKey: string;
+    sessionId: string;
+    instanceId: string;
+    scope: CorrelationScope;
+    metricX: string;
+    metricY: string;
+    windowStart: string;
+    windowEnd: string;
+    resolutionMs: number | null;
+    transform: CorrelationTransform;
+    methodVersion: string;
+    parameters: CorrelationParameters;
+    input: InputIdentity;
+    inputSchemaVersion: number;
+    createdAt: string;
+    source: 'live' | 'replay';
+    validPairCount: number;
+    droppedPairCount: number;
+    coverage: number;
+    qualityFlags: string[];
+    result: CorrelationResult;
+};
+export declare function stableStringify(v: unknown): string;
+export declare const sha256: (s: string) => string;
+export declare const scopeKey: (s: CorrelationScope) => string;
+export declare const parametersHash: (p: CorrelationParameters) => string;
+export declare function seriesKey(a: {
+    sessionId: string;
+    scope: CorrelationScope;
+    pairId: string;
+    resolutionMs: number | null;
+    transform: CorrelationTransform;
+    parameters: CorrelationParameters;
+}): string;
+export declare function evaluationKey(series: string, windowEndSequence: number, inputDigest: string): string;
+export declare function findingIdFor(a: {
+    sessionId: string;
+    scope: CorrelationScope;
+    pairId: string;
+    windowEndSequence: number;
+    evaluationKey: string;
+}): string;

package/dist/core/telemetry/utility/correlation-finding.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parametersHash = exports.scopeKey = exports.sha256 = exports.INPUT_SCHEMA_VERSION = exports.CORRELATION_METHOD_VERSION = void 0;
+exports.stableStringify = stableStringify;
+exports.seriesKey = seriesKey;
+exports.evaluationKey = evaluationKey;
+exports.findingIdFor = findingIdFor;
+const crypto_1 = require("crypto");
+exports.CORRELATION_METHOD_VERSION = 'cor-2.0.0';
+exports.INPUT_SCHEMA_VERSION = 2;
+function stableStringify(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o).sort().map(k => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(',')}}`;
+}
+const sha256 = (s) => (0, crypto_1.createHash)('sha256').update(s).digest('hex');
+exports.sha256 = sha256;
+const scopeKey = (s) => s.method || s.route ? `${s.method ?? '*'} ${s.route ?? '*'}` : 'service';
+exports.scopeKey = scopeKey;
+const parametersHash = (p) => (0, exports.sha256)(stableStringify(p)).slice(0, 12);
+exports.parametersHash = parametersHash;
+function seriesKey(a) {
+    return [
+        a.sessionId,
+        (0, exports.scopeKey)(a.scope),
+        a.pairId,
+        a.resolutionMs ?? 'raw',
+        a.transform,
+        exports.CORRELATION_METHOD_VERSION,
+        (0, exports.parametersHash)(a.parameters),
+    ].join('|');
+}
+function evaluationKey(series, windowEndSequence, inputDigest) {
+    return `${series}|end=${windowEndSequence}|in=${inputDigest}`;
+}
+function findingIdFor(a) {
+    return `${a.sessionId}:${encodeURIComponent((0, exports.scopeKey)(a.scope))}:${a.pairId}:${a.windowEndSequence}:${(0, exports.sha256)(a.evaluationKey).slice(0, 8)}`;
+}

package/dist/core/telemetry/utility/correlation-input.d.ts

@@ -0,0 +1,59 @@
+import type { SeriesPoint } from '../telemetry-query.service';
+import type { CorrelationDirection } from '../../domain';
+import { type CorrelationParameters, type CorrelationResult, type CorrelationTransform } from './correlation-finding';
+export interface Metric {
+    label: string;
+    select: (p: SeriesPoint) => number | null;
+}
+export declare const METRICS: {
+    rps: {
+        label: string;
+        select: (p: SeriesPoint) => number | null;
+    };
+    errorRate: {
+        label: string;
+        select: (p: SeriesPoint) => number | null;
+    };
+    heapUsage: {
+        label: string;
+        select: (p: SeriesPoint) => number | null;
+    };
+    p95Latency: {
+        label: string;
+        select: (p: SeriesPoint) => number | null;
+    };
+    averageLatency: {
+        label: string;
+        select: (p: SeriesPoint) => number | null;
+    };
+    eventLoopLag: {
+        label: string;
+        select: (p: SeriesPoint) => number | null;
+    };
+};
+export type MetricKey = keyof typeof METRICS;
+export interface PairConfig {
+    x: MetricKey;
+    y: MetricKey;
+    expectedDirection: Exclude<CorrelationDirection, 'NONE'>;
+}
+export declare const PAIRS: readonly PairConfig[];
+export declare const pairId: (x: MetricKey, y: MetricKey) => string;
+export interface PreparedSeries {
+    xs: number[];
+    ys: number[];
+    sequences: number[];
+    ranges: Array<[number, number]>;
+    bucketCount: number;
+    windowStart: string;
+    windowEnd: string;
+    windowEndSequence: number;
+    expectedIntervals: number;
+    validPairCount: number;
+    droppedPairCount: number;
+    coverage: number;
+    qualityFlags: string[];
+    digest: string;
+}
+export declare function prepareSeries(points: readonly SeriesPoint[], pair: Pick<PairConfig, 'x' | 'y'>, transform: CorrelationTransform, minCoverage: number): PreparedSeries;
+export declare function runAnalysis(prepared: Pick<PreparedSeries, 'xs' | 'ys'>, pair: Pick<PairConfig, 'x' | 'y'>, params: CorrelationParameters): CorrelationResult;

package/dist/core/telemetry/utility/correlation-input.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pairId = exports.PAIRS = exports.METRICS = void 0;
+exports.prepareSeries = prepareSeries;
+exports.runAnalysis = runAnalysis;
+const correlation_analysis_1 = require("./correlation-analysis");
+const bucket_metric_1 = require("../../storage/stores/bucket-metric");
+const correlation_finding_1 = require("./correlation-finding");
+const finite = (n) => typeof n === 'number' && Number.isFinite(n) ? n : null;
+const whenRequests = (p, pick) => p.requests.requestCount > 0 ? finite(pick((0, bucket_metric_1.deriveMetrics)(p.requests, p.durationMs))) : null;
+exports.METRICS = {
+    rps: { label: 'RPS', select: p => finite((0, bucket_metric_1.deriveMetrics)(p.requests, p.durationMs).rps) },
+    errorRate: { label: 'error rate', select: p => whenRequests(p, m => m.errorRate) },
+    heapUsage: { label: 'heap memory', select: p => finite(p.runtime.heapUsedBytes) },
+    p95Latency: { label: 'p95 latency', select: p => whenRequests(p, m => m.p95) },
+    averageLatency: { label: 'average latency', select: p => whenRequests(p, m => m.averageLatency) },
+    eventLoopLag: { label: 'event loop lag', select: p => finite((0, bucket_metric_1.deriveRuntime)(p.runtime, p.durationMs).eventLoopDelayMeanMs) },
+};
+exports.PAIRS = [
+    { x: 'eventLoopLag', y: 'p95Latency', expectedDirection: 'POSITIVE' },
+    { x: 'eventLoopLag', y: 'averageLatency', expectedDirection: 'POSITIVE' },
+    { x: 'heapUsage', y: 'eventLoopLag', expectedDirection: 'POSITIVE' },
+    { x: 'heapUsage', y: 'p95Latency', expectedDirection: 'POSITIVE' },
+    { x: 'rps', y: 'errorRate', expectedDirection: 'POSITIVE' },
+    { x: 'rps', y: 'p95Latency', expectedDirection: 'POSITIVE' }
+];
+const pairId = (x, y) => `${x}->${y}`;
+exports.pairId = pairId;
+const PROPAGATED_FLAGS = ['LATE_CLOSE', 'PARTIAL', 'MIXED_ORIGIN', 'CLOCK_SKEW'];
+function toRanges(points) {
+    const ranges = [];
+    for (const p of points) {
+        const last = ranges[ranges.length - 1];
+        if (last && p.sequenceFrom === last[1] + 1)
+            last[1] = p.sequenceTo;
+        else
+            ranges.push([p.sequenceFrom, p.sequenceTo]);
+    }
+    return ranges;
+}
+function detrend(seq, values) {
+    const n = values.length;
+    if (n < 2)
+        return values.slice();
+    const t0 = seq[0];
+    let st = 0, sv = 0, stt = 0, stv = 0;
+    for (let i = 0; i < n; i++) {
+        const t = seq[i] - t0;
+        st += t;
+        sv += values[i];
+        stt += t * t;
+        stv += t * values[i];
+    }
+    const denom = n * stt - st * st;
+    const slope = denom === 0 ? 0 : (n * stv - st * sv) / denom;
+    const intercept = (sv - slope * st) / n;
+    return values.map((v, i) => v - (intercept + slope * (seq[i] - t0)));
+}
+function prepareSeries(points, pair, transform, minCoverage) {
+    if (points.length === 0)
+        throw new Error('prepareSeries: empty window');
+    const x = exports.METRICS[pair.x];
+    const y = exports.METRICS[pair.y];
+    let seq = [];
+    let xs = [];
+    let ys = [];
+    for (const p of points) {
+        const vx = x.select(p);
+        const vy = y.select(p);
+        if (vx === null || vy === null)
+            continue;
+        seq.push(p.sequenceTo);
+        xs.push(vx);
+        ys.push(vy);
+    }
+    const afterPairing = seq.length;
+    if (transform === 'difference') {
+        const s2 = [], x2 = [], y2 = [];
+        for (let i = 1; i < seq.length; i++) {
+            if (seq[i] !== seq[i - 1] + 1)
+                continue;
+            s2.push(seq[i]);
+            x2.push(xs[i] - xs[i - 1]);
+            y2.push(ys[i] - ys[i - 1]);
+        }
+        seq = s2;
+        xs = x2;
+        ys = y2;
+    }
+    else if (transform === 'detrend') {
+        xs = detrend(seq, xs);
+        ys = detrend(seq, ys);
+    }
+    const first = points[0];
+    const last = points[points.length - 1];
+    const expectedIntervals = last.sequenceTo - first.sequenceFrom + 1;
+    const presentIntervals = points.reduce((s, p) => s + (p.sequenceTo - p.sequenceFrom + 1), 0);
+    const flags = new Set();
+    if (presentIntervals < expectedIntervals)
+        flags.add('GAPS');
+    if (afterPairing < points.length)
+        flags.add('INVALID_VALUES');
+    if (seq.length < afterPairing)
+        flags.add('TRANSFORM_LOSS');
+    if (seq.length < expectedIntervals && transform !== 'difference')
+        flags.add('COMPACTED_SERIES');
+    for (const p of points)
+        for (const f of p.qualityFlags) {
+            if (PROPAGATED_FLAGS.includes(f))
+                flags.add(f);
+        }
+    const coverage = expectedIntervals > 0 ? seq.length / expectedIntervals : 0;
+    if (coverage < minCoverage)
+        flags.add('LOW_COVERAGE');
+    const digest = (0, correlation_finding_1.sha256)(JSON.stringify({ t: transform, s: seq, x: xs, y: ys }));
+    return {
+        xs, ys,
+        sequences: seq,
+        ranges: toRanges(points),
+        bucketCount: points.reduce((s, p) => s + p.bucketCount, 0),
+        windowStart: first.startTime,
+        windowEnd: last.endTime,
+        windowEndSequence: last.sequenceTo,
+        expectedIntervals,
+        validPairCount: seq.length,
+        droppedPairCount: Math.max(0, expectedIntervals - seq.length),
+        coverage,
+        qualityFlags: [...flags].sort(),
+        digest,
+    };
+}
+function runAnalysis(prepared, pair, params) {
+    return (0, correlation_analysis_1.analyzeCorrelation)(prepared.xs, prepared.ys, params.requiredSampleSize, {
+        strongThreshold: params.strongThreshold,
+        maxLag: params.maxLag,
+        xLabel: exports.METRICS[pair.x].label,
+        yLabel: exports.METRICS[pair.y].label,
+    });
+}

package/dist/core/telemetry/utility/correlation-replay.d.ts

@@ -0,0 +1,24 @@
+import type { TelemetryQueryService } from '../telemetry-query.service';
+import { type CorrelationFinding } from './correlation-finding';
+export type ReplayOutcome = {
+    status: 'REPRODUCED';
+    replayed: CorrelationFinding;
+} | {
+    status: 'INPUT_MISSING';
+    expectedBuckets: number;
+    foundBuckets: number;
+} | {
+    status: 'INPUT_CHANGED';
+    storedDigest: string;
+    replayedDigest: string;
+} | {
+    status: 'RESULT_DIFFERS';
+    replayed: CorrelationFinding;
+} | {
+    status: 'UNSUPPORTED';
+    reason: string;
+} | {
+    status: 'NOT_FOUND';
+    findingId: string;
+};
+export declare function verifyFinding(queries: TelemetryQueryService, finding: CorrelationFinding): Promise<ReplayOutcome>;

package/dist/core/telemetry/utility/correlation-replay.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyFinding = verifyFinding;
+const correlation_finding_1 = require("./correlation-finding");
+const correlation_input_1 = require("./correlation-input");
+const inRanges = (seqFrom, seqTo, ranges) => ranges.some(([a, b]) => seqFrom >= a && seqTo <= b);
+async function verifyFinding(queries, finding) {
+    if (finding.inputSchemaVersion !== correlation_finding_1.INPUT_SCHEMA_VERSION) {
+        return { status: 'UNSUPPORTED', reason: `input schema ${finding.inputSchemaVersion}` };
+    }
+    const pair = correlation_input_1.PAIRS.find(p => p.x === finding.metricX && p.y === finding.metricY);
+    if (!pair)
+        return { status: 'UNSUPPORTED', reason: `unknown pair ${finding.metricX}->${finding.metricY}` };
+    const result = await queries.query({
+        sessionId: finding.sessionId,
+        from: finding.windowStart,
+        to: finding.windowEnd,
+        method: finding.scope.method,
+        route: finding.scope.route,
+        resolutionMs: finding.resolutionMs ?? undefined,
+        consistency: 'committed',
+    });
+    const points = result.points.filter(p => inRanges(p.sequenceFrom, p.sequenceTo, finding.input.ranges));
+    const found = points.reduce((s, p) => s + p.bucketCount, 0);
+    if (found < finding.input.bucketCount) {
+        return { status: 'INPUT_MISSING', expectedBuckets: finding.input.bucketCount, foundBuckets: found };
+    }
+    const prepared = (0, correlation_input_1.prepareSeries)(points, pair, finding.transform, finding.parameters.minCoverage);
+    if (prepared.digest !== finding.input.digest) {
+        return { status: 'INPUT_CHANGED', storedDigest: finding.input.digest, replayedDigest: prepared.digest };
+    }
+    const replayedResult = (0, correlation_input_1.runAnalysis)(prepared, pair, finding.parameters);
+    const replayed = {
+        ...finding,
+        createdAt: new Date().toISOString(),
+        source: 'replay',
+        validPairCount: prepared.validPairCount,
+        droppedPairCount: prepared.droppedPairCount,
+        coverage: prepared.coverage,
+        qualityFlags: prepared.qualityFlags,
+        result: replayedResult,
+    };
+    return (0, correlation_finding_1.stableStringify)(replayedResult) === (0, correlation_finding_1.stableStringify)(finding.result)
+        ? { status: 'REPRODUCED', replayed }
+        : { status: 'RESULT_DIFFERS', replayed };
+}

package/dist/core/utility/correlation.analysis.d.ts

@@ -0,0 +1,9 @@
+import { CorrelationAnalysis } from '../domain';
+interface AnalyzeCorrelationOptions {
+    strongThreshold?: number;
+    maxLag?: number;
+    xLabel?: string;
+    yLabel?: string;
+}
+export declare function analyzeCorrelation(xInput: number[], yInput: number[], requiredN: number, options?: AnalyzeCorrelationOptions): CorrelationAnalysis;
+export {};