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

Tasks: enterprise-events-otel

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

Prerequisites (must be published to Verdaccio first)

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

Tasks

1. Scaffold package

• Create universal/events/events-otel/ directory tree per file layout in proposal.md
• Write package.json (name @suaveplan/events-otel, version 0.1.0, sideEffects: false, correct workspace deps and @opentelemetry/api catalog dep)
• 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 EventsOtelErrorCode union type
• Call defineCodes to register all EVENTS_OTEL.* codes
• Export registerEventsOtelErrorCodes() and EventsOtelError

3. Span attribute constants (src/constants/index.ts)

• Export SPAN_ATTRIBUTES and SPAN_NAMES as as const objects

4. Sampling rule (src/sampling/sampling-rule/)

• Implement SamplingRule type union and decision function
• Write .md, .types.ts, .test.ts, index.ts

5. Trace context propagation (src/propagation/trace-context/)

• Implement serializeTraceContext() using @opentelemetry/api W3C propagator
• Implement deserializeTraceContext(headers) restoring context
• Write .md, .test.ts, index.ts

6. Core attachEventTracing (src/core/attach-event-tracing/)

• Implement attachEventTracing(bus, options?) via @suaveplan/events interceptor API only
• Create events.dispatch span per dispatch; run listeners within that context
• Create events.listener child span per listener invocation
• Set span.status = ERROR and call span.recordException(err) on listener throw
• Apply SamplingRule — check parent sampling decision first
• Return EventTracingHandle with detach()
• Write .md, .types.ts, .test.ts, index.ts

7. Tests

• Unit tests co-located (100% coverage target)
• tests/integration.test.ts — attach to real EventBus with in-memory OTel SDK, dispatch events, assert span tree structure and attributes
• tests/property.test.ts — fast-check properties per proposal.md §5

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-otel green
• bunx turbo test:coverage --filter=@suaveplan/events-otel ≥ 100% on touched modules

10. Publish

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

11. Archive

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