Files
prometeu-runtime/docs/vm-arch/random-producer-handoff.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

74 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Random producer handoff
The runtime implements [Random v1](../specs/runtime/02e-vm-owned-random-core.md).
PBS namespace projection/lowering and reference-game integration remain pending
consumer work. No host entropy, syscall or firmware provider is required.
Use the generated [intrinsic catalog](INTRINSICS.csv); never copy its IDs or
cost/effect rules into an independent algorithm implementation.
## Types and emission
Declare program TypeId 0 as BuiltinId 0x0011 (Int64), TypeId 1 as BuiltinId
0x0016 (Random), and TypeId 2 as BuiltinId 0x0012 (Float). TypeIds are local
program identities, not builtin IDs. Random uses one nullable reference slot.
This function has no parameters, one local slot and results [Int64, Float,
Int64]. Its intrinsic IDs are decimal 16384 through 16387 (hex 0x4000–0x4003),
all version 1. Operands are ordered seed; rng; rng; and rng/min/max respectively.
```text
PUSH_I64 42
INTRINSIC 16384
SET_LOCAL 0
GET_LOCAL 0
INTRINSIC 16385
GET_LOCAL 0
INTRINSIC 16386
GET_LOCAL 0
PUSH_I64 -7
PUSH_I64 -6
INTRINSIC 16387
RET
```
The complete function costs 82 virtual cycles: 32+8+12+12 for the four calls,
three PUSH_I64 at 2 each, three GET_LOCAL at 2 each, SET_LOCAL at 2 and RET at 4.
Its ordered results are Int64 bits 0x86B1DA1D72062B68, Float bits
0x3FB304AA46C98538 and Int64 -7. The unit interval consumes the third word;
a subsequent next returns bits 0xF9090E529A7DAE00. Actual producer emission is
exercised by the VM random contract tests through the official PBX v1 writer
and loader, not direct host callbacks.
## Storage and Dynamic
Emit ordinary SET/GET_LOCAL and SET/GET_GLOBAL for handle aliases; typed
Struct fields and Array elements declare the Random TypeId and use existing
collection instructions. Captures and parameter/result groups use that same
one-slot type. NEW cannot create Random; allocate with random.new first.
DYN_PACK 1 followed by DYN_UNPACK 1 preserves the same generator without a
multislot box. Typed null preserves tag 1 and extracts only to that exact type.
No Struct or Trait adaptation is implied by physical HeapRef representation.
## Consumer acceptance tests
Frontend delivery must import Random and all four exact v1 signatures, preserve
source evaluation order for positional/named arguments, retain aliases, and
emit correct ordered carriers. All random entries are deterministic and
mutates_guest_state=true. Only new may_allocate=true. These calls cannot be
compile-time evaluated, folded, eliminated or reordered based on seeds/literals
or the deterministic flag. Range metadata publishes base 4, attempt 8 and
maximum 64, not a fixed total of 4. Test generated PBX against the sequence and
fault/cycle traces above, including mixed next/nextf/range and duplicated handles.
Reference-game delivery must use explicit seeds and replay equal ordered
inputs to compare result bits, fault identities and cycles. Keep generators
separate when independent state is required; copying handles does not fork a
stream. Test min>=max -> NUMERIC_DOMAIN at cost 4 with retained operands/state;
null receiver -> NULL_REFERENCE; incorrect carriers -> TYPE. Failed attempted
calls retain their charged cycles. No PickRandom or helper surface is exposed.
Additional target qualification must run the pinned fixture suite in debug
and release on each advertised target, recording target/toolchain/features,
lockfile, source/catalog fingerprints and result bits/faults/cycles. The
[current qualification record](RANDOM_QUALIFICATION.md) identifies executed
local evidence; unexecuted comparisons are pending tests, not portability claims.