Initial Commit

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

@@ -0,0 +1,171 @@
+# OpenSpec Change: enterprise-network-assignment
+
+- **Change ID**: enterprise-network-assignment
+- **Package**: `@suaveplan/network-assignment`
+- **Category**: universal/network
+- **Target path**: `universal/network/network-assignment`
+- **Status**: SUPERSEDED-BY-GENESIS-WAVE
+- **Date**: 2026-04-24
+
+---
+
+## Summary
+
+Deliver `@suaveplan/network-assignment` on the genesis branch from scratch at enterprise quality. The package provides peer assignment algorithms: consistent hashing for deterministic peer selection, rendezvous hashing for load balancing, weighted random assignment, geographic/latency-aware assignment, and re-assignment on peer addition/removal with minimal disruption. Genesis adds structured errors via `@suaveplan/error`, Zod schemas for all assignment types, OTel instrumentation on assignment operations, injectable `Rng` for reproducible assignments, and property-based tests for distribution invariants.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | Base class for `NetworkAssignmentError`; stable error codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `Rng` |
+| `@suaveplan/logger` (`workspace:^`) | Structured logging |
+| `zod` (`catalog:forms`) | Zod schemas |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters on assignment |
+| `tslib` (`catalog:build`) | Runtime helpers |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
+
+---
+
+## Public API surface
+
+### Core
+
+```ts
+function createAssigner(options?: AssignerOptions): Assigner
+
+interface Assigner {
+  addPeer(peer: Peer): void
+  removePeer(peerId: string): void
+  assign(key: string): Peer | null
+  assignN(key: string, n: number): ReadonlyArray<Peer>
+  rebalance(): RebalanceResult
+  snapshot(): AssignerSnapshot
+}
+```
+
+### Types
+
+```ts
+interface Peer {
+  id: string
+  weight?: number
+  region?: string
+  latencyMs?: number
+  capacity?: number
+  tags?: Record<string, string>
+}
+
+interface RebalanceResult {
+  readonly reassigned: number
+  readonly moved: ReadonlyArray<{ key: string; from: string; to: string }>
+  readonly durationMs: number
+}
+
+interface AssignerSnapshot {
+  readonly peers: ReadonlyArray<Peer>
+  readonly assignments: number
+  readonly algorithm: AssignmentAlgorithm
+}
+
+type AssignmentAlgorithm = 'consistent-hash' | 'rendezvous' | 'weighted-random' | 'latency-aware'
+
+interface AssignerOptions {
+  algorithm?: AssignmentAlgorithm
+  virtualNodes?: number    // for consistent hashing, default 150
+  replicationFactor?: number
+  rng?: Rng
+  logger?: LoggerLike
+  clock?: Clock
+}
+```
+
+### Algorithm utilities
+
+```ts
+function consistentHash(key: string, peers: Peer[], virtualNodes?: number): Peer | null
+function rendezvousHash(key: string, peers: Peer[]): Peer | null
+function weightedRandom(peers: Peer[], rng: Rng): Peer | null
+function latencyAware(peers: Peer[], maxPeers?: number): Peer | null
+```
+
+### Error codes
+
+```ts
+type NetworkAssignmentErrorCode =
+  | 'ASSIGN_NO_PEERS'
+  | 'ASSIGN_PEER_NOT_FOUND'
+  | 'ASSIGN_INVALID_OPTIONS'
+
+function registerNetworkAssignmentErrorCodes(): void
+```
+
+---
+
+## Genesis additions
+
+1. **Structured `NetworkAssignmentError`** with stable `ASSIGN.*` codes
+2. **Zod schemas** for `AssignerOptions`, `Peer`
+3. **Four assignment algorithms**: consistent hash (FNV-1a + virtual nodes), rendezvous hash (HRW), weighted random, latency-aware
+4. **Injectable `Rng`** for deterministic weighted-random assignments in tests
+5. **OTel instrumentation** — counter `assignment.assign_total`, histogram `assignment.rebalance_duration_ms`
+6. **Property-based tests** — consistent hash monotonicity (adding peer reassigns minimum keys), distribution uniformity, weight-proportional assignment
+
+---
+
+## File layout
+
+```text
+universal/network/network-assignment/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/
+      index.ts
+    types/
+      common.ts
+      common.md
+    core/
+      assigner/
+        assigner.ts
+        assigner.md
+        assigner.types.ts
+        assigner.test.ts
+        index.ts
+    algorithms/
+      consistent-hash.ts
+      consistent-hash.md
+      consistent-hash.test.ts
+      rendezvous-hash.ts
+      rendezvous-hash.md
+      rendezvous-hash.test.ts
+      weighted-random.ts
+      weighted-random.md
+      weighted-random.test.ts
+      latency-aware.ts
+      latency-aware.md
+      latency-aware.test.ts
+    __benchmarks__/
+      assignment.bench.ts
+  tests/
+    integration.test.ts
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger` must be published.

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

@@ -0,0 +1,97 @@
+# 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
+
+- [x] Create `universal/network/network-assignment/` with `src/`, `tests/`, `src/__benchmarks__/`, 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 (including `bench`).
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `Peer`, `AssignerOptions`, `AssignerSnapshot`, `RebalanceResult`, `AssignmentAlgorithm`.
+- [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. Algorithm implementations (`src/algorithms/`)
+
+### 3a. Consistent hash
+
+- [x] 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.
+- [x] Write `consistent-hash.test.ts` (≤500 lines): determinism, adding peer minimally disrupts existing assignments (monotonicity), empty peers returns null.
+- [x] Write `consistent-hash.md` (≥200 words).
+
+### 3b. Rendezvous hash
+
+- [x] Implement `rendezvousHash(key, peers)`:
+  - For each peer, compute `hash(key + peer.id)`.
+  - Return peer with highest hash value (HRW algorithm).
+- [x] Write `rendezvous-hash.test.ts` + `rendezvous-hash.md`.
+
+### 3c. Weighted random
+
+- [x] Implement `weightedRandom(peers, rng)`:
+  - Normalise weights; use CDF + `rng.next()` to select.
+- [x] Write `weighted-random.test.ts` + `weighted-random.md`.
+
+### 3d. Latency-aware
+
+- [x] Implement `latencyAware(peers, maxPeers?)`:
+  - Sort peers by `latencyMs` ascending; return first (lowest-latency).
+  - Fall back to first peer if no latency data.
+- [x] Write `latency-aware.test.ts` + `latency-aware.md`.
+
+---
+
+## 4. Assigner (`src/core/assigner/`)
+
+- [x] Implement `createAssigner(options?)`:
+  - Stores peers in `Map<string, Peer>`.
+  - Selects algorithm implementation based on `options.algorithm`.
+- [x] Implement `assigner.addPeer(peer)`, `removePeer(id)`.
+- [x] Implement `assigner.assign(key)` — calls algorithm; OTel counter `assignment.assign_total`.
+- [x] Implement `assigner.assignN(key, n)` — returns top-N distinct peers (rendezvous iterates CDF; consistent-hash walks ring).
+- [x] Implement `assigner.rebalance()` — snapshot before/after peer list; compute diff; OTel histogram `assignment.rebalance_duration_ms`.
+- [x] Implement `assigner.snapshot()`.
+- [x] Write `assigner.test.ts` (≤500 lines): all four algorithms, assignN, rebalance, no peers.
+- [x] Write `assigner.md` (≥200 words).
+
+---
+
+## 5. Benchmarks (`src/__benchmarks__/assignment.bench.ts`)
+
+- [x] `consistent_hash_1k`: 1k `assign` calls with 20-peer ring.
+- [x] `rendezvous_1k`: 1k `assign` calls with 20 peers.
+- [x] `rebalance_100_keys`: rebalance after adding 1 peer with 100 pre-assigned keys.
+
+---
+
+## 6. Property-based tests (`tests/property.test.ts`)
+
+- [x] Consistent hash monotonicity: adding 1 peer reassigns ≤ `(N_keys / N_peers)` keys on average.
+- [x] Determinism: same key + same peers always yields same assignment across all algorithms.
+- [x] AssignN uniqueness: all N returned peers are distinct.
+
+---
+
+## 7. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-assignment/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-assignment` — all green, 100% coverage.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-assignment`.
+- [x] Update `CLAUDE.md`. Archive change folder.