Rule	Summary
Discriminated unions	Model variants with a `kind` literal discriminant so impossible states can't be represented. No optional-field bags.
Branded types	Brand primitives with `& { readonly __brand: "X" }` so they can't be mixed up. Validate once at the boundary. A brand comes from a verifying type guard (`input is AgentId`), never from `as`.
Constructive modeling	Build the shape so the illegal value can't be constructed. `[T, ...T[]]` for non-empty, `[T, T][]` for even length, `start` plus `duration` for a range. Not a runtime guard, not a wish for refinement types.
Simplest total type	Keep `T[]` while every operation on it stays total. Strengthen to `NonEmpty<T>` only where the loose type forces `!`, a cast, or a "should never happen" throw.
`??` for defaults	Use `??`, not `\|\|`, to fill a default (empty array, object, number, string). `\|\|` also replaces `0`, `""`, and `false`. Use `\|\|` only when those falsy values are intentionally treated as missing.
`unknown` over `any`	External data is `unknown`.
Schemas before guards	Reuse the repository's runtime schema library and existing schemas before writing property-by-property guards. Infer types from schemas. Do not add a schema dependency for one guard.
No `as` casts	Every `as` is a runtime crash waiting. Cast only after validation.
Narrowing hierarchy	Discriminant switch > `in` operator > `typeof`/`instanceof` > user-defined type guard > `as`.
Type guards	Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`.
Exhaustiveness	Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added.
`satisfies` over `as`	Validates the value without widening literal types.
Boundary validation	Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. If `$principle-boundary-discipline` is available, apply it; otherwise validate once at the boundary and trust the parsed type inside.
Schema-derived types	Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface.
Object args	Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers).
Real tests	Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally.
Structured telemetry	Prefer structured logger diagnostics with enough context to debug from an id. No `console.log` in shipped code.

Examples: references/patterns.md.

typescript-best-practices

TypeScript best practices