@graphorin/observability 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/observability",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Observability primitives for the Graphorin framework: typed AISpan tracer over OpenTelemetry, mandatory withValidation wrapper for every exporter, sensitivity-aware RedactionValidator with built-in PII / secret patterns, GenAI Semantic Conventions conformance helpers, OpenInference span-kind emission, structured logger with span correlation, append-only JSONL exporter for replay, sanitized replay primitives, hierarchical CostTracker, and a minimal inline eval runner alongside a zero-default telemetry stub.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -32,8 +32,9 @@
     "logger"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -41,91 +42,73 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./tracer": {
       "types": "./dist/tracer/index.d.ts",
-      "import": "./dist/tracer/index.js"
+      "default": "./dist/tracer/index.js"
     },
     "./redaction": {
       "types": "./dist/redaction/index.d.ts",
-      "import": "./dist/redaction/index.js"
+      "default": "./dist/redaction/index.js"
     },
     "./redaction/patterns": {
       "types": "./dist/redaction/patterns.d.ts",
-      "import": "./dist/redaction/patterns.js"
+      "default": "./dist/redaction/patterns.js"
     },
     "./redaction/imperative-patterns": {
       "types": "./dist/redaction/imperative-patterns.d.ts",
-      "import": "./dist/redaction/imperative-patterns.js"
+      "default": "./dist/redaction/imperative-patterns.js"
     },
     "./exporters": {
       "types": "./dist/exporters/index.d.ts",
-      "import": "./dist/exporters/index.js"
+      "default": "./dist/exporters/index.js"
     },
     "./gen-ai": {
       "types": "./dist/gen-ai/index.d.ts",
-      "import": "./dist/gen-ai/index.js"
+      "default": "./dist/gen-ai/index.js"
     },
     "./openinference": {
       "types": "./dist/openinference/index.d.ts",
-      "import": "./dist/openinference/index.js"
+      "default": "./dist/openinference/index.js"
     },
     "./cost": {
       "types": "./dist/cost/index.d.ts",
-      "import": "./dist/cost/index.js"
+      "default": "./dist/cost/index.js"
     },
     "./replay": {
       "types": "./dist/replay/index.d.ts",
-      "import": "./dist/replay/index.js"
+      "default": "./dist/replay/index.js"
     },
     "./eval": {
       "types": "./dist/eval/index.d.ts",
-      "import": "./dist/eval/index.js"
+      "default": "./dist/eval/index.js"
     },
     "./logger": {
       "types": "./dist/logger/index.d.ts",
-      "import": "./dist/logger/index.js"
+      "default": "./dist/logger/index.js"
     },
     "./telemetry": {
       "types": "./dist/telemetry/index.d.ts",
-      "import": "./dist/telemetry/index.js"
+      "default": "./dist/telemetry/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/core": "0.6.0"
-  },
-  "peerDependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-node": "^0.217.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0"
-  },
-  "peerDependenciesMeta": {
-    "@opentelemetry/api": {
-      "optional": false
-    },
-    "@opentelemetry/sdk-node": {
-      "optional": true
-    },
-    "@opentelemetry/exporter-trace-otlp-http": {
-      "optional": true
-    }
+    "@graphorin/core": "0.7.0"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "devDependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
-    "@opentelemetry/sdk-node": "^0.217.0",
     "fast-check": "^3.23.0"
   },
   "scripts": {

package/src/cost/cost-tracker.ts

@@ -0,0 +1,315 @@
+/**
+ * `createCostTracker(...)` - aggregate token + cost figures across
+ * spans and provide per-scope queries.
+ *
+ * The tracker preserves parent-child relationships: when
+ * `record({ parentSpanId })` is supplied, the recorded usage is also
+ * attributed to the ancestor span via the configured spans-by-id
+ * lookup. Aggregations across runs / sessions / agents / users are
+ * computed on demand.
+ *
+ * @packageDocumentation
+ */
+
+import type { Cost } from '@graphorin/core';
+
+import type {
+  CostBudgetExceededCallback,
+  CostBudgets,
+  CostRecordInput,
+  CostScope,
+  CostSnapshot,
+  CostTrackerOptions,
+} from './types.js';
+
+/**
+ * @stable
+ */
+export interface CostTracker {
+  /** Record a single LLM-call usage / cost figure. */
+  record(input: CostRecordInput): void;
+  /** Snapshot for a given scope id. Returns zero figures when unknown. */
+  usage(scope: CostScope, id: string): CostSnapshot;
+  /** Snapshot for a single span id (carries nested attributions). */
+  usageForSpan(spanId: string): CostSnapshot;
+  /** Reset every counter back to zero. */
+  reset(): void;
+  /** Subscribe to per-scope rollup notifications. Returns an unsubscribe. */
+  onRollup(listener: (input: CostRecordInput) => void): () => void;
+}
+
+interface AggregateBucket {
+  promptTokens: number;
+  completionTokens: number;
+  reasoningTokens: number;
+  cachedReadTokens: number;
+  cacheWriteTokens: number;
+  callCount: number;
+  costAmount: number;
+  costCurrency: string | null;
+  /** RP-22: set when records carrying differing currencies are aggregated. */
+  mixedCurrency: boolean;
+  byModel: Map<string, AggregateBucket>;
+  exceeded: boolean;
+}
+
+function freshBucket(): AggregateBucket {
+  return {
+    promptTokens: 0,
+    completionTokens: 0,
+    reasoningTokens: 0,
+    cachedReadTokens: 0,
+    cacheWriteTokens: 0,
+    callCount: 0,
+    costAmount: 0,
+    costCurrency: null,
+    mixedCurrency: false,
+    byModel: new Map(),
+    exceeded: false,
+  };
+}
+
+// RP-22: accumulate a cost without silently overwriting the currency. The
+// first currency seen is kept; a record in a different currency flags the
+// bucket as `mixedCurrency` so a USD + EUR total is never reported as one
+// clean figure.
+function addCost(bucket: AggregateBucket, cost: Cost): void {
+  if (bucket.costCurrency !== null && bucket.costCurrency !== cost.currency) {
+    bucket.mixedCurrency = true;
+  } else if (bucket.costCurrency === null) {
+    bucket.costCurrency = cost.currency;
+  }
+  bucket.costAmount += cost.amount;
+}
+
+function combine(target: AggregateBucket, input: CostRecordInput): void {
+  target.promptTokens += input.promptTokens;
+  target.completionTokens += input.completionTokens;
+  target.reasoningTokens += input.reasoningTokens ?? 0;
+  target.cachedReadTokens += input.cachedReadTokens ?? 0;
+  target.cacheWriteTokens += input.cacheWriteTokens ?? 0;
+  target.callCount += 1;
+  if (input.cost !== undefined) addCost(target, input.cost);
+  const modelBucket = target.byModel.get(input.model) ?? freshBucket();
+  modelBucket.promptTokens += input.promptTokens;
+  modelBucket.completionTokens += input.completionTokens;
+  modelBucket.reasoningTokens += input.reasoningTokens ?? 0;
+  modelBucket.cachedReadTokens += input.cachedReadTokens ?? 0;
+  modelBucket.cacheWriteTokens += input.cacheWriteTokens ?? 0;
+  modelBucket.callCount += 1;
+  if (input.cost !== undefined) addCost(modelBucket, input.cost);
+  target.byModel.set(input.model, modelBucket);
+}
+
+function snapshotOf(bucket: AggregateBucket): CostSnapshot {
+  const cost: Cost | null =
+    bucket.costCurrency === null
+      ? null
+      : { amount: bucket.costAmount, currency: bucket.costCurrency };
+  return {
+    promptTokens: bucket.promptTokens,
+    completionTokens: bucket.completionTokens,
+    reasoningTokens: bucket.reasoningTokens,
+    cachedReadTokens: bucket.cachedReadTokens,
+    cacheWriteTokens: bucket.cacheWriteTokens,
+    totalTokens: bucket.promptTokens + bucket.completionTokens + bucket.reasoningTokens,
+    callCount: bucket.callCount,
+    cost,
+    mixedCurrency: bucket.mixedCurrency,
+    byModel: [...bucket.byModel.entries()].map(([model, b]) => ({
+      model,
+      promptTokens: b.promptTokens,
+      completionTokens: b.completionTokens,
+      reasoningTokens: b.reasoningTokens,
+      cachedReadTokens: b.cachedReadTokens,
+      cacheWriteTokens: b.cacheWriteTokens,
+      callCount: b.callCount,
+      cost: b.costCurrency === null ? null : { amount: b.costAmount, currency: b.costCurrency },
+      mixedCurrency: b.mixedCurrency,
+    })),
+  };
+}
+
+const ZERO: CostSnapshot = Object.freeze({
+  promptTokens: 0,
+  completionTokens: 0,
+  reasoningTokens: 0,
+  cachedReadTokens: 0,
+  cacheWriteTokens: 0,
+  totalTokens: 0,
+  callCount: 0,
+  cost: null,
+  mixedCurrency: false,
+  byModel: [],
+});
+
+/**
+ * Build a {@link CostTracker} configured with the supplied budgets.
+ *
+ * @stable
+ */
+export function createCostTracker(opts: CostTrackerOptions = {}): CostTracker {
+  const budgets: CostBudgets = opts.budgets ?? {};
+  const currency = budgets.currency ?? 'USD';
+  const onExceed = opts.onExceed;
+  // W-092: memory bounds - the tracker lives for the process lifetime,
+  // so unbounded maps are a leak in the long-running-assistant scenario.
+  const retention = opts.retention;
+  const maxSpanEntries =
+    retention === false
+      ? Number.POSITIVE_INFINITY
+      : (retention?.maxSpanEntries ?? DEFAULT_MAX_SPAN_ENTRIES);
+  const maxScopeEntries =
+    retention === false
+      ? Number.POSITIVE_INFINITY
+      : (retention?.maxScopeEntries ?? DEFAULT_MAX_SCOPE_ENTRIES);
+
+  const bySpan = new Map<string, AggregateBucket>();
+  const byScope: Record<CostScope, Map<string, AggregateBucket>> = {
+    run: new Map(),
+    session: new Map(),
+    agent: new Map(),
+    user: new Map(),
+  };
+
+  // Parent index: child span -> parent span. Used to roll attributions
+  // up the ancestor chain on every record call.
+  const parents = new Map<string, string>();
+  const listeners = new Set<(input: CostRecordInput) => void>();
+
+  // W-092: evict OLDEST entries (Map insertion order - a re-recorded
+  // key keeps its original position on purpose: this is an age bound,
+  // not an LRU) once a map exceeds its cap. Evicting a span also drops
+  // its parent edge so `parents` cannot outgrow `bySpan`.
+  function evictOldest(
+    map: Map<string, AggregateBucket>,
+    max: number,
+    surface: 'span' | CostScope,
+  ): void {
+    while (map.size > max) {
+      const oldest = map.keys().next().value;
+      if (oldest === undefined) return;
+      map.delete(oldest);
+      if (surface === 'span') parents.delete(oldest);
+      try {
+        opts.onEviction?.({ surface, id: oldest });
+      } catch {
+        // Observers must never break the tracker.
+      }
+    }
+  }
+
+  function bump(scope: CostScope, id: string | undefined, input: CostRecordInput): void {
+    if (id === undefined) return;
+    const map = byScope[scope];
+    const bucket = map.get(id) ?? freshBucket();
+    combine(bucket, input);
+    map.set(id, bucket);
+    evictOldest(map, maxScopeEntries, scope);
+    enforceBudget(scope, id, bucket, onExceed);
+  }
+
+  function enforceBudget(
+    scope: CostScope,
+    id: string,
+    bucket: AggregateBucket,
+    cb?: CostBudgetExceededCallback,
+  ): void {
+    const limit = pickBudget(budgets, scope);
+    if (limit === undefined) return;
+    if (bucket.exceeded) return;
+    if (bucket.costAmount > limit) {
+      bucket.exceeded = true;
+      cb?.({
+        scope,
+        id,
+        budget: limit,
+        actual: bucket.costAmount,
+        currency: bucket.costCurrency ?? currency,
+      });
+    }
+  }
+
+  return {
+    record(input: CostRecordInput): void {
+      // Record the raw span figures.
+      const spanBucket = bySpan.get(input.spanId) ?? freshBucket();
+      combine(spanBucket, input);
+      bySpan.set(input.spanId, spanBucket);
+
+      // Walk the ancestor chain so that the figures roll up to every
+      // parent span. The walker breaks if it encounters a cycle.
+      if (input.parentSpanId !== undefined) {
+        parents.set(input.spanId, input.parentSpanId);
+      }
+      const seen = new Set<string>();
+      let ancestor = parents.get(input.spanId);
+      while (ancestor !== undefined && !seen.has(ancestor)) {
+        seen.add(ancestor);
+        const ancestorBucket = bySpan.get(ancestor) ?? freshBucket();
+        combine(ancestorBucket, input);
+        bySpan.set(ancestor, ancestorBucket);
+        ancestor = parents.get(ancestor);
+      }
+      // W-092: bound the span map AFTER the rollup walk so the entries
+      // this record touched are all present before age eviction runs.
+      evictOldest(bySpan, maxSpanEntries, 'span');
+
+      // Roll up to the requested aggregation scopes.
+      bump('run', input.runId, input);
+      bump('session', input.sessionId, input);
+      bump('agent', input.agentId, input);
+      bump('user', input.userId, input);
+
+      for (const listener of listeners) {
+        try {
+          listener(input);
+        } catch {
+          // Listeners must never break the tracker.
+        }
+      }
+    },
+    // W-092: an id evicted by the retention bound reports ZERO - same
+    // as never-seen. Pass `retention: false` for the old unbounded maps.
+    usage(scope: CostScope, id: string): CostSnapshot {
+      const bucket = byScope[scope].get(id);
+      if (bucket === undefined) return ZERO;
+      return snapshotOf(bucket);
+    },
+    usageForSpan(spanId: string): CostSnapshot {
+      const bucket = bySpan.get(spanId);
+      if (bucket === undefined) return ZERO;
+      return snapshotOf(bucket);
+    },
+    reset(): void {
+      bySpan.clear();
+      for (const map of Object.values(byScope)) {
+        map.clear();
+      }
+      parents.clear();
+    },
+    onRollup(listener): () => void {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** W-092: default retention caps - generous for a long-lived assistant. */
+const DEFAULT_MAX_SPAN_ENTRIES = 10_000;
+const DEFAULT_MAX_SCOPE_ENTRIES = 10_000;
+
+function pickBudget(budgets: CostBudgets, scope: CostScope): number | undefined {
+  switch (scope) {
+    case 'session':
+      return budgets.perSession;
+    case 'user':
+      return budgets.perUser;
+    case 'agent':
+      return budgets.perAgent;
+    case 'run':
+      return budgets.perRun;
+  }
+}

package/src/cost/delegate.ts

@@ -0,0 +1,79 @@
+/**
+ * W-092: the documented-but-missing bridge between the provider
+ * middleware `withCostTracking` and a {@link CostTracker}. The
+ * middleware's `onUsage` hook carries per-call figures (incl. the
+ * prompt-cache legs and a computed `costUsd`); this adapter converts
+ * them into a {@link CostRecordInput} and records it - STRUCTURALLY,
+ * with no `@graphorin/provider` import, so the observability package
+ * keeps its dependency profile.
+ *
+ * ```ts
+ * const tracker = createCostTracker({ budgets: { perSession: 5 } });
+ * const provider = withCostTracking(base, {
+ *   priceLookup,
+ *   onUsage: costTrackerUsageDelegate(tracker, () => ({
+ *     spanId: currentSpanId(),
+ *     sessionId: currentSessionId(),
+ *   })),
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { CostTracker } from './cost-tracker.js';
+import type { CostRecordInput } from './types.js';
+
+/**
+ * Structural mirror of the info object `withCostTracking`'s `onUsage`
+ * hook receives (no provider dependency).
+ *
+ * @stable
+ */
+export interface ProviderUsageInfoLike {
+  readonly modelId: string;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly cachedReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+  readonly costUsd: number;
+}
+
+/**
+ * Attribution ids for one recorded call. `spanId` is mandatory (the
+ * tracker keys rollups on it); everything else is optional scope
+ * attribution.
+ *
+ * @stable
+ */
+export type CostTrackerDelegateIds = Pick<
+  CostRecordInput,
+  'spanId' | 'parentSpanId' | 'runId' | 'sessionId' | 'agentId' | 'userId'
+>;
+
+/**
+ * Build an `onUsage` callback that records into `tracker`. Pass either
+ * static ids (a provider instance bound to one session) or a resolver
+ * invoked per call (a shared provider serving many runs). A zero
+ * `costUsd` records token figures WITHOUT a cost so a price-less
+ * middleware does not fabricate a $0 USD cost entry.
+ *
+ * @stable
+ */
+export function costTrackerUsageDelegate(
+  tracker: Pick<CostTracker, 'record'>,
+  ids: CostTrackerDelegateIds | ((info: ProviderUsageInfoLike) => CostTrackerDelegateIds),
+): (info: ProviderUsageInfoLike) => void {
+  return (info) => {
+    const resolved = typeof ids === 'function' ? ids(info) : ids;
+    tracker.record({
+      model: info.modelId,
+      promptTokens: info.promptTokens,
+      completionTokens: info.completionTokens,
+      ...(info.cachedReadTokens !== undefined ? { cachedReadTokens: info.cachedReadTokens } : {}),
+      ...(info.cacheWriteTokens !== undefined ? { cacheWriteTokens: info.cacheWriteTokens } : {}),
+      ...(info.costUsd > 0 ? { cost: { amount: info.costUsd, currency: 'USD' } } : {}),
+      ...resolved,
+    });
+  };
+}

package/src/cost/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Cost / token tracker surface.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  type CostTracker,
+  createCostTracker,
+} from './cost-tracker.js';
+export {
+  type CostTrackerDelegateIds,
+  costTrackerUsageDelegate,
+  type ProviderUsageInfoLike,
+} from './delegate.js';
+export type {
+  CostBudgetExceededCallback,
+  CostBudgets,
+  CostRecordInput,
+  CostScope,
+  CostSnapshot,
+  CostTrackerOptions,
+} from './types.js';

package/src/cost/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Public types for the cost-tracker surface.
+ *
+ * @packageDocumentation
+ */
+
+import type { Cost } from '@graphorin/core';
+
+/**
+ * Aggregation scope used by {@link CostTracker.usage}. The framework
+ * tracks four canonical scopes; deployments needing additional
+ * dimensions can build them by registering listeners on
+ * `CostTracker.onRollup(...)`.
+ *
+ * @stable
+ */
+export type CostScope = 'run' | 'session' | 'agent' | 'user';
+
+/**
+ * Per-call usage record fed into {@link CostTracker.record}.
+ *
+ * @stable
+ */
+export interface CostRecordInput {
+  readonly model: string;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly reasoningTokens?: number;
+  /** Prompt-cache READ leg (W-092; name mirrors core `Usage`). */
+  readonly cachedReadTokens?: number;
+  /** Prompt-cache WRITE leg (W-092; name mirrors core `Usage`). */
+  readonly cacheWriteTokens?: number;
+  readonly cost?: Cost;
+  /** Span id; used to thread parent-child rollups. */
+  readonly spanId: string;
+  /** Optional parent span id (when the call is part of a nested run). */
+  readonly parentSpanId?: string;
+  readonly runId?: string;
+  readonly sessionId?: string;
+  readonly agentId?: string;
+  readonly userId?: string;
+}
+
+/**
+ * Snapshot returned by {@link CostTracker.usage}.
+ *
+ * @stable
+ */
+export interface CostSnapshot {
+  readonly totalTokens: number;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly reasoningTokens: number;
+  /** W-092: aggregated prompt-cache READ tokens (0 when never recorded). */
+  readonly cachedReadTokens: number;
+  /** W-092: aggregated prompt-cache WRITE tokens (0 when never recorded). */
+  readonly cacheWriteTokens: number;
+  readonly callCount: number;
+  /**
+   * Aggregated cost in WHOLE currency units (W-045; for USD - dollars,
+   * fractional values expected). Same convention as core `Cost.amount`
+   * and `@graphorin/pricing.calculateCost` - never minor units.
+   */
+  readonly cost: Cost | null;
+  /**
+   * RP-22: `true` when records carrying differing currencies were aggregated
+   * into this snapshot. `cost.amount` is then a sum across currencies and must
+   * not be treated as a single clean figure.
+   */
+  readonly mixedCurrency: boolean;
+  readonly byModel: ReadonlyArray<{
+    readonly model: string;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly reasoningTokens: number;
+    /** W-092: per-model prompt-cache READ tokens. */
+    readonly cachedReadTokens: number;
+    /** W-092: per-model prompt-cache WRITE tokens. */
+    readonly cacheWriteTokens: number;
+    readonly callCount: number;
+    readonly cost: Cost | null;
+    readonly mixedCurrency: boolean;
+  }>;
+}
+
+/**
+ * Budget configuration shape consumed by {@link createCostTracker}.
+ *
+ * @stable
+ */
+export interface CostBudgets {
+  /** Per-session budget in the configured currency. */
+  readonly perSession?: number;
+  /** Per-user budget. */
+  readonly perUser?: number;
+  /** Per-agent budget. */
+  readonly perAgent?: number;
+  /** Per-run budget. */
+  readonly perRun?: number;
+  /** Currency. Defaults to `'USD'`. */
+  readonly currency?: string;
+}
+
+/**
+ * Callback invoked when an aggregation scope crosses its configured
+ * budget. The handler receives a sanitized payload - the secret-free
+ * scope id + the breached numbers.
+ *
+ * @stable
+ */
+export type CostBudgetExceededCallback = (event: {
+  readonly scope: CostScope;
+  readonly id: string;
+  readonly budget: number;
+  readonly actual: number;
+  readonly currency: string;
+}) => void;
+
+/**
+ * Configuration shape for {@link createCostTracker}.
+ *
+ * @stable
+ */
+export interface CostTrackerOptions {
+  readonly budgets?: CostBudgets;
+  readonly onExceed?: CostBudgetExceededCallback;
+  /**
+   * W-092: memory bound for the tracker's internal maps. The tracker
+   * aggregates for the LIFETIME of the process - exactly the
+   * long-running-assistant scenario - so unbounded per-span / per-scope
+   * maps are a leak. When an insertion pushes a map past its limit the
+   * OLDEST entries (insertion order, not LRU) are evicted and
+   * `onEviction` fires per dropped id; `usage()` / `usageForSpan()` for
+   * an evicted id then report zero figures, and a late rollup to an
+   * evicted ancestor re-creates it from zero. Defaults to
+   * `{ maxSpanEntries: 10_000, maxScopeEntries: 10_000 }`; pass `false`
+   * to restore the previous unbounded behaviour.
+   */
+  readonly retention?:
+    | {
+        readonly maxSpanEntries?: number;
+        /** Per scope-kind cap (each of run/session/agent/user maps). */
+        readonly maxScopeEntries?: number;
+      }
+    | false;
+  /** W-092: observer for retention evictions (dashboards / warnings). */
+  readonly onEviction?: (event: {
+    readonly surface: 'span' | CostScope;
+    readonly id: string;
+  }) => void;
+}