suaveplan/openspec/archive/2026-05-23-enterprise-streams-chunk-queue/tasks.md

Tasks: enterprise-streams-chunk-queue

• Change ID: enterprise-streams-chunk-queue
• Package: @suaveplan/streams-chunk-queue
• Date: 2026-05-23

0. Pre-flight (non-negotiable)

• 0.1 git status clean in worktree; branch renamed to feat/streams-chunk-queue.
• 0.2 Worktree under .claude/worktrees/agent-a42db4238ae08d309 accounted for (this change).
• 0.3 STATUS.md lists @suaveplan/streams-chunk-queue as – (pending) → confirms genesis-side absence.
• 0.4 Upstream source read end-to-end: src/core/streaming-chunk-queue.ts, src/types/types.ts, README.md.
• 0.5 Genesis dependency APIs audited: AbstractStorage, TokenBucket.consume(), ChunkVerifier.verify() shapes confirmed before authoring adapters.

1. Errors

• 1.1 errors/streams-chunk-queue-error.ts — STREAMS_CHUNK_QUEUE_CODES via defineCodes, StreamsChunkQueueError.
• 1.2 Tests cover construction, code preservation, cause chaining.

2. Shared types

• 2.1 types/types.ts — ChunkMetadata, StoredChunk, ChunkRequest, StreamEvent, StreamingQueueStatus, StreamingChunkQueueHooks. All chunk IDs bigint.

3. Validator subsystem

• 3.1 validator/validator.ts — ChunkValidator strategy + NoopChunkValidator.
• 3.2 validator/chunk-verifier-validator.ts — adapter wrapping @suaveplan/packer ChunkVerifier.

4. Decryptor subsystem

• 4.1 decryptor/decryptor.ts — ChunkDecryptor strategy + NoopChunkDecryptor.

5. Rate-limiter adapter

• 5.1 rate-limiter/adapter.ts — TokenBucketRateLimiterAdapter adapting genesis TokenBucket.consume().

6. Storage adapter

• 6.1 storage-adapter/persister.ts — StorageChunkPersister over AbstractStorage.

7. Binary protocol

• 7.1 binary-protocol/encoder.ts — encodeChunkRequest u64+u32+bitmap layout.

8. Hooks + events

• 8.1 hooks/hooks.ts — invokeHook safe-invocation helper.
• 8.2 events/events.ts — StreamEventEmitter with wildcard support.

9. Telemetry

• 9.1 telemetry/telemetry.ts — OTel meter with counters and histogram.

10. Core StreamingChunkQueue

• 10.1 queue/streaming-chunk-queue.ts — composes validator, decryptor, rate limiter, persister, telemetry, hooks, events.
• 10.2 Tests cover construction validation, out-of-range chunkId, duplicate ignore, out-of-order assembly, autostart, rate-limit retry, validation/decryption failure, persist/load round-trip, timeout, status, wildcard listener, hook invocation, cancel + clear.

11. Docs

• 11.1 Every implementation .ts has a sibling .md (≥200 words).
• 11.2 Root README.md with Modules section.

12. Pre-publish gate

• 12.1 bunx turbo lint typecheck test --filter=@suaveplan/streams-chunk-queue green.
• 12.2 bunx turbo test:coverage --filter=@suaveplan/streams-chunk-queue at 100/100/100/100.
• 12.3 docs:check 100%.

13. Spec fold + archive

• 13.1 Fold spec delta into openspec/specs/streams-chunk-queue/spec.md.
• 13.2 Move folder to openspec/archive/2026-05-23-enterprise-streams-chunk-queue/.
• 13.3 Run bun scripts/folder-reorg/generate-manifest.ts.

14. Commit

• 14.1 Commit on feat/streams-chunk-queue. No push, no main, no --no-verify.