suaveplan/openspec/archive/2026-05-02-events-v1.1.0-port/proposal.md

@suaveplan/events v1.1.0 — Port Missing Capabilities from Suaveplan

Status: Active
Target: @suaveplan/events 0.0.0 → additive capabilities, no breaking changes
Source: /home/ubuntu/web/suaveplan/openspec/changes/events-v1.1.0/

---

Why

The genesis EventBus was a cut-down redesign of suaveplan's EventEmitter. While it introduced improvements (interceptor API, BoundedQueue, idempotent listeners, deterministic injection), it was missing several capabilities that suaveplan had already proven necessary:

• No event buffering for late subscribers — plugins attaching after lifecycle transitions miss historical events.
• No wildcard pattern matching — observers must enumerate every event name.
• No async iteration — consumers manually manage on/off instead of for await.
• No prependListener — impossible to insert a listener at the head.
• No listener introspection — listeners() / listenerCount() absent.
• No once() → off() round-trip — off(type, originalListener) fails for once registrations.
• No concurrency control on emitAsync — one slow listener blocks the chain.
• No maxListeners warning — memory leaks go undetected.
• No global errorSink — caller must inspect EmitResult.errors or errors are lost.
• No Symbol.dispose — no RAII cleanup via using.

These gaps force consumers to reinvent the missing primitives downstream.

---

What changes

Core EventBus additions

1. bufferSize option — replays the last N events to subscribers that attach after emission.
2. wildcard option — subscribe to plugin:* and match all plugin:ready, plugin:error, etc.
3. iter(type, signal?) — async iterable over events, compatible with for await.
4. prepend(type, listener) — insert listener at the head of the dispatch queue.
5. listeners(type) / listenerCount(type) — introspection without exposing internals.
6. offAll(type?) — remove all listeners for a type, or everything.
7. once() WeakMap tracking — off(type, originalListener) works for once registrations.
8. concurrency option on emitAsync — sequential (default), parallel, allSettled.
9. maxListeners + errorSink — warnings and centralised error routing.
10. Symbol.dispose on EventBus and Unsubscribe handles.
11. EVENTS.LISTENER.MAX_EXCEEDED error code.

Non-goals

• No breaking changes to existing EventBus API.
• No BoundedQueue integration into EventBus dispatch — remains a standalone utility.
• No changes to companion packages (events-otel, events-schema, events-metrics, events-transport) unless required by API additions.

---

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/events to enumerate. All additive surface, so no downstream code changes required. Verified by running downstream test suites.

• @suaveplan/crypto-vault — no action needed (uses EventBus directly, doesn't touch changed surface)
• @suaveplan/network — no action needed (uses EventBus + BoundedQueue, unchanged)
• @suaveplan/storage — no action needed
• @suaveplan/packer — no action needed
• @suaveplan/fsm — no action needed
• @suaveplan/retry — no action needed
• @suaveplan/migration — no action needed (type-only import)
• @suaveplan/config — no action needed
• @suaveplan/events-schema — no action needed (type-only import)
• @suaveplan/events-metrics — no action needed (type-only import)
• @suaveplan/events-otel — no action needed (type-only import)
• @suaveplan/events-transport — no action needed (type-only import)

---

Migration

No migration needed — purely additive.