M05 Type Driven Agent Skill

Type-Driven Design

> Layer 1: Language Mechanics

Core Question

How can the type system prevent invalid states?

Before reaching for runtime checks:

• Can the compiler catch this error?
• Can invalid states be unrepresentable?
• Can the type encode the invariant?

Error → Design Question

| Pattern | Don't Just Say | Ask Instead |

|---------|----------------|-------------|

| Primitive obsession | "It's just a string" | What does this value represent? |

| Boolean flags | "Add an is_valid flag" | Can states be types? |

| Optional everywhere | "Check for None" | Is absence really possible? |

| Validation at runtime | "Return Err if invalid" | Can we validate at construction? |

Thinking Prompt

Before adding runtime validation:

• Can the type encode the constraint?
• Numeric range → bounded types or newtypes
• Valid states → type state pattern
• Semantic meaning → newtype

• When is validation possible?
• At construction → validated newtype
• At state transition → type state
• Only at runtime → Result with clear error

• Who needs to know the invariant?
• Compiler → type-level encoding
• API users → clear type signatures
• Runtime only → documentation

Trace Up ↑

When type design is unclear:

"Need to validate email format"
    ↑ Ask: Is this a domain value object?
    ↑ Check: m09-domain (Email as Value Object)
    ↑ Check: domain-* (validation requirements)

| Situation | Trace To | Question |

|-----------|----------|----------|

| What types to create | m09-domain | What's the domain model? |

| State machine design | m09-domain | What are valid transitions? |

| Marker trait usage | m04-zero-cost | Static or dynamic dispatch? |

Trace Down ↓

From design to implementation:

"Need type-safe wrapper for primitives"
    ↓ Newtype: struct UserId(u64);

"Need compile-time state validation"
    ↓ Type State: Connection<Connected>

"Need to track phantom type parameters"
    ↓ PhantomData: PhantomData<T>

"Need capability markers"
    ↓ Marker Trait: trait Validated {}

"Need gradual construction"
    ↓ Builder: Builder::new().field(x).build()

Quick Reference

| Pattern | Purpose | Example |

|---------|---------|---------|

| Newtype | Type safety | struct UserId(u64); |

| Type State | State machine | Connection<Connected> |

| PhantomData | Variance/lifetime | PhantomData<&'a T> |

| Marker Trait | Capability flag | trait Validated {} |

| Builder | Gradual construction | Builder::new().name("x").build() |

| Sealed Trait | Prevent external impl | mod private { pub trait Sealed {} } |

Pattern Examples

Newtype

struct Email(String);  // Not just any string

impl Email {
    pub fn new(s: &str) -> Result<Self, ValidationError> {
        // Validate once, trust forever
        validate_email(s)?;
        Ok(Self(s.to_string()))
    }
}

Type State

struct Connection<State>(TcpStream, PhantomData<State>);

struct Disconnected;
struct Connected;
struct Authenticated;

impl Connection<Disconnected> {
    fn connect(self) -> Connection<Connected> { ... }
}

impl Connection<Connected> {
    fn authenticate(self) -> Connection<Authenticated> { ... }
}

Decision Guide

| Need | Pattern |

|------|---------|

| Type safety for primitives | Newtype |

| Compile-time state validation | Type State |

| Lifetime/variance markers | PhantomData |

| Capability flags | Marker Trait |

| Gradual construction | Builder |

| Closed set of impls | Sealed Trait |

| Zero-sized type marker | ZST struct |

Anti-Patterns

| Anti-Pattern | Why Bad | Better |

|--------------|---------|--------|

| Boolean flags for states | Runtime errors | Type state |

| String for semantic types | No type safety | Newtype |

| Option for uninitialized | Unclear invariant | Builder |

| Public fields with invariants | Invariant violation | Private + validated new() |

Related Skills

| When | See |

|------|-----|

| Domain modeling | m09-domain |

| Trait design | m04-zero-cost |

| Error handling in constructors | m06-error-handling |

| Anti-patterns | m15-anti-pattern |