@thotischner/observability-mcp 1.4.1 → 1.5.1

package/dist/analysis/backtest.js

@@ -0,0 +1,206 @@
+// ---------------------------------------------------------------------------
+// Backtesting harness — a labelled synthetic suite + scorer for the anomaly
+// engine. Each case carries ground truth (anomalous or not); the harness runs
+// the production detector over it and computes a confusion matrix →
+// precision / recall / F1. backtest.test.ts asserts a quality bar so a
+// detector regression fails CI, and the published numbers in the README are
+// regenerated from exactly this suite (they cannot silently drift).
+// ---------------------------------------------------------------------------
+import { detectAnomaly, } from "./anomaly.js";
+/** Deterministic LCG so the suite is byte-stable across runs and CI. */
+function rng(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s * 1664525 + 1013904223) >>> 0;
+        return s / 0x100000000;
+    };
+}
+const HOUR = 3_600_000;
+const T0 = Date.UTC(2026, 0, 1);
+const ts = (i, stepMs = 60_000) => T0 + i * stepMs;
+function series(values, stepMs = 60_000) {
+    return values.map((v, i) => ({ timestamp: ts(i, stepMs), value: v }));
+}
+/**
+ * Build the labelled suite. Multiple seeded variants per regime so the
+ * precision/recall figures are stable rather than hostage to one sample.
+ */
+export function buildSuite() {
+    const cases = [];
+    for (let v = 0; v < 6; v++) {
+        const r = rng(1000 + v);
+        const noise = (amp) => (r() - 0.5) * 2 * amp;
+        // --- POSITIVES -------------------------------------------------------
+        // Slow memory-leak ramp toward OOM (the production false-negative).
+        cases.push({
+            name: `mem-leak-ramp#${v}`,
+            category: "slow-ramp",
+            points: series(Array.from({ length: 40 }, (_, i) => 120 + i * 7 + noise(4)), HOUR / 6),
+            metricKind: "saturation",
+            anomalous: true,
+        });
+        // Hard latency spike sustained over the recent window.
+        cases.push({
+            name: `latency-spike#${v}`,
+            category: "spike",
+            points: series([
+                ...Array.from({ length: 25 }, () => 50 + noise(3)),
+                ...Array.from({ length: 6 }, () => 480 + noise(20)),
+            ]),
+            metricKind: "latency",
+            anomalous: true,
+        });
+        // Error-rate step jump.
+        cases.push({
+            name: `error-step#${v}`,
+            category: "step",
+            points: series([
+                ...Array.from({ length: 25 }, () => 1 + Math.abs(noise(0.5))),
+                ...Array.from({ length: 6 }, () => 40 + noise(3)),
+            ]),
+            metricKind: "error_rate",
+            anomalous: true,
+        });
+        // Gradual latency creep (no single spike point).
+        cases.push({
+            name: `latency-creep#${v}`,
+            category: "slow-ramp",
+            points: series(Array.from({ length: 36 }, (_, i) => 60 + i * 5 + noise(3)), HOUR / 6),
+            metricKind: "latency",
+            anomalous: true,
+        });
+        // --- NEGATIVES -------------------------------------------------------
+        // Stable noisy traffic.
+        cases.push({
+            name: `stable-noisy#${v}`,
+            category: "stable",
+            points: series(Array.from({ length: 40 }, () => 100 + noise(6))),
+            metricKind: "generic",
+            anomalous: false,
+        });
+        // Single transient blip — dwell/hysteresis must suppress it.
+        cases.push({
+            name: `transient-blip#${v}`,
+            category: "transient",
+            points: series([
+                ...Array.from({ length: 34 }, () => 50 + noise(3)),
+                520,
+                ...Array.from({ length: 3 }, () => 50 + noise(3)),
+            ]),
+            metricKind: "latency",
+            anomalous: false,
+        });
+        // Recovery: error-rate drops to zero — one-sided, not an anomaly.
+        cases.push({
+            name: `error-recovery#${v}`,
+            category: "one-sided",
+            points: series([
+                ...Array.from({ length: 25 }, () => 15 + Math.abs(noise(2))),
+                ...Array.from({ length: 6 }, () => 0),
+            ]),
+            metricKind: "error_rate",
+            anomalous: false,
+        });
+        // Diurnal pattern, sampled within a normal nightly trough — the
+        // seasonality-aware baseline must treat this as expected.
+        {
+            const pts = [];
+            for (let d = 0; d < 6; d++) {
+                for (let h = 0; h < 24; h++) {
+                    const night = h >= 22 || h <= 5;
+                    pts.push({ timestamp: T0 + (d * 24 + h) * HOUR, value: (night ? 10 : 100) + noise(2) });
+                }
+            }
+            cases.push({
+                name: `diurnal-trough#${v}`,
+                category: "seasonal",
+                points: pts.slice(0, 6 * 24 - 20), // ends mid-night
+                metricKind: "generic",
+                anomalous: false,
+            });
+        }
+    }
+    // --- HARD TIER -------------------------------------------------------
+    // Deliberately ambiguous / low-SNR cases. A perfect score here would be a
+    // sign the suite is too easy; we publish whatever the engine actually does.
+    for (let v = 0; v < 4; v++) {
+        const r = rng(7000 + v);
+        const noise = (amp) => (r() - 0.5) * 2 * amp;
+        // Low-SNR ramp: real leak, but noise amplitude ~ the per-step rise.
+        cases.push({
+            name: `noisy-ramp#${v}`,
+            category: "hard",
+            points: series(Array.from({ length: 38 }, (_, i) => 100 + i * 3 + noise(9)), HOUR / 6),
+            metricKind: "saturation",
+            anomalous: true,
+        });
+        // Modest step (≈3σ) just above the recent baseline.
+        cases.push({
+            name: `small-step#${v}`,
+            category: "hard",
+            points: series([
+                ...Array.from({ length: 25 }, () => 100 + noise(5)),
+                ...Array.from({ length: 6 }, () => 122 + noise(5)),
+            ]),
+            metricKind: "latency",
+            anomalous: true,
+        });
+        // Heavy noise, no real shift — must NOT alarm.
+        cases.push({
+            name: `heavy-noise-stable#${v}`,
+            category: "hard",
+            points: series(Array.from({ length: 40 }, () => 100 + noise(18))),
+            metricKind: "generic",
+            anomalous: false,
+        });
+        // Two-point blip (still below dwell-sustained) — must NOT alarm.
+        cases.push({
+            name: `double-blip#${v}`,
+            category: "hard",
+            points: series([
+                ...Array.from({ length: 32 }, () => 60 + noise(4)),
+                300,
+                300,
+                ...Array.from({ length: 4 }, () => 60 + noise(4)),
+            ]),
+            metricKind: "latency",
+            anomalous: false,
+        });
+    }
+    return cases;
+}
+export function runBacktest(cases = buildSuite()) {
+    let tp = 0, fp = 0, tn = 0, fn = 0;
+    const byCategory = {};
+    for (const c of cases) {
+        const verdict = detectAnomaly(c.points, { metricKind: c.metricKind }).isAnomaly;
+        const correct = verdict === c.anomalous;
+        if (verdict && c.anomalous)
+            tp++;
+        else if (verdict && !c.anomalous)
+            fp++;
+        else if (!verdict && !c.anomalous)
+            tn++;
+        else
+            fn++;
+        const cat = (byCategory[c.category] ??= { total: 0, correct: 0 });
+        cat.total++;
+        if (correct)
+            cat.correct++;
+    }
+    const precision = tp + fp === 0 ? 1 : tp / (tp + fp);
+    const recall = tp + fn === 0 ? 1 : tp / (tp + fn);
+    const f1 = precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+    return { total: cases.length, tp, fp, tn, fn, precision, recall, f1, byCategory };
+}
+export function formatReport(r) {
+    const pct = (n) => `${(n * 100).toFixed(1)}%`;
+    const lines = [
+        `Backtest: ${r.total} labelled cases`,
+        `  TP=${r.tp} FP=${r.fp} TN=${r.tn} FN=${r.fn}`,
+        `  precision=${pct(r.precision)} recall=${pct(r.recall)} F1=${pct(r.f1)}`,
+        `  by category:`,
+        ...Object.entries(r.byCategory).map(([k, v]) => `    ${k}: ${v.correct}/${v.total}`),
+    ];
+    return lines.join("\n");
+}

package/dist/analysis/backtest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/backtest.test.js

@@ -0,0 +1,34 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { buildSuite, runBacktest, formatReport } from "./backtest.js";
+// CI quality gate. The suite is deterministic (seeded), so these bounds are
+// stable; a detector change that regresses precision/recall fails CI here.
+// The README "Detection quality" table is regenerated from this same suite.
+describe("anomaly backtest — quality gate", () => {
+    const report = runBacktest(buildSuite());
+    it("suite is non-trivial and balanced", () => {
+        assert.ok(report.total >= 60, `expected ≥60 labelled cases, got ${report.total}`);
+        const positives = report.tp + report.fn;
+        const negatives = report.tn + report.fp;
+        assert.ok(positives >= 20 && negatives >= 20, "suite must have enough of both classes");
+    });
+    it("precision ≥ 0.95 (no spurious alerts)", () => {
+        assert.ok(report.precision >= 0.95, `precision ${report.precision.toFixed(3)} below gate\n${formatReport(report)}`);
+    });
+    it("recall ≥ 0.80", () => {
+        assert.ok(report.recall >= 0.8, `recall ${report.recall.toFixed(3)} below gate\n${formatReport(report)}`);
+    });
+    it("F1 ≥ 0.88", () => {
+        assert.ok(report.f1 >= 0.88, `F1 ${report.f1.toFixed(3)} below gate\n${formatReport(report)}`);
+    });
+    it("clean regimes are detected perfectly (no regression)", () => {
+        for (const regime of ["slow-ramp", "spike", "step", "stable", "transient", "one-sided", "seasonal"]) {
+            const c = report.byCategory[regime];
+            assert.ok(c, `missing category ${regime}`);
+            assert.equal(c.correct, c.total, `${regime}: ${c.correct}/${c.total} — regression\n${formatReport(report)}`);
+        }
+    });
+    it("prints the report (visible in CI logs)", () => {
+        console.log("\n" + formatReport(report) + "\n");
+    });
+});

package/dist/analysis/correlator.d.ts

@@ -5,3 +5,38 @@ import type { AnomalyReport, LogResult, MetricResult } from "../types.js";
  * in the same time window, they are correlated.
  */
 export declare function correlateSignals(anomalies: AnomalyReport[], logResults: LogResult[], metricResults: MetricResult[]): string[];
+/** Directed edge: `from` calls / depends on `to`. */
+export interface ServiceEdge {
+    from: string;
+    to: string;
+}
+export interface RankInputAnomaly {
+    service: string;
+    metric: string;
+    severity: "low" | "medium" | "high";
+    /** Epoch ms when the anomaly first breached, if known. Lower = earlier. */
+    onsetTs?: number;
+}
+export interface ChangeMarker {
+    service: string;
+    /** Epoch ms of a deploy / config change / rollout. */
+    ts: number;
+    kind?: string;
+}
+export interface RootCauseCandidate {
+    service: string;
+    score: number;
+    confidence: "low" | "medium" | "high";
+    reasons: string[];
+}
+export interface RootCauseResult {
+    ranked: RootCauseCandidate[];
+    summary: string;
+}
+/**
+ * Rank likely root-cause services among co-occurring anomalies.
+ *
+ * `edges` is the (caller → callee) service graph; it may be empty, in which
+ * case ranking falls back to onset ordering + change markers + severity.
+ */
+export declare function rankRootCause(anomalies: RankInputAnomaly[], edges?: ServiceEdge[], changes?: ChangeMarker[]): RootCauseResult;

package/dist/analysis/correlator.js

@@ -29,3 +29,98 @@ export function correlateSignals(anomalies, logResults, metricResults) {
     }
     return [...new Set(correlations)]; // Deduplicate
 }
+const SEV_WEIGHT = { low: 1, medium: 2, high: 3 };
+/**
+ * Rank likely root-cause services among co-occurring anomalies.
+ *
+ * `edges` is the (caller → callee) service graph; it may be empty, in which
+ * case ranking falls back to onset ordering + change markers + severity.
+ */
+export function rankRootCause(anomalies, edges = [], changes = []) {
+    const services = [...new Set(anomalies.map((a) => a.service))];
+    if (services.length === 0) {
+        return { ranked: [], summary: "No anomalies to attribute." };
+    }
+    // "depends on": from -> set(to). A root cause is a service that other
+    // anomalous services (transitively) depend on.
+    const deps = new Map();
+    for (const e of edges) {
+        if (!deps.has(e.from))
+            deps.set(e.from, new Set());
+        deps.get(e.from).add(e.to);
+    }
+    const dependsOn = (from, to, seen = new Set()) => {
+        if (seen.has(from))
+            return false;
+        seen.add(from);
+        const direct = deps.get(from);
+        if (!direct)
+            return false;
+        if (direct.has(to))
+            return true;
+        for (const mid of direct)
+            if (dependsOn(mid, to, seen))
+                return true;
+        return false;
+    };
+    const earliest = Math.min(...anomalies.filter((a) => a.onsetTs !== undefined).map((a) => a.onsetTs));
+    const haveOnset = Number.isFinite(earliest);
+    const candidates = services.map((svc) => {
+        const svcAnoms = anomalies.filter((a) => a.service === svc);
+        const reasons = [];
+        let score = 0;
+        // (1) Dependency position: how many *other* anomalous services depend on
+        // this one. Each dependent is a downstream symptom this service explains.
+        const dependents = services.filter((other) => other !== svc && dependsOn(other, svc));
+        if (dependents.length > 0) {
+            score += 5 * dependents.length;
+            reasons.push(`${dependents.length} anomalous service(s) depend on it (${dependents.join(", ")}) — their symptoms are likely downstream`);
+        }
+        // Penalty: this service depends on another anomalous one → likely a victim.
+        const upstreamCauses = services.filter((other) => other !== svc && dependsOn(svc, other));
+        if (upstreamCauses.length > 0) {
+            score -= 3 * upstreamCauses.length;
+            reasons.push(`depends on anomalous ${upstreamCauses.join(", ")} — may be a downstream victim`);
+        }
+        // (2) Onset ordering: started at/near the earliest onset.
+        if (haveOnset) {
+            const myOnset = Math.min(...svcAnoms.filter((a) => a.onsetTs !== undefined).map((a) => a.onsetTs));
+            if (Number.isFinite(myOnset)) {
+                const lagSec = Math.round((myOnset - earliest) / 1000);
+                if (lagSec <= 0) {
+                    score += 4;
+                    reasons.push("anomaly started first (earliest onset)");
+                }
+                else if (lagSec <= 60) {
+                    score += 1;
+                    reasons.push(`onset ${lagSec}s after the first signal`);
+                }
+                else {
+                    reasons.push(`onset ${lagSec}s after the first signal — likely reactive`);
+                }
+            }
+        }
+        // (3) Deploy/change marker shortly before onset.
+        const myOnset = svcAnoms.find((a) => a.onsetTs !== undefined)?.onsetTs;
+        const marker = changes
+            .filter((c) => c.service === svc)
+            .find((c) => myOnset === undefined || (c.ts <= myOnset && myOnset - c.ts <= 15 * 60_000));
+        if (marker) {
+            score += 4;
+            reasons.push(`${marker.kind || "change"} on this service ${myOnset ? `${Math.round((myOnset - marker.ts) / 1000)}s before onset` : "near the incident"}`);
+        }
+        // Tie-breaker: signal breadth × severity (small weight).
+        const breadth = svcAnoms.reduce((s, a) => s + SEV_WEIGHT[a.severity], 0);
+        score += 0.25 * breadth;
+        return { service: svc, score, confidence: "low", reasons };
+    });
+    candidates.sort((a, b) => b.score - a.score);
+    // Confidence from the score gap between #1 and #2.
+    const top = candidates[0];
+    const gap = candidates.length > 1 ? top.score - candidates[1].score : top.score;
+    top.confidence = gap >= 5 ? "high" : gap >= 2 ? "medium" : "low";
+    const summary = candidates.length === 1
+        ? `Single anomalous service: ${top.service}.`
+        : `Likely root cause: ${top.service} (${top.confidence} confidence). ${top.reasons[0] || "ranked by severity"}. ${candidates.length - 1} other service(s) likely downstream.`;
+    return { ranked: candidates, summary };
+}

package/dist/analysis/correlator.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { correlateSignals } from "./correlator.js";
+import { correlateSignals, rankRootCause } from "./correlator.js";
 describe("correlateSignals", () => {
     it("returns empty for no anomalies", () => {
         const result = correlateSignals([], [], []);
@@ -51,3 +51,62 @@ describe("correlateSignals", () => {
         assert.equal(result.length, unique.size);
     });
 });
+describe("rankRootCause", () => {
+    const A = (service, severity = "high", onsetTs) => ({
+        service,
+        metric: "latency_p99",
+        severity,
+        onsetTs,
+    });
+    it("returns empty result with no anomalies", () => {
+        const r = rankRootCause([]);
+        assert.deepEqual(r.ranked, []);
+    });
+    it("single anomalous service is the trivial answer", () => {
+        const r = rankRootCause([A("payment-service")]);
+        assert.equal(r.ranked.length, 1);
+        assert.equal(r.ranked[0].service, "payment-service");
+        assert.match(r.summary, /Single anomalous service/);
+    });
+    it("KEY: the depended-on service outranks its loud downstream caller", () => {
+        // api-gateway calls payment-service. Both anomalous, gateway has more
+        // signals — but payment-service is the cause; gateway is a victim.
+        const anomalies = [
+            A("api-gateway", "high"),
+            { service: "api-gateway", metric: "error_rate", severity: "high" },
+            A("payment-service", "medium"),
+        ];
+        const edges = [{ from: "api-gateway", to: "payment-service" }];
+        const r = rankRootCause(anomalies, edges);
+        assert.equal(r.ranked[0].service, "payment-service");
+        assert.ok(r.ranked.find((c) => c.service === "api-gateway").score <
+            r.ranked[0].score);
+        assert.match(r.summary, /payment-service/);
+    });
+    it("transitive dependency: gateway → order → payment ranks payment first", () => {
+        const r = rankRootCause([A("api-gateway"), A("order-service"), A("payment-service")], [
+            { from: "api-gateway", to: "order-service" },
+            { from: "order-service", to: "payment-service" },
+        ]);
+        assert.equal(r.ranked[0].service, "payment-service");
+    });
+    it("onset ordering breaks ties when no graph is available", () => {
+        const t = 1_700_000_000_000;
+        const r = rankRootCause([
+            A("order-service", "high", t + 90_000),
+            A("payment-service", "high", t),
+        ]);
+        assert.equal(r.ranked[0].service, "payment-service");
+        assert.ok(r.ranked[0].reasons.some((x) => /started first/.test(x)));
+    });
+    it("a deploy marker shortly before onset boosts that service", () => {
+        const t = 1_700_000_000_000;
+        const r = rankRootCause([A("payment-service", "medium", t), A("order-service", "high", t)], [], [{ service: "payment-service", ts: t - 120_000, kind: "deploy" }]);
+        assert.equal(r.ranked[0].service, "payment-service");
+        assert.ok(r.ranked[0].reasons.some((x) => /deploy/.test(x)));
+    });
+    it("confidence reflects the score gap", () => {
+        const clear = rankRootCause([A("api-gateway"), A("payment-service")], [{ from: "api-gateway", to: "payment-service" }]);
+        assert.equal(clear.ranked[0].confidence, "high");
+    });
+});

package/dist/analysis/health.d.ts

@@ -1,12 +1,12 @@
 import type { HealthStatus, HealthThresholds } from "../types.js";
-interface HealthInputs {
+export interface HealthInputs {
     cpu: number;
     memory: number;
     errorRate: number;
     latencyP99: number;
     logErrorRate: number;
 }
-interface HealthResult {
+export interface HealthResult {
     score: number;
     status: HealthStatus;
     details: Record<string, {
@@ -16,4 +16,3 @@ interface HealthResult {
     }>;
 }
 export declare function calculateHealthScore(inputs: HealthInputs, thresholds: HealthThresholds): HealthResult;
-export {};

package/dist/analysis/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Embeddable analysis library — the deterministic analysis engine
+ * (anomaly detection, seasonality, causal root-cause, health scoring) usable
+ * in-process, without running the MCP server or any transport.
+ *
+ *   import { analyzeMetric, rankRootCause, calculateHealthScore }
+ *     from "@thotischner/observability-mcp/analysis";
+ *
+ * Same code path as the MCP tools — verdicts are identical whether reached via
+ * the gateway or this library.
+ */
+export { detectAnomaly, detectRobustAnomaly, detectSeasonalAnomaly, detectRecentAnomaly, detectAnomalyPoints, calculateZScore, classifyMetric, median, mad, type MetricKind, type SeasonalPoint, type SeasonalAnomalyOptions, type SeasonalAnomalyResult, type RobustAnomalyOptions, type RobustAnomalyResult, type AnomalyPoint, type ZScoreResult, } from "./anomaly.js";
+export { correlateSignals, rankRootCause, type ServiceEdge, type RankInputAnomaly, type ChangeMarker, type RootCauseCandidate, type RootCauseResult, } from "./correlator.js";
+export { calculateHealthScore, type HealthInputs, type HealthResult, } from "./health.js";
+import { type SeasonalPoint } from "./anomaly.js";
+/**
+ * One-call façade: classify the metric by name and run the orchestrated
+ * detector (seasonal when enough history, else robust). Thin convenience over
+ * {@link detectAnomaly}; identical result to calling it directly with the
+ * classified `metricKind`.
+ */
+export declare function analyzeMetric(metric: string, points: SeasonalPoint[], opts?: {
+    threshold?: number;
+}): {
+    isAnomaly: boolean;
+    method: "seasonal" | "robust-z" | "trend" | "none";
+    score: number;
+    recentValue: number;
+    baselineValue: number;
+    direction: "above" | "below" | "flat";
+    reason: string;
+};

package/dist/analysis/index.js

@@ -0,0 +1,29 @@
+/**
+ * Embeddable analysis library — the deterministic analysis engine
+ * (anomaly detection, seasonality, causal root-cause, health scoring) usable
+ * in-process, without running the MCP server or any transport.
+ *
+ *   import { analyzeMetric, rankRootCause, calculateHealthScore }
+ *     from "@thotischner/observability-mcp/analysis";
+ *
+ * Same code path as the MCP tools — verdicts are identical whether reached via
+ * the gateway or this library.
+ */
+export { 
+// robust + seasonal + orchestrated anomaly detection
+detectAnomaly, detectRobustAnomaly, detectSeasonalAnomaly, detectRecentAnomaly, detectAnomalyPoints, calculateZScore, classifyMetric, median, mad, } from "./anomaly.js";
+export { correlateSignals, rankRootCause, } from "./correlator.js";
+export { calculateHealthScore, } from "./health.js";
+import { detectAnomaly, classifyMetric } from "./anomaly.js";
+/**
+ * One-call façade: classify the metric by name and run the orchestrated
+ * detector (seasonal when enough history, else robust). Thin convenience over
+ * {@link detectAnomaly}; identical result to calling it directly with the
+ * classified `metricKind`.
+ */
+export function analyzeMetric(metric, points, opts = {}) {
+    return detectAnomaly(points, {
+        metricKind: classifyMetric(metric),
+        threshold: opts.threshold,
+    });
+}

package/dist/analysis/library.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/analysis/library.test.js

@@ -0,0 +1,44 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import * as lib from "./index.js";
+import { detectAnomaly } from "./anomaly.js";
+// Contract test for the embeddable analysis library surface. Guards that the
+// public API stays importable in-process (no MCP/transport) and that the
+// analyzeMetric façade is exactly the engine path, not a divergent reimpl.
+describe("embeddable analysis library", () => {
+    it("exposes the documented public API", () => {
+        for (const name of [
+            "detectAnomaly",
+            "detectRobustAnomaly",
+            "detectSeasonalAnomaly",
+            "rankRootCause",
+            "correlateSignals",
+            "calculateHealthScore",
+            "classifyMetric",
+            "analyzeMetric",
+        ]) {
+            assert.equal(typeof lib[name], "function", `missing export: ${name}`);
+        }
+    });
+    it("analyzeMetric is identical to detectAnomaly with classified kind", () => {
+        const points = Array.from({ length: 40 }, (_, i) => ({
+            timestamp: 1_700_000_000_000 + i * 60_000,
+            value: i < 30 ? 50 + (i % 3) : 800,
+        }));
+        const viaFacade = lib.analyzeMetric("latency_p99", points);
+        const viaEngine = detectAnomaly(points, { metricKind: "latency" });
+        assert.deepEqual(viaFacade, viaEngine);
+    });
+    it("health scoring is callable standalone", () => {
+        const r = lib.calculateHealthScore({ cpu: 20, memory: 30, errorRate: 0, latencyP99: 0.2, logErrorRate: 0 }, {
+            weights: { errorRate: 1, latency: 1, cpu: 1, logErrors: 1 },
+            cpu: { good: 50, warn: 80, crit: 95 },
+            errorRate: { good: 1, warn: 5, crit: 10 },
+            latencyP99: { good: 0.5, warn: 1, crit: 2 },
+            logErrors: { good: 1, warn: 5, crit: 10 },
+            statusBoundaries: { healthy: 80, degraded: 50 },
+        });
+        assert.ok(r.score >= 0 && r.score <= 100);
+        assert.ok(["healthy", "degraded", "critical"].includes(r.status));
+    });
+});

package/dist/auth/credentials.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Single-tenant authentication primitive (opt-in, backward compatible).
+ *
+ * If no credentials are configured the server behaves exactly as before
+ * (anonymous, all access). If `OMCP_API_KEYS` is set, the `/mcp` endpoint
+ * requires a valid `Authorization: Bearer <token>` or `X-API-Key: <token>`.
+ *
+ * Config (env, no secrets in files):
+ *   OMCP_API_KEYS="ci:tok_abc,agent:tok_def"   # name:token, comma-separated
+ *                  (a bare "tok_xyz" is allowed; name defaults to "key")
+ *   OMCP_KEY_SOURCES="agent=prom-prod|loki-prod;ci=prom-staging"
+ *                  # optional coarse per-key source allow-list
+ *
+ * Rich role-based access control (tools/services/lookback/read-only, the
+ * full governance object) is intentionally NOT here — this is only the
+ * authentication + identity + coarse source-scoping primitive.
+ */
+export interface Credential {
+    name: string;
+    token: string;
+    allowedSources?: string[];
+}
+/** Parse credentials from env. Returns an empty list when unconfigured. */
+export declare function loadCredentials(env?: NodeJS.ProcessEnv): Credential[];
+export declare function credentialsConfigured(env?: NodeJS.ProcessEnv): boolean;
+/** Extract a bearer/api-key token from request headers. */
+export declare function extractToken(headers: Record<string, unknown>): string | null;
+/** Constant-time-ish token match → resolved credential, or null. */
+export declare function resolveToken(token: string | null, creds: Credential[]): Credential | null;