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

143 lines
8.0 KiB
Markdown

# Software numeric qualification
Date: 2026-10-09. Scope: local macOS/aarch64 qualification.
The normative contract is [Gameplay Math and Numeric Semantics](../specs/runtime/02d-gameplay-math-and-numeric-semantics.md).
The exact configuration, dependency checksums, source/catalog fingerprints,
oracle results and measured timings are in [NUMERIC_QUALIFICATION.json](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](https://docs.rs/fpmath/0.1.1/fpmath/)
describes portable soft-float results and error bounds for these functions.
The [versioned source](https://docs.rs/crate/fpmath/0.1.1/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.