suaveplan/openspec/archive/2026-04-24-enterprise-events-metrics/proposal.md

# OpenSpec Change: enterprise-events-metrics

- **Change ID**: enterprise-events-metrics
- **Package**: `@suaveplan/events-metrics`
- **Category**: universal
- **Target path**: `universal/events/events-metrics`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/events-metrics.md`

---

## Summary

Deliver `@suaveplan/events-metrics` on the genesis branch from scratch at enterprise quality. The package is an opt-in metrics companion for `@suaveplan/events`: it attaches to the event bus via the public interceptor/companion API (never monkey-patching), records dispatch totals, listener error counts, dispatch latency histograms, queue depth gauges, and active subscriber counts. All metric names follow the `suaveplan.events.*` convention with stable attribute keys. Sub-microsecond hot-path overhead is a hard requirement.

---

## Current-state audit (genesis)

The package does not exist on genesis yet — fresh build. No prior source, no test results, no coverage data.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/events` (`workspace:^`) | Event bus and interceptor API |
| `@suaveplan/opentelemetry` (`workspace:^`) | `MeterProvider` factory, counter/histogram/gauge helpers |
| `@suaveplan/error` (`workspace:^`) | Base class for `EventsMetricsError`; `defineCodes` for `EVENTS_METRICS.*` codes |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` injection interfaces |
| `zod` (`catalog:forms`) | Zod schemas for all public option types |
| `@opentelemetry/api` (`catalog:observability`) | `Meter`, `Counter`, `Histogram`, `ObservableGauge` |
| `tslib` (`catalog:build`) | Runtime helpers |

Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).

---

## Public API surface

### Setup

```ts
// Attaches metrics companion to an existing EventBus
function attachEventMetrics(bus: EventBusLike, options?: EventMetricsOptions): EventMetricsHandle

interface EventMetricsOptions {
  meter?: Meter                     // default: global meter from @opentelemetry/api
  eventFilter?: (name: string) => boolean  // optional: record only matching events
  clock?: Clock
  logger?: LoggerLike
}

interface EventMetricsHandle {
  detach(): void
  snapshot(): MetricsSnapshot
}
```

### Metric definitions

```ts
// All metric names and attribute keys as stable constants
const METRIC_NAMES = {
  DISPATCH_TOTAL:         "suaveplan.events.dispatch.total",
  LISTENER_ERROR_TOTAL:   "suaveplan.events.listener.error.total",
  DISPATCH_LATENCY_MS:    "suaveplan.events.dispatch.latency_ms",
  QUEUE_DEPTH:            "suaveplan.events.queue.depth",
  ACTIVE_SUBSCRIBERS:     "suaveplan.events.subscribers.active",
} as const

const ATTRIBUTE_KEYS = {
  EVENT_NAME:     "event.name",
  EVENT_CATEGORY: "event.category",
  LISTENER_ID:    "listener.id",
  BUS_ID:         "bus.id",
} as const
```

### Snapshot

```ts
interface MetricsSnapshot {
  dispatchTotal: Record<string, number>      // keyed by event.name
  listenerErrorTotal: Record<string, number>
  avgDispatchLatencyMs: Record<string, number>
  queueDepth: number
  activeSubscribers: number
}
```

### Error handling

```ts
class EventsMetricsError extends SuaveplanError<EventsMetricsErrorCode>

type EventsMetricsErrorCode =
  | "EVENTS_METRICS_ATTACH_FAILED"
  | "EVENTS_METRICS_ALREADY_ATTACHED"
  | "EVENTS_METRICS_DETACHED"

function registerEventsMetricsErrorCodes(): void
```

### Zod schemas

```ts
const EventMetricsOptionsSchema: ZodSchema
```

---

## New additions for genesis

### 1. Companion-API only

`attachEventMetrics` uses only the public `EventBus` interceptor/companion surface from `@suaveplan/events`. No access to private fields, no prototype patching. If the bus is replaced or re-created, callers must call `detach()` and `attachEventMetrics` again.

### 2. Low-overhead hot path

The dispatch interceptor is a thin closure: one array lookup for the counter and one `performance.now()` call for the histogram. Allocation on the critical path is zero when the event name was previously seen (name-to-attributes map is pre-cached).

### 3. Observable gauge for queue depth and subscribers

Queue depth and active subscriber count are reported as OTel `ObservableGauge` (polled at collection time), not recorded on every dispatch, to avoid per-dispatch overhead.

### 4. Property-based tests (fast-check)

- Counter monotonicity: `dispatchTotal[name]` never decreases after more dispatches
- Error counter accuracy: `listenerErrorTotal` equals the number of listener throws injected
- Histogram latency: average latency is within 1ms of a synthetic injected delay

### 5. Benchmark suite (`src/__benchmarks__/`)

- Overhead of `attachEventMetrics` on dispatch hot path: compare instrumented vs uninstrumented bus at 1M events/sec
- Snapshot retrieval latency at 1k distinct event names

---

## File layout

```text
universal/events/events-metrics/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/
      index.ts
    core/
      attach-event-metrics/
        attach-event-metrics.ts
        attach-event-metrics.md
        attach-event-metrics.types.ts
        attach-event-metrics.test.ts
        index.ts
    metrics/
      metric-names/
        metric-names.ts
        metric-names.md
        index.ts
      snapshot/
        snapshot.ts
        snapshot.md
        snapshot.test.ts
        index.ts
    __benchmarks__/
      events-metrics.bench.ts
  tests/
    integration.test.ts
    property.test.ts
```

---

## Impact

**Downstream packages**: any application wiring `@suaveplan/events` that needs production observability without code changes to event publishers or subscribers.

**Workspace dep prerequisites**: `@suaveplan/events`, `@suaveplan/opentelemetry`, `@suaveplan/error`, `@suaveplan/types` must be published to Verdaccio.

**Breaking changes**: none (new package).