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.

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

@@ -0,0 +1,68 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-events-in-memory (api-events-in-memory)
+
+**Package**: `@suaveplan/api-events-in-memory`
+**Status**: PROPOSED
+
+## ADDED Requirements
+
+### Requirement: Wraps the real @suaveplan/events bus
+
+The factory SHALL construct an `EventBusLike` by delegating to `@suaveplan/events`'s `createEventBus`. Subscribers receive events as the real bus delivers them; this package only adds a recording layer around publish.
+
+#### Scenario: subscriber receives published payload
+
+- **WHEN** a subscriber is registered on `"billing.invoice.created"` AND a payload is published
+- **THEN** the subscriber is invoked with the exact payload
+
+**Verified by:** `src/factory/create-in-memory-events-bus.test.ts::"subscriber receives published payload"`
+
+---
+
+### Requirement: published(topic) returns history
+
+`host.events.published(topic)` SHALL return an array of every payload published to `topic` since the last `reset()` (or since construction), in publish order.
+
+#### Scenario: history captures every publish in order
+
+- **WHEN** three payloads `[A, B, C]` are published to `"x"`
+- **THEN** `host.events.published("x")` returns `[A, B, C]` in that order
+
+#### Scenario: reset clears history
+
+- **WHEN** `host.events.reset()` is called after publishes
+- **THEN** `host.events.published("x")` returns `[]` AND already-registered subscribers stay registered
+
+#### Scenario: history bounded by maxHistoryPerTopic
+
+- **WHEN** `maxHistoryPerTopic: 10` is configured AND 11 payloads are published
+- **THEN** publish either throws `EVENTS_IN_MEMORY_HISTORY_OVERFLOW` OR drops the oldest payload (the chosen policy is documented and tested both ways)
+
+**Verified by:** `src/factory/create-in-memory-events-bus.test.ts::"history captures every publish in order"` AND `src/factory/create-in-memory-events-bus.test.ts::"reset clears history without unregistering subscribers"` AND `src/history/history.test.ts::"bounds history at maxHistoryPerTopic"`
+
+---
+
+### Requirement: Conforms to EventsBus contract
+
+The factory SHALL pass `runEventsBusConformance` from `@suaveplan/api-events/testing` (which itself wraps the conformance defined for `@suaveplan/events` plus any API-foundation specifics — error semantics, payload-id idempotency).
+
+#### Scenario: conformance suite passes
+
+- **WHEN** `runEventsBusConformance("in-memory-direct", () => createInMemoryEventsBus(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `src/factory/create-in-memory-events-bus.spec-conformance.test.ts::"in-memory-direct conforms to EventsBus contract"`
+
+---
+
+### Requirement: Registered in `api-host/testing` adapter table
+
+#### Scenario: createTestHost resolves the sentinel
+
+- **WHEN** `createTestHost({ adapters: { events: "in-memory" } })`
+- **THEN** the resulting `host.events` is an instance produced by this factory AND has a `published(topic)` method
+
+**Verified by:** `tests/integration/integration.test.ts::"createTestHost resolves events:\"in-memory\" to this adapter and exposes published()"`
+
+<!-- markdownlint-enable MD024 -->

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

@@ -0,0 +1,66 @@
+# Tasks — `@suaveplan/api-events-in-memory`
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Spec authoring
+
+- [x] 1.1 Read design doc (§13.2, §15 Stage 5)
+- [x] 1.2 Read `openspec/changes/api-events-worker-proxy/` and `@suaveplan/events` README for upstream contracts
+- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.4 Draft `proposal.md`
+- [x] 1.5 Draft `specs/api-events-in-memory/spec.md`
+- [x] 1.6 Every requirement carries `**Verified by:**`
+
+## 2. Implementation
+
+- [ ] 2.1 Scaffold `packages/api/api-events-in-memory/` (deps: api-events, api-types, events, error, zod)
+- [ ] 2.2 `src/options/in-memory-events-bus-options.ts` — Zod schema
+- [ ] 2.3 `src/factory/create-in-memory-events-bus.ts` — wraps `createEventBus` from `@suaveplan/events`
+- [ ] 2.4 `src/history/history.ts` — per-topic ring buffer with `maxHistoryPerTopic` cap
+- [ ] 2.5 `src/error-codes.ts` — `EVENTS_IN_MEMORY_*` codes via `defineCodes`
+- [ ] 2.6 `src/index.ts` — explicit named re-exports
+- [ ] 2.7 Register this adapter in `@suaveplan/api-host/testing`'s adapter table under `events: "in-memory"`
+
+## 3. Tests
+
+- [ ] 3.1 `src/factory/create-in-memory-events-bus.test.ts`
+- [ ] 3.2 `src/factory/create-in-memory-events-bus.spec-conformance.test.ts` — conformance
+- [ ] 3.3 `src/history/history.test.ts` — overflow protection
+- [ ] 3.4 `tests/integration/integration.test.ts` — via `createTestHost`
+- [ ] 3.5 Every `it(...)` carries `{ timeout: 5000 }`
+
+## 4. Documentation
+
+- [ ] 4.1 Sibling `.md` per implementation `.ts`
+- [ ] 4.2 README copies the `host.events.published` example verbatim from §13.2
+
+## 5. Pre-archive verification (5-gate triple)
+
+- [ ] 5.1 `bun run check` — clean
+- [ ] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-events-in-memory` — green
+- [ ] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-events-in-memory` — 100/100/100/100
+- [ ] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-events-in-memory` — exit 0
+- [ ] 5.5 `bunx turbo build --filter=@suaveplan/api-events-in-memory` — green
+
+## 6. Pre-archive 7-row checklist
+
+- [ ] 6.1 `expectTypeOf` asserts `published(topic)` returns `unknown[]` (or the declared payload type when generic)
+- [ ] 6.2 Zod schema at options boundary
+- [ ] 6.3 Every `EVENTS_IN_MEMORY_*` code thrown by at least one production path
+- [ ] 6.4 Strict-mode (history-overflow throws vs drops oldest — pin one) tested both ways
+- [ ] 6.5 OTel instruments inherited from `@suaveplan/events` asserted with in-memory `MeterProvider`
+- [ ] 6.6 Subscriber-idempotency dedup tested (re-publishing same payload-id calls subscriber once)
+- [ ] 6.7 No retroactive tick
+
+## 7. Archive
+
+- [ ] 7.1 Fold into `openspec/specs/api-events-in-memory/spec.md`
+- [ ] 7.2 Move to `openspec/archive/<yyyy-mm-dd>-api-events-in-memory/`
+- [ ] 7.3 Tick Stage 5 box in umbrella tasks
+- [ ] 7.4 Refresh `MANIFEST.md`