m05-type-driven_skill

Overview

This skill focuses on type-driven design for Rust: using the type system to make invalid states unrepresentable and shift validation to compile time where possible. It codifies patterns like newtypes, type-state, PhantomData, marker traits, builders, sealed traits, and zero-sized types to encode invariants and transitions. Use it to decide when to encode constraints in types vs. when runtime checks are unavoidable.

How this skill works

The skill inspects a design problem and maps it to type-level patterns that encode invariants or states. It recommends creating validated newtypes for semantic values, using type-state generics to model allowed transitions, and leveraging PhantomData, marker traits, or ZSTs for capability and lifetime markers. It also guides when builders or Result-returning constructors are appropriate for gradual or runtime validation.

When to use it

• You want the compiler to prevent invalid states instead of runtime checks.
• A value has domain semantics beyond its primitive representation (e.g., Email, UserId).
• You need to model a state machine with compile-time transition constraints.
• You must mark capabilities or ownership without runtime cost (marker traits, ZST).
• Construction requires multi-step validation or gradual initialization (builder pattern).

Best practices

• Prefer newtypes over raw primitives to encode semantic meaning and restrict APIs.
• Model distinct states as types and expose only valid transitions via impl blocks.
• Validate once at construction for trusted invariants; keep inner fields private.
• Use PhantomData for compile-time variance or lifetime markers without runtime overhead.
• Seal traits when you need a closed set of implementations to maintain invariants.

Example use cases

• Wrap strings as validated Email or Username newtypes that validate at creation.
• Implement Connection<State> to allow only connect/authenticate transitions at compile time.
• Create a Builder for complex structs that prevents construction until required fields are set.
• Use marker traits or ZSTs to indicate capabilities like Validated or Secure without runtime cost.
• Seal trait implementations to ensure only internal modules can create trusted instances.