suaveplan/openspec/archive/2026-05-19-add-api-plugin-sse/tasks.md

Tasks — add-api-plugin-sse

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/api-plugin-sse.md end-to-end
• 1.2 Read genesis api-plugin-auth reference impl
• 1.3 Read openspec/AGENTS.md §13/§14 + enterprise-package-migration skill
• 1.4 Draft proposal.md from template with Source mapping
• 1.5 Draft specs/api-plugin-sse/spec.md with **Verified by:** lines

2. Implementation

• 2.1 Scaffold packages/api/api-plugin-sse/ with src/{plugin,services,middleware,formatter,buffer,fanout,schemas,otel,error-codes,types,registry}/ + tests/{setup,integration}/
• 2.2 package.json v0.1.0 with 14 subpath exports + tsconfig + vite + vitest configs
• 2.3 src/error-codes/error-codes.{ts,test,md} — 8 SSE.* codes + SseError
• 2.4 src/types/types.ts — SseEvent, SubscriptionHandle, SseStats, SsePluginOptions, SsePluginConfig
• 2.5 src/schemas/options.{ts,test,md} + src/schemas/event.{ts,test,md} — Zod boundary schemas
• 2.6 src/buffer/ring-buffer.{ts,test,md} — bounded per-channel ring buffer
• 2.7 src/fanout/in-process.{ts,test,md} — listener-set fanout
• 2.8 src/formatter/format.{ts,test,md} + src/formatter/parse.{ts,test,md} — wire format + streaming parser
• 2.9 src/otel/instruments.{ts,test,md} — UpDownCounter + Counters + Histogram
• 2.10 src/services/service.{ts,test,md} — SseService impl (broadcast/subscribe/close/stats)
• 2.11 src/registry/service-registry.{ts,md} — module augmentation
• 2.12 src/middleware/sse-handler.{ts,test,md} — Hono streamSSE handler with heartbeat/abort/resume/backpressure
• 2.13 src/plugin/plugin.{ts,test,md} + src/plugin/on-init.test.ts — createSsePlugin + 6-step onInit
• 2.14 src/index.ts — named re-exports
• 2.15 src/api-plugin-sse.spec-conformance.test.ts — type-level + every-code-thrown assertions

3. Tests

• 3.1 Co-located *.test.ts per scenario
• 3.2 Spec-conformance test pinning types + error registry reachability
• 3.3 tests/integration/full-stream.test.ts — real Hono app + real fetch; 3 ordered events, Last-Event-ID resume, heartbeat via FakeClock
• 3.4 tests/dep-graph.test.ts — exports map matches documented subpaths
• 3.5 All tests imported from @suaveplan/testing/runner; { timeout: 5000 } (60000 for integration)

4. Documentation

• 4.1 Sibling .md for every impl (≥200 words, basic + advanced examples, full API reference)
• 4.2 README with quick-start, modules, 3-way contract notes

5. Pre-archive 5-gate

• 5.1 bun run check — Biome 0/0/0 across the monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-sse --force
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-sse 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-sse exit 0
• 5.5 bunx turbo build --filter=@suaveplan/api-plugin-sse --force
• 5.6 bun scripts/lint/check-test-runner-imports.ts exit 0

6. Pre-archive 9-row checklist

• 6.1 Generics threaded; expectTypeOf on SseService / ServiceRegistry augmentation / SseEvent
• 6.2 Zod schemas wired at every declared boundary
• 6.3 Every error code in error-codes.ts thrown by ≥1 production path
• 6.4 Strict-mode behaviors tested both on and off (overflowPolicy variants)
• 6.5 OTel instruments emitted + asserted via real in-memory MeterProvider
• 6.6 Lifecycle dedup tested (idempotent close)
• 6.7 No retroactive tick — every box reflects work in this change
• 6.8 No export * in feature barrels (grep clean)
• 6.9 No direct vitest/bun:test imports in tests (grep clean)

7. Archive

• 7.1 Fold spec → openspec/specs/api-plugin-sse/spec.md
• 7.2 mv openspec/changes/add-api-plugin-sse → openspec/archive/2026-05-18-add-api-plugin-sse/
• 7.3 DO NOT refresh MANIFEST / STATUS per orchestrator directive