Tasks — network-plugin-intra-relay

Blocked on: network-core, network-plugin-topology, network-plugin-crypto-messages.

1. Scaffold

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

2. Types

2.1 src/types/relay.types.ts — RelayConnection, RelayPath, RelayStrategy, RelayEnvelope.
2.2 src/types/discovery.types.ts — RelayCandidate, DiscoveryConfig.
2.3 src/types/security.types.ts — RelayRateLimit, RelayAuthPolicy.
2.4 src/error-codes.ts — defineCodes("NET_INTRA_RELAY", [...]).

3. Relay discovery

3.1 src/discovery/relay-discovery.ts — RelayDiscovery.
3.2 Discovers candidates from peer:connected bus events.
3.3 Excludes leaf-tier peers (Tier 2) from candidate set.
3.4 Maintains candidate cache with TTL.

4. Relay selector

4.1 src/selector/relay-selector.ts — RelaySelector.
4.2 Strategies: LowestLatency, HighestReliability, FewestHops, TierOptimized, LoadBalanced.
4.3 Tie-breaking: lowest lex peerId.
4.4 Re-evaluates selection when relay:degraded is emitted.

5. Relay connection manager

5.1 src/connection/relay-connection-manager.ts — RelayConnectionManager.
5.2 FSM: pending → active → degraded → closed.
5.3 Tracks active relay paths per (sourceId, targetId) pair.
5.4 Auto-closes inactive paths after configurable timeout.

6. Relay message envelope

6.1 src/envelope/relay-envelope.ts — RelayMessageEnvelope.
6.2 Wraps MessageEnvelope with relayPath, hopCount, maxHops, visitedNodes.
6.3 hopCount increments at each forwarding node.
6.4 visitedNodes appends current peerId at each hop.

7. Loop prevention

7.1 src/loop/loop-prevention.ts — LoopPrevention.
7.2 Drops message if hopCount >= maxHops (default 8).
7.3 Drops message if visitedNodes contains current peerId.
7.4 Emits relay:loop-detected on bus for monitoring.

8. Relay performance monitor

8.1 src/monitor/relay-performance-monitor.ts — RelayPerformanceMonitor.
8.2 Tracks RTT, packet loss, bandwidth per relay path.
8.3 Emits relay:degraded when quality falls below threshold.
8.4 Emits relay:recovered when quality returns.

9. Relay security manager

9.1 src/security/relay-security-manager.ts — RelaySecurityManager.
9.2 Authenticates relay nodes using PeerIdentityVerifier from crypto-messages.
9.3 Validates relay message signatures.
9.4 Enforces per-peer relay rate limits (messages/sec).

10. Plugin wrapper

10.1 src/plugin/intra-relay-plugin.ts — IntraRelayPlugin implements NetworkPlugin.
10.2 Subscribes to peer:connected, peer:disconnected, relay:degraded on bus.
10.3 Intercepts send() to inject relay path when direct connection unavailable.

11. Spec

11.1 Update openspec/specs/network/spec.md with NET-40.

12. Conformance tests

12.1 src/discovery/discovery.spec-conformance.test.ts — candidate discovery, leaf exclusion.
12.2 src/selector/selector.spec-conformance.test.ts — 5 strategies, tie-breaking.
12.3 src/connection/connection.spec-conformance.test.ts — FSM transitions, auto-close.
12.4 src/envelope/envelope.spec-conformance.test.ts — wrapper format, hop increment.
12.5 src/loop/loop.spec-conformance.test.ts — max-hops drop, visited-node drop.
12.6 src/security/security.spec-conformance.test.ts — auth, rate limits, DoS prevention.
12.7 src/monitor/monitor.spec-conformance.test.ts — RTT tracking, degradation, recovery.
12.8 src/error-codes.spec-conformance.test.ts — frozen registry.

13. Verify

13.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-intra-relay green.
13.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-intra-relay 100/100/100/100.
13.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-intra-relay PASS.

Audit (2026-05-05)

Shipped the core intra-mesh relay primitives at 100/100/100/100 statement/branch/function/line coverage across 8 spec-conformance test files (95 tests). Documentation coverage: 9/9 files (100%). OpenSpec conformance: PASS.

All eight NETWORK_INTRA_RELAY_CODES are wired (NO_RELAY_CANDIDATE, RELAY_LOOP_DETECTED, MAX_HOPS_EXCEEDED, INVALID_TRANSITION, PATH_NOT_FOUND, PATH_ALREADY_EXISTS, STRATEGY_UNKNOWN, ENVELOPE_INVALID) — six are thrown via NetworkIntraRelayError, two (RELAY_LOOP_DETECTED / MAX_HOPS_EXCEEDED) are carried on LoopDropResult.code since dropping a relay envelope is a normal outcome rather than an error.

Subsystems wired: RelayDiscovery, RelaySelector (all 5 strategies), RelayConnectionManager (full FSM with auto-close on closed transition, idle sweep), RelayMessageEnvelope (helpers: wrapEnvelope / advanceEnvelope / nextHopFor / unwrapEnvelope), LoopPrevention, RelayPerformanceMonitor (hysteresis-protected degraded/recovered transitions), and the IntraRelayPlugin facade.

Per the proposal's ## Deferred to follow-up changes block (and openspec/AGENTS.md §2c), RelaySecurityManager is deferred to network-plugin-intra-relay-security since its PeerIdentityVerifier integration with @suaveplan/network-plugin-crypto-messages warrants dedicated design + test surface. Three additional codes (RELAY_SIGNATURE_INVALID, RELAY_PEER_UNTRUSTED, RELAY_RATE_LIMIT_EXCEEDED) will be appended to the registry by that follow-up.

5.8 KiB Raw Blame History