@contractspec/lib.observability 0.0.0-canary-20260113162409

package/CHANGELOG.md

@@ -0,0 +1,351 @@
+# @contractspec/lib.observability
+
+## 0.0.0-canary-20260113162409
+
+### Minor Changes
+
+- caf8701: feat: add cli vibe command to run workflow
+- c69b849: feat: add api web services (mcp & website)
+- 42b8d78: feat: add cli `contractspec vibe` workflow to simplify usage
+- fd38e85: feat: auto-fix contractspec issues
+
+### Patch Changes
+
+- e7ded36: feat: improve stability (adding ts-morph)
+- c231a8b: test: improve workspace stability
+- Updated dependencies [e7ded36]
+- Updated dependencies [caf8701]
+- Updated dependencies [c69b849]
+- Updated dependencies [c231a8b]
+- Updated dependencies [42b8d78]
+- Updated dependencies [fd38e85]
+  - @contractspec/lib.lifecycle@0.0.0-canary-20260113162409
+
+## 1.46.2
+
+### Patch Changes
+
+- 7e21625: feat: library services (landing page & api)
+- Updated dependencies [7e21625]
+  - @contractspec/lib.lifecycle@1.46.2
+
+## 1.46.1
+
+### Patch Changes
+
+- 2d8a72b: fix: mcp for presentation
+- Updated dependencies [2d8a72b]
+  - @contractspec/lib.lifecycle@1.46.1
+
+## 1.46.0
+
+### Minor Changes
+
+- 07cb19b: feat: feat: cleaude code & opencode integrations
+
+### Patch Changes
+
+- Updated dependencies [07cb19b]
+  - @contractspec/lib.lifecycle@1.46.0
+
+## 1.45.6
+
+### Patch Changes
+
+- a913074: feat: improve ai agents rules management"
+- Updated dependencies [a913074]
+  - @contractspec/lib.lifecycle@1.45.6
+
+## 1.45.5
+
+### Patch Changes
+
+- 9ddd7fa: feat: improve versioning
+- Updated dependencies [9ddd7fa]
+  - @contractspec/lib.lifecycle@1.45.5
+
+## 1.45.4
+
+### Patch Changes
+
+- fix: github action
+- Updated dependencies
+  - @contractspec/lib.lifecycle@1.45.4
+
+## 1.45.3
+
+### Patch Changes
+
+- e74ea9e: feat: version management
+- Updated dependencies [e74ea9e]
+  - @contractspec/lib.lifecycle@1.45.3
+
+## 1.45.2
+
+### Patch Changes
+
+- 39ca241: code cleaning
+- Updated dependencies [39ca241]
+  - @contractspec/lib.lifecycle@1.45.2
+
+## 1.45.1
+
+### Patch Changes
+
+- feat: improve app config and examples contracts
+- Updated dependencies
+  - @contractspec/lib.lifecycle@1.45.1
+
+## 1.45.0
+
+### Minor Changes
+
+- e73ca1d: feat: improve app config and examples contracts
+  feat: Contract layers support (features, examples, app-configs)
+
+  ### New CLI Commands
+  - `contractspec list layers` - List all contract layers with filtering
+
+  ### Enhanced Commands
+  - `contractspec ci` - New `layers` check category validates features/examples/config
+  - `contractspec doctor` - New `layers` health checks
+  - `contractspec integrity` - Now shows layer statistics
+
+  ### New APIs
+  - `discoverLayers()` - Scan workspace for all layer files
+  - `scanExampleSource()` - Parse ExampleSpec from source code
+  - `isExampleFile()` - Check if file is an example spec
+
+### Patch Changes
+
+- Updated dependencies [e73ca1d]
+  - @contractspec/lib.lifecycle@1.45.0
+
+## 1.44.1
+
+### Patch Changes
+
+- 3c594fb: fix
+- Updated dependencies [3c594fb]
+  - @contractspec/lib.lifecycle@1.44.1
+
+## 1.44.0
+
+### Minor Changes
+
+- 5f3a868: chore: isolate branding to contractspec.io
+
+### Patch Changes
+
+- Updated dependencies [5f3a868]
+  - @contractspec/lib.lifecycle@1.44.0
+
+## 1.43.3
+
+### Patch Changes
+
+- 9216062: fix: cross-platform compatibility
+- Updated dependencies [9216062]
+  - @contractspec/lib.lifecycle@1.43.3
+
+## 1.43.2
+
+### Patch Changes
+
+- 24d9759: improve documentation
+- Updated dependencies [24d9759]
+  - @contractspec/lib.lifecycle@1.43.2
+
+## 1.43.1
+
+### Patch Changes
+
+- e147271: fix: improve stability
+- Updated dependencies [e147271]
+  - @contractspec/lib.lifecycle@1.43.1
+
+## 1.43.0
+
+### Minor Changes
+
+- 042d072: feat: schema declaration using json schema, including zod
+
+### Patch Changes
+
+- Updated dependencies [042d072]
+  - @contractspec/lib.lifecycle@1.43.0
+
+## 1.42.10
+
+### Patch Changes
+
+- 1e6a0f1: fix: mcp server
+- Updated dependencies [1e6a0f1]
+  - @contractspec/lib.lifecycle@1.42.10
+
+## 1.42.9
+
+### Patch Changes
+
+- 9281db7: fix ModelRegistry
+- Updated dependencies [9281db7]
+  - @contractspec/lib.lifecycle@1.42.9
+
+## 1.42.8
+
+### Patch Changes
+
+- e07b5ac: fix
+- Updated dependencies [e07b5ac]
+  - @contractspec/lib.lifecycle@1.42.8
+
+## 1.42.7
+
+### Patch Changes
+
+- e9b575d: fix release
+- Updated dependencies [e9b575d]
+  - @contractspec/lib.lifecycle@1.42.7
+
+## 1.42.6
+
+### Patch Changes
+
+- 1500242: fix tooling
+- Updated dependencies [1500242]
+  - @contractspec/lib.lifecycle@1.42.6
+
+## 1.42.5
+
+### Patch Changes
+
+- 1299719: fix vscode
+- Updated dependencies [1299719]
+  - @contractspec/lib.lifecycle@1.42.5
+
+## 1.42.4
+
+### Patch Changes
+
+- ac28b99: fix: generate from openapi
+- Updated dependencies [ac28b99]
+  - @contractspec/lib.lifecycle@1.42.4
+
+## 1.42.3
+
+### Patch Changes
+
+- 3f5d015: fix(tooling): cicd
+- Updated dependencies [3f5d015]
+  - @contractspec/lib.lifecycle@1.42.3
+
+## 1.42.2
+
+### Patch Changes
+
+- 1f9ac4c: fix
+- Updated dependencies [1f9ac4c]
+  - @contractspec/lib.lifecycle@1.42.2
+
+## 1.42.1
+
+### Patch Changes
+
+- f043995: Fix release
+- Updated dependencies [f043995]
+  - @contractspec/lib.lifecycle@1.42.1
+
+## 1.42.0
+
+### Minor Changes
+
+- 8eefd9c: initial release
+
+### Patch Changes
+
+- Updated dependencies [8eefd9c]
+  - @contractspec/lib.lifecycle@1.42.0
+
+## 0.5.0
+
+### Minor Changes
+
+- Refactor to be compatible with ai-sdk v6
+
+### Patch Changes
+
+- Updated dependencies
+  - @contractspec/lib.lifecycle@0.4.0
+
+## 0.4.1
+
+### Patch Changes
+
+- Fix dependencies
+- Updated dependencies
+  - @contractspec/lib.lifecycle@0.3.1
+
+## 0.4.0
+
+### Minor Changes
+
+- b7621d3: Fix version
+
+### Patch Changes
+
+- Updated dependencies [b7621d3]
+  - @contractspec/lib.lifecycle@0.3.0
+
+## 0.3.0
+
+### Minor Changes
+
+- fix
+
+### Patch Changes
+
+- Updated dependencies
+  - @contractspec/lib.lifecycle@0.2.0
+
+## 0.2.2
+
+### Patch Changes
+
+- fix dependencies
+- Updated dependencies
+  - @contractspec/lib.lifecycle@0.1.2
+
+## 0.2.1
+
+### Patch Changes
+
+- fix
+- Updated dependencies
+  - @contractspec/lib.lifecycle@0.1.1
+
+## 0.2.0
+
+### Minor Changes
+
+- b1d0876: Managed platform
+
+### Patch Changes
+
+- Updated dependencies [b1d0876]
+  - @contractspec/lib.lifecycle@0.1.0
+
+## 0.1.0
+
+### Minor Changes
+
+- f1f4ddd: Foundation Hardening
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release
+- OpenTelemetry tracing integration
+- Metrics collection (counters, histograms)
+- Structured logging with trace correlation
+- HTTP tracing middleware

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @contractspec/lib.observability
+
+Website: https://contractspec.io/
+
+
+OpenTelemetry integration for tracing, metrics, and structured logging.
+
+## Features
+
+- **Distributed Tracing**: Automatic span creation and propagation
+- **Metrics**: Counters, histograms, and gauges
+- **Structured Logging**: JSON logs with trace correlation
+
+## Installation
+
+```bash
+npm install @contractspec/lib.observability @opentelemetry/api
+```
+
+## Quick Start
+
+### Tracing
+
+```typescript
+import { traceAsync } from '@contractspec/lib.observability/tracing';
+
+await traceAsync('process_order', async (span) => {
+  span.setAttribute('order_id', order.id);
+  await db.save(order);
+});
+```
+
+### Metrics
+
+```typescript
+import { createCounter } from '@contractspec/lib.observability/metrics';
+
+const ordersCounter = createCounter('orders_total');
+ordersCounter.add(1, { status: 'success' });
+```
+
+### Middleware
+
+```typescript
+import { createTracingMiddleware } from '@contractspec/lib.observability/tracing/middleware';
+
+app.use(createTracingMiddleware());
+```
+
+## Documentation
+
+Full docs: https://contractspec.io/docs/libraries/observability
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

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

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

package/dist/anomaly/alert-manager.mjs

@@ -0,0 +1,23 @@
+//#region src/anomaly/alert-manager.ts
+var AlertManager = class {
+	cooldownMs;
+	lastAlert = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+		this.cooldownMs = options.cooldownMs ?? 6e4;
+	}
+	async notify(signal, analysis) {
+		const key = `${signal.type}:${analysis.culprit?.id ?? "none"}`;
+		const now = Date.now();
+		if (now - (this.lastAlert.get(key) ?? 0) < this.cooldownMs) return;
+		await this.options.transport({
+			signal,
+			analysis
+		});
+		this.lastAlert.set(key, now);
+	}
+};
+
+//#endregion
+export { AlertManager };
+//# sourceMappingURL=alert-manager.mjs.map

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

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

package/dist/anomaly/anomaly-detector.mjs

@@ -0,0 +1,58 @@
+import { BaselineCalculator } from "./baseline-calculator.mjs";
+
+//#region src/anomaly/anomaly-detector.ts
+var AnomalyDetector = class {
+	baseline;
+	thresholds = {
+		errorRateDelta: .5,
+		latencyDelta: .35,
+		throughputDrop: .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;
+	}
+};
+
+//#endregion
+export { AnomalyDetector };
+//# sourceMappingURL=anomaly-detector.mjs.map

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

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

package/dist/anomaly/baseline-calculator.mjs

@@ -0,0 +1,37 @@
+//#region src/anomaly/baseline-calculator.ts
+var BaselineCalculator = class {
+	snapshot = {
+		latencyP99: 0,
+		latencyP95: 0,
+		errorRate: 0,
+		throughput: 0,
+		sampleCount: 0
+	};
+	constructor(alpha = .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;
+	}
+};
+
+//#endregion
+export { BaselineCalculator };
+//# sourceMappingURL=baseline-calculator.mjs.map

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

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

package/dist/anomaly/root-cause-analyzer.mjs

@@ -0,0 +1,27 @@
+//#region src/anomaly/root-cause-analyzer.ts
+var RootCauseAnalyzer = class {
+	constructor(lookbackMs = 900 * 1e3) {
+		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
+		};
+	}
+};
+
+//#endregion
+export { RootCauseAnalyzer };
+//# sourceMappingURL=root-cause-analyzer.mjs.map