margin-ts 0.6.1 → 0.7.0

package/src/adapters/stream.ts

@@ -0,0 +1,241 @@
+/**
+ * Streaming health updates via Server-Sent Events (SSE).
+ *
+ * Push health/drift/anomaly updates to browser dashboards in real-time.
+ *
+ * Express:
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Next.js Pages Router:
+ *   export default marginSSEHandler(monitor);
+ *
+ * Browser client:
+ *   const source = new EventSource('/margin/stream');
+ *   source.onmessage = (e) => {
+ *     const health = JSON.parse(e.data);
+ *     updateDashboard(health);
+ *   };
+ *
+ * Zero dependencies. Works with any framework that supports
+ * writable response streams (Express, Fastify, Next.js, raw Node http).
+ */
+
+import {
+  Confidence,
+  Health,
+  Absence,
+  Observation,
+  Expression,
+  Parser,
+  isAbsent,
+  createExpression,
+  expressionToString,
+  expressionToDict,
+  classifyDrift,
+  DriftClassification,
+  DriftState,
+  DriftDirection,
+  classifyAnomaly,
+  AnomalyClassification,
+  AnomalyState,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// StreamingMonitor — the TS equivalent of Python's Monitor
+// -----------------------------------------------------------------------
+
+interface ComponentWindow {
+  values: number[];
+  observations: Observation[];
+  maxWindow: number;
+}
+
+export class StreamingMonitor {
+  private parser: Parser;
+  private windows: Map<string, ComponentWindow> = new Map();
+  private _expression: Expression | null = null;
+  private _step = 0;
+  private maxWindow: number;
+  private minAnomalyRef: number;
+
+  constructor(parser: Parser, options: { window?: number; minAnomalyRef?: number } = {}) {
+    this.parser = parser;
+    this.maxWindow = options.window ?? 100;
+    this.minAnomalyRef = options.minAnomalyRef ?? 10;
+  }
+
+  get expression(): Expression | null { return this._expression; }
+  get step(): number { return this._step; }
+
+  update(
+    values: Record<string, number>,
+    nowOrOptions?: Date | { now?: Date; absences?: Record<string, Absence> },
+  ): Expression {
+    let now: Date;
+    let absences: Record<string, Absence> | undefined;
+    if (nowOrOptions instanceof Date) {
+      now = nowOrOptions;
+    } else {
+      now = nowOrOptions?.now ?? new Date();
+      absences = nowOrOptions?.absences;
+    }
+    this._expression = this.parser.parse(values, { step: this._step, absences });
+    this._step++;
+
+    // Update per-component windows (skip absent observations —
+    // they carry no measured value and would corrupt drift/anomaly windows)
+    for (const obs of this._expression.observations) {
+      if (isAbsent(obs)) continue;
+
+      if (!this.windows.has(obs.name)) {
+        this.windows.set(obs.name, { values: [], observations: [], maxWindow: this.maxWindow });
+      }
+      const w = this.windows.get(obs.name)!;
+      w.values.push(obs.value);
+      const stamped = { ...obs, measuredAt: now };
+      w.observations.push(stamped);
+      if (w.values.length > this.maxWindow) {
+        w.values.shift();
+        w.observations.shift();
+      }
+    }
+
+    return this._expression;
+  }
+
+  drift(component: string): DriftClassification | null {
+    const w = this.windows.get(component);
+    if (!w || w.observations.length < 3) return null;
+    return classifyDrift(w.observations);
+  }
+
+  anomaly(component: string): AnomalyClassification | null {
+    const w = this.windows.get(component);
+    if (!w || w.values.length < this.minAnomalyRef + 1) return null;
+    const ref = w.values.slice(0, -1);
+    const current = w.values[w.values.length - 1];
+    return classifyAnomaly(current, ref, { component });
+  }
+
+  status(): Record<string, unknown> {
+    const drift: Record<string, unknown> = {};
+    const anomaly: Record<string, unknown> = {};
+
+    for (const [name] of this.windows) {
+      const dc = this.drift(name);
+      if (dc) drift[name] = { state: dc.state, direction: dc.direction, rate: dc.rate };
+      const ac = this.anomaly(name);
+      if (ac) anomaly[name] = { state: ac.state, zScore: ac.zScore };
+    }
+
+    return {
+      step: this._step,
+      expression: this._expression ? expressionToString(this._expression) : null,
+      health: this._expression ? expressionToDict(this._expression) : null,
+      drift,
+      anomaly,
+    };
+  }
+
+  reset(): void {
+    this.windows.clear();
+    this._expression = null;
+    this._step = 0;
+  }
+}
+
+// -----------------------------------------------------------------------
+// SSE helpers
+// -----------------------------------------------------------------------
+
+/** Connected SSE client. */
+interface SSEClient {
+  id: string;
+  res: any;
+}
+
+let _clients: SSEClient[] = [];
+let _clientIdCounter = 0;
+
+/**
+ * Broadcast a status update to all connected SSE clients.
+ * Call this after each monitor.update().
+ */
+export function broadcast(monitor: StreamingMonitor): void {
+  const data = JSON.stringify(monitor.status());
+  const message = `data: ${data}\n\n`;
+  _clients = _clients.filter(client => {
+    try {
+      client.res.write(message);
+      return true;
+    } catch {
+      return false; // client disconnected
+    }
+  });
+}
+
+/**
+ * Express/Fastify route handler for SSE streaming.
+ *
+ *   app.get('/margin/stream', marginSSE(monitor));
+ *
+ * Each connected browser receives real-time health updates.
+ * Call broadcast(monitor) after each monitor.update() to push.
+ */
+export function marginSSE(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return (req: any, res: any) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+
+    // Send current state immediately
+    const initial = JSON.stringify(monitor.status());
+    res.write(`data: ${initial}\n\n`);
+
+    const client: SSEClient = { id: String(++_clientIdCounter), res };
+    _clients.push(client);
+
+    req.on('close', () => {
+      _clients = _clients.filter(c => c.id !== client.id);
+    });
+  };
+}
+
+/**
+ * Next.js Pages Router SSE handler.
+ *
+ *   // pages/api/margin/stream.ts
+ *   export default marginSSEHandler(monitor);
+ */
+export function marginSSEHandler(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return marginSSE(monitor);
+}
+
+/**
+ * Create a polling endpoint (for environments that don't support SSE).
+ * Returns the current status as JSON on each request.
+ *
+ *   app.get('/margin/poll', marginPoll(monitor));
+ */
+export function marginPoll(monitor: StreamingMonitor): (req: any, res: any) => void {
+  return (_req: any, res: any) => {
+    res.json(monitor.status());
+  };
+}
+
+/** Number of connected SSE clients. */
+export function connectedClients(): number {
+  return _clients.length;
+}
+
+/** Disconnect all SSE clients (for testing). */
+export function resetClients(): void {
+  for (const client of _clients) {
+    try { client.res.end(); } catch {}
+  }
+  _clients = [];
+  _clientIdCounter = 0;
+}

package/src/index.ts

@@ -15,10 +15,12 @@ export {
 } from './health.js';
 
 export {
+  Absence,
   Op, Observation, Correction, Expression,
+  isAbsent,
   observationSigma, observationToAtom, observationToDict, observationFromDict,
   correctionIsActive,
-  createExpression, healthOf, degraded, expressionToString, expressionToDict,
+  createExpression, healthOf, degraded, absent, intact, expressionToString, expressionToDict,
   Parser,
 } from './observation.js';
 
@@ -44,3 +46,17 @@ export {
   DEFAULT_SUITE_THRESHOLDS,
   type SuiteResults, type SuiteThresholds,
 } from './adapters/vitest.js';
+
+export {
+  withMargin, withMarginApp,
+  marginHealthHandler, marginHealthAppHandler,
+  resetRoutes,
+  DEFAULT_NEXTJS_THRESHOLDS,
+  type WithMarginOptions, type NextjsThresholds,
+} from './adapters/nextjs.js';
+
+export {
+  StreamingMonitor,
+  broadcast, marginSSE, marginSSEHandler, marginPoll,
+  connectedClients, resetClients,
+} from './adapters/stream.js';

package/src/observation.ts

@@ -5,6 +5,20 @@
 import { Confidence, minConfidence } from './confidence.js';
 import { Health, Thresholds, classify, createThresholds, isIntact, SEVERITY } from './health.js';
 
+// -----------------------------------------------------------------------
+// Absence — why a value is missing
+// -----------------------------------------------------------------------
+
+export enum Absence {
+  NOT_MEASURED = 'not_measured',
+  BELOW_DETECTION = 'below_detection',
+  ABOVE_RANGE = 'above_range',
+  SENSOR_FAILED = 'sensor_failed',
+  REDACTED = 'redacted',
+  NOT_APPLICABLE = 'not_applicable',
+  PENDING = 'pending',
+}
+
 // -----------------------------------------------------------------------
 // Observation
 // -----------------------------------------------------------------------
@@ -18,6 +32,12 @@ export interface Observation {
   higherIsBetter: boolean;
   provenance: string[];
   measuredAt?: Date;
+  absence?: Absence;
+  absenceDetail?: string;
+}
+
+export function isAbsent(obs: Observation): boolean {
+  return obs.absence !== undefined;
 }
 
 export function observationSigma(obs: Observation): number {
@@ -27,6 +47,7 @@ export function observationSigma(obs: Observation): number {
 }
 
 export function observationToAtom(obs: Observation): string {
+  if (obs.absence !== undefined) return `${obs.name}:ABSENT(${obs.absence})`;
   if (obs.health === Health.OOD) return `${obs.name}:${obs.health}`;
   const sigma = observationSigma(obs);
   const sign = sigma >= 0 ? '+' : '';
@@ -45,11 +66,13 @@ export function observationToDict(obs: Observation): Record<string, unknown> {
     provenance: obs.provenance,
   };
   if (obs.measuredAt) d.measuredAt = obs.measuredAt.toISOString();
+  if (obs.absence !== undefined) d.absence = obs.absence;
+  if (obs.absenceDetail !== undefined) d.absenceDetail = obs.absenceDetail;
   return d;
 }
 
 export function observationFromDict(d: Record<string, unknown>): Observation {
-  return {
+  const obs: Observation = {
     name: d.name as string,
     health: d.health as Health,
     value: d.value as number,
@@ -59,6 +82,9 @@ export function observationFromDict(d: Record<string, unknown>): Observation {
     provenance: (d.provenance as string[]) ?? [],
     measuredAt: d.measuredAt ? new Date(d.measuredAt as string) : undefined,
   };
+  if (d.absence !== undefined) obs.absence = d.absence as Absence;
+  if (d.absenceDetail !== undefined) obs.absenceDetail = d.absenceDetail as string;
+  return obs;
 }
 
 // -----------------------------------------------------------------------
@@ -119,6 +145,14 @@ export function degraded(expr: Expression): Observation[] {
   );
 }
 
+export function absent(expr: Expression): Observation[] {
+  return expr.observations.filter(o => isAbsent(o));
+}
+
+export function intact(expr: Expression): Observation[] {
+  return expr.observations.filter(o => o.health === Health.INTACT);
+}
+
 export function expressionToString(expr: Expression): string {
   if (expr.observations.length === 0) return '[∅]';
   const parts = expr.observations.map(o => {
@@ -174,12 +208,15 @@ export class Parser {
       label?: string;
       step?: number;
       confidences?: Record<string, Confidence>;
+      absences?: Record<string, Absence>;
     } = {},
   ): Expression {
     const confidences = options.confidences ?? {};
+    const absences = options.absences ?? {};
     const observations: Observation[] = [];
 
     for (const [name, val] of Object.entries(values)) {
+      if (name in absences) continue; // handled below
       const baseline = this.baselines[name] ?? val;
       const conf = confidences[name] ?? Confidence.MODERATE;
       const t = this.thresholdsFor(name);
@@ -196,6 +233,24 @@ export class Parser {
       });
     }
 
+    // Emit absent observations
+    for (const [name, reason] of Object.entries(absences)) {
+      const baseline = this.baselines[name] ?? 0;
+      const t = this.thresholdsFor(name);
+      const conf = confidences[name] ?? Confidence.INDETERMINATE;
+      observations.push({
+        name,
+        health: Health.OOD,
+        value: baseline,
+        baseline,
+        confidence: conf,
+        higherIsBetter: t.higherIsBetter !== false,
+        provenance: [],
+        measuredAt: undefined,
+        absence: reason,
+      });
+    }
+
     return createExpression(observations, [], options.label ?? '', options.step);
   }
 }