Files
prometeu-runtime/docs/vm-arch/RANDOM_QUALIFICATION.md
T
bquarkz 3e39a90083
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
feat(vm): add VM-owned PCG64 random and coverage headroom
Implement GC-managed random generators, next/nextf intrinsics, bounded ranges and deterministic conformance coverage. Publish the runtime contract and producer guidance.

Give coverage domains at least five percentage points of measured headroom while preserving sufficient floors. Record local qualification: make ci-domains passes with 939 tests and all domain gates green.
2026-10-09 12:51:05 +01:00

80 lines
4.5 KiB
Markdown

# Random qualification
Executed on 2026-10-09, target `aarch64-apple-darwin`, default features, with
fpmath 0.1.1 soft-float. Toolchain: rustc 1.98.1 (48a229cea, 2026-09-01),
LLVM 22.1.8. Exact rustc -Vv, source/lockfile/catalog/fixture fingerprints and
per-file source hashes are in [RANDOM_QUALIFICATION.json](RANDOM_QUALIFICATION.json).
This record qualifies only the executed local target/profiles.
## Executed checks
| Check | Result |
| --- | --- |
| cargo test --locked -p prometeu-bytecode -p prometeu-vm | 400 passed, 3 existing ignored |
| cargo test --locked -p prometeu-bytecode -p prometeu-vm --release | 401 passed, 3 existing ignored |
| cargo test --locked --workspace | 938 passed, 9 existing ignored |
| Final random_contract guest suite, debug / release | 13 passed / 13 passed |
| Private engine/VM random tests, debug / release | 11 passed / 11 passed |
| cargo fmt --all -- --check | Passed |
| Generated intrinsic CSV and constant CSV comparison | Exact metadata parity; constants unchanged |
| Coverage source ownership audit | All source files have exactly one owner |
| git diff --check and changed-doc link/workflow-reference checks | Passed |
The complete runs preceded the final additional guest handoff assertion; the
final targeted guest runs cover all 13 assertions in both profiles. No
production source changed between these checks. The ignored tests are existing
repository tests, not unexecuted random acceptance cases.
## Independent oracle and state behavior
[Fixture provenance](../../crates/console/prometeu-vm/tests/fixtures/random-oracle.md)
pins pcg-cpp revision 428802d1a5634f96bcd0705fab379ff0113bcf13 and the six
canonical seed=42 words. A separate test-only Python mathematical model produces
48 words, signed outputs and Float bits for seeds 0, 1, 42, -1 and Int64 MIN/MAX.
Guest tests replay both integer and Float output streams and mixed operations.
The Float grid endpoint checks include +0 and the greatest value below 1.
Tests cover alias/separate-object state, direct Dynamic with exact types/typed
null, locals/globals/fields/arrays/captures/parameters/results, reachable GC
roots, reclamation, stale generations and existing session reset/import rules.
Native snapshots are not guest roots; raw handle copies are not a supported
cross-session import API. Opaque payload access and Struct/Trait misuse are
rejected by the existing admission/runtime type boundaries.
## Bounded work, faults and resources
Real PCG output exercises a rejected word followed by acceptance, charging
20 cycles and committing as one instruction. Private synthetic words exercise
the production bounded loop/transaction: immediate/multiple rejection, acceptance
on attempt 64 and 64 rejections. The cap costs 516 cycles and preserves public
state and operands; the next normal draw still returns the first canonical word.
Tests do not alter production PRNG selection or wait for a rare random event.
Fault matrices cover argument carriers before receiver checks, null/invalid/
wrong-kind handles, numeric bounds, stack height and GuestBytes/HandleSlots/
AuxiliaryBytes/TemporaryBytes refusals. Snapshots prove no operand/state changes,
no provisional charge leaks and no partial handle publication. Billing remains
observable; zero budget does nothing, positive budget allows whole-instruction
overshoot, and faults precede BudgetExhausted without successful-step credit.
Generated metadata exposes guest mutation and variable costs. No RNG execution
uses HostContext, syscalls, host entropy/time/address initialization, FFI,
bigint runtime arithmetic or a parallel catalog. PBX v1 remains unchanged;
unreachable unknown IDs reject with InvalidCode/NativeId and Unknown analysis
retains full runtime checks.
## Pending comparisons and consumers
Linux, Windows, x86_64 and other target comparisons have not been executed.
For each advertised target, run the pinned guest and private fixture suites in
debug/release and record toolchain/features/source/catalog fingerprints plus
bits/faults/cycles. Do not infer qualification from this local result.
CPU benchmarks were not run and do not set virtual costs.
Frontend emission/optimization and reference-game workload integration remain
separate consumer deliveries. Their concrete acceptance tests are in the
[random producer handoff](random-producer-handoff.md). Statistical quality,
sequence conformance and game readiness are separate evidence; none is a
cryptographic guarantee. The normative contract is the
[random spec](../specs/runtime/02e-vm-owned-random-core.md).