# `@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.