apcore-js 0.1.0

package/planning/middleware-system/tasks/logging-middleware.md

@@ -0,0 +1,304 @@
+# Task: LoggingMiddleware with Logger Interface and Timing
+
+## Goal
+
+Implement a `LoggingMiddleware` that provides structured logging for every module call lifecycle phase (before, after, onError). It uses a pluggable `Logger` interface with `info()` and `error()` methods, defaults to `console.log`/`console.error`, and measures execution duration with `performance.now()`. The middleware stores its start timestamp on `context.data['_logging_mw_start']` and computes duration in the `after()` phase. Logging of inputs, outputs, and errors is individually configurable.
+
+## Files Involved
+
+| File | Action |
+|------|--------|
+| `src/middleware/logging.ts` | Create -- LoggingMiddleware class and Logger interface |
+| `src/middleware/base.ts` | Read -- Middleware base class (dependency) |
+| `tests/test-middleware.test.ts` | Extend -- Unit tests for logging middleware (or separate test file) |
+
+## Steps (TDD)
+
+### Step 1: Define the Logger interface
+
+```typescript
+export interface Logger {
+  info(message: string, extra?: Record<string, unknown>): void;
+  error(message: string, extra?: Record<string, unknown>): void;
+}
+```
+
+### Step 2: Implement the default logger
+
+```typescript
+const defaultLogger: Logger = {
+  info(message: string, extra?: Record<string, unknown>) {
+    console.log(message, extra ?? '');
+  },
+  error(message: string, extra?: Record<string, unknown>) {
+    console.error(message, extra ?? '');
+  },
+};
+```
+
+### Step 3: Write failing tests for before() logging and timing
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { LoggingMiddleware, Logger } from '../src/middleware/logging.js';
+import { Context, createIdentity } from '../src/context.js';
+
+function makeContext(): Context {
+  return Context.create(null, createIdentity('test-user'));
+}
+
+describe('LoggingMiddleware', () => {
+  it('before() stores start time on context.data and logs START message', () => {
+    const logs: Array<{ message: string; extra: Record<string, unknown> }> = [];
+    const mockLogger: Logger = {
+      info(message, extra) { logs.push({ message, extra: extra ?? {} }); },
+      error(message, extra) { logs.push({ message, extra: extra ?? {} }); },
+    };
+    const mw = new LoggingMiddleware({ logger: mockLogger });
+    const ctx = makeContext();
+
+    const result = mw.before('mod.test', { x: 1 }, ctx);
+
+    expect(result).toBeNull();
+    expect(ctx.data['_logging_mw_start']).toBeTypeOf('number');
+    expect(logs).toHaveLength(1);
+    expect(logs[0].message).toContain('START mod.test');
+    expect(logs[0].extra['moduleId']).toBe('mod.test');
+  });
+});
+```
+
+### Step 4: Implement before() with performance.now() timing
+
+```typescript
+override before(
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  context: Context,
+): null {
+  context.data['_logging_mw_start'] = performance.now();
+
+  if (this._logInputs) {
+    const redacted = context.redactedInputs ?? inputs;
+    this._logger.info(`[${context.traceId}] START ${moduleId}`, {
+      traceId: context.traceId,
+      moduleId,
+      callerId: context.callerId,
+      inputs: redacted,
+    });
+  }
+
+  return null;
+}
+```
+
+Key design choice: `performance.now()` provides sub-millisecond resolution and is available in Node.js 18+ globally. It is preferable to `Date.now()` for duration measurement because it is monotonic and not affected by system clock adjustments.
+
+### Step 5: Write failing tests for after() logging with duration
+
+```typescript
+it('after() logs END message with duration', () => {
+  const logs: Array<{ message: string; extra: Record<string, unknown> }> = [];
+  const mockLogger: Logger = {
+    info(message, extra) { logs.push({ message, extra: extra ?? {} }); },
+    error() {},
+  };
+  const mw = new LoggingMiddleware({ logger: mockLogger });
+  const ctx = makeContext();
+
+  mw.before('mod.test', { x: 1 }, ctx);
+  const result = mw.after('mod.test', { x: 1 }, { y: 2 }, ctx);
+
+  expect(result).toBeNull();
+  expect(logs).toHaveLength(2); // START + END
+  expect(logs[1].message).toContain('END mod.test');
+  expect(logs[1].extra['durationMs']).toBeTypeOf('number');
+});
+```
+
+### Step 6: Implement after() with duration calculation
+
+```typescript
+override after(
+  moduleId: string,
+  _inputs: Record<string, unknown>,
+  output: Record<string, unknown>,
+  context: Context,
+): null {
+  const startTime = (context.data['_logging_mw_start'] as number) ?? performance.now();
+  const durationMs = performance.now() - startTime;
+
+  if (this._logOutputs) {
+    this._logger.info(
+      `[${context.traceId}] END ${moduleId} (${durationMs.toFixed(2)}ms)`,
+      {
+        traceId: context.traceId,
+        moduleId,
+        durationMs,
+        output,
+      },
+    );
+  }
+
+  return null;
+}
+```
+
+### Step 7: Write failing tests for onError() logging
+
+```typescript
+it('onError() logs ERROR message with redacted inputs', () => {
+  const logs: Array<{ message: string; extra: Record<string, unknown> }> = [];
+  const mockLogger: Logger = {
+    info() {},
+    error(message, extra) { logs.push({ message, extra: extra ?? {} }); },
+  };
+  const mw = new LoggingMiddleware({ logger: mockLogger });
+  const ctx = makeContext();
+
+  const result = mw.onError('mod.test', { x: 1 }, new Error('boom'), ctx);
+
+  expect(result).toBeNull();
+  expect(logs).toHaveLength(1);
+  expect(logs[0].message).toContain('ERROR mod.test');
+  expect(logs[0].extra['error']).toBe('Error: boom');
+});
+```
+
+### Step 8: Implement onError()
+
+```typescript
+override onError(
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  error: Error,
+  context: Context,
+): null {
+  if (this._logErrors) {
+    const redacted = context.redactedInputs ?? inputs;
+    this._logger.error(`[${context.traceId}] ERROR ${moduleId}: ${error}`, {
+      traceId: context.traceId,
+      moduleId,
+      error: String(error),
+      inputs: redacted,
+    });
+  }
+
+  return null;
+}
+```
+
+### Step 9: Write tests for configuration flags
+
+```typescript
+it('respects logInputs=false', () => {
+  const logs: string[] = [];
+  const mockLogger: Logger = {
+    info(msg) { logs.push(msg); },
+    error() {},
+  };
+  const mw = new LoggingMiddleware({ logger: mockLogger, logInputs: false });
+  const ctx = makeContext();
+  mw.before('mod.test', { x: 1 }, ctx);
+  expect(logs).toHaveLength(0);
+  // But timing is still stored
+  expect(ctx.data['_logging_mw_start']).toBeTypeOf('number');
+});
+
+it('respects logOutputs=false', () => {
+  const logs: string[] = [];
+  const mockLogger: Logger = {
+    info(msg) { logs.push(msg); },
+    error() {},
+  };
+  const mw = new LoggingMiddleware({ logger: mockLogger, logOutputs: false });
+  const ctx = makeContext();
+  mw.before('mod.test', {}, ctx);
+  mw.after('mod.test', {}, { y: 1 }, ctx);
+  expect(logs).toHaveLength(1); // Only START, no END
+});
+
+it('respects logErrors=false', () => {
+  const logs: string[] = [];
+  const mockLogger: Logger = {
+    info() {},
+    error(msg) { logs.push(msg); },
+  };
+  const mw = new LoggingMiddleware({ logger: mockLogger, logErrors: false });
+  const ctx = makeContext();
+  mw.onError('mod.test', {}, new Error('boom'), ctx);
+  expect(logs).toHaveLength(0);
+});
+```
+
+### Step 10: Implement constructor with options
+
+```typescript
+export class LoggingMiddleware extends Middleware {
+  private _logger: Logger;
+  private _logInputs: boolean;
+  private _logOutputs: boolean;
+  private _logErrors: boolean;
+
+  constructor(options?: {
+    logger?: Logger;
+    logInputs?: boolean;
+    logOutputs?: boolean;
+    logErrors?: boolean;
+  }) {
+    super();
+    this._logger = options?.logger ?? defaultLogger;
+    this._logInputs = options?.logInputs ?? true;
+    this._logOutputs = options?.logOutputs ?? true;
+    this._logErrors = options?.logErrors ?? true;
+  }
+}
+```
+
+### Step 11: Write test for redactedInputs usage
+
+```typescript
+it('uses context.redactedInputs when available', () => {
+  const logs: Array<{ extra: Record<string, unknown> }> = [];
+  const mockLogger: Logger = {
+    info(_msg, extra) { logs.push({ extra: extra ?? {} }); },
+    error() {},
+  };
+  const mw = new LoggingMiddleware({ logger: mockLogger });
+  const ctx = makeContext();
+  (ctx as any).redactedInputs = { x: '***' };
+
+  mw.before('mod.test', { x: 'secret' }, ctx);
+
+  expect(logs[0].extra['inputs']).toEqual({ x: '***' });
+});
+```
+
+### Step 12: Run all tests and confirm green
+
+```bash
+npx vitest run tests/test-middleware.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] `Logger` interface is exported with `info(message, extra?)` and `error(message, extra?)` methods
+- [x] Default logger delegates to `console.log` and `console.error`
+- [x] `LoggingMiddleware` extends `Middleware`
+- [x] `before()` stores `performance.now()` on `context.data['_logging_mw_start']` and logs START
+- [x] `after()` computes duration from stored start time and logs END with `durationMs`
+- [x] `onError()` logs ERROR with trace ID, module ID, and stringified error
+- [x] Uses `context.redactedInputs` when available instead of raw inputs
+- [x] `logInputs`, `logOutputs`, `logErrors` flags default to `true` and are individually configurable
+- [x] All hooks return `null` (logging middleware does not transform inputs/outputs)
+- [x] Duration is formatted with `.toFixed(2)` in the log message
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `src/middleware/base.ts` -- `Middleware` base class (task: base)
+- `src/context.ts` -- `Context` class with `traceId`, `callerId`, `data`, `redactedInputs` properties
+
+## Estimated Time
+
+2 hours

package/planning/middleware-system/tasks/manager.md

@@ -0,0 +1,313 @@
+# Task: MiddlewareManager with Onion-Model Execution
+
+## Goal
+
+Implement the `MiddlewareManager` class that manages middleware registration and executes the onion-model pipeline. The manager provides `add()`, `remove()` (by reference identity), and `snapshot()` for list management. It exposes `executeBefore()` (forward order), `executeAfter()` (reverse order), and `executeOnError()` (reverse over executed subset, first non-null recovery wins). Also implement `MiddlewareChainError` extending `ModuleError` to wrap failures during the `before()` phase with tracking of which middlewares have already executed.
+
+## Files Involved
+
+| File | Action |
+|------|--------|
+| `src/middleware/manager.ts` | Create -- MiddlewareManager and MiddlewareChainError |
+| `src/errors.ts` | Read -- ModuleError base class (dependency) |
+| `tests/test-middleware-manager.test.ts` | Create -- Unit tests for manager and chain error |
+
+## Steps (TDD)
+
+### Step 1: Write failing tests for add/remove/snapshot
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { Middleware } from '../src/middleware/base.js';
+import { MiddlewareManager } from '../src/middleware/manager.js';
+
+describe('MiddlewareManager', () => {
+  it('starts empty', () => {
+    const mgr = new MiddlewareManager();
+    expect(mgr.snapshot()).toEqual([]);
+  });
+
+  it('add and snapshot', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new Middleware());
+    mgr.add(new Middleware());
+    expect(mgr.snapshot()).toHaveLength(2);
+  });
+
+  it('snapshot returns a copy', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new Middleware());
+    const snap = mgr.snapshot();
+    snap.pop();
+    expect(mgr.snapshot()).toHaveLength(1);
+  });
+
+  it('remove by identity', () => {
+    const mgr = new MiddlewareManager();
+    const mw1 = new Middleware();
+    const mw2 = new Middleware();
+    mgr.add(mw1);
+    mgr.add(mw2);
+    expect(mgr.remove(mw1)).toBe(true);
+    expect(mgr.snapshot()).toEqual([mw2]);
+  });
+
+  it('remove returns false when not found', () => {
+    const mgr = new MiddlewareManager();
+    expect(mgr.remove(new Middleware())).toBe(false);
+  });
+});
+```
+
+### Step 2: Implement add, remove, snapshot
+
+```typescript
+import { Middleware } from './base.js';
+
+export class MiddlewareManager {
+  private _middlewares: Middleware[] = [];
+
+  add(middleware: Middleware): void {
+    this._middlewares.push(middleware);
+  }
+
+  remove(middleware: Middleware): boolean {
+    for (let i = 0; i < this._middlewares.length; i++) {
+      if (this._middlewares[i] === middleware) {
+        this._middlewares.splice(i, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  snapshot(): Middleware[] {
+    return [...this._middlewares];
+  }
+}
+```
+
+No thread locking is needed -- Node.js is single-threaded. The Python implementation uses `threading.Lock`; in TypeScript, `snapshot()` returning a shallow copy is sufficient to guard against mutations during iteration.
+
+### Step 3: Write failing tests for executeBefore (forward order)
+
+```typescript
+it('executeBefore runs in forward order', () => {
+  const mgr = new MiddlewareManager();
+  mgr.add(new TaggingMiddleware('A'));
+  mgr.add(new TaggingMiddleware('B'));
+  mgr.add(new TaggingMiddleware('C'));
+  const ctx = makeContext();
+  const [result, executed] = mgr.executeBefore('mod.test', { trail: '' }, ctx);
+  expect(result['trail']).toBe('ABC');
+  expect(executed).toHaveLength(3);
+});
+
+it('executeBefore passes original inputs when all return null', () => {
+  const mgr = new MiddlewareManager();
+  mgr.add(new Middleware());
+  const ctx = makeContext();
+  const [result] = mgr.executeBefore('mod.test', { x: 42 }, ctx);
+  expect(result).toEqual({ x: 42 });
+});
+```
+
+### Step 4: Implement executeBefore
+
+```typescript
+executeBefore(
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  context: Context,
+): [Record<string, unknown>, Middleware[]] {
+  let currentInputs = inputs;
+  const executedMiddlewares: Middleware[] = [];
+  const middlewares = this.snapshot();
+
+  for (const mw of middlewares) {
+    executedMiddlewares.push(mw);
+    try {
+      const result = mw.before(moduleId, currentInputs, context);
+      if (result !== null) {
+        currentInputs = result;
+      }
+    } catch (e) {
+      throw new MiddlewareChainError(e as Error, executedMiddlewares);
+    }
+  }
+
+  return [currentInputs, executedMiddlewares];
+}
+```
+
+### Step 5: Write failing tests for executeAfter (reverse order)
+
+```typescript
+it('executeAfter runs in reverse order', () => {
+  const mgr = new MiddlewareManager();
+  mgr.add(new TaggingMiddleware('A'));
+  mgr.add(new TaggingMiddleware('B'));
+  mgr.add(new TaggingMiddleware('C'));
+  const ctx = makeContext();
+  const result = mgr.executeAfter('mod.test', {}, { trail: '' }, ctx);
+  expect(result['trail']).toBe('CBA');
+});
+```
+
+### Step 6: Implement executeAfter
+
+```typescript
+executeAfter(
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  output: Record<string, unknown>,
+  context: Context,
+): Record<string, unknown> {
+  let currentOutput = output;
+  const middlewares = this.snapshot();
+
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    const result = middlewares[i].after(moduleId, inputs, currentOutput, context);
+    if (result !== null) {
+      currentOutput = result;
+    }
+  }
+
+  return currentOutput;
+}
+```
+
+### Step 7: Write failing tests for executeOnError (reverse, first recovery wins, errors swallowed)
+
+```typescript
+it('executeOnError returns first non-null recovery (reverse order)', () => {
+  const mgr = new MiddlewareManager();
+  const mwA = new RecoveringMiddleware({ recovered: 'A' });
+  const mwB = new RecoveringMiddleware({ recovered: 'B' });
+  mgr.add(mwA);
+  mgr.add(mwB);
+  const ctx = makeContext();
+  const result = mgr.executeOnError('mod.test', {}, new Error('oops'), ctx, [mwA, mwB]);
+  expect(result).toEqual({ recovered: 'B' });
+});
+
+it('executeOnError returns null when no recovery', () => {
+  const mgr = new MiddlewareManager();
+  const mw = new Middleware();
+  mgr.add(mw);
+  const ctx = makeContext();
+  const result = mgr.executeOnError('mod.test', {}, new Error('oops'), ctx, [mw]);
+  expect(result).toBeNull();
+});
+
+it('executeOnError swallows errors in onError handlers', () => {
+  // ThrowingOnError middleware throws inside onError()
+  // RecoveringMiddleware before it should still provide recovery
+  const result = mgr.executeOnError('mod.test', {}, new Error('original'), ctx, [mwRecover, mwThrow]);
+  expect(result).toEqual({ safe: true });
+});
+```
+
+### Step 8: Implement executeOnError
+
+```typescript
+executeOnError(
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  error: Error,
+  context: Context,
+  executedMiddlewares: Middleware[],
+): Record<string, unknown> | null {
+  for (let i = executedMiddlewares.length - 1; i >= 0; i--) {
+    try {
+      const result = executedMiddlewares[i].onError(moduleId, inputs, error, context);
+      if (result !== null) {
+        return result;
+      }
+    } catch {
+      // Swallow errors in onError handlers
+      continue;
+    }
+  }
+  return null;
+}
+```
+
+### Step 9: Write failing test for MiddlewareChainError
+
+```typescript
+it('MiddlewareChainError wraps before() failure', () => {
+  class FailingBefore extends Middleware {
+    override before(): Record<string, unknown> | null {
+      throw new Error('before exploded');
+    }
+  }
+  const mgr = new MiddlewareManager();
+  mgr.add(new TaggingMiddleware('A'));
+  mgr.add(new FailingBefore());
+  const ctx = makeContext();
+
+  let caught: MiddlewareChainError | undefined;
+  try {
+    mgr.executeBefore('mod.test', { trail: '' }, ctx);
+  } catch (e) {
+    caught = e as MiddlewareChainError;
+  }
+
+  expect(caught).toBeInstanceOf(MiddlewareChainError);
+  expect(caught!.original.message).toBe('before exploded');
+  expect(caught!.executedMiddlewares).toHaveLength(2);
+});
+```
+
+### Step 10: Implement MiddlewareChainError
+
+```typescript
+import { ModuleError } from '../errors.js';
+
+export class MiddlewareChainError extends ModuleError {
+  readonly original: Error;
+  readonly executedMiddlewares: Middleware[];
+
+  constructor(original: Error, executedMiddlewares: Middleware[]) {
+    super('MIDDLEWARE_CHAIN_ERROR', String(original));
+    this.name = 'MiddlewareChainError';
+    this.original = original;
+    this.executedMiddlewares = executedMiddlewares;
+  }
+}
+```
+
+Key difference from Python: extends `ModuleError` (which extends `Error`), not `Exception`. This integrates with the framework's structured error hierarchy providing `code`, `details`, and `timestamp` properties.
+
+### Step 11: Run all tests and confirm green
+
+```bash
+npx vitest run tests/test-middleware-manager.test.ts
+```
+
+## Acceptance Criteria
+
+- [x] `MiddlewareManager` is exported from `src/middleware/manager.ts`
+- [x] `add()` appends a middleware to the internal list
+- [x] `remove()` removes by strict reference identity (`===`) and returns `boolean`
+- [x] `snapshot()` returns a shallow copy; mutations to the copy do not affect the internal list
+- [x] `executeBefore()` runs in forward registration order, returns `[transformedInputs, executedMiddlewares]`
+- [x] `executeBefore()` wraps middleware errors in `MiddlewareChainError`
+- [x] `executeAfter()` runs in reverse registration order
+- [x] `executeOnError()` runs in reverse over the executed middlewares subset
+- [x] `executeOnError()` returns the first non-null recovery value
+- [x] `executeOnError()` swallows errors thrown by `onError()` handlers
+- [x] `MiddlewareChainError` extends `ModuleError` with `original` and `executedMiddlewares` properties
+- [x] No thread locking is used (Node.js single-threaded model)
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `src/middleware/base.ts` -- `Middleware` base class (task: base)
+- `src/errors.ts` -- `ModuleError` base error class
+- `src/context.ts` -- `Context` class (parameter type)
+
+## Estimated Time
+
+3 hours

package/planning/observability/overview.md

@@ -0,0 +1,53 @@
+# Feature: Observability
+
+## Overview
+
+The Observability module provides the three pillars of runtime visibility for apcore: distributed tracing, metrics collection, and structured logging. All three integrate into the executor's middleware pipeline as composable `Middleware` subclasses that use stack-based state in the shared `context.data` record to correctly handle nested module-to-module calls. Tracing produces `Span` objects exported through pluggable `SpanExporter` implementations. Metrics are collected via `MetricsCollector` with Prometheus-compatible text export. Logging is handled by `ContextLogger` with JSON and text output formats, automatic `_secret_`-prefixed key redaction, and a `fromContext()` factory that binds trace/module/caller metadata.
+
+## Scope
+
+### Included
+
+- `Span` interface and `createSpan()` factory function for trace span creation
+- `SpanExporter` interface with `StdoutExporter` (JSON.stringify to stdout) and `InMemoryExporter` (bounded array with shift() eviction)
+- `TracingMiddleware` with stack-based span management and 4 sampling strategies: `full`, `proportional`, `error_first`, `off`
+- `MetricsCollector` with counter and histogram support, string-encoded composite keys (`name|key1=val1,key2=val2`), Prometheus text format export, and convenience methods (`incrementCalls`, `incrementErrors`, `observeDuration`)
+- `MetricsMiddleware` with stack-based `performance.now()` timing and automatic call/error/duration recording
+- `ContextLogger` with JSON and text output formats, level filtering (trace/debug/info/warn/error/fatal), `_secret_`-prefixed key redaction, and `fromContext()` static factory
+- `ObsLoggingMiddleware` with stack-based timing, configurable input/output logging, and start/complete/error structured log events
+
+### Excluded
+
+- `OTLPExporter` for OpenTelemetry Protocol export (not yet implemented -- noted as a gap for future work)
+- OpenTelemetry SDK bridge or direct OTel integration
+- Persistent metric storage or time-series database integration
+- Log file rotation or external log shipping
+- Dashboard or alerting configuration
+
+## Technology Stack
+
+- **TypeScript 5.5+** with strict mode
+- **Node.js >= 18.0.0** with ES Module support (`performance.now()`, `node:crypto`)
+- **vitest** for unit testing
+
+## Task Execution Order
+
+| # | Task File | Description | Status |
+|---|-----------|-------------|--------|
+| 1 | [span-model](./tasks/span-model.md) | Span interface and createSpan() factory, SpanExporter interface | completed |
+| 2 | [exporters](./tasks/exporters.md) | StdoutExporter and InMemoryExporter implementations | completed |
+| 3 | [tracing-middleware](./tasks/tracing-middleware.md) | TracingMiddleware with stack-based spans and sampling strategies | completed |
+| 4 | [metrics-collector](./tasks/metrics-collector.md) | MetricsCollector with counters, histograms, and Prometheus export | completed |
+| 5 | [metrics-middleware](./tasks/metrics-middleware.md) | MetricsMiddleware with stack-based performance.now() timing | completed |
+| 6 | [context-logger](./tasks/context-logger.md) | ContextLogger with JSON/text formats, redaction, fromContext() | completed |
+| 7 | [obs-logging-middleware](./tasks/obs-logging-middleware.md) | ObsLoggingMiddleware with stack-based timing and structured logs | completed |
+
+## Progress
+
+| Total | Completed | In Progress | Pending |
+|-------|-----------|-------------|---------|
+| 7     | 7         | 0           | 0       |
+
+## Reference Documents
+
+- [Observability Feature Specification](../../features/observability.md)