apcore-js 0.1.0

package/planning/observability/plan.md

@@ -0,0 +1,119 @@
+# Implementation Plan: Observability
+
+## Goal
+
+Implement the three pillars of observability -- tracing, metrics, and logging -- as middleware-integrated components that provide runtime visibility into the apcore execution pipeline. Each pillar operates through a `Middleware` subclass that uses stack-based state in the shared `context.data` record to handle nested module-to-module calls correctly.
+
+## Architecture Design
+
+### Component Structure
+
+The observability module is organized into three source files, each housing one pillar and its associated middleware:
+
+- **Tracing** (`observability/tracing.ts`, ~190 lines) -- `Span` interface describing a trace span with `traceId`, `spanId`, `parentSpanId`, timing, status, attributes, and events. `createSpan()` factory function generates spans with `randomBytes(8).toString('hex')` for span IDs. `SpanExporter` interface with two implementations: `StdoutExporter` (JSON.stringify to console.log) and `InMemoryExporter` (bounded array, shift()-based eviction, configurable max 10,000). `TracingMiddleware` extends `Middleware` with stack-based span management and 4 sampling strategies.
+
+- **Metrics** (`observability/metrics.ts`, ~210 lines) -- `MetricsCollector` class with counter (`increment`) and histogram (`observe`) primitives. Uses string-encoded composite keys in the format `name|key1=val1,key2=val2` stored in `Map<string, number>`. No thread locking required (Node.js single-threaded). Histogram support with configurable buckets (13 Prometheus-standard defaults), `+Inf` bucket, and full Prometheus text format export. Convenience methods `incrementCalls()`, `incrementErrors()`, `observeDuration()` for apcore-standard metrics. `MetricsMiddleware` extends `Middleware` with stack-based `performance.now()` timing.
+
+- **Logging** (`observability/context-logger.ts`, ~200 lines) -- `ContextLogger` class with 6 log levels (trace/debug/info/warn/error/fatal mapped to numeric values 0-50), JSON and text output formats, automatic `_secret_`-prefixed key redaction, and `fromContext()` static factory that binds trace ID, module ID, and caller ID. Output targets a `WritableOutput` interface (defaults to `process.stderr`). `ObsLoggingMiddleware` extends `Middleware` with stack-based timing and configurable input/output logging.
+
+### Three Pillars Architecture
+
+```
+                    Executor Pipeline
+                         |
+          +--------------+--------------+
+          |              |              |
+   TracingMiddleware  MetricsMiddleware  ObsLoggingMiddleware
+          |              |              |
+     SpanExporter   MetricsCollector   ContextLogger
+     /        \          |              |
+StdoutExp  InMemoryExp  Prometheus    JSON/Text
+                        Export        Output
+```
+
+### Data Flow
+
+Each middleware hooks into the executor pipeline at three points: `before()`, `after()`, and `onError()`. State is carried across nested calls via the shared `context.data` record using reserved keys:
+
+1. **TracingMiddleware** stores a span stack at `context.data['_tracing_spans']` and a sampling decision at `context.data['_tracing_sampled']`. On `before()`, a new span is created and pushed onto the stack with the current top-of-stack span as parent. On `after()`/`onError()`, the span is popped, finalized with end time and status, and conditionally exported based on the sampling decision.
+
+2. **MetricsMiddleware** stores a timing stack at `context.data['_metrics_starts']`. On `before()`, `performance.now()` is pushed. On `after()`/`onError()`, the start time is popped and duration computed as `(performance.now() - startTime) / 1000` (converted to seconds for Prometheus conventions).
+
+3. **ObsLoggingMiddleware** stores a timing stack at `context.data['_obs_logging_starts']`. On `before()`, `performance.now()` is pushed and a "Module call started" log entry is emitted. On `after()`, the start time is popped, duration computed in milliseconds, and "Module call completed" is emitted. On `onError()`, "Module call failed" is emitted with error details.
+
+### Technical Choices and Rationale
+
+- **`performance.now()` for timing**: Provides monotonic millisecond resolution. Unlike `Date.now()`, it is not affected by system clock adjustments. Unlike Python's `time.time()` (wall-clock seconds), this returns monotonic milliseconds, so MetricsMiddleware divides by 1000 for Prometheus-standard seconds.
+
+- **String-encoded composite keys**: `MetricsCollector` stores counters and histogram data using keys in the format `name|key1=val1,key2=val2`. This avoids the overhead of nested Maps or object hashing and allows simple Map lookups. Labels are sorted alphabetically for deterministic key generation.
+
+- **No thread locking**: Node.js runs JavaScript on a single thread. Unlike the Python implementation which requires threading locks for metric state, no synchronization primitives are needed here.
+
+- **`randomBytes(8).toString('hex')` for span IDs**: Produces 16-character hex strings (64 bits of entropy). Uses Node.js `node:crypto` for cryptographic randomness rather than `crypto.randomUUID().slice(0,16)` to avoid partial UUID collisions.
+
+- **Bounded array with `shift()` for InMemoryExporter**: Simple FIFO eviction. Python uses `collections.deque(maxlen=...)` which is O(1) for left-pop; JavaScript `Array.shift()` is O(n) but acceptable for the expected span volumes. A ring buffer could be a future optimization.
+
+- **No OTel bridge**: An `OTLPExporter` is not yet implemented. The `SpanExporter` interface is designed to be compatible with future OpenTelemetry integration, but no OTel SDK dependency exists today.
+
+- **`WritableOutput` interface for logger**: Abstracts the output target to support both `process.stderr` (default) and test buffers. Avoids coupling to Node.js streams directly.
+
+## Task Breakdown
+
+```mermaid
+graph TD
+    T1[span-model] --> T2[exporters]
+    T1 --> T3[tracing-middleware]
+    T2 --> T3
+    T4[metrics-collector] --> T5[metrics-middleware]
+    T6[context-logger] --> T7[obs-logging-middleware]
+```
+
+| Task ID | Title | Estimated Time | Dependencies |
+|---------|-------|---------------|--------------|
+| span-model | Span interface and createSpan() factory | 1h | none |
+| exporters | StdoutExporter and InMemoryExporter | 1.5h | span-model |
+| tracing-middleware | TracingMiddleware with sampling strategies | 3h | span-model, exporters |
+| metrics-collector | MetricsCollector with Prometheus export | 3h | none |
+| metrics-middleware | MetricsMiddleware with stack-based timing | 2h | metrics-collector |
+| context-logger | ContextLogger with formats and redaction | 2h | none |
+| obs-logging-middleware | ObsLoggingMiddleware with structured logging | 2h | context-logger |
+
+## Risks and Considerations
+
+- **`Array.shift()` performance in InMemoryExporter**: Eviction via `shift()` is O(n) per call when the buffer is full. For high-throughput tracing with maxSpans in the thousands, this is acceptable. If maxSpans grows to tens of thousands, consider a ring buffer implementation.
+- **Missing OTLPExporter**: Production deployments expecting OpenTelemetry Protocol export will need a custom `SpanExporter` implementation or a future `OTLPExporter` addition. The `SpanExporter` interface is stable and ready for this extension.
+- **Prometheus export is in-memory only**: `MetricsCollector.exportPrometheus()` generates text on demand. There is no HTTP endpoint or push gateway integration. Consumers must call `exportPrometheus()` and serve or ship the output themselves.
+- **Sampling decision propagation**: The `_tracing_sampled` flag is set once per context (on first `before()` call) and inherited by all nested spans. This means proportional sampling is all-or-nothing per trace, not per span. The `error_first` strategy overrides this by always exporting error spans regardless of the sampling decision.
+- **Logger output blocking**: `process.stderr.write()` is synchronous for small payloads on most platforms. High-volume logging could introduce backpressure in latency-sensitive paths.
+
+## Acceptance Criteria
+
+- [x] `Span` interface defines all required fields (traceId, spanId, parentSpanId, name, startTime, endTime, status, attributes, events)
+- [x] `createSpan()` generates unique 16-hex-char span IDs via `randomBytes(8).toString('hex')`
+- [x] `StdoutExporter` serializes spans via `JSON.stringify` to `console.log`
+- [x] `InMemoryExporter` respects `maxSpans` limit with FIFO eviction via `shift()`
+- [x] `InMemoryExporter.getSpans()` returns a defensive copy (spread into new array)
+- [x] `TracingMiddleware` supports all 4 sampling strategies: full, proportional, error_first, off
+- [x] `TracingMiddleware` validates sampling rate (0.0-1.0) and strategy on construction
+- [x] Nested spans correctly chain via `parentSpanId` using stack-based management
+- [x] `error_first` strategy always exports error spans even when not sampled
+- [x] `MetricsCollector` supports counter increment and histogram observe operations
+- [x] String-encoded keys use sorted labels for deterministic composite key generation
+- [x] `exportPrometheus()` produces valid Prometheus text format with HELP, TYPE, buckets, sum, count
+- [x] `MetricsMiddleware` records calls, errors, and duration via stack-based timing
+- [x] Duration is converted from milliseconds to seconds for Prometheus conventions
+- [x] `ContextLogger` supports JSON and text output formats with level filtering
+- [x] `_secret_`-prefixed keys are automatically redacted to `***REDACTED***`
+- [x] `fromContext()` binds traceId, moduleId, and callerId from a `Context` instance
+- [x] `ObsLoggingMiddleware` emits structured start/complete/error log entries with timing
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## References
+
+- `src/observability/tracing.ts` -- Span model, exporters, and TracingMiddleware
+- `src/observability/metrics.ts` -- MetricsCollector and MetricsMiddleware
+- `src/observability/context-logger.ts` -- ContextLogger and ObsLoggingMiddleware
+- `src/observability/index.ts` -- Public API barrel exports
+- `tests/observability/test-tracing.test.ts` -- Tracing tests
+- `tests/observability/test-metrics.test.ts` -- Metrics tests
+- `tests/observability/test-context-logger.test.ts` -- Logger tests

package/planning/observability/state.json

@@ -0,0 +1,98 @@
+{
+  "feature": "observability",
+  "created": "2026-02-16T00:00:00Z",
+  "updated": "2026-02-16T00:00:00Z",
+  "status": "completed",
+  "execution_order": [
+    "span-model",
+    "exporters",
+    "tracing-middleware",
+    "metrics-collector",
+    "metrics-middleware",
+    "context-logger",
+    "obs-logging-middleware"
+  ],
+  "progress": {
+    "total_tasks": 7,
+    "completed": 7,
+    "in_progress": 0,
+    "pending": 0
+  },
+  "tasks": [
+    {
+      "id": "span-model",
+      "file": "tasks/span-model.md",
+      "title": "Span Interface and createSpan() Factory",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T09:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "exporters",
+      "file": "tasks/exporters.md",
+      "title": "StdoutExporter and InMemoryExporter",
+      "status": "completed",
+      "started_at": "2026-02-16T09:00:00Z",
+      "completed_at": "2026-02-16T10:30:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "tracing-middleware",
+      "file": "tasks/tracing-middleware.md",
+      "title": "TracingMiddleware with Sampling Strategies",
+      "status": "completed",
+      "started_at": "2026-02-16T10:30:00Z",
+      "completed_at": "2026-02-16T13:30:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "metrics-collector",
+      "file": "tasks/metrics-collector.md",
+      "title": "MetricsCollector with Counters, Histograms, Prometheus Export",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T11:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "metrics-middleware",
+      "file": "tasks/metrics-middleware.md",
+      "title": "MetricsMiddleware with Stack-Based Timing",
+      "status": "completed",
+      "started_at": "2026-02-16T11:00:00Z",
+      "completed_at": "2026-02-16T13:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "context-logger",
+      "file": "tasks/context-logger.md",
+      "title": "ContextLogger with JSON/Text Formats and Redaction",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T10:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "obs-logging-middleware",
+      "file": "tasks/obs-logging-middleware.md",
+      "title": "ObsLoggingMiddleware with Structured Logging",
+      "status": "completed",
+      "started_at": "2026-02-16T10:00:00Z",
+      "completed_at": "2026-02-16T12:00:00Z",
+      "assignee": null,
+      "commits": []
+    }
+  ],
+  "metadata": {
+    "source_doc": "planning/features/observability.md",
+    "created_by": "code-forge",
+    "version": "1.0"
+  }
+}

package/planning/observability/tasks/context-logger.md

@@ -0,0 +1,201 @@
+# Task: ContextLogger with JSON/Text Formats and Redaction
+
+## Goal
+
+Implement `ContextLogger` that provides structured logging with JSON and text output formats, numeric level filtering (trace/debug/info/warn/error/fatal), automatic redaction of `_secret_`-prefixed keys, and a `fromContext()` static factory method that binds trace, module, and caller metadata from a `Context` instance.
+
+## Files Involved
+
+- `src/observability/context-logger.ts` -- ContextLogger class, LEVELS map, WritableOutput interface
+- `src/context.ts` -- Context class (dependency for `fromContext()`)
+- `tests/observability/test-context-logger.test.ts` -- Unit tests for ContextLogger
+
+## Steps (TDD)
+
+### 1. Write failing tests for basic logging
+
+```typescript
+function createBufferOutput() {
+  const lines: string[] = [];
+  return {
+    output: { write: (s: string) => lines.push(s) },
+    lines,
+  };
+}
+
+describe('ContextLogger', () => {
+  it('logs JSON format by default', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ output });
+    logger.info('test message');
+    expect(lines).toHaveLength(1);
+    const parsed = JSON.parse(lines[0]);
+    expect(parsed.level).toBe('info');
+    expect(parsed.message).toBe('test message');
+    expect(parsed.timestamp).toBeDefined();
+    expect(parsed.logger).toBe('apcore');
+  });
+
+  it('logs text format', () => {
+    const { output, lines } = createBufferOutput();
+    const logger = new ContextLogger({ format: 'text', output });
+    logger.info('test message');
+    expect(lines[0]).toContain('[INFO]');
+    expect(lines[0]).toContain('test message');
+  });
+});
+```
+
+### 2. Define WritableOutput interface and level map
+
+```typescript
+interface WritableOutput {
+  write(s: string): void;
+}
+
+const LEVELS: Record<string, number> = {
+  trace: 0,
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50,
+};
+```
+
+### 3. Implement ContextLogger constructor with options
+
+```typescript
+export class ContextLogger {
+  constructor(options?: {
+    name?: string;      // default: 'apcore'
+    format?: string;    // 'json' (default) or 'text'
+    level?: string;     // minimum level, default: 'info'
+    redactSensitive?: boolean;  // default: true
+    output?: WritableOutput;    // default: process.stderr
+  }) { /* ... */ }
+}
+```
+
+### 4. Write failing tests for level filtering
+
+```typescript
+it('respects log level filtering', () => {
+  const { output, lines } = createBufferOutput();
+  const logger = new ContextLogger({ level: 'warn', output });
+  logger.debug('should not appear');
+  logger.info('should not appear');
+  logger.warn('should appear');
+  logger.error('should appear');
+  expect(lines).toHaveLength(2);
+});
+```
+
+### 5. Implement _emit() with level check and dual format output
+
+The internal `_emit()` method:
+1. Checks if the message level meets the minimum threshold
+2. Redacts `_secret_`-prefixed keys in the `extra` record if `redactSensitive` is true
+3. Builds a log entry record with `timestamp`, `level`, `message`, `trace_id`, `module_id`, `caller_id`, `logger`, `extra`
+4. Serializes as JSON (`JSON.stringify + newline`) or text (`timestamp [LEVEL] [trace=...] [module=...] message extras`)
+
+### 6. Write failing tests for redaction
+
+```typescript
+it('redacts _secret_ prefix keys', () => {
+  const { output, lines } = createBufferOutput();
+  const logger = new ContextLogger({ output });
+  logger.info('test', { _secret_token: 'abc123', name: 'Bob' });
+  const parsed = JSON.parse(lines[0]);
+  expect(parsed.extra._secret_token).toBe('***REDACTED***');
+  expect(parsed.extra.name).toBe('Bob');
+});
+
+it('does not redact when disabled', () => {
+  const { output, lines } = createBufferOutput();
+  const logger = new ContextLogger({ output, redactSensitive: false });
+  logger.info('test', { _secret_token: 'abc123' });
+  const parsed = JSON.parse(lines[0]);
+  expect(parsed.extra._secret_token).toBe('abc123');
+});
+```
+
+### 7. Implement _secret_ redaction in _emit()
+
+```typescript
+if (extra != null && this._redactSensitive) {
+  redactedExtra = {};
+  for (const [k, v] of Object.entries(extra)) {
+    redactedExtra[k] = k.startsWith('_secret_') ? '***REDACTED***' : v;
+  }
+}
+```
+
+### 8. Write failing tests for fromContext()
+
+```typescript
+it('fromContext sets trace/module/caller', () => {
+  const { output, lines } = createBufferOutput();
+  const ctx = Context.create(undefined, createIdentity('user1'));
+  const childCtx = ctx.child('mod.test');
+  const logger = ContextLogger.fromContext(childCtx, 'test-logger', { output });
+  logger.info('context log');
+  const parsed = JSON.parse(lines[0]);
+  expect(parsed.trace_id).toBe(ctx.traceId);
+  expect(parsed.module_id).toBe('mod.test');
+  expect(parsed.logger).toBe('test-logger');
+});
+```
+
+### 9. Implement fromContext() static factory
+
+```typescript
+static fromContext(context: Context, name: string, options?: {
+  format?: string;
+  level?: string;
+  redactSensitive?: boolean;
+  output?: WritableOutput;
+}): ContextLogger {
+  const logger = new ContextLogger({ name, ...options });
+  logger._traceId = context.traceId;
+  logger._moduleId = context.callChain.length > 0
+    ? context.callChain[context.callChain.length - 1]
+    : null;
+  logger._callerId = context.callerId;
+  return logger;
+}
+```
+
+### 10. Implement all 6 log level methods
+
+```typescript
+trace(message: string, extra?: Record<string, unknown>): void { this._emit('trace', message, extra); }
+debug(message: string, extra?: Record<string, unknown>): void { this._emit('debug', message, extra); }
+info(message: string, extra?: Record<string, unknown>): void { this._emit('info', message, extra); }
+warn(message: string, extra?: Record<string, unknown>): void { this._emit('warn', message, extra); }
+error(message: string, extra?: Record<string, unknown>): void { this._emit('error', message, extra); }
+fatal(message: string, extra?: Record<string, unknown>): void { this._emit('fatal', message, extra); }
+```
+
+### 11. Run tests and verify all pass
+
+## Acceptance Criteria
+
+- [x] `ContextLogger` supports JSON (default) and text output formats
+- [x] 6 log levels: trace (0), debug (10), info (20), warn (30), error (40), fatal (50)
+- [x] Level filtering suppresses messages below the configured minimum level
+- [x] `_secret_`-prefixed extra keys redacted to `***REDACTED***` when `redactSensitive` is true (default)
+- [x] Redaction can be disabled via `redactSensitive: false`
+- [x] `fromContext()` binds `traceId`, `moduleId` (last in callChain), and `callerId` from a Context
+- [x] JSON format includes: timestamp, level, message, trace_id, module_id, caller_id, logger, extra
+- [x] Text format: `timestamp [LEVEL] [trace=...] [module=...] message extras`
+- [x] Default output is `process.stderr`; custom `WritableOutput` accepted via options
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- None (independent pillar, but uses `Context` from core-executor for `fromContext()`)
+
+## Estimated Time
+
+2 hours

package/planning/observability/tasks/exporters.md

@@ -0,0 +1,121 @@
+# Task: StdoutExporter and InMemoryExporter
+
+## Goal
+
+Implement two `SpanExporter` implementations: `StdoutExporter` that serializes spans to stdout via `JSON.stringify`, and `InMemoryExporter` that stores spans in a bounded array with FIFO eviction. Note: `OTLPExporter` (OpenTelemetry Protocol) is not implemented -- this is a known gap for future work.
+
+## Files Involved
+
+- `src/observability/tracing.ts` -- StdoutExporter and InMemoryExporter classes
+- `tests/observability/test-tracing.test.ts` -- Unit tests for both exporters
+
+## Steps (TDD)
+
+### 1. Write failing tests for InMemoryExporter
+
+```typescript
+describe('InMemoryExporter', () => {
+  it('collects and retrieves spans', () => {
+    const exporter = new InMemoryExporter();
+    const span = createSpan({ traceId: 't1', name: 'test', startTime: 0 });
+    exporter.export(span);
+    expect(exporter.getSpans()).toHaveLength(1);
+    expect(exporter.getSpans()[0].traceId).toBe('t1');
+  });
+
+  it('respects max_spans limit', () => {
+    const exporter = new InMemoryExporter(3);
+    for (let i = 0; i < 5; i++) {
+      exporter.export(createSpan({ traceId: `t${i}`, name: 'test', startTime: i }));
+    }
+    const spans = exporter.getSpans();
+    expect(spans).toHaveLength(3);
+    expect(spans[0].traceId).toBe('t2'); // oldest evicted
+  });
+
+  it('clear removes all spans', () => {
+    const exporter = new InMemoryExporter();
+    exporter.export(createSpan({ traceId: 't1', name: 'test', startTime: 0 }));
+    exporter.clear();
+    expect(exporter.getSpans()).toHaveLength(0);
+  });
+
+  it('getSpans returns defensive copy', () => {
+    const exporter = new InMemoryExporter();
+    exporter.export(createSpan({ traceId: 't1', name: 'test', startTime: 0 }));
+    const spans = exporter.getSpans();
+    spans.pop(); // mutate the copy
+    expect(exporter.getSpans()).toHaveLength(1); // original unaffected
+  });
+});
+```
+
+### 2. Implement StdoutExporter
+
+```typescript
+export class StdoutExporter implements SpanExporter {
+  export(span: Span): void {
+    console.log(JSON.stringify(span));
+  }
+}
+```
+
+Simple passthrough: serialize the span as a JSON string and write to stdout via `console.log`. No buffering or batching.
+
+### 3. Implement InMemoryExporter
+
+```typescript
+export class InMemoryExporter implements SpanExporter {
+  private _spans: Span[] = [];
+  private _maxSpans: number;
+
+  constructor(maxSpans: number = 10_000) {
+    this._maxSpans = maxSpans;
+  }
+
+  export(span: Span): void {
+    this._spans.push(span);
+    while (this._spans.length > this._maxSpans) {
+      this._spans.shift(); // FIFO eviction
+    }
+  }
+
+  getSpans(): Span[] {
+    return [...this._spans]; // defensive copy
+  }
+
+  clear(): void {
+    this._spans = [];
+  }
+}
+```
+
+Key design decisions:
+- Default `maxSpans` of 10,000 (configurable via constructor)
+- `shift()` for FIFO eviction (O(n) but acceptable for expected volumes, unlike Python's O(1) `deque.popleft()`)
+- `getSpans()` returns a spread copy to prevent external mutation of internal state
+- No thread locking needed (Node.js single-threaded)
+
+### 4. Run tests and verify all pass
+
+## Known Gap: OTLPExporter
+
+The Python implementation includes an `OTLPExporter` for shipping spans to OpenTelemetry-compatible backends. This is **not yet implemented** in the TypeScript version. The `SpanExporter` interface is designed to be forward-compatible -- a future `OTLPExporter` would implement `export(span: Span): void` and handle HTTP/gRPC transport to an OTLP collector.
+
+## Acceptance Criteria
+
+- [x] `StdoutExporter` implements `SpanExporter` and calls `console.log(JSON.stringify(span))`
+- [x] `InMemoryExporter` stores spans in a bounded array with configurable `maxSpans` (default 10,000)
+- [x] FIFO eviction via `shift()` when array exceeds `maxSpans`
+- [x] `getSpans()` returns a defensive copy via spread operator
+- [x] `clear()` empties the internal span array
+- [x] OTLPExporter absence is documented as a known gap
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- **span-model** -- Requires `Span` interface and `SpanExporter` interface
+
+## Estimated Time
+
+1.5 hours