@contractspec/lib.observability 1.57.0 → 1.59.0

package/dist/node/index.js

@@ -0,0 +1,1077 @@
+// src/anomaly/alert-manager.ts
+class AlertManager {
+  options;
+  cooldownMs;
+  lastAlert = new Map;
+  constructor(options) {
+    this.options = options;
+    this.cooldownMs = options.cooldownMs ?? 60000;
+  }
+  async notify(signal, analysis) {
+    const key = `${signal.type}:${analysis.culprit?.id ?? "none"}`;
+    const now = Date.now();
+    const last = this.lastAlert.get(key) ?? 0;
+    if (now - last < this.cooldownMs) {
+      return;
+    }
+    await this.options.transport({ signal, analysis });
+    this.lastAlert.set(key, now);
+  }
+}
+
+// src/anomaly/baseline-calculator.ts
+class BaselineCalculator {
+  alpha;
+  snapshot = {
+    latencyP99: 0,
+    latencyP95: 0,
+    errorRate: 0,
+    throughput: 0,
+    sampleCount: 0
+  };
+  constructor(alpha = 0.2) {
+    this.alpha = alpha;
+  }
+  update(point) {
+    const { sampleCount } = this.snapshot;
+    const nextCount = sampleCount + 1;
+    const weight = sampleCount === 0 ? 1 : this.alpha;
+    this.snapshot = {
+      latencyP99: this.mix(this.snapshot.latencyP99, point.latencyP99, weight),
+      latencyP95: this.mix(this.snapshot.latencyP95, point.latencyP95, weight),
+      errorRate: this.mix(this.snapshot.errorRate, point.errorRate, weight),
+      throughput: this.mix(this.snapshot.throughput, point.throughput, weight),
+      sampleCount: nextCount
+    };
+    return this.snapshot;
+  }
+  getSnapshot() {
+    return this.snapshot;
+  }
+  mix(current, next, weight) {
+    if (this.snapshot.sampleCount === 0) {
+      return next;
+    }
+    return current * (1 - weight) + next * weight;
+  }
+}
+
+// src/anomaly/anomaly-detector.ts
+class AnomalyDetector {
+  baseline;
+  thresholds = {
+    errorRateDelta: 0.5,
+    latencyDelta: 0.35,
+    throughputDrop: 0.4,
+    minSamples: 10
+  };
+  constructor(options = {}) {
+    this.baseline = new BaselineCalculator;
+    this.thresholds = { ...this.thresholds, ...options };
+  }
+  evaluate(point) {
+    const baselineSnapshot = this.baseline.update(point);
+    if (baselineSnapshot.sampleCount < this.thresholds.minSamples) {
+      return [];
+    }
+    const signals = [];
+    const errorDelta = this.relativeDelta(point.errorRate, baselineSnapshot.errorRate);
+    if (errorDelta > this.thresholds.errorRateDelta) {
+      signals.push({
+        type: "error_rate_spike",
+        delta: errorDelta,
+        point,
+        baseline: baselineSnapshot
+      });
+    }
+    const latencyDelta = this.relativeDelta(point.latencyP99, baselineSnapshot.latencyP99);
+    if (latencyDelta > this.thresholds.latencyDelta) {
+      signals.push({
+        type: "latency_regression",
+        delta: latencyDelta,
+        point,
+        baseline: baselineSnapshot
+      });
+    }
+    const throughputDelta = this.relativeDrop(point.throughput, baselineSnapshot.throughput);
+    if (throughputDelta > this.thresholds.throughputDrop) {
+      signals.push({
+        type: "throughput_drop",
+        delta: throughputDelta,
+        point,
+        baseline: baselineSnapshot
+      });
+    }
+    return signals;
+  }
+  relativeDelta(value, baseline) {
+    if (baseline === 0) {
+      return 0;
+    }
+    return (value - baseline) / baseline;
+  }
+  relativeDrop(value, baseline) {
+    if (baseline === 0) {
+      return 0;
+    }
+    return (baseline - value) / baseline;
+  }
+}
+
+// src/anomaly/root-cause-analyzer.ts
+class RootCauseAnalyzer {
+  lookbackMs;
+  constructor(lookbackMs = 15 * 60 * 1000) {
+    this.lookbackMs = lookbackMs;
+  }
+  analyze(signal, deployments) {
+    const windowStart = new Date(signal.point.timestamp.getTime() - this.lookbackMs);
+    const candidates = deployments.filter((deployment) => deployment.deployedAt >= windowStart).sort((a, b) => b.deployedAt.getTime() - a.deployedAt.getTime());
+    const notes = [];
+    let culprit;
+    if (candidates.length > 0) {
+      culprit = candidates[0];
+      if (culprit) {
+        notes.push(`Closest deployment ${culprit.id} (${culprit.operation}) at ${culprit.deployedAt.toISOString()}`);
+      }
+    } else {
+      notes.push("No deployments found within lookback window.");
+    }
+    if (signal.type === "latency_regression") {
+      notes.push("Verify recent schema changes and external dependency latency.");
+    }
+    if (signal.type === "error_rate_spike") {
+      notes.push("Check SLO monitor for correlated incidents.");
+    }
+    return { signal, culprit, notes };
+  }
+}
+
+// src/tracing/index.ts
+import {
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+var DEFAULT_TRACER_NAME = "@contractspec/lib.observability";
+function getTracer(name = DEFAULT_TRACER_NAME) {
+  return trace.getTracer(name);
+}
+async function traceAsync(name, fn, tracerName) {
+  const tracer = getTracer(tracerName);
+  return tracer.startActiveSpan(name, async (span) => {
+    try {
+      const result = await fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+function traceSync(name, fn, tracerName) {
+  const tracer = getTracer(tracerName);
+  return tracer.startActiveSpan(name, (span) => {
+    try {
+      const result = fn(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+// 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/logging/index.ts
+import { trace as trace2, context } from "@opentelemetry/api";
+
+class Logger {
+  serviceName;
+  constructor(serviceName) {
+    this.serviceName = serviceName;
+  }
+  log(level, message, meta = {}) {
+    const span = trace2.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");
+
+// src/tracing/middleware.ts
+function createTracingMiddleware(options = {}) {
+  return async (req, next) => {
+    const method = req.method;
+    const url = new URL(req.url);
+    const path = url.pathname;
+    standardMetrics.httpRequests.add(1, { method, path });
+    const startTime = performance.now();
+    return traceAsync(`HTTP ${method} ${path}`, async (span) => {
+      span.setAttribute("http.method", method);
+      span.setAttribute("http.url", req.url);
+      try {
+        const response = await next();
+        span.setAttribute("http.status_code", response.status);
+        const duration = (performance.now() - startTime) / 1000;
+        standardMetrics.httpDuration.record(duration, {
+          method,
+          path,
+          status: response.status.toString()
+        });
+        emitTelemetrySample({
+          req,
+          res: response,
+          span,
+          success: true,
+          durationMs: duration * 1000,
+          options
+        });
+        return response;
+      } catch (error) {
+        standardMetrics.operationErrors.add(1, { method, path });
+        emitTelemetrySample({
+          req,
+          span,
+          success: false,
+          durationMs: performance.now() - startTime,
+          error,
+          options
+        });
+        throw error;
+      }
+    });
+  };
+}
+function emitTelemetrySample({
+  req,
+  res,
+  span,
+  success,
+  durationMs,
+  error,
+  options
+}) {
+  if (!options.onSample || !options.resolveOperation)
+    return;
+  const operation = options.resolveOperation({ req, res });
+  if (!operation)
+    return;
+  const sample = {
+    operation,
+    durationMs,
+    success,
+    timestamp: new Date,
+    errorCode: !success && error instanceof Error ? error.name : success ? undefined : "unknown",
+    tenantId: options.tenantResolver?.(req),
+    actorId: options.actorResolver?.(req),
+    traceId: span.spanContext().traceId,
+    metadata: {
+      method: req.method,
+      path: new URL(req.url).pathname,
+      status: res?.status
+    }
+  };
+  options.onSample(sample);
+}
+
+// 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 metrics2 = this.aggregateMetrics(windowSamples);
+    const sequences = this.buildSequences(windowSamples);
+    const timestamps = windowSamples.map((sample) => sample.timestamp.getTime());
+    return {
+      metrics: metrics2,
+      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);
+  }
+}
+
+// src/pipeline/lifecycle-pipeline.ts
+import { EventEmitter as EventEmitter2 } 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 EventEmitter2;
+    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 }
+    });
+  }
+}
+
+// src/telemetry/posthog-telemetry.ts
+class PosthogTelemetryProvider {
+  provider;
+  eventPrefix;
+  includeMetadata;
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.eventPrefix = options.eventPrefix ?? "observability";
+    this.includeMetadata = options.includeMetadata ?? false;
+  }
+  async captureSample(sample) {
+    await this.provider.capture({
+      distinctId: sample.actorId ?? sample.tenantId ?? "unknown",
+      event: `${this.eventPrefix}.operation`,
+      timestamp: sample.timestamp,
+      properties: {
+        operation: sample.operation.name,
+        version: sample.operation.version,
+        durationMs: sample.durationMs,
+        success: sample.success,
+        errorCode: sample.errorCode ?? null,
+        tenantId: sample.tenantId ?? null,
+        traceId: sample.traceId ?? null,
+        ...this.includeMetadata && sample.metadata ? { metadata: sample.metadata } : {}
+      }
+    });
+  }
+  async captureSnapshot(snapshot) {
+    await this.provider.capture({
+      distinctId: "system",
+      event: `${this.eventPrefix}.window`,
+      timestamp: snapshot.windowEnd ?? new Date,
+      properties: {
+        sampleCount: snapshot.sampleCount,
+        metricsCount: snapshot.metrics.length,
+        sequencesCount: snapshot.sequences.length,
+        windowStart: snapshot.windowStart?.toISOString() ?? null,
+        windowEnd: snapshot.windowEnd?.toISOString() ?? null,
+        ...this.includeMetadata ? {
+          metrics: snapshot.metrics.map((metric) => ({
+            operation: metric.operation.name,
+            version: metric.operation.version,
+            totalCalls: metric.totalCalls,
+            successRate: metric.successRate,
+            errorRate: metric.errorRate,
+            averageLatencyMs: metric.averageLatencyMs,
+            p95LatencyMs: metric.p95LatencyMs,
+            p99LatencyMs: metric.p99LatencyMs,
+            maxLatencyMs: metric.maxLatencyMs,
+            topErrors: metric.topErrors
+          })),
+          sequences: snapshot.sequences
+        } : {}
+      }
+    });
+  }
+}
+
+// src/telemetry/posthog-baseline-reader.ts
+class PosthogBaselineReader {
+  reader;
+  eventPrefix;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.eventPrefix = options.eventPrefix ?? "observability";
+  }
+  async readSamples(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.operation as operationName,",
+        "  properties.version as version,",
+        "  properties.durationMs as durationMs,",
+        "  properties.success as success,",
+        "  properties.errorCode as errorCode,",
+        "  properties.tenantId as tenantId,",
+        "  properties.traceId as traceId,",
+        "  properties.metadata as metadata,",
+        "  distinct_id as actorId,",
+        "  timestamp as timestamp",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 1000}`
+      ].join(`
+`),
+      values: buildOperationValues(input)
+    });
+    return mapTelemetrySamples(result);
+  }
+  async readAggregatedMetrics(operation, windowDays = 7) {
+    const dateRange = buildWindowRange(windowDays);
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  count() as totalCalls,",
+        "  avg(properties.durationMs) as averageLatencyMs,",
+        "  quantile(0.95)(properties.durationMs) as p95LatencyMs,",
+        "  quantile(0.99)(properties.durationMs) as p99LatencyMs,",
+        "  max(properties.durationMs) as maxLatencyMs,",
+        "  sum(if(properties.success = 1, 1, 0)) as successCount,",
+        "  sum(if(properties.success = 0, 1, 0)) as errorCount",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, {
+          operations: [operation],
+          dateRange
+        })}`
+      ].join(`
+`),
+      values: buildOperationValues({
+        operations: [operation],
+        dateRange
+      })
+    });
+    const stats = mapAggregatedMetrics(result, operation, dateRange);
+    if (!stats)
+      return null;
+    const topErrors = await this.readTopErrors(operation, dateRange);
+    return {
+      ...stats,
+      topErrors
+    };
+  }
+  async readOperationSequences(dateRange) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.sequences as sequences",
+        "from events",
+        `where event = {eventName}`,
+        dateRange?.from ? "and timestamp >= {dateFrom}" : "",
+        dateRange?.to ? "and timestamp < {dateTo}" : "",
+        "order by timestamp desc",
+        "limit 50"
+      ].filter(Boolean).join(`
+`),
+      values: {
+        eventName: `${this.eventPrefix}.window`,
+        dateFrom: toIsoString(dateRange?.from),
+        dateTo: toIsoString(dateRange?.to)
+      }
+    });
+    return mergeSequences(result);
+  }
+  async readTopErrors(operation, dateRange) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.errorCode as errorCode,",
+        "  count() as errorCount",
+        "from events",
+        `where ${buildOperationWhereClause(this.eventPrefix, {
+          operations: [operation],
+          dateRange
+        })} and properties.success = 0`,
+        "group by errorCode",
+        "order by errorCount desc",
+        "limit 5"
+      ].join(`
+`),
+      values: buildOperationValues({
+        operations: [operation],
+        dateRange
+      })
+    });
+    const rows = mapRows(result);
+    return rows.reduce((acc, row) => {
+      const code = asString(row.errorCode);
+      if (!code)
+        return acc;
+      acc[code] = asNumber(row.errorCount);
+      return acc;
+    }, {});
+  }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    return this.reader.queryHogQL(input);
+  }
+}
+function buildOperationWhereClause(eventPrefix, input) {
+  const clauses = [`event = '${eventPrefix}.operation'`];
+  if (input.operations?.length) {
+    clauses.push(`(${buildOperationFilters(input.operations)})`);
+  }
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
+  }
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
+  }
+  return clauses.join(" and ");
+}
+function buildOperationValues(input) {
+  const values = {
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+  input.operations?.forEach((op, index) => {
+    values[`operationName${index}`] = op.name;
+    values[`operationVersion${index}`] = op.version;
+  });
+  return values;
+}
+function buildOperationFilters(operations) {
+  return operations.map((_op, index) => `(properties.operation = {operationName${index}} and properties.version = {operationVersion${index}})`).join(" or ");
+}
+function mapTelemetrySamples(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const operationName = asString(row.operationName);
+    const version = asString(row.version);
+    const timestamp = asDate(row.timestamp);
+    if (!operationName || !version || !timestamp) {
+      return [];
+    }
+    return [
+      {
+        operation: { name: operationName, version },
+        durationMs: asNumber(row.durationMs),
+        success: asBoolean(row.success),
+        timestamp,
+        errorCode: asOptionalString(row.errorCode) ?? undefined,
+        tenantId: asOptionalString(row.tenantId) ?? undefined,
+        traceId: asOptionalString(row.traceId) ?? undefined,
+        actorId: asOptionalString(row.actorId) ?? undefined,
+        metadata: isRecord(row.metadata) ? row.metadata : undefined
+      }
+    ];
+  });
+}
+function mapAggregatedMetrics(result, operation, dateRange) {
+  const rows = mapRows(result);
+  const row = rows[0];
+  if (!row)
+    return null;
+  const totalCalls = asNumber(row.totalCalls);
+  if (!totalCalls)
+    return null;
+  const successCount = asNumber(row.successCount);
+  const errorCount = asNumber(row.errorCount);
+  const windowStart = toDate(dateRange.from) ?? new Date;
+  const windowEnd = toDate(dateRange.to) ?? new Date;
+  return {
+    operation,
+    totalCalls,
+    successRate: totalCalls ? successCount / totalCalls : 0,
+    errorRate: totalCalls ? errorCount / totalCalls : 0,
+    averageLatencyMs: asNumber(row.averageLatencyMs),
+    p95LatencyMs: asNumber(row.p95LatencyMs),
+    p99LatencyMs: asNumber(row.p99LatencyMs),
+    maxLatencyMs: asNumber(row.maxLatencyMs),
+    windowStart,
+    windowEnd,
+    topErrors: {}
+  };
+}
+function mergeSequences(result) {
+  const rows = mapRows(result);
+  const merged = new Map;
+  rows.forEach((row) => {
+    const sequences = row.sequences;
+    if (!Array.isArray(sequences))
+      return;
+    sequences.forEach((sequence) => {
+      if (!isRecord(sequence))
+        return;
+      const steps = Array.isArray(sequence.steps) ? sequence.steps.filter((step) => typeof step === "string") : [];
+      if (steps.length === 0)
+        return;
+      const tenantId = typeof sequence.tenantId === "string" ? sequence.tenantId : undefined;
+      const count = typeof sequence.count === "number" && Number.isFinite(sequence.count) ? sequence.count : 0;
+      const key = `${tenantId ?? "global"}:${steps.join(">")}`;
+      const existing = merged.get(key);
+      if (existing) {
+        existing.count += count;
+      } else {
+        merged.set(key, { steps, tenantId, count });
+      }
+    });
+  });
+  return [...merged.values()];
+}
+function mapRows(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return [];
+  }
+  const columns = result.columns;
+  return result.results.flatMap((row) => {
+    if (!Array.isArray(row))
+      return [];
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return [record];
+  });
+}
+function buildWindowRange(windowDays) {
+  const windowEnd = new Date;
+  const windowStart = new Date(windowEnd.getTime() - windowDays * 24 * 60 * 60 * 1000);
+  return {
+    from: windowStart,
+    to: windowEnd
+  };
+}
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asOptionalString(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed))
+      return parsed;
+  }
+  return 0;
+}
+function asBoolean(value) {
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number")
+    return value !== 0;
+  if (typeof value === "string")
+    return value.toLowerCase() === "true";
+  return false;
+}
+function asDate(value) {
+  if (value instanceof Date)
+    return value;
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime()))
+      return date;
+  }
+  return null;
+}
+function toIsoString(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
+}
+function toDate(value) {
+  if (!value)
+    return null;
+  return value instanceof Date ? value : new Date(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  traceSync,
+  traceAsync,
+  standardMetrics,
+  logger,
+  getTracer,
+  getMeter,
+  createUpDownCounter,
+  createTracingMiddleware,
+  createHistogram,
+  createCounter,
+  RootCauseAnalyzer,
+  PosthogTelemetryProvider,
+  PosthogBaselineReader,
+  Logger,
+  LifecycleKpiPipeline,
+  IntentDetector,
+  IntentAggregator,
+  EvolutionPipeline,
+  BaselineCalculator,
+  AnomalyDetector,
+  AlertManager
+};