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

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

• Create universal/network/network-standby-transport/ with src/, tests/, and feature subdirectories.
• Write package.json at version 0.1.0: "sideEffects": false, exports map, deps per proposal.md.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. Types and error codes

• Define all public types in src/types/common.ts: Transport, TransportState, TransportEvent, PoolState, PoolEvent, PoolEventData, StandbyTransportPoolOptions.
• Write src/types/common.md (≥200 words, simple + advanced examples).
• Define error codes in src/error-codes.ts.
• Write Zod schemas in src/types/schemas.ts + src/types/schemas.md.

---

3. Promoter (src/core/promoter/)

• 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.
• Write promoter.test.ts (≤500 lines): promotion triggered on score drop, debounce prevents rapid promotion, no standby available → stays with degraded primary.
• Write promoter.md (≥200 words).

---

4. Standby transport pool (src/core/pool/)

• Implement createStandbyTransportPool(options):
  • Validates options with Zod.
  • Maintains ordered standby list (sorted by priority, then score).
  • Delegates promotion logic to createPromoter.
• Implement pool.add(transport) — adds to standby or sets as primary if none.
• Implement pool.remove(transportId) — removes; triggers promotion if primary removed.
• 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.
• Implement pool.promote(transportId) — manually promote a specific standby.
• OTel: span standby.send, counter standby.promotions_total.
• Write pool.test.ts (≤500 lines): add/remove, send routes to primary, send fails and promotes, manual promote.
• Write pool.md (≥200 words).

---

5. Property-based tests (tests/property.test.ts)

• Pool invariant: with N transports, primary is always the transport with highest score.
• Promotion ordering: standby sorted descending by score; best standby always promoted.

---

6. Docs and verify

• All per-file .md files per layout in proposal.md.
• universal/network/network-standby-transport/README.md.
• bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-standby-transport — all green, 100% coverage.
• bun scripts/publish.ts --package @suaveplan/network-standby-transport.
• Update CLAUDE.md. Archive change folder.