Wrap primitives when the wrapper changes correctness, not when it only signals virtue.
Wrap When
-
The value has a domain name and invariant.
-
Two values of the same primitive type can be confused.
-
Validation is repeated or easy to forget.
-
Behavior naturally belongs with the value.
-
Invalid states cause meaningful business risk.
Do Not Wrap Yet When
- The value has no behavior or invariant.
-
The wrapper would only forward primitive operations.
-
The type is local, temporary, or purely technical.
-
The team would pay high ceremony for little safety.
Workflow
-
List candidate primitives and their risks.
-
Score invariant strength, misuse risk, behavior, reuse, and migration cost.
-
Wrap the highest-value candidates first.
-
Keep construction explicit and error reporting useful.
Detailed Reference
For non-trivial implementation, review, or refactoring work, read references/details.md before giving final guidance. It contains the detailed rules, examples, smells, and migration notes that do not belong in the short invocation body.
Output
Return a wrap/keep table with rationale and example APIs for the chosen wrappers.