margin-ts 0.6.0

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+
+export { Confidence, confidenceRank, confidenceGte, confidenceLt, minConfidence } from './confidence.js';
+
+export {
+  Health, SEVERITY, Thresholds, createThresholds,
+  isIntact, isAblated, classify,
+} from './health.js';
+
+export {
+  Op, Observation, Correction, Expression,
+  observationSigma, observationToAtom, observationToDict, observationFromDict,
+  correctionIsActive,
+  createExpression, healthOf, degraded, expressionToString, expressionToDict,
+  Parser,
+} from './observation.js';
+
+export {
+  DriftState, DriftDirection, DriftClassification,
+  classifyDrift,
+} from './drift.js';
+
+export {
+  AnomalyState, ANOMALY_SEVERITY, AnomalyClassification,
+  classifyAnomaly,
+} from './anomaly.js';

package/src/observation.ts

@@ -0,0 +1,201 @@
+/**
+ * Observations, corrections, expressions, and parser.
+ */
+
+import { Confidence, minConfidence } from './confidence.js';
+import { Health, Thresholds, classify, createThresholds, isIntact, SEVERITY } from './health.js';
+
+// -----------------------------------------------------------------------
+// Observation
+// -----------------------------------------------------------------------
+
+export interface Observation {
+  name: string;
+  health: Health;
+  value: number;
+  baseline: number;
+  confidence: Confidence;
+  higherIsBetter: boolean;
+  provenance: string[];
+  measuredAt?: Date;
+}
+
+export function observationSigma(obs: Observation): number {
+  if (obs.baseline === 0) return 0;
+  const raw = (obs.value - obs.baseline) / Math.abs(obs.baseline);
+  return obs.higherIsBetter ? raw : -raw;
+}
+
+export function observationToAtom(obs: Observation): string {
+  if (obs.health === Health.OOD) return `${obs.name}:${obs.health}`;
+  const sigma = observationSigma(obs);
+  const sign = sigma >= 0 ? '+' : '';
+  return `${obs.name}:${obs.health}(${sign}${sigma.toFixed(2)}σ)`;
+}
+
+export function observationToDict(obs: Observation): Record<string, unknown> {
+  const d: Record<string, unknown> = {
+    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;
+}
+
+export function observationFromDict(d: Record<string, unknown>): Observation {
+  return {
+    name: d.name as string,
+    health: d.health as Health,
+    value: d.value as number,
+    baseline: d.baseline as number,
+    confidence: d.confidence as Confidence,
+    higherIsBetter: (d.higherIsBetter as boolean) ?? true,
+    provenance: (d.provenance as string[]) ?? [],
+    measuredAt: d.measuredAt ? new Date(d.measuredAt as string) : undefined,
+  };
+}
+
+// -----------------------------------------------------------------------
+// Correction
+// -----------------------------------------------------------------------
+
+export 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 function correctionIsActive(c: Correction): boolean {
+  return c.op !== Op.NOOP && c.alpha > 0;
+}
+
+// -----------------------------------------------------------------------
+// Expression
+// -----------------------------------------------------------------------
+
+export interface Expression {
+  observations: Observation[];
+  corrections: Correction[];
+  confidence: Confidence;
+  label: string;
+  step?: number;
+}
+
+export function createExpression(
+  observations: Observation[] = [],
+  corrections: Correction[] = [],
+  label = '',
+  step?: number,
+): Expression {
+  const confidence = observations.length > 0
+    ? minConfidence(...observations.map(o => o.confidence))
+    : Confidence.INDETERMINATE;
+  return { observations, corrections, confidence, label, step };
+}
+
+export function healthOf(expr: Expression, name: string): Health | undefined {
+  return expr.observations.find(o => o.name === name)?.health;
+}
+
+export function degraded(expr: Expression): Observation[] {
+  return expr.observations.filter(
+    o => o.health === Health.DEGRADED || o.health === Health.ABLATED || o.health === Health.RECOVERING,
+  );
+}
+
+export function expressionToString(expr: Expression): string {
+  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(' ');
+}
+
+export function expressionToDict(expr: Expression): Record<string, unknown> {
+  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
+// -----------------------------------------------------------------------
+
+export class Parser {
+  baselines: Record<string, number>;
+  thresholds: Thresholds;
+  componentThresholds: Record<string, Thresholds>;
+
+  constructor(
+    baselines: Record<string, number>,
+    thresholds: Thresholds,
+    componentThresholds: Record<string, Thresholds> = {},
+  ) {
+    this.baselines = baselines;
+    this.thresholds = thresholds;
+    this.componentThresholds = componentThresholds;
+  }
+
+  thresholdsFor(name: string): Thresholds {
+    return this.componentThresholds[name] ?? this.thresholds;
+  }
+
+  parse(
+    values: Record<string, number>,
+    options: {
+      label?: string;
+      step?: number;
+      confidences?: Record<string, Confidence>;
+    } = {},
+  ): Expression {
+    const confidences = options.confidences ?? {};
+    const observations: Observation[] = [];
+
+    for (const [name, val] of Object.entries(values)) {
+      const baseline = this.baselines[name] ?? val;
+      const conf = confidences[name] ?? Confidence.MODERATE;
+      const t = this.thresholdsFor(name);
+      const h = 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);
+  }
+}