nw-type-level-design
Design or review evidence-preserving APIs that model invalid states, state transitions, capabilities, and trusted construction proportionately to the target language.
SKILL.mdnWave/skills/nw-type-level-design/SKILL.md
GitHubType-Level Design and Evidence-Preserving APIs
Use this skill when an API must represent valid states, excluded states, a phase transition, a capability, or evidence obtained at a trust boundary. Choose the smallest representation that makes ordinary misuse difficult and keeps the accepted call site clear.
Knowledge basis for the advanced Haskell material: Sandy Maguire, Thinking with Types.
Trigger
Use when a design or implementation needs one of these:
- an invalid call or state must be rejected or made hard to construct;
- a sum/product, opaque value, smart constructor, result type, or state/phase API may make the invariant clearer;
- a successful parse, validation, authorization, or transition must carry evidence to the next operation;
- a finite, stable state or capability changes which operations are valid; or
- a proposed generic, phantom, indexed, dependent, GADT, type-family, or singleton technique needs a proportionate design review.
Do not trigger merely because an invariant exists. Keep volatile policy, user-defined schemas, external behavior, time, concurrency, I/O, migration, and untrusted input at their owning runtime boundary.
Core design method
- State the proposition in one sentence: which call or state is excluded, who could otherwise construct it, and what harm follows. Name admitted input, constructor, consumer, and public observation.
- Start with the least powerful representation: a named sum for alternatives, a product/record for required parts, an opaque value with a smart constructor, or a result carrying a reason and validated value. Do not replace domain names with a clever encoding.
- For a phase or capability, name the finite stable states and each permitted transition. Expose operations only through the state or evidence they need: an operation that may only receive validated input takes the validator's evidence type as its parameter. Where the repository runs a checker, re-checking inside the operation instead keeps the rule at runtime but leaves the checker nothing to reject. Do not let clients forge a later phase through a public raw constructor.
- Sketch one ordinary accepted call and one rejected or refused call. The
accepted call must remain more legible than a value-level validation loop.
When implementing, demonstrate both as
nw-certainty-by-constructionstep 5 requires. - State bypasses and residual obligations: deserialization, reflection, casts, database writers, foreign code, process failure, and other systems may remain outside the representation.
- Keep evidence through the boundary. Return a validated value, capability, or explicit outcome rather than a Boolean that discards what the next step needs. A Boolean validator left beside the evidence path returns that evidence instead, or is removed.
Witness granularity. Return evidence at the smallest unit its consumer needs,
retaining independent failures separately until final assembly. A valid
CustomerId can be resolved despite an invalid address; failed ID parsing supplies
no lookup input. Changing an unrelated field's validity must not remove that
witness or its checks. For the mixed composition policy, load nw-fp-principles
§5 when applicable. This partial-aggregate API is application synthesis from Sandy
Maguire, Thinking with Types, Indexed Monads → Definition and Necessary
Machinery; Certainty by Construction, An Exploration of Numbers → Constructing
Evidence—not a need for a generic scheduler on a single check.
Calibrate the guarantee
State the claim at the strength of the matching row of
nw-certainty-by-construction's calibration table, chosen by the checker the
repository actually runs.
State and evidence boundaries
Use a state/phase-indexed API only when the states are small, stable, and central to the product contract, and when a rejected call matters before execution. Otherwise use a closed state value plus an explicit transition or validation result. A representation is successful when clients can see what they possess, which operation they may call, and what failure means without knowing its internal machinery.
For representation-preserving conversion, distinguish representational equality from semantic equality. For normalization or transformation, state the observation and preservation claim before optimizing. For an existential or hidden implementation, preserve only the operations the client genuinely needs through a named eliminator or interface.
Retained identity. Coalescing returns the identity actually retained, not a discarded candidate's ID. Allocate only after retention is decided; ownership names the semantic parent, not its ordinal. Duplicate-contact replay preserves IDs and counters; parent reordering preserves each child's owner. At persisted ingress, enforce unique owned IDs and freshness of future issuance relative to all retained IDs. Apply only within declared semantic equality: equal parameter values do not merge intentionally distinct histories. Exact identity policy is application synthesis from Sandy Maguire, Certainty by Construction, An Exploration of Numbers → Unique Integer Representations; Thinking with Types, Roles → Roles; Indexed Monads → Linear Allocations.
Semantic kind before spelling. Where fields have different meanings, use
their declared field kind or named alternative: only reference slots resolve;
literal text such as R7 stays literal. Under a verbatim command-text contract,
preserve the payload bytes rather than trim, interpolate or dereference them.
Represent file absence and unreadability as distinct load outcomes; only absence
permits an absence default. Reusing a string representation does not make these
kinds interchangeable; a single literal-string API needs no extra variants.
These boundary policies are application synthesis from Sandy Maguire, Thinking
with Types, Constraints and GADTs → GADTs; Roles → Roles—not a shell-safety
guarantee or a prescribed exit-code policy.
Advanced Haskell/GHC
Read advanced Haskell design
only when the target and its compiler range make GADTs, DataKinds, rank-N
types, families, roles, open rows, or singletons a concrete option. Then read
technique selection and
ergonomics and compatibility
before exposing the API. These techniques are optional tools for GHC projects,
not a requirement for other languages.