suaveplan/openspec/changes/enterprise-browser-web-workers/tasks.md

# Tasks: enterprise-browser-web-workers

**Change ID**: enterprise-browser-web-workers
**Package**: `@suaveplan/web-workers`
**Target path**: `browser/platform/web-workers`
**Prerequisite packages on Verdaccio**: `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/logger`

---

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Scaffold

- [ ] Create directory tree per `proposal.md`.
- [ ] `package.json` v0.0.0, `"sideEffects": false`.
  - `dependencies`: `@suaveplan/events workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/logger workspace:^`, `@suaveplan/schema-registry workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
  - `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `happy-dom catalog:testing`, `@suaveplan/testing workspace:^`
  - Subpath exports: `"."`, `"./worker-manager"`, `"./shared-worker-manager"`, `"./worker-pool"`, `"./message-bus"`, `"./helpers/vite-worker"`
- [ ] `tsconfig.json`, `vitest.config.ts` (pool: forks, happy-dom environment).

---

## 2. Error codes

- [ ] `WORKER_NOT_FOUND`, `WORKER_QUEUE_FULL`, `WORKER_REQUEST_TIMEOUT`, `WORKER_CIRCUIT_OPEN`.
- [ ] `registerWebWorkerErrorCodes()` — call eagerly.

---

## 3. Types (`src/types/web-workers.types.ts`)

- [ ] `WorkerConfig`, `WorkerStatus`, `WorkerFactory`, `WorkerLike`, `WorkerMessage`, `WorkerPoolConfig`, `WorkerTask`, `PoolMetrics`, `MessageBusEventMap`, `WorkerManagerEventMap`, `RequestOptions`, `SharedWorkerFactory`.
- [ ] Write `web-workers.types.md`.

---

## 4. `BaseWorkerManager` (`src/core/base-manager/`)

- [ ] `base-manager.ts` — shared correlation-ID map, timeout logic, event emission, `AbortSignal` wiring.
- [ ] `WorkerManager` and `SharedWorkerManager` both extend this.
- [ ] Write `base-manager.md`.

---

## 5. Circuit breaker (`src/worker-manager/circuit-breaker/`)

- [ ] `circuit-breaker.ts` — state machine (closed → open → half-open); injectable clock; `record(success)`, `isOpen()`, `reset()`.
- [ ] Write `circuit-breaker.test.ts` (open on N failures, half-open after cooldown, reset on success). Write `circuit-breaker.md`.

---

## 6. `WorkerManager` (`src/worker-manager/worker-manager/`)

- [ ] `worker-manager.ts` — extends `BaseWorkerManager`; `create`, `postMessage` (with transfer list), `sendRequest` (with `AbortSignal` + backpressure ceiling), `terminate`, `terminateAll`, `has`, `getStatus`, `getWorkerNames`, `onError`.
- [ ] Wire circuit breaker and OTel metrics.
- [ ] Wire `@suaveplan/events` runtime emission.
- [ ] Write `worker-manager.test.ts` (create, postMessage, sendRequest, abort, backpressure, circuit open). Write `worker-manager.md`.

---

## 7. `SharedWorkerManager` (`src/shared-worker-manager/shared-worker-manager/`)

- [ ] `shared-worker-manager.ts` — `new SharedWorker(url)`; one `MessagePort` per named connection; `connect`, `disconnect`, `sendRequest` (AbortSignal).
- [ ] Write `shared-worker-manager.test.ts` (connect, message, disconnect). Write `shared-worker-manager.md`.

---

## 8. `WorkerPool` (`src/worker-pool/worker-pool/`)

- [ ] `worker-pool.ts` — FIFO task queue, round-robin dispatch, `minIdle`/`maxIdle`, health checks, per-task timeout, drain.
- [ ] `getMetrics()` returning `PoolMetrics` (size, idle, pending, completed, failed).
- [ ] Write `worker-pool.test.ts` (submit, saturation, backpressure, drain, health-check eviction). Write `worker-pool.md`.

---

## 9. `MessageBus` (`src/message-bus/message-bus/`)

- [ ] `message-bus.ts` — topic pub/sub, `subscribeOnce`, `broadcast`, `request` (AbortSignal), `registerHandler`, subscriber count, topic enumeration.
- [ ] Wire `@suaveplan/events` runtime emission via `MessageBusEventMap`.
- [ ] Write `message-bus.test.ts` (subscribe, publish, request/response, abort, broadcast). Write `message-bus.md`.

---

## 10. Streaming RPC (`src/streaming/stream/`)

- [ ] `stream.ts` — `sendStream<T>(manager, name, type, payload): AsyncIterable<T>` using correlation IDs and `MessagePort` transfer.
- [ ] Write `stream.test.ts`. Write `stream.md`.

---

## 11. Vite worker helper (`src/helpers/vite-worker/`)

- [ ] `vite-worker.ts` — `defineWorker(url, options?)` using `new URL(url, import.meta.url)`; exports factory and type.
- [ ] Write `vite-worker.test.ts`. Write `vite-worker.md`.

---

## 12. Integration test (`tests/integration.test.ts`)

- [ ] `WorkerManager` + `MessageBus` together: publish from worker, subscribe in main.
- [ ] `WorkerPool` saturation test with 10 concurrent tasks and `maxIdle: 3`.
- [ ] `AbortSignal` cancels in-flight `sendRequest`.
- [ ] Transfer `ArrayBuffer` via transfer list (verify zero-copy).

---

## 13. Docs + verify

- [ ] Write `.md` per module (≥200 words, API reference, examples).
- [ ] Write `README.md` with subpath table, pool guide, streaming RPC example, circuit-breaker reference.
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/web-workers` — green.
- [ ] `bunx turbo test:coverage` — 100%.
- [ ] No `@ts-expect-error` in `src/` or tests. No `vi.stubGlobal`.
- [ ] `SharedWorkerManager` and `WorkerPool` fully implemented (no stubs).
- [ ] `bun scripts/publish.ts --package @suaveplan/web-workers`.
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-browser-web-workers/`.