@elsium-ai/observe 0.1.6

package/dist/index.js

@@ -0,0 +1,1082 @@
+// @bun
+// ../core/src/errors.ts
+class ElsiumError extends Error {
+  code;
+  provider;
+  model;
+  statusCode;
+  retryable;
+  retryAfterMs;
+  cause;
+  metadata;
+  constructor(details) {
+    super(details.message);
+    this.name = "ElsiumError";
+    this.code = details.code;
+    this.provider = details.provider;
+    this.model = details.model;
+    this.statusCode = details.statusCode;
+    this.retryable = details.retryable;
+    this.retryAfterMs = details.retryAfterMs;
+    this.cause = details.cause;
+    this.metadata = details.metadata;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      provider: this.provider,
+      model: this.model,
+      statusCode: this.statusCode,
+      retryable: this.retryable,
+      retryAfterMs: this.retryAfterMs,
+      metadata: this.metadata
+    };
+  }
+  static providerError(message, opts) {
+    return new ElsiumError({
+      code: "PROVIDER_ERROR",
+      message,
+      provider: opts.provider,
+      statusCode: opts.statusCode,
+      retryable: opts.retryable ?? false,
+      cause: opts.cause
+    });
+  }
+  static rateLimit(provider, retryAfterMs) {
+    return new ElsiumError({
+      code: "RATE_LIMIT",
+      message: `Rate limited by ${provider}`,
+      provider,
+      statusCode: 429,
+      retryable: true,
+      retryAfterMs
+    });
+  }
+  static authError(provider) {
+    return new ElsiumError({
+      code: "AUTH_ERROR",
+      message: `Authentication failed for ${provider}. Check your API key.`,
+      provider,
+      statusCode: 401,
+      retryable: false
+    });
+  }
+  static timeout(provider, timeoutMs) {
+    return new ElsiumError({
+      code: "TIMEOUT",
+      message: `Request to ${provider} timed out after ${timeoutMs}ms`,
+      provider,
+      retryable: true
+    });
+  }
+  static validation(message, metadata) {
+    return new ElsiumError({
+      code: "VALIDATION_ERROR",
+      message,
+      retryable: false,
+      metadata
+    });
+  }
+  static budgetExceeded(spent, budget) {
+    return new ElsiumError({
+      code: "BUDGET_EXCEEDED",
+      message: `Token budget exceeded: spent ${spent}, budget ${budget}`,
+      retryable: false,
+      metadata: { spent, budget }
+    });
+  }
+}
+// ../core/src/utils.ts
+import { randomBytes } from "crypto";
+function cryptoHex(bytes) {
+  return randomBytes(bytes).toString("hex");
+}
+function generateId(prefix = "els") {
+  const timestamp = Date.now().toString(36);
+  const random = cryptoHex(4);
+  return `${prefix}_${timestamp}_${random}`;
+}
+// ../core/src/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+function createLogger(options = {}) {
+  const { level = "info", pretty = false, context = {} } = options;
+  const minLevel = LOG_LEVELS[level];
+  function log(logLevel, message, data) {
+    if (LOG_LEVELS[logLevel] < minLevel)
+      return;
+    const entry = {
+      ...context,
+      level: logLevel,
+      message,
+      timestamp: new Date().toISOString(),
+      ...data ? { data } : {}
+    };
+    const output = pretty ? JSON.stringify(entry, null, 2) : JSON.stringify(entry);
+    if (logLevel === "error") {
+      console.error(output);
+    } else if (logLevel === "warn") {
+      console.warn(output);
+    } else {
+      console.log(output);
+    }
+  }
+  return {
+    debug: (msg, data) => log("debug", msg, data),
+    info: (msg, data) => log("info", msg, data),
+    warn: (msg, data) => log("warn", msg, data),
+    error: (msg, data) => log("error", msg, data),
+    child(childContext) {
+      return createLogger({
+        level,
+        pretty,
+        context: { ...context, ...childContext }
+      });
+    }
+  };
+}
+// src/span.ts
+function createSpan(name, options = {}) {
+  const id = generateId("spn");
+  const traceId = options.traceId ?? generateId("trc");
+  const kind = options.kind ?? "custom";
+  const startTime = Date.now();
+  const metadata = {};
+  const events = [];
+  let status = "running";
+  let endTime;
+  const span = {
+    id,
+    traceId,
+    name,
+    kind,
+    addEvent(eventName, data) {
+      events.push({
+        name: eventName,
+        timestamp: Date.now(),
+        data
+      });
+    },
+    setMetadata(key, value) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype")
+        return;
+      metadata[key] = value;
+    },
+    end(result) {
+      if (endTime !== undefined)
+        return;
+      endTime = Date.now();
+      status = result?.status ?? "ok";
+      if (result?.metadata) {
+        for (const [key, value] of Object.entries(result.metadata)) {
+          if (key === "__proto__" || key === "constructor" || key === "prototype")
+            continue;
+          metadata[key] = value;
+        }
+      }
+      options.onEnd?.(span.toJSON());
+    },
+    child(childName, childKind) {
+      return createSpan(childName, {
+        traceId,
+        parentId: id,
+        kind: childKind ?? kind,
+        onEnd: options.onEnd
+      });
+    },
+    toJSON() {
+      const duration = endTime !== undefined ? endTime - startTime : undefined;
+      return {
+        id,
+        traceId,
+        parentId: options.parentId,
+        name,
+        kind,
+        status,
+        startTime,
+        endTime,
+        durationMs: duration !== undefined ? Math.round(duration) : undefined,
+        metadata,
+        events
+      };
+    }
+  };
+  return span;
+}
+// src/cost-engine.ts
+function registerModelTier(model, entry) {
+  MODEL_TIERS[model] = entry;
+}
+var MODEL_TIERS = {
+  "gpt-5-nano": { tier: "low", costPerMToken: 0.05 },
+  "gemini-2.0-flash-lite": { tier: "low", costPerMToken: 0.075 },
+  "gemini-2.0-flash": { tier: "low", costPerMToken: 0.1 },
+  "gpt-4.1-nano": { tier: "low", costPerMToken: 0.1 },
+  "gpt-4o-mini": { tier: "low", costPerMToken: 0.15 },
+  "gpt-5-mini": { tier: "low", costPerMToken: 0.25 },
+  "gpt-4.1-mini": { tier: "low", costPerMToken: 0.4 },
+  "claude-haiku-4-5-20251001": { tier: "low", costPerMToken: 1 },
+  "o3-mini": { tier: "mid", costPerMToken: 1.1 },
+  "o1-mini": { tier: "mid", costPerMToken: 1.1 },
+  "o4-mini": { tier: "mid", costPerMToken: 1.1 },
+  "gpt-5": { tier: "mid", costPerMToken: 1.25 },
+  "gemini-2.5-pro-preview-05-06": { tier: "mid", costPerMToken: 1.25 },
+  o3: { tier: "mid", costPerMToken: 2 },
+  "gpt-4.1": { tier: "mid", costPerMToken: 2 },
+  "gpt-4o": { tier: "mid", costPerMToken: 2.5 },
+  "claude-sonnet-4-6": { tier: "mid", costPerMToken: 3 },
+  "claude-opus-4-6": { tier: "high", costPerMToken: 15 },
+  o1: { tier: "high", costPerMToken: 15 },
+  "o3-pro": { tier: "high", costPerMToken: 20 }
+};
+function createDimension() {
+  return { totalCost: 0, totalTokens: 0, callCount: 0, firstCallAt: 0, lastCallAt: 0 };
+}
+function updateDimension(dim, cost, tokens) {
+  const now = Date.now();
+  dim.totalCost += cost;
+  dim.totalTokens += tokens;
+  dim.callCount++;
+  if (dim.firstCallAt === 0)
+    dim.firstCallAt = now;
+  dim.lastCallAt = now;
+}
+function createCostEngine(config = {}) {
+  const byModel = {};
+  const byAgent = {};
+  const byUser = {};
+  const byFeature = {};
+  let totalSpend = 0;
+  let totalTokens = 0;
+  let pendingSpend = 0;
+  let totalCalls = 0;
+  const startedAt = Date.now();
+  const alerts = [];
+  const recentCalls = [];
+  const alertedThresholds = new Set;
+  const maxAlerts = 1000;
+  function emitAlert(alert) {
+    alerts.push(alert);
+    if (alerts.length > maxAlerts)
+      alerts.shift();
+    config.onAlert?.(alert);
+  }
+  function checkDailyBudget() {
+    if (!config.dailyBudget)
+      return;
+    const elapsedMs = Date.now() - startedAt;
+    const elapsedDays = Math.max(elapsedMs / (24 * 60 * 60 * 1000), 1 / 24);
+    const dailyRate = totalSpend / elapsedDays;
+    if (dailyRate <= config.dailyBudget)
+      return;
+    const key = `daily:${Math.floor(Date.now() / (60 * 60 * 1000))}`;
+    if (alertedThresholds.has(key))
+      return;
+    alertedThresholds.add(key);
+    emitAlert({
+      type: "budget_exceeded",
+      dimension: "daily",
+      currentValue: dailyRate,
+      limit: config.dailyBudget,
+      message: `Daily spend rate $${dailyRate.toFixed(4)} exceeds budget $${config.dailyBudget}`,
+      timestamp: Date.now()
+    });
+  }
+  function checkDimensionBudget(limit, dimensionKey, store) {
+    if (!limit || !dimensionKey)
+      return;
+    const dim = store[dimensionKey];
+    if (dim && dim.totalCost > limit) {
+      throw ElsiumError.budgetExceeded(dim.totalCost, limit);
+    }
+  }
+  function emitThresholdAlertIfNew(threshold, budget) {
+    const thresholdAmount = budget * threshold;
+    if (totalSpend < thresholdAmount)
+      return;
+    const key = `threshold:${threshold}`;
+    if (alertedThresholds.has(key))
+      return;
+    alertedThresholds.add(key);
+    emitAlert({
+      type: "threshold",
+      dimension: "total",
+      currentValue: totalSpend,
+      limit: thresholdAmount,
+      message: `Spend reached ${(threshold * 100).toFixed(0)}% of budget ($${totalSpend.toFixed(4)} / $${budget})`,
+      timestamp: Date.now()
+    });
+  }
+  function checkAlertThresholds() {
+    if (!config.alertThresholds || !config.totalBudget)
+      return;
+    for (const threshold of config.alertThresholds) {
+      emitThresholdAlertIfNew(threshold, config.totalBudget);
+    }
+  }
+  function checkBudgets(dimensions) {
+    if (config.totalBudget && totalSpend > config.totalBudget) {
+      throw ElsiumError.budgetExceeded(totalSpend, config.totalBudget);
+    }
+    checkDailyBudget();
+    checkDimensionBudget(config.perAgent, dimensions.agent, byAgent);
+    checkDimensionBudget(config.perUser, dimensions.user, byUser);
+    checkDimensionBudget(config.perFeature, dimensions.feature, byFeature);
+    checkAlertThresholds();
+  }
+  function checkLoopDetection() {
+    if (!config.loopDetection)
+      return;
+    const now = Date.now();
+    const oneMinuteAgo = now - 60000;
+    while (recentCalls.length > 0 && recentCalls[0].timestamp < oneMinuteAgo) {
+      recentCalls.shift();
+    }
+    if (config.loopDetection.maxCallsPerMinute && recentCalls.length > config.loopDetection.maxCallsPerMinute) {
+      emitAlert({
+        type: "loop_detected",
+        dimension: "calls_per_minute",
+        currentValue: recentCalls.length,
+        limit: config.loopDetection.maxCallsPerMinute,
+        message: `Loop detected: ${recentCalls.length} calls in last minute (max: ${config.loopDetection.maxCallsPerMinute})`,
+        timestamp: now
+      });
+    }
+    if (config.loopDetection.maxCostPerMinute) {
+      const recentCost = recentCalls.reduce((sum, r) => sum + r.cost, 0);
+      if (recentCost > config.loopDetection.maxCostPerMinute) {
+        emitAlert({
+          type: "loop_detected",
+          dimension: "cost_per_minute",
+          currentValue: recentCost,
+          limit: config.loopDetection.maxCostPerMinute,
+          message: `Cost loop detected: $${recentCost.toFixed(4)} in last minute (max: $${config.loopDetection.maxCostPerMinute})`,
+          timestamp: now
+        });
+      }
+    }
+  }
+  function trackDimension(store, key, cost, tokens) {
+    if (!key)
+      return;
+    if (!store[key])
+      store[key] = createDimension();
+    updateDimension(store[key], cost, tokens);
+  }
+  function trackCall(response, dimensions = {}) {
+    const cost = response.cost.totalCost;
+    const tokens = response.usage.totalTokens;
+    totalSpend += cost;
+    totalTokens += tokens;
+    totalCalls++;
+    trackDimension(byModel, response.model, cost, tokens);
+    trackDimension(byAgent, dimensions.agent, cost, tokens);
+    trackDimension(byUser, dimensions.user, cost, tokens);
+    trackDimension(byFeature, dimensions.feature, cost, tokens);
+    recentCalls.push({ timestamp: Date.now(), cost, model: response.model, tokens });
+    checkLoopDetection();
+    checkBudgets(dimensions);
+  }
+  return {
+    middleware() {
+      return async (ctx, next) => {
+        const agent = ctx.metadata.agentName;
+        const user = ctx.metadata.userId;
+        const feature = ctx.metadata.feature;
+        let reserved = 0;
+        if (config.totalBudget) {
+          const inputText = ctx.request.messages.map((m) => typeof m.content === "string" ? m.content : "").join("");
+          const estimatedTokens = Math.ceil(inputText.length / 4);
+          const modelTier = MODEL_TIERS[ctx.model];
+          if (modelTier) {
+            const estimatedCost = estimatedTokens / 1e6 * modelTier.costPerMToken;
+            if (totalSpend + pendingSpend + estimatedCost > config.totalBudget) {
+              throw ElsiumError.validation("Budget would be exceeded");
+            }
+            reserved = estimatedCost;
+            pendingSpend += reserved;
+          }
+        }
+        try {
+          const response = await next(ctx);
+          pendingSpend -= reserved;
+          trackCall(response, { agent, user, feature });
+          return response;
+        } catch (error) {
+          pendingSpend -= reserved;
+          throw error;
+        }
+      };
+    },
+    trackCall,
+    getReport() {
+      const elapsedMs = Math.max(Date.now() - startedAt, 1);
+      const elapsedHours = elapsedMs / (60 * 60 * 1000);
+      const projectedDailySpend = totalCalls > 0 ? totalSpend / elapsedHours * 24 : 0;
+      const projectedMonthlySpend = projectedDailySpend * 30;
+      const recommendations = [];
+      for (const [model, dim] of Object.entries(byModel)) {
+        const tier = MODEL_TIERS[model];
+        if (tier?.tier === "high" && dim.callCount > 10) {
+          recommendations.push(`Consider using a mid-tier model instead of ${model} for routine tasks. ${dim.callCount} calls at $${dim.totalCost.toFixed(4)} total.`);
+        }
+      }
+      if (config.totalBudget && projectedMonthlySpend > config.totalBudget * 1.2) {
+        recommendations.push(`Projected monthly spend ($${projectedMonthlySpend.toFixed(2)}) exceeds budget by ${((projectedMonthlySpend / config.totalBudget - 1) * 100).toFixed(0)}%.`);
+      }
+      if (totalCalls > 50 && totalTokens / totalCalls < 100) {
+        recommendations.push("Average token count per call is very low. Consider batching requests to reduce overhead.");
+      }
+      return {
+        totalSpend,
+        totalTokens,
+        totalCalls,
+        projectedDailySpend,
+        projectedMonthlySpend,
+        byModel: { ...byModel },
+        byAgent: { ...byAgent },
+        byUser: { ...byUser },
+        byFeature: { ...byFeature },
+        recommendations,
+        alerts: [...alerts]
+      };
+    },
+    suggestModel(currentModel, inputTokens) {
+      const current = MODEL_TIERS[currentModel];
+      if (!current || current.tier === "low")
+        return null;
+      const cheaper = Object.entries(MODEL_TIERS).filter(([, info]) => {
+        if (current.tier === "high")
+          return info.tier === "mid" || info.tier === "low";
+        if (current.tier === "mid")
+          return info.tier === "low";
+        return false;
+      }).sort((a, b) => a[1].costPerMToken - b[1].costPerMToken);
+      if (cheaper.length === 0)
+        return null;
+      const isSimple = inputTokens < 500;
+      const [suggestedModel, suggestedInfo] = cheaper[0];
+      if (!isSimple && current.tier !== "high")
+        return null;
+      const estimatedSavings = (current.costPerMToken - suggestedInfo.costPerMToken) / current.costPerMToken * 100;
+      return {
+        currentModel,
+        suggestedModel,
+        estimatedSavings,
+        reason: isSimple ? `Simple request (${inputTokens} tokens) could use a cheaper model` : `Consider ${suggestedModel} for routine tasks (${estimatedSavings.toFixed(0)}% savings)`
+      };
+    },
+    reset() {
+      for (const key of Object.keys(byModel))
+        delete byModel[key];
+      for (const key of Object.keys(byAgent))
+        delete byAgent[key];
+      for (const key of Object.keys(byUser))
+        delete byUser[key];
+      for (const key of Object.keys(byFeature))
+        delete byFeature[key];
+      totalSpend = 0;
+      totalTokens = 0;
+      pendingSpend = 0;
+      totalCalls = 0;
+      alerts.length = 0;
+      recentCalls.length = 0;
+      alertedThresholds.clear();
+    }
+  };
+}
+// src/tracer.ts
+var log = createLogger();
+function observe(config = {}) {
+  const {
+    output = ["console"],
+    costTracking = true,
+    samplingRate = 1,
+    maxSpans = 1e4
+  } = config;
+  const spans = [];
+  const llmCalls = [];
+  const exporters = [];
+  const handlers = [];
+  for (const out of output) {
+    if (out === "console") {
+      handlers.push(consoleHandler);
+    } else if (out === "json-file") {} else {
+      exporters.push(out);
+    }
+  }
+  function shouldSample() {
+    if (samplingRate >= 1)
+      return true;
+    return Math.random() < samplingRate;
+  }
+  function onSpanEnd(span) {
+    if (spans.length >= maxSpans) {
+      spans.shift();
+    }
+    spans.push(span);
+    for (const handler of handlers) {
+      handler(span);
+    }
+  }
+  return {
+    startSpan(name, kind) {
+      if (!shouldSample()) {
+        return createNoopSpan(name, kind);
+      }
+      return createSpan(name, { kind, onEnd: onSpanEnd });
+    },
+    getSpans() {
+      return [...spans];
+    },
+    getCostReport() {
+      const byModel = {};
+      for (const call of llmCalls) {
+        if (!byModel[call.model]) {
+          byModel[call.model] = { cost: 0, tokens: 0, calls: 0 };
+        }
+        byModel[call.model].cost += call.cost;
+        byModel[call.model].tokens += call.inputTokens + call.outputTokens;
+        byModel[call.model].calls++;
+      }
+      return {
+        totalCost: llmCalls.reduce((sum, c) => sum + c.cost, 0),
+        totalTokens: llmCalls.reduce((sum, c) => sum + c.inputTokens + c.outputTokens, 0),
+        totalInputTokens: llmCalls.reduce((sum, c) => sum + c.inputTokens, 0),
+        totalOutputTokens: llmCalls.reduce((sum, c) => sum + c.outputTokens, 0),
+        callCount: llmCalls.length,
+        byModel
+      };
+    },
+    trackLLMCall(data) {
+      if (!costTracking)
+        return;
+      llmCalls.push(data);
+      if (llmCalls.length > maxSpans) {
+        llmCalls.shift();
+      }
+    },
+    reset() {
+      spans.length = 0;
+      llmCalls.length = 0;
+    },
+    async flush() {
+      for (const exporter of exporters) {
+        await exporter.export([...spans]);
+      }
+    }
+  };
+}
+function consoleHandler(span) {
+  const duration = span.durationMs !== undefined ? `${span.durationMs}ms` : "running";
+  const status = span.status === "error" ? "[ERROR]" : span.status === "ok" ? "[OK]" : "[...]";
+  log.info("span", {
+    trace: span.traceId,
+    span: span.name,
+    kind: span.kind,
+    status,
+    duration,
+    ...Object.keys(span.metadata).length > 0 ? { metadata: span.metadata } : {}
+  });
+}
+function createNoopSpan(name, kind) {
+  const id = generateId("spn");
+  const traceId = generateId("trc");
+  return {
+    id,
+    traceId,
+    name,
+    kind: kind ?? "custom",
+    addEvent() {},
+    setMetadata() {},
+    end() {},
+    child(childName, childKind) {
+      return createNoopSpan(childName, childKind);
+    },
+    toJSON() {
+      return {
+        id,
+        traceId,
+        name,
+        kind: kind ?? "custom",
+        status: "ok",
+        startTime: 0,
+        metadata: {},
+        events: []
+      };
+    }
+  };
+}
+// src/metrics.ts
+function createMetrics(options) {
+  const maxEntries = options?.maxEntries ?? 50000;
+  const entries = [];
+  const counters = new Map;
+  const gauges = new Map;
+  function tagKey(name, tags) {
+    if (!tags || Object.keys(tags).length === 0)
+      return name;
+    const sorted = Object.entries(tags).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(",");
+    return `${name}{${sorted}}`;
+  }
+  return {
+    increment(name, value = 1, tags) {
+      const key = tagKey(name, tags);
+      const current = counters.get(key) ?? 0;
+      counters.set(key, current + value);
+      entries.push({
+        name,
+        type: "counter",
+        value: current + value,
+        tags: tags ?? {},
+        timestamp: Date.now()
+      });
+      if (entries.length > maxEntries)
+        entries.shift();
+    },
+    gauge(name, value, tags) {
+      const key = tagKey(name, tags);
+      gauges.set(key, value);
+      entries.push({
+        name,
+        type: "gauge",
+        value,
+        tags: tags ?? {},
+        timestamp: Date.now()
+      });
+      if (entries.length > maxEntries)
+        entries.shift();
+    },
+    histogram(name, value, tags) {
+      entries.push({
+        name,
+        type: "histogram",
+        value,
+        tags: tags ?? {},
+        timestamp: Date.now()
+      });
+      if (entries.length > maxEntries)
+        entries.shift();
+    },
+    getMetrics() {
+      return [...entries];
+    },
+    reset() {
+      entries.length = 0;
+      counters.clear();
+      gauges.clear();
+    }
+  };
+}
+// src/audit.ts
+import { createHash } from "crypto";
+function computeEventHash(event, previousHash) {
+  const content = JSON.stringify({
+    id: event.id,
+    sequenceId: event.sequenceId,
+    type: event.type,
+    timestamp: event.timestamp,
+    actor: event.actor,
+    traceId: event.traceId,
+    data: event.data,
+    previousHash
+  });
+  return createHash("sha256").update(content).digest("hex");
+}
+
+class InMemoryAuditStorage {
+  events = [];
+  maxEvents;
+  constructor(maxEvents) {
+    this.maxEvents = maxEvents ?? 1e4;
+  }
+  append(event) {
+    this.events.push(event);
+    if (this.events.length > this.maxEvents) {
+      this.events = this.events.slice(-this.maxEvents);
+    }
+  }
+  query(filter) {
+    let results = [...this.events];
+    if (filter.type) {
+      const types = Array.isArray(filter.type) ? filter.type : [filter.type];
+      results = results.filter((e) => types.includes(e.type));
+    }
+    if (filter.actor) {
+      results = results.filter((e) => e.actor === filter.actor);
+    }
+    if (filter.traceId) {
+      results = results.filter((e) => e.traceId === filter.traceId);
+    }
+    if (filter.fromTimestamp !== undefined) {
+      const from = filter.fromTimestamp;
+      results = results.filter((e) => e.timestamp >= from);
+    }
+    if (filter.toTimestamp !== undefined) {
+      const to = filter.toTimestamp;
+      results = results.filter((e) => e.timestamp <= to);
+    }
+    const offset = filter.offset ?? 0;
+    const limit = filter.limit ?? results.length;
+    return results.slice(offset, offset + limit);
+  }
+  count() {
+    return this.events.length;
+  }
+  verifyIntegrity() {
+    if (this.events.length === 0) {
+      return { valid: true, totalEvents: 0, chainComplete: true };
+    }
+    for (let i = 0;i < this.events.length; i++) {
+      const event = this.events[i];
+      const expectedHash = computeEventHash(event, event.previousHash);
+      if (event.hash !== expectedHash) {
+        return { valid: false, totalEvents: this.events.length, brokenAt: i };
+      }
+      if (i > 0 && event.previousHash !== this.events[i - 1].hash) {
+        return { valid: false, totalEvents: this.events.length, brokenAt: i };
+      }
+    }
+    const chainComplete = this.events[0].previousHash === "0".repeat(64);
+    return { valid: true, totalEvents: this.events.length, chainComplete };
+  }
+  getLastHash() {
+    if (this.events.length === 0)
+      return "0".repeat(64);
+    return this.events[this.events.length - 1].hash;
+  }
+}
+function createAuditTrail(config) {
+  const useHashChain = config?.hashChain !== false;
+  const storage = config?.storage && typeof config.storage !== "string" ? config.storage : new InMemoryAuditStorage(config?.maxEvents);
+  let sequenceId = 0;
+  let idCounter = 0;
+  let previousHash = "0".repeat(64);
+  if (useHashChain && storage.getLastHash) {
+    const lastHash = storage.getLastHash();
+    if (typeof lastHash === "string") {
+      previousHash = lastHash;
+    } else if (lastHash && typeof lastHash.then === "function") {
+      lastHash.then((hash) => {
+        if (typeof hash === "string")
+          previousHash = hash;
+      });
+    }
+  }
+  return {
+    log(type, data, options) {
+      sequenceId++;
+      idCounter++;
+      const event = {
+        id: `audit_${idCounter.toString(36)}_${Date.now().toString(36)}`,
+        sequenceId,
+        type,
+        timestamp: Date.now(),
+        actor: options?.actor,
+        traceId: options?.traceId,
+        data,
+        previousHash: useHashChain ? previousHash : "0".repeat(64)
+      };
+      const hash = useHashChain ? computeEventHash(event, event.previousHash) : createHash("sha256").update(JSON.stringify(event)).digest("hex");
+      const finalEvent = { ...event, hash };
+      if (useHashChain) {
+        previousHash = hash;
+      }
+      const result = storage.append(finalEvent);
+      if (result && typeof result.catch === "function") {
+        result.catch((err2) => config?.onError?.(err2));
+      }
+    },
+    async query(filter) {
+      return storage.query(filter);
+    },
+    async verifyIntegrity() {
+      return storage.verifyIntegrity();
+    },
+    get count() {
+      const result = storage.count();
+      return typeof result === "number" ? result : 0;
+    }
+  };
+}
+function auditMiddleware(auditTrail) {
+  return async (ctx, next) => {
+    const startTime = performance.now();
+    try {
+      const response = await next(ctx);
+      const latencyMs = Math.round(performance.now() - startTime);
+      auditTrail.log("llm_call", {
+        provider: ctx.provider,
+        model: ctx.model,
+        inputTokens: response.usage.inputTokens,
+        outputTokens: response.usage.outputTokens,
+        totalTokens: response.usage.totalTokens,
+        cost: response.cost.totalCost,
+        latencyMs,
+        stopReason: response.stopReason
+      }, { traceId: ctx.traceId });
+      return response;
+    } catch (error) {
+      const latencyMs = Math.round(performance.now() - startTime);
+      auditTrail.log("llm_call", {
+        provider: ctx.provider,
+        model: ctx.model,
+        error: error instanceof Error ? error.message : String(error),
+        latencyMs,
+        success: false
+      }, { traceId: ctx.traceId });
+      throw error;
+    }
+  };
+}
+// src/provenance.ts
+import { createHash as createHash2 } from "crypto";
+function sha256(input) {
+  return createHash2("sha256").update(input).digest("hex");
+}
+function matchesFilter(record, filter) {
+  if (filter.outputHash && record.outputHash !== filter.outputHash)
+    return false;
+  if (filter.promptVersion && record.promptVersion !== filter.promptVersion)
+    return false;
+  if (filter.modelVersion && record.modelVersion !== filter.modelVersion)
+    return false;
+  if (filter.traceId && record.traceId !== filter.traceId)
+    return false;
+  return true;
+}
+function createProvenanceTracker(options) {
+  const maxRecords = options?.maxRecords ?? 1e4;
+  const records = [];
+  let idCounter = 0;
+  return {
+    record(data) {
+      idCounter++;
+      const record = {
+        id: `prov_${idCounter.toString(36)}_${Date.now().toString(36)}`,
+        outputHash: sha256(data.output),
+        promptVersion: sha256(data.prompt),
+        modelVersion: sha256(data.model),
+        configHash: sha256(JSON.stringify(data.config)),
+        inputHash: sha256(data.input),
+        timestamp: Date.now(),
+        traceId: data.traceId,
+        metadata: data.metadata
+      };
+      records.push(record);
+      if (records.length > maxRecords) {
+        records.shift();
+      }
+      return record;
+    },
+    query(filter) {
+      return records.filter((r) => matchesFilter(r, filter));
+    },
+    getLineage(outputHash) {
+      const target = records.find((r) => r.outputHash === outputHash);
+      if (!target?.traceId)
+        return target ? [target] : [];
+      return records.filter((r) => r.traceId === target.traceId).sort((a, b) => a.timestamp - b.timestamp);
+    },
+    get count() {
+      return records.length;
+    },
+    clear() {
+      records.length = 0;
+    }
+  };
+}
+// src/otel.ts
+var log2 = createLogger();
+var SPAN_KIND_MAP = {
+  llm: 3,
+  tool: 1,
+  agent: 1,
+  workflow: 1,
+  custom: 0
+};
+function toNanoString(ms) {
+  return String(Math.round(ms * 1e6));
+}
+function toOTelAttribute(key, value) {
+  if (typeof value === "string") {
+    return { key, value: { stringValue: value } };
+  }
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? { key, value: { intValue: value } } : { key, value: { doubleValue: value } };
+  }
+  if (typeof value === "boolean") {
+    return { key, value: { boolValue: value } };
+  }
+  return { key, value: { stringValue: JSON.stringify(value) } };
+}
+function toOTelSpan(span) {
+  const attributes = [toOTelAttribute("elsium.span.kind", span.kind)];
+  for (const [key, value] of Object.entries(span.metadata)) {
+    attributes.push(toOTelAttribute(`elsium.${key}`, value));
+  }
+  const events = span.events.map((e) => ({
+    name: e.name,
+    timeUnixNano: toNanoString(e.timestamp),
+    attributes: e.data ? Object.entries(e.data).map(([k, v]) => toOTelAttribute(k, v)) : []
+  }));
+  let statusCode = 0;
+  if (span.status === "ok")
+    statusCode = 1;
+  if (span.status === "error")
+    statusCode = 2;
+  return {
+    traceId: normalizeId(span.traceId, 32),
+    spanId: normalizeId(span.id, 16),
+    parentSpanId: span.parentId ? normalizeId(span.parentId, 16) : undefined,
+    name: span.name,
+    kind: SPAN_KIND_MAP[span.kind] ?? 0,
+    startTimeUnixNano: toNanoString(span.startTime),
+    endTimeUnixNano: span.endTime ? toNanoString(span.endTime) : toNanoString(span.startTime),
+    attributes,
+    events,
+    status: { code: statusCode }
+  };
+}
+function normalizeId(id, length) {
+  const clean = id.replace(/^[a-z]+_/, "");
+  const hex = Array.from(clean).map((c) => c.charCodeAt(0).toString(16).padStart(2, "0")).join("");
+  return hex.slice(0, length).padEnd(length, "0");
+}
+function toOTelExportRequest(spans, options = {}) {
+  const { serviceName = "elsium-ai", serviceVersion = "0.1.0" } = options;
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            toOTelAttribute("service.name", serviceName),
+            toOTelAttribute("service.version", serviceVersion),
+            toOTelAttribute("telemetry.sdk.name", "elsium-ai"),
+            toOTelAttribute("telemetry.sdk.language", "typescript")
+          ]
+        },
+        scopeSpans: [
+          {
+            scope: {
+              name: "@elsium-ai/observe",
+              version: serviceVersion
+            },
+            spans: spans.map(toOTelSpan)
+          }
+        ]
+      }
+    ]
+  };
+}
+function toTraceparent(span) {
+  const version = "00";
+  const traceId = normalizeId(span.traceId, 32);
+  const spanId = normalizeId(span.id, 16);
+  const flags = "01";
+  return `${version}-${traceId}-${spanId}-${flags}`;
+}
+function parseTraceparent(header) {
+  const parts = header.trim().split("-");
+  if (parts.length < 4)
+    return null;
+  const [version, traceId, spanId, flags] = parts;
+  if (version !== "00")
+    return null;
+  if (traceId.length !== 32 || spanId.length !== 16)
+    return null;
+  return {
+    traceId,
+    spanId,
+    traceFlags: Number.parseInt(flags, 16)
+  };
+}
+function injectTraceContext(span, headers = {}) {
+  return {
+    ...headers,
+    traceparent: toTraceparent(span)
+  };
+}
+function extractTraceContext(headers) {
+  const traceparent = headers.traceparent ?? headers.Traceparent;
+  if (!traceparent)
+    return null;
+  return parseTraceparent(traceparent);
+}
+function createOTLPExporter(config) {
+  const {
+    endpoint,
+    headers = {},
+    serviceName,
+    serviceVersion,
+    batchSize = 100,
+    flushIntervalMs = 5000
+  } = config;
+  const buffer = [];
+  let flushTimer = null;
+  async function sendBatch(spans) {
+    if (spans.length === 0)
+      return;
+    const payload = toOTelExportRequest(spans, { serviceName, serviceVersion });
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...headers
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        log2.error(`OTLP export failed: ${response.status} ${response.statusText}`);
+      }
+    } catch (err2) {
+      log2.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
+    }
+  }
+  function startAutoFlush() {
+    if (flushTimer)
+      return;
+    flushTimer = setInterval(async () => {
+      if (buffer.length > 0) {
+        const batch = buffer.splice(0, buffer.length);
+        await sendBatch(batch);
+      }
+    }, flushIntervalMs);
+  }
+  return {
+    name: "otlp",
+    async export(spans) {
+      buffer.push(...spans);
+      if (buffer.length >= batchSize) {
+        const batch = buffer.splice(0, batchSize);
+        await sendBatch(batch);
+      } else {
+        startAutoFlush();
+      }
+    }
+  };
+}
+export {
+  toTraceparent,
+  toOTelSpan,
+  toOTelExportRequest,
+  registerModelTier,
+  parseTraceparent,
+  observe,
+  injectTraceContext,
+  extractTraceContext,
+  createSpan,
+  createProvenanceTracker,
+  createOTLPExporter,
+  createMetrics,
+  createCostEngine,
+  createAuditTrail,
+  auditMiddleware
+};