suaveplan/openspec/archive/2026-05-26-api-ws-broker-in-memory/tasks.md

Tasks — @suaveplan/api-ws-broker-in-memory

Every checkbox MUST reflect work actually done in this change.

0. Pre-flight (non-negotiable)

• 0.1 Clean working tree confirmed in worktree (git status clean before changes).
• 0.2 Worktree accounted for — agent-a080e5bdf978057c8 is this active agent; will be removed on merge.
• 0.3 Manifest re-generation triggered after package add (see §7.4).

1. Spec authoring

• 1.1 Read api-ws Stage-1 contract (packages/api-stack/api/api-ws/src/broker/broker.ts)
• 1.2 Read api-ws testing harness (runWsEngineConformance)
• 1.3 Read openspec/changes/api-ws-broker-in-memory/proposal.md and existing spec delta
• 1.4 Reconciled spec to actual WsBroker contract (publish/subscribe(topic,handler)/dispose) — diverged from initial connectionId-style proposal which did not match the upstream contract
• 1.5 Folded reconciled spec into openspec/specs/api-ws-broker-in-memory/spec.md
• 1.6 Every requirement carries **Verified by:**

2. Implementation

• 2.1 Scaffolded packages/api-stack/api/api-ws-broker-in-memory/ (deps: api-ws, api-types, error, tslib, zod)
• 2.2 src/options/options.ts — InMemoryWsBrokerOptions + strict Zod schema + resolveInMemoryWsBrokerOptions
• 2.3 src/broker/broker.ts — createInMemoryWsBroker(options?) factory returning InMemoryWsBroker<Payload> (extends abstract WsBroker<Payload> + subscriberCount + isDisposed)
• 2.4 Delivery mode handled inline in broker.ts dispatch() — await-all awaits Promise.all, fire-and-forget returns sync after dispatch
• 2.5 src/error-codes/error-codes.ts — WS_BROKER_IN_MEMORY_CODES (INVALID_OPTIONS, BROKER_DISPOSED) via defineCodes
• 2.6 src/index.ts — explicit named re-exports (no export *)
• 2.7 src/testing/testing.ts — createInMemoryBrokerHarness shipped under ./testing subpath

3. Tests

• 3.1 src/broker/broker.test.ts — 15 tests covering fan-out, isolation, lifecycle, dispose
• 3.2 tests/conformance/api-ws-broker.conformance.test.ts — WsBroker type+behaviour conformance
• 3.3 Delivery-mode behaviour exercised inline in broker.test.ts (isolates handler rejections in {fire-and-forget,await-all} mode)
• 3.4 src/testing/testing.test.ts — harness behaviour
• 3.5 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md per implementation .ts — broker.md, options.md, error-codes.md, testing.md (docs:check 4/4 100%)
• 4.2 README documents single-host topology and points operators to api-ws-broker-redis for multi-host

5. Pre-archive verification gates

• 5.1 bunx turbo lint --filter=@suaveplan/api-ws-broker-in-memory — green
• 5.2 bunx turbo typecheck --filter=@suaveplan/api-ws-broker-in-memory — green
• 5.3 bunx turbo test --filter=@suaveplan/api-ws-broker-in-memory — 34/34 passed
• 5.4 bunx turbo test:coverage --filter=@suaveplan/api-ws-broker-in-memory — 100/100/100/100 (istanbul)
• 5.5 bunx turbo build --filter=@suaveplan/api-ws-broker-in-memory — green

6. Pre-archive checklist

• 6.1 expectTypeOf(broker).toMatchTypeOf<WsBroker<Payload>>() asserted in conformance test
• 6.2 Zod strict-mode schema at options boundary
• 6.3 Both WS_BROKER_IN_MEMORY.* codes (INVALID_OPTIONS, BROKER_DISPOSED) thrown by ≥1 production path each; covered by tests
• 6.4 Both delivery modes (fire-and-forget, await-all) exercised under both happy-path and rejecting-handler scenarios
• 6.5 Snapshot-before-dispatch behaviour asserted ("publish snapshot is stable against mid-fan-out unsubscribe")
• 6.6 Dispose idempotency asserted explicitly
• 6.7 No // biome-ignore suppressions; no direct vitest/bun:test imports (verified by grep)

7. Archive

• 7.1 Folded into openspec/specs/api-ws-broker-in-memory/spec.md
• 7.2 Moved to openspec/archive/2026-05-26-api-ws-broker-in-memory/
• 7.3 STATUS.md ticked (see commit)
• 7.4 Manifest regenerated via bun scripts/folder-reorg/generate-manifest.ts