apcore-js 0.5.0 → 0.7.0

package/planning/observability/tasks/metrics-collector.md

@@ -1,162 +0,0 @@
-# Task: MetricsCollector with Counters, Histograms, and Prometheus Export
-
-## Goal
-
-Implement `MetricsCollector` that provides in-memory counter and histogram metric primitives with string-encoded composite keys, configurable histogram buckets, and Prometheus text format export. Includes convenience methods for apcore-standard metrics (calls, errors, duration).
-
-## Files Involved
-
-- `src/observability/metrics.ts` -- MetricsCollector class, labelsKey(), parseLabels(), formatLabels() helpers
-- `tests/observability/test-metrics.test.ts` -- Unit tests for MetricsCollector
-
-## Steps (TDD)
-
-### 1. Write failing tests for counter operations
-
-```typescript
-describe('MetricsCollector', () => {
-  it('increments counters', () => {
-    const collector = new MetricsCollector();
-    collector.increment('test_counter', { method: 'GET' });
-    collector.increment('test_counter', { method: 'GET' });
-    const snap = collector.snapshot();
-    expect(snap.counters['test_counter|method=GET']).toBe(2);
-  });
-
-  it('supports custom increment amounts', () => {
-    const collector = new MetricsCollector();
-    collector.increment('test_counter', { method: 'POST' }, 5);
-    const snap = collector.snapshot();
-    expect(snap.counters['test_counter|method=POST']).toBe(5);
-  });
-});
-```
-
-### 2. Implement string-encoded key system
-
-Labels are encoded as sorted key-value pairs joined by commas:
-
-```typescript
-function labelsKey(labels: Record<string, string>): string {
-  return Object.entries(labels)
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([k, v]) => `${k}=${v}`)
-    .join(',');
-}
-```
-
-Composite keys use the format `name|key1=val1,key2=val2`. Sorting ensures deterministic keys regardless of insertion order. No thread locking is needed because Node.js is single-threaded (unlike the Python implementation which requires locks).
-
-### 3. Implement counter increment
-
-```typescript
-increment(name: string, labels: Record<string, string>, amount: number = 1): void {
-  const key = `${name}|${labelsKey(labels)}`;
-  this._counters.set(key, (this._counters.get(key) ?? 0) + amount);
-}
-```
-
-### 4. Write failing tests for histogram operations
-
-```typescript
-it('observes histogram values', () => {
-  const collector = new MetricsCollector();
-  collector.observe('test_hist', { module: 'a' }, 0.05);
-  collector.observe('test_hist', { module: 'a' }, 0.5);
-  const snap = collector.snapshot();
-  expect(snap.histograms.sums['test_hist|module=a']).toBeCloseTo(0.55);
-  expect(snap.histograms.counts['test_hist|module=a']).toBe(2);
-});
-```
-
-### 5. Implement histogram observe with bucket tracking
-
-```typescript
-observe(name: string, labels: Record<string, string>, value: number): void {
-  const lk = labelsKey(labels);
-  const key = `${name}|${lk}`;
-  this._histogramSums.set(key, (this._histogramSums.get(key) ?? 0) + value);
-  this._histogramCounts.set(key, (this._histogramCounts.get(key) ?? 0) + 1);
-
-  for (const b of this._buckets) {
-    if (value <= b) {
-      const bkey = `${name}|${lk}|${b}`;
-      this._histogramBuckets.set(bkey, (this._histogramBuckets.get(bkey) ?? 0) + 1);
-    }
-  }
-  const infKey = `${name}|${lk}|Inf`;
-  this._histogramBuckets.set(infKey, (this._histogramBuckets.get(infKey) ?? 0) + 1);
-}
-```
-
-Default buckets follow Prometheus conventions: `[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0]`.
-
-### 6. Write failing tests for Prometheus export
-
-```typescript
-it('exportPrometheus produces valid format', () => {
-  const collector = new MetricsCollector();
-  collector.incrementCalls('mod.a', 'success');
-  collector.observeDuration('mod.a', 0.05);
-  const output = collector.exportPrometheus();
-  expect(output).toContain('# HELP apcore_module_calls_total Total module calls');
-  expect(output).toContain('# TYPE apcore_module_calls_total counter');
-  expect(output).toContain('# TYPE apcore_module_duration_seconds histogram');
-  expect(output).toContain('_bucket{');
-  expect(output).toContain('le="+Inf"');
-  expect(output).toContain('_sum{');
-  expect(output).toContain('_count{');
-});
-
-it('empty collector returns empty prometheus string', () => {
-  const collector = new MetricsCollector();
-  expect(collector.exportPrometheus()).toBe('');
-});
-```
-
-### 7. Implement exportPrometheus()
-
-Generates Prometheus text format with:
-- `# HELP` and `# TYPE` headers (emitted once per metric name)
-- Counter lines: `metric_name{label="value"} count`
-- Histogram lines: `_bucket{...,le="bound"}`, `_sum{...}`, `_count{...}`
-- Labels formatted as `{key="value",le="bound"}` with `le` sorted last
-
-### 8. Implement convenience methods and snapshot/reset
-
-```typescript
-incrementCalls(moduleId: string, status: string): void {
-  this.increment('apcore_module_calls_total', { module_id: moduleId, status });
-}
-incrementErrors(moduleId: string, errorCode: string): void {
-  this.increment('apcore_module_errors_total', { module_id: moduleId, error_code: errorCode });
-}
-observeDuration(moduleId: string, durationSeconds: number): void {
-  this.observe('apcore_module_duration_seconds', { module_id: moduleId }, durationSeconds);
-}
-```
-
-### 9. Run tests and verify all pass
-
-## Acceptance Criteria
-
-- [x] `MetricsCollector` stores counters in `Map<string, number>` with string-encoded composite keys
-- [x] `increment()` supports custom amounts (default 1)
-- [x] `observe()` tracks histogram sums, counts, and per-bucket cumulative counts
-- [x] Default histogram buckets match Prometheus standard (13 values + Inf)
-- [x] Custom bucket arrays accepted and sorted on construction
-- [x] `exportPrometheus()` produces valid Prometheus text format with HELP, TYPE, buckets, sum, count
-- [x] Labels sorted alphabetically with `le` last in histogram bucket lines
-- [x] `snapshot()` returns counters and histograms as plain objects
-- [x] `reset()` clears all internal state
-- [x] Convenience methods `incrementCalls()`, `incrementErrors()`, `observeDuration()` use apcore-standard metric names
-- [x] No thread locking (Node.js single-threaded -- differs from Python implementation)
-- [x] All tests pass with `vitest`
-
-## Dependencies
-
-- None (independent pillar)
-
-## Estimated Time
-
-3 hours

package/planning/observability/tasks/metrics-middleware.md

@@ -1,141 +0,0 @@
-# Task: MetricsMiddleware with Stack-Based Timing
-
-## Goal
-
-Implement `MetricsMiddleware` that extends the `Middleware` base class to automatically record call counts, error counts, and execution duration for every module call. Uses a stack-based timing approach via `performance.now()` stored in `context.data` to correctly handle nested module-to-module calls.
-
-## Files Involved
-
-- `src/observability/metrics.ts` -- MetricsMiddleware class
-- `src/middleware/base.ts` -- Middleware base class (dependency)
-- `src/context.ts` -- Context class with shared `data` record (dependency)
-- `src/errors.ts` -- ModuleError for error code extraction (dependency)
-- `tests/observability/test-metrics.test.ts` -- Unit tests for MetricsMiddleware
-
-## Steps (TDD)
-
-### 1. Write failing tests for success path
-
-```typescript
-describe('MetricsMiddleware', () => {
-  it('records call metrics on success', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap.counters as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
-  });
-});
-```
-
-### 2. Write failing tests for error path
-
-```typescript
-  it('records error metrics on failure', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap.counters as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=error']).toBe(1);
-    expect(counters['apcore_module_errors_total|error_code=Error,module_id=mod.a']).toBe(1);
-  });
-```
-
-### 3. Implement before() with stack-based timing
-
-```typescript
-export class MetricsMiddleware extends Middleware {
-  private _collector: MetricsCollector;
-
-  constructor(collector: MetricsCollector) {
-    super();
-    this._collector = collector;
-  }
-
-  override before(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = (context.data['_metrics_starts'] as number[]) ?? [];
-    starts.push(performance.now());
-    context.data['_metrics_starts'] = starts;
-    return null;
-  }
-}
-```
-
-The timing stack at `context.data['_metrics_starts']` is an array of `performance.now()` values. Each `before()` pushes the current time, and the corresponding `after()`/`onError()` pops it. This stack-based approach correctly pairs start/end times even for nested calls (A calls B calls C).
-
-### 4. Implement after() with duration conversion
-
-```typescript
-override after(
-  moduleId: string,
-  _inputs: Record<string, unknown>,
-  _output: Record<string, unknown>,
-  context: Context,
-): null {
-  const starts = context.data['_metrics_starts'] as number[];
-  const startTime = starts.pop()!;
-  const durationS = (performance.now() - startTime) / 1000;
-  this._collector.incrementCalls(moduleId, 'success');
-  this._collector.observeDuration(moduleId, durationS);
-  return null;
-}
-```
-
-Key detail: `performance.now()` returns monotonic milliseconds, but Prometheus conventions use seconds. The division by 1000 converts to seconds. This differs from Python's `time.time()` which returns wall-clock seconds directly.
-
-### 5. Implement onError() with error code extraction
-
-```typescript
-override onError(
-  moduleId: string,
-  _inputs: Record<string, unknown>,
-  error: Error,
-  context: Context,
-): null {
-  const starts = context.data['_metrics_starts'] as number[];
-  const startTime = starts.pop()!;
-  const durationS = (performance.now() - startTime) / 1000;
-  const errorCode = error instanceof ModuleError ? error.code : error.constructor.name;
-  this._collector.incrementCalls(moduleId, 'error');
-  this._collector.incrementErrors(moduleId, errorCode);
-  this._collector.observeDuration(moduleId, durationS);
-  return null;
-}
-```
-
-Error code is extracted from `ModuleError.code` (structured apcore errors) or falls back to `error.constructor.name` (generic JS errors).
-
-### 6. Run tests and verify all pass
-
-## Acceptance Criteria
-
-- [x] `MetricsMiddleware` extends `Middleware` and accepts a `MetricsCollector` instance
-- [x] `before()` pushes `performance.now()` onto `context.data['_metrics_starts']` stack
-- [x] `after()` pops start time, computes duration in seconds, records success call + duration
-- [x] `onError()` pops start time, computes duration, records error call + error count + duration
-- [x] Duration converted from milliseconds to seconds (`/ 1000`) for Prometheus conventions
-- [x] Error code extracted from `ModuleError.code` or `error.constructor.name`
-- [x] Stack-based timing correctly handles nested module calls
-- [x] All tests pass with `vitest`
-
-## Dependencies
-
-- **metrics-collector** -- Requires `MetricsCollector` class
-
-## Estimated Time
-
-2 hours

package/planning/observability/tasks/obs-logging-middleware.md

@@ -1,179 +0,0 @@
-# Task: ObsLoggingMiddleware with Stack-Based Timing
-
-## Goal
-
-Implement `ObsLoggingMiddleware` that extends the `Middleware` base class to provide structured logging of module call lifecycle events (start, complete, error) with stack-based `performance.now()` timing and configurable input/output logging. Delegates all log output to a `ContextLogger` instance.
-
-## Files Involved
-
-- `src/observability/context-logger.ts` -- ObsLoggingMiddleware class
-- `src/middleware/base.ts` -- Middleware base class (dependency)
-- `src/context.ts` -- Context class with shared `data` record (dependency)
-- `tests/observability/test-context-logger.test.ts` -- Unit tests for ObsLoggingMiddleware
-
-## Steps (TDD)
-
-### 1. Write failing tests for before/after lifecycle
-
-```typescript
-describe('ObsLoggingMiddleware', () => {
-  it('logs before and after', () => {
-    const { output, lines } = createBufferOutput();
-    const logger = new ContextLogger({ output });
-    const mw = new ObsLoggingMiddleware({ logger });
-    const ctx = Context.create();
-
-    mw.before('mod.a', { name: 'Alice' }, ctx);
-    mw.after('mod.a', { name: 'Alice' }, { result: 'ok' }, ctx);
-
-    expect(lines).toHaveLength(2);
-    const before = JSON.parse(lines[0]);
-    const after = JSON.parse(lines[1]);
-    expect(before.message).toBe('Module call started');
-    expect(before.extra.module_id).toBe('mod.a');
-    expect(after.message).toBe('Module call completed');
-    expect(after.extra.duration_ms).toBeDefined();
-  });
-});
-```
-
-### 2. Write failing tests for error lifecycle
-
-```typescript
-  it('logs onError', () => {
-    const { output, lines } = createBufferOutput();
-    const logger = new ContextLogger({ output });
-    const mw = new ObsLoggingMiddleware({ logger });
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    expect(lines).toHaveLength(2);
-    const errorLog = JSON.parse(lines[1]);
-    expect(errorLog.message).toBe('Module call failed');
-    expect(errorLog.extra.error_type).toBe('Error');
-    expect(errorLog.extra.duration_ms).toBeDefined();
-  });
-```
-
-### 3. Implement constructor with configurable options
-
-```typescript
-export class ObsLoggingMiddleware extends Middleware {
-  private _logger: ContextLogger;
-  private _logInputs: boolean;
-  private _logOutputs: boolean;
-
-  constructor(options?: {
-    logger?: ContextLogger;
-    logInputs?: boolean;   // default: true
-    logOutputs?: boolean;  // default: true
-  }) {
-    super();
-    this._logger = options?.logger ?? new ContextLogger({ name: 'apcore.obs_logging' });
-    this._logInputs = options?.logInputs ?? true;
-    this._logOutputs = options?.logOutputs ?? true;
-  }
-}
-```
-
-### 4. Implement before() with stack-based timing and start log
-
-```typescript
-override before(
-  moduleId: string,
-  inputs: Record<string, unknown>,
-  context: Context,
-): null {
-  const starts = (context.data['_obs_logging_starts'] as number[]) ?? [];
-  starts.push(performance.now());
-  context.data['_obs_logging_starts'] = starts;
-
-  const extra: Record<string, unknown> = {
-    module_id: moduleId,
-    caller_id: context.callerId,
-  };
-  if (this._logInputs) {
-    extra['inputs'] = context.redactedInputs ?? inputs;
-  }
-  this._logger.info('Module call started', extra);
-  return null;
-}
-```
-
-Note: When `logInputs` is true, the middleware prefers `context.redactedInputs` (already sanitized by the executor's redaction step) over raw inputs.
-
-### 5. Implement after() with completion log and duration
-
-```typescript
-override after(
-  moduleId: string,
-  _inputs: Record<string, unknown>,
-  output: Record<string, unknown>,
-  context: Context,
-): null {
-  const starts = context.data['_obs_logging_starts'] as number[];
-  const startTime = starts.pop()!;
-  const durationMs = performance.now() - startTime;
-
-  const extra: Record<string, unknown> = {
-    module_id: moduleId,
-    duration_ms: durationMs,
-  };
-  if (this._logOutputs) {
-    extra['output'] = output;
-  }
-  this._logger.info('Module call completed', extra);
-  return null;
-}
-```
-
-Duration is kept in milliseconds (not converted to seconds like MetricsMiddleware) since this is for human-readable log output, not Prometheus metrics.
-
-### 6. Implement onError() with error details
-
-```typescript
-override onError(
-  moduleId: string,
-  _inputs: Record<string, unknown>,
-  error: Error,
-  context: Context,
-): null {
-  const starts = context.data['_obs_logging_starts'] as number[];
-  const startTime = starts.pop()!;
-  const durationMs = performance.now() - startTime;
-
-  this._logger.error('Module call failed', {
-    module_id: moduleId,
-    duration_ms: durationMs,
-    error_type: error.constructor.name,
-    error_message: String(error),
-  });
-  return null;
-}
-```
-
-### 7. Run tests and verify all pass
-
-## Acceptance Criteria
-
-- [x] `ObsLoggingMiddleware` extends `Middleware` and accepts optional `logger`, `logInputs`, `logOutputs`
-- [x] Defaults to a `ContextLogger` named `apcore.obs_logging` if no logger provided
-- [x] `before()` pushes `performance.now()` onto `context.data['_obs_logging_starts']` stack
-- [x] `before()` emits "Module call started" at info level with module_id and caller_id
-- [x] `before()` includes `context.redactedInputs` (or raw inputs) when `logInputs` is true
-- [x] `after()` pops start time, computes duration in milliseconds, emits "Module call completed"
-- [x] `after()` includes output when `logOutputs` is true
-- [x] `onError()` pops start time, computes duration, emits "Module call failed" at error level
-- [x] Error log includes `error_type` (constructor name) and `error_message` (stringified error)
-- [x] Stack-based timing correctly handles nested module calls
-- [x] All tests pass with `vitest`
-
-## Dependencies
-
-- **context-logger** -- Requires `ContextLogger` class
-
-## Estimated Time
-
-2 hours

package/planning/observability/tasks/span-model.md

@@ -1,120 +0,0 @@
-# Task: Span Interface and createSpan() Factory
-
-## Goal
-
-Define the `Span` interface representing a single trace span and implement the `createSpan()` factory function that produces span instances with auto-generated span IDs. Also define the `SpanExporter` interface that all exporter implementations must satisfy.
-
-## Files Involved
-
-- `src/observability/tracing.ts` -- Span interface, createSpan() factory, SpanExporter interface
-- `tests/observability/test-tracing.test.ts` -- Unit tests for span creation
-
-## Steps (TDD)
-
-### 1. Write failing tests for Span creation
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { createSpan } from '../../src/observability/tracing.js';
-
-describe('Span', () => {
-  it('createSpan creates span with defaults', () => {
-    const span = createSpan({
-      traceId: 'trace-1',
-      name: 'test.span',
-      startTime: 100,
-    });
-    expect(span.traceId).toBe('trace-1');
-    expect(span.name).toBe('test.span');
-    expect(span.startTime).toBe(100);
-    expect(span.spanId).toBeDefined();
-    expect(span.spanId).toHaveLength(16); // randomBytes(8).toString('hex')
-    expect(span.parentSpanId).toBeNull();
-    expect(span.status).toBe('ok');
-    expect(span.endTime).toBeNull();
-    expect(span.events).toEqual([]);
-    expect(span.attributes).toEqual({});
-  });
-
-  it('createSpan accepts custom spanId and parentSpanId', () => {
-    const span = createSpan({
-      traceId: 'trace-2',
-      name: 'child.span',
-      startTime: 200,
-      spanId: 'custom-span-id-01',
-      parentSpanId: 'parent-span-0001',
-      attributes: { moduleId: 'mod.a' },
-    });
-    expect(span.spanId).toBe('custom-span-id-01');
-    expect(span.parentSpanId).toBe('parent-span-0001');
-    expect(span.attributes['moduleId']).toBe('mod.a');
-  });
-});
-```
-
-### 2. Define the Span interface
-
-Define a TypeScript `interface Span` with the following fields:
-- `traceId: string` -- trace identifier linking related spans
-- `name: string` -- operation name (e.g., `apcore.module.execute`)
-- `startTime: number` -- `performance.now()` timestamp in milliseconds
-- `spanId: string` -- unique 16-hex-char identifier
-- `parentSpanId: string | null` -- parent span for nesting, null for root spans
-- `attributes: Record<string, unknown>` -- key-value metadata
-- `endTime: number | null` -- set when span completes, null while active
-- `status: string` -- `'ok'` or `'error'`
-- `events: Array<Record<string, unknown>>` -- timeline annotations
-
-### 3. Implement createSpan() factory
-
-```typescript
-import { randomBytes } from 'node:crypto';
-
-export function createSpan(options: {
-  traceId: string;
-  name: string;
-  startTime: number;
-  spanId?: string;
-  parentSpanId?: string | null;
-  attributes?: Record<string, unknown>;
-}): Span {
-  return {
-    traceId: options.traceId,
-    name: options.name,
-    startTime: options.startTime,
-    spanId: options.spanId ?? randomBytes(8).toString('hex'),
-    parentSpanId: options.parentSpanId ?? null,
-    attributes: options.attributes ?? {},
-    endTime: null,
-    status: 'ok',
-    events: [],
-  };
-}
-```
-
-### 4. Define the SpanExporter interface
-
-```typescript
-export interface SpanExporter {
-  export(span: Span): void;
-}
-```
-
-### 5. Run tests and verify all pass
-
-## Acceptance Criteria
-
-- [x] `Span` interface defines all 9 fields with correct types
-- [x] `createSpan()` generates 16-character hex span IDs via `randomBytes(8).toString('hex')`
-- [x] Default values: `parentSpanId: null`, `attributes: {}`, `endTime: null`, `status: 'ok'`, `events: []`
-- [x] Custom `spanId`, `parentSpanId`, and `attributes` can be provided via options
-- [x] `SpanExporter` interface declares a single `export(span: Span): void` method
-- [x] All tests pass with `vitest`
-
-## Dependencies
-
-- None (foundational task)
-
-## Estimated Time
-
-1 hour