Initial Commit

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

@@ -0,0 +1,78 @@
+# Tasks: enterprise-events-metrics
+
+- **Change ID**: enterprise-events-metrics
+- **Package**: `@suaveplan/events-metrics`
+- **Date**: 2026-04-24
+
+## Prerequisites (must be published to Verdaccio first)
+
+- [x] `@suaveplan/events`
+- [x] `@suaveplan/opentelemetry`
+- [x] `@suaveplan/error`
+- [x] `@suaveplan/types`
+
+## Tasks
+
+### 1. Scaffold package
+
+- [x] Create `universal/events/events-metrics/` directory tree per file layout in `proposal.md`
+- [x] Write `package.json` (name `@suaveplan/events-metrics`, version `0.1.0`, `sideEffects: false`, correct workspace deps)
+- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`
+- [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`
+
+### 2. Error codes (`src/error-codes.ts`)
+
+- [x] Define `EventsMetricsErrorCode` union type
+- [x] Call `defineCodes` to register all `EVENTS_METRICS.*` codes
+- [x] Export `registerEventsMetricsErrorCodes()` and `EventsMetricsError`
+
+### 3. Metric name constants (`src/metrics/metric-names/`)
+
+- [x] Export `METRIC_NAMES` and `ATTRIBUTE_KEYS` as `as const` objects
+- [x] Write `metric-names.md` and `index.ts`
+
+### 4. Core `attachEventMetrics` (`src/core/attach-event-metrics/`)
+
+- [x] Implement `attachEventMetrics(bus, options?)` using `@suaveplan/events` interceptor API only
+- [x] Zero-allocation hot path: pre-cache event-name → attribute set on first dispatch; no object creation on subsequent dispatches for the same event name
+- [x] Counter: `DISPATCH_TOTAL` per event.name
+- [x] Counter: `LISTENER_ERROR_TOTAL` per event.name + listener.id
+- [x] Histogram: `DISPATCH_LATENCY_MS` using `performance.now()` or injectable clock
+- [x] ObservableGauge: `QUEUE_DEPTH` and `ACTIVE_SUBSCRIBERS` — polled at collection time, not per-dispatch
+- [x] Return `EventMetricsHandle` with `detach()` and `snapshot()`
+- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`
+
+### 5. Snapshot (`src/metrics/snapshot/`)
+
+- [x] Implement `MetricsSnapshot` accumulator that mirrors the OTel metric state in-memory for test/introspection
+- [x] Write `.md`, `.test.ts`, `index.ts`
+
+### 6. Tests
+
+- [x] Unit tests co-located (100% coverage target)
+- [x] `tests/integration.test.ts` — attach to real EventBus, dispatch events, assert snapshot counts match
+- [x] `tests/property.test.ts` — fast-check properties per `proposal.md` §4
+
+### 7. Benchmarks (`src/__benchmarks__/events-metrics.bench.ts`)
+
+- [x] Overhead benchmark: instrumented vs uninstrumented bus at high dispatch frequency
+- [x] Snapshot retrieval benchmark
+
+### 8. Docs
+
+- [x] Every `.ts` implementation file has a sibling `.md`
+- [x] Root `README.md`
+
+### 9. Pre-publish gate
+
+- [x] `bunx turbo lint typecheck test --filter=@suaveplan/events-metrics` green
+- [x] `bunx turbo test:coverage --filter=@suaveplan/events-metrics` ≥ 100% on touched modules
+
+### 10. Publish
+
+- [x] `bun scripts/publish.ts --package @suaveplan/events-metrics`
+
+### 11. Archive
+
+- [x] Fold spec delta into `openspec/specs/events/spec.md`
+- [x] `mv openspec/changes/enterprise-events-metrics openspec/archive/2026-04-24-enterprise-events-metrics`