@madeinoz67/voice-server 0.1.9 → 0.1.11
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.
- package/CHANGELOG.md +9 -72
- package/CLAUDE.md +5 -0
- package/bun.lock +13 -13
- package/cliff.toml +10 -3
- package/docs/api.md +4 -0
- package/docs/assets/queue-error-handling-flow.png +0 -0
- package/docs/assets/queue-request-flow-success.png +0 -0
- package/docs/assets/queue-states.png +0 -0
- package/docs/assets/queue-system-overview.png +0 -0
- package/docs/assets/voice-server-architecture.png +0 -0
- package/docs/fifo-queue.md +175 -0
- package/docs/queue-architecture.md +182 -0
- package/homebrew.mxcl.voice-server.plist +33 -0
- package/mkdocs.yml +3 -0
- package/package.json +1 -1
- package/specs/002-fifo-notify-queue/checklists/requirements.md +50 -0
- package/specs/002-fifo-notify-queue/contracts/api.yaml +283 -0
- package/specs/002-fifo-notify-queue/data-model.md +379 -0
- package/specs/002-fifo-notify-queue/plan.md +320 -0
- package/specs/002-fifo-notify-queue/quickstart.md +273 -0
- package/specs/002-fifo-notify-queue/research.md +374 -0
- package/specs/002-fifo-notify-queue/spec.md +125 -0
- package/specs/002-fifo-notify-queue/tasks.md +136 -0
- package/src/ts/models/queue.ts +140 -0
- package/src/ts/server.ts +98 -19
- package/src/ts/services/mlx-tts-client.ts +75 -20
- package/src/ts/services/notification-queue.ts +382 -0
- package/tests/integration/queue-api.test.ts +298 -0
- package/tests/unit/services/notification-queue.test.ts +622 -0
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
# Data Model: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Feature**: FIFO Notification Queue
|
|
4
|
+
**Date**: 2026-02-09
|
|
5
|
+
**Status**: Draft
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
This document defines the data structures and entities for the FIFO notification queue system.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Core Entities
|
|
14
|
+
|
|
15
|
+
### QueuedNotification
|
|
16
|
+
|
|
17
|
+
Represents a single notification request awaiting or undergoing processing.
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
interface QueuedNotification {
|
|
21
|
+
/** Unique identifier for this queued item */
|
|
22
|
+
id: string;
|
|
23
|
+
|
|
24
|
+
/** Notification title (optional) */
|
|
25
|
+
title?: string;
|
|
26
|
+
|
|
27
|
+
/** Text message to synthesize (required) */
|
|
28
|
+
message: string;
|
|
29
|
+
|
|
30
|
+
/** Voice identifier to use */
|
|
31
|
+
voice_id: string;
|
|
32
|
+
|
|
33
|
+
/** Voice prosody settings (optional) */
|
|
34
|
+
voice_settings?: ProsodySettings;
|
|
35
|
+
|
|
36
|
+
/** Playback volume (0.0-1.0) */
|
|
37
|
+
volume: number;
|
|
38
|
+
|
|
39
|
+
/** Timestamp when request was received (ms since epoch) */
|
|
40
|
+
arrived_at: number;
|
|
41
|
+
|
|
42
|
+
/** Current processing status */
|
|
43
|
+
status: QueuedNotificationStatus;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
type QueuedNotificationStatus =
|
|
47
|
+
| "pending" // Awaiting processing
|
|
48
|
+
| "processing" // Currently being synthesized
|
|
49
|
+
| "completed" // Successfully played
|
|
50
|
+
| "failed"; // Failed during synthesis/playback
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Relationships**: None (standalone entity)
|
|
54
|
+
|
|
55
|
+
**Lifecycle**: `pending` → `processing` → `completed` OR `failed`
|
|
56
|
+
|
|
57
|
+
**Validation Rules**:
|
|
58
|
+
- `id`: Non-empty string, UUID format
|
|
59
|
+
- `message`: 1-500 characters after sanitization
|
|
60
|
+
- `voice_id`: Must match available voice or use default
|
|
61
|
+
- `volume`: 0.0-1.0 inclusive
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
### QueueState
|
|
66
|
+
|
|
67
|
+
Represents the current state of the notification queue for monitoring.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
interface QueueState {
|
|
71
|
+
/** Current number of items in queue */
|
|
72
|
+
depth: number;
|
|
73
|
+
|
|
74
|
+
/** Whether queue is actively processing */
|
|
75
|
+
processing_status: ProcessingStatus;
|
|
76
|
+
|
|
77
|
+
/** Overall system health indicator */
|
|
78
|
+
health: HealthIndicator;
|
|
79
|
+
|
|
80
|
+
/** Optional metrics for monitoring */
|
|
81
|
+
metrics?: QueueMetrics;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
type ProcessingStatus = "idle" | "active";
|
|
85
|
+
|
|
86
|
+
type HealthIndicator = "healthy" | "degraded" | "unavailable";
|
|
87
|
+
|
|
88
|
+
interface QueueMetrics {
|
|
89
|
+
/** Average wait time for queued items (milliseconds) */
|
|
90
|
+
average_wait_time_ms: number;
|
|
91
|
+
|
|
92
|
+
/** Total items processed since server start */
|
|
93
|
+
items_processed: number;
|
|
94
|
+
|
|
95
|
+
/** Total items that failed since server start */
|
|
96
|
+
items_failed: number;
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Relationships**: References `QueuedNotification` (aggregate)
|
|
101
|
+
|
|
102
|
+
**State Transitions**:
|
|
103
|
+
- `processing_status`: `idle` ↔ `active` based on whether worker is running
|
|
104
|
+
- `health`: Determined by TTS availability and queue depth
|
|
105
|
+
|
|
106
|
+
**Health Determination Logic**:
|
|
107
|
+
```
|
|
108
|
+
if (TTS unavailable) → unavailable
|
|
109
|
+
else if (queue depth >= 80) → degraded
|
|
110
|
+
else → healthy
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
### QueueConfig
|
|
116
|
+
|
|
117
|
+
Configuration for queue behavior.
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
interface QueueConfig {
|
|
121
|
+
/** Maximum number of items allowed in queue */
|
|
122
|
+
maxDepth: number;
|
|
123
|
+
|
|
124
|
+
/** Timeout for queue drain during shutdown (milliseconds) */
|
|
125
|
+
drainTimeoutMs: number;
|
|
126
|
+
|
|
127
|
+
/** Threshold for degraded health status (percentage of maxDepth) */
|
|
128
|
+
degradedThreshold: number;
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**Default Values**:
|
|
133
|
+
- `maxDepth`: 100
|
|
134
|
+
- `drainTimeoutMs`: 30000 (30 seconds)
|
|
135
|
+
- `degradedThreshold`: 0.8 (80%)
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Data Flow
|
|
140
|
+
|
|
141
|
+
### Request → Queue → Processing Flow
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
┌─────────────┐
|
|
145
|
+
│ HTTP Request│
|
|
146
|
+
└──────┬──────┘
|
|
147
|
+
│
|
|
148
|
+
▼
|
|
149
|
+
┌─────────────────┐
|
|
150
|
+
│ Input Validation│ (schema, voice_id, sanitization)
|
|
151
|
+
└──────┬──────────┘
|
|
152
|
+
│
|
|
153
|
+
▼ (if valid)
|
|
154
|
+
┌─────────────┐
|
|
155
|
+
│ Enqueue │ (add to queue array)
|
|
156
|
+
└──────┬──────┘
|
|
157
|
+
│
|
|
158
|
+
▼
|
|
159
|
+
┌─────────────────┐
|
|
160
|
+
│ Return 201 │ (immediate, async processing)
|
|
161
|
+
└─────────────────┘
|
|
162
|
+
│
|
|
163
|
+
▼ (background)
|
|
164
|
+
┌─────────────────┐
|
|
165
|
+
│ Queue Worker │ (process items sequentially)
|
|
166
|
+
└──────┬──────────┘
|
|
167
|
+
│
|
|
168
|
+
▼
|
|
169
|
+
┌─────────────────┐
|
|
170
|
+
│ TTS Synthesis │ (processTTS function)
|
|
171
|
+
└──────┬──────────┘
|
|
172
|
+
│
|
|
173
|
+
▼
|
|
174
|
+
┌─────────────────┐
|
|
175
|
+
│ Audio Playback │
|
|
176
|
+
└─────────────────┘
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## State Management
|
|
182
|
+
|
|
183
|
+
### Queue Processing State
|
|
184
|
+
|
|
185
|
+
The queue maintains a processing flag to prevent concurrent processing:
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
class NotificationQueue {
|
|
189
|
+
private queue: QueuedNotification[] = [];
|
|
190
|
+
private processing = false; // Single worker flag
|
|
191
|
+
|
|
192
|
+
private async processQueue(): Promise<void> {
|
|
193
|
+
if (this.processing || this.queue.length === 0) return;
|
|
194
|
+
this.processing = true;
|
|
195
|
+
|
|
196
|
+
try {
|
|
197
|
+
while (this.queue.length > 0) {
|
|
198
|
+
const item = this.queue.shift();
|
|
199
|
+
// Process item...
|
|
200
|
+
}
|
|
201
|
+
} finally {
|
|
202
|
+
this.processing = false;
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Graceful Shutdown State
|
|
209
|
+
|
|
210
|
+
During shutdown, the queue enters a draining state:
|
|
211
|
+
|
|
212
|
+
```typescript
|
|
213
|
+
interface QueueState {
|
|
214
|
+
draining: boolean; // true during shutdown
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Shutdown sequence:
|
|
219
|
+
1. Set `draining = true`
|
|
220
|
+
2. Stop accepting new requests
|
|
221
|
+
3. Wait for queue to empty (with timeout)
|
|
222
|
+
4. Exit process
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Error State Transitions
|
|
227
|
+
|
|
228
|
+
### Item Failure
|
|
229
|
+
|
|
230
|
+
When TTS synthesis fails for a queued item:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
pending → processing → failed
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Behavior:
|
|
237
|
+
- Log error with item ID
|
|
238
|
+
- Skip to next item
|
|
239
|
+
- Increment `items_failed` metric
|
|
240
|
+
- Continue processing remaining items
|
|
241
|
+
|
|
242
|
+
### Queue Overflow
|
|
243
|
+
|
|
244
|
+
When enqueue would exceed `maxDepth`:
|
|
245
|
+
|
|
246
|
+
```
|
|
247
|
+
HTTP Request → 429 Too Many Requests
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Behavior:
|
|
251
|
+
- Return 429 immediately
|
|
252
|
+
- Do not add item to queue
|
|
253
|
+
- Client may retry later
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Persistence Strategy
|
|
258
|
+
|
|
259
|
+
### In-Memory Only (Per Spec)
|
|
260
|
+
|
|
261
|
+
- Queue data stored in JavaScript array
|
|
262
|
+
- No persistence to disk or database
|
|
263
|
+
- Server restart = queue cleared
|
|
264
|
+
- Queue depth limit (100) prevents memory issues
|
|
265
|
+
|
|
266
|
+
### Rationale
|
|
267
|
+
|
|
268
|
+
- Voice notifications are transient (3-10s playback)
|
|
269
|
+
- Local voice server (not distributed)
|
|
270
|
+
- Persistence would add complexity without significant benefit
|
|
271
|
+
- Server restarts are infrequent
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Type Dependencies
|
|
276
|
+
|
|
277
|
+
### Existing Types Used
|
|
278
|
+
|
|
279
|
+
From `src/ts/models/notification.ts`:
|
|
280
|
+
- `NotificationRequest`
|
|
281
|
+
- `PaiNotificationRequest`
|
|
282
|
+
- `SuccessResponse`
|
|
283
|
+
- `ErrorResponse`
|
|
284
|
+
|
|
285
|
+
From `src/ts/models/voice-config.ts`:
|
|
286
|
+
- `ProsodySettings`
|
|
287
|
+
|
|
288
|
+
From `src/ts/models/health.ts`:
|
|
289
|
+
- `HealthStatus` (extended with queue fields)
|
|
290
|
+
|
|
291
|
+
### New Types Defined
|
|
292
|
+
|
|
293
|
+
- `QueuedNotification`
|
|
294
|
+
- `QueuedNotificationStatus`
|
|
295
|
+
- `QueueState`
|
|
296
|
+
- `ProcessingStatus`
|
|
297
|
+
- `HealthIndicator`
|
|
298
|
+
- `QueueMetrics`
|
|
299
|
+
- `QueueConfig`
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## Indexes and Ordering
|
|
304
|
+
|
|
305
|
+
### FIFO Ordering
|
|
306
|
+
|
|
307
|
+
Queue maintains strict FIFO ordering:
|
|
308
|
+
- Items added with `push()` to end of array
|
|
309
|
+
- Items removed with `shift()` from beginning of array
|
|
310
|
+
- `arrived_at` timestamp preserves order for debugging
|
|
311
|
+
|
|
312
|
+
### No Indexes Required
|
|
313
|
+
|
|
314
|
+
- In-memory array access is O(1) for push
|
|
315
|
+
- O(n) shift is acceptable for n ≤ 100
|
|
316
|
+
- No lookup by ID required
|
|
317
|
+
- No sorting or reordering needed
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## Memory Considerations
|
|
322
|
+
|
|
323
|
+
### Per-Item Memory
|
|
324
|
+
|
|
325
|
+
Approximate memory per `QueuedNotification`:
|
|
326
|
+
- `id`: 36 bytes (UUID string)
|
|
327
|
+
- `message`: ~100 bytes average
|
|
328
|
+
- `voice_id`: 20 bytes
|
|
329
|
+
- `voice_settings`: ~50 bytes
|
|
330
|
+
- Metadata: ~50 bytes
|
|
331
|
+
- **Total**: ~250 bytes per item
|
|
332
|
+
|
|
333
|
+
### Total Memory
|
|
334
|
+
|
|
335
|
+
- 100 items × 250 bytes = ~25 KB
|
|
336
|
+
- Negligible impact on server memory
|
|
337
|
+
- Well under 2GB memory limit (Constitution)
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## Concurrency Model
|
|
342
|
+
|
|
343
|
+
### Single-Threaded Event Loop
|
|
344
|
+
|
|
345
|
+
Bun/JavaScript is single-threaded:
|
|
346
|
+
- No mutex needed for queue operations
|
|
347
|
+
- Array operations are atomic
|
|
348
|
+
- `processing` flag prevents race conditions
|
|
349
|
+
|
|
350
|
+
### Multiple Producers
|
|
351
|
+
|
|
352
|
+
Multiple HTTP requests can call `enqueue()` concurrently:
|
|
353
|
+
- Each request is handled by event loop
|
|
354
|
+
- `enqueue()` returns immediately after array push
|
|
355
|
+
- `processQueue()` is idempotent (checks `processing` flag)
|
|
356
|
+
|
|
357
|
+
### Single Consumer
|
|
358
|
+
|
|
359
|
+
Background worker processes items sequentially:
|
|
360
|
+
- Only one `processQueue()` runs at a time
|
|
361
|
+
- Ensures strict FIFO ordering
|
|
362
|
+
- Prevents audio overlap
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## Validation Rules Summary
|
|
367
|
+
|
|
368
|
+
| Field | Validation | Error Response |
|
|
369
|
+
|-------|-----------|----------------|
|
|
370
|
+
| `message` | 1-500 chars, not empty after sanitization | 400 Bad Request |
|
|
371
|
+
| `voice_id` | Valid voice from available list | 400 Bad Request |
|
|
372
|
+
| `volume` | 0.0-1.0 inclusive | 400 Bad Request |
|
|
373
|
+
| Queue depth | < maxDepth (100) | 429 Too Many Requests |
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
## Next Steps
|
|
378
|
+
|
|
379
|
+
Proceed to API contract generation in `/contracts/` directory.
|
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
# Implementation Plan: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Branch**: `002-fifo-notify-queue` | **Date**: 2026-02-09 | **Spec**: [spec.md](./spec.md)
|
|
4
|
+
**Input**: Feature specification from `/specs/002-fifo-notify-queue/spec.md`
|
|
5
|
+
|
|
6
|
+
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
7
|
+
|
|
8
|
+
## Summary
|
|
9
|
+
|
|
10
|
+
Implement a FIFO (first-in-first-out) queue for the voice server's `/notify` endpoint to prevent audio overlap when multiple agents send notifications simultaneously. The queue accepts requests immediately with a 201 Accepted response, then processes notifications sequentially in the background. Includes a `/queue/status` monitoring endpoint and graceful shutdown with queue draining.
|
|
11
|
+
|
|
12
|
+
**Key Requirements**:
|
|
13
|
+
- FIFO ordering for all notifications
|
|
14
|
+
- 201 Accepted response within 100ms
|
|
15
|
+
- Max 100 item queue depth with 429 on overflow
|
|
16
|
+
- Invalid requests rejected immediately (400 Bad Request)
|
|
17
|
+
- Graceful shutdown drains queue before exit
|
|
18
|
+
|
|
19
|
+
## Technical Context
|
|
20
|
+
|
|
21
|
+
**Language/Version**: TypeScript 5.x (Bun runtime)
|
|
22
|
+
**Primary Dependencies**: Bun native APIs, MLX-audio CLI (existing)
|
|
23
|
+
**Storage**: In-memory array (no persistence per spec)
|
|
24
|
+
**Testing**: Bun test runner (built-in)
|
|
25
|
+
**Target Platform**: macOS only (Constitution Principle IV)
|
|
26
|
+
**Project Type**: Single (monorepo with server code in `src/ts/`)
|
|
27
|
+
**Performance Goals**:
|
|
28
|
+
- 201 Accepted response < 100ms
|
|
29
|
+
- Queue status response < 50ms
|
|
30
|
+
- Max 100 queued items
|
|
31
|
+
- Sequential audio playback (no overlap)
|
|
32
|
+
**Constraints**:
|
|
33
|
+
- In-memory queue only (no persistence)
|
|
34
|
+
- Single worker for FIFO ordering
|
|
35
|
+
- Queue depth ≤ 100 items
|
|
36
|
+
- Shutdown drain timeout ≤ 30 seconds
|
|
37
|
+
**Scale/Scope**:
|
|
38
|
+
- Local voice server (single instance)
|
|
39
|
+
- 2-7 rapid notifications per PAI Algorithm operation
|
|
40
|
+
- Average 3-10 second TTS processing time per notification
|
|
41
|
+
|
|
42
|
+
## Constitution Check
|
|
43
|
+
|
|
44
|
+
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
45
|
+
|
|
46
|
+
### Principle I: Drop-in Compatibility
|
|
47
|
+
✅ **PASS** - `/notify` endpoint maintains exact contract. 201 Accepted is compatible with existing PAI system expectations. No breaking changes to request/response formats.
|
|
48
|
+
|
|
49
|
+
### Principle II: Local-First Architecture
|
|
50
|
+
✅ **PASS** - Queue is in-memory, no external API dependencies. MLX-audio remains primary TTS backend.
|
|
51
|
+
|
|
52
|
+
### Principle III: Graceful Degradation
|
|
53
|
+
✅ **PASS** - Queue skip-on-failure pattern continues processing even when individual items fail. Existing fallback to macOS `say` preserved.
|
|
54
|
+
|
|
55
|
+
### Principle IV: Platform Honesty
|
|
56
|
+
✅ **PASS** - No cross-platform abstractions. Uses macOS-native commands (`afplay`, `osascript`) directly.
|
|
57
|
+
|
|
58
|
+
### Principle V: Test-First Validation
|
|
59
|
+
✅ **PASS** - Unit and integration tests planned for all queue operations, API endpoints, and error conditions. TDD approach followed.
|
|
60
|
+
|
|
61
|
+
### Principle VI: Codanna Workflow
|
|
62
|
+
✅ **PASS** - All new TypeScript files in `src/ts/services/` and `src/ts/models/` will be indexed. Codanna used for symbol lookup and impact analysis.
|
|
63
|
+
|
|
64
|
+
### Principle VII: Documentation Standards
|
|
65
|
+
✅ **PASS** - This plan follows Markdown formatting requirements. API documentation in OpenAPI format. Code will have JSDoc comments.
|
|
66
|
+
|
|
67
|
+
**Overall Gate Status**: ✅ **PASS** - All constitutional principles satisfied.
|
|
68
|
+
|
|
69
|
+
## Project Structure
|
|
70
|
+
|
|
71
|
+
### Documentation (this feature)
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
specs/002-fifo-notify-queue/
|
|
75
|
+
├── plan.md # This file (/speckit.plan command output)
|
|
76
|
+
├── research.md # Phase 0 output (/speckit.plan command)
|
|
77
|
+
├── data-model.md # Phase 1 output (/speckit.plan command)
|
|
78
|
+
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
|
79
|
+
├── contracts/ # Phase 1 output (/speckit.plan command)
|
|
80
|
+
│ └── api.yaml # OpenAPI specification
|
|
81
|
+
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Source Code (repository root)
|
|
85
|
+
|
|
86
|
+
```text
|
|
87
|
+
src/ts/
|
|
88
|
+
├── services/
|
|
89
|
+
│ ├── notification-queue.ts # NEW: Queue implementation
|
|
90
|
+
│ ├── mlx-tts-client.ts # EXISTING: No changes needed
|
|
91
|
+
│ ├── pronunciation.ts # EXISTING: No changes needed
|
|
92
|
+
│ ├── prosody-translator.ts # EXISTING: No changes needed
|
|
93
|
+
│ └── voice-loader.ts # EXISTING: No changes needed
|
|
94
|
+
├── models/
|
|
95
|
+
│ ├── queue.ts # NEW: Queue types
|
|
96
|
+
│ ├── notification.ts # EXISTING: No changes needed
|
|
97
|
+
│ ├── health.ts # EXISTING: Extended with queue fields
|
|
98
|
+
│ ├── tts.ts # EXISTING: No changes needed
|
|
99
|
+
│ └── voice-config.ts # EXISTING: No changes needed
|
|
100
|
+
├── middleware/
|
|
101
|
+
│ ├── cors.ts # EXISTING: No changes needed
|
|
102
|
+
│ └── rate-limiter.ts # EXISTING: No changes needed
|
|
103
|
+
├── utils/
|
|
104
|
+
│ ├── logger.ts # EXISTING: No changes needed
|
|
105
|
+
│ └── text-sanitizer.ts # EXISTING: No changes needed
|
|
106
|
+
└── server.ts # MODIFY: Add queue integration, /queue/status endpoint
|
|
107
|
+
|
|
108
|
+
tests/
|
|
109
|
+
├── unit/
|
|
110
|
+
│ └── services/
|
|
111
|
+
│ └── notification-queue.test.ts # NEW: Queue unit tests
|
|
112
|
+
└── integration/
|
|
113
|
+
└── queue-api.test.ts # NEW: Queue API integration tests
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Structure Decision**: Single project structure (Option 1). This is a backend service with HTTP API, no frontend component. All code resides in `src/ts/` following existing patterns.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Phase 0: Research ✓ Complete
|
|
121
|
+
|
|
122
|
+
**Status**: Complete
|
|
123
|
+
|
|
124
|
+
**Research Output**: [research.md](./research.md)
|
|
125
|
+
|
|
126
|
+
**Key Decisions**:
|
|
127
|
+
1. **Queue Implementation**: Array-based in-memory queue with async/await processing
|
|
128
|
+
2. **Concurrency**: Single async worker with Promise-based processing
|
|
129
|
+
3. **Graceful Shutdown**: Await queue drain with 30-second timeout
|
|
130
|
+
4. **Error Handling**: Skip failed items, continue processing
|
|
131
|
+
5. **Health Monitoring**: Extend existing HealthStatus model with queue fields
|
|
132
|
+
6. **Rate Limiting**: Apply before queue admission, separate 429 for queue full
|
|
133
|
+
|
|
134
|
+
**Open Questions Resolved**:
|
|
135
|
+
- ✅ Shutdown behavior: Drain queue before exit (30s timeout)
|
|
136
|
+
- ✅ Queue status returns: 200 OK with health indicator
|
|
137
|
+
- ✅ Invalid requests: Reject immediately (400) before queuing
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Phase 1: Design & Contracts ✓ Complete
|
|
142
|
+
|
|
143
|
+
**Status**: Complete
|
|
144
|
+
|
|
145
|
+
### Data Model
|
|
146
|
+
|
|
147
|
+
**Output**: [data-model.md](./data-model.md)
|
|
148
|
+
|
|
149
|
+
**Entities Defined**:
|
|
150
|
+
- `QueuedNotification` - Queued item with message, voice settings, status
|
|
151
|
+
- `QueueState` - Current queue depth, processing status, health indicator
|
|
152
|
+
- `QueueConfig` - Configuration for max depth, drain timeout, degraded threshold
|
|
153
|
+
|
|
154
|
+
**Type Dependencies**:
|
|
155
|
+
- Uses existing `NotificationRequest`, `ProsodySettings` from `models/notification.ts` and `models/voice-config.ts`
|
|
156
|
+
- Extends `HealthStatus` from `models/health.ts` with queue fields
|
|
157
|
+
|
|
158
|
+
### API Contracts
|
|
159
|
+
|
|
160
|
+
**Output**: [contracts/api.yaml](./contracts/api.yaml)
|
|
161
|
+
|
|
162
|
+
**Endpoints Specified**:
|
|
163
|
+
1. `POST /notify` - Queue notification (201/400/429/500)
|
|
164
|
+
2. `GET /queue/status` - Get queue state (200 always)
|
|
165
|
+
|
|
166
|
+
**Request/Response Schemas**:
|
|
167
|
+
- `NotificationRequest` - Queue request body
|
|
168
|
+
- `SuccessResponse` - Success response
|
|
169
|
+
- `ErrorResponse` - Error response
|
|
170
|
+
- `QueueStateResponse` - Queue status response
|
|
171
|
+
|
|
172
|
+
### Quickstart Guide
|
|
173
|
+
|
|
174
|
+
**Output**: [quickstart.md](./quickstart.md)
|
|
175
|
+
|
|
176
|
+
**Covers**:
|
|
177
|
+
- Development setup
|
|
178
|
+
- API usage examples
|
|
179
|
+
- Testing queue behavior
|
|
180
|
+
- Troubleshooting
|
|
181
|
+
- Configuration options
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Phase 2: Tasks (NOT CREATED YET)
|
|
186
|
+
|
|
187
|
+
**Status**: Pending `/speckit.tasks` command
|
|
188
|
+
|
|
189
|
+
**Note**: Run `/speckit.tasks` to generate `tasks.md` with dependency-ordered implementation tasks.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Testing Strategy (Per Constitution Principle V)
|
|
194
|
+
|
|
195
|
+
### Unit Tests
|
|
196
|
+
|
|
197
|
+
**File**: `tests/unit/services/notification-queue.test.ts`
|
|
198
|
+
|
|
199
|
+
Coverage:
|
|
200
|
+
- Queue enqueue/dequeue operations
|
|
201
|
+
- FIFO ordering verification
|
|
202
|
+
- Max depth enforcement
|
|
203
|
+
- Processing state management
|
|
204
|
+
- Error handling (skip failed items)
|
|
205
|
+
- Graceful shutdown with drain
|
|
206
|
+
|
|
207
|
+
### Integration Tests
|
|
208
|
+
|
|
209
|
+
**File**: `tests/integration/queue-api.test.ts`
|
|
210
|
+
|
|
211
|
+
Coverage:
|
|
212
|
+
- `POST /notify` returns 201 Accepted
|
|
213
|
+
- Multiple requests process sequentially (no audio overlap)
|
|
214
|
+
- Queue overflow returns 429
|
|
215
|
+
- Invalid requests return 400
|
|
216
|
+
- `GET /queue/status` returns correct state
|
|
217
|
+
- Health indicator reflects TTS availability
|
|
218
|
+
|
|
219
|
+
### Test Doubles
|
|
220
|
+
|
|
221
|
+
- Mock `processTTS()` function for unit tests
|
|
222
|
+
- Mock MLX TTS client for integration tests
|
|
223
|
+
- Fake timers for timing-sensitive tests
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Constitution Re-Check (Post-Design)
|
|
228
|
+
|
|
229
|
+
*Re-evaluated after Phase 1 design*
|
|
230
|
+
|
|
231
|
+
✅ **All Principles Pass** - No violations, no complexity tracking required.
|
|
232
|
+
|
|
233
|
+
Design decisions uphold all constitutional principles:
|
|
234
|
+
- Drop-in compatibility maintained (201 Accepted is standard HTTP pattern)
|
|
235
|
+
- Local-first architecture (in-memory queue)
|
|
236
|
+
- Graceful degradation (skip-on-failure)
|
|
237
|
+
- Platform honesty (macOS-only)
|
|
238
|
+
- Test-first validation (comprehensive tests planned)
|
|
239
|
+
- Codanna workflow (new files will be indexed)
|
|
240
|
+
- Documentation standards (OpenAPI, JSDoc, Markdown)
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## Implementation Notes
|
|
245
|
+
|
|
246
|
+
### Queue Processing Flow
|
|
247
|
+
|
|
248
|
+
```
|
|
249
|
+
HTTP Request → Validate → Enqueue → Return 201
|
|
250
|
+
↓
|
|
251
|
+
Background Worker
|
|
252
|
+
↓
|
|
253
|
+
Process TTS → Play Audio
|
|
254
|
+
↓
|
|
255
|
+
Next Item (if any)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Graceful Shutdown Flow
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
SIGTERM/SIGINT → Set draining flag → Stop accepting requests
|
|
262
|
+
↓
|
|
263
|
+
Wait for queue empty (30s timeout)
|
|
264
|
+
↓
|
|
265
|
+
Exit process
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Error Handling Flow
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
TTS Failure → Log error → Skip to next item → Continue processing
|
|
272
|
+
Queue Full → Return 429 → Client may retry
|
|
273
|
+
Invalid Request → Return 400 → Never queued
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Dependencies
|
|
279
|
+
|
|
280
|
+
### Internal Dependencies
|
|
281
|
+
|
|
282
|
+
- `src/ts/models/notification.ts` - Request/response types
|
|
283
|
+
- `src/ts/models/voice-config.ts` - ProsodySettings type
|
|
284
|
+
- `src/ts/models/health.ts` - HealthStatus extension
|
|
285
|
+
- `src/ts/services/mlx-tts-client.ts` - TTS synthesis
|
|
286
|
+
- `src/ts/utils/logger.ts` - Logging
|
|
287
|
+
- `src/ts/utils/text-sanitizer.ts` - Input validation
|
|
288
|
+
- `src/ts/services/voice-loader.ts` - Voice ID validation
|
|
289
|
+
|
|
290
|
+
### External Dependencies
|
|
291
|
+
|
|
292
|
+
- Bun runtime (native Promise, Array, crypto APIs)
|
|
293
|
+
- MLX-audio CLI (existing TTS backend)
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Success Criteria Verification
|
|
298
|
+
|
|
299
|
+
**From Spec**:
|
|
300
|
+
|
|
301
|
+
| Criterion | Verification |
|
|
302
|
+
|-----------|--------------|
|
|
303
|
+
| SC-001: Sequential playback | Integration test sends 10 concurrent requests, verifies no audio overlap |
|
|
304
|
+
| SC-002: 201 in < 100ms | Unit test measures response time for enqueue operation |
|
|
305
|
+
| SC-003: Status < 50ms | Unit test measures `/queue/status` response time |
|
|
306
|
+
| SC-004: 429 on overflow | Integration test fills queue to 100, verifies 429 on 101st request |
|
|
307
|
+
| SC-005: 400 on invalid | Unit tests for each validation failure scenario |
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
## Next Steps
|
|
312
|
+
|
|
313
|
+
1. **Run `/speckit.tasks`** - Generate implementation task list
|
|
314
|
+
2. **Update agent context** - Run `.specify/scripts/bash/update-agent-context.sh claude`
|
|
315
|
+
3. **Begin implementation** - Follow tasks in dependency order
|
|
316
|
+
4. **Update Codanna index** - After adding new TypeScript files
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
**Plan Status**: ✅ Phase 0 & 1 Complete | Phase 2 Pending `/speckit.tasks`
|