@elsium-ai/observe 0.2.2 → 0.3.0

package/dist/audit.d.ts

@@ -44,6 +44,8 @@ export interface AuditTrail {
         actor?: string;
         traceId?: string;
     }): void;
+    /** Resolves once async initialization (e.g. getLastHash) has completed. */
+    ready(): Promise<void>;
     query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
     verifyIntegrity(): Promise<AuditIntegrityResult>;
     readonly count: number;

package/dist/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,iBAAiB,CAAA;AAEpF,MAAM,MAAM,cAAc,GACvB,UAAU,GACV,gBAAgB,GAChB,oBAAoB,GACpB,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,CAAA;AAElB,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,cAAc,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACrE,KAAK,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACjC,eAAe,IAAI,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACvE,WAAW,CAAC,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAA;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,EAAE,mBAAmB,GAAG,QAAQ,CAAA;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAClC;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,CACF,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,IAAI,CAAA;IACP,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACtD,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAyFD,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAuEtE;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CA0ClE"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,iBAAiB,CAAA;AAEpF,MAAM,MAAM,cAAc,GACvB,UAAU,GACV,gBAAgB,GAChB,oBAAoB,GACpB,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,CAAA;AAElB,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,cAAc,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACrE,KAAK,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACjC,eAAe,IAAI,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACvE,WAAW,CAAC,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAA;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,EAAE,mBAAmB,GAAG,QAAQ,CAAA;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAClC;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,CACF,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,IAAI,CAAA;IACP,2EAA2E;IAC3E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACtD,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACtB;AAyFD,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAqGtE;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CA0ClE"}

package/dist/experiment.d.ts

@@ -0,0 +1,28 @@
+export interface ExperimentVariant {
+    name: string;
+    weight: number;
+    config: Record<string, unknown>;
+}
+export interface ExperimentResults {
+    name: string;
+    totalAssignments: number;
+    variants: Record<string, {
+        assignments: number;
+        metrics: Record<string, {
+            sum: number;
+            count: number;
+            avg: number;
+        }>;
+    }>;
+}
+export interface Experiment {
+    assign(userId?: string): ExperimentVariant;
+    record(variant: string, metrics: Record<string, number>): void;
+    results(): ExperimentResults;
+}
+export interface ExperimentConfig {
+    name: string;
+    variants: ExperimentVariant[];
+}
+export declare function createExperiment(config: ExperimentConfig): Experiment;
+//# sourceMappingURL=experiment.d.ts.map

package/dist/experiment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.d.ts","sourceRoot":"","sources":["../src/experiment.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CACf,MAAM,EACN;QACC,WAAW,EAAE,MAAM,CAAA;QACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACpE,CACD,CAAA;CACD;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAC1C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC9D,OAAO,IAAI,iBAAiB,CAAA;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA0FrE"}

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { createAuditTrail, auditMiddleware } from './audit';
 export type { AuditEventType, AuditEvent, AuditStorageAdapter, AuditQueryFilter, AuditIntegrityResult, AuditTrailConfig, AuditTrail, } from './audit';
 export { createProvenanceTracker } from './provenance';
 export type { ProvenanceRecord, ProvenanceTracker } from './provenance';
+export { createExperiment } from './experiment';
+export type { Experiment, ExperimentConfig, ExperimentVariant, ExperimentResults, } from './experiment';
 export { toOTelSpan, toOTelExportRequest, toTraceparent, parseTraceparent, injectTraceContext, extractTraceContext, createOTLPExporter, } from './otel';
 export type { OTelSpan, OTelSpanKind, OTelStatusCode, OTelAttribute, OTelAttributeValue, OTelEvent, OTelResource, OTelExportRequest, TraceContext, OTLPExporterConfig, } from './otel';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnE,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC3D,YAAY,EACX,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,QAAQ,CAAA;AACf,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACnC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAG1F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnE,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,aAAa,EACb,sBAAsB,EACtB,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAG9F,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC3D,YAAY,EACX,cAAc,EACd,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACV,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GACjB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACN,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GAClB,MAAM,QAAQ,CAAA;AACf,YAAY,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -140,6 +140,11 @@ function createLogger(options = {}) {
     }
   };
 }
+// ../core/src/schema.ts
+var log = createLogger();
+// ../core/src/registry.ts
+var log2 = createLogger();
+var BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 // src/span.ts
 function createSpan(name, options = {}) {
   const id = generateId("spn");
@@ -491,7 +496,8 @@ function createCostEngine(config = {}) {
   };
 }
 // src/tracer.ts
-var log = createLogger();
+import { writeFileSync } from "node:fs";
+var log3 = createLogger();
 function observe(config = {}) {
   const {
     output = ["console"],
@@ -506,7 +512,21 @@ function observe(config = {}) {
   for (const out of output) {
     if (out === "console") {
       handlers.push(consoleHandler);
-    } else if (out === "json-file") {} else {
+    } else if (out === "json-file") {
+      exporters.push({
+        name: "json-file",
+        export(spansToExport) {
+          const filename = `.elsium/traces-${Date.now()}.json`;
+          try {
+            writeFileSync(filename, JSON.stringify(spansToExport, null, 2));
+          } catch (err2) {
+            log3.error("Failed to write trace file", {
+              error: err2 instanceof Error ? err2.message : String(err2)
+            });
+          }
+        }
+      });
+    } else {
       exporters.push(out);
     }
   }
@@ -575,7 +595,7 @@ function observe(config = {}) {
 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", {
+  log3.info("span", {
     trace: span.traceId,
     span: span.name,
     kind: span.kind,
@@ -757,41 +777,55 @@ function createAuditTrail(config) {
   let sequenceId = 0;
   let idCounter = 0;
   let previousHash = "0".repeat(64);
+  let isReady = true;
+  let readyPromise = Promise.resolve();
   if (useHashChain && storage.getLastHash) {
     const lastHash = storage.getLastHash();
     if (typeof lastHash === "string") {
       previousHash = lastHash;
-    } else if (lastHash && typeof lastHash.then === "function") {
-      lastHash.then((hash) => {
+    } else {
+      isReady = false;
+      readyPromise = lastHash.then((hash) => {
         if (typeof hash === "string")
           previousHash = hash;
+        isReady = true;
       });
     }
   }
+  function appendEntry(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));
+    }
+  }
   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));
+      if (isReady) {
+        appendEntry(type, data, options);
+      } else {
+        readyPromise = readyPromise.then(() => appendEntry(type, data, options));
       }
     },
+    ready() {
+      return readyPromise;
+    },
     async query(filter) {
       return storage.query(filter);
     },
@@ -891,8 +925,86 @@ function createProvenanceTracker(options) {
     }
   };
 }
+// src/experiment.ts
+import { createHash as createHash3 } from "node:crypto";
+var log4 = createLogger();
+function createExperiment(config) {
+  const { name, variants } = config;
+  if (variants.length === 0) {
+    throw new Error("Experiment must have at least one variant");
+  }
+  const totalWeight = variants.reduce((sum, v) => sum + v.weight, 0);
+  const stats = {};
+  for (const v of variants) {
+    stats[v.name] = { assignments: 0, metrics: {} };
+  }
+  function hashAssign(userId) {
+    const hash = createHash3("sha256").update(`${name}:${userId}`).digest();
+    const value = hash.readUInt32BE(0) % 1e4 / 1e4;
+    return pickVariant(value);
+  }
+  function randomAssign() {
+    const value = Math.random();
+    return pickVariant(value);
+  }
+  function pickVariant(value) {
+    let cumulative = 0;
+    for (const v of variants) {
+      cumulative += v.weight / totalWeight;
+      if (value < cumulative)
+        return v;
+    }
+    return variants[variants.length - 1];
+  }
+  return {
+    assign(userId) {
+      const variant = userId ? hashAssign(userId) : randomAssign();
+      const s = stats[variant.name];
+      if (s)
+        s.assignments++;
+      log4.debug("Experiment assignment", {
+        experiment: name,
+        variant: variant.name,
+        userId
+      });
+      return variant;
+    },
+    record(variant, metrics) {
+      const s = stats[variant];
+      if (!s)
+        return;
+      for (const [key, value] of Object.entries(metrics)) {
+        if (!s.metrics[key]) {
+          s.metrics[key] = { sum: 0, count: 0 };
+        }
+        s.metrics[key].sum += value;
+        s.metrics[key].count++;
+      }
+    },
+    results() {
+      let totalAssignments = 0;
+      const variantResults = {};
+      for (const [vName, s] of Object.entries(stats)) {
+        totalAssignments += s.assignments;
+        const metricsResult = {};
+        for (const [key, m] of Object.entries(s.metrics)) {
+          metricsResult[key] = {
+            sum: m.sum,
+            count: m.count,
+            avg: m.count > 0 ? m.sum / m.count : 0
+          };
+        }
+        variantResults[vName] = {
+          assignments: s.assignments,
+          metrics: metricsResult
+        };
+      }
+      return { name, totalAssignments, variants: variantResults };
+    }
+  };
+}
 // src/otel.ts
-var log2 = createLogger();
+var log5 = createLogger();
 var SPAN_KIND_MAP = {
   llm: 3,
   tool: 1,
@@ -1033,10 +1145,10 @@ function createOTLPExporter(config) {
         body: JSON.stringify(payload)
       });
       if (!response.ok) {
-        log2.error(`OTLP export failed: ${response.status} ${response.statusText}`);
+        log5.error(`OTLP export failed: ${response.status} ${response.statusText}`);
       }
     } catch (err2) {
-      log2.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
+      log5.error("OTLP export error", { error: err2 instanceof Error ? err2.message : String(err2) });
     }
   }
   function startAutoFlush() {
@@ -1059,6 +1171,16 @@ function createOTLPExporter(config) {
       } else {
         startAutoFlush();
       }
+    },
+    async shutdown() {
+      if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+      }
+      if (buffer.length > 0) {
+        const batch = buffer.splice(0, buffer.length);
+        await sendBatch(batch);
+      }
     }
   };
 }
@@ -1075,6 +1197,7 @@ export {
   createProvenanceTracker,
   createOTLPExporter,
   createMetrics,
+  createExperiment,
   createCostEngine,
   createAuditTrail,
   auditMiddleware

package/dist/otel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"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"}

package/dist/tracer.d.ts

@@ -9,6 +9,7 @@ export type TracerOutput = 'console' | 'json-file' | TracerExporter;
 export interface TracerExporter {
     name: string;
     export(spans: SpanData[]): void | Promise<void>;
+    shutdown?(): void | Promise<void>;
 }
 export interface CostReport {
     totalCost: number;

package/dist/tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAe,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAGnE,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;IACvB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,cAAc,CAAA;AAEnE,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,UAAU;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CACd,MAAM,EACN;QACC,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,EAAE,MAAM,CAAA;KACb,CACD,CAAA;CACD;AAED,MAAM,WAAW,MAAM;IACtB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC9C,QAAQ,IAAI,QAAQ,EAAE,CAAA;IACtB,aAAa,IAAI,UAAU,CAAA;IAC3B,YAAY,CAAC,IAAI,EAAE;QAClB,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;KACjB,GAAG,IAAI,CAAA;IACR,KAAK,IAAI,IAAI,CAAA;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED,wBAAgB,OAAO,CAAC,MAAM,GAAE,YAAiB,GAAG,MAAM,CAkGzD"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAe,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAGnE,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;IACvB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,cAAc,CAAA;AAEnE,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,UAAU;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CACd,MAAM,EACN;QACC,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,EAAE,MAAM,CAAA;KACb,CACD,CAAA;CACD;AAED,MAAM,WAAW,MAAM;IACtB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IAC9C,QAAQ,IAAI,QAAQ,EAAE,CAAA;IACtB,aAAa,IAAI,UAAU,CAAA;IAC3B,YAAY,CAAC,IAAI,EAAE;QAClB,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;KACjB,GAAG,IAAI,CAAA;IACR,KAAK,IAAI,IAAI,CAAA;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED,wBAAgB,OAAO,CAAC,MAAM,GAAE,YAAiB,GAAG,MAAM,CA8GzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elsium-ai/observe",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"description": "Observability, tracing, and cost tracking for ElsiumAI",
 	"license": "MIT",
 	"author": "Eric Utrera <ebutrera9103@gmail.com>",
@@ -26,7 +26,7 @@
 		"dev": "bun --watch src/index.ts"
 	},
 	"dependencies": {
-		"@elsium-ai/core": "^0.2.2"
+		"@elsium-ai/core": "^0.3.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.7.0"