# 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.