Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
171 lines
8.8 KiB
Markdown
171 lines
8.8 KiB
Markdown
# VM-owned random core
|
|
|
|
## Identity and memory
|
|
|
|
`Random` version 1 is BuiltinId `0x0016`, an opaque nullable reference builtin.
|
|
It occupies one execution slot: present values use `Value::HeapRef`; the default
|
|
is `Value::Null`. Typed storage uses index:u32 and generation:u32, eight bytes
|
|
aligned to eight, with GuestReference ownership. Registry categories remain
|
|
Builtin, Struct, Array, Trait and Fn. PBX v0 encoding is unchanged.
|
|
|
|
ObjectKind::Random has tag 9; DynamicBox remains 8 and tag 6 remains reserved.
|
|
Its private logical payload is State:u128 and Inc:u128, 32 bytes with no child
|
|
references. Payload, header, handle tables and auxiliary storage are charged
|
|
to existing session quotas. Only `random.new` constructs Random; NEW and
|
|
Struct/array access cannot construct or expose its payload.
|
|
|
|
Random is valid in locals, globals, fields, arrays, captures and function
|
|
parameters/results. Copying a handle aliases the same state. Separate objects
|
|
with equal seeds have equal initial streams and evolve independently. Dynamic
|
|
retains the exact TypeId and direct single-slot HeapRef without copying state
|
|
or allocating a multislot box. Extraction requires that exact type, including
|
|
typed null. There is no implicit Struct or Trait adaptation.
|
|
|
|
Existing reference maps and roots retain reachable objects. Random is a GC
|
|
leaf; collection occurs only at existing safepoints. There are no guest
|
|
finalizers, callbacks or reentrant collection. Pause/resume preserves state;
|
|
reset/unload releases the session and prior handles cease to authorize access.
|
|
Existing native-boundary provenance rules apply: copying raw reference bits
|
|
between sessions is not an import operation.
|
|
|
|
## Exact algorithm
|
|
|
|
Use PCG-XSL-RR 128/64 setseq, with unsigned wrapping modulo 2^128:
|
|
|
|
```text
|
|
M = 0x2360ED051FC65DA44385DF649FCCF645
|
|
= 47026247687942121848144207491837523525
|
|
seq = 54
|
|
Inc = (seq << 1) | 1 = 109
|
|
B = zero_extend_128(bits_u64(seed))
|
|
State = ((B + 109) * M + 109) mod 2^128
|
|
|
|
each draw:
|
|
State = (State * M + 109) mod 2^128
|
|
X = low_u64(State) XOR high_u64(State)
|
|
R = State >> 122
|
|
W = rotate_right_64(X, R)
|
|
```
|
|
|
|
Int64 seed bits are reinterpreted as u64 and zero-extended, never sign-extended
|
|
or expanded. Zero, negative and extreme seeds are valid. Advance before
|
|
output; rotation zero preserves X. Inc is always 109 and State zero is valid.
|
|
There is no additional warm-up, discard, buffer, implicit global RNG or host
|
|
entropy. Explicit wrapping produces identical debug/release bits. Equivalent
|
|
limb arithmetic must match; operational host bigint/FFI or platform-selected
|
|
variants are forbidden. PCG32, PCG64DXSM and NumPy SeedSequence compatibility
|
|
is not promised.
|
|
|
|
Seed=42, seq=54 reference vectors; the Float column maps the same W:
|
|
|
|
| Draw | W hex | nextf binary64 bits |
|
|
| --- | --- | --- |
|
|
| 1 | 86B1DA1D72062B68 | 3FE0D63B43AE40C5 |
|
|
| 2 | 1304AA46C9853D39 | 3FB304AA46C98538 |
|
|
| 3 | A3670E9E0DD50358 | 3FE46CE1D3C1BAA0 |
|
|
| 4 | F9090E529A7DAE00 | 3FEF2121CA534FB5 |
|
|
| 5 | C85B9FD837996F2C | 3FE90B73FB06F32D |
|
|
| 6 | 606121F8E3919196 | 3FD818487E38E464 |
|
|
|
|
## Intrinsics and metadata
|
|
|
|
| ID | Version 1 name | Ordered signature | Virtual cycles |
|
|
| --- | --- | --- | --- |
|
|
| 0x4000 | random.new | (seed:Int64)->Random | 32 |
|
|
| 0x4001 | random.next | (rng:Random)->Int64 | 8 |
|
|
| 0x4002 | random.nextf | (rng:Random)->Float | 12 |
|
|
| 0x4003 | random.range | (rng:Random,min:Int64,max:Int64)->Int64 | 4+8*N |
|
|
|
|
There are no hidden receivers, defaults, Int32 coercions or alternative names.
|
|
Random is the type and random the namespace, not a singleton. Version 1 has
|
|
no PickRandom, collection/string/Bool helpers, destroy, reseed, clone, split,
|
|
exposed stream selector or serialization/replay API. It is not cryptographic.
|
|
|
|
All four descriptors publish deterministic=true and mutates_guest_state=true;
|
|
only new publishes may_allocate=true. Deterministic means reproducible with
|
|
the same state and ordered inputs, not pure. Compilers must preserve calls,
|
|
source evaluation order and state consumption, including named arguments.
|
|
They must not execute the generator at compile time, fold, eliminate or
|
|
reorder calls based on literals or deterministic metadata.
|
|
|
|
The shared catalog publishes cost_model. Fixed entries use `fixed`, complete
|
|
cost_cycles and zero attempt_cost_cycles/max_attempts. range uses
|
|
`random_rejection_v1`, cost_cycles=4 (base), attempt_cost_cycles=8 and
|
|
max_attempts=64. Four is not range's total cost. Existing identities and costs
|
|
are preserved. Execution is VM-owned through the same catalog/resolver/verifier,
|
|
without a HostContext RNG, host syscall or public host heap-access API.
|
|
|
|
## Outputs and bounded intervals
|
|
|
|
next consumes one W and reinterprets its bits as Int64, including negatives.
|
|
nextf consumes one W, computes k=W>>11 and returns k/2^53 through the VM's
|
|
software binary64 semantics. Values are exact points on [0,1); +0 is valid
|
|
and 1 is excluded. Float32, rounded W/2^64, host libm and frontend floating
|
|
arithmetic are forbidden. Calls share the same stream; no per-output buffers.
|
|
|
|
range requires exact Int64 min<max and returns [min,max). Compute n=max-min
|
|
in wide arithmetic, then as u64 (1 through 2^64-1). Compute threshold=2^64 mod n
|
|
using wrapping_neg(n)%n. For each word, reject W<threshold; otherwise return
|
|
min+(W%n) in wide arithmetic with exact Int64 conversion. No abs, signed
|
|
modulus, Float, swapped or clamped limits. A unit span consumes one word.
|
|
|
|
At most 64 words are attempted; acceptance on attempt 64 succeeds. Rejecting
|
|
all 64 raises TRAP_RANDOM_REJECTION_LIMIT `0x00000015`, without fallback.
|
|
The mapping removes additional modulo bias for uniform input words; it does
|
|
not promise statistical independence between deterministic words or streams.
|
|
|
|
## Validation and atomicity
|
|
|
|
Order checks as follows: instruction structure/height; all argument carriers
|
|
in parameter order; complete receiver reference; limits; resource reservations;
|
|
draws. Wrong carriers use TYPE, null receiver NULL_REFERENCE, invalid index,
|
|
generation or liveness INVALID_HANDLE, live wrong object/type TYPE, min>=max
|
|
NUMERIC_DOMAIN, and quota/recoverable allocation refusals RESOURCE_LIMIT.
|
|
Keep PC, opcode, source span and available resource details. No operational
|
|
panic, guest catchable exception or host-status substitute is introduced.
|
|
|
|
Retain operands and roots, validate, and reserve result/resources before
|
|
mutation. Stage candidate state and result, then publish and consume operands
|
|
atomically with no fallible work afterward. Every fault preserves operands,
|
|
generator state and prior owners, releases provisional resources and publishes
|
|
no partial handle. range draws on private candidate state and rolls it back
|
|
on any fault, including the rejection limit. Executed cycles are not refunded.
|
|
|
|
Loader/verifier recognize Random and all signatures without changing PBX v0.
|
|
Unknown intrinsic IDs, including unreachable ones, use LOAD_INVALID_CODE/NativeId;
|
|
runtime INVALID_INTRINSIC is invariant defense. Invalid Registry IDs/signatures
|
|
retain existing categories. Unknown type analysis requires full runtime checks.
|
|
An old VM may reject the new identities; no alternate-algorithm fallback exists.
|
|
|
|
## Budget and evidence
|
|
|
|
Charge fixed cost or range base before checks/reservations and 8 before every
|
|
draw, rejected or accepted. N counts words actually drawn: refusal before
|
|
draws costs 4, a unit interval 12, 64 attempts 516. Do not charge generic
|
|
INTRINSIC +1 or public math/next costs for private steps. Argument-producing
|
|
instructions retain their own costs.
|
|
|
|
Zero budget starts/charges no instruction. Positive budget admits the whole
|
|
instruction with existing overshoot between instructions. Fault retains cycles
|
|
and takes precedence over BudgetExhausted; failed calls are not successful steps.
|
|
There is no mid-attempt pause, continuation, added GC, tick or frame sync.
|
|
|
|
Qualification requires independently sourced words/Int64/Float bits, consumption,
|
|
faults and cycles in debug/release, seeds 0/1/42/-1/MIN/MAX, interleaving,
|
|
aliasing, storage/capture/Dynamic roots, GC/stale/provenance cases, extreme spans,
|
|
threshold boundaries, 64th acceptance, cap rollback and resource refusals.
|
|
Test-only synthetic words exercise rare paths without changing production RNG.
|
|
Record executed target/toolchain/profile and catalog fingerprints; do not
|
|
claim unexecuted host comparisons. CPU benchmarks do not set virtual costs.
|
|
|
|
Frontend and reference-game integration consume the published contract through
|
|
separate handoffs. Local core completion does not require those implementations
|
|
or acquisition of hardware. See [numeric semantics](02d-gameplay-math-and-numeric-semantics.md),
|
|
[Registry/PBX](02c-program-registry-and-pbx-v0.md),
|
|
[memory](03-memory-stack-heap-and-allocation.md) and
|
|
[cycles](01-time-model-and-cycles.md).
|
|
|
|
Producer examples and integration acceptance tests are published in the
|
|
[random handoff](../../vm-arch/random-producer-handoff.md). Executed evidence is
|
|
recorded in [random qualification](../../vm-arch/RANDOM_QUALIFICATION.md).
|