Initial Commit

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

@@ -0,0 +1,99 @@
+# Tasks: enterprise-network-protocol
+
+**Change ID**: enterprise-network-protocol
+**Package**: `@suaveplan/network-protocol`
+**Target path**: `universal/network/network-protocol`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`, `@suaveplan/serialize`, `@suaveplan/crypto-utils`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-protocol/` with `src/`, `tests/`, and all 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`: `ProtocolDefinition`, `FramingStrategy`, `MessageCodec`, `HandshakeDefinition`, `ProtocolMessage`, `ProtocolOffer`, `ProtocolNegotiationResult`, `SessionState`, `SessionEvent`, `SessionOptions`.
+- [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. Framing implementations (`src/framing/`)
+
+### 3a. Length-prefix framing
+
+- [x] Implement `encodeLengthPrefix(data, opts)` — prepend 2 or 4-byte length header (big-endian or little-endian) using `@suaveplan/crypto-utils` `i2osp`.
+- [x] Implement `decodeLengthPrefix(buffer, opts)` — parse header, extract payload bytes.
+- [x] Write `length-prefix.test.ts` + `length-prefix.md`.
+
+### 3b. Delimiter framing
+
+- [x] Implement `encodeDelimiter(data, delimiter)` — append delimiter to message bytes.
+- [x] Implement `decodeDelimiter(buffer, delimiter)` — split on delimiter bytes.
+- [x] Write `delimiter.test.ts` + `delimiter.md`.
+
+### 3c. Fixed-length framing
+
+- [x] Implement `encodeFixed(data, size)` — pad or throw if `data.length !== size`.
+- [x] Implement `decodeFixed(buffer, size)` — slice `size` bytes.
+- [x] Write `fixed.test.ts` + `fixed.md`.
+
+---
+
+## 4. Codec registry (`src/codecs/`)
+
+- [x] Implement `createCodecRegistry()` — stores `Map<string, MessageCodec<unknown>>`.
+- [x] Implement `register(codec)` / `get(type)` / `encode(message)` / `decode(type, data)`.
+- [x] `encode` throws `NetworkProtocolError(PROTO_CODEC_NOT_FOUND)` if codec missing.
+- [x] Write `codec-registry.test.ts` + `codec-registry.md`.
+
+---
+
+## 5. Protocol session (`src/core/session/`)
+
+- [x] Implement `ProtocolSession` class:
+  - Stores `framing`, `codecs` from parent protocol.
+  - `encode(message)`: check `maxMessageSize`; look up codec; apply framing.
+  - `decode(data)`: strip framing; look up codec by message type header.
+  - `handshake(signal?)`: call `definition.handshake.clientHello()`, await response, call `verify()`.
+  - Emit lifecycle events via event bus.
+- [x] Write `session.test.ts` (≤500 lines): encode/decode round-trip, handshake, too-large message throws.
+- [x] Write `session.md` (≥200 words).
+
+---
+
+## 6. Protocol factory (`src/core/protocol/`)
+
+- [x] Implement `defineProtocol(definition)`:
+  - Validates definition with Zod.
+  - Returns `Protocol` object.
+- [x] Implement `protocol.createSession(options?)` — creates `ProtocolSession`, returns it.
+- [x] Implement `protocol.negotiate(offered, signal?)`:
+  - Compute version intersection; take highest common version.
+  - Compute capability intersection.
+  - Return `ProtocolNegotiationResult`.
+- [x] Write `protocol.test.ts` + `protocol.md` (≥200 words).
+
+---
+
+## 7. Property-based tests (`tests/property.test.ts`)
+
+- [x] Encode/decode round-trip: for arbitrary `ProtocolMessage` with registered codec, `decode(encode(m))` deep-equals `m`.
+- [x] Framing round-trip: `decode(encode(payload))` equals payload for all three strategies.
+- [x] Negotiation symmetry: `negotiate(A, B)` produces same version as `negotiate(B, A)`.
+
+---
+
+## 8. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-protocol/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-protocol` — all green, 100%.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-protocol`.
+- [x] Update `CLAUDE.md`. Archive change folder.