Skip to content

net-svc: Port per-peer monitor connection-selection FSM to FASM internally (no API/wire changes) #106

@Zk2u

Description

@Zk2u

Description

Port the net-svc peer monitor state machine to use FASM as the internal transition engine, while preserving current external behavior and keeping net-svc-api unchanged.

The target is to make connection-selection correctness mechanically enforced by a deterministic STF, improve reproducibility of race bugs, and enable high-volume deterministic chaos/simulation testing against the normative spec in connection-soundness-model.md.

Motivation

  • Current peer-monitor logic is correctable but still hard to reason about because state transitions and side effects are interleaved.
  • We now have a detailed normative model; FASM is a good fit to encode it directly as (State, Input) -> (State', Actions).
  • We need faster, deterministic, reproducible chaos testing for race/cancel/loss/reorder paths.

Scope

  • Internal refactor in crates/net/svc only.
  • Keep crates/net/svc-api API unchanged.
  • Keep wire behavior/protocol compatibility unchanged.
  • Keep existing service runtime/tasks model, but move transition logic to FASM-driven STF.

Non-goals

  • No public API redesign.
  • No QUIC/TLS transport rewrite.
  • No protocol format changes.
  • No behavior changes outside what is required for strict spec compliance.

Implementation Plan

  1. Define FASM machine types for peer monitor domain state.
  2. Model all relevant commands/events as FASM inputs with identity fields (attempt_id, candidate_id, generation, request_id).
  3. Implement STF transitions to match spec section 6 exactly.
  4. Encode side effects as FASM actions (spawn outbound, spawn monitor, close connection, fail pending, schedule reconnect, open stream, etc.).
  5. Add adapter layer to execute emitted actions via existing task/runtime functions.
  6. Implement restore semantics appropriate for in-memory runtime (and document limits).
  7. Add invariant checks in tests for safety/liveness properties from spec section 7/8.

Acceptance Criteria

  • No external API changes in mosaic-net-svc-api.
  • Existing net-svc/net-client integration tests pass.
  • New STF-level deterministic simulation tests cover:
  1. Simultaneous connect convergence.
  2. Reorder compensation.
  3. Stale event isolation + resource cleanup.
  4. Race exhaustion termination.
  5. Open request pending/in-flight/cancel/loss completion semantics.
  • Seeded chaos tests are reproducible and print failing seed/trace.
  • cargo clippy and project lint targets pass.

Deliverables

  • FASM-based monitor module in crates/net/svc.
  • Runtime adapter from FASM actions to existing task spawns/close operations.
  • New STF simulation/property tests and updated integration assertions.
  • Documentation update mapping spec clauses to STF transitions for auditability.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions