Files
prometeu-runtime/docs/vm-arch/random-producer-handoff.md
bquarkz a2275932a5
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
Keep PBX at v0 and simplify Jenkins quality gate
2026-10-14 14:35:44 +01:00

3.5 KiB
Raw Permalink Blame History

Random producer handoff

The runtime implements Random v1. 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; 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.

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 v0 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 identifies executed local evidence; unexecuted comparisons are pending tests, not portability claims.