@lssm/lib.observability 0.0.0-canary-20251217052941 → 0.0.0-canary-20251217060433

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @lssm/lib.observability
 
-## 0.0.0-canary-20251217052941
+## 0.0.0-canary-20251217060433
 
 ### Minor Changes
 
@@ -9,7 +9,7 @@
 ### Patch Changes
 
 - Updated dependencies [66a5dfd]
-  - @lssm/lib.lifecycle@0.0.0-canary-20251217052941
+  - @lssm/lib.lifecycle@0.0.0-canary-20251217060433
 
 ## 0.5.0
 

package/dist/anomaly/alert-manager.d.mts

@@ -0,0 +1,20 @@
+import { AnomalySignal } from "./anomaly-detector.mjs";
+import { RootCauseAnalysis } from "./root-cause-analyzer.mjs";
+
+//#region src/anomaly/alert-manager.d.ts
+interface AlertManagerOptions {
+  cooldownMs?: number;
+  transport: (payload: {
+    signal: AnomalySignal;
+    analysis: RootCauseAnalysis;
+  }) => Promise<void> | void;
+}
+declare class AlertManager {
+  private readonly options;
+  private readonly cooldownMs;
+  private readonly lastAlert;
+  constructor(options: AlertManagerOptions);
+  notify(signal: AnomalySignal, analysis: RootCauseAnalysis): Promise<void>;
+}
+//#endregion
+export { AlertManager, AlertManagerOptions };

package/dist/anomaly/anomaly-detector.d.mts

@@ -0,0 +1,25 @@
+import { BaselineCalculator, MetricPoint } from "./baseline-calculator.mjs";
+
+//#region src/anomaly/anomaly-detector.d.ts
+interface AnomalyThresholds {
+  errorRateDelta?: number;
+  latencyDelta?: number;
+  throughputDrop?: number;
+  minSamples?: number;
+}
+interface AnomalySignal {
+  type: 'error_rate_spike' | 'latency_regression' | 'throughput_drop';
+  delta: number;
+  point: MetricPoint;
+  baseline: ReturnType<BaselineCalculator['getSnapshot']>;
+}
+declare class AnomalyDetector {
+  private readonly baseline;
+  private readonly thresholds;
+  constructor(options?: AnomalyThresholds);
+  evaluate(point: MetricPoint): AnomalySignal[];
+  private relativeDelta;
+  private relativeDrop;
+}
+//#endregion
+export { AnomalyDetector, AnomalySignal, AnomalyThresholds };

package/dist/anomaly/baseline-calculator.d.mts

@@ -0,0 +1,25 @@
+//#region src/anomaly/baseline-calculator.d.ts
+interface MetricPoint {
+  latencyP99: number;
+  latencyP95: number;
+  errorRate: number;
+  throughput: number;
+  timestamp: Date;
+}
+interface BaselineSnapshot {
+  latencyP99: number;
+  latencyP95: number;
+  errorRate: number;
+  throughput: number;
+  sampleCount: number;
+}
+declare class BaselineCalculator {
+  private readonly alpha;
+  private snapshot;
+  constructor(alpha?: number);
+  update(point: MetricPoint): BaselineSnapshot;
+  getSnapshot(): BaselineSnapshot;
+  private mix;
+}
+//#endregion
+export { BaselineCalculator, BaselineSnapshot, MetricPoint };

package/dist/anomaly/root-cause-analyzer.d.mts

@@ -0,0 +1,22 @@
+import { AnomalySignal } from "./anomaly-detector.mjs";
+
+//#region src/anomaly/root-cause-analyzer.d.ts
+interface DeploymentEvent {
+  id: string;
+  operation: string;
+  deployedAt: Date;
+  stage?: string;
+  status: 'in_progress' | 'completed' | 'rolled_back';
+}
+interface RootCauseAnalysis {
+  signal: AnomalySignal;
+  culprit?: DeploymentEvent;
+  notes: string[];
+}
+declare class RootCauseAnalyzer {
+  private readonly lookbackMs;
+  constructor(lookbackMs?: number);
+  analyze(signal: AnomalySignal, deployments: DeploymentEvent[]): RootCauseAnalysis;
+}
+//#endregion
+export { DeploymentEvent, RootCauseAnalysis, RootCauseAnalyzer };

package/dist/index.d.mts

@@ -0,0 +1,13 @@
+import { BaselineCalculator } from "./anomaly/baseline-calculator.mjs";
+import { AnomalyDetector, AnomalySignal, AnomalyThresholds } from "./anomaly/anomaly-detector.mjs";
+import { RootCauseAnalysis, RootCauseAnalyzer } from "./anomaly/root-cause-analyzer.mjs";
+import { AlertManager } from "./anomaly/alert-manager.mjs";
+import { getTracer, traceAsync, traceSync } from "./tracing/index.mjs";
+import { createCounter, createHistogram, createUpDownCounter, getMeter, standardMetrics } from "./metrics/index.mjs";
+import { LogEntry, LogLevel, Logger, logger } from "./logging/index.mjs";
+import { IntentAggregator, IntentAggregatorSnapshot, TelemetrySample } from "./intent/aggregator.mjs";
+import { TracingMiddlewareOptions, createTracingMiddleware } from "./tracing/middleware.mjs";
+import { IntentDetector, IntentSignal, IntentSignalType } from "./intent/detector.mjs";
+import { EvolutionPipeline, EvolutionPipelineEvent, EvolutionPipelineOptions } from "./pipeline/evolution-pipeline.mjs";
+import { LifecycleKpiPipeline, LifecycleKpiPipelineOptions, LifecyclePipelineEvent } from "./pipeline/lifecycle-pipeline.mjs";
+export { AlertManager, AnomalyDetector, type AnomalySignal, type AnomalyThresholds, BaselineCalculator, EvolutionPipeline, type EvolutionPipelineEvent, type EvolutionPipelineOptions, IntentAggregator, type IntentAggregatorSnapshot, IntentDetector, type IntentSignal, type IntentSignalType, LifecycleKpiPipeline, type LifecycleKpiPipelineOptions, type LifecyclePipelineEvent, type LogEntry, type LogLevel, Logger, type RootCauseAnalysis, RootCauseAnalyzer, type TelemetrySample, type TracingMiddlewareOptions, createCounter, createHistogram, createTracingMiddleware, createUpDownCounter, getMeter, getTracer, logger, standardMetrics, traceAsync, traceSync };

package/dist/intent/aggregator.d.mts

@@ -0,0 +1,59 @@
+//#region src/intent/aggregator.d.ts
+interface TelemetrySample {
+  operation: {
+    name: string;
+    version: number;
+  };
+  durationMs: number;
+  success: boolean;
+  timestamp: Date;
+  errorCode?: string;
+  tenantId?: string;
+  traceId?: string;
+  actorId?: string;
+  metadata?: Record<string, unknown>;
+}
+interface AggregatedOperationMetrics {
+  operation: {
+    name: string;
+    version: number;
+  };
+  totalCalls: number;
+  successRate: number;
+  errorRate: number;
+  averageLatencyMs: number;
+  p95LatencyMs: number;
+  p99LatencyMs: number;
+  maxLatencyMs: number;
+  windowStart: Date;
+  windowEnd: Date;
+  topErrors: Record<string, number>;
+}
+interface OperationSequence {
+  steps: string[];
+  tenantId?: string;
+  count: number;
+}
+interface IntentAggregatorSnapshot {
+  metrics: AggregatedOperationMetrics[];
+  sequences: OperationSequence[];
+  sampleCount: number;
+  windowStart?: Date;
+  windowEnd?: Date;
+}
+interface IntentAggregatorOptions {
+  windowMs?: number;
+  sequenceSampleSize?: number;
+}
+declare class IntentAggregator {
+  private readonly windowMs;
+  private readonly sequenceSampleSize;
+  private readonly samples;
+  constructor(options?: IntentAggregatorOptions);
+  add(sample: TelemetrySample): void;
+  flush(now?: Date): IntentAggregatorSnapshot;
+  private aggregateMetrics;
+  private buildSequences;
+}
+//#endregion
+export { AggregatedOperationMetrics, IntentAggregator, IntentAggregatorOptions, IntentAggregatorSnapshot, OperationSequence, TelemetrySample };

package/dist/intent/detector.d.mts

@@ -0,0 +1,31 @@
+import { AggregatedOperationMetrics, OperationSequence } from "./aggregator.mjs";
+
+//#region src/intent/detector.d.ts
+type IntentSignalType = 'latency-regression' | 'error-spike' | 'throughput-drop' | 'missing-workflow-step';
+interface IntentSignal {
+  id: string;
+  type: IntentSignalType;
+  operation?: AggregatedOperationMetrics['operation'];
+  confidence: number;
+  description: string;
+  metadata?: Record<string, unknown>;
+  evidence: {
+    type: 'metric' | 'sequence' | 'anomaly';
+    description: string;
+    data?: Record<string, unknown>;
+  }[];
+}
+interface IntentDetectorOptions {
+  errorRateThreshold?: number;
+  latencyP99ThresholdMs?: number;
+  throughputDropThreshold?: number;
+  minSequenceLength?: number;
+}
+declare class IntentDetector {
+  private readonly options;
+  constructor(options?: IntentDetectorOptions);
+  detectFromMetrics(current: AggregatedOperationMetrics[], previous?: AggregatedOperationMetrics[]): IntentSignal[];
+  detectSequentialIntents(sequences: OperationSequence[]): IntentSignal[];
+}
+//#endregion
+export { IntentDetector, IntentDetectorOptions, IntentSignal, IntentSignalType };

package/dist/logging/index.d.mts

@@ -0,0 +1,19 @@
+//#region src/logging/index.d.ts
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  [key: string]: unknown;
+}
+declare class Logger {
+  private readonly serviceName;
+  constructor(serviceName: string);
+  private log;
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+declare const logger: Logger;
+//#endregion
+export { LogEntry, LogLevel, Logger, logger };

package/dist/metrics/index.d.mts

@@ -0,0 +1,16 @@
+import * as _opentelemetry_api0 from "@opentelemetry/api";
+import { Counter, Histogram, Meter, UpDownCounter } from "@opentelemetry/api";
+
+//#region src/metrics/index.d.ts
+declare function getMeter(name?: string): Meter;
+declare function createCounter(name: string, description?: string, meterName?: string): Counter;
+declare function createUpDownCounter(name: string, description?: string, meterName?: string): UpDownCounter;
+declare function createHistogram(name: string, description?: string, meterName?: string): Histogram;
+declare const standardMetrics: {
+  httpRequests: Counter<_opentelemetry_api0.Attributes>;
+  httpDuration: Histogram<_opentelemetry_api0.Attributes>;
+  operationErrors: Counter<_opentelemetry_api0.Attributes>;
+  workflowDuration: Histogram<_opentelemetry_api0.Attributes>;
+};
+//#endregion
+export { createCounter, createHistogram, createUpDownCounter, getMeter, standardMetrics };

package/dist/pipeline/evolution-pipeline.d.mts

@@ -0,0 +1,39 @@
+import { IntentAggregator, IntentAggregatorSnapshot, TelemetrySample } from "../intent/aggregator.mjs";
+import { IntentDetector, IntentSignal } from "../intent/detector.mjs";
+import { EventEmitter } from "node:events";
+
+//#region src/pipeline/evolution-pipeline.d.ts
+type EvolutionPipelineEvent = {
+  type: 'intent.detected';
+  payload: IntentSignal;
+} | {
+  type: 'telemetry.window';
+  payload: {
+    sampleCount: number;
+  };
+};
+interface EvolutionPipelineOptions {
+  detector?: IntentDetector;
+  aggregator?: IntentAggregator;
+  emitter?: EventEmitter;
+  onIntent?: (intent: IntentSignal) => Promise<void> | void;
+  onSnapshot?: (snapshot: IntentAggregatorSnapshot) => Promise<void> | void;
+}
+declare class EvolutionPipeline {
+  private readonly detector;
+  private readonly aggregator;
+  private readonly emitter;
+  private readonly onIntent?;
+  private readonly onSnapshot?;
+  private timer?;
+  private previousMetrics?;
+  constructor(options?: EvolutionPipelineOptions);
+  ingest(sample: TelemetrySample): void;
+  on(listener: (event: EvolutionPipelineEvent) => void): void;
+  start(intervalMs?: number): void;
+  stop(): void;
+  run(): Promise<void>;
+  private emit;
+}
+//#endregion
+export { EvolutionPipeline, EvolutionPipelineEvent, EvolutionPipelineOptions };

package/dist/pipeline/lifecycle-pipeline.d.mts

@@ -0,0 +1,43 @@
+import { EventEmitter } from "node:events";
+import { LifecycleAssessment, LifecycleStage } from "@lssm/lib.lifecycle";
+
+//#region src/pipeline/lifecycle-pipeline.d.ts
+type LifecyclePipelineEvent = {
+  type: 'assessment.recorded';
+  payload: {
+    tenantId?: string;
+    stage: LifecycleStage;
+  };
+} | {
+  type: 'stage.changed';
+  payload: {
+    tenantId?: string;
+    previousStage?: LifecycleStage;
+    nextStage: LifecycleStage;
+  };
+} | {
+  type: 'confidence.low';
+  payload: {
+    tenantId?: string;
+    confidence: number;
+  };
+};
+interface LifecycleKpiPipelineOptions {
+  meterName?: string;
+  emitter?: EventEmitter;
+  lowConfidenceThreshold?: number;
+}
+declare class LifecycleKpiPipeline {
+  private readonly assessmentCounter;
+  private readonly confidenceHistogram;
+  private readonly stageUpDownCounter;
+  private readonly emitter;
+  private readonly lowConfidenceThreshold;
+  private readonly currentStageByTenant;
+  constructor(options?: LifecycleKpiPipelineOptions);
+  recordAssessment(assessment: LifecycleAssessment, tenantId?: string): void;
+  on(listener: (event: LifecyclePipelineEvent) => void): void;
+  private ensureStageCounters;
+}
+//#endregion
+export { LifecycleKpiPipeline, LifecycleKpiPipelineOptions, LifecyclePipelineEvent };

package/dist/tracing/index.d.mts

@@ -0,0 +1,8 @@
+import { Span, Tracer } from "@opentelemetry/api";
+
+//#region src/tracing/index.d.ts
+declare function getTracer(name?: string): Tracer;
+declare function traceAsync<T>(name: string, fn: (span: Span) => Promise<T>, tracerName?: string): Promise<T>;
+declare function traceSync<T>(name: string, fn: (span: Span) => T, tracerName?: string): T;
+//#endregion
+export { getTracer, traceAsync, traceSync };

package/dist/tracing/middleware.d.mts

@@ -0,0 +1,18 @@
+import { TelemetrySample } from "../intent/aggregator.mjs";
+
+//#region src/tracing/middleware.d.ts
+interface TracingMiddlewareOptions {
+  resolveOperation?: (input: {
+    req: Request;
+    res?: Response;
+  }) => {
+    name: string;
+    version: number;
+  } | undefined;
+  onSample?: (sample: TelemetrySample) => void;
+  tenantResolver?: (req: Request) => string | undefined;
+  actorResolver?: (req: Request) => string | undefined;
+}
+declare function createTracingMiddleware(options?: TracingMiddlewareOptions): (req: Request, next: () => Promise<Response>) => Promise<Response>;
+//#endregion
+export { TracingMiddlewareOptions, createTracingMiddleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.observability",
-  "version": "0.0.0-canary-20251217052941",
+  "version": "0.0.0-canary-20251217060433",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "scripts": {
@@ -17,7 +17,7 @@
     "test": "bun run"
   },
   "dependencies": {
-    "@lssm/lib.lifecycle": "0.0.0-canary-20251217052941"
+    "@lssm/lib.lifecycle": "0.0.0-canary-20251217060433"
   },
   "peerDependencies": {
     "@opentelemetry/api": "*"
@@ -26,19 +26,19 @@
     "typescript": "^5.0.0"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./anomaly/alert-manager": "./src/anomaly/alert-manager.ts",
-    "./anomaly/anomaly-detector": "./src/anomaly/anomaly-detector.ts",
-    "./anomaly/baseline-calculator": "./src/anomaly/baseline-calculator.ts",
-    "./anomaly/root-cause-analyzer": "./src/anomaly/root-cause-analyzer.ts",
-    "./intent/aggregator": "./src/intent/aggregator.ts",
-    "./intent/detector": "./src/intent/detector.ts",
-    "./logging": "./src/logging/index.ts",
-    "./metrics": "./src/metrics/index.ts",
-    "./pipeline/evolution-pipeline": "./src/pipeline/evolution-pipeline.ts",
-    "./pipeline/lifecycle-pipeline": "./src/pipeline/lifecycle-pipeline.ts",
-    "./tracing": "./src/tracing/index.ts",
-    "./tracing/middleware": "./src/tracing/middleware.ts",
+    ".": "./dist/index.mjs",
+    "./anomaly/alert-manager": "./dist/anomaly/alert-manager.mjs",
+    "./anomaly/anomaly-detector": "./dist/anomaly/anomaly-detector.mjs",
+    "./anomaly/baseline-calculator": "./dist/anomaly/baseline-calculator.mjs",
+    "./anomaly/root-cause-analyzer": "./dist/anomaly/root-cause-analyzer.mjs",
+    "./intent/aggregator": "./dist/intent/aggregator.mjs",
+    "./intent/detector": "./dist/intent/detector.mjs",
+    "./logging": "./dist/logging/index.mjs",
+    "./metrics": "./dist/metrics/index.mjs",
+    "./pipeline/evolution-pipeline": "./dist/pipeline/evolution-pipeline.mjs",
+    "./pipeline/lifecycle-pipeline": "./dist/pipeline/lifecycle-pipeline.mjs",
+    "./tracing": "./dist/tracing/index.mjs",
+    "./tracing/middleware": "./dist/tracing/middleware.mjs",
     "./*": "./*"
   },
   "module": "./dist/index.mjs",