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
@@ -10,7 +10,11 @@ tags: [tests, coverage, ci, governance]
PROMETEU moved runtime-edge coverage governance away from a single workspace-wide percentage and toward canonical domain gates. That shift mattered not only for policy, but also for how CI logic is expressed and maintained.
The resulting model now treats `system/runtime`, `fs`, `asset/bank`, `firmware`, and `host-dependent` as the operational coverage authorities for runtime-edge changes.
The initial model focused on runtime edges. It now preserves the specialized
system/asset/firmware/host owners and also covers VM, bytecode, residual
HAL/drivers/system sources, tooling and test infrastructure.
The published operational reference is
[Coverage domains](../../../docs/vm-arch/COVERAGE_DOMAINS.md).
## Key Decisions
@@ -36,20 +40,67 @@ The coverage contract evolves with the repository. When CI duplicates the decisi
**Trade-offs:**
The helper must remain readable and stable, because it becomes part of the repository contract rather than a local convenience script.
### Complete and exclusive source ownership
**What:**
Every crate src Rust file has exactly one domain, including sources without
executable LLVM lines. Residual crate owners exclude the existing specialized
prefixes. A shared auditor normalizes report paths and supplies the same
statistics used by evidence display and percentage gates.
**Why:**
Tests can run successfully while the implementation they exercise belongs
to no coverage gate. Moving test files does not repair that omission.
Auditing only report files also misses sources absent from instrumentation.
Separate matching implementations can disagree on absolute/relative paths
or symlink aliases while producing plausible percentages.
**Trade-offs:**
New crates require explicit ownership. Reports with missing domains, duplicate
sources or zero instrumented lines are rejected before threshold comparison.
The current source map assigns 232 files to 15 exclusive owners without
changing the original eight domain baselines.
## Patterns and Algorithms
- Keep the policy in repository files (`Makefile`, coverage scripts, domain baseline config), and keep Jenkins as a thin caller.
- Use domain-scoped baselines as a quantitative gate, but keep mandatory scenarios as the governing behavioral rule.
- Publish operationally useful coverage output that emphasizes gate status first and only exposes deeper evidence on demand.
- Let Cargo discover unit/integration/cross-layer suites in their existing
targets. Their execution contributes coverage to every implementation owner
they exercise; the physical test-file directory is not the ownership map.
- Measure new starting baselines from fresh coverage and preserve existing
ones. Keep precision/bit-level oracles complementary to line coverage.
## Pitfalls
- Treating a global coverage increase as proof that a touched domain is adequately tested.
- Encoding gate math directly in Jenkins and forcing future policy changes to update multiple authorities.
- Letting verbose evidence output bury the actual pass/fail signal in CI logs.
- Allowing an absent or zero-line report to pass a zero baseline.
- Assigning the whole VM to the system integration domain, or counting one
source in both a specialized owner and its enclosing residual crate owner.
- Treating local host measurements as evidence for unexecuted platforms.
## Published Extension and Evidence
The ownership extension derives from accepted DEC-0049 and its completed local
implementation PLN-0180. It preserves the domain-first governance of the
original completed discussion. The
[measured evidence](../../../docs/vm-arch/COVERAGE_DOMAINS_EVIDENCE.json)
records the actual host/configuration, source/report fingerprints and counts.
Local macOS/aarch64 make ci-domains passed 915 tests, with nine existing ignored
tests, formatting, Clippy and all 15 coverage gates. Eight policy regression
tests exercise real repository ownership and independent invalid evidence.
Mathematics and its portable MPFR-generated fixture now exercise vm/core;
bytecode has its own gate. The standalone MPFR qualification remains separate.
This evidence does not claim Linux or Intel Mac coverage execution.
## Takeaways
- Runtime-edge coverage is safer when CI enforces domain ownership instead of trusting a workspace aggregate.
- Scenario-first review and domain baselines complement each other; neither should replace the other.
- Coverage gates that live in repository helpers are easier to evolve, audit, and keep consistent than CI-local logic.
- Audit source ownership and evidence validity before comparing percentages.
A passing percentage is useful only when its denominator has a clear owner.
@@ -0,0 +1,144 @@
---
id: LSN-0062
ticket: gameplay-math-and-numeric-semantics
title: Portable Math Requires a Runtime-Owned Numeric Contract
created: 2026-10-09
tags: [game-readiness]
---
## Context
Gameplay code can be produced on one computer and executed by different hosts.
That portability depends on preserving numeric behavior in the runtime that
executes the cartridge. A frontend-only math implementation would make
different producers responsible for agreeing on details that affect game state.
This lesson derives from accepted decision DEC-0048, implemented through
PLN-0179. The published normative result is
[Gameplay Math and Numeric Semantics](../../../docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md).
The discussion lifecycle remains in the [index](../../index.ndjson).
The [qualification record](../../../docs/vm-arch/NUMERIC_QUALIFICATION.md)
contains executed evidence, configuration and remaining host comparisons.
## Key Decisions
### Own observable numeric behavior in the VM
**What:** Guest Float operations, conversions and math use the same binary64
software adapter. Runtime metadata owns exact signatures, argument names,
identities, constants, flags and fixed virtual costs. The intended frontend
projection uses math for integers and mathf for Float.
**Why:** Producers select an exact identity and emit a call; the runtime
determines the result. The frontend does not become a second numeric engine.
**Trade-offs:** Software execution costs CPU time. The measured direct-call
costs range from tens of nanoseconds for dot to microseconds for atan2 on the
available machine. Those measurements do not alter guest-visible cycle costs.
Frontend projection and integration remain a separate delivery.
### Separate reproducibility from mathematical accuracy
**What:** Result bits, faults and virtual cycles must agree exactly between
qualified runtime builds. The mathematical reference comparison separately
checks correct rounding or the prescribed strict error bound.
**Why:** Two results can both satisfy a mathematical error bound and still
drive different simulation branches. Approximation quality does not establish
reproducibility.
**Trade-offs:** Backend/dependency changes require a new qualification
baseline. Recognizing the unchanged vec2 v1 identities alone does not qualify
an older runtime for the revised operation sequence.
### Specify composite operations as sequences
**What:** dot rounds and checks two products and their sum separately.
length uses a scaled sequence of division, multiplication, addition and sqrt.
**Why:** Avoiding overflow by scaling improves useful input coverage, while
specifying every step prevents FMA, wider accumulators or library hypot from
silently changing observable bits or faults.
**Trade-offs:** A prescribed sequence need not equal the single correctly
rounded ideal composite function. Intermediate overflow remains observable,
even if a hypothetical wider calculation would cancel it.
## Patterns and Algorithms
Keep f64 as bit transport. SoftF64 delegates arithmetic/comparison to APFloat;
the adapter owns finite admission, signed-zero rules, domain/range faults and
explicit integer conversions. Integer-to-Float conversion rounds significand
bits with ties to even. Float-to-integer conversion truncates the exact
represented value before checking destination bounds.
Validate all declared carriers before all nonfinite parameters, then domain
and result range. Reject invalid Float constants and immediate instructions
at loading, including unreachable code. Native signature import and public
stack import prevent NaN/infinity from entering guest state.
Charge a known mathematical attempt once before validation or scratch
reservation. Failed attempts retain the same cost. Zero budget starts no
instruction; positive budget can admit a complete operation and overshoot.
Keep this independent of actual CPU latency and unchanged unrelated opcode
accounting.
Generate consumer catalogs from runtime descriptors and compare checked-in
exports to that source in tests. Publishing exact parameter order is especially
useful for atan2(y,x), explicit conversions and named-argument lowering.
Use an independent MPFR oracle with exact imports, directed intervals and
adaptive precision. Importing a decimal rendering can test the wrong input.
Binary64 exponent limits and gradual underflow matter as much as precision.
For composite sequences, round each reference step in the same binary64 model.
## Pitfalls
- Upstream round uses ties away from zero; matching a function name did not
make it compatible with the runtime's ties-to-even contract.
- Int64 MAX rounds to +2^63 as Float. Using that rounded value as an inclusive
cast bound would accept an out-of-range conversion; saturating casts would
hide the error.
- Signed zeros affect min/max, rounding, axes and vector results despite
comparing equal numerically.
- A remainder against approximate tau does not provide the required reduction
for every large finite angle.
- Taking abs after an upward-rounded negative subtraction can underestimate
an oracle error bound. Round positive endpoint distances upward instead.
- The existing payload-preservation tests used NaN bit patterns. Finite
subnormal patterns preserve their original bit-transport coverage, while
separate tests assert the new rejection contract.
- An x86_64 oracle process on the same Mac is not x86_64 runtime execution.
Cross-compilation and local debug/release equality also do not replace
empirical comparison between runtime architectures.
## Delivered Evidence and Handoffs
Local macOS/aarch64 dev/release qualification passed 380,946 MPFR cases per
profile with identical corpus bytes. The largest sampled strict error upper
bounds were approximately 0.733 ULP for sin, 0.699 for cos and 0.514 for atan2.
The checked-in 4,747-row fixture runs without MPFR. All 907 workspace tests
passed, with nine existing ignored tests; formatting and Clippy passed.
The 14 numeric contract tests passed in both debug and release.
Sampling plus source/upstream review supports this local baseline without
claiming an exhaustive proof over binary64.
Remaining host validation targets macOS/x86_64 and Linux/x86_64 headless.
Acceptance requires passing the same oracle/contract tests in debug/release
and matching the complete corpus bits, faults and cycles to the published
hash. These runs await available infrastructure; the local delivery did not
execute or certify them.
The frontend handoff is to consume the runtime catalogs, implement namespace
projection and exact overload selection, preserve ordered arguments and calls
with literal inputs, and use canonical constant bits. The published spec
contains consumer/emission examples. No frontend code or frontend integration
tests were implemented in this delivery.
## Takeaways
- Deterministic math is a runtime execution contract, including faults and cost.
- Mathematical accuracy and exact agreement between hosts need separate gates.
- Explicit composite sequences and conversion bounds prevent hidden changes.
- Keep local evidence useful and reproducible while naming unexecuted hosts
and consumer integration precisely.