Initial Commit

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

@@ -0,0 +1,92 @@
+# 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`