# Tasks: enterprise-events-transport

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

## Prerequisites (must be published to Verdaccio first)

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

## Optional peer (for trace context injection)

- [x] `@suaveplan/events-otel` — if present, `serializeTraceContext`/`deserializeTraceContext` are used automatically

## Tasks

### 1. Scaffold package

- [x] Create `universal/events/events-transport/` directory tree per file layout in `proposal.md`
- [x] Write `package.json` (name `@suaveplan/events-transport`, 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 `EventsTransportErrorCode` union type
- [x] Call `defineCodes` to register all `EVENTS_TRANSPORT.*` codes
- [x] Export `registerEventsTransportErrorCodes()` and `EventsTransportError`

### 3. Types (`src/types/common.ts`)

- [x] Define and export `EventTransport`, `DeliveryGuarantee`, `ConnectOptions`, `TransportHandle`, `TransportStats`
- [x] Write `common.md`

### 4. Transport envelope (`src/core/envelope/`)

- [x] Define `TransportEnvelope` interface and `TransportEnvelopeSchema` Zod schema
- [x] Export stable envelope version constant `ENVELOPE_VERSION = 1`
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

### 5. Nonce dedup window (`src/core/nonce-window/`)

- [x] Implement LRU sliding window of received nonces with configurable `windowSize`
- [x] `has(nonce)` and `add(nonce)` methods
- [x] Write `.md`, `.test.ts`, `index.ts`

### 6. Structured-clone safety check (`src/utils/structured-clone-check.ts`)

- [x] Implement `isStructuredCloneable(value)` — attempt `structuredClone(value)` and return false on error
- [x] Implement `assertStructuredCloneable(value)` — throws `EventsTransportError("EVENTS_TRANSPORT_NOT_CLONEABLE")`
- [x] Write `.md` and `.test.ts`

### 7. MessageChannel transport (`src/transports/message-channel/`)

- [x] Implement at-least-once delivery: send envelope, wait for ack within `ackTimeoutMs`, retry up to `maxRetries`
- [x] Receiver sends ack immediately after re-dispatching
- [x] Nonce dedup window prevents duplicate re-dispatch
- [x] OTel span linking: `events_transport.send` and `events_transport.receive` linked via trace context in envelope
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

### 8. BroadcastChannel transport (`src/transports/broadcast-channel/`)

- [x] Implement at-most-once delivery: fire-and-forget with nonce dedup on receive
- [x] Optional origin filter
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

### 9. Tests

- [x] Unit tests co-located (100% coverage target)
- [x] `tests/integration.test.ts` — real MessageChannel and BroadcastChannel in Bun worker context; assert delivery and dedup behaviour
- [x] `tests/property.test.ts` — fast-check properties per `proposal.md` §5

### 10. Docs

- [x] Every `.ts` implementation file has a sibling `.md`
- [x] Root `README.md`

### 11. Pre-publish gate

- [x] `bunx turbo lint typecheck test --filter=@suaveplan/events-transport` green
- [x] `bunx turbo test:coverage --filter=@suaveplan/events-transport` ≥ 100% on touched modules

### 12. Publish

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

### 13. Archive

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