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.