suaveplan/openspec/changes/archive/2026-05-04-network-plugin-protocol/tasks.md

Tasks — network-plugin-protocol

Blocked on: network-core.

1. Scaffold

• 1.1 packages/network/network-plugin-protocol/ with package.json (@suaveplan/network-plugin-protocol@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/bitpacker, @suaveplan/streams, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/protocol.types.ts — ProtocolHeader, ProtocolMessage, MessageType.
• 2.2 src/types/pipeline.types.ts — PipelineConfig, PipelineStage.
• 2.3 src/error-codes.ts — defineCodes("NET_PROTO", [...]).

3. Binary protocol

• 3.1 src/protocol/binary-protocol.ts — BinaryProtocol.
• 3.2 Header: version(1) | flags(1) | messageType(1) | timestamp(8) | payloadLength(2) = 13 bytes.
• 3.3 Version negotiation placeholder (v1 only for now).

4. Message encoder/decoder

• 4.1 src/encoder/message-encoder.ts — schema-aware encoding with @suaveplan/bitpacker.
• 4.2 src/encoder/message-decoder.ts — reverse decoding.
• 4.3 Roundtrip test for all MessageType variants.

5. Protocol pipeline

• 5.1 src/pipeline/protocol-pipeline.ts — ProtocolPipeline.
• 5.2 Outgoing: MessageEncoder → lengthPrefixEncode → CryptoTransform → compressStream.
• 5.3 Incoming: reverse order with decompressStream, CryptoTransform, lengthPrefixDecode, MessageDecoder.
• 5.4 Error handling: StreamPipeFailedError on any stage failure.

6. Plugin wrapper

• 6.1 src/plugin/protocol-plugin.ts — ProtocolPlugin implements NetworkPlugin.
• 6.2 Installs protocol, encoder, decoder, pipeline on install().

7. Spec

• 7.1 Update openspec/specs/network/spec.md with NET-16, NET-17.

8. Conformance tests

• 8.1 src/protocol/protocol.spec-conformance.test.ts — header format, version, flags.
• 8.2 src/encoder/encoder.spec-conformance.test.ts — schema encoding, roundtrip.
• 8.3 src/pipeline/pipeline.spec-conformance.test.ts — pipeline ordering, error handling.
• 8.4 src/error-codes.spec-conformance.test.ts — frozen registry.

9. Serialization strategy framework

• 9.1 src/serialization/serializer-factory.ts — SerializerFactory, registers by content type.
• 9.2 src/serialization/json-serializer.ts — JsonSerializer.
• 9.3 src/serialization/binary-serializer.ts — BinarySerializer with optional compression.
• 9.4 src/serialization/msgpack-serializer.ts — MessagePackSerializer.
• 9.5 Content-type negotiation via header flags.

10. Priority queue & adaptive batching

• 10.1 src/queue/priority-message-queue.ts — PriorityMessageQueue, 5 tiers, FIFO within tier.
• 10.2 src/batcher/message-batcher.ts — MessageBatcher, flush on size/time/priority.
• 10.3 src/backpressure/backpressure-controller.ts — BackpressureController, slows on overwhelm.
• 10.4 CRITICAL messages bypass queue entirely.

11. Message TTL & loop detection

• 11.1 src/ttl/message-ttl.ts — MessageTTL, decrements per hop, drops at zero.
• 11.2 src/loop/loop-detector.ts — LoopDetector, checks visitedNodes for cycles.
• 11.3 src/dedup/duplicate-detector.ts — DuplicateDetector, bloom filter for broadcast dedup.

12. Route caching

• 12.1 src/cache/route-cache.ts — RouteCache, (source, target) → nextHop.
• 12.2 Invalidation on topology:changed bus event.
• 12.3 Adaptive size based on memory availability.

13. Spec

• 13.1 Update openspec/specs/network/spec.md with NET-45, NET-57, NET-58, NET-59.

14. Conformance tests

• 14.1 src/serialization/serialization.spec-conformance.test.ts — factory, JSON, Binary, MessagePack.
• 14.2 src/queue/queue.spec-conformance.test.ts — 5 tiers, FIFO, CRITICAL bypass.
• 14.3 src/batcher/batcher.spec-conformance.test.ts — grouping, flush triggers, adaptive.
• 14.4 src/backpressure/backpressure.spec-conformance.test.ts — detection, slowdown, recovery.
• 14.5 src/ttl/ttl.spec-conformance.test.ts — hop decrement, drop at zero.
• 14.6 src/loop/loop.spec-conformance.test.ts — cycle detection, visited tracking.
• 14.7 src/dedup/dedup.spec-conformance.test.ts — bloom filter, false positive tolerance.
• 14.8 src/cache/cache.spec-conformance.test.ts — caching, invalidation, memory bounds.

15. Verify

• 15.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-protocol green.
• 15.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-protocol 100/100/100/100.
• 15.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-protocol PASS.