Type System Discipline

Use GHC to reject impossible states, mismatched semantic values, and unhandled constructors. Prefer defining errors and special cases out of existence over proliferating handlers. This skill guides development of NeoHaskell's framework and language implementation. Public APIs should express useful guarantees without imposing unnecessary type machinery on callers.

• Make illegal states unrepresentable. Use algebraic data types with a constructor for each valid case instead of records with contradictory combinations of fields. For example, data Completion = Open | Done DateTime ties the timestamp to the completed case; a Bool beside a Maybe DateTime permits inconsistent combinations. Put constructor-specific fields on that constructor and handle the cases with pattern matching.
• Types are constructions, not restrictions. Build Haskell types from the values the operation needs instead of starting with a loose shape and scattering checks over it. A non-empty collection is a head plus a rest. Use data constructors or smart constructors to establish the required shape and expose the interface callers need on top.
• Distinguish semantic primitives with newtypes. Use newtype, rather than a type synonym, when values with the same representation must not be interchangeable. The existing StreamId wrapper distinguishes an event stream identifier from arbitrary Text. A newtype does not validate its contents by itself. When a type promises a validated value, ensure its construction and decoding paths establish that invariant before trusting it downstream. Do not assume a derived instance or an exported constructor performs validation.
• Parse external data into internal types. Turn raw Text/Bytes, JSON, CLI arguments, configuration, environment variables, protocol messages, and database rows into the typed model at their boundaries. Use Result error value for an explained failure or Maybe value for absence, according to the contract. Keep parsing pure where possible. The Boundary Discipline principle says where validation belongs.
• Do not bypass GHC's guarantees. Do not use unsafeCoerce, partial pattern matches, undefined, or an error path to silence a type mismatch or pretend an invariant has been proved. Refine the data model, match the constructors, or validate the missing condition. A compiler-checked coerce establishes representational compatibility, not semantic validation. If an unsafe primitive is necessary at an implementation boundary, isolate it and state the invariant and evidence that justify it.
• Make pattern matching exhaustive. Match the constructors of an ADT so GHC can identify affected callers when a constructor is added. Avoid catch-all patterns where a new constructor should force a decision. Incomplete-pattern warnings must fail the build: use -Wincomplete-patterns with -Werror, or -Werror=incomplete-patterns. The current core Cabal configuration already combines -Wall and -Werror; do not weaken that policy to get a change through.
• Derive from the authoritative model. Reuse existing Generic derivation, Template Haskell generators, and typeclass instances instead of maintaining parallel declarations by hand. In NeoHaskell, a Haskell type can own the shape and generate a Schema through ToSchema; preserve that direction when the type is the authority. If an external schema owns the shape, derive the Haskell representation from it instead. See the Encode Lessons in Structure principle.
• Strengthen types where partiality appears, then stop. A partial match, runtime assertion, or "this should never happen" failure can reveal a missing case or precondition. Express the useful guarantee in the input type or handle the case explicitly in the result. An operation that promises a first element needs non-empty input; Array.first and LinkedList.head already return Maybe and can keep ordinary collection inputs. Prefer total functions. If the existing contract handles every case, keep the plain type rather than adding type-level machinery just to describe more facts.