sd-rust-design

Replace state-dependent Option fields and boolean flags with enum variants that each carry exactly the data their state needs. For example, model a connection as enum variants Idle, Connected { socket }, and Failed { error } instead of a struct with optional socket and error fields.

Use the typestate pattern: each state is its own type, and a transition consumes the current state and returns the next one. The compiler then enforces the transition graph, so invalid sequences like using an unverified value fail to compile.

Use a newtype with a public field when every inner value is valid and only identity confusion is at stake, such as user id versus team id. Use a private field with a single validating constructor when only some values are valid, like email formats or non-zero ports.

Fallible constructors should return Result<Self, Error> with the error enum written up front, following the parse-don't-validate principle. Downstream code then accepts only already-valid types, so no check is repeated and no validate-then-use gap opens.

Types cannot prove derive behavior, serialization semantics, or runtime logic. For example, an untagged serde enum with overlapping variant shapes deserializes by declaration order at runtime, and the compiler never flags it, so such behavior needs inspection and review.