# Tasks: enterprise-events-otel

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

## Prerequisites (must be published to Verdaccio first)

- [x] `@suaveplan/events`
- [x] `@suaveplan/error`
- [x] `@suaveplan/types`

## Tasks

### 1. Scaffold package

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

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

- [x] Export `SPAN_ATTRIBUTES` and `SPAN_NAMES` as `as const` objects

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

- [x] Implement `SamplingRule` type union and decision function
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

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

- [x] Implement `serializeTraceContext()` using `@opentelemetry/api` W3C propagator
- [x] Implement `deserializeTraceContext(headers)` restoring context
- [x] Write `.md`, `.test.ts`, `index.ts`

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

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

### 7. Tests

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

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

### 10. Publish

- [x] `bun scripts/publish.ts --package @suaveplan/events-otel`

### 11. Archive

- [x] Fold spec delta into `openspec/specs/events/spec.md`
- [x] `mv openspec/changes/enterprise-events-otel openspec/archive/2026-04-24-enterprise-events-otel`