fix-types

Fix Types

Make invalid states unrepresentable. All possible types and states should be defined upfront ahead of time. Every bare primitive that carries domain meaning is a bug waiting for a call site to swap two arguments of the same type. The compiler/type-checker is free; runtime debugging is not!

1. Newtypes / branded types over bare primitives

If a value means different things in different parameters of the same function, wrap each in a distinct type.

Rust:

struct AccountId(u64);
struct Cents(u64);
fn transfer(from: AccountId, to: AccountId, amount: Cents);

TypeScript:

type AccountId = string & { readonly __brand: "AccountId" };
type Cents = number & { readonly __brand: "Cents" };
function transfer(from: AccountId, to: AccountId, amount: Cents): void;

Python:

from typing import NewType
AccountId = NewType("AccountId", int)
Cents = NewType("Cents", int)
def transfer(from_: AccountId, to: AccountId, amount: Cents) -> None: ...

Go:

type AccountId uint64
type Cents uint64
func Transfer(from, to AccountId, amount Cents) error

Apply when a bare primitive appears in 3+ function signatures with different semantics. Common candidates: identifiers, indices, offsets, sizes, timestamps, currency amounts, ports, sequence numbers.

2. Checked casts at trust boundaries

When converting between signed/unsigned or narrowing width, validate at the boundary where untrusted data enters. Silent truncation or wraparound is a corruption vector.

// Bad: silent wraparound on corrupt input.
let id = row.get::<_, i64>(0)? as u64;

// Good: fails loud on negative.
let id = u64::try_from(raw).map_err(|_| Error::Corrupt(raw))?;

# Bad: silently wraps on overflow.
port = int(raw_value) & 0xFFFF

# Good: explicit bounds check.
port = int(raw_value)
if not (0 <= port <= 65535):
    raise ValueError(f"port out of range: {port}")

// Bad: silent truncation.
port := uint16(rawPort)

// Good: bounds check.
if rawPort < 0 || rawPort > math.MaxUint16 {
    return fmt.Errorf("port out of range: %d", rawPort)
}