Files
prometeu-runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md
T
bquarkz 3e39a90083
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat(vm): add VM-owned PCG64 random and coverage headroom
Implement GC-managed random generators, next/nextf intrinsics, bounded ranges and deterministic conformance coverage. Publish the runtime contract and producer guidance.

Give coverage domains at least five percentage points of measured headroom while preserving sufficient floors. Record local qualification: make ci-domains passes with 939 tests and all domain gates green.
2026-10-09 12:51:05 +01:00

15 KiB

Gameplay Math and Numeric Semantics

Domain: VM numeric execution and mathematical intrinsics Function: normative

Didactic companion: Portable math requires a runtime-owned numeric contract.

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 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 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=axbx, p2=ayby, 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 reports the executed configuration, source audit, observed precision and timings, reproducible commands and pending host comparisons.

Random core integration

The random core 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.