Files
prometeu-runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md
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

314 lines
15 KiB
Markdown

# 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.