# Gameplay Math and Numeric Semantics Domain: VM numeric execution and mathematical intrinsics Function: normative Didactic companion: [Portable math requires a runtime-owned numeric contract](../../../discussion/lessons/DSC-0053-gameplay-math-and-numeric-semantics/LSN-0062-portable-math-requires-a-runtime-owned-numeric-contract.md). ## Ownership and reproducibility The VM owns numeric semantics, implementations, exact intrinsic signatures, constants and virtual cycle costs. With the same cartridge, numeric contract and inputs, supported runtime builds MUST produce identical result bits, faults and cycles. Mathematical error bounds measure deviation from the ideal function; they are never a tolerance between hosts. Float is finite IEEE 754 binary64. Its physical f64 carrier transports bits; guest arithmetic MUST use the canonical software backend. ADD/SUB/MUL/DIV, conversion to Float and sqrt round correctly to the nearest representable value, ties to even. Preserve gradual underflow, subnormals and signed zeros. Underflow to subnormal or signed zero is valid; finite overflow faults. No fast-math, reassociation or implicit multiply-add fusion is allowed. The reference uses fpmath exactly 0.1.1 with soft-float and the dependency resolution in Cargo.lock. The VM adapter supplies the selected rounding, domains, signed zeros, conversions and fault mapping. Private algorithm temporaries are not guest instructions; published vector steps below are canonical binary64 operations. Existing integer wrapping and arithmetic-opcode promotions remain unchanged: Int32/Int64 ADD/SUB/MUL/NEG wrap; MIN/-1 returns MIN; MIN%-1 returns zero. Integer division truncates toward zero and remainder has the dividend sign: -7/3=-2 and -7%3=-1. Integer division/modulo by zero faults. Mixed Float opcode operands convert integers through the software conversion before computing. This does not authorize coercion at Registry or intrinsic boundaries. Numeric Float comparisons use software conversion/comparison; +0 and -0 compare equal. Native acceleration is optional and MUST preserve exact bits, faults and cycles per operation/host. A runtime recognizing old vec2 IDs is not thereby qualified for this numeric contract. ## Public surface and exact catalog The intended consumer surface uses math for Int32/Int64 overloads and mathf for Float functions. Names identify namespaces, not guest types or receivers. A frontend resolves overloads at compile time to an exact identity. Mixed intrinsic carriers require explicit conversion. [INTRINSICS.csv](../../vm-arch/INTRINSICS.csv) is generated from runtime metadata: ID, owner/name/version, ordered ABI layout, parameter names, fixed cost or variable base/attempt/limit model, determinism, guest-allocation and guest-state mutation flags. Math entries use fixed complete costs; stateful random entries publish their variable model separately. [BUILTIN_CONSTANTS.csv](../../vm-arch/BUILTIN_CONSTANTS.csv) publishes constant slots and Float bits. Consumers MUST use these artifacts rather than duplicate ID/cost maps. Math functions are pure and allocate no guest objects; runtime result/scratch reservations remain possible. All scalar entries below have version 1. vec2.dot/length retain version 1 and existing IDs with the behavior and costs specified here. | ID | Exact identity | Ordered signature | Call cycles | | --- | --- | --- | ---: | | 0x3000 | math.i32.min | (a:Int32,b:Int32)->Int32 | 2 | | 0x3001 | math.i32.max | (a:Int32,b:Int32)->Int32 | 2 | | 0x3002 | math.i32.clamp | (value:Int32,min:Int32,max:Int32)->Int32 | 4 | | 0x3003 | math.i32.abs | (value:Int32)->Int32 | 2 | | 0x3004 | math.i64.min | (a:Int64,b:Int64)->Int64 | 2 | | 0x3005 | math.i64.max | (a:Int64,b:Int64)->Int64 | 2 | | 0x3006 | math.i64.clamp | (value:Int64,min:Int64,max:Int64)->Int64 | 4 | | 0x3007 | math.i64.abs | (value:Int64)->Int64 | 2 | | 0x3008 | mathf.min | (a:Float,b:Float)->Float | 2 | | 0x3009 | mathf.max | (a:Float,b:Float)->Float | 2 | | 0x300A | mathf.clamp | (value:Float,min:Float,max:Float)->Float | 4 | | 0x300B | mathf.abs | (value:Float)->Float | 2 | | 0x300C | mathf.floor | (value:Float)->Float | 4 | | 0x300D | mathf.ceil | (value:Float)->Float | 4 | | 0x300E | mathf.trunc | (value:Float)->Float | 4 | | 0x300F | mathf.round | (value:Float)->Float | 4 | | 0x3010 | mathf.sqrt | (value:Float)->Float | 16 | | 0x3011 | mathf.sin | (angle:Float)->Float | 32 | | 0x3012 | mathf.cos | (angle:Float)->Float | 32 | | 0x3013 | mathf.atan2 | (y:Float,x:Float)->Float | 48 | | 0x3014 | math.i32.to_i64 | (value:Int32)->Int64 | 2 | | 0x3015 | math.i64.to_i32 | (value:Int64)->Int32 | 2 | | 0x3016 | math.i32.to_float | (value:Int32)->Float | 2 | | 0x3017 | math.i64.to_float | (value:Int64)->Float | 2 | | 0x3018 | mathf.to_i32 | (value:Float)->Int32 | 2 | | 0x3019 | mathf.to_i64 | (value:Float)->Int64 | 2 | | 0x1000 | vec2.dot | (ax:Float,ay:Float,bx:Float,by:Float)->Float | 10 | | 0x1001 | vec2.length | (x:Float,y:Float)->Float | 40 | There are no identity conversions. Public conversions follow the source carrier: math.to_float(Int32/Int64), math.to_i64(Int32), math.to_i32(Int64), mathf.to_i32(Float), mathf.to_i64(Float). ## Limits, rounding and conversions min/max return the numerical limit. Equal nonzero inputs have identical bits. Equal-sign zeros retain their sign; opposite zeros return -0 for min and +0 for max, in either argument order. Float abs clears the sign bit; integer abs(MIN) faults NUMERIC_RANGE. clamp validates all arguments, requires min<=max numerically, then evaluates min(max(value,min),max) under these zero rules. Opposite zero limits are numerically equal and valid. Invalid limits fault NUMERIC_DOMAIN; do not silently swap or correct them. floor, ceil, trunc and round return Float. For -2.7, the first three yield -3, -2 and -2. round ties to even: 2.5->2, 3.5->4, -2.5->-2. Preserve zero input signs; a nonzero input rounding to zero uses its sign. Float-to-integer conversion checks finitude, truncates toward zero, then checks the exact truncated value against [-2^31,2^31-1] or [-2^63,2^63-1]. MUST NOT saturate or use Float(Int64 MAX) as an inclusive upper bound. Int64-to-Int32 requires range. Int32-to-Int64 is exact. Integer-to-Float uses nearest/ties-to-even; Int64 precision can be lost. Float -0 converts to integer zero. | Expression | Result or fault | | --- | --- | | mathf.to_i32(3.9) / mathf.to_i32(-3.9) | 3 / -3 | | mathf.to_i32(-2147483648.9) | Int32 MIN; the truncated value fits | | mathf.to_i32(2147483648.0) | NUMERIC_RANGE | | mathf.to_i64(-2^63 as Float) | Int64 MIN | | mathf.to_i64(+2^63 as Float) | NUMERIC_RANGE | | math.to_float(Int64 MAX) | Float bits 0x43E0000000000000, equal to +2^63 | | Convert that Float back to Int64 | NUMERIC_RANGE | | math.to_float(Int64 9007199254740993) | 9007199254740992, ties-to-even | ## Angles, constants and signed axes Angles use radians. sin/cos accept every finite binary64 angle, including very large arguments. Controlled argument reduction is part of the reference; x%tau alone is insufficient. Functions act on the supplied binary64 value; sin(pi) is not snapped to zero because binary64 pi approximates π. | Constant | Binary64 bits | | --- | --- | | mathf.pi | 0x400921FB54442D18 | | mathf.tau | 0x401921FB54442D18 | | Internal pi/2 for atan2 axes | 0x3FF921FB54442D18 | pi/tau load through existing constant instructions and their ordinary cost. They are not intrinsic calls or host-computed literals. sqrt(-0)=-0, abs(-0)=+0, sin(+/-0)=+/-0 and cos(+/-0)=1. sqrt of a finite negative nonzero value faults NUMERIC_DOMAIN. atan2 takes y first, x second. All four signed-zero combinations with x=y=0 fault NUMERIC_DOMAIN. Other axes are fixed: | Inputs | Result | | --- | --- | | atan2(+0,x>0) / atan2(-0,x>0) | +0 / -0 | | atan2(+0,x<0) / atan2(-0,x<0) | +pi / -pi | | atan2(y>0,+/-0) | +pi/2 | | atan2(y<0,+/-0) | -pi/2 | ## Vector sequences Validate every carrier and then every Float input before calculating. dot executes p1=ax*bx, p2=ay*by, result=p1+p2. Every step rounds to binary64 and checks range. Intermediate overflow faults even if the ideal final expression could cancel. No FMA or wider accumulator is allowed. length executes this canonical scaled sequence: ax = abs(x); ay = abs(y) m = max(ax, ay); n = min(ax, ay) if m == 0: return +0 r = n / m q = r * r s = 1 + q t = sqrt(s) return m * t Each step rounds independently; underflow in r/q is permitted. Final overflow faults NUMERIC_RANGE. This specifies a sequence, not one rounding of ideal hypot. Both branches cost 40 cycles. | Example | Result or fault | | --- | --- | | length(1e200,0) | 1e200 without squaring 1e200 | | length(binary64 bits 0x0000000000000001,0) | bits 0x0000000000000001 | | length(-0,-0) | +0 | | length(MAX_FINITE,MAX_FINITE) | NUMERIC_RANGE | | dot(MAX_FINITE,MAX_FINITE,2,-2) | NUMERIC_RANGE at the first multiplication | | min(-0,+0) / max(-0,+0) | -0 / +0 | | clamp(-0,+0,1) | +0 | | clamp(0,2,1) / atan2(0,0) / abs(Int32 MIN) | NUMERIC_DOMAIN / NUMERIC_DOMAIN / NUMERIC_RANGE | ## Faults, admission and virtual cycles | Fault | ID | Meaning | | --- | --- | --- | | TRAP_NUMERIC_DOMAIN | 0x00000012 | Finite arguments outside the mathematical domain | | TRAP_NUMERIC_RANGE | 0x00000013 | Finite input whose result/destination cannot be represented | | TRAP_NON_FINITE | 0x00000014 | NaN or infinite input | | TRAP_DIV_ZERO | 0x0000000A | Numerical zero divisor, including either signed Float zero | Use existing TrapInfo interruption and available PC/opcode/source span. Messages identify operation and argument when applicable. Do not panic Rust, coerce invalid inputs to zero or add guest-catchable exceptions. Precedence is structure/height/types, all nonfinite inputs in parameter order, domain/divisor zero, then range/result. NaN/0 faults NON_FINITE; 1/0 DIV_ZERO. Native signature import checks all declared layouts before finitude and refuses invalid values before publishing guest slots. Public native stack import push returns VmFault::Trap(NON_FINITE) for a nonfinite Float and VmFault::ResourceLimit for quota refusal. Current HostReturn producers do not expose a Float result writer. Loading checks declared instruction ranges, including unreachable code: - Unknown/unsupported intrinsic: LOAD_INVALID_CODE/NativeId, function/PC and referenced_id. Runtime TRAP_INVALID_INTRINSIC is a defensive invariant check; an unknown identity has no mathematical attempt cost. - NaN/infinite constant: LOAD_INVALID_FORMAT/NonFiniteValue with section, file offset and constant index. - NaN/infinite PushF64: LOAD_INVALID_CODE/NonFiniteValue with function/PC and available offset context. - Structural decoding/tag/truncation errors retain their categories and precede classifying the corresponding numerical payload. No PBX version/encoding change is introduced. Known mathematical calls admitted by positive budget charge their full cost once before validation, scratch reservations and execution, including type/domain/range/nonfinite/resource failures. No generic extra INTRINSIC cycle or refund. Zero budget does not begin or charge a call; positive budget admits the complete call and can overshoot. Private steps add no guest costs. Argument-producing instructions are charged separately. Unrelated input/color intrinsic costs/accounting and arithmetic opcode costs/accounting remain unchanged. ## Consumer examples and emission These examples document the runtime contract for frontend implementers. Frontend integration is pending: namespace/free-function projection is not an already-delivered PBS parser/lowering feature. No Math guest type, receiver, syscall or duplicate numeric backend is required. | Typed source expression | Required identity/emission | Call cycles | | --- | --- | ---: | | math.min(a,b), both Int32 | Push a,b; INTRINSIC 0x3000 | 2 | | math.clamp(value,min,max), all Int64 | Push value,min,max; INTRINSIC 0x3006 | 4 | | math.to_float(counter), Int64 | Push counter; INTRINSIC 0x3017 | 2 | | mathf.to_i32(position), Float | Push position; INTRINSIC 0x3018 | 2 | | mathf.atan2(y,x), both Float | Push y,x in that order; INTRINSIC 0x3013 | 48 | | mathf.sin(0.0), Float literal | Load +0; INTRINSIC 0x3011; preserve call | 32 | | mathf.pi | Existing constant load, canonical bits; no intrinsic | ordinary load cost | | math.min(a,b), Int32 and Int64 | Require explicit conversion; no exact mixed signature | no call until resolved | For a Float literal position -3.9, explicit conversion can emit: PUSH_F64 f64:0xC00F333333333333 INTRINSIC 0x3018 It returns Int32 -3. The constant load costs 2 and the call costs 2. For direction (y=1,x=0), preserving argument order: PUSH_F64 f64:0x3FF0000000000000 PUSH_F64 f64:0x0000000000000000 INTRINSIC 0x3013 It returns bits 0x3FF921FB54442D18; the two loads plus call cost 52. pi can use PUSH_F64 f64:0x400921FB54442D18 or the constant pool. Mathematical executable expressions MUST retain calls even with literal arguments in the initial consumer contract. Future folding requires exact result/fault/cycle equivalence, not host libm evaluation. ## Qualification and evidence Fundamentals and sqrt require correct rounding; limits/rounding functions require the exact semantic result. sin/cos/atan2 require absolute error strictly below 1 ULP of the ideal result of exact binary64 inputs. For normal ideal results, ULP=2^(floor(log2(abs(result)))-52); for subnormal/zero it is 2^-1074. Exact special cases also preserve documented bits/signs. Vector accuracy follows the prescribed sequence. Qualification uses independent MPFR with exact binary64 import, directed bounds and adaptive precision. Emulate exponent limits and gradual underflow for reference rounding. MPFR is tooling, never cartridge execution. Combine critical/random/extreme fixtures with reference source/upstream audits; sampling alone is not proof over all binary64. Record compiler, target/profile/features, lockfile/backend revision and catalog snapshot. Reference changes require requalification, without pinning the entire workspace's stable toolchain. Local evidence covers available macOS/aarch64 debug/release. Reproduce the same portable corpus on macOS/x86_64 and Linux/x86_64 headless when execution infrastructure becomes available; compare exact bits/faults/cycles in both profiles. Cross-architecture runs remain pending. Cross-compilation is build evidence only. Hardware acquisition, frontend integration and new graphical/audio hosts are not prerequisites for local qualification. Benchmark real execution separately; never interpret virtual costs as CPU timings or relax numeric guarantees to improve performance. Generate/check catalogs: cargo run -p prometeu-vm --example export_numeric_catalog cargo run -p prometeu-vm --example export_numeric_catalog -- constants The independent harness is scripts/qualify-numeric.py and the bit probe is the numeric_probe example. Portable fixed fixtures reside in crates/console/prometeu-vm/tests/fixtures/numeric-conformance.tsv. The versioned [local qualification record](../../vm-arch/NUMERIC_QUALIFICATION.md) reports the executed configuration, source audit, observed precision and timings, reproducible commands and pending host comparisons. ## Random core integration The [random core](02e-vm-owned-random-core.md) uses this software binary64 backend for exact nextf values k/2^53. Its deterministic calls mutate guest state; exported metadata includes mutates_guest_state and fixed or random_rejection_v1 cost models.