@contractspec/lib.observability 1.56.1 → 1.58.0

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/tracing/index.d.mts

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

package/dist/tracing/index.mjs

@@ -1,47 +0,0 @@
-import { SpanStatusCode, trace } from "@opentelemetry/api";
-
-//#region src/tracing/index.ts
-const DEFAULT_TRACER_NAME = "@contractspec/lib.observability";
-function getTracer(name = DEFAULT_TRACER_NAME) {
-	return trace.getTracer(name);
-}
-async function traceAsync(name, fn, tracerName) {
-	return getTracer(tracerName).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) {
-	return getTracer(tracerName).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();
-		}
-	});
-}
-
-//#endregion
-export { getTracer, traceAsync, traceSync };
-//# sourceMappingURL=index.mjs.map

package/dist/tracing/middleware.d.mts

@@ -1,19 +0,0 @@
-import { TelemetrySample } from "../intent/aggregator.mjs";
-
-//#region src/tracing/middleware.d.ts
-interface TracingMiddlewareOptions {
-  resolveOperation?: (input: {
-    req: Request;
-    res?: Response;
-  }) => {
-    name: string;
-    version: string;
-  } | 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 };
-//# sourceMappingURL=middleware.d.mts.map

package/dist/tracing/middleware.mjs

@@ -1,80 +0,0 @@
-import { traceAsync } from "./index.mjs";
-import { standardMetrics } from "../metrics/index.mjs";
-
-//#region src/tracing/middleware.ts
-function createTracingMiddleware(options = {}) {
-	return async (req, next) => {
-		const method = req.method;
-		const path = new URL(req.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) / 1e3;
-				standardMetrics.httpDuration.record(duration, {
-					method,
-					path,
-					status: response.status.toString()
-				});
-				emitTelemetrySample({
-					req,
-					res: response,
-					span,
-					success: true,
-					durationMs: duration * 1e3,
-					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: /* @__PURE__ */ new Date(),
-		errorCode: !success && error instanceof Error ? error.name : success ? void 0 : "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);
-}
-
-//#endregion
-export { createTracingMiddleware };
-//# sourceMappingURL=middleware.mjs.map