@contractspec/lib.observability 1.57.0 → 1.58.0

package/dist/node/intent/aggregator.js

@@ -0,0 +1,109 @@
+// src/intent/aggregator.ts
+var DEFAULT_WINDOW_MS = 15 * 60 * 1000;
+
+class IntentAggregator {
+  windowMs;
+  sequenceSampleSize;
+  samples = [];
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    this.sequenceSampleSize = options.sequenceSampleSize ?? 1000;
+  }
+  add(sample) {
+    this.samples.push(sample);
+  }
+  flush(now = new Date) {
+    const minTimestamp = now.getTime() - this.windowMs;
+    const windowSamples = this.samples.filter((sample) => sample.timestamp.getTime() >= minTimestamp);
+    this.samples.length = 0;
+    const metrics = this.aggregateMetrics(windowSamples);
+    const sequences = this.buildSequences(windowSamples);
+    const timestamps = windowSamples.map((sample) => sample.timestamp.getTime());
+    return {
+      metrics,
+      sequences,
+      sampleCount: windowSamples.length,
+      windowStart: timestamps.length ? new Date(Math.min(...timestamps)) : undefined,
+      windowEnd: timestamps.length ? new Date(Math.max(...timestamps)) : undefined
+    };
+  }
+  aggregateMetrics(samples) {
+    if (!samples.length)
+      return [];
+    const groups = new Map;
+    for (const sample of samples) {
+      const key = `${sample.operation.name}.v${sample.operation.version}`;
+      const arr = groups.get(key) ?? [];
+      arr.push(sample);
+      groups.set(key, arr);
+    }
+    return [...groups.values()].map((group) => {
+      const first = group[0];
+      if (!first)
+        throw new Error("Empty group in aggregation");
+      const durations = group.map((s) => s.durationMs).sort((a, b) => a - b);
+      const errors = group.filter((s) => !s.success);
+      const totalCalls = group.length;
+      const topErrors = errors.reduce((acc, sample) => {
+        if (!sample.errorCode)
+          return acc;
+        acc[sample.errorCode] = (acc[sample.errorCode] ?? 0) + 1;
+        return acc;
+      }, {});
+      const timestamps = group.map((s) => s.timestamp.getTime());
+      return {
+        operation: first.operation,
+        totalCalls,
+        successRate: (totalCalls - errors.length) / totalCalls,
+        errorRate: errors.length / totalCalls,
+        averageLatencyMs: durations.reduce((sum, value) => sum + value, 0) / totalCalls,
+        p95LatencyMs: percentile(durations, 0.95),
+        p99LatencyMs: percentile(durations, 0.99),
+        maxLatencyMs: Math.max(...durations),
+        windowStart: new Date(Math.min(...timestamps)),
+        windowEnd: new Date(Math.max(...timestamps)),
+        topErrors
+      };
+    });
+  }
+  buildSequences(samples) {
+    const byTrace = new Map;
+    for (const sample of samples.slice(-this.sequenceSampleSize)) {
+      if (!sample.traceId)
+        continue;
+      const arr = byTrace.get(sample.traceId) ?? [];
+      arr.push(sample);
+      byTrace.set(sample.traceId, arr);
+    }
+    const sequences = {};
+    for (const events of byTrace.values()) {
+      const ordered = events.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+      const steps = ordered.map((event) => event.operation.name);
+      if (steps.length < 2)
+        continue;
+      const key = `${steps.join(">")}@${ordered[0]?.tenantId ?? "global"}`;
+      const existing = sequences[key];
+      if (existing) {
+        existing.count += 1;
+      } else {
+        sequences[key] = {
+          steps,
+          tenantId: ordered[0]?.tenantId,
+          count: 1
+        };
+      }
+    }
+    return Object.values(sequences).sort((a, b) => b.count - a.count);
+  }
+}
+function percentile(values, ratio) {
+  if (!values.length)
+    return 0;
+  if (values.length === 1)
+    return values[0] ?? 0;
+  const index = Math.min(values.length - 1, Math.floor(ratio * values.length));
+  return values[index] ?? 0;
+}
+export {
+  IntentAggregator
+};

package/dist/node/intent/detector.js

@@ -0,0 +1,132 @@
+// src/intent/detector.ts
+import { randomUUID } from "node:crypto";
+var DEFAULTS = {
+  errorRateThreshold: 0.05,
+  latencyP99ThresholdMs: 750,
+  throughputDropThreshold: 0.3,
+  minSequenceLength: 3
+};
+
+class IntentDetector {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      errorRateThreshold: options.errorRateThreshold ?? DEFAULTS.errorRateThreshold,
+      latencyP99ThresholdMs: options.latencyP99ThresholdMs ?? DEFAULTS.latencyP99ThresholdMs,
+      throughputDropThreshold: options.throughputDropThreshold ?? DEFAULTS.throughputDropThreshold,
+      minSequenceLength: options.minSequenceLength ?? DEFAULTS.minSequenceLength
+    };
+  }
+  detectFromMetrics(current, previous) {
+    const signals = [];
+    const baseline = new Map((previous ?? []).map((metric) => [
+      `${metric.operation.name}.v${metric.operation.version}`,
+      metric
+    ]));
+    for (const metric of current) {
+      if (metric.errorRate >= this.options.errorRateThreshold) {
+        signals.push({
+          id: randomUUID(),
+          type: "error-spike",
+          operation: metric.operation,
+          confidence: Math.min(1, metric.errorRate / this.options.errorRateThreshold),
+          description: `Error rate ${metric.errorRate.toFixed(2)} exceeded threshold`,
+          metadata: {
+            errorRate: metric.errorRate,
+            topErrors: metric.topErrors
+          },
+          evidence: [
+            {
+              type: "metric",
+              description: "error-rate",
+              data: {
+                errorRate: metric.errorRate,
+                threshold: this.options.errorRateThreshold
+              }
+            }
+          ]
+        });
+        continue;
+      }
+      if (metric.p99LatencyMs >= this.options.latencyP99ThresholdMs) {
+        signals.push({
+          id: randomUUID(),
+          type: "latency-regression",
+          operation: metric.operation,
+          confidence: Math.min(1, metric.p99LatencyMs / this.options.latencyP99ThresholdMs),
+          description: `P99 latency ${metric.p99LatencyMs}ms exceeded threshold`,
+          metadata: { p99LatencyMs: metric.p99LatencyMs },
+          evidence: [
+            {
+              type: "metric",
+              description: "p99-latency",
+              data: {
+                p99LatencyMs: metric.p99LatencyMs,
+                threshold: this.options.latencyP99ThresholdMs
+              }
+            }
+          ]
+        });
+        continue;
+      }
+      const base = baseline.get(`${metric.operation.name}.v${metric.operation.version}`);
+      if (base) {
+        const drop = (base.totalCalls - metric.totalCalls) / Math.max(base.totalCalls, 1);
+        if (drop >= this.options.throughputDropThreshold) {
+          signals.push({
+            id: randomUUID(),
+            type: "throughput-drop",
+            operation: metric.operation,
+            confidence: Math.min(1, drop / this.options.throughputDropThreshold),
+            description: `Throughput dropped ${(drop * 100).toFixed(1)}% vs baseline`,
+            metadata: {
+              baselineCalls: base.totalCalls,
+              currentCalls: metric.totalCalls
+            },
+            evidence: [
+              {
+                type: "metric",
+                description: "throughput-drop",
+                data: {
+                  baselineCalls: base.totalCalls,
+                  currentCalls: metric.totalCalls
+                }
+              }
+            ]
+          });
+        }
+      }
+    }
+    return signals;
+  }
+  detectSequentialIntents(sequences) {
+    const signals = [];
+    for (const sequence of sequences) {
+      if (sequence.steps.length < this.options.minSequenceLength)
+        continue;
+      const description = sequence.steps.join(" → ");
+      signals.push({
+        id: randomUUID(),
+        type: "missing-workflow-step",
+        confidence: 0.6,
+        description: `Repeated workflow detected: ${description}`,
+        metadata: {
+          steps: sequence.steps,
+          tenantId: sequence.tenantId,
+          occurrences: sequence.count
+        },
+        evidence: [
+          {
+            type: "sequence",
+            description: "sequential-calls",
+            data: { steps: sequence.steps, count: sequence.count }
+          }
+        ]
+      });
+    }
+    return signals;
+  }
+}
+export {
+  IntentDetector
+};

package/dist/node/logging/index.js

@@ -0,0 +1,41 @@
+// src/logging/index.ts
+import { trace, context } from "@opentelemetry/api";
+
+class Logger {
+  serviceName;
+  constructor(serviceName) {
+    this.serviceName = serviceName;
+  }
+  log(level, message, meta = {}) {
+    const span = trace.getSpan(context.active());
+    const traceId = span?.spanContext().traceId;
+    const spanId = span?.spanContext().spanId;
+    const entry = {
+      timestamp: new Date().toISOString(),
+      service: this.serviceName,
+      level,
+      message,
+      traceId,
+      spanId,
+      ...meta
+    };
+    console.log(JSON.stringify(entry));
+  }
+  debug(message, meta) {
+    this.log("debug", message, meta);
+  }
+  info(message, meta) {
+    this.log("info", message, meta);
+  }
+  warn(message, meta) {
+    this.log("warn", message, meta);
+  }
+  error(message, meta) {
+    this.log("error", message, meta);
+  }
+}
+var logger = new Logger(process.env.OTEL_SERVICE_NAME || "unknown-service");
+export {
+  logger,
+  Logger
+};

package/dist/node/metrics/index.js

@@ -0,0 +1,30 @@
+// src/metrics/index.ts
+import {
+  metrics
+} from "@opentelemetry/api";
+var DEFAULT_METER_NAME = "@contractspec/lib.observability";
+function getMeter(name = DEFAULT_METER_NAME) {
+  return metrics.getMeter(name);
+}
+function createCounter(name, description, meterName) {
+  return getMeter(meterName).createCounter(name, { description });
+}
+function createUpDownCounter(name, description, meterName) {
+  return getMeter(meterName).createUpDownCounter(name, { description });
+}
+function createHistogram(name, description, meterName) {
+  return getMeter(meterName).createHistogram(name, { description });
+}
+var standardMetrics = {
+  httpRequests: createCounter("http_requests_total", "Total HTTP requests"),
+  httpDuration: createHistogram("http_request_duration_seconds", "HTTP request duration"),
+  operationErrors: createCounter("operation_errors_total", "Total operation errors"),
+  workflowDuration: createHistogram("workflow_duration_seconds", "Workflow execution duration")
+};
+export {
+  standardMetrics,
+  getMeter,
+  createUpDownCounter,
+  createHistogram,
+  createCounter
+};

package/dist/node/pipeline/evolution-pipeline.js

@@ -0,0 +1,299 @@
+// src/intent/aggregator.ts
+var DEFAULT_WINDOW_MS = 15 * 60 * 1000;
+
+class IntentAggregator {
+  windowMs;
+  sequenceSampleSize;
+  samples = [];
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    this.sequenceSampleSize = options.sequenceSampleSize ?? 1000;
+  }
+  add(sample) {
+    this.samples.push(sample);
+  }
+  flush(now = new Date) {
+    const minTimestamp = now.getTime() - this.windowMs;
+    const windowSamples = this.samples.filter((sample) => sample.timestamp.getTime() >= minTimestamp);
+    this.samples.length = 0;
+    const metrics = this.aggregateMetrics(windowSamples);
+    const sequences = this.buildSequences(windowSamples);
+    const timestamps = windowSamples.map((sample) => sample.timestamp.getTime());
+    return {
+      metrics,
+      sequences,
+      sampleCount: windowSamples.length,
+      windowStart: timestamps.length ? new Date(Math.min(...timestamps)) : undefined,
+      windowEnd: timestamps.length ? new Date(Math.max(...timestamps)) : undefined
+    };
+  }
+  aggregateMetrics(samples) {
+    if (!samples.length)
+      return [];
+    const groups = new Map;
+    for (const sample of samples) {
+      const key = `${sample.operation.name}.v${sample.operation.version}`;
+      const arr = groups.get(key) ?? [];
+      arr.push(sample);
+      groups.set(key, arr);
+    }
+    return [...groups.values()].map((group) => {
+      const first = group[0];
+      if (!first)
+        throw new Error("Empty group in aggregation");
+      const durations = group.map((s) => s.durationMs).sort((a, b) => a - b);
+      const errors = group.filter((s) => !s.success);
+      const totalCalls = group.length;
+      const topErrors = errors.reduce((acc, sample) => {
+        if (!sample.errorCode)
+          return acc;
+        acc[sample.errorCode] = (acc[sample.errorCode] ?? 0) + 1;
+        return acc;
+      }, {});
+      const timestamps = group.map((s) => s.timestamp.getTime());
+      return {
+        operation: first.operation,
+        totalCalls,
+        successRate: (totalCalls - errors.length) / totalCalls,
+        errorRate: errors.length / totalCalls,
+        averageLatencyMs: durations.reduce((sum, value) => sum + value, 0) / totalCalls,
+        p95LatencyMs: percentile(durations, 0.95),
+        p99LatencyMs: percentile(durations, 0.99),
+        maxLatencyMs: Math.max(...durations),
+        windowStart: new Date(Math.min(...timestamps)),
+        windowEnd: new Date(Math.max(...timestamps)),
+        topErrors
+      };
+    });
+  }
+  buildSequences(samples) {
+    const byTrace = new Map;
+    for (const sample of samples.slice(-this.sequenceSampleSize)) {
+      if (!sample.traceId)
+        continue;
+      const arr = byTrace.get(sample.traceId) ?? [];
+      arr.push(sample);
+      byTrace.set(sample.traceId, arr);
+    }
+    const sequences = {};
+    for (const events of byTrace.values()) {
+      const ordered = events.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+      const steps = ordered.map((event) => event.operation.name);
+      if (steps.length < 2)
+        continue;
+      const key = `${steps.join(">")}@${ordered[0]?.tenantId ?? "global"}`;
+      const existing = sequences[key];
+      if (existing) {
+        existing.count += 1;
+      } else {
+        sequences[key] = {
+          steps,
+          tenantId: ordered[0]?.tenantId,
+          count: 1
+        };
+      }
+    }
+    return Object.values(sequences).sort((a, b) => b.count - a.count);
+  }
+}
+function percentile(values, ratio) {
+  if (!values.length)
+    return 0;
+  if (values.length === 1)
+    return values[0] ?? 0;
+  const index = Math.min(values.length - 1, Math.floor(ratio * values.length));
+  return values[index] ?? 0;
+}
+
+// src/intent/detector.ts
+import { randomUUID } from "node:crypto";
+var DEFAULTS = {
+  errorRateThreshold: 0.05,
+  latencyP99ThresholdMs: 750,
+  throughputDropThreshold: 0.3,
+  minSequenceLength: 3
+};
+
+class IntentDetector {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      errorRateThreshold: options.errorRateThreshold ?? DEFAULTS.errorRateThreshold,
+      latencyP99ThresholdMs: options.latencyP99ThresholdMs ?? DEFAULTS.latencyP99ThresholdMs,
+      throughputDropThreshold: options.throughputDropThreshold ?? DEFAULTS.throughputDropThreshold,
+      minSequenceLength: options.minSequenceLength ?? DEFAULTS.minSequenceLength
+    };
+  }
+  detectFromMetrics(current, previous) {
+    const signals = [];
+    const baseline = new Map((previous ?? []).map((metric) => [
+      `${metric.operation.name}.v${metric.operation.version}`,
+      metric
+    ]));
+    for (const metric of current) {
+      if (metric.errorRate >= this.options.errorRateThreshold) {
+        signals.push({
+          id: randomUUID(),
+          type: "error-spike",
+          operation: metric.operation,
+          confidence: Math.min(1, metric.errorRate / this.options.errorRateThreshold),
+          description: `Error rate ${metric.errorRate.toFixed(2)} exceeded threshold`,
+          metadata: {
+            errorRate: metric.errorRate,
+            topErrors: metric.topErrors
+          },
+          evidence: [
+            {
+              type: "metric",
+              description: "error-rate",
+              data: {
+                errorRate: metric.errorRate,
+                threshold: this.options.errorRateThreshold
+              }
+            }
+          ]
+        });
+        continue;
+      }
+      if (metric.p99LatencyMs >= this.options.latencyP99ThresholdMs) {
+        signals.push({
+          id: randomUUID(),
+          type: "latency-regression",
+          operation: metric.operation,
+          confidence: Math.min(1, metric.p99LatencyMs / this.options.latencyP99ThresholdMs),
+          description: `P99 latency ${metric.p99LatencyMs}ms exceeded threshold`,
+          metadata: { p99LatencyMs: metric.p99LatencyMs },
+          evidence: [
+            {
+              type: "metric",
+              description: "p99-latency",
+              data: {
+                p99LatencyMs: metric.p99LatencyMs,
+                threshold: this.options.latencyP99ThresholdMs
+              }
+            }
+          ]
+        });
+        continue;
+      }
+      const base = baseline.get(`${metric.operation.name}.v${metric.operation.version}`);
+      if (base) {
+        const drop = (base.totalCalls - metric.totalCalls) / Math.max(base.totalCalls, 1);
+        if (drop >= this.options.throughputDropThreshold) {
+          signals.push({
+            id: randomUUID(),
+            type: "throughput-drop",
+            operation: metric.operation,
+            confidence: Math.min(1, drop / this.options.throughputDropThreshold),
+            description: `Throughput dropped ${(drop * 100).toFixed(1)}% vs baseline`,
+            metadata: {
+              baselineCalls: base.totalCalls,
+              currentCalls: metric.totalCalls
+            },
+            evidence: [
+              {
+                type: "metric",
+                description: "throughput-drop",
+                data: {
+                  baselineCalls: base.totalCalls,
+                  currentCalls: metric.totalCalls
+                }
+              }
+            ]
+          });
+        }
+      }
+    }
+    return signals;
+  }
+  detectSequentialIntents(sequences) {
+    const signals = [];
+    for (const sequence of sequences) {
+      if (sequence.steps.length < this.options.minSequenceLength)
+        continue;
+      const description = sequence.steps.join(" → ");
+      signals.push({
+        id: randomUUID(),
+        type: "missing-workflow-step",
+        confidence: 0.6,
+        description: `Repeated workflow detected: ${description}`,
+        metadata: {
+          steps: sequence.steps,
+          tenantId: sequence.tenantId,
+          occurrences: sequence.count
+        },
+        evidence: [
+          {
+            type: "sequence",
+            description: "sequential-calls",
+            data: { steps: sequence.steps, count: sequence.count }
+          }
+        ]
+      });
+    }
+    return signals;
+  }
+}
+
+// src/pipeline/evolution-pipeline.ts
+import { EventEmitter } from "node:events";
+class EvolutionPipeline {
+  detector;
+  aggregator;
+  emitter;
+  onIntent;
+  onSnapshot;
+  timer;
+  previousMetrics;
+  constructor(options = {}) {
+    this.detector = options.detector ?? new IntentDetector;
+    this.aggregator = options.aggregator ?? new IntentAggregator;
+    this.emitter = options.emitter ?? new EventEmitter;
+    this.onIntent = options.onIntent;
+    this.onSnapshot = options.onSnapshot;
+  }
+  ingest(sample) {
+    this.aggregator.add(sample);
+  }
+  on(listener) {
+    this.emitter.on("event", listener);
+  }
+  start(intervalMs = 5 * 60 * 1000) {
+    this.stop();
+    this.timer = setInterval(() => {
+      this.run();
+    }, intervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+  async run() {
+    const snapshot = this.aggregator.flush();
+    this.emit({
+      type: "telemetry.window",
+      payload: { sampleCount: snapshot.sampleCount }
+    });
+    if (this.onSnapshot)
+      await this.onSnapshot(snapshot);
+    if (!snapshot.sampleCount)
+      return;
+    const metricSignals = this.detector.detectFromMetrics(snapshot.metrics, this.previousMetrics);
+    const sequenceSignals = this.detector.detectSequentialIntents(snapshot.sequences);
+    this.previousMetrics = snapshot.metrics;
+    const signals = [...metricSignals, ...sequenceSignals];
+    for (const signal of signals) {
+      if (this.onIntent)
+        await this.onIntent(signal);
+      this.emit({ type: "intent.detected", payload: signal });
+    }
+  }
+  emit(event) {
+    this.emitter.emit("event", event);
+  }
+}
+export {
+  EvolutionPipeline
+};

package/dist/node/pipeline/lifecycle-pipeline.js

@@ -0,0 +1,85 @@
+// src/metrics/index.ts
+import {
+  metrics
+} from "@opentelemetry/api";
+var DEFAULT_METER_NAME = "@contractspec/lib.observability";
+function getMeter(name = DEFAULT_METER_NAME) {
+  return metrics.getMeter(name);
+}
+function createCounter(name, description, meterName) {
+  return getMeter(meterName).createCounter(name, { description });
+}
+function createUpDownCounter(name, description, meterName) {
+  return getMeter(meterName).createUpDownCounter(name, { description });
+}
+function createHistogram(name, description, meterName) {
+  return getMeter(meterName).createHistogram(name, { description });
+}
+var standardMetrics = {
+  httpRequests: createCounter("http_requests_total", "Total HTTP requests"),
+  httpDuration: createHistogram("http_request_duration_seconds", "HTTP request duration"),
+  operationErrors: createCounter("operation_errors_total", "Total operation errors"),
+  workflowDuration: createHistogram("workflow_duration_seconds", "Workflow execution duration")
+};
+
+// src/pipeline/lifecycle-pipeline.ts
+import { EventEmitter } from "node:events";
+import { getStageLabel } from "@contractspec/lib.lifecycle";
+class LifecycleKpiPipeline {
+  assessmentCounter;
+  confidenceHistogram;
+  stageUpDownCounter;
+  emitter;
+  lowConfidenceThreshold;
+  currentStageByTenant = new Map;
+  constructor(options = {}) {
+    const meterName = options.meterName ?? "@contractspec/lib.lifecycle-kpi";
+    this.assessmentCounter = createCounter("lifecycle_assessments_total", "Total lifecycle assessments", meterName);
+    this.confidenceHistogram = createHistogram("lifecycle_assessment_confidence", "Lifecycle assessment confidence distribution", meterName);
+    this.stageUpDownCounter = createUpDownCounter("lifecycle_stage_tenants", "Current tenants per lifecycle stage", meterName);
+    this.emitter = options.emitter ?? new EventEmitter;
+    this.lowConfidenceThreshold = options.lowConfidenceThreshold ?? 0.4;
+  }
+  recordAssessment(assessment, tenantId) {
+    const stageLabel = getStageLabel(assessment.stage);
+    const attributes = { stage: stageLabel, tenantId };
+    this.assessmentCounter.add(1, attributes);
+    this.confidenceHistogram.record(assessment.confidence, attributes);
+    this.ensureStageCounters(assessment.stage, tenantId);
+    this.emitter.emit("event", {
+      type: "assessment.recorded",
+      payload: { tenantId, stage: assessment.stage }
+    });
+    if (assessment.confidence < this.lowConfidenceThreshold) {
+      this.emitter.emit("event", {
+        type: "confidence.low",
+        payload: { tenantId, confidence: assessment.confidence }
+      });
+    }
+  }
+  on(listener) {
+    this.emitter.on("event", listener);
+  }
+  ensureStageCounters(stage, tenantId) {
+    if (!tenantId)
+      return;
+    const previous = this.currentStageByTenant.get(tenantId);
+    if (previous === stage)
+      return;
+    if (previous !== undefined) {
+      this.stageUpDownCounter.add(-1, {
+        stage: getStageLabel(previous),
+        tenantId
+      });
+    }
+    this.stageUpDownCounter.add(1, { stage: getStageLabel(stage), tenantId });
+    this.currentStageByTenant.set(tenantId, stage);
+    this.emitter.emit("event", {
+      type: "stage.changed",
+      payload: { tenantId, previousStage: previous, nextStage: stage }
+    });
+  }
+}
+export {
+  LifecycleKpiPipeline
+};