Initial Commit

openspec/archive/2026-04-24-enterprise-queue/tasks.md

@@ -0,0 +1,84 @@
+# Tasks: enterprise-queue
+
+- **Change ID**: enterprise-queue
+- **Package**: `@suaveplan/queue`
+- **Date**: 2026-04-24
+
+## Prerequisites (must be published to Verdaccio first)
+
+- [x] `@suaveplan/error`
+- [x] `@suaveplan/types`
+- [x] `@suaveplan/events`
+
+## Tasks
+
+### 1. Scaffold package
+
+- [x] Create `universal/streams/queue/` directory tree per file layout in `proposal.md`
+- [x] Write `package.json` (name `@suaveplan/queue`, version `0.1.0`, `sideEffects: false`, correct workspace deps)
+- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`
+- [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`
+
+### 2. Error codes (`src/error-codes.ts`)
+
+- [x] Define `QueueErrorCode` union type
+- [x] Call `defineCodes` to register all `QUEUE.*` codes
+- [x] Export `registerQueueErrorCodes()` and `QueueError`
+
+### 3. Types (`src/types/common.ts`)
+
+- [x] Define and export `Queue<T>`, `Job<T>`, `JobState`, `QueueWorker`, `QueueWorkerOptions`, `RetryPolicy`, `WorkerStats`
+- [x] Write `common.md`
+
+### 4. Queue implementations
+
+- [x] `createMemoryQueue<T>` in `src/queues/memory-queue/` — FIFO with `maxSize` bound, injectable clock/idGenerator/bus
+- [x] `createPriorityQueue<T>` in `src/queues/priority-queue/` — max-heap by `job.priority`
+- [x] `createDelayedQueue<T>` in `src/queues/delayed-queue/` — delayed dequeue based on `job.scheduledAt` with injectable clock
+- [x] Each: `.ts`, `.md`, `.types.ts`, `.test.ts`, `index.ts`; Zod options schema; lifecycle events on bus
+
+### 5. Retry policy helpers (`src/utils/retry-policy.ts`)
+
+- [x] Implement constant, linear, exponential backoff delay computation
+- [x] Write `.md` and `.test.ts`
+
+### 6. QueueWorker (`src/worker/queue-worker/`)
+
+- [x] Implement `createQueueWorker<T>` with:
+  - Configurable `concurrency` (semaphore-based)
+  - `AbortSignal` propagation to handler
+  - Retry loop per `RetryPolicy` on handler failure
+  - Dead letter queue routing after `maxRetries` exhausted
+  - `WorkerStats` accumulation
+  - Job lifecycle event emission via `@suaveplan/events` bus
+  - OTel spans, counters, histogram per `proposal.md` §3
+- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`
+
+### 7. Tests
+
+- [x] Unit tests co-located (100% coverage target)
+- [x] `tests/integration.test.ts` — enqueue jobs, start worker, assert completion stats and events
+- [x] `tests/property.test.ts` — fast-check properties per `proposal.md` §4
+
+### 8. Benchmarks (`src/__benchmarks__/queue.bench.ts`)
+
+- [x] Implement benchmark cases per `proposal.md` §5
+
+### 9. Docs
+
+- [x] Every `.ts` implementation file has a sibling `.md`
+- [x] Root `README.md`
+
+### 10. Pre-publish gate
+
+- [x] `bunx turbo lint typecheck test --filter=@suaveplan/queue` green
+- [x] `bunx turbo test:coverage --filter=@suaveplan/queue` ≥ 100% on touched modules
+
+### 11. Publish
+
+- [x] `bun scripts/publish.ts --package @suaveplan/queue`
+
+### 12. Archive
+
+- [x] Fold spec delta into `openspec/specs/streams/spec.md`
+- [x] `mv openspec/changes/enterprise-queue openspec/archive/2026-04-24-enterprise-queue`