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

Tasks: enterprise-network-assignment

Change ID: enterprise-network-assignment Package: @suaveplan/network-assignment Target path: universal/network/network-assignment Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/logger

---

1. Scaffold

• Create universal/network/network-assignment/ with src/, tests/, src/__benchmarks__/, 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 (including bench).

---

2. Types and error codes

• Define all public types in src/types/common.ts: Peer, AssignerOptions, AssignerSnapshot, RebalanceResult, AssignmentAlgorithm.
• 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. Algorithm implementations (src/algorithms/)

3a. Consistent hash

• Implement consistentHash(key, peers, virtualNodes?):
  • Build virtual node ring: for each peer, hash ${peer.id}#${i} for i in 0..virtualNodes.
  • For assignment, hash key and find the next clockwise virtual node.
  • Return the peer owning that virtual node.
• Write consistent-hash.test.ts (≤500 lines): determinism, adding peer minimally disrupts existing assignments (monotonicity), empty peers returns null.
• Write consistent-hash.md (≥200 words).

3b. Rendezvous hash

• Implement rendezvousHash(key, peers):
  • For each peer, compute hash(key + peer.id).
  • Return peer with highest hash value (HRW algorithm).
• Write rendezvous-hash.test.ts + rendezvous-hash.md.

3c. Weighted random

• Implement weightedRandom(peers, rng):
  • Normalise weights; use CDF + rng.next() to select.
• Write weighted-random.test.ts + weighted-random.md.

3d. Latency-aware

• Implement latencyAware(peers, maxPeers?):
  • Sort peers by latencyMs ascending; return first (lowest-latency).
  • Fall back to first peer if no latency data.
• Write latency-aware.test.ts + latency-aware.md.

---

4. Assigner (src/core/assigner/)

• Implement createAssigner(options?):
  • Stores peers in Map<string, Peer>.
  • Selects algorithm implementation based on options.algorithm.
• Implement assigner.addPeer(peer), removePeer(id).
• Implement assigner.assign(key) — calls algorithm; OTel counter assignment.assign_total.
• Implement assigner.assignN(key, n) — returns top-N distinct peers (rendezvous iterates CDF; consistent-hash walks ring).
• Implement assigner.rebalance() — snapshot before/after peer list; compute diff; OTel histogram assignment.rebalance_duration_ms.
• Implement assigner.snapshot().
• Write assigner.test.ts (≤500 lines): all four algorithms, assignN, rebalance, no peers.
• Write assigner.md (≥200 words).

---

5. Benchmarks (src/__benchmarks__/assignment.bench.ts)

• consistent_hash_1k: 1k assign calls with 20-peer ring.
• rendezvous_1k: 1k assign calls with 20 peers.
• rebalance_100_keys: rebalance after adding 1 peer with 100 pre-assigned keys.

---

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

• Consistent hash monotonicity: adding 1 peer reassigns ≤ (N_keys / N_peers) keys on average.
• Determinism: same key + same peers always yields same assignment across all algorithms.
• AssignN uniqueness: all N returned peers are distinct.

---

7. Docs and verify

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