feat(vm): add deterministic gameplay math and domain coverage gates
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
This commit is contained in:
+52
-1
@@ -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.
|
||||
|
||||
+144
@@ -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.
|
||||
Reference in New Issue
Block a user