apcore-js 0.1.0

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

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

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

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

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