100 lines
7.5 KiB
Markdown
100 lines
7.5 KiB
Markdown
# 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
|
|
|
|
- [x] 1.1 Read `../suaveplan/enterprise/queue-distribution.md` end-to-end (stub — only L1-L12 are populated; recorded in proposal)
|
|
- [x] 1.2 Read upstream source under `../suaveplan/packages/universal/queue-distribution/src/`
|
|
- [x] 1.3 Read `openspec/AGENTS.md` §0a (parity), §0b (status), §6a (barrels), §7 (test runner), §13 (pre-archive)
|
|
- [x] 1.4 Replace placeholder `proposal.md` with upstream-faithful design
|
|
- [x] 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
|
|
- [x] 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`
|
|
- [x] 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
|