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

Tasks: enterprise-events-metrics

• Change ID: enterprise-events-metrics
• Package: @suaveplan/events-metrics
• Date: 2026-04-24

Prerequisites (must be published to Verdaccio first)

• @suaveplan/events
• @suaveplan/opentelemetry
• @suaveplan/error
• @suaveplan/types

Tasks

1. Scaffold package

• Create universal/events/events-metrics/ directory tree per file layout in proposal.md
• Write package.json (name @suaveplan/events-metrics, version 0.1.0, sideEffects: false, correct workspace deps)
• Write tsconfig.json extending @suaveplan/typescript-config/library.json
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config

2. Error codes (src/error-codes.ts)

• Define EventsMetricsErrorCode union type
• Call defineCodes to register all EVENTS_METRICS.* codes
• Export registerEventsMetricsErrorCodes() and EventsMetricsError

3. Metric name constants (src/metrics/metric-names/)

• Export METRIC_NAMES and ATTRIBUTE_KEYS as as const objects
• Write metric-names.md and index.ts

4. Core attachEventMetrics (src/core/attach-event-metrics/)

• Implement attachEventMetrics(bus, options?) using @suaveplan/events interceptor API only
• Zero-allocation hot path: pre-cache event-name → attribute set on first dispatch; no object creation on subsequent dispatches for the same event name
• Counter: DISPATCH_TOTAL per event.name
• Counter: LISTENER_ERROR_TOTAL per event.name + listener.id
• Histogram: DISPATCH_LATENCY_MS using performance.now() or injectable clock
• ObservableGauge: QUEUE_DEPTH and ACTIVE_SUBSCRIBERS — polled at collection time, not per-dispatch
• Return EventMetricsHandle with detach() and snapshot()
• Write .md, .types.ts, .test.ts, index.ts

5. Snapshot (src/metrics/snapshot/)

• Implement MetricsSnapshot accumulator that mirrors the OTel metric state in-memory for test/introspection
• Write .md, .test.ts, index.ts

6. Tests

• Unit tests co-located (100% coverage target)
• tests/integration.test.ts — attach to real EventBus, dispatch events, assert snapshot counts match
• tests/property.test.ts — fast-check properties per proposal.md §4

7. Benchmarks (src/__benchmarks__/events-metrics.bench.ts)

• Overhead benchmark: instrumented vs uninstrumented bus at high dispatch frequency
• Snapshot retrieval benchmark

8. Docs

• Every .ts implementation file has a sibling .md
• Root README.md

9. Pre-publish gate

• bunx turbo lint typecheck test --filter=@suaveplan/events-metrics green
• bunx turbo test:coverage --filter=@suaveplan/events-metrics ≥ 100% on touched modules

10. Publish

• bun scripts/publish.ts --package @suaveplan/events-metrics

11. Archive

• Fold spec delta into openspec/specs/events/spec.md
• mv openspec/changes/enterprise-events-metrics openspec/archive/2026-04-24-enterprise-events-metrics