Initial Commit

openspec/archive/2026-05-26-api-events-in-memory/proposal.md

@@ -0,0 +1,54 @@
+# `@suaveplan/api-events-in-memory` — In-memory events bus for tests
+
+**Package**: `@suaveplan/api-events-in-memory`
+**Status**: PROPOSED
+**Type**: new-package
+**Stage**: 5 (Testing kit + conformance suites) — see umbrella `openspec/changes/api-plugin-foundation/`
+
+## Why
+
+Per design doc §13.2, the testing kit needs an events bus whose `publish` calls are recordable so tests can assert side effects:
+
+```ts
+expect(host.events.published("billing.invoice.created")).toHaveLength(1);
+```
+
+The simplest correct implementation wraps `@suaveplan/events` (production-grade pub/sub) with a recording layer. Subscribers fire as usual; publish history is queryable; ordering and idempotency invariants from the real bus are preserved. No mocks, no test doubles.
+
+## What changes
+
+Net-new package depending on `@suaveplan/api-events` (contract + `./testing` conformance), `@suaveplan/api-types`, `@suaveplan/events` (production bus), `@suaveplan/error`, `zod`.
+
+- ADDED: `createInMemoryEventsBus(opts)` — factory returning an `EventBusLike` (per `@suaveplan/api-types`) wrapping `@suaveplan/events`'s `createEventBus`.
+- ADDED: `host.events.published(topic)` — returns an array of every payload published to `topic` since `reset()` (or since construction).
+- ADDED: `host.events.reset()` — clears the publish history (subscribers remain registered).
+- ADDED: `InMemoryEventsBusOptions` — Zod schema (`maxHistoryPerTopic?: number` (default 1000 — guard against runaway tests)).
+- ADDED: `EVENTS_IN_MEMORY_*` error codes (`EVENTS_IN_MEMORY_HISTORY_OVERFLOW`, `EVENTS_IN_MEMORY_INVALID_OPTIONS`).
+- ADDED: Registered in `@suaveplan/api-host/testing`'s adapter table as `events: "in-memory"`.
+
+## Out of scope
+
+- Persistence across process restarts — by design, in-memory.
+- Multi-host fan-out — `api-events-redis` future work.
+- Bounded-queue backpressure — `@suaveplan/events` already provides this; this adapter inherits the behaviour and runs the bounded-queue conformance scenarios from `api-events/testing`.
+
+## Source mapping
+
+Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
+
+| Requirement | Design doc section |
+|---|---|
+| `host.events.published(topic)` query | §13.2 |
+| Real bus underneath, not a double | §13.2 (final paragraph) |
+| Registered in `api-host/testing` adapter table | §15 Stage 5 |
+
+## Verification approach
+
+- `src/factory/create-in-memory-events-bus.test.ts` — publish/subscribe, history capture, reset, ordering preserved.
+- `src/factory/create-in-memory-events-bus.spec-conformance.test.ts` — `runEventsBusConformance("in-memory-direct", ...)`.
+- `src/history/history.test.ts` — overflow protection at `maxHistoryPerTopic`.
+- `tests/integration/integration.test.ts` — via `createTestHost`; assertion API from §13.2 example works end-to-end.
+
+## Migration impact
+
+None — additive only.