feat(vm): add deterministic gameplay math and domain coverage gates
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit

This commit is contained in:
2026-10-09 10:25:11 +01:00
parent 2e041266f1
commit 9318cf7cd3
47 changed files with 8825 additions and 281 deletions
@@ -171,3 +171,15 @@ Budget admission remains between instructions. Zero executes nothing. A positive
## Typed Callable Costs
Charge each admitted attempt once, including trap: MAKE_CLOSURE 8+C (declared capture-slot sum), CALL_CLOSURE 6, GET_CAPTURE 2+W (selected complete-group width), CALL_TRAIT 6. Direct CALL/RET retain 5/4. No extra callback budget, partial-instruction pause or GC-cycle redesign. Zero budget executes nothing; positive budget may admit an instruction that overshoots. Root-return GC does not grant cycles, advance frames or invoke guest cleanup.
## Mathematical intrinsic attempts
The [numeric contract](02d-gameplay-math-and-numeric-semantics.md) publishes
fixed total call costs: min/max/abs/conversions 2, clamp and rounding 4,
vec2.dot 10, sqrt 16, sin/cos 32, vec2.length 40, atan2 48.
Charge known mathematical attempts before checks and scratch reservations,
including failure, exactly once without an extra generic INTRINSIC cycle.
Zero budget begins no attempt; positive budget admits the complete operation
and retains the existing overshoot rule. Argument-producing bytecode costs
remain additional. Input/color and other intrinsic/opcode costs and accounting
remain unchanged. CPU timings never change guest-visible cycle weights.
@@ -129,3 +129,14 @@ Use a bounded worklist to fixed point, reprocessing widened states; decide state
Builtin IDs, exact slot carriers, nullable defaults and stored layouts are defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization). A fixed list of results does not imply a tuple object or boxing. Parameter names are optional signature metadata; frontend argument reordering must preserve source evaluation order.
## Finite Float and explicit math conversions
Float is binary64 with the VM-owned software semantics in
[Gameplay Math and Numeric Semantics](02d-gameplay-math-and-numeric-semantics.md).
NaN/infinity are rejected at image admission and native import, never stored
as guest numeric defaults. Preserve signed-zero bits and subnormals; numeric
equality treats both zeros equally. Numeric overflow faults by range.
Exact Registry/intrinsic carriers prohibit implicit conversion; math/mathf
supplies explicit conversions with truncation/range and ties-even rules.
Existing arithmetic opcode promotions do not relax typed boundaries.
@@ -194,6 +194,9 @@ Preserve typed reasons and available section/file offset, ID domain/record/membe
| TRAP_INVALID_HANDLE | 0x0000000F | Invalid index, dead slot, stale/invalid generation |
| TRAP_RESOURCE_LIMIT | 0x00000010 | Runtime quota/size overflow/recoverable allocation failure |
| TRAP_UNAVAILABLE | 0x00000011 | Known input query unavailable on the platform |
| TRAP_NUMERIC_DOMAIN | 0x00000012 | Invalid mathematical domain of finite arguments |
| TRAP_NUMERIC_RANGE | 0x00000013 | Finite result/destination outside representable range |
| TRAP_NON_FINITE | 0x00000014 | NaN/infinite input rejected before guest publication |
Keep TrapInfo(code,opcode,pc,message,optional span) and current trap interruption behavior; no guest-catchable exception system. Untyped null to Int32 is TRAP_TYPE, not null dereference. Invalid handles never become false/null and are validated before following them. Preserve existing stack/function/return/intrinsic error categories. No promise to recover process/allocator abort; use fallible new allocation paths rather than operational panics.
@@ -239,3 +242,16 @@ Nested records count fields, methods, parameters/results and implementation Func
Auxiliary state includes capacities of the VM operand stack, CallFrames, globals, handles/free lists, string ledgers and persistent GC structures. The VM owns one context directly; entry preparation allocates no heap execution object. Closure headers and capture payloads remain heap-owned. Call depth and per-frame cap coexist with aggregate session auxiliary cap. Constants are checked at load; runtime excess traps. Growth must not geometrically reserve beyond available quota. Cycle/frame budgets remain separate. Asset and host admission limits are outside these totals.
## Numeric admission
Float64 constant bits must be finite. Reject NaN/infinity using
LOAD_INVALID_FORMAT/NonFiniteValue with Constants section, file offset and
constant index. Reject nonfinite PushF64, even in unreachable declared code,
with LOAD_INVALID_CODE/NonFiniteValue and function/PC/offset context.
Decode/tag/truncation failures preserve structural categories. Unsupported
INTRINSIC identities are LOAD_INVALID_CODE/NativeId with function/PC and ID.
No envelope/version change is introduced. Native signature import validates
complete layouts before checking Float finitude and publishing guest slots.
See [numeric semantics](02d-gameplay-math-and-numeric-semantics.md) for fault
precedence, conversions, catalog metadata and producer examples.
@@ -0,0 +1,307 @@
# 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,
total call cost and determinism/guest-allocation flags.
[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.
@@ -79,17 +79,19 @@ All performance is measured in **PROMETEU cycles**, not in milliseconds.
## 5 Floating Point Precision
To guarantee numerical consistency:
[Numeric execution](02d-gameplay-math-and-numeric-semantics.md) uses finite
binary64 software arithmetic, explicit rounding, signed zeros and subnormals.
Supported hosts MUST agree on result bits, numeric faults and virtual cycles.
The mathematical precision bound for trigonometry is not a tolerance between
hosts. Native acceleration requires exact equivalence to the reference.
- PROMETEU defines explicit mathematical operations
- avoids dependence on specific FPUs
- standardizes `number` behavior
This avoids:
- divergences between architectures
- unpredictable cumulative errors
- subtle differences between platforms
Qualification evidence identifies runtime build/revision, target, profile,
dependency resolution and catalog snapshot. The current independent numeric
delivery qualifies available macOS/aarch64 in debug/release.
Comparative macOS/x86_64 and Linux/x86_64 execution remains pending; recognizing
the same intrinsic IDs or successfully cross-compiling does not certify a
new host. Unavailable hardware does not weaken the contract or require a new
graphical/audio backend for mathematical qualification.
## 6 Cross-Platform Input
+1
View File
@@ -79,6 +79,7 @@ In the current state, no chapter under the active `docs/specs/runtime/` root is
| [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) | VM values and calling convention | normative |
| [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) | VM closures and function values | normative |
| [`02c-program-registry-and-pbx-v1.md`](02c-program-registry-and-pbx-v1.md) | Registry, typed storage, PBX v1 and quotas | normative |
| [02d-gameplay-math-and-numeric-semantics.md](02d-gameplay-math-and-numeric-semantics.md) | VM math, numeric faults, cycles and consumer examples | normative |
| [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) | VM memory model | normative |
| [`04-gfx-peripheral.md`](04-gfx-peripheral.md) | virtual hardware: graphics | normative |
| [`05-audio-peripheral.md`](05-audio-peripheral.md) | virtual hardware: audio | normative |