feat(pbs): integrate explicit runtime Random handles

This commit is contained in:
2026-10-17 13:51:12 +01:00
parent d1e9259085
commit b62db87245
22 changed files with 895 additions and 8 deletions
@@ -0,0 +1,155 @@
---
id: LSN-0086
ticket: pbs-runtime-random-integration
title: Explicit Random handles and source-to-runtime conformance
created: 2026-10-17
tags: [runtime-integration]
---
## Original problem and ownership
Owner: `compiler/pbs`; supporting integration: `compiler/general`. This lesson
consolidates AGD-0084, accepted DEC-0070 and completed PLN-0149 of DSC-0082.
The user accepted the direction and authorized plan generation and implementation.
The workflow scaffolding is removed by housekeeping; the normative PBS contract
is [Runtime Random Integration](../../../docs/compiler/pbs/specs/runtime-random-integration.md).
The common catalog already contained all four Random entries, with a synthetic
IR test of mutation and aliasing. That did not establish a usable PBS SDK or
prove source evaluation, typed storage, imports and captures. A deterministic
operation can still mutate state: the same seed is not permission to fold or
eliminate a call.
## Consolidated decision
Expose an explicit opaque `Random` handle and `random.new/next/nextf/range`.
Use the runtime's exact signatures, single-slot BuiltinId 0x0016 and catalog
metadata. All operations mutate guest state; only new allocates. Do not add an
implicit global generator, duplicate algorithm or compiler-side billing engine.
Copies alias the same generator. Two allocations with the same seed begin with
equal sequences and evolve independently. Source order, named-argument effects
and discarded calls must survive lowering and optimization. Handle identity must
survive locals, globals, fields, arrays, parameters, results, captures and private
Dynamic storage. The runtime remains authoritative for faults, transactional
mutation, resources and cycles. No game seed policy or replay serialization API
is introduced.
## Final implementation
Game SDK 1 publishes `Random` and `random` from `@sdk:random`, with normal import
aliases and reserved metadata bindings. PBS registers Random as the existing
runtime builtin. The parser accepts `new` in callable/member positions so the
published spelling is `random.new(seed)`. It still distinguishes source allocation
expressions, and rejects `new Random()`.
Fieldless builtins are treated as opaque by the semantic model. Exact contextual
types prevent returning a Random reference as an unrelated Struct or contract;
explicit contract adaptation is rejected too. Existing member checks reject
payload access. The discovered return-path gap is now a frontend diagnostic,
not a later backend stack/Registry error.
Existing array, optional, struct and closure lowering already preserves reference
identity, so no second storage representation or common backend algorithm was
needed. Common catalog tests and runtime execution verify the inherited effects
and costs. The reference model remains language-neutral.
```pbs
import { Random, random } from @sdk:random;
fn sample() -> long {
let generator: Random = random.new(42 as long);
let alias = generator;
random.next(generator); // discarded result still advances shared state
return random.range(alias, 0 as long, 100 as long);
}
```
The four operations use long/Float carriers exactly. `nextf` returns `[0,1)`;
`range` returns `[min,max)` and requires `min < max`. Intrinsic costs are 32, 8,
12 and `4 + 8*N` respectively. Range accepts at most 64 attempted words: attempt
64 can succeed, while rejecting all 64 faults and rolls state back without
refunding 516 charged cycles. Explicit source conversions and ordinary bytecode
instructions have separate costs.
## Source evidence and provider evidence
`PbsRuntimeRandomTest` compiles the packaged SDK and project declarations through
production linking, common lowering, optimization and PBX emission. A dedicated
fixture uses the real workspace builder, import aliases and lifecycle assembler.
The focused callable driver explicitly calls file initialization before Probe.main;
it does not replace or introduce a lifecycle feature.
The 48 provider oracle rows cover six seeds and eight draws. Projecting both
integer and Float outputs, with optimization off/on, produces 192 fixtures.
Another 34 paired fixtures cover aliases, independent objects, mixed/discarded
operations, named/positional effects, storage/captures, limits, faults and GC.
Together with real imports this is **227 mandatory fixtures per runtime profile**.
Each of the 226 callable fixtures executes with single-step budgets and twice
with full budgets to compare exact bits/faults, call charges and total cycles.
The runner checks oracle byte equality against the selected runtime.
The GC fixture reuses the established test-only FRAME_SYNC marker mechanism.
All allocations and accesses are PBS source. After at least 1,100 discarded
Random objects are reclaimed, array, field and closure roots still draw the
expected shared sequence. The source corpus also exercises a genuine rejected
PCG word followed by acceptance, charging range 20 cycles.
PBS has no public null or Dynamic type. A source struct constructor that leaves
a Random field at its runtime default provides a null reference for tests.
Storing it in a typed array preserves a present Dynamic tag and exact TypeId;
extracting it then drawing traps NULL_REFERENCE. This must not be confused with
an empty array slot. Existing global-initializer restrictions are unchanged.
Provider evidence is separate: 13 guest contract tests and 11 private Random
engine/VM tests passed in both debug and release. Those prove synthetic
64th-attempt success, capped rejection rollback, malformed carriers, fault
precedence, resource refusal, exact Dynamic types, stale handles, reset and
native provenance. They are not described as PBS-produced rare-path execution.
## Validation and limits
The [evidence record](evidence.json) pins source/catalog/oracle/lockfile hashes,
commands, toolchains, profiles and suite counts. Executed on macOS arm64 with
runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`.
- Java: frontend 249 passed; architecture 63 passed; common pipeline 175 passed
with 12 existing skips; installed knowledge 2 passed. Total: 489 passed.
- Full production-loader conformance harness passed in debug and release,
including all 227 Random fixtures and existing math/input/Registry/collection
and closure suites.
- Runtime provider Random suites: 13 contract + 11 private tests per profile.
- Catalog copies and provider exporter matched; workflow and diff validation passed.
Qualification covers the local target only. Other platforms and the reference
game's corpus are not claimed. The full harness retains the pre-existing,
explicitly reported runtime fault-schema gaps for LifecycleRole and NonFiniteValue;
this work neither changes nor hides them. Installed knowledge validates packaged
SDK/spec/example delivery, not execution through an installed runtime process.
## Pitfalls and maintenance
1. Do not confuse deterministic with pure. Eliminating a discarded draw changes
every subsequent result; eliminating discarded new also changes allocation.
2. Do not duplicate the RNG in Java to prove Java output. Keep independent provider
vectors and execute generated PBX on the VM.
3. Do not use interface-module validation for arbitrary project code. The tests
compile SDK metadata separately and link trusted declarations into project source.
4. Do not use a runtime carrier's physical HeapRef shape as permission for a
Struct/contract adaptation. Exact source and Registry identities matter.
5. Distinguish present typed null from absent Dynamic. Check the tag before unpacking.
6. Keep new fixture families separate from older enumerated corpora; the old
eight-type input suite must not accidentally count Random fixtures.
7. Record fingerprints and distinguish provider rare-path proofs from source
tests. A passing synthetic common-IR test is not a source integration claim.
## References
- [PBS Random specification](../../../docs/compiler/pbs/specs/runtime-random-integration.md).
- [Typed arrays and optional execution](../../../docs/compiler/pbs/specs/typed-arrays-and-optional-execution.md).
- [Functions and captures](../../../docs/compiler/pbs/specs/first-class-functions-and-captures.md).
- [Conformance commands and boundaries](../../../tools/pbx-conformance/README.md).
- [Provider Random specification](../../../../runtime/docs/specs/runtime/02e-vm-owned-random-core.md).
- [Provider qualification](../../../../runtime/docs/vm-arch/RANDOM_QUALIFICATION.md).
- Historical accepted DEC-0070 and completed PLN-0149: obligations are preserved
in the normative spec, this lesson and its evidence after workflow cleanup.
@@ -0,0 +1,108 @@
{
"date": "2026-10-17",
"discussion": "DSC-0082",
"decision": "DEC-0070",
"plan": "PLN-0149",
"runtime_revision": "f7d7c167531bb662a1af9d73fc326bb476bf8aa7",
"platform": "macOS-27.0.1-arm64-arm-64bit-Mach-O",
"rustc": "rustc 1.98.1 (48a229cea 2026-09-01)\nbinary: rustc\ncommit-hash: 48a229ceaefd4985c50990b14116b6d856af0985\ncommit-date: 2026-09-01\nhost: aarch64-apple-darwin\nrelease: 1.98.1\nLLVM version: 22.1.8",
"java": "openjdk version \"25.0.4\" 2026-07-21 LTS\nOpenJDK Runtime Environment Corretto-25.0.4.7.1 (build 25.0.4+7-LTS)\nOpenJDK 64-Bit Server VM Corretto-25.0.4.7.1 (build 25.0.4+7-LTS, mixed mode, sharing)",
"runtime_profiles": [
"dev",
"release"
],
"harness_features": [
"resource-diagnostics"
],
"provider_features": "default",
"source_fingerprints": {
"../runtime/Cargo.lock": "cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795",
"../runtime/docs/vm-arch/INTRINSICS.csv": "0c1bb78a9b81d1e3480ef5713f3d70f0b06772a7dfab2fd00c1f0a6364f98daa",
"../runtime/docs/vm-arch/BUILTIN_CONSTANTS.csv": "e407e4718127aa7ef7b1097b5b4b67d86dd979235e73a551a7c36b628cddc039",
"../runtime/crates/console/prometeu-vm/tests/fixtures/random-conformance.tsv": "0bee1cd0366f1716687aee8c7ac39dd495da5fe2908cce37b1443cb04fac542f",
"../runtime/crates/console/prometeu-vm/tests/random_contract.rs": "de961a4c57c4ed7b1f01b002abd8a319c3fed90cb5bce07a5c023ef9239490b1",
"../runtime/crates/console/prometeu-vm/src/random.rs": "48e46d50f0665c85bb899d7324783cb1b5121378cb21f06059f2c2617e6d9e16",
"../runtime/crates/console/prometeu-vm/src/virtual_machine/random.rs": "136cdbe46a687a7b755d559a2842d44f494cf76e8a34427eeb48494820935a42",
"tools/pbx-conformance/main.rs": "76d3d1b90b417c33737fb0ede6ea7af8ffe586bfb2bf4f710684a8d9f72c7466",
"tools/pbx-conformance/run.py": "49b01cfc81d378871ca3cc32dec7b1f830fdb7c86545d5a32e2e3455c4f1588f",
"prometeu-architecture-tests/src/test/java/p/studio/compiler/backend/irvm/PbsRuntimeRandomTest.java": "2d474bd65b0ddcfa2b9ad8d7887c2f964cf73336a8747f4f34478e6a2137bf59",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/random/main.pbs": "c21c12d99c5a033a1e4026432bbab56393ad09c0fe2d36711504ccca01ce93b5",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/random/mod.barrel": "7924c022a140b9bc634f3699175c8775f24093d3aa82e650752232971b0380fb",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsRuntimeTypes.java": "c973cb5de13a3e1bddaecad140436ea54d4a78ac5f08310511a60b637630889a",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsDeclarationParser.java": "50d494f4e2b79d7147acc25e0ce4cad244ef2a04288ea823aecdd5347feb48c6",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsExprParserContext.java": "7b6de40de18fd676210bcfc6655b0dbbd10d589513d35f1cf0c4b01cbf30e7d5",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java": "4775395a00edba94ff55cd2d93959973fc8ad70cae260cc5e2631087827eee9d",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowSemanticSupport.java": "2c39d3fed360aeef0ac1c6c8f8c1d92989f84f60cbe23dd01ebce8a9d575d128",
"prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStructuralExpressionAnalyzer.java": "ba32cc9521ee4bc4840e0910566b4fad7d50a382dac8288c4f6e1ac3ab2fe4ab"
},
"java_tests": {
"frontend": {
"passed": 249
},
"architecture": {
"passed": 63
},
"common_pipeline": {
"passed": 175,
"existing_skipped": 12
},
"installed_knowledge": {
"passed": 2
}
},
"random_fixtures_per_profile": 227,
"callable_replays_per_fixture": 3,
"provider_tests_per_profile": {
"random_contract": 13,
"private_random": 11
},
"commands": [
"./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test :prometeu-architecture-tests:test :prometeu-compiler:prometeu-build-pipeline:test :prometeu-app:installedKnowledgeTest --console=plain",
"CARGO_TARGET_DIR=/tmp/pln149-cargo-target python3 tools/pbx-conformance/run.py",
"CARGO_TARGET_DIR=/tmp/pln149-cargo-target python3 tools/pbx-conformance/run.py --release",
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm random --target-dir /tmp/pln149-provider-target",
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm --lib random --release --target-dir /tmp/pln149-provider-target",
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm --test random_contract --target-dir /tmp/pln149-provider-target",
"cargo test --manifest-path ../runtime/Cargo.toml --locked --offline -p prometeu-vm --test random_contract --release --target-dir /tmp/pln149-provider-target",
"python3 tools/runtime-catalog/verify.py --runtime ../runtime"
],
"logs": {
"regression": {
"sha256": "1379beaf5dbb205c9ff5894775835467dd0772fad3b87f3241b94e03c6609bf8",
"result": "passed"
},
"conformance-dev": {
"sha256": "99e7c3a4b5c3f1a408d22eef8a736b9a6fd061eff5c13e405c1bd019f504ce4d",
"result": "passed"
},
"conformance-release": {
"sha256": "f1df27a348bb98976b4ee0b46a0e121b56d524aab5f43deecc0c705c08e1fd79",
"result": "passed"
},
"provider-dev": {
"sha256": "3b9b0b522d3c5ed305536aa5be621fc34f0b4cce0f6b5705626052a4fb252be2",
"result": "passed"
},
"provider-release": {
"sha256": "8555828137f4e747f079145892c7c11e18ac55f2e9720497affaf9fe828f48b9",
"result": "passed"
},
"provider-contract-dev": {
"sha256": "5c2a31b0f33e75dfe644993e0e79f8cf19bd01bc95db23b41190fc2069d16f8e",
"result": "passed"
},
"provider-contract-release": {
"sha256": "cbf430b84132edbdda2fe0b5ab34cf5fad6e78a048811695efe223eac37a3333",
"result": "passed"
},
"catalog": {
"sha256": "66b7003ff94115aece4b278522b0c080e806497e26ca17dd756163bc7974fa83",
"result": "passed"
}
},
"limitations": [
"macOS arm64 only",
"Reference-game and installed-runtime process qualification excluded",
"Existing explicit provider schema gaps LifecycleRole and NonFiniteValue retained"
]
}