apm-optima 1.0.4 → 2.0.0

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

@@ -0,0 +1,144 @@
+"use strict";
+//! MOVE THIS FILE TO SERVICES/UTILITY
+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' ? 'negativna' : 'pozitivna';
+    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/utility/statistics.d.ts

@@ -48,6 +48,16 @@ export declare function median(data: number[]): number;
  * @returns The required sample size to achieve the specified margin of error and confidence level.
  */
 export declare function calculateSampleSizeProportion(marginOfError: number, confidenceLevel?: number): number;
+/**
+ * Calculates the number of INDEPENDENT observations needed to detect a correlation of at least
+ * `minCorrelation` with a two-sided test at significance level `alpha` and statistical power `power`.
+ * @param minCorrelation The smallest |r| worth detecting, in the open interval (0, 1). The sign is ignored.
+ * @param alpha Type I error probability (default 0.05).
+ * @param power Probability of detecting a true correlation of `minCorrelation` (default 0.80).
+ * @returns The required number of independent observations.
+ * @throws RangeError if any argument is outside its valid range.
+ */
+export declare function calculateSampleSizeCorrelation(minCorrelation: number, alpha?: number, power?: number): number;
 /**
  * Calculates the Pearson correlation coefficient (r) between two datasets.
  * The correlation coefficient measures the strength and direction of the linear relationship between two variables.
@@ -138,3 +148,58 @@ export declare function isDataAnomaly(value: number, data: number[], threshold?:
  * @returns A boolean indicating whether the value is an anomaly (true) or not (false).
  */
 export declare function isDataAnomalyHistogram(value: number, totalCount: number, totalSum: number, totalSumOfSquares: number, threshold?: number): boolean;
+/**
+ * Removes a linear trend from a series: fits an ordinary least squares line against the sample index
+ * and returns the residuals. Two series that both drift over time correlate strongly even when they are
+ * unrelated ("spurious correlation"); detrending removes that shared drift.
+ * @param data The series to detrend.
+ * @returns The residuals (same length as `data`, zero mean).
+ */
+export declare function linearDetrend(data: number[]): number[];
+/**
+ * Calculates the first differences of a series: d[i] = data[i + 1] - data[i].
+ * Correlating differences measures whether the CHANGES of two series move together,
+ * which is robust against shared trends and level shifts.
+ * @param data The series to difference.
+ * @returns An array of length `data.length - 1` (empty for fewer than 2 samples).
+ */
+export declare function difference(data: number[]): number[];
+/**
+ * Calculates the sample autocorrelation of a series at the given lag
+ * (the correlation of the series with a copy of itself shifted by `lag` samples).
+ * @param data The series.
+ * @param lag The shift in samples (default 1).
+ * @returns The autocorrelation in [-1, 1]; 0 for constant or too short series.
+ */
+export declare function autocorrelation(data: number[], lag?: number): number;
+/**
+ * Estimates the effective number of independent observations in a pair of autocorrelated series
+ * (Bartlett's AR(1) approximation):  n_eff = n * (1 - rhoX * rhoY) / (1 + rhoX * rhoY).
+ *
+ * 100 samples taken one second apart are usually NOT 100 independent observations. When both series
+ * are positively autocorrelated, n_eff can be several times smaller than n. When the product of the
+ * autocorrelations is not positive the samples are treated as independent (n_eff = n, never larger).
+ * @param n The raw number of samples.
+ * @param autocorrX Lag-1 autocorrelation of the first series.
+ * @param autocorrY Lag-1 autocorrelation of the second series.
+ * @returns The effective sample size, in [min(n, 2), n].
+ */
+export declare function effectiveSampleSize(n: number, autocorrX: number, autorcorrY: number): number;
+/**
+ * Finds the shift at which two series are most strongly (Pearson) correlated.
+ *
+ * Convention: a POSITIVE lag k pairs x[t] with y[t + k], i.e. x leads y by k samples;
+ * a NEGATIVE lag pairs x[t + k] with y[t], i.e. y leads x. At least 3 overlapping samples are kept.
+ * Ties prefer the smaller |lag| (lag 0 first).
+ *
+ * Because 2 * maxLag + 1 candidates are compared, the winning |r| is biased upwards -
+ * treat it as descriptive, not as a significance test.
+ * @param x The first series.
+ * @param y The second series (same length as x).
+ * @param maxLag The largest shift, in samples, to search in each direction.
+ * @returns The lag with the largest |r| and the correlation at that lag.
+ */
+export declare function laggedCorrelation(x: number[], y: number[], maxLag: number): {
+    lag: number;
+    r: number;
+};

package/dist/core/utility/statistics.js

@@ -7,6 +7,7 @@ exports.percentile = percentile;
 exports.percentileHistogram = percentileHistogram;
 exports.median = median;
 exports.calculateSampleSizeProportion = calculateSampleSizeProportion;
+exports.calculateSampleSizeCorrelation = calculateSampleSizeCorrelation;
 exports.pearsonCorrelation = pearsonCorrelation;
 exports.spearmanCorrelation = spearmanCorrelation;
 exports.determinationAndAlienation = determinationAndAlienation;
@@ -16,6 +17,11 @@ exports.zScore = zScore;
 exports.zScoreHistogram = zScoreHistogram;
 exports.isDataAnomaly = isDataAnomaly;
 exports.isDataAnomalyHistogram = isDataAnomalyHistogram;
+exports.linearDetrend = linearDetrend;
+exports.difference = difference;
+exports.autocorrelation = autocorrelation;
+exports.effectiveSampleSize = effectiveSampleSize;
+exports.laggedCorrelation = laggedCorrelation;
 /**
  * Generates a hash code for a given value. This function converts the value to a JSON string and computes a hash code based on its characters.
  * @param value The value to be hashed. It can be of any type that can be serialized to JSON.
@@ -159,6 +165,27 @@ function calculateSampleSizeProportion(marginOfError, confidenceLevel = 0.95) {
     const n = (Math.pow(z, 2) * p * (1 - p)) / Math.pow(marginOfError, 2);
     return Math.ceil(n);
 }
+/**
+ * Calculates the number of INDEPENDENT observations needed to detect a correlation of at least
+ * `minCorrelation` with a two-sided test at significance level `alpha` and statistical power `power`.
+ * @param minCorrelation The smallest |r| worth detecting, in the open interval (0, 1). The sign is ignored.
+ * @param alpha Type I error probability (default 0.05).
+ * @param power Probability of detecting a true correlation of `minCorrelation` (default 0.80).
+ * @returns The required number of independent observations.
+ * @throws RangeError if any argument is outside its valid range.
+ */
+function calculateSampleSizeCorrelation(minCorrelation, alpha = 0.05, power = 0.8) {
+    const r = Math.abs(minCorrelation);
+    if (!(r > 0 && r < 1))
+        throw new RangeError('minCorrelation must be in the open interval (0, 1)');
+    if (!(alpha > 0 && alpha < 1))
+        throw new RangeError('alpha must be in the open interval (0, 1)');
+    if (!(power > 0 && power < 1))
+        throw new RangeError('power must be in the open interval (0, 1)');
+    const fisherZ = 0.5 * Math.log((1 + r) / (1 - r));
+    const zSum = normsinv(1 - alpha / 2) + normsinv(power);
+    return Math.ceil((zSum / fisherZ) ** 2 + 3);
+}
 /**
  * Calculates the Pearson correlation coefficient (r) between two datasets.
  * The correlation coefficient measures the strength and direction of the linear relationship between two variables.
@@ -347,3 +374,117 @@ function isDataAnomalyHistogram(value, totalCount, totalSum, totalSumOfSquares,
     const z = zScoreHistogram(value, totalCount, totalSum, totalSumOfSquares);
     return Math.abs(z) > threshold;
 }
+/**
+ * Removes a linear trend from a series: fits an ordinary least squares line against the sample index
+ * and returns the residuals. Two series that both drift over time correlate strongly even when they are
+ * unrelated ("spurious correlation"); detrending removes that shared drift.
+ * @param data The series to detrend.
+ * @returns The residuals (same length as `data`, zero mean).
+ */
+function linearDetrend(data) {
+    const n = data.length;
+    if (n < 2)
+        return data.map(() => 0);
+    const meanT = (n - 1) / 2;
+    const meanY = mean(data);
+    let covariance = 0;
+    let varianceT = 0;
+    for (let i = 0; i < n; i++) {
+        const dt = i - meanT;
+        covariance += dt * (data[i] - meanY);
+        varianceT += dt * dt;
+    }
+    const slope = varianceT === 0 ? 0 : covariance / varianceT;
+    return data.map((value, i) => value - (meanY + slope * (i - meanT)));
+}
+/**
+ * Calculates the first differences of a series: d[i] = data[i + 1] - data[i].
+ * Correlating differences measures whether the CHANGES of two series move together,
+ * which is robust against shared trends and level shifts.
+ * @param data The series to difference.
+ * @returns An array of length `data.length - 1` (empty for fewer than 2 samples).
+ */
+function difference(data) {
+    const result = [];
+    for (let i = 1; i < data.length; i++) {
+        result.push(data[i] - data[i - 1]);
+    }
+    return result;
+}
+/**
+ * Calculates the sample autocorrelation of a series at the given lag
+ * (the correlation of the series with a copy of itself shifted by `lag` samples).
+ * @param data The series.
+ * @param lag The shift in samples (default 1).
+ * @returns The autocorrelation in [-1, 1]; 0 for constant or too short series.
+ */
+function autocorrelation(data, lag = 1) {
+    const n = data.length;
+    if (lag < 0 || n <= lag + 1)
+        return 0;
+    const mu = mean(data);
+    let denominator = 0;
+    for (let i = 0; i < n; i++) {
+        denominator += (data[i] - mu) ** 2;
+    }
+    if (denominator === 0)
+        return 0;
+    let numerator = 0;
+    for (let i = 0; i < n - lag; i++) {
+        numerator += (data[i] - mu) * (data[i + lag] - mu);
+    }
+    return numerator / denominator;
+}
+/**
+ * Estimates the effective number of independent observations in a pair of autocorrelated series
+ * (Bartlett's AR(1) approximation):  n_eff = n * (1 - rhoX * rhoY) / (1 + rhoX * rhoY).
+ *
+ * 100 samples taken one second apart are usually NOT 100 independent observations. When both series
+ * are positively autocorrelated, n_eff can be several times smaller than n. When the product of the
+ * autocorrelations is not positive the samples are treated as independent (n_eff = n, never larger).
+ * @param n The raw number of samples.
+ * @param autocorrX Lag-1 autocorrelation of the first series.
+ * @param autocorrY Lag-1 autocorrelation of the second series.
+ * @returns The effective sample size, in [min(n, 2), n].
+ */
+function effectiveSampleSize(n, autocorrX, autorcorrY) {
+    if (n <= 0)
+        return 0;
+    const product = autocorrX * autorcorrY;
+    if (product <= 0)
+        return n;
+    const nEff = (n * (1 - product)) / (1 + product);
+    return Math.min(n, Math.max(2, nEff));
+}
+/**
+ * Finds the shift at which two series are most strongly (Pearson) correlated.
+ *
+ * Convention: a POSITIVE lag k pairs x[t] with y[t + k], i.e. x leads y by k samples;
+ * a NEGATIVE lag pairs x[t + k] with y[t], i.e. y leads x. At least 3 overlapping samples are kept.
+ * Ties prefer the smaller |lag| (lag 0 first).
+ *
+ * Because 2 * maxLag + 1 candidates are compared, the winning |r| is biased upwards -
+ * treat it as descriptive, not as a significance test.
+ * @param x The first series.
+ * @param y The second series (same length as x).
+ * @param maxLag The largest shift, in samples, to search in each direction.
+ * @returns The lag with the largest |r| and the correlation at that lag.
+ */
+function laggedCorrelation(x, y, maxLag) {
+    if (x.length !== y.length || x.length === 0)
+        return { lag: 0, r: 0 };
+    const n = x.length;
+    let best = { lag: 0, r: pearsonCorrelation(x, y) };
+    const limit = Math.min(Math.floor(maxLag), n - 3);
+    for (let k = 1; k <= limit; k++) {
+        for (const lag of [k, -k]) {
+            const xs = lag > 0 ? x.slice(0, n - lag) : x.slice(-lag);
+            const ys = lag > 0 ? y.slice(lag) : y.slice(0, n + lag);
+            const r = pearsonCorrelation(xs, ys);
+            if (Math.abs(r) > Math.abs(best.r) + 1e-12) {
+                best = { lag, r };
+            }
+        }
+    }
+    return best;
+}

package/dist/express/index.d.ts

@@ -2,5 +2,5 @@ import express from 'express';
 import { Server as HTTPServer } from 'http';
 import { type ConfigOptions } from '../config';
 export declare function setupOptima(app: express.Express, options?: ConfigOptions): {
-    attachServer: (server: HTTPServer) => () => void;
+    attachServer: (server: HTTPServer) => (options?: import("./metrics.bootstrap").ExpressStopOptions) => Promise<void>;
 };

package/dist/express/index.js

@@ -9,17 +9,19 @@ const metrics_middleware_1 = require("./metrics.middleware");
 const metrics_dashboard_1 = require("./metrics.dashboard");
 const metrics_bootstrap_1 = require("./metrics.bootstrap");
 const logger_1 = __importDefault(require("../core/telemetry/logger"));
+const runtime_1 = require("../runtime");
 function setupOptima(app, options) {
     logger_1.default.debug('Initializing Optima with provided configuration options...');
     config_1.ConfigManager.getInstance().initialize(options);
     const config = config_1.ConfigManager.getInstance().get();
+    const dependencies = (0, runtime_1.createOptimaRuntime)(config);
     // Registering the metrics middleware
-    app.use(metrics_middleware_1.expressMetricsMiddleware);
+    app.use((0, metrics_middleware_1.createExpressMetricsMiddleware)(dependencies));
     logger_1.default.debug('Middlware for metrics collection has been registered successfully.');
     // Attaching the dashboard on provided path
-    if (config.dashboardPath !== false) {
-        (0, metrics_dashboard_1.attachDashboard)(app, config.dashboardPath);
-        logger_1.default.debug(`Dashboard has been attached at path: ${config.dashboardPath}`);
+    if (config.dashboard !== false) {
+        (0, metrics_dashboard_1.attachDashboard)(app, config.dashboard.path, dependencies.persistence);
+        logger_1.default.debug(`Dashboard has been attached at path: ${config.dashboard.path}`);
     }
     else {
         logger_1.default.debug('Dashboard attachment skipped as per configuration.');
@@ -27,7 +29,7 @@ function setupOptima(app, options) {
     return {
         attachServer: (server) => {
             logger_1.default.debug('Attaching server for metrics collection...');
-            return (0, metrics_bootstrap_1.expressMetricsBootstrap)(server);
+            return (0, metrics_bootstrap_1.expressMetricsBootstrap)(server, dependencies);
         }
     };
 }

package/dist/express/metrics-websocket.adapter.d.ts

@@ -1,11 +1,17 @@
 import type { Server as HTTPServer } from 'http';
 import type { WebSocketAdapter } from '../adapters/websocket.adapter';
-import { type MetricsDataProvider } from '../core/delivery';
+import { type CorrelationDataProvider, type IncidentDataProvider, type MetricsDataProvider, type SessionDataProvider } from '../core/delivery';
+import { type ReadonlyConfig } from '../config';
 export declare class ExpressWebSocketAdapter implements WebSocketAdapter {
     private readonly server;
     private readonly provider;
+    private readonly sessionProvider;
+    private readonly correlationProvider;
+    private readonly incidentProvider;
+    private readonly config;
     private io?;
-    constructor(server: HTTPServer, provider: MetricsDataProvider);
+    private isClosed;
+    constructor(server: HTTPServer, provider: MetricsDataProvider, sessionProvider: SessionDataProvider, correlationProvider: CorrelationDataProvider, incidentProvider: IncidentDataProvider, config: ReadonlyConfig);
     init(): void;
     private setupEvents;
     private setupClient;

package/dist/express/metrics-websocket.adapter.js

@@ -7,30 +7,32 @@ exports.ExpressWebSocketAdapter = void 0;
 const socket_io_1 = require("socket.io");
 const delivery_1 = require("../core/delivery");
 const config_1 = require("../config");
+const socket_options_1 = require("../adapters/socket.options");
 const logger_1 = __importDefault(require("../core/telemetry/logger"));
 class ExpressWebSocketAdapter {
     server;
     provider;
+    sessionProvider;
+    correlationProvider;
+    incidentProvider;
+    config;
     io;
-    constructor(server, provider) {
+    isClosed = false;
+    constructor(server, provider, sessionProvider, correlationProvider, incidentProvider, config) {
         this.server = server;
         this.provider = provider;
+        this.sessionProvider = sessionProvider;
+        this.correlationProvider = correlationProvider;
+        this.incidentProvider = incidentProvider;
+        this.config = config;
     }
     init() {
         if (this.io) {
             logger_1.default.debug('WebSocket server is already initialized.');
             return;
         }
-        this.io = new socket_io_1.Server(this.server, {
-            transports: ['websocket'],
-            maxHttpBufferSize: 1e8, // 100MB
-            pingTimeout: 10000, // 10 seconds
-            pingInterval: 25000, // 25 seconds
-            cors: {
-                origin: '*',
-                methods: ['GET', 'POST'],
-            },
-        });
+        this.io = new socket_io_1.Server(this.server, (0, socket_options_1.socketServerOptions)(this.config.transport));
+        this.isClosed = false;
         logger_1.default.debug('WebSocket server initialized successfully.');
         this.setupEvents();
     }
@@ -44,29 +46,62 @@ class ExpressWebSocketAdapter {
         });
     }
     setupClient(socket) {
+        socket.on(delivery_1.WebSocketEvents.REQUEST_SESSION_METADATA, async () => {
+            socket.emit(delivery_1.WebSocketEvents.RESPONSE_SESSION_METADATA, await this.sessionProvider.getSessionManifest());
+        });
+        socket.on(delivery_1.WebSocketEvents.REQUEST_SESSION_SUMMARY, async ({ sessionNumber }) => {
+            socket.emit(delivery_1.WebSocketEvents.RESPONSE_SESSION_SUMMARY, await this.sessionProvider.getSessionSummary(sessionNumber));
+        });
         socket.on(delivery_1.WebSocketEvents.REQUEST_CONFIGURATION, () => {
-            socket.emit(delivery_1.WebSocketEvents.RESPONSE_CONFIGURATION, config_1.ConfigManager.getInstance().get());
+            socket.emit(delivery_1.WebSocketEvents.RESPONSE_CONFIGURATION, (0, config_1.toClientConfig)(this.config));
         });
         socket.on(delivery_1.WebSocketEvents.REQUEST_SYSTEM_DATA, () => {
             socket.emit(delivery_1.WebSocketEvents.RESPONSE_SYSTEM_DATA, this.provider.getSystemStaticInfo());
         });
-        socket.on(delivery_1.WebSocketEvents.REQUEST_DASHBOARD_DATA, () => {
-            socket.emit(delivery_1.WebSocketEvents.RESPONSE_DASHBOARD_DATA, this.provider.getDashboardData());
-        });
-        socket.on(delivery_1.WebSocketEvents.REQUEST_ANALYTICS_DATA, () => {
-            socket.emit(delivery_1.WebSocketEvents.RESPONSE_ANALYTICS_DATA, this.provider.getAnalyticsData());
+        socket.on(delivery_1.WebSocketEvents.REQUEST_ANALYTICS_DATA, (filters) => {
+            if (filters === null) {
+                socket.emit(delivery_1.WebSocketEvents.RESPONSE_ANALYTICS_DATA, this.provider.getAnalyticsData());
+            }
+            else {
+                socket.emit(delivery_1.WebSocketEvents.RESPONSE_FILTERED_ANALYTICS_DATA, this.provider.getAnalyticsData(filters));
+            }
         });
         socket.on(delivery_1.WebSocketEvents.REQUEST_HEALTH_DATA, () => {
             socket.emit(delivery_1.WebSocketEvents.RESPONSE_HEALTH_DATA, this.provider.getHealthData());
         });
+        socket.on(delivery_1.WebSocketEvents.REQUEST_CORRELATION_DATA, () => {
+            socket.emit(delivery_1.WebSocketEvents.RESPONSE_CORRELATION_DATA, this.correlationProvider.pack());
+        });
+        socket.on(delivery_1.WebSocketEvents.REQUEST_INCIDENTS, () => {
+            socket.emit(delivery_1.WebSocketEvents.RESPONSE_INCIDENTS, this.incidentProvider.snapshot());
+        });
+        socket.on(delivery_1.WebSocketEvents.REQUEST_DASHBOARD_BUCKETS, async (raw) => {
+            const req = (0, delivery_1.parseBucketsRequest)(raw);
+            if (!req)
+                return;
+            try {
+                socket.emit(delivery_1.WebSocketEvents.RESPONSE_DASHBOARD_BUCKETS, await this.provider.getBackFill(req));
+            }
+            catch (err) {
+                logger_1.default.error('Dashboard backfill failed:', err);
+            }
+        });
+        socket.on(delivery_1.WebSocketEvents.REQUEST_CORRELATION_REPLAY, async ({ findingId }) => {
+            socket.emit(delivery_1.WebSocketEvents.RESPONSE_CORRELATION_REPLAY, { findingId, outcome: await this.correlationProvider.replay(String(findingId)) });
+        });
         socket.on('disconnect', () => {
             logger_1.default.debug(`WebSocket disconnected: ${socket.id}`);
         });
+        void this.sessionProvider.getSessionManifest().then(manifest => socket.emit(delivery_1.WebSocketEvents.RESPONSE_SESSION_METADATA, manifest));
     }
     broadcast(event, data) {
         this.io?.emit(event, data);
     }
     disconnect() {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.io?.disconnectSockets(true);
         this.io?.close();
         this.io = undefined;
     }

package/dist/express/metrics.adapter.d.ts

@@ -1,6 +1,7 @@
 import type { Request, Response } from 'express';
 import type { HttpAdapter } from '../adapters/http.adapter';
 export declare class ExpressAdapter implements HttpAdapter<Request, Response> {
+    private getEndpoint;
     getRequest(request: Request): {
         method: string;
         endpoint: string;

package/dist/express/metrics.adapter.js

@@ -2,6 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExpressAdapter = void 0;
 class ExpressAdapter {
+    getEndpoint(request) {
+        const route = request.route?.path;
+        if (!route)
+            return request.path;
+        const baseUrl = request.baseUrl ?? '';
+        return `${baseUrl}${route}`;
+    }
     getRequest(request) {
         const { body, // Parsed JSON or form data
         params, // Route path variables
@@ -16,7 +23,7 @@ class ExpressAdapter {
          } = request;
         return {
             method,
-            endpoint: path,
+            endpoint: this.getEndpoint(request),
             clientIp: ip,
         };
     }

package/dist/express/metrics.bootstrap.d.ts

@@ -1,2 +1,7 @@
 import { Server as HTTPServer } from 'http';
-export declare function expressMetricsBootstrap(server: HTTPServer): () => void;
+import { type OptimaRuntimeDependencies } from '../runtime';
+export interface ExpressStopOptions {
+    closeServer?: boolean;
+    drainTimeoutMs?: number;
+}
+export declare function expressMetricsBootstrap(server: HTTPServer, dependencies: OptimaRuntimeDependencies): (options?: ExpressStopOptions) => Promise<void>;