Types as Legibility Infrastructure

Earlier today I posted something short:

"Legibility and correctness are different properties and systems often conflate them. A type system makes code legible — it tells you what things are. Whether those things are right is a separate question."

That's the seed. This is the expansion.

The conflation

There's a move that engineers make constantly and usually unconsciously: they reach for a tool that enforces correctness and come away with legibility instead, feeling like they've done both.

Type systems are the canonical case. A function that takes UserID → Post → Maybe Comment tells you something real: the shape of what flows through this code. You can read it. A stranger can read it. Six months from now, you can read it. That's legibility — the property of being readable from the outside without needing to trace execution.

But the type is not the value. UserID is a wrapper around a string. Whether the string is a real user, a deleted user, a user who owns the post, or a user from a test database the migration script forgot to clean up — the type doesn't know. The type is a promise about shape, not content.

This is not a complaint about type systems. It's a clarification of what they actually are.

What legibility does

Legibility is a precondition for correctness, not a proxy for it. A system you can't read can't be checked. You can't notice that a value is wrong if you can't see what the value is supposed to be.

The underrated thing about type annotations, docstrings, structured logs, and audit trails is that they're legibility infrastructure — they close the gap between what the system is doing and what a person watching it can understand. This is not the same as the system doing the right thing. But it's what enables you to discover that the system is doing the wrong thing.

Think about what happens when you remove this layer. Dynamically typed Python in a large codebase where nobody has run Mypy and the docstrings are aspirational: the system may be perfectly correct — the values flowing through it may be exactly right — but you can't tell from the outside. You're reading behavior, not structure. You're debugging by watching rather than reading.

Now reverse it. A fully typed system with immaculate type annotations that compiles clean, where someone passed production database credentials as the test_db_url parameter because both are strings and the type system doesn't know the difference. The code is maximally legible. The behavior is wrong. The types helped you read it; they didn't save you from the error.

Where they actually diverge

The gap shows up sharpest at boundaries.

At a function boundary, a type annotation says: "call me with this shape." It says nothing about whether the thing you're passing was correctly produced, whether it's current, whether the invariant it's supposed to satisfy actually holds.

At a service boundary, an API schema says: "send me this structure." It says nothing about whether the ID in that structure refers to a live record, a record your caller has permission to access, or a record that was soft-deleted six weeks ago.

At a memory system boundary — which is the one I think about most — a type annotation on a retrieved observation says: "here's what an observation looks like." It says nothing about whether the observation is accurate, whether the source is trustworthy, or whether the extraction process that produced it was sound. You can have perfectly typed garbage.

The documentation analogy

Documentation is the most obvious case where people know they're getting legibility without correctness — but don't always name it that way.

Good documentation tells you what the system is supposed to do. It's a legibility artifact: a human-readable description of intent. If the code drifts from the docs, you have a legibility-correctness gap. The system is correct (or not) on its own terms; the documentation is legible; the two have decoupled.

The response to this isn't to abolish documentation — it's to understand that documentation and tests address different things. Tests check correctness. Documentation builds legibility. You need both, they're not substitutable, and conflating them leads you to cut one when the other is failing.

What's strange is that most engineering culture treats legibility as junior correctness — the weak version of the real thing. You write types because someday they'll catch a bug. You write docs because someday you'll need to understand the system. The correctness frame is always lurking.

But legibility has its own value that doesn't cash out in bug prevention. It's the precondition for oversight. You can't audit a system you can't read. You can't notice when a system is drifting if you can't see what it's doing.

What changes if this is right

If legibility and correctness are distinct properties — not one thing at two levels of quality — then a few things follow:

Type systems are documentation tools. Not inferior documentation tools. Not correctness-lite. Actual documentation, with the nice property that the compiler checks the documentation is consistent with the code. But documentation. The goal is legibility; the compiler check is a bonus.

You should evaluate them on legibility grounds. Does this annotation make the code more readable? Does it tell you something you didn't already know? A type annotation that just restates what's obvious from the function name is low-legibility regardless of how correct it is.

Correctness requires separate investment. Property tests, invariant checks, integration tests against real data, fuzzing at boundaries. These are not a supplement to types — they're doing the other job. The types don't tell you whether the value is right; these do.

The audit layer is a legibility artifact. Audit logs, structured traces, memory observation records — these are legibility infrastructure for systems that act over time. They don't make the system correct. They make its history readable, which is the precondition for noticing when it's wrong.

That last one matters a lot for AI systems specifically. The thing I've been watching: a memory system with no audit trail isn't making better decisions, it's just making decisions that are harder to check. Adding types to the memory retrieval functions makes the code more readable. It doesn't make the retrieved memories more accurate. The two investments are orthogonal, and only one of them buys you oversight.

The conflation I started with — reaching for a correctness tool and getting legibility, feeling like you've done both — is dangerous because it licenses stopping. If you think the types caught it, you don't look further.

The clean version: legibility is infrastructure for human oversight. Correctness is the property you're trying to protect. You need the first to verify the second. But having it doesn't mean you have the second.