Skip to content

Section 21: Numeric Types, Precision, and Arithmetic Semantics

TECHSPEC-21 — Section 21 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Numeric Philosophy

Numeric behavior must be predictable, precise, and consistent across execution environments.

The language must not silently accept overflow, lose precision, or rely on the default arithmetic behavior of its compilation target.

Every numeric operation must have defined semantics.

2. Integer Type

Integer represents signed 64-bit whole numbers.

Range:

  • Minimum: -9,223,372,036,854,775,808
  • Maximum: 9,223,372,036,854,775,807

Rules: - Integer operations must use checked arithmetic. - Overflow must produce an explicit arithmetic failure. - Underflow must produce an explicit arithmetic failure. - Integer division must have defined rounding behavior. - Division by zero must produce an explicit arithmetic failure. - Implicit conversion to or from another numeric type is prohibited.

The compiler must not silently wrap overflowing values.

3. Decimal Type

Decimal represents base-10 decimal numbers.

The initial implementation will use decimal128-compatible arithmetic:

  • 34 significant decimal digits.
  • Defined decimal exponent range.
  • Round-to-nearest, ties-to-even as the default rounding mode.
  • Explicit handling of overflow, underflow, and division by zero.

Rules: - Decimal calculations must not silently fall back to binary floating-point arithmetic. - Decimal operations must follow the language's defined precision and rounding rules. - Inexact results must be detectable. - Rounding must not occur invisibly when a more precise result is required. - Explicit rounding operations must identify their rounding mode. - Decimal values must have consistent behavior across supported compilation targets.

4. Numeric Conversions

Conversions between numeric types must be explicit.

Examples:

LET count: Integer = 10
LET price: Decimal = CONVERT<Decimal>(count)

Rules: - Conversions must identify the source and destination types. - Conversions that can lose information must be distinguishable from exact conversions. - Conversions that can fail must return an explicit failure. - Narrowing conversions must check range limits. - Decimal-to-integer conversion must specify its rounding behavior. - The compiler must reject ambiguous numeric conversions.

5. Arithmetic Operators

The initial language supports:

  • Addition: +
  • Subtraction: -
  • Multiplication: *
  • Division: /
  • Remainder: %
  • Negation: -

Rules: - Operators must define behavior for each supported numeric type. - Mixed-type arithmetic requires explicit conversion. - Operator precedence must be formally specified. - Division by zero must never produce an unreported result. - Overflow and underflow must be detected. - Remainder behavior for negative operands must be explicitly defined. - Arithmetic failures must remain visible to the caller.

6. Comparison and Equality

Numeric comparison must have consistent semantics.

Supported comparisons:

  • Equal: ==
  • Not equal: !=
  • Less than: <
  • Greater than: >
  • Less than or equal: <=
  • Greater than or equal: >=

Rules: - Comparisons require compatible numeric types. - Equality must not silently apply approximate comparisons. - Decimal comparisons must use their defined decimal values. - Numeric conversions must not occur implicitly during comparison. - The language must not treat two different numeric representations as equal merely because they appear similar when displayed.

7. Literal Definitions

Numeric literals must have unambiguous syntax.

Examples:

LET quantity: Integer = 250
LET price: Decimal = 19.99
LET taxRate: Decimal = 0.0825

Rules: - Integer literals must fit within the Integer range. - Decimal literals must follow the defined decimal format. - Invalid numeric literals must be rejected during compilation. - Literal type inference must follow deterministic rules. - Scientific notation must have explicitly defined syntax and behavior before implementation.

8. Arithmetic Failures

Arithmetic operations can fail during execution.

The initial language must distinguish: - Integer overflow. - Integer underflow. - Decimal overflow. - Decimal underflow. - Division by zero. - Invalid numeric conversion. - Inexact arithmetic where exactness is required.

Rules: - Arithmetic failures must not silently produce SUCCESS. - Functions must account for possible arithmetic failures. - Failure propagation must preserve the original cause. - Operations requiring exact results must reject unintended rounding. - Runtime arithmetic behavior must match the language specification.

9. Compiler and Runtime Responsibilities

The compiler and runtime must: - Enforce numeric type rules. - Detect invalid numeric literals. - Enforce conversion requirements. - Generate checked integer arithmetic. - Preserve decimal precision. - Apply defined rounding rules. - Detect arithmetic failures. - Produce precise diagnostics. - Ensure generated Python does not introduce different numeric semantics.

10. Design Goal

AI agents must be able to reason about numeric operations without guessing about precision, overflow, conversion, or rounding.

The same source program must follow the same defined arithmetic rules regardless of the compilation target.

Source file: TECHSPEC-21.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.