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

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

• Create universal/network/network-protocol/ with src/, tests/, and all 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.

---

2. Types and error codes

• Define all public types in src/types/common.ts: ProtocolDefinition, FramingStrategy, MessageCodec, HandshakeDefinition, ProtocolMessage, ProtocolOffer, ProtocolNegotiationResult, SessionState, SessionEvent, SessionOptions.
• 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. Framing implementations (src/framing/)

3a. Length-prefix framing

• Implement encodeLengthPrefix(data, opts) — prepend 2 or 4-byte length header (big-endian or little-endian) using @suaveplan/crypto-utils i2osp.
• Implement decodeLengthPrefix(buffer, opts) — parse header, extract payload bytes.
• Write length-prefix.test.ts + length-prefix.md.

3b. Delimiter framing

• Implement encodeDelimiter(data, delimiter) — append delimiter to message bytes.
• Implement decodeDelimiter(buffer, delimiter) — split on delimiter bytes.
• Write delimiter.test.ts + delimiter.md.

3c. Fixed-length framing

• Implement encodeFixed(data, size) — pad or throw if data.length !== size.
• Implement decodeFixed(buffer, size) — slice size bytes.
• Write fixed.test.ts + fixed.md.

---

4. Codec registry (src/codecs/)

• Implement createCodecRegistry() — stores Map<string, MessageCodec<unknown>>.
• Implement register(codec) / get(type) / encode(message) / decode(type, data).
• encode throws NetworkProtocolError(PROTO_CODEC_NOT_FOUND) if codec missing.
• Write codec-registry.test.ts + codec-registry.md.

---

5. Protocol session (src/core/session/)

• 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.
• Write session.test.ts (≤500 lines): encode/decode round-trip, handshake, too-large message throws.
• Write session.md (≥200 words).

---

6. Protocol factory (src/core/protocol/)

• Implement defineProtocol(definition):
  • Validates definition with Zod.
  • Returns Protocol object.
• Implement protocol.createSession(options?) — creates ProtocolSession, returns it.
• Implement protocol.negotiate(offered, signal?):
  • Compute version intersection; take highest common version.
  • Compute capability intersection.
  • Return ProtocolNegotiationResult.
• Write protocol.test.ts + protocol.md (≥200 words).

---

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

• Encode/decode round-trip: for arbitrary ProtocolMessage with registered codec, decode(encode(m)) deep-equals m.
• Framing round-trip: decode(encode(payload)) equals payload for all three strategies.
• Negotiation symmetry: negotiate(A, B) produces same version as negotiate(B, A).

---

8. Docs and verify

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