suaveplan/openspec/archive/2026-05-11-enterprise-queue-distribution/tasks.md

Tasks — enterprise-queue-distribution

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened. Retroactive ticking is the failure mode this template guards against.

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/queue-distribution.md end-to-end (stub — only L1-L12 are populated; recorded in proposal)
• 1.2 Read upstream source under ../suaveplan/packages/universal/queue-distribution/src/
• 1.3 Read openspec/AGENTS.md §0a (parity), §0b (status), §6a (barrels), §7 (test runner), §13 (pre-archive)
• 1.4 Replace placeholder proposal.md with upstream-faithful design
• 1.5 Fill ## Source mapping table — every requirement cites a line range in upstream source OR appears in the "no source line" table with justification
• 1.6 Draft specs/queue-distribution/spec.md, specs/queue-distribution-http/spec.md, specs/queue-distribution-worker-thread/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement in each spec delta carries a **Verified by:** line naming concrete it(...) titles

2. Implementation — @suaveplan/queue-distribution (core)

• 2.1 Scaffold packages/streams/queue-distribution/ (package.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md)
• 2.2 src/errors/queue-distribution-error.ts — QueueDistributionError + defineCodes("QUEUE_DIST", [...]) registry (12 codes)
• 2.3 src/task/task.ts — DistributedTask<I,O>, TaskStatus, TaskMetadata, TaskMetadataSchema, ExecutionContext
• 2.4 src/worker/worker.ts — Worker interface, WorkerStatus, WorkerHealth, WorkerInfo, WorkerHealthSchema, WorkerInfoSchema
• 2.5 src/worker/abstract/abstract.ts + abstract-execute.ts + abstract-metrics.ts — AbstractWorker split across ≤300-LOC files
• 2.6 src/worker/local/local.ts — LocalWorker<Ctx>
• 2.7 src/load-balancing/base/base.ts — LoadBalancingStrategy, AbstractLoadBalancingStrategy.filterAvailableWorkers
• 2.8 src/load-balancing/round-robin/round-robin.ts — RoundRobinStrategy
• 2.9 src/load-balancing/least-busy/least-busy.ts — LeastBusyStrategy with optional EWMA perf bias
• 2.10 src/load-balancing/weighted/weighted.ts — WeightedStrategy with injectable Rng
• 2.11 src/health-checker/health-checker.ts — WorkerHealthChecker interface + PeriodicHealthChecker (Clock-driven timeout race)
• 2.12 src/pool/pool.ts — WorkerPool + WorkerSearchCriteria + WorkerSearchCriteriaSchema
• 2.13 src/manager/manager.ts + manager-dispatch.ts + manager-supervisor.ts — WorkerManager split across ≤300-LOC files
• 2.14 src/observability/instruments.ts — @suaveplan/opentelemetry counter/histogram/span definitions
• 2.15 src/index.ts — explicit named re-exports (no export *)
• 2.16 Subpath exports in package.json per feature module (one entry per src/<category>/<feature>/)

3. Implementation — @suaveplan/queue-distribution-http

• 3.1 Scaffold packages/streams/queue-distribution-http/
• 3.2 src/errors/queue-distribution-http-error.ts — 6 codes
• 3.3 src/communicator/base/base.ts — WorkerCommunicator interface + AbstractWorkerCommunicator (Clock-driven withTimeout)
• 3.4 src/communicator/http/http-communicator.ts — HttpWorkerCommunicator with injectable fetch, Zod-validated wire envelope WorkerApiResponse<T>
• 3.5 src/worker/remote/remote.ts + remote-connect.ts + remote-health.ts — RemoteWorker split across ≤300-LOC files; backoff via @suaveplan/retry
• 3.6 src/index.ts — explicit named re-exports
• 3.7 Subpath exports per feature module

4. Implementation — @suaveplan/queue-distribution-worker-thread

• 4.1 Scaffold packages/streams/queue-distribution-worker-thread/
• 4.2 src/errors/queue-distribution-worker-thread-error.ts — 4 codes
• 4.3 src/communicator/worker-thread/worker-thread-communicator.ts — message-correlation map, Zod envelope, AbortSignal
• 4.4 src/worker/worker-thread/worker-thread-worker.ts — WorkerThreadWorker subclass, injectable WorkerFactory
• 4.5 src/index.ts — explicit named re-exports
• 4.6 Subpath exports per feature module

5. Tests (all three packages)

• 5.1 Per-feature *.test.ts covering happy path + every failure branch
• 5.2 Per-feature *.spec-conformance.test.ts pinning type-level / OTel / strict-mode / lifecycle scenarios
• 5.3 src/errors/queue-distribution-error.test.ts — every registered code thrown by ≥1 production path
• 5.4 tests/dep-graph.test.ts — runtime + dev deps respect plugin model
• 5.5 fast-check property suite for WeightedStrategy distribution
• 5.6 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)
• 5.7 All test files import runner primitives from @suaveplan/testing/runner — verified with the grep in §13 step 4b
• 5.8 OTel emission asserted with real in-memory MeterProvider (no vi.mock)

6. Documentation

• 6.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 6.2 Each package's README.md with module index + Quick-start
• 6.3 Update CLAUDE.md package listing (3 new packages under streams plugin)
• 6.4 Update STATUS.md — flip queue-distribution row to ✅ and add 2 new plugin rows
• 6.5 Update SUMMARY.md — paragraph per package
• 6.6 mitata benchmarks under src/__benchmarks__/ for each package

7. Pre-archive verification (the 5-gate triple per package)

• 7.1 bun run check — Biome 0/0/0 across whole monorepo
• 7.2 bunx turbo lint typecheck test --filter=@suaveplan/queue-distribution{,-http,-worker-thread} — green
• 7.3 bunx turbo test:coverage --filter=@suaveplan/queue-distribution{,-http,-worker-thread} — 100/100/100/100
• 7.4 bun scripts/openspec-conformance.ts @suaveplan/queue-distribution (+ both plugins) — exit 0, no error findings
• 7.5 bunx turbo build --filter=@suaveplan/queue-distribution{,-http,-worker-thread} — green

8. Pre-archive 9-row checklist (skill / AGENTS.md §13)

• 8.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 8.2 Zod schemas wired at every declared boundary
• 8.3 Every error code thrown by ≥1 production code path
• 8.4 Strict-mode behaviors tested both on and off
• 8.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 8.6 Lifecycle dedup tested where claimed (in-flight Promise, idempotent start/stop)
• 8.7 No retroactive tick — every box reflects work done in this change
• 8.8 No export * in any feature-module barrel — verified with the grep in §13 step 4a
• 8.9 No direct vitest / bun:test imports — verified with the grep in §13 step 4b

9. Archive

• 9.1 Fold spec deltas into openspec/specs/queue-distribution/spec.md, openspec/specs/queue-distribution-http/spec.md, openspec/specs/queue-distribution-worker-thread/spec.md
• 9.2 Move openspec/changes/enterprise-queue-distribution/ → openspec/archive/2026-05-11-enterprise-queue-distribution/
• 9.3 Refresh MANIFEST.md (bun scripts/folder-reorg/generate-manifest.ts)
• 9.4 Refresh MISSING.yml (bun scripts/generate-missing.ts)
• 9.5 bunx markdownlint-cli2 --fix and verify exit 0 on second pass