@contractspec/lib.observability 1.57.0 → 1.59.0

package/dist/intent/aggregator.mjs

@@ -1,98 +0,0 @@
-//#region src/intent/aggregator.ts
-const DEFAULT_WINDOW_MS = 900 * 1e3;
-var IntentAggregator = class {
-	windowMs;
-	sequenceSampleSize;
-	samples = [];
-	constructor(options = {}) {
-		this.windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
-		this.sequenceSampleSize = options.sequenceSampleSize ?? 1e3;
-	}
-	add(sample) {
-		this.samples.push(sample);
-	}
-	flush(now = /* @__PURE__ */ 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)) : void 0,
-			windowEnd: timestamps.length ? new Date(Math.max(...timestamps)) : void 0
-		};
-	}
-	aggregateMetrics(samples) {
-		if (!samples.length) return [];
-		const groups = /* @__PURE__ */ 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, .95),
-				p99LatencyMs: percentile(durations, .99),
-				maxLatencyMs: Math.max(...durations),
-				windowStart: new Date(Math.min(...timestamps)),
-				windowEnd: new Date(Math.max(...timestamps)),
-				topErrors
-			};
-		});
-	}
-	buildSequences(samples) {
-		const byTrace = /* @__PURE__ */ 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;
-	return values[Math.min(values.length - 1, Math.floor(ratio * values.length))] ?? 0;
-}
-
-//#endregion
-export { IntentAggregator };
-//# sourceMappingURL=aggregator.mjs.map

package/dist/intent/detector.d.mts

@@ -1,32 +0,0 @@
-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 };
-//# sourceMappingURL=detector.d.mts.map

package/dist/intent/detector.mjs

@@ -1,122 +0,0 @@
-import { randomUUID } from "node:crypto";
-
-//#region src/intent/detector.ts
-const DEFAULTS = {
-	errorRateThreshold: .05,
-	latencyP99ThresholdMs: 750,
-	throughputDropThreshold: .3,
-	minSequenceLength: 3
-};
-var IntentDetector = class {
-	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: .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;
-	}
-};
-
-//#endregion
-export { IntentDetector };
-//# sourceMappingURL=detector.mjs.map

package/dist/logging/index.d.mts

@@ -1,20 +0,0 @@
-//#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 };
-//# sourceMappingURL=index.d.mts.map

package/dist/logging/index.mjs

@@ -1,40 +0,0 @@
-import { context, trace } from "@opentelemetry/api";
-
-//#region src/logging/index.ts
-var Logger = class {
-	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: (/* @__PURE__ */ 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);
-	}
-};
-const logger = new Logger(process.env.OTEL_SERVICE_NAME || "unknown-service");
-
-//#endregion
-export { Logger, logger };
-//# sourceMappingURL=index.mjs.map

package/dist/metrics/index.d.mts

@@ -1,17 +0,0 @@
-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 };
-//# sourceMappingURL=index.d.mts.map

package/dist/metrics/index.mjs

@@ -1,26 +0,0 @@
-import { metrics } from "@opentelemetry/api";
-
-//#region src/metrics/index.ts
-const 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 });
-}
-const 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")
-};
-
-//#endregion
-export { createCounter, createHistogram, createUpDownCounter, getMeter, standardMetrics };
-//# sourceMappingURL=index.mjs.map

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

@@ -1,40 +0,0 @@
-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 };
-//# sourceMappingURL=evolution-pipeline.d.mts.map

package/dist/pipeline/evolution-pipeline.mjs

@@ -1,66 +0,0 @@
-import { IntentAggregator } from "../intent/aggregator.mjs";
-import { IntentDetector } from "../intent/detector.mjs";
-import { EventEmitter } from "node:events";
-
-//#region src/pipeline/evolution-pipeline.ts
-var EvolutionPipeline = class {
-	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 = 300 * 1e3) {
-		this.stop();
-		this.timer = setInterval(() => {
-			this.run();
-		}, intervalMs);
-	}
-	stop() {
-		if (this.timer) {
-			clearInterval(this.timer);
-			this.timer = void 0;
-		}
-	}
-	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);
-	}
-};
-
-//#endregion
-export { EvolutionPipeline };
-//# sourceMappingURL=evolution-pipeline.mjs.map

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

@@ -1,44 +0,0 @@
-import { EventEmitter } from "node:events";
-import { LifecycleAssessment, LifecycleStage } from "@contractspec/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 };
-//# sourceMappingURL=lifecycle-pipeline.d.mts.map

package/dist/pipeline/lifecycle-pipeline.mjs

@@ -1,73 +0,0 @@
-import { createCounter, createHistogram, createUpDownCounter } from "../metrics/index.mjs";
-import { EventEmitter } from "node:events";
-import { getStageLabel } from "@contractspec/lib.lifecycle";
-
-//#region src/pipeline/lifecycle-pipeline.ts
-var LifecycleKpiPipeline = class {
-	assessmentCounter;
-	confidenceHistogram;
-	stageUpDownCounter;
-	emitter;
-	lowConfidenceThreshold;
-	currentStageByTenant = /* @__PURE__ */ 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 ?? .4;
-	}
-	recordAssessment(assessment, tenantId) {
-		const attributes = {
-			stage: getStageLabel(assessment.stage),
-			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 !== void 0) 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
-			}
-		});
-	}
-};
-
-//#endregion
-export { LifecycleKpiPipeline };
-//# sourceMappingURL=lifecycle-pipeline.mjs.map

package/dist/telemetry/posthog-baseline-reader.d.mts

@@ -1,31 +0,0 @@
-import { AggregatedOperationMetrics, OperationSequence, TelemetrySample } from "../intent/aggregator.mjs";
-import { AnalyticsReader, DateRangeInput } from "@contractspec/lib.contracts/integrations/providers/analytics";
-
-//#region src/telemetry/posthog-baseline-reader.d.ts
-interface ReadTelemetrySamplesInput {
-  operations?: {
-    name: string;
-    version: string;
-  }[];
-  dateRange?: DateRangeInput;
-  limit?: number;
-}
-interface PosthogBaselineReaderOptions {
-  eventPrefix?: string;
-}
-declare class PosthogBaselineReader {
-  private readonly reader;
-  private readonly eventPrefix;
-  constructor(reader: AnalyticsReader, options?: PosthogBaselineReaderOptions);
-  readSamples(input: ReadTelemetrySamplesInput): Promise<TelemetrySample[]>;
-  readAggregatedMetrics(operation: {
-    name: string;
-    version: string;
-  }, windowDays?: number): Promise<AggregatedOperationMetrics | null>;
-  readOperationSequences(dateRange?: DateRangeInput): Promise<OperationSequence[]>;
-  private readTopErrors;
-  private queryHogQL;
-}
-//#endregion
-export { PosthogBaselineReader, PosthogBaselineReaderOptions, ReadTelemetrySamplesInput };
-//# sourceMappingURL=posthog-baseline-reader.d.mts.map