@elsium-ai/observe 0.6.0 → 0.7.0

package/README.md

@@ -565,6 +565,8 @@ type AuditEventType =
   | 'approval_request'
   | 'approval_decision'
   | 'config_change'
+  | 'provider_failover'
+  | 'circuit_breaker_state_change'
 ```
 
 ### `AuditEvent`
@@ -622,6 +624,20 @@ interface AuditIntegrityResult {
 }
 ```
 
+### `AuditBatchConfig`
+
+```ts
+interface AuditBatchConfig {
+  size?: number
+  intervalMs?: number
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `size` | `number` | `100` | Flush the buffer when it reaches this many events. |
+| `intervalMs` | `number` | `50` | Flush the buffer on this interval (ms), regardless of size. |
+
 ### `AuditTrailConfig`
 
 ```ts
@@ -629,6 +645,7 @@ interface AuditTrailConfig {
   storage?: AuditStorageAdapter | 'memory'
   hashChain?: boolean
   maxEvents?: number
+  batch?: AuditBatchConfig
   onError?: (error: unknown) => void
 }
 ```
@@ -642,12 +659,27 @@ interface AuditTrail {
     data: Record<string, unknown>,
     options?: { actor?: string; traceId?: string },
   ): void
+  ready(): Promise<void>
   query(filter: AuditQueryFilter): Promise<AuditEvent[]>
   verifyIntegrity(): Promise<AuditIntegrityResult>
+  flush(): Promise<void>
+  dispose(): void
   readonly count: number
+  readonly pending: number
 }
 ```
 
+| Member | Description |
+|---|---|
+| `log()` | Append an event. In batched mode, this buffers the event without hashing — zero CPU on the hot path. |
+| `ready()` | Resolves once async initialization (e.g. `getLastHash`) has completed. |
+| `query()` | Query events by type, actor, traceId, or timestamp range. Auto-flushes pending events in batched mode. |
+| `verifyIntegrity()` | Verify the hash chain has not been tampered with. Auto-flushes pending events in batched mode. |
+| `flush()` | Drain all pending events — computes hashes and writes to storage. No-op when not in batched mode. |
+| `dispose()` | Stop the flush timer and drain remaining events. Call this on shutdown. |
+| `count` | Total events (stored + pending). |
+| `pending` | Number of buffered events not yet flushed (0 when not in batched mode). |
+
 ### `createAuditTrail()`
 
 Creates a hash-chained audit trail for tamper-evident event logging.
@@ -660,7 +692,8 @@ function createAuditTrail(config?: AuditTrailConfig): AuditTrail
 |---|---|---|---|
 | `config.storage` | `AuditStorageAdapter \| 'memory'` | `'memory'` | Storage backend for audit events |
 | `config.hashChain` | `boolean` | `true` | Enable SHA-256 hash chaining for tamper detection |
-| `config.maxEvents` | `number` | `10000` | Maximum events retained in memory storage |
+| `config.maxEvents` | `number` | `10000` | Maximum events retained (ring buffer — O(1) eviction) |
+| `config.batch` | `AuditBatchConfig` | `undefined` | Enable batched mode for high-volume scenarios |
 | `config.onError` | `(error: unknown) => void` | `undefined` | Error handler for async storage failures |
 
 **Returns:** `AuditTrail`
@@ -694,6 +727,33 @@ console.log('Audit chain valid:', integrity.valid)
 console.log('Total events:', integrity.totalEvents)
 ```
 
+#### Batched mode (high-volume)
+
+In high-volume scenarios, `log()` computes a SHA-256 hash on every call — blocking the hot path. Batched mode moves hashing off the critical path: `log()` buffers raw event data, and hashing + storage writes happen asynchronously on flush.
+
+```ts
+import { createAuditTrail } from '@elsium-ai/observe'
+
+const audit = createAuditTrail({
+  batch: {
+    size: 500,         // Flush after 500 events
+    intervalMs: 100,   // Or every 100ms, whichever comes first
+  },
+  maxEvents: 100_000,
+})
+
+// log() is now near-zero cost — just pushes to an internal buffer
+audit.log('llm_call', { model: 'gpt-4o', tokens: 100 })
+
+// Force-flush before reading (query/verifyIntegrity auto-flush)
+await audit.flush()
+
+// Clean up on shutdown
+process.on('SIGTERM', () => audit.dispose())
+```
+
+Hash chain integrity is fully preserved — events are hashed sequentially during flush, not during `log()`.
+
 ### `auditMiddleware()`
 
 Creates an ElsiumAI middleware that automatically logs every LLM call (success or failure) to the given audit trail.

package/dist/audit.d.ts

@@ -1,5 +1,5 @@
 import type { Middleware } from '@elsium-ai/core';
-export type AuditEventType = 'llm_call' | 'tool_execution' | 'security_violation' | 'budget_alert' | 'policy_violation' | 'auth_event' | 'approval_request' | 'approval_decision' | 'config_change';
+export type AuditEventType = 'llm_call' | 'tool_execution' | 'security_violation' | 'budget_alert' | 'policy_violation' | 'auth_event' | 'approval_request' | 'approval_decision' | 'config_change' | 'provider_failover' | 'circuit_breaker_state_change';
 export interface AuditEvent {
     id: string;
     sequenceId: number;
@@ -33,10 +33,15 @@ export interface AuditIntegrityResult {
     brokenAt?: number;
     chainComplete?: boolean;
 }
+export interface AuditBatchConfig {
+    size?: number;
+    intervalMs?: number;
+}
 export interface AuditTrailConfig {
     storage?: AuditStorageAdapter | 'memory';
     hashChain?: boolean;
     maxEvents?: number;
+    batch?: AuditBatchConfig;
     onError?: (error: unknown) => void;
 }
 export interface AuditTrail {
@@ -48,7 +53,10 @@ export interface AuditTrail {
     ready(): Promise<void>;
     query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
     verifyIntegrity(): Promise<AuditIntegrityResult>;
+    flush(): Promise<void>;
+    dispose(): void;
     readonly count: number;
+    readonly pending: number;
 }
 export declare function createAuditTrail(config?: AuditTrailConfig): AuditTrail;
 export declare function auditMiddleware(auditTrail: AuditTrail): Middleware;

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

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { Tracer, TracerConfig, TracerOutput, TracerExporter, CostReport } f
 export { createMetrics } from './metrics';
 export type { MetricsCollector, MetricEntry } from './metrics';
 export { createAuditTrail, auditMiddleware } from './audit';
-export type { AuditEventType, AuditEvent, AuditStorageAdapter, AuditQueryFilter, AuditIntegrityResult, AuditTrailConfig, AuditTrail, } from './audit';
+export type { AuditEventType, AuditEvent, AuditStorageAdapter, AuditQueryFilter, AuditIntegrityResult, AuditTrailConfig, AuditBatchConfig, AuditTrail, } from './audit';
 export { createProvenanceTracker } from './provenance';
 export type { ProvenanceRecord, ProvenanceTracker } from './provenance';
 export { createExperiment, createFileExperimentStore } from './experiment';

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,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GACf,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,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,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,yBAAyB,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EACX,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GACf,MAAM,cAAc,CAAA;AAGrB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,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

@@ -708,21 +708,53 @@ function computeEventHash(event, previousHash) {
   });
   return createHash("sha256").update(content).digest("hex");
 }
+var ZERO_HASH = "0".repeat(64);
+
+class RingBuffer {
+  buffer;
+  head = 0;
+  size = 0;
+  capacity;
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.buffer = new Array(capacity);
+  }
+  push(item) {
+    const index = (this.head + this.size) % this.capacity;
+    if (this.size === this.capacity) {
+      this.head = (this.head + 1) % this.capacity;
+    } else {
+      this.size++;
+    }
+    this.buffer[index] = item;
+  }
+  toArray() {
+    const result = new Array(this.size);
+    for (let i = 0;i < this.size; i++) {
+      result[i] = this.buffer[(this.head + i) % this.capacity];
+    }
+    return result;
+  }
+  get length() {
+    return this.size;
+  }
+  last() {
+    if (this.size === 0)
+      return;
+    return this.buffer[(this.head + this.size - 1) % this.capacity];
+  }
+}
 
 class InMemoryAuditStorage {
-  events = [];
-  maxEvents;
+  ring;
   constructor(maxEvents) {
-    this.maxEvents = maxEvents ?? 1e4;
+    this.ring = new RingBuffer(maxEvents ?? 1e4);
   }
   append(event) {
-    this.events.push(event);
-    if (this.events.length > this.maxEvents) {
-      this.events = this.events.slice(-this.maxEvents);
-    }
+    this.ring.push(event);
   }
   query(filter) {
-    let results = [...this.events];
+    let results = this.ring.toArray();
     if (filter.type) {
       const types = Array.isArray(filter.type) ? filter.type : [filter.type];
       results = results.filter((e) => types.includes(e.type));
@@ -746,29 +778,29 @@ class InMemoryAuditStorage {
     return results.slice(offset, offset + limit);
   }
   count() {
-    return this.events.length;
+    return this.ring.length;
   }
   verifyIntegrity() {
-    if (this.events.length === 0) {
+    const events = this.ring.toArray();
+    if (events.length === 0) {
       return { valid: true, totalEvents: 0, chainComplete: true };
     }
-    for (let i = 0;i < this.events.length; i++) {
-      const event = this.events[i];
+    for (let i = 0;i < events.length; i++) {
+      const event = events[i];
       const expectedHash = computeEventHash(event, event.previousHash);
       if (event.hash !== expectedHash) {
-        return { valid: false, totalEvents: this.events.length, brokenAt: i };
+        return { valid: false, totalEvents: events.length, brokenAt: i };
       }
-      if (i > 0 && event.previousHash !== this.events[i - 1].hash) {
-        return { valid: false, totalEvents: this.events.length, brokenAt: i };
+      if (i > 0 && event.previousHash !== events[i - 1].hash) {
+        return { valid: false, totalEvents: events.length, brokenAt: i };
       }
     }
-    const chainComplete = this.events[0].previousHash === "0".repeat(64);
-    return { valid: true, totalEvents: this.events.length, chainComplete };
+    const chainComplete = events[0].previousHash === ZERO_HASH;
+    return { valid: true, totalEvents: events.length, chainComplete };
   }
   getLastHash() {
-    if (this.events.length === 0)
-      return "0".repeat(64);
-    return this.events[this.events.length - 1].hash;
+    const last = this.ring.last();
+    return last ? last.hash : ZERO_HASH;
   }
 }
 function createAuditTrail(config) {
@@ -776,7 +808,7 @@ function createAuditTrail(config) {
   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);
+  let previousHash = ZERO_HASH;
   let isReady = true;
   let readyPromise = Promise.resolve();
   if (useHashChain && storage.getLastHash) {
@@ -792,18 +824,25 @@ function createAuditTrail(config) {
       });
     }
   }
-  function appendEntry(type, data, options) {
+  const batchConfig = config?.batch;
+  const batchSize = batchConfig?.size ?? 100;
+  const batchIntervalMs = batchConfig?.intervalMs ?? 50;
+  const isBatched = !!batchConfig;
+  const pendingBuffer = [];
+  let flushTimer = null;
+  const flushPromise = Promise.resolve();
+  function buildAndAppend(entry) {
     sequenceId++;
     idCounter++;
     const event = {
-      id: `audit_${idCounter.toString(36)}_${Date.now().toString(36)}`,
+      id: `audit_${idCounter.toString(36)}_${entry.timestamp.toString(36)}`,
       sequenceId,
-      type,
-      timestamp: Date.now(),
-      actor: options?.actor,
-      traceId: options?.traceId,
-      data,
-      previousHash: useHashChain ? previousHash : "0".repeat(64)
+      type: entry.type,
+      timestamp: entry.timestamp,
+      actor: entry.actor,
+      traceId: entry.traceId,
+      data: entry.data,
+      previousHash: useHashChain ? previousHash : ZERO_HASH
     };
     const hash = useHashChain ? computeEventHash(event, event.previousHash) : createHash("sha256").update(JSON.stringify(event)).digest("hex");
     const finalEvent = { ...event, hash };
@@ -815,26 +854,77 @@ function createAuditTrail(config) {
       result.catch((err2) => config?.onError?.(err2));
     }
   }
+  function drainBuffer() {
+    let entry = pendingBuffer.shift();
+    while (entry) {
+      buildAndAppend(entry);
+      entry = pendingBuffer.shift();
+    }
+  }
+  if (isBatched) {
+    flushTimer = setInterval(() => {
+      if (pendingBuffer.length > 0)
+        drainBuffer();
+    }, batchIntervalMs);
+    if (typeof flushTimer === "object" && "unref" in flushTimer) {
+      flushTimer.unref();
+    }
+  }
+  function logEntry(type, data, options) {
+    const entry = {
+      type,
+      data,
+      timestamp: Date.now(),
+      actor: options?.actor,
+      traceId: options?.traceId
+    };
+    if (isBatched) {
+      pendingBuffer.push(entry);
+      if (pendingBuffer.length >= batchSize)
+        drainBuffer();
+      return;
+    }
+    buildAndAppend(entry);
+  }
   return {
     log(type, data, options) {
       if (isReady) {
-        appendEntry(type, data, options);
+        logEntry(type, data, options);
       } else {
-        readyPromise = readyPromise.then(() => appendEntry(type, data, options));
+        readyPromise = readyPromise.then(() => logEntry(type, data, options));
       }
     },
     ready() {
       return readyPromise;
     },
+    async flush() {
+      await readyPromise;
+      drainBuffer();
+      await flushPromise;
+    },
+    dispose() {
+      if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+      }
+      drainBuffer();
+    },
     async query(filter) {
+      if (isBatched)
+        drainBuffer();
       return storage.query(filter);
     },
     async verifyIntegrity() {
+      if (isBatched)
+        drainBuffer();
       return storage.verifyIntegrity();
     },
     get count() {
       const result = storage.count();
-      return typeof result === "number" ? result : 0;
+      return (typeof result === "number" ? result : 0) + pendingBuffer.length;
+    },
+    get pending() {
+      return pendingBuffer.length;
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elsium-ai/observe",
-	"version": "0.6.0",
+	"version": "0.7.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.6.0"
+		"@elsium-ai/core": "^0.7.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.7.0"