@contractspec/lib.observability 3.0.0 → 3.1.1

package/AGENTS.md

@@ -0,0 +1,34 @@
+# AI Agent Guide — `@contractspec/lib.observability`
+
+Scope: `packages/libs/observability/*`
+
+OpenTelemetry-based observability primitives. Provides tracing, metrics, logging, and anomaly detection for contract-driven systems.
+
+## Quick Context
+
+- **Layer**: lib
+- **Consumers**: evolution, progressive-delivery, bundles
+
+## Public Exports
+
+- `.` — main entry
+- `./anomaly/*` — anomaly detection sub-modules
+- `./intent/*` — intent tracking sub-modules
+- `./logging` — structured logging integration
+- `./metrics` — metric collection helpers
+- `./pipeline/*` — telemetry pipeline interfaces
+- `./telemetry/*` — telemetry primitives
+- `./tracing` — distributed tracing helpers
+
+## Guardrails
+
+- OTel span and metric naming conventions must stay consistent across the platform
+- Pipeline interfaces are adapter boundaries — do not leak vendor-specific details
+- Anomaly detection thresholds affect alerting; changes require validation
+
+## Local Commands
+
+- Build: `bun run build`
+- Test: `bun test`
+- Lint: `bun run lint`
+- Dev: `bun run dev`

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @contractspec/lib.observability
 
+## 3.1.1
+
+### Patch Changes
+
+- Updated dependencies [02c0cc5]
+  - @contractspec/lib.contracts-integrations@3.1.1
+  - @contractspec/lib.contracts-spec@3.1.1
+  - @contractspec/lib.lifecycle@3.1.1
+
+## 3.1.0
+
+### Minor Changes
+
+- 28987eb: chore: upgrade dependencies
+
+### Patch Changes
+
+- Updated dependencies [f2a4faf]
+- Updated dependencies [28987eb]
+- Updated dependencies [28987eb]
+  - @contractspec/lib.contracts-spec@3.1.0
+  - @contractspec/lib.contracts-integrations@3.1.0
+  - @contractspec/lib.lifecycle@3.1.0
+
 ## 3.0.0
 
 ### Major Changes

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { getTracer, traceAsync, traceSync } from './tracing';
+export { traceModelSelection, type ModelSelectionSpanInput, type ModelSelectionSpanAttributes, } from './tracing/model-selection.span';
+export { ModelSelectionTelemetry, type ModelSelectionEventProperties, } from './telemetry/model-selection-telemetry';
 export { getMeter, createCounter, createUpDownCounter, createHistogram, standardMetrics, } from './metrics';
 export { Logger, logger } from './logging';
 export { createTracingMiddleware, type TracingMiddlewareOptions, } from './tracing/middleware';

package/dist/index.js

@@ -196,6 +196,56 @@ function traceSync(name, fn, tracerName) {
   });
 }
 
+// src/tracing/model-selection.span.ts
+async function traceModelSelection(fn, input) {
+  const startMs = performance.now();
+  return traceAsync("model.selection", async (span) => {
+    const result = await fn();
+    const durationMs = performance.now() - startMs;
+    span.setAttribute("model.selected", input.modelId);
+    span.setAttribute("model.provider", input.providerKey);
+    span.setAttribute("model.score", input.score);
+    span.setAttribute("model.alternatives_count", input.alternativesCount);
+    span.setAttribute("model.selection_duration_ms", durationMs);
+    span.setAttribute("model.reason", input.reason);
+    if (input.dimension) {
+      span.setAttribute("model.dimension", input.dimension);
+    }
+    if (input.constraints) {
+      span.setAttribute("model.constraints", JSON.stringify(input.constraints));
+    }
+    return result;
+  });
+}
+
+// src/telemetry/model-selection-telemetry.ts
+class ModelSelectionTelemetry {
+  provider;
+  eventName;
+  constructor(provider, options) {
+    this.provider = provider;
+    this.eventName = options?.eventName ?? "$model_selection";
+  }
+  async trackSelection(distinctId, properties) {
+    await this.provider.capture({
+      distinctId,
+      event: this.eventName,
+      timestamp: new Date,
+      properties: {
+        $model_id: properties.modelId,
+        $model_provider: properties.providerKey,
+        $model_score: properties.score,
+        $model_dimension: properties.dimension ?? null,
+        $model_reason: properties.reason,
+        $model_alternatives_count: properties.alternativesCount,
+        $model_cost_estimate_input: properties.costEstimateInput ?? null,
+        $model_cost_estimate_output: properties.costEstimateOutput ?? null,
+        $model_selection_duration_ms: properties.selectionDurationMs ?? null
+      }
+    });
+  }
+}
+
 // src/metrics/index.ts
 import {
   metrics
@@ -1055,6 +1105,7 @@ function isRecord(value) {
 }
 export {
   traceSync,
+  traceModelSelection,
   traceAsync,
   standardMetrics,
   logger,
@@ -1067,6 +1118,7 @@ export {
   RootCauseAnalyzer,
   PosthogTelemetryProvider,
   PosthogBaselineReader,
+  ModelSelectionTelemetry,
   Logger,
   LifecycleKpiPipeline,
   IntentDetector,

package/dist/node/index.js

@@ -195,6 +195,56 @@ function traceSync(name, fn, tracerName) {
   });
 }
 
+// src/tracing/model-selection.span.ts
+async function traceModelSelection(fn, input) {
+  const startMs = performance.now();
+  return traceAsync("model.selection", async (span) => {
+    const result = await fn();
+    const durationMs = performance.now() - startMs;
+    span.setAttribute("model.selected", input.modelId);
+    span.setAttribute("model.provider", input.providerKey);
+    span.setAttribute("model.score", input.score);
+    span.setAttribute("model.alternatives_count", input.alternativesCount);
+    span.setAttribute("model.selection_duration_ms", durationMs);
+    span.setAttribute("model.reason", input.reason);
+    if (input.dimension) {
+      span.setAttribute("model.dimension", input.dimension);
+    }
+    if (input.constraints) {
+      span.setAttribute("model.constraints", JSON.stringify(input.constraints));
+    }
+    return result;
+  });
+}
+
+// src/telemetry/model-selection-telemetry.ts
+class ModelSelectionTelemetry {
+  provider;
+  eventName;
+  constructor(provider, options) {
+    this.provider = provider;
+    this.eventName = options?.eventName ?? "$model_selection";
+  }
+  async trackSelection(distinctId, properties) {
+    await this.provider.capture({
+      distinctId,
+      event: this.eventName,
+      timestamp: new Date,
+      properties: {
+        $model_id: properties.modelId,
+        $model_provider: properties.providerKey,
+        $model_score: properties.score,
+        $model_dimension: properties.dimension ?? null,
+        $model_reason: properties.reason,
+        $model_alternatives_count: properties.alternativesCount,
+        $model_cost_estimate_input: properties.costEstimateInput ?? null,
+        $model_cost_estimate_output: properties.costEstimateOutput ?? null,
+        $model_selection_duration_ms: properties.selectionDurationMs ?? null
+      }
+    });
+  }
+}
+
 // src/metrics/index.ts
 import {
   metrics
@@ -1054,6 +1104,7 @@ function isRecord(value) {
 }
 export {
   traceSync,
+  traceModelSelection,
   traceAsync,
   standardMetrics,
   logger,
@@ -1066,6 +1117,7 @@ export {
   RootCauseAnalyzer,
   PosthogTelemetryProvider,
   PosthogBaselineReader,
+  ModelSelectionTelemetry,
   Logger,
   LifecycleKpiPipeline,
   IntentDetector,

package/dist/node/telemetry/model-selection-telemetry.js

@@ -0,0 +1,30 @@
+// src/telemetry/model-selection-telemetry.ts
+class ModelSelectionTelemetry {
+  provider;
+  eventName;
+  constructor(provider, options) {
+    this.provider = provider;
+    this.eventName = options?.eventName ?? "$model_selection";
+  }
+  async trackSelection(distinctId, properties) {
+    await this.provider.capture({
+      distinctId,
+      event: this.eventName,
+      timestamp: new Date,
+      properties: {
+        $model_id: properties.modelId,
+        $model_provider: properties.providerKey,
+        $model_score: properties.score,
+        $model_dimension: properties.dimension ?? null,
+        $model_reason: properties.reason,
+        $model_alternatives_count: properties.alternativesCount,
+        $model_cost_estimate_input: properties.costEstimateInput ?? null,
+        $model_cost_estimate_output: properties.costEstimateOutput ?? null,
+        $model_selection_duration_ms: properties.selectionDurationMs ?? null
+      }
+    });
+  }
+}
+export {
+  ModelSelectionTelemetry
+};

package/dist/node/tracing/middleware.js

@@ -46,6 +46,28 @@ function traceSync(name, fn, tracerName) {
   });
 }
 
+// src/tracing/model-selection.span.ts
+async function traceModelSelection(fn, input) {
+  const startMs = performance.now();
+  return traceAsync("model.selection", async (span) => {
+    const result = await fn();
+    const durationMs = performance.now() - startMs;
+    span.setAttribute("model.selected", input.modelId);
+    span.setAttribute("model.provider", input.providerKey);
+    span.setAttribute("model.score", input.score);
+    span.setAttribute("model.alternatives_count", input.alternativesCount);
+    span.setAttribute("model.selection_duration_ms", durationMs);
+    span.setAttribute("model.reason", input.reason);
+    if (input.dimension) {
+      span.setAttribute("model.dimension", input.dimension);
+    }
+    if (input.constraints) {
+      span.setAttribute("model.constraints", JSON.stringify(input.constraints));
+    }
+    return result;
+  });
+}
+
 // src/metrics/index.ts
 import {
   metrics

package/dist/node/tracing/{index.js → model-selection.span.js}

@@ -45,8 +45,28 @@ function traceSync(name, fn, tracerName) {
     }
   });
 }
+
+// src/tracing/model-selection.span.ts
+async function traceModelSelection(fn, input) {
+  const startMs = performance.now();
+  return traceAsync("model.selection", async (span) => {
+    const result = await fn();
+    const durationMs = performance.now() - startMs;
+    span.setAttribute("model.selected", input.modelId);
+    span.setAttribute("model.provider", input.providerKey);
+    span.setAttribute("model.score", input.score);
+    span.setAttribute("model.alternatives_count", input.alternativesCount);
+    span.setAttribute("model.selection_duration_ms", durationMs);
+    span.setAttribute("model.reason", input.reason);
+    if (input.dimension) {
+      span.setAttribute("model.dimension", input.dimension);
+    }
+    if (input.constraints) {
+      span.setAttribute("model.constraints", JSON.stringify(input.constraints));
+    }
+    return result;
+  });
+}
 export {
-  traceSync,
-  traceAsync,
-  getTracer
+  traceModelSelection
 };

package/dist/telemetry/model-selection-telemetry.d.ts

@@ -0,0 +1,26 @@
+import type { AnalyticsProvider } from '@contractspec/lib.contracts-integrations';
+export interface ModelSelectionEventProperties {
+    modelId: string;
+    providerKey: string;
+    score: number;
+    dimension?: string;
+    reason: string;
+    alternativesCount: number;
+    costEstimateInput?: number;
+    costEstimateOutput?: number;
+    selectionDurationMs?: number;
+}
+/**
+ * Track model selection decisions via PostHog analytics.
+ *
+ * Captures a `$model_selection` event with the selection result properties,
+ * enabling analytics dashboards for model usage patterns and cost tracking.
+ */
+export declare class ModelSelectionTelemetry {
+    private readonly provider;
+    private readonly eventName;
+    constructor(provider: AnalyticsProvider, options?: {
+        eventName?: string;
+    });
+    trackSelection(distinctId: string, properties: ModelSelectionEventProperties): Promise<void>;
+}

package/dist/telemetry/model-selection-telemetry.js

@@ -0,0 +1,31 @@
+// @bun
+// src/telemetry/model-selection-telemetry.ts
+class ModelSelectionTelemetry {
+  provider;
+  eventName;
+  constructor(provider, options) {
+    this.provider = provider;
+    this.eventName = options?.eventName ?? "$model_selection";
+  }
+  async trackSelection(distinctId, properties) {
+    await this.provider.capture({
+      distinctId,
+      event: this.eventName,
+      timestamp: new Date,
+      properties: {
+        $model_id: properties.modelId,
+        $model_provider: properties.providerKey,
+        $model_score: properties.score,
+        $model_dimension: properties.dimension ?? null,
+        $model_reason: properties.reason,
+        $model_alternatives_count: properties.alternativesCount,
+        $model_cost_estimate_input: properties.costEstimateInput ?? null,
+        $model_cost_estimate_output: properties.costEstimateOutput ?? null,
+        $model_selection_duration_ms: properties.selectionDurationMs ?? null
+      }
+    });
+  }
+}
+export {
+  ModelSelectionTelemetry
+};

package/dist/tracing/index.d.ts

@@ -1,4 +1,5 @@
 import { type Span, type Tracer } from '@opentelemetry/api';
+export * from './model-selection.span';
 export declare function getTracer(name?: string): Tracer;
 export declare function traceAsync<T>(name: string, fn: (span: Span) => Promise<T>, tracerName?: string): Promise<T>;
 export declare function traceSync<T>(name: string, fn: (span: Span) => T, tracerName?: string): T;

package/dist/tracing/middleware.js

@@ -47,6 +47,28 @@ function traceSync(name, fn, tracerName) {
   });
 }
 
+// src/tracing/model-selection.span.ts
+async function traceModelSelection(fn, input) {
+  const startMs = performance.now();
+  return traceAsync("model.selection", async (span) => {
+    const result = await fn();
+    const durationMs = performance.now() - startMs;
+    span.setAttribute("model.selected", input.modelId);
+    span.setAttribute("model.provider", input.providerKey);
+    span.setAttribute("model.score", input.score);
+    span.setAttribute("model.alternatives_count", input.alternativesCount);
+    span.setAttribute("model.selection_duration_ms", durationMs);
+    span.setAttribute("model.reason", input.reason);
+    if (input.dimension) {
+      span.setAttribute("model.dimension", input.dimension);
+    }
+    if (input.constraints) {
+      span.setAttribute("model.constraints", JSON.stringify(input.constraints));
+    }
+    return result;
+  });
+}
+
 // src/metrics/index.ts
 import {
   metrics

package/dist/tracing/model-selection.span.d.ts

@@ -0,0 +1,26 @@
+export interface ModelSelectionSpanAttributes {
+    'model.selected': string;
+    'model.provider': string;
+    'model.score': number;
+    'model.dimension'?: string;
+    'model.alternatives_count': number;
+    'model.constraints'?: string;
+    'model.selection_duration_ms': number;
+    'model.reason': string;
+}
+export interface ModelSelectionSpanInput {
+    modelId: string;
+    providerKey: string;
+    score: number;
+    dimension?: string;
+    alternativesCount: number;
+    constraints?: Record<string, unknown>;
+    reason: string;
+}
+/**
+ * Trace a model selection decision as an OpenTelemetry span.
+ *
+ * Wraps an async operation (typically the selector call) and records
+ * the selection result as span attributes for distributed tracing.
+ */
+export declare function traceModelSelection<T>(fn: () => Promise<T>, input: ModelSelectionSpanInput): Promise<T>;

package/dist/tracing/{index.js → model-selection.span.js}

@@ -46,8 +46,28 @@ function traceSync(name, fn, tracerName) {
     }
   });
 }
+
+// src/tracing/model-selection.span.ts
+async function traceModelSelection(fn, input) {
+  const startMs = performance.now();
+  return traceAsync("model.selection", async (span) => {
+    const result = await fn();
+    const durationMs = performance.now() - startMs;
+    span.setAttribute("model.selected", input.modelId);
+    span.setAttribute("model.provider", input.providerKey);
+    span.setAttribute("model.score", input.score);
+    span.setAttribute("model.alternatives_count", input.alternativesCount);
+    span.setAttribute("model.selection_duration_ms", durationMs);
+    span.setAttribute("model.reason", input.reason);
+    if (input.dimension) {
+      span.setAttribute("model.dimension", input.dimension);
+    }
+    if (input.constraints) {
+      span.setAttribute("model.constraints", JSON.stringify(input.constraints));
+    }
+    return result;
+  });
+}
 export {
-  traceSync,
-  traceAsync,
-  getTracer
+  traceModelSelection
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.observability",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "OpenTelemetry-based observability primitives",
   "keywords": [
     "contractspec",
@@ -27,17 +27,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.lifecycle": "3.0.0",
-    "@contractspec/lib.contracts-spec": "3.0.0",
-    "@contractspec/lib.contracts-integrations": "3.0.0"
+    "@contractspec/lib.lifecycle": "3.1.1",
+    "@contractspec/lib.contracts-spec": "3.1.1",
+    "@contractspec/lib.contracts-integrations": "3.1.1"
   },
   "peerDependencies": {
     "@opentelemetry/api": "*"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.0.0",
+    "@contractspec/tool.typescript": "3.1.0",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.0.0"
+    "@contractspec/tool.bun": "3.1.0"
   },
   "exports": {
     ".": {
@@ -118,6 +118,12 @@
       "node": "./dist/node/pipeline/lifecycle-pipeline.js",
       "default": "./dist/pipeline/lifecycle-pipeline.js"
     },
+    "./telemetry/model-selection-telemetry": {
+      "types": "./dist/telemetry/model-selection-telemetry.d.ts",
+      "bun": "./dist/telemetry/model-selection-telemetry.js",
+      "node": "./dist/node/telemetry/model-selection-telemetry.js",
+      "default": "./dist/telemetry/model-selection-telemetry.js"
+    },
     "./telemetry/posthog-baseline-reader": {
       "types": "./dist/telemetry/posthog-baseline-reader.d.ts",
       "bun": "./dist/telemetry/posthog-baseline-reader.js",
@@ -147,6 +153,12 @@
       "bun": "./dist/tracing/middleware.js",
       "node": "./dist/node/tracing/middleware.js",
       "default": "./dist/tracing/middleware.js"
+    },
+    "./tracing/model-selection.span": {
+      "types": "./dist/tracing/model-selection.span.d.ts",
+      "bun": "./dist/tracing/model-selection.span.js",
+      "node": "./dist/node/tracing/model-selection.span.js",
+      "default": "./dist/tracing/model-selection.span.js"
     }
   },
   "publishConfig": {
@@ -230,6 +242,12 @@
         "node": "./dist/node/pipeline/lifecycle-pipeline.js",
         "default": "./dist/pipeline/lifecycle-pipeline.js"
       },
+      "./telemetry/model-selection-telemetry": {
+        "types": "./dist/telemetry/model-selection-telemetry.d.ts",
+        "bun": "./dist/telemetry/model-selection-telemetry.js",
+        "node": "./dist/node/telemetry/model-selection-telemetry.js",
+        "default": "./dist/telemetry/model-selection-telemetry.js"
+      },
       "./telemetry/posthog-baseline-reader": {
         "types": "./dist/telemetry/posthog-baseline-reader.d.ts",
         "bun": "./dist/telemetry/posthog-baseline-reader.js",
@@ -259,6 +277,12 @@
         "bun": "./dist/tracing/middleware.js",
         "node": "./dist/node/tracing/middleware.js",
         "default": "./dist/tracing/middleware.js"
+      },
+      "./tracing/model-selection.span": {
+        "types": "./dist/tracing/model-selection.span.d.ts",
+        "bun": "./dist/tracing/model-selection.span.js",
+        "node": "./dist/node/tracing/model-selection.span.js",
+        "default": "./dist/tracing/model-selection.span.js"
       }
     },
     "registry": "https://registry.npmjs.org/"