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

Tasks — network-core

Blocked on: none. Consumes existing genesis packages only.

1. Scaffold

• 1.1 packages/network/network/ with package.json (@suaveplan/network@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/streams, @suaveplan/bitpacker, @suaveplan/serialize, @opentelemetry/api, zod.
• 1.3 No external runtime deps beyond catalog.

2. Types and contracts

• 2.1 src/types/plugin.types.ts — NetworkPlugin, PluginContext, PluginLifecycle.
• 2.2 src/types/envelope.types.ts — MessageEnvelope, EnvelopeHeaders, Zod schema.
• 2.3 src/types/transport.types.ts — Transport, TransportConfig, PeerInfo.
• 2.4 src/types/node.types.ts — NetworkNodeConfig, NetworkNodeState.
• 2.5 src/error-codes.ts — defineCodes("NET", [...]) frozen registry.

3. Plugin manager

• 3.1 src/plugin/plugin-manager.ts — use(plugin), installAll(), startAll(), stopAll(), disposeAll() in correct order.
• 3.2 Lifecycle dedup: installing the same plugin twice is a no-op.

4. Network bus

• 4.1 src/bus/network-bus.ts — wraps @suaveplan/events with topic-based routing, bounded queue, interceptors.
• 4.2 Topics: peer:joined, peer:left, peer:latency, election:vote, election:completed, failover:triggered, message:received, topology:changed.

5. Message router

• 5.1 src/router/message-router.ts — route(envelope) resolves targetId to transport, broadcast() fans out to all transports.
• 5.2 broadcast skips the sender.

6. Network node

• 6.1 src/node/network-node.ts — use(plugin), start(), stop(), send(), broadcast(), on(event).
• 6.2 Envelope validation via Zod before routing.
• 6.3 Idempotent start() / stop().

7. Spec

• 7.1 openspec/specs/network/spec.md — requirements NET-01 through NET-05 and NET-12.

8. Conformance tests

• 8.1 src/plugin/plugin.spec-conformance.test.ts — lifecycle order, duplicate install no-op.
• 8.2 src/node/node.spec-conformance.test.ts — send, broadcast, envelope validation, plugin wiring.
• 8.3 src/bus/bus.spec-conformance.test.ts — FIFO, backpressure, interceptor.
• 8.4 src/router/router.spec-conformance.test.ts — unicast, broadcast, skip-sender.
• 8.5 src/envelope/envelope.spec-conformance.test.ts — Zod accept/reject.
• 8.6 src/error-codes.spec-conformance.test.ts — frozen registry.
• 8.7 tests/dep-graph.test.ts — no cycles, tree-shake clean.

10. API versioning

• 10.1 src/versioning/version-info.ts — VersionInfo, semantic versioning, compatibility check.
• 10.2 src/versioning/version-manager.ts — VersionManager, migration paths, stability classification.
• 10.3 src/versioning/version-negotiator.ts — VersionNegotiator, exchanges versions during handshake.
• 10.4 Version embedded in MessageEnvelope headers.

11. Network timestamps

• 11.1 src/timing/network-timestamp.ts — NetworkTimestamp, ISO8601/unix/custom, timezone, precision.
• 11.2 src/timing/clock.ts — Clock interface, injectable for testing.
• 11.3 src/timing/timestamp-comparer.ts — TimestampComparer, isAfter, isBefore, compare.

12. Standardized event constants

• 12.1 src/events/network-events.ts — NetworkEvents, frozen enum of all standard bus topics.
• 12.2 Node lifecycle, message, hierarchy, plugin, system topics.

13. Spec

• 13.1 Update openspec/specs/network/spec.md with NET-53, NET-54, NET-55.

14. Conformance tests

• 14.1 src/versioning/versioning.spec-conformance.test.ts — compatibility, negotiation, rejection.
• 14.2 src/timing/timing.spec-conformance.test.ts — formats, timezone, precision, comparison.
• 14.3 src/events/events.spec-conformance.test.ts — constants, no typos, coverage.

15. Verify

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