Files
prometeu-runtime/docs/vm-arch/NUMERIC_QUALIFICATION.md
T
bquarkz 9318cf7cd3
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
feat(vm): add deterministic gameplay math and domain coverage gates
2026-10-09 10:25:11 +01:00

8.0 KiB

Software numeric qualification

Date: 2026-10-09. Scope: local macOS/aarch64 qualification. The normative contract is Gameplay Math and Numeric Semantics. The exact configuration, dependency checksums, source/catalog fingerprints, oracle results and measured timings are in NUMERIC_QUALIFICATION.json.

Configuration and source audit

The runtime uses fpmath 0.1.1, feature soft-float, with rustc_apfloat 0.2.3+llvm-462a31f5a5ab resolved in Cargo.lock. Both dev and release probes ran as aarch64-apple-darwin executables under rustc 1.98.1, commit 48a229ceaefd4985c50990b14116b6d856af0985, LLVM 22.1.8. No native numeric acceleration is enabled. Source fingerprints identify the implementation independently of the pre-change repository commit.

The reviewed paths in the published fpmath source are:

Path Finding relevant to the runtime
src/soft_f64.rs SoftF64 stores an APFloat Double. Bit import/export does not calculate with native f64. Basic operators delegate to APFloat; comparisons also use that representation.
rustc_apfloat src/lib.rs The default ADD/SUB/MUL/DIV operator implementations select NearestTiesToEven explicitly.
src/generic/sqrt.rs Normalizes subnormals, computes the integer root with an extra bit and constructs the rounded result bits. Zero signs are preserved. The documented upstream error bound is below half an ULP.
src/generic/sin_cos.rs; src/generic/reduce_pi_2.rs Selects small, medium and large argument reduction. Medium reduction uses split constants and additional cancellation correction.
src/generic/reduce_pi_2_large.rs Uses integer/fixed-point chunks and a stored 2/pi expansion derived from the musl/FreeBSD reduction algorithm, rather than a remainder against binary64 tau.
src/generic/atan.rs Generic atan/atan2 calculations use the software scalar implementation. The runtime handles the zero vector and signed axes explicitly before delegation.

The published fpmath documentation describes portable soft-float results and error bounds for these functions. The versioned source is the audit reference. Upstream claims, source review and independent testing support the selected reference; this record is not a formal proof over every binary64 input.

The VM adapter supplies semantics that cannot be taken directly from every upstream convenience function. In particular, upstream round uses ties away from zero; runtime mathf.round implements ties to even from bits. Integer conversions also use bits, avoiding saturation and the rounded Float representation of Int64 MAX as a range bound. Every public numeric path validates inputs and maps domains/range to the runtime fault contract. Float arithmetic, mixed-carrier promotion and comparisons in guest opcodes use this adapter. Host inspection utilities are outside guest arithmetic.

Independent oracle and results

The tooling uses gmpy2 2.3.0 and MPFR 4.2.2. Binary64 inputs are imported through exact rational representations, with explicit preservation of -0. Directed MPFR bounds start at 160 bits and adapt up to 10,240 bits when needed. Basic operations, sqrt and integer-to-Float conversions must match the independently rounded binary64 result, including exponent limits and gradual underflow. Rounding and Float-to-integer conversions are also checked against exact integer/rational rules. Vector results match the prescribed sequence with a binary64 MPFR context at each step.

For sin/cos/atan2 the gate certifies a strict upper error bound below 1 ULP of the ideal result. Positive endpoint distances are rounded upward before comparison; taking the absolute value of a negative subtraction rounded upward would underestimate that bound.

Both profiles passed 380,946 cases with seed 560053 and count 10000. The corpus combines critical constants, neighboring binades, subnormal transitions, finite extremes and random finite bit patterns. Arithmetic opcode rows execute validated bytecode. Scalar/vector rows call the same runtime implementations directly; their reported cycles come from metadata. Interpreter accounting is independently exercised by the contract tests for every scalar/vector identity, refusals, zero budget and overshoot.

Function Largest certified error upper bound in the sampled corpus
sin 0.7327914722897216 ULP
cos 0.698851370176746 ULP
atan2 0.5139939747008185 ULP

Fundamentals, sqrt, conversions, rounding and vector sequences had no disagreement with their corresponding exact oracle. Debug and release corpus bytes were identical, including results/faults and cycles. SHA-256:

51f9361e79b2e648d557d38dad775250ed3c5d57f8ff5f187dc3ee7aab7ddfdb

The checked-in portable fixture contains 4,747 independently verified rows (count 100, same seed). It replays without installing MPFR. Workspace validation passed 907 tests with 9 existing ignored tests, cargo fmt and workspace Clippy. All 14 numeric contract tests passed in release as well as debug.

The oracle process runs as x86_64 on the available Mac, while both runtime executables are aarch64. This is independent oracle execution, not an x86_64 runtime qualification.

Indicative local cost

One release microbenchmark called each intrinsic implementation 20,000 times, after 100 warmup calls, with the inputs in numeric_benchmark.rs. These timings exclude interpreter dispatch, argument production and frame scheduling; they are neither worst-case bounds nor virtual cycle calibration.

Function Observed ns/call Fixed virtual call cycles
sqrt 113.21 16
sin, large argument 853.40 32
cos, MAX_FINITE 922.79 32
atan2 2274.13 48
dot 51.81 10
length 248.53 40

Reproduction and remaining host evidence

Install the independent oracle in an isolated environment:

python3 -m venv /tmp/prometeu-numeric-oracle
/tmp/prometeu-numeric-oracle/bin/python -m pip install -r scripts/numeric-oracle-requirements.txt

Build with the locked dependency resolution and run both profiles:

cargo build --locked -p prometeu-vm --examples
cargo build --locked -p prometeu-vm --examples --release
mkdir -p target/numeric
/tmp/prometeu-numeric-oracle/bin/python scripts/qualify-numeric.py --probe target/debug/examples/numeric_probe --output target/numeric/debug-corpus.tsv --count 10000 > target/numeric/debug-report.json
/tmp/prometeu-numeric-oracle/bin/python scripts/qualify-numeric.py --probe target/release/examples/numeric_probe --output target/numeric/release-corpus.tsv --count 10000 > target/numeric/release-report.json
cmp target/numeric/debug-corpus.tsv target/numeric/release-corpus.tsv
cargo test --locked -p prometeu-vm --test numeric_contract
cargo test --locked -p prometeu-vm --test numeric_contract --release
target/release/examples/numeric_benchmark

Regenerate/check catalog artifacts with export_numeric_catalog. The parity test compares generated output to both checked-in CSV files. Record rustc -Vv, target, features, lockfile, source/catalog fingerprints and oracle versions on every new qualification run.

Runtime execution on macOS/x86_64 and Linux/x86_64 headless remains pending. When those hosts are available, reproduce this same seed/count in debug and release, pass the oracle and contract tests, and compare the complete corpus to the SHA-256 above. Any difference in bits, faults or cycles requires investigation; meeting the ULP bound alone does not qualify a different result. Cross-compilation only provides build evidence. A future intentional backend revision requires a new qualification baseline.

Frontend integration remains pending independently: consume runtime metadata, project math/mathf namespaces, resolve exact overloads, retain ordered arguments and preserve calls with literal inputs. The spec supplies examples; this delivery contains no frontend implementation or frontend integration tests.