Type Safety

This project's TypeScript policy. Apply when writing or reviewing TypeScript.

Rule	Summary
No `as` casts	Every `as` is a potential runtime crash. Validate at boundaries, then cast only if earned. Prefer Zod/Valibot over manual validation.
`unknown` over `any`	`any` disables type checking for everything it touches. External data is always `unknown`.
Discriminated unions	Model variants with a shared literal discriminant. No optional-field bags.
Narrowing hierarchy	Prefer: discriminated union switch > `in` operator > typeof/instanceof > type guard > `as`
Type guards	Must actually verify the claim. Name them `isX` or `hasX`. Prefer discriminant narrowing when possible.
Exhaustiveness checks	Always add `default: never` arm to switches over discriminated unions. Use an `absurd()` helper to reduce boilerplate.
`satisfies` over `as`	When verifying a value matches a type without widening, use `satisfies` to preserve literal types.
Impossible states	If a bug requires asking "can this combination happen?" the type is too loose. Tighten it.

Read references/patterns.md for code examples of each rule.

ts-best-practices