margin-ts 0.6.0

package/dist/index.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * margin — Typed health classification for systems that measure things.
+ *
+ * TypeScript port of the Python margin library.
+ * Zero dependencies. Pure TypeScript.
+ *
+ * Copyright (c) 2026 Cope Labs LLC. MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyAnomaly = exports.ANOMALY_SEVERITY = exports.AnomalyState = exports.classifyDrift = exports.DriftDirection = exports.DriftState = exports.Parser = exports.expressionToDict = exports.expressionToString = exports.degraded = exports.healthOf = exports.createExpression = exports.correctionIsActive = exports.observationFromDict = exports.observationToDict = exports.observationToAtom = exports.observationSigma = exports.Op = exports.classify = exports.isAblated = exports.isIntact = exports.createThresholds = exports.SEVERITY = exports.Health = exports.minConfidence = exports.confidenceLt = exports.confidenceGte = exports.confidenceRank = exports.Confidence = void 0;
+var confidence_js_1 = require("./confidence.js");
+Object.defineProperty(exports, "Confidence", { enumerable: true, get: function () { return confidence_js_1.Confidence; } });
+Object.defineProperty(exports, "confidenceRank", { enumerable: true, get: function () { return confidence_js_1.confidenceRank; } });
+Object.defineProperty(exports, "confidenceGte", { enumerable: true, get: function () { return confidence_js_1.confidenceGte; } });
+Object.defineProperty(exports, "confidenceLt", { enumerable: true, get: function () { return confidence_js_1.confidenceLt; } });
+Object.defineProperty(exports, "minConfidence", { enumerable: true, get: function () { return confidence_js_1.minConfidence; } });
+var health_js_1 = require("./health.js");
+Object.defineProperty(exports, "Health", { enumerable: true, get: function () { return health_js_1.Health; } });
+Object.defineProperty(exports, "SEVERITY", { enumerable: true, get: function () { return health_js_1.SEVERITY; } });
+Object.defineProperty(exports, "createThresholds", { enumerable: true, get: function () { return health_js_1.createThresholds; } });
+Object.defineProperty(exports, "isIntact", { enumerable: true, get: function () { return health_js_1.isIntact; } });
+Object.defineProperty(exports, "isAblated", { enumerable: true, get: function () { return health_js_1.isAblated; } });
+Object.defineProperty(exports, "classify", { enumerable: true, get: function () { return health_js_1.classify; } });
+var observation_js_1 = require("./observation.js");
+Object.defineProperty(exports, "Op", { enumerable: true, get: function () { return observation_js_1.Op; } });
+Object.defineProperty(exports, "observationSigma", { enumerable: true, get: function () { return observation_js_1.observationSigma; } });
+Object.defineProperty(exports, "observationToAtom", { enumerable: true, get: function () { return observation_js_1.observationToAtom; } });
+Object.defineProperty(exports, "observationToDict", { enumerable: true, get: function () { return observation_js_1.observationToDict; } });
+Object.defineProperty(exports, "observationFromDict", { enumerable: true, get: function () { return observation_js_1.observationFromDict; } });
+Object.defineProperty(exports, "correctionIsActive", { enumerable: true, get: function () { return observation_js_1.correctionIsActive; } });
+Object.defineProperty(exports, "createExpression", { enumerable: true, get: function () { return observation_js_1.createExpression; } });
+Object.defineProperty(exports, "healthOf", { enumerable: true, get: function () { return observation_js_1.healthOf; } });
+Object.defineProperty(exports, "degraded", { enumerable: true, get: function () { return observation_js_1.degraded; } });
+Object.defineProperty(exports, "expressionToString", { enumerable: true, get: function () { return observation_js_1.expressionToString; } });
+Object.defineProperty(exports, "expressionToDict", { enumerable: true, get: function () { return observation_js_1.expressionToDict; } });
+Object.defineProperty(exports, "Parser", { enumerable: true, get: function () { return observation_js_1.Parser; } });
+var drift_js_1 = require("./drift.js");
+Object.defineProperty(exports, "DriftState", { enumerable: true, get: function () { return drift_js_1.DriftState; } });
+Object.defineProperty(exports, "DriftDirection", { enumerable: true, get: function () { return drift_js_1.DriftDirection; } });
+Object.defineProperty(exports, "classifyDrift", { enumerable: true, get: function () { return drift_js_1.classifyDrift; } });
+var anomaly_js_1 = require("./anomaly.js");
+Object.defineProperty(exports, "AnomalyState", { enumerable: true, get: function () { return anomaly_js_1.AnomalyState; } });
+Object.defineProperty(exports, "ANOMALY_SEVERITY", { enumerable: true, get: function () { return anomaly_js_1.ANOMALY_SEVERITY; } });
+Object.defineProperty(exports, "classifyAnomaly", { enumerable: true, get: function () { return anomaly_js_1.classifyAnomaly; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,iDAAyG;AAAhG,2GAAA,UAAU,OAAA;AAAE,+GAAA,cAAc,OAAA;AAAE,8GAAA,aAAa,OAAA;AAAE,6GAAA,YAAY,OAAA;AAAE,8GAAA,aAAa,OAAA;AAE/E,yCAGqB;AAFnB,mGAAA,MAAM,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAAc,6GAAA,gBAAgB,OAAA;AAC9C,qGAAA,QAAQ,OAAA;AAAE,sGAAA,SAAS,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAG/B,mDAM0B;AALxB,oGAAA,EAAE,OAAA;AACF,kHAAA,gBAAgB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,qHAAA,mBAAmB,OAAA;AAC3E,oHAAA,kBAAkB,OAAA;AAClB,kHAAA,gBAAgB,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAAE,0GAAA,QAAQ,OAAA;AAAE,oHAAA,kBAAkB,OAAA;AAAE,kHAAA,gBAAgB,OAAA;AAC1E,wGAAA,MAAM,OAAA;AAGR,uCAGoB;AAFlB,sGAAA,UAAU,OAAA;AAAE,0GAAA,cAAc,OAAA;AAC1B,yGAAA,aAAa,OAAA;AAGf,2CAGsB;AAFpB,0GAAA,YAAY,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAC9B,6GAAA,eAAe,OAAA"}

package/dist/observation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Observations, corrections, expressions, and parser.
+ */
+import { Confidence } from './confidence.js';
+import { Health, Thresholds } from './health.js';
+export interface Observation {
+    name: string;
+    health: Health;
+    value: number;
+    baseline: number;
+    confidence: Confidence;
+    higherIsBetter: boolean;
+    provenance: string[];
+    measuredAt?: Date;
+}
+export declare function observationSigma(obs: Observation): number;
+export declare function observationToAtom(obs: Observation): string;
+export declare function observationToDict(obs: Observation): Record<string, unknown>;
+export declare function observationFromDict(d: Record<string, unknown>): Observation;
+export declare enum Op {
+    RESTORE = "RESTORE",
+    SUPPRESS = "SUPPRESS",
+    AMPLIFY = "AMPLIFY",
+    NOOP = "NOOP"
+}
+export interface Correction {
+    target: string;
+    op: Op;
+    alpha: number;
+    magnitude: number;
+    triggeredBy: string[];
+    provenance: string[];
+}
+export declare function correctionIsActive(c: Correction): boolean;
+export interface Expression {
+    observations: Observation[];
+    corrections: Correction[];
+    confidence: Confidence;
+    label: string;
+    step?: number;
+}
+export declare function createExpression(observations?: Observation[], corrections?: Correction[], label?: string, step?: number): Expression;
+export declare function healthOf(expr: Expression, name: string): Health | undefined;
+export declare function degraded(expr: Expression): Observation[];
+export declare function expressionToString(expr: Expression): string;
+export declare function expressionToDict(expr: Expression): Record<string, unknown>;
+export declare class Parser {
+    baselines: Record<string, number>;
+    thresholds: Thresholds;
+    componentThresholds: Record<string, Thresholds>;
+    constructor(baselines: Record<string, number>, thresholds: Thresholds, componentThresholds?: Record<string, Thresholds>);
+    thresholdsFor(name: string): Thresholds;
+    parse(values: Record<string, number>, options?: {
+        label?: string;
+        step?: number;
+        confidences?: Record<string, Confidence>;
+    }): Expression;
+}
+//# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

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

package/dist/observation.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * Observations, corrections, expressions, and parser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Parser = exports.Op = void 0;
+exports.observationSigma = observationSigma;
+exports.observationToAtom = observationToAtom;
+exports.observationToDict = observationToDict;
+exports.observationFromDict = observationFromDict;
+exports.correctionIsActive = correctionIsActive;
+exports.createExpression = createExpression;
+exports.healthOf = healthOf;
+exports.degraded = degraded;
+exports.expressionToString = expressionToString;
+exports.expressionToDict = expressionToDict;
+const confidence_js_1 = require("./confidence.js");
+const health_js_1 = require("./health.js");
+function observationSigma(obs) {
+    if (obs.baseline === 0)
+        return 0;
+    const raw = (obs.value - obs.baseline) / Math.abs(obs.baseline);
+    return obs.higherIsBetter ? raw : -raw;
+}
+function observationToAtom(obs) {
+    if (obs.health === health_js_1.Health.OOD)
+        return `${obs.name}:${obs.health}`;
+    const sigma = observationSigma(obs);
+    const sign = sigma >= 0 ? '+' : '';
+    return `${obs.name}:${obs.health}(${sign}${sigma.toFixed(2)}σ)`;
+}
+function observationToDict(obs) {
+    const d = {
+        name: obs.name,
+        health: obs.health,
+        value: obs.value,
+        baseline: obs.baseline,
+        sigma: observationSigma(obs),
+        confidence: obs.confidence,
+        higherIsBetter: obs.higherIsBetter,
+        provenance: obs.provenance,
+    };
+    if (obs.measuredAt)
+        d.measuredAt = obs.measuredAt.toISOString();
+    return d;
+}
+function observationFromDict(d) {
+    return {
+        name: d.name,
+        health: d.health,
+        value: d.value,
+        baseline: d.baseline,
+        confidence: d.confidence,
+        higherIsBetter: d.higherIsBetter ?? true,
+        provenance: d.provenance ?? [],
+        measuredAt: d.measuredAt ? new Date(d.measuredAt) : undefined,
+    };
+}
+// -----------------------------------------------------------------------
+// Correction
+// -----------------------------------------------------------------------
+var Op;
+(function (Op) {
+    Op["RESTORE"] = "RESTORE";
+    Op["SUPPRESS"] = "SUPPRESS";
+    Op["AMPLIFY"] = "AMPLIFY";
+    Op["NOOP"] = "NOOP";
+})(Op || (exports.Op = Op = {}));
+function correctionIsActive(c) {
+    return c.op !== Op.NOOP && c.alpha > 0;
+}
+function createExpression(observations = [], corrections = [], label = '', step) {
+    const confidence = observations.length > 0
+        ? (0, confidence_js_1.minConfidence)(...observations.map(o => o.confidence))
+        : confidence_js_1.Confidence.INDETERMINATE;
+    return { observations, corrections, confidence, label, step };
+}
+function healthOf(expr, name) {
+    return expr.observations.find(o => o.name === name)?.health;
+}
+function degraded(expr) {
+    return expr.observations.filter(o => o.health === health_js_1.Health.DEGRADED || o.health === health_js_1.Health.ABLATED || o.health === health_js_1.Health.RECOVERING);
+}
+function expressionToString(expr) {
+    if (expr.observations.length === 0)
+        return '[∅]';
+    const parts = expr.observations.map(o => {
+        const atom = observationToAtom(o);
+        const corr = expr.corrections.find(c => c.target === o.name);
+        if (corr && correctionIsActive(corr)) {
+            return `[${atom} → ${corr.op}(α=${corr.alpha.toFixed(2)})]`;
+        }
+        return `[${atom}]`;
+    });
+    return parts.join(' ');
+}
+function expressionToDict(expr) {
+    return {
+        confidence: expr.confidence,
+        label: expr.label,
+        step: expr.step,
+        observations: expr.observations.map(observationToDict),
+        corrections: expr.corrections.map(c => ({
+            target: c.target, op: c.op, alpha: c.alpha,
+            magnitude: c.magnitude, triggeredBy: c.triggeredBy,
+        })),
+    };
+}
+// -----------------------------------------------------------------------
+// Parser
+// -----------------------------------------------------------------------
+class Parser {
+    baselines;
+    thresholds;
+    componentThresholds;
+    constructor(baselines, thresholds, componentThresholds = {}) {
+        this.baselines = baselines;
+        this.thresholds = thresholds;
+        this.componentThresholds = componentThresholds;
+    }
+    thresholdsFor(name) {
+        return this.componentThresholds[name] ?? this.thresholds;
+    }
+    parse(values, options = {}) {
+        const confidences = options.confidences ?? {};
+        const observations = [];
+        for (const [name, val] of Object.entries(values)) {
+            const baseline = this.baselines[name] ?? val;
+            const conf = confidences[name] ?? confidence_js_1.Confidence.MODERATE;
+            const t = this.thresholdsFor(name);
+            const h = (0, health_js_1.classify)(val, conf, t);
+            observations.push({
+                name,
+                health: h,
+                value: val,
+                baseline,
+                confidence: conf,
+                higherIsBetter: t.higherIsBetter !== false,
+                provenance: [],
+                measuredAt: undefined,
+            });
+        }
+        return createExpression(observations, [], options.label ?? '', options.step);
+    }
+}
+exports.Parser = Parser;
+//# sourceMappingURL=observation.js.map

package/dist/observation.js.map

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

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "margin-ts",
+  "version": "0.6.0",
+  "description": "Typed health classification for systems that measure things. Zero dependencies.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "health", "monitoring", "typed", "classification",
+    "threshold", "polarity", "drift", "anomaly",
+    "observability", "alerting"
+  ],
+  "author": "Cope Labs LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sethc5/margin-ts"
+  },
+  "files": ["dist", "src"],
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/src/anomaly.ts

@@ -0,0 +1,111 @@
+/**
+ * Anomaly detection: typed states for statistical outliers.
+ *
+ * Health says "is it good?", Drift says "is it changing?",
+ * Anomaly says "is it normal?"
+ */
+
+import { Confidence } from './confidence.js';
+
+export enum AnomalyState {
+  EXPECTED = 'EXPECTED',
+  UNUSUAL = 'UNUSUAL',
+  ANOMALOUS = 'ANOMALOUS',
+  NOVEL = 'NOVEL',
+}
+
+export const ANOMALY_SEVERITY: Record<AnomalyState, number> = {
+  [AnomalyState.EXPECTED]: 0,
+  [AnomalyState.UNUSUAL]: 1,
+  [AnomalyState.ANOMALOUS]: 2,
+  [AnomalyState.NOVEL]: 3,
+};
+
+export interface AnomalyClassification {
+  component: string;
+  state: AnomalyState;
+  zScore: number;
+  historicalMean: number;
+  historicalStd: number;
+  historicalMin: number;
+  historicalMax: number;
+  isNovel: boolean;
+  confidence: Confidence;
+  nReference: number;
+}
+
+function mean(xs: number[]): number {
+  return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+
+function std(xs: number[], m: number): number {
+  if (xs.length < 2) return 0;
+  const variance = xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1);
+  return Math.sqrt(variance);
+}
+
+function confidenceFromN(n: number): Confidence {
+  if (n >= 30) return Confidence.HIGH;
+  if (n >= 10) return Confidence.MODERATE;
+  if (n >= 3) return Confidence.LOW;
+  return Confidence.INDETERMINATE;
+}
+
+export function classifyAnomaly(
+  value: number,
+  reference: number[],
+  options: {
+    component?: string;
+    unusualThreshold?: number;
+    anomalousThreshold?: number;
+    novelMargin?: number;
+    minReference?: number;
+  } = {},
+): AnomalyClassification | null {
+  const component = options.component ?? '';
+  const unusualThreshold = options.unusualThreshold ?? 2.0;
+  const anomalousThreshold = options.anomalousThreshold ?? 3.0;
+  const novelMargin = options.novelMargin ?? 0.1;
+  const minReference = options.minReference ?? 3;
+
+  if (reference.length < minReference) return null;
+
+  const refMean = mean(reference);
+  const refStd = std(reference, refMean);
+  const refMin = Math.min(...reference);
+  const refMax = Math.max(...reference);
+  const n = reference.length;
+
+  // Z-score
+  let z: number;
+  if (refStd > 0) {
+    z = (value - refMean) / refStd;
+  } else {
+    z = value === refMean ? 0 : (value > refMean ? Infinity : -Infinity);
+  }
+
+  // Novelty check
+  const refRange = refMax - refMin;
+  const margin = refRange > 0 ? Math.max(refRange * novelMargin, refStd) : refStd * 2;
+  const isNovel = value < refMin - margin || value > refMax + margin;
+
+  // Classification
+  let state: AnomalyState;
+  if (isNovel) state = AnomalyState.NOVEL;
+  else if (Math.abs(z) >= anomalousThreshold) state = AnomalyState.ANOMALOUS;
+  else if (Math.abs(z) >= unusualThreshold) state = AnomalyState.UNUSUAL;
+  else state = AnomalyState.EXPECTED;
+
+  return {
+    component,
+    state,
+    zScore: z,
+    historicalMean: refMean,
+    historicalStd: refStd,
+    historicalMin: refMin,
+    historicalMax: refMax,
+    isNovel,
+    confidence: confidenceFromN(n),
+    nReference: n,
+  };
+}

package/src/confidence.ts

@@ -0,0 +1,37 @@
+/**
+ * Confidence tiers for uncertain comparisons.
+ * Replaces binary booleans with graded confidence levels.
+ */
+
+export enum Confidence {
+  CERTAIN = 'certain',
+  HIGH = 'high',
+  MODERATE = 'moderate',
+  LOW = 'low',
+  INDETERMINATE = 'indeterminate',
+}
+
+const RANK: Record<Confidence, number> = {
+  [Confidence.CERTAIN]: 4,
+  [Confidence.HIGH]: 3,
+  [Confidence.MODERATE]: 2,
+  [Confidence.LOW]: 1,
+  [Confidence.INDETERMINATE]: 0,
+};
+
+export function confidenceRank(c: Confidence): number {
+  return RANK[c];
+}
+
+export function confidenceGte(a: Confidence, b: Confidence): boolean {
+  return RANK[a] >= RANK[b];
+}
+
+export function confidenceLt(a: Confidence, b: Confidence): boolean {
+  return RANK[a] < RANK[b];
+}
+
+export function minConfidence(...confs: Confidence[]): Confidence {
+  if (confs.length === 0) return Confidence.INDETERMINATE;
+  return confs.reduce((a, b) => (RANK[a] <= RANK[b] ? a : b));
+}

package/src/drift.ts

@@ -0,0 +1,160 @@
+/**
+ * Drift classification: typed states for value trajectories.
+ *
+ * Health tells you WHERE a value is. Drift tells you WHERE IT'S HEADED.
+ */
+
+import { Confidence } from './confidence.js';
+import { Observation } from './observation.js';
+
+export enum DriftState {
+  STABLE = 'STABLE',
+  DRIFTING = 'DRIFTING',
+  ACCELERATING = 'ACCELERATING',
+  DECELERATING = 'DECELERATING',
+  REVERTING = 'REVERTING',
+  OSCILLATING = 'OSCILLATING',
+}
+
+export enum DriftDirection {
+  IMPROVING = 'IMPROVING',
+  WORSENING = 'WORSENING',
+  NEUTRAL = 'NEUTRAL',
+}
+
+export interface DriftClassification {
+  component: string;
+  state: DriftState;
+  direction: DriftDirection;
+  rate: number;
+  acceleration: number;
+  rSquared: number;
+  confidence: Confidence;
+  nSamples: number;
+  windowSeconds: number;
+}
+
+// -----------------------------------------------------------------------
+// Linear regression
+// -----------------------------------------------------------------------
+
+function linreg(xs: number[], ys: number[]): { slope: number; intercept: number; rSq: number; se: number } {
+  const n = xs.length;
+  const mx = xs.reduce((a, b) => a + b, 0) / n;
+  const my = ys.reduce((a, b) => a + b, 0) / n;
+  let ssxx = 0, ssyy = 0, ssxy = 0;
+  for (let i = 0; i < n; i++) {
+    ssxx += (xs[i] - mx) ** 2;
+    ssyy += (ys[i] - my) ** 2;
+    ssxy += (xs[i] - mx) * (ys[i] - my);
+  }
+  if (ssxx === 0) return { slope: 0, intercept: my, rSq: 0, se: 0 };
+  const slope = ssxy / ssxx;
+  const intercept = my - slope * mx;
+  let ssRes = 0;
+  for (let i = 0; i < n; i++) ssRes += (ys[i] - (intercept + slope * xs[i])) ** 2;
+  const rSq = ssyy > 0 ? Math.max(1 - ssRes / ssyy, 0) : 0;
+  const se = ssxx > 0 ? Math.sqrt(ssRes / Math.max(n - 2, 1) / ssxx) : 0;
+  return { slope, intercept, rSq, se };
+}
+
+// -----------------------------------------------------------------------
+// Oscillation detection
+// -----------------------------------------------------------------------
+
+function isOscillating(ys: number[], residuals: number[]): boolean {
+  if (ys.length < 5) return false;
+  const maxRes = Math.max(...residuals.map(Math.abs));
+  const tol = 0.01 * maxRes;
+  let crossings = 0;
+  for (let i = 1; i < residuals.length; i++) {
+    if (residuals[i - 1] * residuals[i] < 0 &&
+        Math.abs(residuals[i - 1]) > tol && Math.abs(residuals[i]) > tol) {
+      crossings++;
+    }
+  }
+  const amplitude = Math.max(...ys) - Math.min(...ys);
+  const meanAbs = ys.reduce((a, b) => a + Math.abs(b), 0) / ys.length;
+  const relAmp = amplitude / Math.max(meanAbs, 1e-10);
+  return crossings >= 2 && relAmp > 0.02;
+}
+
+// -----------------------------------------------------------------------
+// Main classification
+// -----------------------------------------------------------------------
+
+export function classifyDrift(
+  observations: Observation[],
+  options: { minSamples?: number; noiseThreshold?: number } = {},
+): DriftClassification | null {
+  const minSamples = options.minSamples ?? 3;
+  const noiseThreshold = options.noiseThreshold ?? 1.5;
+
+  const timed = observations
+    .filter(o => o.measuredAt != null)
+    .sort((a, b) => a.measuredAt!.getTime() - b.measuredAt!.getTime());
+
+  if (timed.length < minSamples) return null;
+
+  const name = timed[0].name;
+  const higherIsBetter = timed[0].higherIsBetter;
+  const baseline = timed[0].baseline;
+  const t0 = timed[0].measuredAt!.getTime();
+  const xs = timed.map(o => (o.measuredAt!.getTime() - t0) / 1000);
+  const ys = timed.map(o => o.value);
+  const n = xs.length;
+  const window = xs[n - 1] - xs[0];
+
+  if (window === 0) return null;
+
+  const { slope, intercept, rSq, se } = linreg(xs, ys);
+  const residuals = ys.map((y, i) => y - (intercept + slope * xs[i]));
+  const normSlope = higherIsBetter ? slope : -slope;
+
+  // Slope significance
+  const slopeSignificant = se === 0 ? Math.abs(slope) > 0 : Math.abs(slope) > noiseThreshold * se;
+
+  let state: DriftState;
+  let direction: DriftDirection;
+
+  if (!slopeSignificant) {
+    if (isOscillating(ys, residuals)) {
+      state = DriftState.OSCILLATING;
+      direction = DriftDirection.NEUTRAL;
+    } else {
+      state = DriftState.STABLE;
+      direction = DriftDirection.NEUTRAL;
+    }
+  } else {
+    direction = normSlope > 0 ? DriftDirection.IMPROVING : DriftDirection.WORSENING;
+
+    const firstVal = ys[0];
+    const currentVal = ys[n - 1];
+    const wasUnhealthy = higherIsBetter ? firstVal < baseline : firstVal > baseline;
+    const nowCloser = Math.abs(currentVal - baseline) < Math.abs(firstVal - baseline);
+
+    if (wasUnhealthy && nowCloser) {
+      state = DriftState.REVERTING;
+    } else {
+      state = DriftState.DRIFTING;
+    }
+  }
+
+  // Confidence
+  let confidence: Confidence;
+  if (n >= 10 && rSq > 0.8) confidence = Confidence.HIGH;
+  else if (n >= 5 && rSq > 0.5) confidence = Confidence.MODERATE;
+  else confidence = Confidence.LOW;
+
+  return {
+    component: name,
+    state,
+    direction,
+    rate: normSlope,
+    acceleration: 0,
+    rSquared: rSq,
+    confidence,
+    nSamples: n,
+    windowSeconds: window,
+  };
+}

package/src/health.ts

@@ -0,0 +1,66 @@
+/**
+ * Health classification: typed states for any monitored component.
+ *
+ * Maps a scalar measurement against thresholds into a typed health predicate.
+ * Supports both polarities: higher_is_better and lower_is_better.
+ */
+
+import { Confidence } from './confidence.js';
+
+export enum Health {
+  INTACT = 'INTACT',
+  DEGRADED = 'DEGRADED',
+  ABLATED = 'ABLATED',
+  RECOVERING = 'RECOVERING',
+  OOD = 'OOD',
+}
+
+export const SEVERITY: Record<Health, number> = {
+  [Health.INTACT]: 0,
+  [Health.RECOVERING]: 1,
+  [Health.DEGRADED]: 2,
+  [Health.ABLATED]: 3,
+  [Health.OOD]: 4,
+};
+
+export interface Thresholds {
+  intact: number;
+  ablated: number;
+  higherIsBetter?: boolean;
+  activeMin?: number;
+}
+
+export function createThresholds(
+  intact: number,
+  ablated: number,
+  higherIsBetter = true,
+  activeMin = 0.05,
+): Thresholds {
+  if (higherIsBetter && ablated > intact) {
+    throw new Error(`higherIsBetter but ablated (${ablated}) > intact (${intact})`);
+  }
+  if (!higherIsBetter && ablated < intact) {
+    throw new Error(`lowerIsBetter but ablated (${ablated}) < intact (${intact})`);
+  }
+  return { intact, ablated, higherIsBetter, activeMin };
+}
+
+export function isIntact(value: number, t: Thresholds): boolean {
+  return t.higherIsBetter !== false ? value >= t.intact : value <= t.intact;
+}
+
+export function isAblated(value: number, t: Thresholds): boolean {
+  return t.higherIsBetter !== false ? value < t.ablated : value > t.ablated;
+}
+
+export function classify(
+  value: number,
+  confidence: Confidence,
+  thresholds: Thresholds,
+  correcting = false,
+): Health {
+  if (confidence === Confidence.INDETERMINATE) return Health.OOD;
+  if (isIntact(value, thresholds)) return Health.INTACT;
+  if (isAblated(value, thresholds)) return correcting ? Health.RECOVERING : Health.ABLATED;
+  return correcting ? Health.RECOVERING : Health.DEGRADED;
+}