feat(pbs): integrate explicit runtime Random handles
This commit is contained in:
+155
@@ -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"
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user