ADR-0006: Numeric Semantics
Status: accepted
Date: 2026-07-25
Context
P1 branch mix combines integers and binary64 values. C/C++ undefined signed
overflow and fast-math could create false parity or performance results.
Current surface Num also hides the runtime distinction between small integers
and floats.
Options considered
| Option | Benefit | Cost |
|---|---|---|
| Host-language behavior | Fast to implement | Platform drift and possible UB |
| One global checked mode | Safe | Prevents explicit high-performance modes |
| Explicit operation modes | Precise and optimizable | More Core primitives |
Decision
Core separates I64 and F64.
Integer arithmetic names its mode: checked, two’s-complement wrapping, or saturating. There is no undefined overflow and no ambiguous default Core opcode.
F64 uses strict IEEE-754 binary64, left-to-right evaluation, and no reassociate, contraction, reciprocal approximation, or fast-math by default. NaN payload is not observable in Core-N0 v0.1.
Rationale
- Baselines can implement exactly the same contract.
- Proof-backed range facts can remove checked-overflow cost safely.
- Relaxed arithmetic can be introduced explicitly instead of leaking through compiler flags.
Trade-offs
- Strict math may initially trail unsafe or fast-math baselines.
- Surface elaboration must select and expose integer modes.
Consequences
Every benchmark artifact hashes the numeric contract and rejects mismatched baseline flags.
Revisit trigger
Add relaxed vector/numeric modes only with a distinct observable contract, syntax/policy, parity suite, and fair matching baselines.