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.
🎯 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.
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.
# 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."
# 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."
@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.
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:
| Pattern | What it does | Problem |
|---|---|---|
| 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. |
# ── 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.
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 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.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.
# 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.
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
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.
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.
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) -> RunningRuntells 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
Noneor 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
RunIdis always non-empty and alphanumeric. ACompletedRunalways has anended_attimestamp. - 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__. Withfrozen=True, instances are immutable. - Illegal-but-representable state
- A value that your language allows but your domain forbids.
"compelted"is representable as astrbut illegal as a status;Noneis representable as anOptional[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.