apcore-js 0.5.0 → 0.7.0

package/planning/observability/plan.md

@@ -1,119 +0,0 @@
-# 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

@@ -1,98 +0,0 @@
-{
-  "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

@@ -1,201 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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