feat(vm): add VM-owned PCG64 random and coverage headroom
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
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:
+116
@@ -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.
|
||||
+50
@@ -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.
|
||||
Reference in New Issue
Block a user