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

Tasks: enterprise-events-transport

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

Prerequisites (must be published to Verdaccio first)

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

Optional peer (for trace context injection)

• @suaveplan/events-otel — if present, serializeTraceContext/deserializeTraceContext are used automatically

Tasks

1. Scaffold package

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

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

• Define and export EventTransport, DeliveryGuarantee, ConnectOptions, TransportHandle, TransportStats
• Write common.md

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

• Define TransportEnvelope interface and TransportEnvelopeSchema Zod schema
• Export stable envelope version constant ENVELOPE_VERSION = 1
• Write .md, .types.ts, .test.ts, index.ts

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

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

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

• Implement isStructuredCloneable(value) — attempt structuredClone(value) and return false on error
• Implement assertStructuredCloneable(value) — throws EventsTransportError("EVENTS_TRANSPORT_NOT_CLONEABLE")
• Write .md and .test.ts

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

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

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

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

9. Tests

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

10. Docs

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

11. Pre-publish gate

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

12. Publish

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

13. Archive

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