feat(vm): add VM-owned PCG64 random and coverage headroom
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

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.
This commit is contained in:
2026-10-09 12:51:05 +01:00
parent 9318cf7cd3
commit 3e39a90083
50 changed files with 2545 additions and 189 deletions
@@ -0,0 +1,116 @@
---
id: LSN-0063
ticket: vm-owned-random-service
title: Reproducible Random Is Stateful Transactional Work
created: 2026-10-09
tags: []
---
## Context
Random generation is a useful example of deterministic work that cannot be
modeled as a pure function of its visible arguments. A seed identifies the
initial stream, but each call changes where the generator is in that stream.
The runtime must preserve identity, call order, memory ownership and consumed
work together if a cartridge is to replay the same logical behavior.
This lesson derives from accepted decision DEC-0050, executed through PLN-0181.
Its normative result is the [VM-owned random contract](../../../docs/specs/runtime/02e-vm-owned-random-core.md).
Historical lineage is retained by the [discussion index](../../index.ndjson);
completed control artifacts are disposable. The
[qualification record](../../../docs/vm-arch/RANDOM_QUALIFICATION.md) contains
executed environment, fixtures, checks and pending target comparisons.
## Key Decisions
### Identity belongs to the object, reproducibility to the ordered stream
**What:** Random is an opaque reference builtin backed by a GC-managed object.
Copies retain the same state; separate constructions with equal seed bits start
at the same point and then evolve independently. Existing fields, arrays,
Dynamic, captures and function boundaries store references, not generator copies.
**Why:** This fits the published reference/ownership model and avoids accidental
stream duplication through ordinary value copies. The frontend selects an
intrinsic; it does not implement the generator or choose host entropy.
**Trade-offs:** Consumers must distinguish aliasing from independent construction.
Reproducible generators with the same seed are not evidence of statistical
independence. Native snapshots do not become guest GC roots or import authority.
### Freeze the complete algorithm, including initialization and consumption
**What:** The implementation uses PCG-XSL-RR 128/64 setseq with explicit wrapping,
fixed increment and advance-before-output. Integer and Float calls consume the
same sequence. Seed Int64 bits are zero-extended after u64 reinterpretation.
**Why:** An algorithm family name alone is insufficient: variants, seed expansion,
old-versus-new-state output and hidden buffers all change the stream. Float
conversion also needs an exact endpoint rule; retaining the high 53 bits and
scaling with software binary64 excludes 1 without a Float32 narrowing step.
**Trade-offs:** Compatibility claims are limited to this exact contract.
Independent canonical words plus a separate arithmetic oracle are stronger
than comparing two instances of the same implementation. Debug/release equality
is necessary; it does not qualify unexecuted operating systems or targets.
### Stage state changes but retain the cost of attempted work
**What:** The interpreter validates all carriers before reference/bounds checks,
reserves resources, draws on a private state candidate, and publishes the result
and state only after success. Faults preserve operands and state while retaining
cycles. Bounded range mapping charges a base plus every attempted word.
**Why:** Popping operands first loses roots/owners and makes resource refusal
or rejection-limit failure difficult to undo. Mutating public state while
retrying creates an observable half-completed instruction. Refunding cycles,
however, would erase work that the machine actually attempted.
**Trade-offs:** Unbiased rejection may fail after its bounded work allowance.
A cap fault leaves the generator at its original state; identical inputs/state
will repeat the same failed candidate stream. Accepting the final permitted
attempt and rejecting all permitted attempts are distinct cases. Whole-instruction
budget overshoot remains sufficient; no new continuation/scheduler is needed.
## Patterns and Algorithms
Treat a stateful intrinsic as a transaction over existing VM resources:
retain source roots, validate in published order, reserve, prepare privately,
then commit without fallible operations. A leaf payload does not require a new
GC model: integrate its reference builtin with the existing ownership maps.
Use the same shared catalog for signatures, admission, execution routing and
exports. An explicit VM-owned implementation variant avoids giving host
callbacks heap mutation authority. Publish guest-state effects separately from
determinism, and publish variable cost structure rather than a misleading
fixed base-only total.
Rare paths require deliberate evidence. Test-only synthetic candidates execute
the production bounded loop and transaction for multiple rejections, final
acceptance and cap rollback. Real PCG fixtures separately prove the stream,
including a natural rejection followed by acceptance. These two tests answer
different questions and should not replace each other.
## Pitfalls
- Treating deterministic=true as permission to fold or reorder stateful calls.
- Copying a handle while expecting an independent stream.
- Reducing unsigned words with simple modulus without the rejection threshold.
- Computing an Int64 interval width in signed 64-bit arithmetic.
- Rounding W/2^64 or narrowing to Float32 and accidentally including endpoint 1.
- Committing generator state before result capacity or quota checks finish.
- Advertising local reproducibility as cross-platform qualification or game readiness.
## Published Evidence and Handoffs
The delivered core passed bytecode/VM suites in debug and release and the
workspace regression suite. Twenty-four focused random tests cover guest
fixtures and private engine/transaction behavior, including GC roots, rollback,
resource ownership and exact costs. Metadata and published CSV agree; the
constant catalog remains unchanged. Exact counts, fingerprints and commands
belong to the qualification record, not to a normative lesson.
The [producer handoff](../../../docs/vm-arch/random-producer-handoff.md) gives
emitted PBX, expected result bits/cycles and consumer acceptance tests.
Frontend projection/optimization, reference-game workloads and other-target
comparison runs remain separate deliveries. No helper selection API was added.
@@ -0,0 +1,50 @@
---
id: LSN-0064
ticket: coverage-domain-minimum-margin
title: Measured Coverage and Acceptance Floors
created: 2026-10-09
tags: [coverage, ci, measurement]
---
## Context
A coverage gate set equal to its observed percentage has almost no room for
variation. This workspace had several such floors. An explicitly reviewed
revision now provides at least five percentage points of local headroom in
all 15 domains, lowering eight floors and retaining seven.
The published contract is in [Coverage domains](../../../docs/vm-arch/COVERAGE_DOMAINS.md),
with [measured evidence](../../../docs/vm-arch/COVERAGE_DOMAINS_MARGIN.json) and
[fixed configuration](../../../files/config/runtime-edge-coverage-domains.json).
DEC-0051 and PLN-0182 record the accepted revision and execution; their lifecycle
is retained in the [discussion index](../../index.ndjson).
## Separate the Measurement from the Floor
Observed coverage describes one execution. A floor describes how much decline
the reviewed gate accepts. They serve different purposes even when their
numbers initially coincide. Five percentage points below 88.56% is 83.56%,
not a relative five-percent reduction.
Snapshot original floors before editing. For this revision, compute
`min(original_floor, measured_percent - 5.00)` in integer hundredths after
the auditor's downward truncation. This retains already sufficient floors
and prevents repeated subtraction from weakening the policy accidentally.
Keep floors fixed in later CI runs; future revisions require explicit review.
## Use Verification to Account for Observed Variation
Two full local runs passed, but system/runtime measured 81.26% initially and
81.19% during verification. The final 76.19% floor uses the lower observation.
All gates were rechecked against that unchanged verification report. Treating
the initial measurement as immutable would have left only 4.93 points of
headroom. Local evidence qualifies the executed host, not an unexecuted pipeline.
## Preserve Independent Checks
Margin changes affect acceptance floors only. Source ownership, exclusions,
nonempty evidence requirements and percentage arithmetic still apply. The
939 passing tests continue to check behavior independently of coverage.
Historical evidence remains unchanged; new evidence records the current
measurements, floors and fingerprints. A fresh snapshot explains the revision
without making an earlier run appear to have used the new configuration.