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.