Initial Commit

openspec/archive/2026-05-12-enterprise-network-standby-transport/tasks.md

@@ -0,0 +1,71 @@
+# Tasks: enterprise-network-standby-transport
+
+**Change ID**: enterprise-network-standby-transport
+**Package**: `@suaveplan/network-standby-transport`
+**Target path**: `universal/network/network-standby-transport`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/retry`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-standby-transport/` with `src/`, `tests/`, and feature subdirectories.
+- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
+- [x] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `Transport`, `TransportState`, `TransportEvent`, `PoolState`, `PoolEvent`, `PoolEventData`, `StandbyTransportPoolOptions`.
+- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
+- [x] Define error codes in `src/error-codes.ts`.
+- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
+
+---
+
+## 3. Promoter (`src/core/promoter/`)
+
+- [x] Implement `createPromoter(pool, options)`:
+  - Watches transport score changes.
+  - When primary score drops below `degradationThreshold`, select best standby (highest score ≥ `promotionThreshold`).
+  - Debounce via `@suaveplan/timing` throttle using injectable `Clock`.
+  - Emit `primary-promoted` event.
+- [x] Write `promoter.test.ts` (≤500 lines): promotion triggered on score drop, debounce prevents rapid promotion, no standby available → stays with degraded primary.
+- [x] Write `promoter.md` (≥200 words).
+
+---
+
+## 4. Standby transport pool (`src/core/pool/`)
+
+- [x] Implement `createStandbyTransportPool(options)`:
+  - Validates options with Zod.
+  - Maintains ordered standby list (sorted by priority, then score).
+  - Delegates promotion logic to `createPromoter`.
+- [x] Implement `pool.add(transport)` — adds to standby or sets as primary if none.
+- [x] Implement `pool.remove(transportId)` — removes; triggers promotion if primary removed.
+- [x] Implement `pool.send(message, signal?)`:
+  - Routes to primary.
+  - On send failure, trigger immediate promotion, then retry on new primary.
+  - Throw `StandbyTransportError(STANDBY_ALL_FAILED)` if all transports fail.
+- [x] Implement `pool.promote(transportId)` — manually promote a specific standby.
+- [x] OTel: span `standby.send`, counter `standby.promotions_total`.
+- [x] Write `pool.test.ts` (≤500 lines): add/remove, send routes to primary, send fails and promotes, manual promote.
+- [x] Write `pool.md` (≥200 words).
+
+---
+
+## 5. Property-based tests (`tests/property.test.ts`)
+
+- [x] Pool invariant: with N transports, primary is always the transport with highest score.
+- [x] Promotion ordering: standby sorted descending by score; best standby always promoted.
+
+---
+
+## 6. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-standby-transport/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-standby-transport` — all green, 100% coverage.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-standby-transport`.
+- [x] Update `CLAUDE.md`. Archive change folder.