principle-type-system-discipline

• SKILL.mdcore · 2,814 bytes

# Type system discipline

Let the type checker refuse impossible states, swapped primitives, and variants nobody handles. Design types so error cases and special cases cannot arise, rather than adding handlers for them.

## When it applies

Designing types, reviewing a function signature, and writing in any statically typed language. In an untyped language, apply the same intent with parse functions and runtime schemas.

## What to do

1. Brand semantic primitives. Values that share a primitive but mean different things get distinct types: a branded intersection in TypeScript, a newtype in Rust or Haskell, a distinct type in Go. `UserId` and `TenantId` are both strings, and a function that takes both in the wrong order is a cross-tenant access bug the compiler could have caught. Validate once at construction and trust the type afterward.
2. Consider data from outside the program untyped until a parser has accepted it. That covers IPC messages, JSON documents, RPC payloads, command-line arguments, config files, environment variables, database rows, and tool-call arguments produced by a model. Each boundary has a parse function that produces the typed model.
3. Derive types from authoritative schemas (protocol buffers, OpenAPI, GraphQL schemas, database migrations, design-token files).
4. Make illegal states unrepresentable. Use a discriminated union in place of an object with optional fields that are only valid in certain combinations.