@madeinoz67/voice-server 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,374 @@
1
+ # Research: FIFO Notification Queue
2
+
3
+ **Feature**: FIFO Notification Queue
4
+ **Date**: 2026-02-09
5
+ **Status**: Complete
6
+
7
+ ## Overview
8
+
9
+ This document consolidates research findings for implementing a FIFO queue for the voice server's `/notify` endpoint. The queue must handle concurrent requests, process them sequentially, and return 201 Accepted immediately.
10
+
11
+ ---
12
+
13
+ ## Queue Implementation Strategy
14
+
15
+ ### Decision: Array-based In-Memory Queue with Async/Await Processing
16
+
17
+ **Rationale**:
18
+ - Bun/TypeScript has native support for async/await and Promise-based patterns
19
+ - Array operations are fast for queue sizes ≤ 100 items
20
+ - No external dependencies required
21
+ - Simple to implement and maintain
22
+ - Preserves FIFO ordering naturally (shift/push operations)
23
+
24
+ **Alternatives Considered**:
25
+ - **Linked List**: More complex to implement in TypeScript, no performance benefit for small queues
26
+ - **Bun Atomics**: Overkill for single-worker scenario, adds complexity
27
+ - **Bun Workers**: Unnecessary overhead for single-threaded queue processing
28
+ - **External Queue Libraries** (bull, bee-queue): Too heavy for local voice server use case
29
+
30
+ **Implementation Pattern**:
31
+ ```typescript
32
+ interface QueuedNotification {
33
+ id: string;
34
+ message: string;
35
+ title?: string;
36
+ voice_id: string;
37
+ voice_settings?: ProsodySettings;
38
+ volume: number;
39
+ arrived_at: number;
40
+ status: "pending" | "processing" | "completed" | "failed";
41
+ }
42
+
43
+ class NotificationQueue {
44
+ private queue: QueuedNotification[] = [];
45
+ private processing = false;
46
+ private maxDepth = 100;
47
+
48
+ async enqueue(request: NotificationRequest): Promise<boolean> {
49
+ if (this.queue.length >= this.maxDepth) return false;
50
+ this.queue.push({ ...request, id: crypto.randomUUID(), arrived_at: Date.now(), status: "pending" });
51
+ this.processQueue().catch(() => {});
52
+ return true;
53
+ }
54
+
55
+ private async processQueue(): Promise<void> {
56
+ if (this.processing || this.queue.length === 0) return;
57
+ this.processing = true;
58
+
59
+ while (this.queue.length > 0) {
60
+ const item = this.queue.shift();
61
+ if (!item) break;
62
+
63
+ try {
64
+ await processTTS(item.message, item.voice_id, item.voice_settings || {}, item.volume);
65
+ } catch (error) {
66
+ logger.warn("TTS processing failed for queued item", { id: item.id, error });
67
+ }
68
+ }
69
+
70
+ this.processing = false;
71
+ }
72
+ }
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Concurrency & Producer-Consumer Pattern
78
+
79
+ ### Decision: Single Async Worker with Promise-Based Queue Processing
80
+
81
+ **Rationale**:
82
+ - Single worker maintains strict FIFO ordering (no concurrent processing)
83
+ - Async/await naturally handles the producer-consumer pattern
84
+ - Multiple producers (HTTP requests) can call `enqueue()` concurrently
85
+ - Queue is protected by JavaScript's single-threaded event loop
86
+ - `processing` flag prevents concurrent queue processing
87
+
88
+ **Alternatives Considered**:
89
+ - **Bun Workers**: Adds complexity with message passing, unnecessary for TTS bottleneck
90
+ - **Mutex/Semaphore**: JavaScript is single-threaded, atomic operations not needed
91
+ - **Concurrent Processing**: Would violate FIFO requirement and cause audio overlap
92
+
93
+ **Flow**:
94
+ 1. HTTP request arrives → `enqueue()` adds to array
95
+ 2. `enqueue()` triggers `processQueue()` if not already processing
96
+ 3. `processQueue()` marks processing flag, processes items sequentially
97
+ 4. Each item: `processTTS()` (await) → next item
98
+ 5. Queue empty → processing flag cleared
99
+
100
+ ---
101
+
102
+ ## Graceful Shutdown Strategy
103
+
104
+ ### Decision: Await Queue Drain with Timeout
105
+
106
+ **Rationale**:
107
+ - Ensures all queued notifications are played before exit
108
+ - Local voice server with short notifications (3-10s) makes this practical
109
+ - Users expect voice feedback to complete even during shutdown
110
+ - Timeout prevents indefinite hangs on errors
111
+
112
+ **Alternatives Considered**:
113
+ - **Immediate Shutdown**: Loses queued notifications, poor UX
114
+ - **Best-Effort Drain**: Same as chosen approach with explicit timeout
115
+ - **Persist Queue**: Out of scope per assumptions
116
+
117
+ **Implementation Pattern**:
118
+ ```typescript
119
+ const shutdown = async () => {
120
+ logger.info("Shutting down server...");
121
+
122
+ // Stop accepting new requests
123
+ server.stop();
124
+
125
+ // Drain queue with timeout
126
+ const drainTimeout = 30000; // 30 seconds
127
+ const startTime = Date.now();
128
+
129
+ while (queue.length > 0 && Date.now() - startTime < drainTimeout) {
130
+ await new Promise(resolve => setTimeout(resolve, 100));
131
+ }
132
+
133
+ if (queue.length > 0) {
134
+ logger.warn("Queue drain timeout, exiting with pending items", { remaining: queue.length });
135
+ }
136
+
137
+ logger.info("Server stopped");
138
+ process.exit(0);
139
+ };
140
+ ```
141
+
142
+ ---
143
+
144
+ ## Error Handling Strategy
145
+
146
+ ### Decision: Skip Failed Items, Continue Processing
147
+
148
+ **Rationale**:
149
+ - Single TTS failure shouldn't block entire queue
150
+ - Users want to hear remaining notifications
151
+ - Logging provides visibility into failures
152
+ - Graceful degradation aligns with Constitution Principle III
153
+
154
+ **Alternatives Considered**:
155
+ - **Stop on First Error**: Blocks remaining items, poor UX
156
+ - **Retry Failed Items**: Adds complexity, could cause indefinite loops
157
+ - **Dead Letter Queue**: Overkill for local voice server
158
+
159
+ **Validation Timing**:
160
+ - **Schema Validation**: Immediate (before enqueue) — return 400 Bad Request
161
+ - **Voice ID Validation**: Immediate (before enqueue) — return 400 Bad Request
162
+ - **TTS Synthesis Failure**: Deferred (during processing) — skip to next item
163
+
164
+ ---
165
+
166
+ ## Health Monitoring Strategy
167
+
168
+ ### Decision: Extend Existing HealthStatus Model with Queue Fields
169
+
170
+ **Rationale**:
171
+ - Existing `/health` endpoint infrastructure already in place
172
+ - Consistent with current monitoring patterns
173
+ - Simple addition of queue-related fields
174
+ - Health indicator (healthy/degraded/unavailable) aligns with existing status values
175
+
176
+ **Alternatives Considered**:
177
+ - **Separate `/queue/status` Endpoint**: Creates separate API surface, but required by spec
178
+ - **Circuit Breaker Pattern**: Overkill for local server
179
+ - **Push Notifications**: Out of scope per spec
180
+
181
+ **QueueState Model**:
182
+ ```typescript
183
+ interface QueueState {
184
+ depth: number;
185
+ processing_status: "idle" | "active";
186
+ health: "healthy" | "degraded" | "unavailable";
187
+ metrics?: {
188
+ average_wait_time_ms: number;
189
+ items_processed: number;
190
+ items_failed: number;
191
+ };
192
+ }
193
+ ```
194
+
195
+ **Health Determination**:
196
+ - `healthy`: TTS available, queue < 80% capacity
197
+ - `degraded`: TTS available but queue ≥ 80% capacity
198
+ - `unavailable`: TTS health check failed
199
+
200
+ ---
201
+
202
+ ## Rate Limiting Integration
203
+
204
+ ### Decision: Apply Rate Limits Before Queue Admission
205
+
206
+ **Rationale**:
207
+ - Existing rate limiter middleware applies to POST requests
208
+ - Rate limiting prevents abuse regardless of queue state
209
+ - Queue overflow (429) is separate from rate limit (429)
210
+ - Both protections apply at different layers
211
+
212
+ **Distinction**:
213
+ - **Rate Limit 429**: Too many requests from this client (time-window based)
214
+ - **Queue Full 429**: Server queue at capacity (depth-based)
215
+
216
+ **Response Codes**:
217
+ - Rate limit exceeded: `429 Too Many Requests` with existing rate limiter message
218
+ - Queue full: `429 Too Many Requests` with queue-specific message
219
+ - Both use same status code but different error messages
220
+
221
+ **No Retry-After Header**: Spec doesn't require it, can be added later if needed
222
+
223
+ ---
224
+
225
+ ## Dependencies & Integration Points
226
+
227
+ ### Existing Components Used
228
+
229
+ 1. **MLX TTS Client** (`src/ts/services/mlx-tts-client.ts`)
230
+ - Already has `synthesize()` method with streaming support
231
+ - Health check method available
232
+ - Used by existing `processTTS()` function
233
+
234
+ 2. **Logger** (`src/ts/utils/logger.ts`)
235
+ - Existing logging infrastructure
236
+ - Use for queue event logging (FR-008)
237
+
238
+ 3. **Text Sanitizer** (`src/ts/utils/text-sanitizer.ts`)
239
+ - Input validation before queuing
240
+ - Returns empty string for invalid input
241
+
242
+ 4. **Voice Loader** (`src/ts/services/voice-loader.ts`)
243
+ - Validate voice_id against available voices
244
+ - Returns list of available voices
245
+
246
+ 5. **Rate Limiter** (`src/ts/middleware/rate-limiter.ts`)
247
+ - Existing middleware, applies before queue check
248
+ - No changes needed
249
+
250
+ ### New Components Required
251
+
252
+ 1. **NotificationQueue Class** (`src/ts/services/notification-queue.ts`)
253
+ - Queue management
254
+ - Enqueue/dequeue operations
255
+ - Graceful shutdown support
256
+
257
+ 2. **QueueState Type** (`src/ts/models/queue.ts`)
258
+ - Type definitions for queue state
259
+ - Status response types
260
+
261
+ 3. **Queue Status Handler** (`src/ts/server.ts`)
262
+ - GET `/queue/status` endpoint handler
263
+
264
+ ---
265
+
266
+ ## Testing Strategy
267
+
268
+ ### Decision: Test-First with TDD Approach (Constitution Principle V)
269
+
270
+ **Unit Tests** (`tests/unit/services/notification-queue.test.ts`):
271
+ - Queue enqueue/dequeue operations
272
+ - FIFO ordering verification
273
+ - Max depth enforcement
274
+ - Processing state management
275
+ - Error handling (skip failed items)
276
+
277
+ **Integration Tests** (`tests/integration/queue-api.test.ts`):
278
+ - POST `/notify` returns 201 Accepted
279
+ - Multiple requests process sequentially
280
+ - Queue overflow returns 429
281
+ - Invalid requests return 400
282
+ - GET `/queue/status` returns correct state
283
+
284
+ **Test Doubles**:
285
+ - Mock `processTTS()` for unit tests
286
+ - Mock MLX TTS client for integration tests
287
+ - Fake timers for timing-sensitive tests
288
+
289
+ ---
290
+
291
+ ## Performance Considerations
292
+
293
+ ### Queue Operations
294
+
295
+ - **Enqueue**: O(1) array push
296
+ - **Dequeue**: O(n) array shift, but n ≤ 100 so negligible
297
+ - **Memory**: ~1KB per queued item (100 items = ~100KB max)
298
+
299
+ ### Response Times
300
+
301
+ - **201 Accepted**: < 10ms (validation + array push)
302
+ - **Queue Status**: < 5ms (array length + status check)
303
+ - **Processing**: 3-10s per item (TTS synthesis time)
304
+
305
+ ### Bottlenecks
306
+
307
+ - **TTS Synthesis**: Primary bottleneck, queue doesn't solve this
308
+ - **Sequential Processing**: By design (FIFO requirement)
309
+ - **Queue Depth**: Limited to 100 items prevents memory issues
310
+
311
+ ---
312
+
313
+ ## Security Considerations
314
+
315
+ ### Input Validation (Before Queue)
316
+
317
+ 1. **JSON Parse**: Handle malformed JSON, return 400
318
+ 2. **Schema Validation**: Required fields present, return 400
319
+ 3. **Type Validation**: String types, length limits, return 400
320
+ 4. **Voice ID Validation**: Against available voices, return 400
321
+ 5. **Text Sanitization**: Remove dangerous characters, return 400 if empty
322
+
323
+ ### Rate Limiting (Before Queue)
324
+
325
+ - Existing rate limiter applies (10 req/min per client)
326
+ - Prevents queue flooding from abusive clients
327
+
328
+ ### Queue Isolation
329
+
330
+ - In-memory queue = per-server instance
331
+ - No cross-client pollution
332
+ - Server restart = queue cleared
333
+
334
+ ---
335
+
336
+ ## Documentation Requirements
337
+
338
+ ### API Documentation (OpenAPI/Swagger)
339
+
340
+ **POST /notify**:
341
+ - Request body schema
342
+ - 201 Accepted response
343
+ - 400 Bad Request response (validation failure)
344
+ - 429 Too Many Requests response (queue full)
345
+
346
+ **GET /queue/status**:
347
+ - Response schema with queue depth, status, health
348
+ - 200 OK response (always, even when TTS unavailable)
349
+
350
+ ### Code Documentation
351
+
352
+ - JSDoc comments for `NotificationQueue` class
353
+ - Type definitions with documentation
354
+ - Inline comments for non-obvious logic
355
+
356
+ ---
357
+
358
+ ## Open Questions Resolved
359
+
360
+ All questions from spec clarification have been addressed:
361
+
362
+ 1. ✅ **Shutdown Behavior**: Drain queue before exit with 30s timeout
363
+ 2. ✅ **Queue Status Returns**: 200 OK with health indicator field
364
+ 3. ✅ **Invalid Request Handling**: Reject immediately (400) before queuing
365
+
366
+ ---
367
+
368
+ ## Next Steps
369
+
370
+ Proceed to Phase 1: Design & Contracts
371
+ - Generate `data-model.md` with entity definitions
372
+ - Generate API contracts in `/contracts/`
373
+ - Generate `quickstart.md` with development setup
374
+ - Update agent context with queue-specific information
@@ -0,0 +1,125 @@
1
+ # Feature Specification: FIFO Notification Queue
2
+
3
+ **Feature Branch**: `001-fifo-notify-queue`
4
+ **Created**: 2026-02-09
5
+ **Status**: Draft
6
+ **Input**: User description: "implement queue system https://github.com/madeinoz67/madeinoz-voice-server/issues/13"
7
+ **Related Issue**: https://github.com/madeinoz67/madeinoz-voice-server/issues/13
8
+
9
+ ## User Scenarios & Testing *(mandatory)*
10
+
11
+ ### User Story 1 - Sequential Audio Playback (Priority: P1)
12
+
13
+ When multiple automated agents send voice notifications simultaneously (e.g., during PAI Algorithm phase transitions), the system must play them in sequence rather than overlapping, ensuring each notification is clearly audible and intelligible.
14
+
15
+ **Why this priority**: This is the core problem - overlapping audio makes notifications unintelligible, defeating the purpose of the voice feedback system. Without sequential playback, the feature provides no value.
16
+
17
+ **Independent Test**: Can be fully tested by sending multiple simultaneous `/notify` requests and verifying that audio plays one after another without overlap. Delivers clear, sequential voice notifications.
18
+
19
+ **Acceptance Scenarios**:
20
+
21
+ 1. **Given** the voice server is running, **When** three simultaneous `/notify` POST requests arrive, **Then** all three notifications play sequentially in order of arrival
22
+ 2. **Given** a notification is currently playing, **When** a new `/notify` request arrives, **Then** the new request is queued and plays after the current notification completes
23
+ 3. **Given** the notification queue is empty, **When** a single `/notify` request arrives, **Then** the notification plays immediately with no perceptible delay
24
+
25
+ ---
26
+
27
+ ### User Story 2 - Immediate Response Acknowledgment (Priority: P1)
28
+
29
+ When a client sends a notification request, they receive immediate acknowledgment that the request was accepted, without waiting for audio playback to complete. This prevents timeout issues and allows clients to continue processing immediately.
30
+
31
+ **Why this priority**: Without immediate acknowledgment, clients may timeout or block waiting for audio to finish. The 201 Accepted pattern is essential for non-blocking client behavior.
32
+
33
+ **Independent Test**: Can be fully tested by sending a `/notify` request and measuring response time. Expect immediate 201 status response regardless of audio playback duration. Delivers non-blocking API behavior.
34
+
35
+ **Acceptance Scenarios**:
36
+
37
+ 1. **Given** a `/notify` request is sent, **When** the request is received, **Then** a 201 Accepted status is returned within 100ms (before audio processing begins)
38
+ 2. **Given** a `/notify` request with a long message, **When** the request is received, **Then** the client receives immediate 201 response and can continue processing while audio plays in background
39
+ 3. **Given** a client sends multiple rapid requests, **When** each request arrives, **Then** each receives 201 Accepted immediately and queue position is maintained
40
+
41
+ ---
42
+
43
+ ### User Story 3 - Queue Status Monitoring (Priority: P2)
44
+
45
+ System operators can check the current depth and status of the notification queue to understand system load and identify potential bottlenecks.
46
+
47
+ **Why this priority**: Operational visibility is important for monitoring and debugging, but the core functionality works without it. Lower priority than P1 stories that deliver the primary value.
48
+
49
+ **Independent Test**: Can be tested by querying the queue status endpoint and verifying accurate queue depth is returned. Delivers operational visibility into system state.
50
+
51
+ **Acceptance Scenarios**:
52
+
53
+ 1. **Given** the voice server is running, **When** a GET request to `/queue/status` is made, **Then** the response includes current queue depth, processing status, and health indicator
54
+ 2. **Given** three notifications are queued, **When** `/queue/status` is queried, **Then** queue depth is reported as 3 and health indicator shows "healthy"
55
+ 3. **Given** the queue is empty, **When** `/queue/status` is queried, **Then** queue depth is reported as 0
56
+ 4. **Given** the TTS system is unavailable, **When** `/queue/status` is queried, **Then** health indicator shows "unavailable" while still returning 200 OK
57
+
58
+ ---
59
+
60
+ ### Edge Cases
61
+
62
+ - When queue exceeds maximum capacity (100 items): Return 429 Too Many Requests
63
+ - Malformed notification request (invalid JSON, missing fields): Reject immediately with 400 Bad Request, never queued
64
+ - Invalid voice_id or settings: Reject immediately with 400 Bad Request before queuing
65
+ - Audio synthesis fails for a queued item: Skip to next item, continue processing
66
+ - Server shutdown with queued notifications: Drain queue — complete all pending items before exiting
67
+
68
+ ## Requirements *(mandatory)*
69
+
70
+ ### Functional Requirements
71
+
72
+ - **FR-001**: System MUST process voice notification requests in first-in-first-out (FIFO) order
73
+ - **FR-002**: System MUST return HTTP 201 Accepted status immediately upon receiving a valid notification request
74
+ - **FR-003**: System MUST play notification audio sequentially, with no overlap between notifications
75
+ - **FR-004**: System MUST maintain a queue of pending notification requests
76
+ - **FR-005**: System MUST limit maximum queue depth to 100 items
77
+ - **FR-006**: System MUST return 429 Too Many Requests when queue is at maximum capacity
78
+ - **FR-013**: System MUST validate request schema and voice_id immediately before queuing, returning 400 Bad Request for invalid input
79
+ - **FR-007**: System MUST skip to next queued item if audio synthesis fails for current item
80
+ - **FR-008**: System MUST log queue events (item queued, processing started, completed, failed)
81
+ - **FR-009**: System MUST provide `/queue/status` endpoint returning current queue depth and status
82
+ - **FR-010**: System MUST preserve original notification order based on arrival timestamp
83
+ - **FR-011**: System MUST drain all queued notifications before completing graceful shutdown
84
+ - **FR-012**: `/queue/status` endpoint MUST include health indicator field (healthy/degraded/unavailable)
85
+
86
+ ### Key Entities
87
+
88
+ - **QueuedNotification**: Represents a notification request awaiting processing. Contains message content, voice settings, arrival timestamp, and processing status. Maintains order relative to other queued items.
89
+
90
+ - **QueueState**: Represents the current state of the notification queue. Contains current depth, processing status (idle/active), health indicator (healthy/degraded/unavailable), and optional metrics (average wait time, items processed).
91
+
92
+ ## Success Criteria *(mandatory)*
93
+
94
+ ### Measurable Outcomes
95
+
96
+ - **SC-001**: Multiple simultaneous notification requests (up to 10) result in sequential audio playback with no overlap
97
+ - **SC-002**: All valid notification requests receive 201 Accepted response within 100ms of receipt
98
+ - **SC-003**: Queue status endpoint returns accurate queue depth and health indicator within 50ms
99
+ - **SC-004**: System gracefully handles queue overflow by rejecting requests with 429 status when queue contains 100 items
100
+ - **SC-005**: Invalid requests (malformed JSON, missing fields, invalid voice_id) are rejected with 400 Bad Request within 50ms
101
+
102
+ ## Assumptions
103
+
104
+ 1. **In-memory queue**: Queue data is stored in memory and does not persist across server restarts
105
+ 2. **Single worker**: Queue processing is handled by a single background worker to maintain strict FIFO ordering
106
+ 3. **Standard client behavior**: Clients are expected to handle 201 Accepted as success and not retry the request
107
+ 4. **Audio duration**: Average notification duration is 3-10 seconds, informing reasonable queue depth limits
108
+ 5. **PAI Algorithm usage**: Primary use case is PAI Algorithm phase transitions, which generate 2-7 rapid notifications per operation
109
+
110
+ ## Clarifications
111
+
112
+ ### Session 2026-02-09
113
+
114
+ - Q: When the voice server shuts down gracefully (SIGTERM/SIGINT), what should happen to notifications currently queued but not yet played? → A: Drain queue before shutdown — play all queued items, then exit
115
+ - Q: What should the `/queue/status` endpoint return when the queue service is unhealthy or the underlying TTS system is unavailable? → B: Return 200 OK with health indicator field (healthy/degraded/unavailable)
116
+ - Q: When a notification request contains invalid data (malformed JSON, missing required fields, invalid voice_id), should the system reject it immediately upon receipt (before queuing) or queue it and fail during processing? → A: Reject immediately — return 400 Bad Request before queuing
117
+
118
+ ## Out of Scope
119
+
120
+ - Persistent queue storage (surviving server restarts)
121
+ - Priority queuing (all items have equal priority)
122
+ - Queue item cancellation or removal
123
+ - Distributed/clustered queue support
124
+ - WebSocket or push notifications for queue events
125
+ - Admin APIs for queue manipulation (clear, pause, resume)
@@ -0,0 +1,136 @@
1
+ # Implementation Tasks: FIFO Notification Queue
2
+
3
+ **Feature**: FIFO Notification Queue
4
+ **Branch**: 002-fifo-notify-queue
5
+ **Date**: 2026-02-09
6
+ **Status**: In Progress
7
+
8
+ ## Task Legend
9
+
10
+ - `[ ]` - Pending task
11
+ - `[X]` - Completed task
12
+ - `[P]` - Parallel task (can run concurrently with other [P] tasks)
13
+ - `[→ N]` - Depends on task N completing first
14
+
15
+ ---
16
+
17
+ ## Phase 1: Setup
18
+
19
+ ### 1.1 Project Structure
20
+ - [ ] 1.1.1 Verify `.gitignore` contains TypeScript patterns (`node_modules/`, `dist/`, `*.log`)
21
+ - [ ] 1.1.2 Create `src/ts/models/queue.ts` file
22
+ - [ ] 1.1.3 Create `src/ts/services/notification-queue.ts` file
23
+ - [ ] 1.1.4 Create `tests/unit/services/` directory
24
+ - [ ] 1.1.5 Create `tests/integration/` directory
25
+
26
+ ---
27
+
28
+ ## Phase 2: Core Types
29
+
30
+ ### 2.1 Queue Models
31
+ - [ ] 2.1.1 Define `QueuedNotification` interface with id, message, voice_id, status, arrived_at
32
+ - [ ] 2.1.2 Define `QueueState` interface with depth, processing_status, health, metrics
33
+ - [ ] 2.1.3 Define `QueueConfig` interface with maxDepth, drainTimeoutMs, degradedThreshold
34
+ - [ ] 2.1.4 Export all types from `src/ts/models/queue.ts`
35
+
36
+ ---
37
+
38
+ ## Phase 3: Queue Service
39
+
40
+ ### 3.1 NotificationQueue Class
41
+ - [ ] 3.1.1 Implement `NotificationQueue` class constructor
42
+ - [ ] 3.1.2 Implement `enqueue()` method with maxDepth validation
43
+ - [ ] 3.1.3 Implement `processQueue()` private method with sequential processing
44
+ - [ ] 3.1.4 Implement `getQueueState()` method for status monitoring
45
+ - [ ] 3.1.5 Implement `drain()` method for graceful shutdown
46
+ - [ ] 3.1.6 Add queue event logging (item queued, processing, completed, failed)
47
+
48
+ ### 3.2 Queue Processing Logic
49
+ - [ ] 3.2.1 Implement TTS synthesis with error handling (skip on failure)
50
+ - [ ] 3.2.2 Implement processing flag to prevent concurrent processing
51
+ - [ ] 3.2.3 Implement health indicator logic (healthy/degraded/unavailable)
52
+
53
+ ---
54
+
55
+ ## Phase 4: Server Integration
56
+
57
+ ### 4.1 Notify Endpoint Updates
58
+ - [ ] 4.1.1 Create NotificationQueue instance in server state
59
+ - [ ] 4.1.2 Update `handleNotify()` to use queue instead of direct TTS call
60
+ - [ ] 4.1.3 Return 201 Accepted immediately on successful enqueue
61
+ - [ ] 4.1.4 Return 400 Bad Request for invalid input (before queue)
62
+ - [ ] 4.1.5 Return 429 Too Many Requests when queue is full
63
+
64
+ ### 4.2 Queue Status Endpoint
65
+ - [ ] 4.2.1 Add `handleQueueStatus()` function
66
+ - [ ] 4.2.2 Add GET `/queue/status` route to Bun.serve handler
67
+ - [ ] 4.2.3 Return QueueStateResponse with depth, status, health, metrics
68
+
69
+ ### 4.3 Graceful Shutdown
70
+ - [ ] 4.3.1 Update shutdown handler to call `queue.drain()`
71
+ - [ ] 4.3.2 Implement drain timeout (30 seconds)
72
+ - [ ] 4.3.3 Log remaining items on timeout
73
+
74
+ ---
75
+
76
+ ## Phase 5: Tests
77
+
78
+ ### 5.1 Unit Tests [P]
79
+ - [ ] 5.1.1 Test `enqueue()` adds items to queue
80
+ - [ ] 5.1.2 Test `enqueue()` rejects when maxDepth exceeded
81
+ - [ ] 5.1.3 Test FIFO ordering with multiple items
82
+ - [ ] 5.1.4 Test `processQueue()` processes items sequentially
83
+ - [ ] 5.1.5 Test `processQueue()` skips failed items
84
+ - [ ] 5.1.6 Test `getQueueState()` returns correct state
85
+ - [ ] 5.1.7 Test `drain()` completes within timeout
86
+ - [ ] 5.1.8 Test queue event logging
87
+
88
+ ### 5.2 Integration Tests [P]
89
+ - [ ] 5.2.1 Test POST /notify returns 201 Accepted
90
+ - [ ] 5.2.2 Test multiple requests process sequentially
91
+ - [ ] 5.2.3 Test queue overflow returns 429
92
+ - [ ] 5.2.4 Test invalid requests return 400
93
+ - [ ] 5.2.5 Test GET /queue/status returns correct state
94
+ - [ ] 5.2.6 Test health indicator reflects TTS availability
95
+
96
+ ---
97
+
98
+ ## Phase 6: Validation
99
+
100
+ ### 6.1 Code Quality
101
+ - [ ] 6.1.1 Run `bun run typecheck` - zero errors
102
+ - [ ] 6.1.2 Run `bun run lint` - zero warnings
103
+ - [ ] 6.1.3 Run `bun test` - all tests pass
104
+ - [ ] 6.1.4 Verify Codanna index is updated
105
+
106
+ ### 6.2 Documentation
107
+ - [ ] 6.2.1 Verify JSDoc comments on all public methods
108
+ - [ ] 6.2.2 Verify quickstart.md examples are accurate
109
+ - [ ] 6.2.3 Verify API contracts match implementation
110
+
111
+ ---
112
+
113
+ ## Execution Notes
114
+
115
+ - **TDD Approach**: Write tests before implementation (Phase 5 before Phase 3-4)
116
+ - **File Coordination**: Tasks in Phase 3 affect `notification-queue.ts`, must run sequentially
117
+ - **Parallel Tasks**: Phase 5.1 and 5.2 marked [P] can run concurrently after test setup
118
+ - **Dependencies**: Each phase must complete before the next phase begins
119
+
120
+ ---
121
+
122
+ ## Progress Tracking
123
+
124
+ | Phase | Tasks | Completed | Status |
125
+ |-------|-------|------------|--------|
126
+ | 1. Setup | 5 | 0 | Pending |
127
+ | 2. Core Types | 4 | 0 | Pending |
128
+ | 3. Queue Service | 9 | 0 | Pending |
129
+ | 4. Server Integration | 8 | 0 | Pending |
130
+ | 5. Tests | 14 | 0 | Pending |
131
+ | 6. Validation | 7 | 0 | Pending |
132
+ | **Total** | **47** | **0** | **0%** |
133
+
134
+ ---
135
+
136
+ **Next Steps**: Begin with Phase 1 (Setup) to establish project structure.