j5ik2o When To Wrap Primitives
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.