ProjekinAja. Software Engineering Stage 2 · Craft Lesson 2.5
● Stage 2 · Lesson 2.5

Types and Invariants: Making Illegal States Unrepresentable

Type hints as machine-checked documentation, parsing over validating, and modeling states so the wrong ones cannot exist.

⏱ ~20 min read 🧠 Type design 🛡 Invariant modeling

🎯 By the end you'll understand

Why types are a design tool — not bureaucracy — and how enums beat strings, dataclasses beat dicts, and smart constructors enforce invariants at the boundary. You'll see parse-don't-validate as a philosophy, model TraceLab's Run lifecycle as a typed state machine, and count exactly how many illegal-but-representable states each modeling choice permits — making sloppiness quantifiable.

KEY INSIGHTThe type system is your free collaborator

Every runtime error that could have been a type error is a test you forgot to write and a bug you will debug at 2 am.

Here is a real pattern from experiment-tracking code. A Run is stored as a dict with a "status" key. Somewhere upstream, a typo produces run["status"] = "compelted". Everything downstream that checks if run["status"] == "completed" silently falls through. The run is logged. The aggregation query misses it. Your RL agent reports 12% better reward than it actually got.

🔑 Hold onto this

A type is a set of values plus the operations that are valid over them. When you design a type well, the values that should be impossible simply do not exist in the set. A Python str can hold "compelted"; a Python enum with three members cannot. The bug above is not caught by the type system because the type was chosen wrong — not because types can't catch it. Using the type system as a design tool means asking: "What is the smallest type whose members are all valid?" at every modeling decision.

CORE CONCEPTTypes as design tools: four moves

Python's type system is opt-in and gradual — you can add annotations anywhere without breaking anything, and a type checker like mypy or pyright runs separately from the interpreter. That makes it easy to ignore. Here is why ignoring it costs more than you think.

Move 1: Enums over strings

Strings are the universe of all Unicode sequences. An experiment status is one of three things. Using a string for experiment status means the type of "status" admits effectively unbounded values — the cardinality is astronomical compared to a validated type — when three were intended. An enum admits exactly three.

status_comparison.pybefore / after
# Before — a string "type" that is actually untyped
run["status"] = "compelted"     # no error, ever

# After — an enum whose members are the entire valid domain
from enum import Enum

class RunStatus(Enum):
    QUEUED    = "queued"
    RUNNING   = "running"
    COMPLETED = "completed"
    FAILED    = "failed"

RunStatus("compelted")           # → ValueError at the boundary, immediately
status = RunStatus.COMPELTED     # → AttributeError from mypy AND at runtime

Enums also make exhaustiveness checking possible: a match statement (Python 3.10+) over a RunStatus can be statically verified to cover all cases. A match over a string cannot.

Move 2: Dataclasses over dicts

A dict is a runtime-checked bag of key/value pairs. A dataclass is a statically-typed record with named, typed fields. The difference is not syntactic sugar — it is the difference between "this key might be present" and "this field always exists and is this type."

run_model.pydict vs dataclass
# Before — a dict where anything goes
run = {"id": "exp-001", "loss": 0.42}
run["lsos"] = 0.41              # typo; old value survives unnoticed

# After — a dataclass with typed, named fields
from dataclasses import dataclass, field
from typing import Optional

@dataclass
class Run:
    id:         str
    status:     RunStatus
    loss:       Optional[float] = None
    started_at: Optional[float] = None  # Unix timestamp
    ended_at:   Optional[float] = None

run = Run(id="exp-001", status=RunStatus.QUEUED)
run.lsos = 0.41                  # → AttributeError (frozen=True makes it louder)

Move 3: Smart constructors

A smart constructor is a class method or function that enforces invariants before creating an object — so a valid object can never be constructed in an invalid state. The goal: make the invalid state physically impossible to represent, not just "checked by convention."

smart_constructor.pyclassmethod pattern
@dataclass(frozen=True)
class RunId:
    value: str

    @classmethod
    def parse(cls, raw: str) -> "RunId":
        raw = raw.strip()
        if not raw:
            raise ValueError("RunId cannot be empty")
        if not raw.replace("-", "").replace("_", "").isalnum():
            raise ValueError(f"Invalid RunId: {raw!r}")
        return cls(raw)

# Every RunId in the system passed through .parse() — so every RunId is valid
run_id = RunId.parse("exp-001")  # ok
run_id = RunId.parse("  "  )   # → ValueError, immediately, at the boundary

Move 4: Optional means "might not be there" — not "probably is there"

This is where real outages live. An Optional[float] timestamp that "should never be None at this point" is an assertion waiting to fail. The type system has already told you the truth: it can be None. When you ignore that, you are betting production stability on an invariant your model cannot enforce.

⚠ The timestamp that "should never be None"

Pattern seen in production: a Run has started_at: Optional[float] and ended_at: Optional[float]. After weeks in production, a metric dashboard divides ended_at - started_at without checking. A run reaches the dashboard in QUEUED state (bug elsewhere). None - None raises TypeError. The dashboard 500s for all users. The fix is not "add a None check there." The fix is a type that physically prevents a QUEUED run from having a duration computed — which requires modeling the lifecycle.

CORE CONCEPTParse, don't validate

This principle, articulated clearly by Alexis King (blog post "Parse, don't validate," 2019), distinguishes two patterns that look similar but have fundamentally different failure modes:

PatternWhat it doesProblem
Validate Check a str is valid, return bool, use the str downstream as a str The validation result is not attached to the value. Future call sites must re-validate — or forget to.
Parse Check a str is valid, return a new type that only exists if valid Proof of validity is encoded in the type. Downstream code receives a RunId, not a str.
parse_vs_validate.pythe concrete difference
# ── Validate: proof evaporates at the function boundary ──
def is_valid_run_id(s: str) -> bool:
    return bool(s) and s.replace("-", "").replace("_", "").isalnum()

def store_run(run_id: str, data: dict) -> None:
    if not is_valid_run_id(run_id):        # have to validate again
        raise ValueError("bad id")
    # … do work …

# ── Parse: the type carries the proof ──
def store_run(run_id: RunId, data: dict) -> None:
    # RunId.parse() already ran. If we have a RunId, it's valid. Period.
    # No re-validation. No way to pass in an unvalidated string.
    pass

The boundary principle follows naturally: parse at the edges, trust in the middle. Validate (and convert) untrusted input at the moment it enters your system — CLI args, HTTP bodies, CSV rows, environment variables. Once inside, only typed values travel. A str is never a RunId inside your package; it becomes one at the boundary or it raises immediately.

SEE ITInvariant builder: count the illegal states

The question that makes sloppiness quantifiable: how many illegal-but-representable states does each design permit? Select a modeling approach, then fire deterministic event sequences at both implementations and watch which illegal states get admitted. Tighten the model and watch the count collapse.

⚙ Interactive · Invariant builder — TraceLab Run lifecycle

Two implementations of Run receive the same event sequence. The invalid-state counter counts how many of those events land in a state that should be impossible. Tighten the model on the right to collapse the count.

dict-of-strings
typed + Optional timestamps
—
illegal states admitted
dict-of-strings
—
illegal states admitted
typed + Optional
—
states eliminated
by your design choice
Event log

Choose a model and an event sequence, then fire it.

The key observation: the dict model never rejects anything — illegal status strings, duration computations on a queued run, transitions from completed back to running — all pass silently. The "typed + Optional timestamps" model catches bad status strings and typos, but still admits duration computation on a run that has no ended_at. Only the state machine model makes that operation physically impossible — there is no ended_at field on a QueuedRun to dereference.

HOW IT WORKSModeling a lifecycle as a state machine

The breakthrough is structural: instead of one Run class with optional fields for everything, you model each lifecycle state as a separate type that only carries the fields that exist in that state.

QueuedRun id, queued_at RunningRun id, queued_at, started_at .start() CompletedRun id, queued_at, started_at, ended_at, metrics FailedRun id, queued_at, started_at, ended_at, error .complete() .fail()
Each lifecycle state is a distinct type. A QueuedRun has no started_at to dereference. A CompletedRun always has ended_at — it is a required field, not an optional one. Illegal transitions don't need to be checked; they don't exist.
run_states.pystate machine as types
from dataclasses import dataclass
from typing import Union
import time

@dataclass(frozen=True)
class QueuedRun:
    id:         RunId
    queued_at:  float           # always present — not Optional

@dataclass(frozen=True)
class RunningRun:
    id:         RunId
    queued_at:  float
    started_at: float           # always present once running

    def complete(self, metrics: dict[str, float]) -> "CompletedRun":
        return CompletedRun(
            id=self.id, queued_at=self.queued_at,
            started_at=self.started_at,
            ended_at=time.time(), metrics=metrics
        )

    def fail(self, error: str) -> "FailedRun":
        return FailedRun(
            id=self.id, queued_at=self.queued_at,
            started_at=self.started_at,
            ended_at=time.time(), error=error
        )

@dataclass(frozen=True)
class CompletedRun:
    id:         RunId
    queued_at:  float
    started_at: float
    ended_at:   float           # required — no Optional, no None-check in callers
    metrics:    dict[str, float]

    def duration(self) -> float:
        return self.ended_at - self.started_at  # can never fail

@dataclass(frozen=True)
class FailedRun:
    id:         RunId
    queued_at:  float
    started_at: float
    ended_at:   float
    error:      str

# The union type used wherever "any run state" is needed
AnyRun = Union[QueuedRun, RunningRun, CompletedRun, FailedRun]

Notice what you can no longer write: run.duration() where run is a QueuedRun. The method does not exist. run.ended_at where run is a QueuedRun. The field does not exist. The mypy error is the bug report — before the code runs. The runtime error would have been the production alert at 2 am.

The frozen=True on the dataclasses is also load-bearing: it prevents mutation, which means a QueuedRun cannot silently transform into something else mid-flight. State transitions produce a new object of a different type — the old one is unchanged and the transition is explicit.

TRACELABTyping the TraceLab v1 Run model

TraceLab v0 stored runs as CSV rows — flat strings, no types, no lifecycle enforcement. Every field was a string, including the timestamp. TraceLab v1 is where this changes. The tracelab/models.py module becomes the type boundary: untrusted inputs (CLI args, CSV rows from disk) get parsed here and converted to typed objects; everything downstream trusts them.

src/tracelab/models.pyv1 boundary module
# The type boundary for TraceLab v1.
# Untrusted data enters here and is converted to typed objects.
# Everything internal to the package deals in these types only.

from __future__ import annotations
from dataclasses import dataclass, field
from enum import Enum
from typing import Union
import re, time

class RunId:
    """A validated, immutable run identifier."""
    __slots__ = ("value",)
    _RE = re.compile(r"^[\w][\w\-]{0,63}$")

    def __init__(self, value: str) -> None:
        if not self._RE.fullmatch(value):
            raise ValueError(f"Invalid RunId {value!r}: must be 1-64 word chars or hyphens")
        object.__setattr__(self, "value", value)

    def __setattr__(self, *_: object) -> None:
        raise AttributeError("RunId is immutable")

    def __repr__(self) -> str:
        return f"RunId({self.value!r})"

    def __eq__(self, other: object) -> bool:
        return isinstance(other, RunId) and self.value == other.value

    def __hash__(self) -> int:
        return hash(self.value)

# State-per-type lifecycle — see lesson 2.5
@dataclass(frozen=True)
class QueuedRun:
    id:        RunId
    queued_at: float = field(default_factory=time.time)

@dataclass(frozen=True)
class RunningRun:
    id:         RunId
    queued_at:  float
    started_at: float = field(default_factory=time.time)

    def complete(self, metrics: dict[str, float]) -> CompletedRun:
        return CompletedRun(self.id, self.queued_at, self.started_at, time.time(), metrics)

    def fail(self, error: str) -> FailedRun:
        return FailedRun(self.id, self.queued_at, self.started_at, time.time(), error)

@dataclass(frozen=True)
class CompletedRun:
    id:         RunId
    queued_at:  float
    started_at: float
    ended_at:   float
    metrics:    dict[str, float]

    def duration(self) -> float:
        return self.ended_at - self.started_at

@dataclass(frozen=True)
class FailedRun:
    id:         RunId
    queued_at:  float
    started_at: float
    ended_at:   float
    error:      str

AnyRun = Union[QueuedRun, RunningRun, CompletedRun, FailedRun]

The debt this repays: TraceLab v0's runs were strings from end to end — log_run(values) accepted any list, stored anything, retrieved strings only. Now the lifecycle is a contract in the type system. tracelab log exp-001 loss=0.42 at the CLI calls RunId("exp-001") at the entry point — either it validates and creates a typed object, or it raises with a clear message before touching the store. The store never sees an invalid id.

💡 mypy + pyright give you free code review

Add mypy src/ to your CI pipeline (or run pyright in VS Code continuously). The type checker finds cases where you've passed a QueuedRun to a function that expects a CompletedRun — without running a single test. That is not free testing; it is the type system eliminating an entire class of bug structurally. The tests you do write then focus on behavior, not "did I pass the right type."

WEAKNESSWhere this bites

✗ Over-engineering small utilities

Typed state machines with four dataclasses are right for TraceLab's core domain model. They are wrong for a 30-line script that runs once. The cost of the state machine is indirection and more code to read. Senior engineers fight about where the line is — "this will grow" vs "you aren't gonna need it." The honest heuristic: if the invariant will be relied upon across call sites you don't control, type-encode it. If it lives inside one function, a comment and an assert are fine.

✗ Type annotations as decoration rather than design

Adding -> None and str annotations everywhere while leaving every domain concept as a raw string or dict is compliance theater. The value is in the domain model — RunId instead of str, QueuedRun instead of dict. If mypy passes but your types are all str | dict | Any, you have typed annotations on untyped semantics. The checker is satisfied; the bugs are not.

✗ Forgetting the serialization boundary

A common mistake: you have a beautiful typed model internally, but when you serialize a CompletedRun to JSON and deserialize it later, you get back a dict. If deserialization produces raw dicts, your entire type discipline collapses at the store boundary. Parse-don't-validate applies at every I/O boundary — disk, network, database. Libraries like pydantic (validation on model construction) or cattrs (structuring/unstructuring to/from primitives) solve this explicitly; choosing neither and hoping is the third common failure.

KEY INSIGHTHow this connects

  • Code Is Read 10× (2.1) — well-typed code documents itself: def start(run: QueuedRun) -> RunningRun tells the reader more than any comment. The typing discipline from this lesson is the structural companion to the readability discipline there.
  • Errors Are Part of the API (2.4) — parse-don't-validate produces values or raises immediately. That is the error design from 2.4 applied at the type level: errors surface at the boundary, not silently propagated as None or an invalid string.
  • Testing I: What Tests Are Actually For (2.6) — types reduce the number of tests you need by eliminating whole categories of invalid input from the domain. Knowing which bugs the type system catches for free helps you write tests that focus on behavior, not plumbing.

The principle this lesson establishes — model the domain so that invalid states have no representation — runs through the rest of the course. It appears in database schema design (Stage 4), API contracts (Stage 3), and code review (Stage 2.9). A codebase that makes invariants structural is one that survives handoff, refactoring, and AI-generated patches with less ceremony.

GLOSSARYKey terms introduced

Type
A set of values plus the operations valid over them. Choosing a type means choosing which values can exist, not just which operations are named.
Invariant
A property that is always true of a value or object throughout its life. A RunId is always non-empty and alphanumeric. A CompletedRun always has an ended_at timestamp.
Smart constructor
A class method or factory function that enforces invariants before creating an object, so any instance that exists is guaranteed valid.
Parse, don't validate
The discipline of converting untrusted input into a typed value at the boundary, so that downstream code receives proof of validity in the form of the type itself — not a boolean or a checked string.
State machine (as types)
A design where each lifecycle state is a distinct type carrying only the fields that exist in that state, so illegal transitions and field accesses are statically impossible.
Enum
A type whose members are an explicit, exhaustive, fixed set of values. Enums make invalid members unrepresentable at the type level and enable exhaustiveness checking.
Dataclass
A Python construct (@dataclass) that defines a class with typed, named fields and auto-generates __init__, __repr__, and optionally __eq__/__hash__. With frozen=True, instances are immutable.
Illegal-but-representable state
A value that your language allows but your domain forbids. "compelted" is representable as a str but illegal as a status; None is representable as an Optional[float] duration but illegal for a completed run. Design work is eliminating these.

ACTIVE RECALLCheck your understanding

Answer in your own words first, then reveal.

1Why is an Optional[float] timestamp that "should never be None" a design problem, not just a missing check?›

The type has already told you the truth: None is a valid value for that field. Every call site that uses the timestamp must defensively check for None — or bet on the invariant holding. When something breaks the invariant (a race condition, a bug, an unexpected code path), the crash happens at the call site, not at the point of creation. The fix is to model the state machine so a run that has no ended_at is a different type entirely — one that lacks the field, making the None-check impossible and the invariant structural.

2What is the difference between validating input and parsing it?›

Validation checks a raw value and returns a boolean (or raises). The raw value is still a str downstream, so every call site must re-validate or trust that someone else did. Parsing converts the raw value into a new type that only exists if valid — a RunId, not a str. Downstream code receives proof of validity in the type itself. No re-validation. No way to accidentally pass an unvalidated string. Validation evaporates at function boundaries; parsing encodes the invariant permanently.

3Why does a state machine encoded as distinct types eliminate an entire category of bugs that a single dataclass with optional fields cannot?›

A single dataclass with optional fields makes every field potentially absent — you rely on discipline and runtime checks to ensure "in QUEUED state, ended_at is None." Those checks are invisible to the type system and can be bypassed. With distinct types, a QueuedRun literally does not have an ended_at attribute — there is nothing to dereference. An illegal transition from QUEUED to COMPLETED without passing through RUNNING means calling .start() first, which returns a RunningRun. The type checker enforces the protocol; you cannot skip it.

4A colleague argues that adding a typed state machine to TraceLab is over-engineering. What is the honest response?›

They might be right for a specific scope, and the critique deserves engagement. The honest question is: will this invariant be relied upon across call sites you don't control? If TraceLab stays a personal script, a comment and an assert are probably fine. If it becomes a package used by multiple researchers — which is the Stage 2 milestone — then the answer is yes: the typed model documents the contract, catches violations statically, and survives people who haven't read the comments. The cost is more code to read; the benefit is invariant enforcement for free at every future call site. That tradeoff favors the type machine for shared infrastructure.

Next: what tests actually prove — and what they silently lie about →